UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Landscape Tool
Using Editor Tools for Specific Tasks
FAQ
Programming
Fundamentals
Setting Up Development Environment
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
CIGI Client Plugin
Rendering-Related Classes

Basic Object Movements

After adding an object to Unigine, you can control its transformations with your control devices. This article shows how to control basic object movements and combine different transformations.

See Also#

Direction Vector#

A direction vector is an important concept of mesh transformation. To move the node forward, you should know where is the forward direction of the mesh. When the mesh is exported from a 3D editor, it saves the information about the forward direction. And when you add the mesh to the Unigine, it will have the same orientation as it had in a 3D editor.

A mesh in Maya
The same mesh in Unigine

On pictures given above, the direction vector has positive Y-direction. To move this mesh forward, you should get the direction of the mesh by using the Y component (the second column) of the world transformation matrix of the mesh.

The point is that content creators and programmers should make an arrangement about the direction vector.

Basic Movements#

Moving Forward#

This section contains different ways of setting the forward movement of the mesh.

In this example, we used the "p" key pressing to move the mesh forward. The direction vector is visualized for clarity.

Source code (C++)
// AppWorldLogic.h

#include <UnigineLogic.h>
#include <UnigineStreams.h>
#include <UnigineObjects.h>

class AppWorldLogic : public Unigine::WorldLogic {

public:
	AppWorldLogic();
	virtual ~AppWorldLogic();

	virtual int init();

	virtual int update();
	virtual int render();
	virtual int flush();

	virtual int shutdown();
	virtual int destroy();

	virtual int save(const Unigine::StreamPtr &stream);
	virtual int restore(const Unigine::StreamPtr &stream);

private:
	// define the ObjectMeshStatic instance
	// so that it will be deleted with the AppWorldLogic instance
	Unigine::ObjectMeshStaticPtr mesh;
	
	Unigine::PlayerSpectatorPtr player;
};
Source code (C++)
// AppWorldLogic.cpp

#include "AppWorldLogic.h"
#include <UnigineControls.h>
#include <UnigineObjects.h>
#include <UnigineEditor.h>
#include <UniginePlayers.h>
#include <UnigineMathLib.h>
#include <UnigineGame.h>
#include <UnigineMesh.h>
#include <UnigineVisualizer.h>

using namespace Unigine;
using namespace Math;

// define the movement speed
float movement_speed = 5.0f;

int AppWorldLogic::init() {

	// enable visualizer
	Visualizer::get()->setEnabled(1);

	// create a camera and add it to the world
	player = PlayerSpectator::create();
	
	// set the camera position and direction so that it is pointed at the object
	player->setPosition(Vec3(4.0f, -3.401f, 1.5f));
	player->setDirection(vec3(0.0f, 1.0f, -0.4f),player->getUp());
	Game::get()->setPlayer(player->getPlayer());

	// create a mesh by adding a box surface to it
	MeshPtr mesh_0 = Mesh::create();
	mesh_0->addBoxSurface("box_surface", vec3(1.0f));
	// create the ObjectMeshStatic by using the new mesh
	mesh = ObjectMeshStatic::create(mesh_0);
	
	// set the mesh position and material
	mesh->setPosition(Vec3(4.0f,0.0f,1.0f));
	mesh->setMaterial("mesh_base", "*");

	// check if the key is pressed and update the state of the specified control
	// you can use both 'p' or ASCII code (112)
	ControlsApp::get()->setStateKey(Controls::STATE_AUX_0, 'p');

	return 1;
}

// start of the main loop
int AppWorldLogic::update() {

	// get the frame duration
	float ifps = Game::get()->getIFps();

	// get the current world transformation matrix of the mesh
	Mat4 transform = mesh->getWorldTransform();

	// get the direction vector of the mesh from the second column of the transformation matrix
	Vec3 direction = transform.getColumn3(1);
	
	// render the direction vector for visual clarity
	Visualizer::get()->renderDirection(mesh->getWorldPosition(), vec3(direction), vec4(1.0f, 0.0f, 0.0f, 1.0f), 0.1f, 0);

	// check if the control key is pressed
	if (ControlsApp::get()->getState(Controls::STATE_AUX_0)) {

		// calculate the delta of movement
		Vec3 delta_movement = direction * movement_speed * ifps;

		// set a new position to the mesh
		mesh->setWorldPosition(mesh->getWorldPosition() + delta_movement);
	}

	return 1;
}

Another Way of Setting Mesh Position#

The new position can be also set by setting the WorldTransform variable. The following examples contain the code from the Update() function of the AppWorldLogic class. The part of controls initialization is the same for this method, the difference is in the Update() function only.

Source code (C++)
// check if the control key is pressed
if (ControlsApp::get()->getState(Controls::STATE_AUX_0)) {

	// calculate the delta of movement
	Vec3 delta_movement = direction * movement_speed * ifps;

	// set a new position to the mesh
	mesh->setWorldTransform(translate(delta_movement) * transform);
}

Or you can change the translation column of the world transformation matrix (see the Matrix Transformations article) to move the mesh:

Source code (C++)
// check if the control key is pressed.
if (ControlsApp::get()->getState(Controls::STATE_AUX_0)) {

	// calculate the delta of movement
	Vec3 delta_movement = direction * movement_speed * ifps;

	// set a new position
	// here, you can also use transform.setColumn3(3, transform.getColumn3(3) + delta_movement);
	transform.setColumn(3, transform.getColumn(3) + Vec4(delta_movement, 1.0f));

	// set a new world transform matrix to the mesh
	mesh->setWorldTransform(transform);
}

Rotation#

This section contains implementation of the mesh rotation.

You can rotate the mesh in two ways, by changing the transformation matrix represented by the WorldTransform variable (recommended way) or via the SetWorldRotation() function. The following example uses the second one:

Source code (C++)
// AppWorldLogic.h

#include <UnigineLogic.h>
#include <UnigineStreams.h>
#include <UnigineObjects.h>

class AppWorldLogic : public Unigine::WorldLogic {

public:
	AppWorldLogic();
	virtual ~AppWorldLogic();

	virtual int init();

	virtual int update();
	virtual int render();
	virtual int flush();

	virtual int shutdown();
	virtual int destroy();

	virtual int save(const Unigine::StreamPtr &stream);
	virtual int restore(const Unigine::StreamPtr &stream);

private:
	// define the ObjectMeshStatic instane
	// so that it will be deleted with the AppWorldLogic instance
	Unigine::ObjectMeshStaticPtr mesh;
	
	Unigine::PlayerSpectatorPtr player
};
Source code (C++)
// AppWorldLogic.cpp

#include "AppWorldLogic.h"
#include <UnigineControls.h>
#include <UnigineObjects.h>
#include <UnigineEditor.h>
#include <UniginePlayers.h>
#include <UnigineMathLib.h>
#include <UnigineGame.h>
#include <UnigineMesh.h>
#include <UnigineVisualizer.h>

using namespace Unigine;
using namespace Math;

// define the rotation speed
float rotation_speed = 30.0f;

int AppWorldLogic::init() {

	// enable visualizer
	Visualizer::get()->setEnabled(1);

	// create a camera and add it to the world
	player = PlayerSpectator::create();
	
	// set the camera position and direction so that it is pointed at the object
	player->setPosition(Vec3(4.0f, -3.401f, 1.5f));
	player->setDirection(vec3(0.0f, 1.0f, -0.4f),player->getUp());
	Game::get()->setPlayer(player->getPlayer());

	// create a mesh by adding a box surface to it
	MeshPtr mesh_0 = Mesh::create();
	mesh_0->addBoxSurface("box_surface", vec3(1.0f));
	// create the ObjectMeshStatic by using the new mesh
	mesh = ObjectMeshStatic::create(mesh_0);
	
	// set the mesh position and material
	mesh->setPosition(Vec3(4.0f,0.0f,1.0f));
	mesh->setMaterial("mesh_base", "*");

	// check if the key is pressed and update the state of the specified control
	// you can use both 'o' or ASCII code (111)
	ControlsApp::get()->setStateKey(Controls::STATE_AUX_1, 'o');

	return 1;
}

// start of the main loop
int AppWorldLogic::update() {

	// get the frame duration
	float ifps = Game::get()->getIFps();

	// check if the control key is pressed
	if (ControlsApp::get()->getState(Controls::STATE_AUX_1)) {

		// set the node rotation along the Z axis assuming node's scale equal to 1
		mesh->setWorldRotation(mesh->getWorldRotation() * quat(rotateZ(rotation_speed * ifps)), 1);
	}

	return 1;
}

In the example above, the node is rotated to the left by pressing the "o" keyboard key.

Notice
  • It is recommended to set the second argument of the SetWorldRotation() function to 1 for all non-scaled nodes to improve performance and accuracy.
  • Scaling of nodes should be avoided whenever possible, as it requires addidional calculations and may lead to error accumulation.

To rotate the object by via the WorldTransform variable, you should replace the line with the SetWorldRotation() function in the example above with the following one:

Source code (C++)
mesh->setWorldTransform(mesh->getWorldTransform() * Mat4(rotateZ(rotation_speed * ifps)));

This way is preferred, especially in case of complex transformations, as it allows to compose transformation matrix and set it only once.

Combining Movements#

Combining different movement controls is not more difficult than adding only one movement control.

The following example adds a mesh to the world and allows you to control it. You can rotate the mesh by using the "o", "[" keyboard keys and move forward by using the "p" key.

Source code (C++)
// AppWorldLogic.h

#include <UnigineLogic.h>
#include <UnigineStreams.h>
#include <UnigineObjects.h>
#include <UniginePlayers.h>

class AppWorldLogic : public Unigine::WorldLogic {

public:
	AppWorldLogic();
	virtual ~AppWorldLogic();

	virtual int init();
	
	virtual int update();
	virtual int render();
	virtual int flush();

	virtual int shutdown();
	virtual int destroy();

	virtual int save(const Unigine::StreamPtr &stream);
	virtual int restore(const Unigine::StreamPtr &stream);

private:
	// define the ObjectMeshStatic mesh and the player
	// so that they are deleted with the AppWorldLogic instance
	Unigine::ObjectMeshStaticPtr mesh;
	
	Unigine::PlayerSpectatorPtr player;
};
Source code (C++)
// AppWorldLogic.cpp

#include "AppWorldLogic.h"

#include <UnigineControls.h>
#include <UnigineObjects.h>
#include <UnigineEditor.h>
#include <UniginePlayers.h>
#include <UnigineMathLib.h>
#include <UnigineGame.h>
#include <UnigineMesh.h>
#include <UnigineVisualizer.h>

using namespace Unigine;
using namespace Math;

// define the movement and rotation speed
float movement_speed = 5.0f;
float rotation_speed = 30.0f;


int AppWorldLogic::init() {

	// enable visualizer
	Visualizer::get()->setEnabled(1);

	// create a camera and add it to the world
	player = PlayerSpectator::create();
	
	// set the camera position and direction so that it is pointed at the object
	player->setPosition(Vec3(4.0f, -3.401f, 1.5f));
	player->setDirection(vec3(0.0f, 1.0f, -0.4f),player->getUp());
	Game::get()->setPlayer(player->getPlayer());

	// create a mesh by adding a box surface to it
	MeshPtr mesh_0 = Mesh::create();
	mesh_0->addBoxSurface("box_surface", vec3(1.0f));
	// create the ObjectMeshStatic by using the new mesh
	mesh = ObjectMeshStatic::create(mesh_0);
	
	// set the mesh position and material
	mesh->setPosition(Vec3(4.0f,0.0f,1.0f));
	mesh->setMaterial("mesh_base", "*");

	// check if the key is pressed and update the state of the specified control
	// you can use both 'p', 'o', '[' or ASCII codes (112, 111, 113)
	ControlsApp::get()->setStateKey(Controls::STATE_AUX_0, 'p');
	ControlsApp::get()->setStateKey(Controls::STATE_AUX_1, 'o');
	ControlsApp::get()->setStateKey(Controls::STATE_AUX_2, '[');

	return 1;
}

// start of the main loop
int AppWorldLogic::update() {

	// get the frame duration
	float ifps = Game::get()->getIFps();

	// get the current world transform matrix of the mesh
	Mat4 transform = mesh->getWorldTransform();

	// get the direction vector of the mesh from the second column of the transformation matrix
	Vec3 direction = transform.getColumn3(1);

	// initialize the update flag and declare rotation and movement
	int update_transform = 0;
	Mat4 rotation;
	Vec3 delta_movement;

	// render the direction vector for visual clarity
	Visualizer::get()->renderDirection(mesh->getWorldPosition(), vec3(direction), vec4(1.0f, 0.0f, 0.0f, 1.0f), 0.1f, 0);

	// check if the control key for movement is pressed
	if (ControlsApp::get()->getState(Controls::STATE_AUX_0))
	{
		// calculate the delta of movement
		delta_movement = direction * movement_speed * ifps;
		
		update_transform = 1;
	}

	// check if the control key for left rotation is pressed
	if (ControlsApp::get()->getState(Controls::STATE_AUX_1)) 
	{
		// set the node left rotation along the Z axis
		rotation.setRotateZ(rotation_speed * ifps);
		update_transform = 1;
	}
	// check if the control key for right rotation is pressed
	else if (ControlsApp::get()->getState(Controls::STATE_AUX_2)) 
	{
		// set the node right rotation along the Z axis
		rotation.setRotateZ(-rotation_speed * ifps);
		update_transform = 1;
	}
	
	// update transformation if necessary
	if (update_transform)
	{
		// combine transformations: movement + rotation
		transform = transform * rotation;
		transform.setColumn3(3, transform.getColumn3(3) + delta_movement);

		// set the resulting transformation
		mesh->setWorldTransform(transform);
	}

	return 1;
}
Last update: 2019-08-16