Programming Quick References

Introduction#

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:

Basic Scene Objects#

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.

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.

Additional information:

For more information on UNIGINE node types, see Built-in Node Types section.
For more information on managing nodes via API, see Node-Related Classes section.

Coordinate System#

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.

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

Additional information:

For more information on UNIGINE node types, see Built-in Node Types section.
For more information on managing nodes via API, see Node-Related Classes section.

Logging and Printing Messages to Console#

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:

NoticeTo enable displaying messages in the onscreen overlay use the following command: console_onscreen 1

Source code (C++)

using namespace Unigine;

// auxiliary variables for messages
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", 10);
	
// 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 page.
For more information on the Log class, see Log class page.

Saving and Loading a World#

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.

Notice

In order to use the World class, include the UnigineWorld.h library.

Source code (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.

Notice

In order to use the Console class, include the UnigineConsole.h library.

Source code (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 World class page.
For more information on the console and available commands, see Console page.
For more information on managing the console via API, see Console class page.
For more information on managing world nodes that are to be saved via API, see the methods of the Node class.

Closing the Application#

Any application needs to be closed at some moment. To close your application as well as to manage its window parameters, controls events, etc. you should use App class.

NoticeIn order to work with App class the UnigineApp.h library must be included.

To close the application the following code is to be used:

Source code (C++)

#include <UnigineApp.h>
using namespace Unigine;

/* .. */
		
// closing the application 
App::exit();

Additional information:

For more information on managing the application via API, see App class page.

Creating and Deleting Nodes at Runtime#

Nodes can be created and deleted at runtime almost as easy as in the Editor. The basic set of actions is as follows:

Creation. To create a node we should declare a smart pointer for the type of the node we are going to create and call a constructor of the corresponding class providing construction parameters if necessary.
Deletion. To delete a node we simply call the deleteLater() method for the node we are going to remove.

Source code (C++)

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

Now let us illustrate the process of creating and deleting a node using a simple static mesh (ObjectMeshStatic) by both creating a box surface and loading a mesh from an asset as an example.

Source code (C++)

#include <UnigineObjects.h>
using namespace Unigine;

/* .. */
int AppWorldLogic::init() 
{
	// first, we're creating a mesh instance as it is required to call an ObjectMeshStatic constructor
	MeshPtr mesh = Mesh::create();

	// loading a mesh from an fbx model imported to the data/fbx/ folder using the Editor
	mesh->load("fbx/model.fbx/model.mesh");

	// creating a box surface with a given size to the mesh
	mesh->addBoxSurface("box_surface", Math::vec3(0.5f, 0.5f, 0.5f));

	//create an ObjectMeshStatic node
	ObjectMeshStaticPtr my_object = ObjectMeshStatic::create(mesh);

	// removing the node
	my_object.deleteLater();

	// clearing the mesh
	mesh.clear();

	return 1;
}

Additional information:

For more information on managing world nodes, see the methods of the Node class.

Creating and Setting Up a Camera#

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.

In order to set a new player as active one we should use the Game class which is designed as a singleton.

Notice

In order to use the Game class and PlayerSpectator class we must include the UnigineGame.h and the UniginePlayers.h libraries.

The following code illustrates creation of a PlayerSpectator and setting it as the active game camera.

NoticeBy default the player uses a standard set of controls which can be overridden if necessary.

Source code (C++)

#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::dvec3(-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.
For more information on the Game class, see the Game class article.

Creating and Setting up Light Sources#

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.

Let us consider creation of a world light source as an example:

Source code (C++)

#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.

Creating, Applying and Deleting Materials at Runtime#

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.
Material class which is used to manage each individual material.

Notice

In order to use materials we must include the UnigineMaterials.h library

The following code can be used to create a new material inherited from the mesh_base material.

Source code (C++)

#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.
For more information on managing loaded materials via API, see the Materials class article.
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.

Managing Existing Scene Objects#

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:

getNodeByName() method - when we know node's name
getNodeByID() method - when we know the node's ID

NoticeIn order to be able to use the methods of the World class we must include the UnigineWorld.h library.

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).

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.

Source code (C++)

#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:

Source code (C++)

// 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);

Additional information:

For more information on working managing smart pointers, see the Working with Smart Pointers article.
For more information on the World class, see the World class article.

Performing Basic Transformations (Move, Rotate, Scale)#

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:

Source code (C++)

// 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.

Making the Game Process Framerate-independent#

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:

App::getIfps() returns the inverse FPS value for your application.
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.

To change the transformations you can use the following code:

Source code (C++)

// 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:

Source code (C++)

#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.
For more information on the App class, see the App class article.

Managing Intersections#

Intersections are widely used in 3D applications. In UNIGINE there are three main types of intersections:

World intersection - an intersection with objects and nodes.
Physics intersection - an intersection with shapes and collision objects.
Game intersection - an intersection with pathfinding nodes like obstacles.

But there are some conditions to detect intersections with the surface:

The surface is enabled.
The surface has a material assigned.
Per-surface Intersection flag is enabled.
Notice
You can set this flag to the object's surface by using the Object.setIntersection() function.

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

Source code (C++)

// AppWorldLogic.cpp

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

/* ... */

int listNodes(Vector<Ptr<Node>> &nodes, const char *intersection_with)
{
	Log::message("Total number of nodes intersecting a %s is: %i \n", intersection_with, nodes.size());

	for (int i = 0; i < nodes.size(); i++)
	{
		Log::message("Intersected node: %s \n", nodes.get(i)->getName());
	}

	// clearing the list of nodes 
	nodes.clear();

	return 1;
}

int AppWorldLogic::update() 
{
	// getting a player pointer
	PlayerPtr player = Game::getPlayer();

	// creating a vector to store intersected nodes
	Vector<Ptr<Node>> nodes;

	//-------------------------- FINDING INTERSECTIONS WITH A BOUNDING BOX -------------------------
	
	// initializing a bounding box with a size of 3 units, located at the World's origin 
	WorldBoundBox boundBox(Math::Vec3(0.0f), Math::Vec3(3.0f));

	// finding nodes intersecting a bounding box and listing them if any
	if (World::getIntersection(boundBox, nodes)) 
		listNodes(nodes, "bounding box");

	//------------------------- FINDING INTERSECTIONS WITH A BOUNDING SPHERE ------------------------
		
	// initializing a bounding sphere with a radius of 3 units, located at the World's origin 
	WorldBoundSphere boundSphere(Math::Vec3(0.0f), 3.0f);

	// finding nodes intersecting a bounding sphere and listing them if any
	if (World::getIntersection(boundSphere, nodes)) 
		listNodes(nodes, "bounding sphere");

	//------------------------- FINDING INTERSECTIONS WITH A BOUNDING FRUSTUM -----------------------
		
	// initializing a bounding frustum with a  frustum of the player's camera
	WorldBoundFrustum boundFrustum(player->getCamera()->getProjection(), player->getCamera()->getModelview());

	// finding ObjectMeshStaticNodes intersecting a bounding frustum and listing them if any
	if (World::getIntersection(boundFrustum, Node::OBJECT_MESH_STATIC, nodes)) 
		listNodes(nodes, "bounding frustum");

	//---------------- FINDING THE FIRST OBJECT INTERSECTED BY A RAY CAST FROM P0 to P1 --------------
		
	// initializing points of the ray from player's position in the direction pointed by the mouse cursor 
	Math::ivec2 mouse = Input::getMouseCoord();
	Math::Vec3 p0 = player->getWorldPosition();
	Math::Vec3 p1 = p0 + Math::Vec3(player->getDirectionFromScreen(mouse.x, mouse.y)) * 100;

	//creating a WorldIntersection object to store the information about the intersection
	WorldIntersectionPtr intersection = WorldIntersection::create();

	// casting a ray from p0 to p1 to find the first intersected object
	ObjectPtr obj = World::getIntersection(p0, p1, 1, intersection);

	// print the name of the first intersected object and coordinates of intersection point if any
	if (obj)
	{
		Math::Vec3 p = intersection->getPoint();
		Log::message("The first object intersected by the ray at point (%f, %f, %f) is: %s \n ", p.x, p.y, p.z, obj->getName());
	}
	
	return 1;
}

Additional information:

For more information on intersections, see the Intersections article.
For more information on managing World intersections via API, see the World class article.
For more information on managing Game intersections via API, see the Game class article.
For more information on managing Physics intersections via API, see the Physics class article.

Getting and Managing User Inputs#

The majority of applications are designed to interact with the user. In UNIGINE you can manage user inputs using the following classes:

The following code illustrates how to use Input class to get mouse coordinates in case if a right mouse button was clicked and to close the application if "q" key was pressed (ignoring this key if the console is opened):

Source code (C++)

// AppWorldLogic.cpp

#include <UnigineApp.h>
#include <UnigineConsole.h>
#include <UnigineInput.h>

/* .. */

int AppWorldLogic::update() 
{
	// if right mouse button is clicked
	if (Input::isMouseButtonDown(Input::MOUSE_BUTTON_RIGHT))
	{
		Math::ivec2 mouse = Input::getMouseCoord();
		// report mouse cursor coordinates to the console
		Log::message("Right mouse button was clicked at (%d, %d)\n", mouse.x, mouse.y);
	}
	
	// closing the application if a 'Q' key is pressed, ignoring the key if the console is opened
	if (Input::isKeyDown(Input::KEY_Q) && !Console::isActive())
	{
		App::exit();
	}

	return 1;
}

/* .. */

The following code illustrates how to use App class to do the same: get mouse coordinates in case if a right mouse button was clicked and to close the application if "q" key was pressed (ignoring this key if the console is opened):

Source code (C++)

// AppWorldLogic.cpp

#include <UnigineApp.h>
#include <UnigineConsole.h>

/* .. */

int AppWorldLogic::update() 
{
	// if right mouse button is clicked
	if (App::clearMouseButtonState(App::BUTTON_RIGHT))
	{
		// report mouse cursor coordinates to the console
		Log::message("Right mouse button was clicked at (%d, %d)\n", App::getMouseX(), App::getMouseY());
	}
	
	// closing the application if a 'Q' key is pressed, ignoring the key if the console is opened
	if (App::getKeyState("q") && !Console::isActive())
	{
		App::exit();
	}

	return 1;
}

/* .. */

The following code illustrates how to use Controls class to handle keyboard input:

Source code (C++)

// AppWorldLogic.cpp

#include <UnigineGame.h>

/* .. */

int AppWorldLogic::update() 
{

	// getting current controls
	ControlsPtr controls = Game::getPlayer()->getControls();

	// checking controls states and reporting which buttons were pressed
	if (controls->clearState(Controls::STATE_FORWARD) || controls->clearState(Controls::STATE_TURN_UP))
	{
		Log::message("FORWARD or UP key pressed\n");
	}
	else if (controls->clearState(Controls::STATE_BACKWARD) || controls->clearState(Controls::STATE_TURN_DOWN))
	{
		Log::message("BACKWARD or DOWN key pressed\n");
	}
	else if (controls->clearState(Controls::STATE_MOVE_LEFT) || controls->clearState(Controls::STATE_TURN_LEFT))
	{
		Log::message("MOVE_LEFT or TURN_LEFT key pressed\n");
	}
	else if (controls->clearState(Controls::STATE_MOVE_RIGHT) || controls->clearState(Controls::STATE_TURN_RIGHT))
	{
		Log::message("MOVE_RIGHT or TURN_RIGHT key pressed\n");
	}

	return 1;
}

/* .. */

The following code illustrates how to use ControlsApp class to map keys and buttons to states and then to handle user input:

Source code (C++)

// AppWorldLogic.cpp

#include <UnigineGame.h>

/* .. */

int AppWorldLogic::init() 
{
	// remapping states to other keys and buttons
	ControlsApp::setStateKey(Controls::STATE_FORWARD, App::KEY_PGUP);
	ControlsApp::setStateKey(Controls::STATE_BACKWARD, App::KEY_PGDOWN);
	ControlsApp::setStateKey(Controls::STATE_MOVE_LEFT, 'l');
	ControlsApp::setStateKey(Controls::STATE_MOVE_RIGHT, 'r');
	ControlsApp::setStateButton(Controls::STATE_JUMP, App::BUTTON_LEFT);

	return 1;
}

int AppWorldLogic::update() 
{
	if (ControlsApp::clearState(Controls::STATE_FORWARD))
	{
		Log::message("FORWARD key pressed\n");
	}
	else if (ControlsApp::clearState(Controls::STATE_BACKWARD))
	{
		Log::message("BACKWARD key pressed\n");
	}
	else if (ControlsApp::clearState(Controls::STATE_MOVE_LEFT))
	{
		Log::message("MOVE_LEFT key pressed\n");
	}
	else if (ControlsApp::clearState(Controls::STATE_MOVE_RIGHT))
	{
		Log::message("MOVE_RIGHT key pressed\n");
	}
	else if (ControlsApp::clearState(Controls::STATE_JUMP))
	{
		Log::message("JUMP button pressed\n");
	}

	return 1;
}

/* .. */

Additional information:

For more information on managing user inputs using Input class, see the Input class article.
For more information on managing user inputs using App class, see the App class article.
For more information on managing user inputs using Controls class, see the Controls class article.
For more information on managing user inputs using ControlsApp class, see the ControlsApp class article.

Creating User Interface#

In UNIGINE a Graphical User Interface (GUI) is composed of different types of widgets added to it. Basically, there are two ways of creating GUI:

By adding widgets to the system GUI (Unigine user interface) that is rendered on top of application window.
By adding widgets to a GUI object positioned in the world. In this case, any postprocessing filter can be applied.

To add elements to the system GUI you should use the Gui class.

NoticeIn order to use GUI widgets we must include the UnigineUserInterface.h library.

There are 2 ways to create the GUI layout:

Directly from the code via GUI-related classes
By using User interface (UI) files

The following code demonstrates how to add a label and a slider to the system GUI:

Source code (C++)

#include <UnigineUserInterface.h>
using namespace Unigine;
GuiPtr gui;

int AppWorldLogic::init() 
{
	// getting a GUI pointer
	gui = Gui::get();

	// creating a label widget and setting up its parameters
	WidgetLabelPtr widget_label = WidgetLabel::create(gui, "Label text:");
	widget_label->setToolTip("This is my label!");
	widget_label->arrange();
	widget_label->setPosition(10, 10);

	// creating a slider widget and setting up its parameters
	WidgetSliderPtr widget_slider = WidgetSlider::create(gui, 0, 360, 90);
	widget_slider->setToolTip("This is my slider!");
	widget_slider->arrange();
	widget_slider->setPosition(100, 10);

	gui->addChild(widget_label, Gui::ALIGN_OVERLAP | Gui::ALIGN_FIXED);
	gui->addChild(widget_slider, Gui::ALIGN_OVERLAP | Gui::ALIGN_FIXED);

	return 1;
}

In order to use GUI elements we must specify handlers for various events (click, change, etc.). The following code demonstrates how to set event handlers

Source code (C++)

#include <UnigineUserInterface.h>
using namespace Unigine;

GuiPtr gui;

/// function to be called when button1 is clicked
int onButton1Clicked()
{
	/* .. */
}

/// method to be called when button2 is clicked
int AppWorldLogic::onButton2Clicked()
{
	/* .. */
}

/// method to be called when delete button is clicked
int AppWorldLogic::onButtonDelClicked()
{
	/* .. */
}

/// method to be called when slider position is changed
int AppWorldLogic::onSliderChanged()
{
	/* .. */
}
		
int AppWorldLogic::init()
{

	/* .. */
	
	// getting a GUI pointer
	gui = Gui::get();

	// setting onButton1Clicked function as a clicked event handler for a buttonwidget1 using a CallbackBase variable
	Unigine::CallbackBase *button1_clicked_callback_function = MakeCallback(onButton1Clicked);
	buttonwidget1->addCallback(Gui::CLICKED, button1_clicked_callback_function);

	// setting AppWorldLogic::onButton2Clicked method as a clicked event handler for a buttonwidget2 using a CallbackBase variable
	Unigine::CallbackBase *button2_clicked_callback_method = MakeCallback(this, &AppWorldLogic::onButton2Clicked);
	buttonwidget2->addCallback(Gui::CLICKED, button2_clicked_callback_method);
	
	buttonwidget1->addCallback(Gui::CLICKED, MakeCallback(this, &AppWorldLogic::onButtonDelClicked));

	// setting AppWorldLogic::onSliderChanged method as a changed event handler for a widget_slider
	widget_slider->addCallback(Gui::CHANGED, MakeCallback(this, &AppWorldLogic::onSliderChanged));
	/* .. */
	
}

Additional information:

For more information on UI files, see the UI files article.
For more information on GUI-related API, see the GUI-related classes page.
For more information on the Gui class, see the Gui class article.
For more information on handling events, see the Event Handling Callbacks article.

Playing Sound and Music#

Sound Source

The SoundSource class is used to create directional sound sources. To create a sound source, create an instance of the SoundSource class and specify all required settings:

Source code (C++)

// create a new sound source using the given sound sample file
SoundSourcePtr sound = SoundSource::create("sound.mp3");

// disable sound muffling when being occluded
sound->setOcclusion(0);
// set the distance at which the sound gets clear
sound->setMinDistance(10.0f);
// set the distance at which the sound becomes out of audible range
sound->setMaxDistance(100.0f);
// set the gain that result in attenuation of 6 dB
sound->setGain(0.5f);
// loop the sound
sound->setLoop(1);
// start playing the sound sample 
sound->play();

Ambient Source

To play ambient background music create an instance of the AmbientSource class, specify all required parameters and enable it. Make sure to import the sound asset to the project.

Notice

For an ambient source to be played, a player is always required. In case an ambient source needs to be played when neither a world, nor the editor are loaded, a player, as well as the sound source (see code below), should be created in the SystemLogic.Init() method; otherwise, no sound will be heard.

Source code (C++)

// create a player so that an ambient sound source is played
PlayerSpectatorPtr player = PlayerSpectator::create();
player->setPosition(Vec3(0.0f, -3.401f, 1.5f));
player->setViewDirection(vec3(0.0f, 1.0f, -0.4f));
Game::setPlayer(player);

// create the ambient sound source
AmbientSourcePtr sound = AmbientSource::create("sound.mp3");

// set necessary sound settings
sound->setGain(0.5f);
sound->setPitch(1.0f);
sound->setLoop(1);
sound->play();

Additional information:

For more information on directional sound, see the SoundSource class article.
For more information on ambient sound, see the AmbientSource class article.

Setting Up Physics#

An object should have a body and a shape to be affected by gravity and to collide with other physical objects:

Source code (C++)

// cube 
MeshPtr meshBox = Mesh::create();
meshBox->addBoxSurface("box_surface", Math::vec3(1.0f));
ObjectMeshStaticPtr box = ObjectMeshStatic::create(meshBox);

// create a body and a shape based on the mesh
BodyRigidPtr bodyBox = BodyRigid::create(box);
ShapeBoxPtr shapeBox = ShapeBox::create(bodyBox, Math::vec3(1.0f));

Catching Nodes with World Triggers#

World trigger fire callbacks when any nodes (colliders or not) get inside or outside of them. The trigger can detect a node of any type by its bounding box. The trigger reacts to all nodes (default behavior).

The callback function of World Trigger is actually executed only when the next engine function is called: that is, before updatePhysics() (in the current frame) or before update() (in the next frame) — whatever comes first.

Notice

If you have moved some nodes and want to get callbacks based on changed positions in the same frame, you need to call updateSpatial() first.

The methods addEnterCallback() and addLeaveCallback() add callback functions to be fired when a node enters or leaves the world trigger. A callback function must receive a Node as its first argument.

Source code (C++)

// implement the enter callback
void AppWorldLogic::enter_callback(NodePtr node)
{
	Log::message("\nA node named %s has entered the trigger\n", node->getName());
}

// implement the leave callback
void AppWorldLogic::leave_callback(NodePtr node)
{
	Log::message("\nA node named %s has left the trigger\n", node->getName());
}

WorldTriggerPtr trigger;

int AppWorldLogic::init() {

	// create a world trigger node
	trigger = WorldTrigger::create(Math::vec3(3.0f));
	
	// add the enter callback to be fired when a node enters the world trigger
	trigger->addEnterCallback(MakeCallback(this, &AppWorldLogic::enter_callback));

	// add the leave callback to be fired when a node leaves the world trigger
	trigger->addLeaveCallback(MakeCallback(this, &AppWorldLogic::leave_callback));

	return 1;
}

Last update: 2022-02-18

Help improve this article

Was this article helpful?

Report a problem related to this article

(or select a word/phrase and press Ctrl+Enter)

Programming Quick References

In This Article:

Introduction#

Basic Scene Objects#

Additional information:

Coordinate System#

Additional information:

Logging and Printing Messages to Console#

Saving and Loading a World#

Closing the Application#

Creating and Deleting Nodes at Runtime#

Creating and Setting Up a Camera#

Creating and Setting up Light Sources#

Creating, Applying and Deleting Materials at Runtime#

Managing Existing Scene Objects#

Performing Basic Transformations (Move, Rotate, Scale)#

Making the Game Process Framerate-independent#

Managing Intersections#

Getting and Managing User Inputs#

Creating User Interface#

Playing Sound and Music#

Sound Source

Ambient Source

Setting Up Physics#

Catching Nodes with World Triggers#