编程快速参考

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:在接下来的章节中，你会发现如何开始使用UNIGINE编程3D应用程序和视频游戏的基本信息。本常见问题解答包括以下几章:

1. Basic Scene Objects基本场景物体
2. Coordinate System坐标系
3. Logging and Printing Messages to Console日志和打印消息到控制台
4. Saving and Loading a World保存和加载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 Creating用户界面
16. Playing Sound and Music播放声音和音乐
17. Setting Up Physics设置物理
18. Catching Nodes with World Triggers使用World Triggers捕获节点

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 而言，节点 是一种基本类型，所有类型的场景对象都继承自该类型。 其中一些在视觉上出现：Objects、Decals 和 Effects，它们 都有 surfaces 来表示它们的几何体（网格），而其他的（Light Sources、玩家等）是不可见的。

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中的3D空间用右手笛卡尔坐标系表示：X和Y轴形成一个水平面，Z轴指向上方 . 当 exporting 从 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，通过使用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.有关控制台和可用命令的更多信息，请参阅 console 文章。
• 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.一个 camera是一个对世界的视口，没有它你实际上将看不到任何东西。相机在UNIGINE使用players管理。当你添加一个新的播放器时，它会创建一个camera，并指定控件mask ，该相机的后期处理材质。

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>
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.有关玩家的更多信息，请参阅 players 文章。
• For more information on players API, see the Players-Related Classes article.有关播放器 API 的更多信息，请参阅 播放器相关类 文章。
• For more information on the Game class, see the Game class article.有关Game类的更多信息，请参阅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>
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的更多信息，请参阅灯相关类文章。

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:材质分配给节点的特定表面决定了节点的渲染方式。 他们实现 shaders 并控制 options、states、参数和不同类型的纹理 用于在 渲染通道 期间渲染节点。 为了管理材质，我们使用以下两个类：

• 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 <UnigineObjects.h>
using namespace Unigine;

/* .. */

int AppWorldLogic::init() 
{

	// creating a box (ObjectMeshDynamic node)
	MeshPtr mesh = Mesh::create();
	mesh->addBoxSurface("box_surface", Math::vec3(1.5f, 1.5f, 1.5f));
	ObjectMeshDynamicPtr my_mesh = ObjectMeshDynamic::create(mesh);

	// 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", "*");


}

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 namegetNodeByName()方法——当我们知道节点名时
• getNodeByID() method - when we know the node's IDgetNodeByID()方法——当我们知道节点的ID

注意

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)我们需要执行 的向下类型转换(即转换从pointer-to-base pointer-to-derived)。

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:要更改转换，您可以使用以下代码:

// AppWorldLogic.cpp
#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;
// AppWorldLogic.cpp

	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: intersection 在3D应用中被广泛使用。在UNIGINE中有三种主要的交叉口类型:

• World intersection - an intersection with objects and nodes.World intersection - objects 和 nodes 的交集。
• 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:下面的代码说明了几种使用世界交点的方法：

• to find all nodes intersected by a bounding box找出与边界框相交的所有结点
• to find all nodes intersected by a bounding sphere找到所有节点分割的边界范围
• to find all nodes intersected by a bounding frustum找出与边界截锥相交的所有结点
• to find the first object intersected by a ray找到第一个对象分割的射线