Краткий справочник по программированию

In the next chapters you will find the basic information on how to start programming 3D applications and videogames with UNIGINE. This FAQ consists of the following chapters:В настоящем справочнике вы найдете основную информацию о том, как начать программировать 3D-приложения и видеоигры с помощью UNIGINE. Справочник включает в себя следующие главы:

1. Basic Scene Objects Основные объекты сцены
2. Coordinate System Система координат
3. Logging and Printing Messages to ConsoleВедение журнала и вывод сообщений в консоль
4. Saving and Loading a World Сохранение и загрузка мира
5. Closing the Application Закрытие приложения
6. Creating and Deleting Nodes at Runtime Создание и удаление объектов во время выполнения
7. Creating and Setting Up a Camera Создание и настройка камеры
8. Creating and Setting up Light Sources Создание и настройка источников света
9. Creating, Applying and Deleting Materials at Runtime Создание, применение и удаление материалов во время выполнения
10. Managing Existing Scene Objects Управление существующими объектами сцены
11. Performing Basic Transformations (Move, Rotate, Scale) Выполнение базовых преобразований (перемещение, поворот, масштабирование)
12. Making the Game Process Framerate-independent Как сделать игровой процесс независимым от частоты кадров
13. Managing Intersections Управление пересечениями
14. Getting and Managing User Inputs Получение пользовательских вводов и управление ими
15. Creating User Interface Создание пользовательского интерфейса
16. Playing Sound and Music Воспроизведение звука и музыки
17. Setting Up Physics Настройка физики
18. Catching Nodes with World Triggers Обнаружение объектов с помощью World Trigger

In terms of UNIGINE, node is a basic type from which all types of scene objects are inherited. Some of them appear visually: Objects, Decals, and Effects they all have surfaces to represent their geometry (mesh), while others (Light Sources, Players, etc.) are invisible.В UNIGINE нода (node) — это базовый тип, от которого наследуются все типы объектов сцены. Некоторые из них отображаются визуально: объекты, декали и эффекты — все они имеют поверхности для представления их геометрии (меш), в то время как другие ( Источники света, Персонажи и т.д.) невидимы.

Each node has a transformation matrix, which encodes position, rotation, and scale of the node in the world.Каждая нода имеет матрицу преобразования, которая кодирует положение, поворот и масштаб ноды в мире.

All scene objects added to the scene regardless of their type are called nodes.Все объекты сцены, добавленные в сцену, независимо от их типа, называются нодами.

Дополнительная информация:

The 3D space in UNIGINE is represented by the right-handed Cartesian coordinate system: X and Y axes form a horizontal plane, Z axis points up. When exporting an animation from 3D editors, Y is considered a forward direction.Трехмерное пространство в UNIGINE представлено правой декартовой системой координат: оси X и Y образуют горизонтальную плоскость, ось Z направлена вверх. При экспорте анимации из 3D-редакторов Y считается прямым направлением.

Coordinate SystemСистема координат

Positive rotation angle sets the rotation counterclockwise. It corresponds to the right-hand rule: if you set right hand thumb along the axis, other fingers wrapped will show rotation direction.Положительный угол поворота задает вращение против часовой стрелки. Это соответствует правилу правой руки: если вы установите большой палец правой руки вдоль оси, другие обернутые пальцы будут показывать направление вращения.

Rotation DirectionsНаправления вращения

Дополнительная информация:

Printing messages to the log file and console helps to monitor overall progress of execution of your application and report errors which can be used in debugging. Log class makes it possible to print formatted string messages to the log file and the console. The code below demonstrates how to print various types of messages:Вывод сообщений в файл журнала и консоль помогает отслеживать общий ход выполнения вашего приложения и сообщать об ошибках, которые могут быть использованы при отладке. Класс Log позволяет печатать форматированные строковые сообщения в файл журнала и консоль. Приведенный ниже код демонстрирует, как выводить различные типы сообщений:

Примечание

To enable displaying messages in the onscreen overlay use the following command: console_onscreen 1Чтобы включить отображение сообщений в оверлее экрана, используйте следующую команду: console_onscreen 1

using namespace Unigine;

// auxiliary variables for messages
const char* file_name = "file.txt";
int ID = 10;

	// reporting an error message
	Log::error("Loading mesh: can't open \"%s\" file\n", file_name);

	// reporting a message
	Log::message("-> Added %d UI elements.\n", ID);

	// reporting a warning message
	Log::warning("ID of the \"%s\" file: %d.\n", file_name, ID);

	// reporting a fatal error message to the log file and closing the application
	Log::fatal("FATAL ERROR reading \"%s\" file!\n", file_name);

Additional information: Дополнительная информация:

• For more information on the console, see Console article.Для получения дополнительной информации о консоли см. статью Console.
• For more information on the Log class, see Log class article.Для получения дополнительной информации о классе Log см. статью о классе Log.

Some applications manage a single world, while other require several worlds to be managed. In any case, it is very useful to know how to save our current world and load some other. In order to solve this task, we should use the World class, which is designed as a singleton.Некоторые приложения управляют одним миром, в то время как другие требуют управления несколькими мирами. В любом случае, очень полезно знать, как сохранить наш текущий мир и загрузить какой-нибудь другой. Чтобы решить эту задачу, мы должны использовать класс World, который разработан как синглтон.

Примечание

In order to use the World class, include the UnigineWorld.h library.Чтобы использовать класс World, включите библиотеку UnigineWorld.h.

Исходный код (C++)

#include <UnigineWorld.h>

using namespace Unigine;
/* .. */

// loading world from the my_world.world file
World::loadWorld("my_world");

We can also do the same via the console by using the Console class, which is also designed as a singleton.Мы также можем сделать то же самое через консоль, используя класс Console, который также разработан как синглтон.

Примечание

In order to use the Console class, include the UnigineConsole.h library.Чтобы использовать класс Console, включите библиотеку UnigineConsole.h.

Исходный код (C++)

#include <UnigineConsole.h>

using namespace Unigine;
/* .. */

// saving current world to the my_world.world file
Console::run("world_save my_world");

// loading world from the my_world.world file
Console::run("world_load my_world");

Additional information: Дополнительная информация:

• For more information on managing worlds via API, see the World class article.Для получения дополнительной информации об управлении мирами с помощью API см. статью о классе World.
• For more information on the console and available commands, see Console article.Для получения дополнительной информации о консоли и доступных командах см. статью Консоль.
• For more information on managing the console via API, see Console class article.Для получения дополнительной информации об управлении консолью через API см. статью о классе Console.
• For more information on managing world nodes that are to be saved via API, see the methods of the Node class.Для получения дополнительной информации об управлении мировыми нодами, которые должны быть сохранены с помощью API, см. методы класса Node.

Any application needs to be closed at some moment. To close your application you should use the Engine class.Любое приложение должно быть закрыто в какой-то момент. Чтобы закрыть ваше приложение, используйте класс Engine.

To close the application the following code is to be used:Чтобы закрыть приложение, необходимо использовать следующий код:

using namespace Unigine;

/* .. */
		
// closing the application 
Engine::get()->quit();

Nodes can be created and deleted at runtime almost as easy as in the Editor. The basic set of actions is as follows:Ноды можно создавать и удалять во время выполнения почти так же просто, как в редакторе. Основной набор действий заключается в следующем:

// creating a node of the NodeType named nodename
<NodeType>Ptr nodename = <NodeType>::create(<construction_parameters>);
	
// removing the node
nodename.deleteLater();

int AppWorldLogic::init()
{

	//create an ObjectMeshStatic node from an fbx model imported to the data/fbx/ folder using the Editor
	ObjectMeshStaticPtr my_object = ObjectMeshStatic::create("fbx/model.fbx/model.mesh");

	// removing the node
	my_object.deleteLater();

	return 1;
}

A camera is a viewport to the world, without it you actually won't be able to see anything. Cameras in UNIGINE are managed using players. When you add a new player, it creates a camera and specifies controls, masks, postprocess materials for this camera. Камера — это окно в мир, без него вы на самом деле ничего не сможете увидеть. Камеры в UNIGINE управляются с помощью Player. Когда вы добавляете нового персонажа, он создает камеру и задает элементы управления, маски, материалы для последующей обработки для этой камеры.

In order to set a new player as active one we should use the Game class which is designed as a singleton.Для того, чтобы установить нового персонажа в качестве активного, мы должны использовать класс Game, который разработан как синглтон.

Примечание

In order to use the Game class and PlayerSpectator class we must include the UnigineGame.h and the UniginePlayers.h libraries.Чтобы использовать класс Game и класс PlayerSpectator, мы должны включить библиотеки UnigineGame.h и UniginePlayers.h.

The following code illustrates creation of a PlayerSpectator and setting it as the active game camera.Следующий код иллюстрирует создание PlayerSpectator и установку его в качестве активной игровой камеры.

Примечание

By default the player uses a standard set of controls which can be overridden if necessary.По умолчанию персонаж использует стандартный набор элементов управления, которые при необходимости могут быть переопределены.

#include <UnigineGame.h>

// injecting Unigine namespace to the global namespace
using namespace Unigine;

int AppWorldLogic::init()
{

	// creating a new PlayerSpectator instance
	PlayerSpectatorPtr playerSpectator = PlayerSpectator::create();

	// setting necessary parameters: FOV, ZNear, ZFar, view direction vector and position.
	playerSpectator->setFov(90.0f);
	playerSpectator->setZNear(0.1f);
	playerSpectator->setZFar(10000.0f);
	playerSpectator->setViewDirection(Math::vec3(0.0f, 1.0f, 0.0f));
	playerSpectator->setWorldPosition(Math::Vec3(-1.6f, -1.7f, 1.7f));

	// setting the player as a default one via the Game singleton instance
	Game::setPlayer(playerSpectator);

	return 1;
}

Additional information: Дополнительная информация:

• For more information on players, see the Players article.Для получения дополнительной информации об игроках см. статью Персонажи.
• For more information on players API, see the Players-Related Classes article.Для получения дополнительной информации об API игроков см. статью Player-классы.
• For more information on the Game class, see the Game class article.Для получения дополнительной информации о игровом классе см. статью о классе Game.

Lighting is the basis of every scene defining colors and final look of your objects. Lights in UNIGINE are created the same way as all nodes. Освещение является основой каждой сцены, определяющей цвета и окончательный вид ваших объектов. Источники света в UNIGINE создаются так же, как и все остальные ноды.

Let us consider creation of a world light source as an example:Давайте рассмотрим создание мирового источника света в качестве примера:

#include <UnigineLights.h>

// injecting Unigine namespace to the global namespace
using namespace Unigine;

int AppWorldLogic::init()
{

	// creating a world light source and setting its color to white
	LightWorldPtr sun = LightWorld::create(Math::vec4(1.0f, 1.0f, 1.0f, 1.0f));

	// setting light source's parameters (intensity, disable angle, scattering type, name and rotation)
	sun->setName("Sun");
	sun->setDisableAngle(90.0f);
	sun->setIntensity(1.0f);
	sun->setScattering(LightWorld::SCATTERING::SCATTERING_SUN);
	sun->setWorldRotation(Math::quat(86.0f, 30.0f, 300.0f));

	return 1;
}

Additional information: Дополнительная информация:

• For more information on light sources, see the Light sources article.Для получения дополнительной информации об источниках света см. статью Источники света.
• For more information on light sources API, see the Lights-Related Classes article.Для получения дополнительной информации об API источников света см. статью Lights-классы.

Materials assigned to particular surfaces of a node determine how the node is to be rendered. They implement the shaders and control what options, states, parameters of different types and textures are used to render the node during the rendering passes. To manage materials we use the following two classes: Материалы, назначенные определенным поверхностям объекта, определяют, как будет отображаться объект. Они реализуют шейдеры и управляют тем, какие опции, состояния, параметры различных типов и текстуры используются для рендеринга объекта во время прохода рендеринга. Для управления материалами мы используем следующие два класса:

• Materials class which represents an interface for managing loaded materials.Класс Materials, который представляет интерфейс для управления загруженными материалами.
• Material class which is used to manage each individual material.Класс Material, который используется для управления каждым отдельным материалом.

Примечание

In order to use materials we must include the UnigineMaterials.h libraryДля того, чтобы использовать материалы, мы должны включить библиотеку UnigineMaterials.h

The following code can be used to create a new material inherited from the mesh_base material.Следующий код можно использовать для создания нового материала, унаследованного от материала mesh_base.

#include <UnigineMaterials.h>
#include <UniginePrimitives.h>

// injecting Unigine namespace to the global namespace
using namespace Unigine;

int AppWorldLogic::init()
{

	// creating a box (ObjectMeshDynamic node)
	ObjectMeshDynamicPtr my_mesh = Primitives::createBox(Math::vec3(1.5f, 1.5f, 1.5f));

	// getting the base mesh_base material to inherit from
	MaterialPtr mesh_base = Materials::findManualMaterial("Unigine::mesh_base");

	// inherit a new child material from it
	MaterialPtr my_mesh_base = mesh_base->inherit();

	// save it to  "materials/my_mesh_base0.mat"
	my_mesh_base->createMaterialFile("materials/my_mesh_base0.mat");

	// setting the albedo color of the material to red
	my_mesh_base->setParameterFloat4("albedo_color", Math::vec4(255, 0, 0, 255));

	// assigning a "my_mesh_base0.mat" material to the surface 0 of the my_mesh ObjectMeshDynamic node
	my_mesh->setMaterialPath("materials/my_mesh_base0.mat", 0);

	// assigning a "my_mesh_base0.mat" material to all surfaces of the my_mesh ObjectMeshDynamic node
	my_mesh->setMaterialPath("materials/my_mesh_base0.mat", "*");

	return 1;
}

int AppWorldLogic::shutdown()
{

	// deleting the material "materials/my_mesh_base0.mat"
	Materials::removeMaterial(Materials::findMaterialByPath("materials/my_mesh_base0.mat")->getGUID());
	return 1;
}

Additional information: Дополнительная информация:

• For more information on creating and editing materials via API, see the Material class article.Для получения дополнительной информации о создании и редактировании материалов с помощью API см. статью о классе Material.
• For more information on managing loaded materials via API, see the Materials class article.Для получения дополнительной информации об управлении загруженными материалами с помощью API см. статью о классе Materials.
• For more information on materials files formats, see the Materials Files section.Для получения дополнительной информации о форматах файлов материалов см. раздел Файлы материалов.
• For more information on materials parameters, see the materials files in the %UNIGINE_SDK_BROWSER_INSTALLATION_FOLDER%/sdks/%CURRENT_SDK%/data/core/materials/default/ folder.Для получения дополнительной информации о параметрах материалов см. файлы материалов в папке %UNIGINE_SDK_BROWSER_INSTALLATION_FOLDER%/sdks/%CURRENT_SDK%/data/core/materials/default/.

Not all content in the world is created at runtime, so we should be able to operate with nodes that already exist. How do we get pointers to existing objects in order to manage them? This is where the World class comes into play again. Basically, there are two ways we can get a pointer to a certain node using the methods of the World class:Не весь контент в мире создается во время выполнения, поэтому мы должны иметь возможность работать с уже существующими нодами. Как мы получаем указатели на существующие объекты, чтобы управлять ими? Здесь снова вступает в игру класс World. В принципе, есть два способа, которыми мы можем получить указатель на определенную ноду, используя методы класса World:

• getNodeByName() method - when we know node's nameметод getNodeByName() — когда мы знаем имя ноды
• getNodeByID() method - when we know the node's IDметод getNodeByID() — когда мы знаем идентификатор ноды

Примечание

In order to be able to use the methods of the World class we must include the UnigineWorld.h library.Для того, чтобы иметь возможность использовать методы класса World, мы должны включить библиотеку UnigineWorld.h.

These methods return a NodePtr value, which is a pointer to the base class, but in order to perform operations with a certain object (e.g. ObjectMeshDynamicPtr) we need to perform downcasting (i.e. convert from a pointer-to-base to a pointer-to-derived).Эти методы возвращают значение NodePtr, которое является указателем на базовый класс, но для выполнения операций с определенным объектом (например, ObjectMeshDynamicPtr) нам необходимо выполнить понижающее преобразование (т.е. преобразовать указатель на базовый класс в указатель на производный).

Sometimes you may also need to perform upcasting (i.e. convert from a pointer-to-derived to a pointer-to-base), in this case you can use the derived class itself. The code below demonstrates the points described above.Иногда вам также может потребоваться выполнить upcasting (т.е. преобразовать указатель на производный в указатель на базовый), в этом случае вы можете использовать сам производный класс. Приведенный ниже код демонстрирует моменты, описанные выше.

#include <UnigineWorld.h>
using namespace Unigine;
/* .. */

// find a pointer to node by a given name
NodePtr baseptr = World::getNodeByName("my_meshdynamic");

// cast a pointer-to-derived from pointer-to-base with automatic type checking
ObjectMeshDynamicPtr derivedptr = checked_ptr_cast<ObjectMeshDynamic>(baseptr);

// static cast (pointer-to-derived from pointer-to-base)
ObjectMeshDynamicPtr derivedptr = static_ptr_cast<ObjectMeshDynamic>(World::getNodeByName("my_meshdynamic"));

// upcast to the pointer to the Object class which is a base class for ObjectMeshDynamic
ObjectPtr object = derivedptr;

// upcast to the pointer to the Node class which is a base class for all scene objects
NodePtr node = derivedptr;

There are the following ways to get a component from a node:Существуют следующие способы получения компонента для ноды:

// get the component assigned to a node by type "MyComponent"
MyComponent* my_component = ComponentBase::getComponent<MyComponent>(node);

// // do the same by using the function of the Component System
MyComponent* my_component = ComponentSystem::get()->getComponent<MyComponent>(color_zone);

Every node has a transformation matrix, which encodes position, rotation, and scale of the node in the world. If a node is added as a child of another node, it has a transformation matrix that is related to its parent node. That is why the Node class has different functions: getTransform(), setTransform() and getWorldTransform(), setWorldTransform() that operate with local and world transformation matrices respectively. The following code illustrates how to perform basic node transformations:Каждая нода имеет матрицу преобразования, которая кодирует положение, поворот и масштаб ноды в мире. Если нода добавляется как дочерняя для другой ноды, она имеет матрицу преобразования, связанную с ее родительской нодой. Вот почему класс Node имеет разные функции: getTransform(), setTransform() и getWorldTransform(), setWorldTransform(), которые работают с локальными и мировыми матрицами преобразования соответственно. Следующий код иллюстрирует, как выполнять базовые преобразования нод:

// injecting Unigine namespace to the global namespace
using namespace Unigine;
using namespace Unigine::Math;

// move the node by X, Y, Z units along the corresponding axes
node->setWorldPosition(node->getWorldPosition() + Vec3(X, Y, Z));

// move the node by one unit along the Y axis
node->worldTranslate(0.0f, 1.0f, 0.0f);

// rotate the node around the axis (X, Y, Z) by the Alpha angle 
node->setWorldRotation(node->getWorldRotation() * quat(Vec3(X, Y, Z), Alpha));

// rotate the node around X, Y, and Z axes by the corresponding angle (angle_X, angle_Y, angle_Z)
node->setWorldRotation(node->getWorldRotation() * quat(angle_X, angle_Y, angle_Z));

// rotate the node by 45 degrees along the Z axis
node->worldRotate(0.0f, 0.0f, 45.0f);

// orient the node using a direction vector and a vector pointing upwards
node->setWorldDirection(vec3(0.5f, 0.5f, 0.0f), vec3_up, AXIS_Y);

// setting node scale to Scale_X, Scale_Y, Scale_Z along the corresponding axes
node->setWorldScale(vec3(Scale_X, Scale_Y, Scale_Z));

// setting new transformation matrix to scale the node 2 times along all axes, rotate it by 45 degrees around the Z-axis and move it by 1 unit along all axes
Mat4 transform = Mat4(translate(vec3(1.0f, 1.0f, 1.0f)) * rotate(quat(0.0f, 0.0f, 1.0f, 45.0f)) * scale(vec3(2.0f)));

// setting node transformation matrix relative to its parent
node->setTransform(transform);

// setting node transformation matrix relative to the world origin
node->setWorldTransform(transform);

Additional information: Дополнительная информация:

• For more information on matrix transformations, see the Matrix Transformations article.Для получения дополнительной информации о матричных преобразованиях см. статью Матричные преобразования.

As the frame rate of our application may vary (i.e. the AppWorldLogic::update() method will be called more or less frequently) depending on hardware, we should do something to ensure that certain actions are performed at the same time periods regardless of the frame rate (e.g. change something once per second etc). To make your game frame rate independent you can use a scaling multiplier (the time in seconds it took to complete the last frame) returned by the following methods:Поскольку частота кадров нашего приложения может варьироваться (т.е. метод AppWorldLogic::update() будет вызываться более или менее часто) в зависимости от аппаратного обеспечения, мы должны что-то сделать, чтобы гарантировать, что определенные действия выполняются в одни и те же периоды времени независимо от частоты кадров (например, изменять что-то один раз в секунду и т.д.). Чтобы сделать частоту кадров вашей игры независимой, вы можете использовать множитель масштабирования (время в секундах, затраченное на завершение последнего кадра), возвращаемый следующими методами:

• Engine::getIfps() returns the inverse FPS value for your application.Engine::getIfps() возвращает обратное значение FPS для вашего приложения.
• Game::getIfps() returns the scaled inverse FPS value. This class is to be used when you want to speed up, slow down or pause rendering, physics or game logic.Game::getIfps() возвращает масштабированное обратное значение FPS. Этот класс предназначен для использования, когда вы хотите ускорить, замедлить или приостановить рендеринг, физику или игровую логику.

To change the transformations you can use the following code:Чтобы изменить преобразования, вы можете использовать следующий код:

#include <UnigineGame.h>

// injecting Unigine namespace to the global namespace
using namespace Unigine;

int AppWorldLogic::update()
{

	// getting an inverse FPS value (the time in seconds it took to complete the last frame)
	float ifps = Game::getIFps();

	// moving the node up by 0.3 units every second instead of every frame
	node->worldTranslate(Math::Vec3(0.0f, 0.0f, 0.3f * ifps));

	return 1;
}

To perform some changes once in a certain period of time you can use the following code:Чтобы выполнить некоторые изменения один раз за определенный промежуток времени, вы можете использовать следующий код:

#include <UnigineGame.h>

// injecting Unigine namespace to the global namespace
using namespace Unigine;

const float INTERVAL_DURATION = 5;		// interval duration
float elapsed_time = INTERVAL_DURATION;	// current time left to make changes

int AppWorldLogic::update()
{

	// getting an inverse FPS value (the time in seconds it took to complete the last frame)
	float ifps = Game::getIFps();

	// checking if it's time to make changes
	if (elapsed_time < 0.0f)
	{

		/* .. DO SOME CHANGES .. */

		// resetting elapsed time counter
		elapsed_time = INTERVAL_DURATION;
	}

	// decreasing elapsed time counter
	elapsed_time -= ifps;

	return 1;
}

Additional information: Дополнительная информация:

• For more information on the Game class, see the Game class article.Для получения дополнительной информации о классе Game см. статью Game.
• For more information on the Engine class, see the Engine class article.Для получения дополнительной информации о классе Engine см. статью Engine.

Intersections are widely used in 3D applications. In UNIGINE there are three main types of intersections: Пересечения широко используются в 3D-приложениях. В UNIGINE существует три основных типа пересечений:

• World intersection - an intersection with objects and nodes. World Intersection — пересечение с объектами и нодами.
• Physics intersection - an intersection with shapes and collision objects. Physics Intersection — пересечение с формами и коллизионными объектами.
• Game intersection - an intersection with pathfinding nodes like obstacles. Game Intersection — пересечение с нодами поиска пути, такими как препятствия.

But there are some conditions to detect intersections with the surface: Но есть некоторые условия для обнаружения пересечений с поверхностью:

1. The surface is enabled.Поверхность включена.
2. The surface has a material assigned.Поверхности присвоен материал.

3. Per-surface Intersection flag is enabled.Для каждой поверхности включен флаг Intersection.

   Примечание

   You can set this flag to the object's surface by using the Object.setIntersection() function.Вы можете установить этот флаг на поверхность объекта с помощью функции Object.setIntersection().

The code below illustrates several ways of using world intersections:Приведенный ниже код иллюстрирует несколько способов использования мировых пересечений: