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

Virtual World Structure

A Unigine-based virtual world is a scene that includes a set of different built-in objects with certain properties. Almost all objects can be seen in the virtual world. However, some of them are pseudo-objects, which cannot be displayed in a normal mode (such as physicals, sectors, occluders and so on).

In general, a world includes the following:

  • Built-in objects called nodes, which, in turn, may refer to other nodes (*.node), meshes (*.mesh), audio files (*.oga), paths (*.path) or scripts (*.h).
    A world can store both nodes themselves and/or references to nodes stored in external *.node files. A *.node file, in turn, can also store both nodes and references to other external *.node files.
  • Materials and properties.
  • Shaders and textures to which materials refer.
  • General rendering, physics, sound and game settings.

A new world can be created via the Menu bar of UnigineEditor or via UNIGINE SDK Browser when creating a new project.

Each world is stored on the disk in a separate file in the XML format with the .world extension.

To be loaded properly, a world must be stored together with a world script UnigineScript file (*.usc) named after this world.
In general, the world and the world script can interact bilaterally: via the world script you can affect the world by using data received from this world. However, there may be the following cases:
  • A world script has no implementation. In this case, the world content is created and managed via UnigineEditor.
  • A .world file is empty. In this case, the world content is generated and managed via the world script.

Interaction of the Main Components of the World

Worlds can be as large as a level designer wishes as Unigine supports data streaming, and required resources — meshes, textures, animations, sounds — are dynamically loaded at run time. Resources that are no longer needed are unloaded from memory.

As coordinates of objects in a world are stored as floats, the accuracy of the float data type may be insufficient. However, visual artifacts are noticeable for small objects starting from the distance of 50  thousand units.
Also, for common outdoor scenes, we recommend you to use the scale 1 unit = 1 meter, when you export objects from a 3D modeling software.

For convenience of a large world designing and editing, a world can be split into several parts.

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

Built-in Objects#

Unigine provides a set of built-in objects allowing you to add to a world practically all objects existing in real life. For convenience, they are divided into several groups that are responsible for different kinds of operations.

In terms of Unigine, all objects added into a scene are called nodes and displayed in the World Hierarchy window of UnigineEditor.

A world can store both nodes themselves and/or references to nodes stored in external files with the .node extension.

Irrespective of whether a node is stored in a world or in an external file, it will consist of the same entities.
A node can refer to a mesh ( *.mesh), an audio file (*.oga) or a path (*.path) depending on the node type.

Nodes of object-related types may have surfaces and physical bodies (including collision shapes connected with joints). Surfaces contain references to particular materials and properties. Such references are created automatically when you assign a material or a property to a surface.

A single surface can refer only 1 material and 1 property.

A surface serves as an atomic rendering unit and can represent:

  • A part of the object that needs to have its own separate material.
  • Different levels of details (LODs) (including reflection LODs and shadow LODs). In this case, they represent the same object or its part in more or less detailed variants (a high-polygonal and a low-polygonal model). Which of these surfaces is visible at any given time is determined by the surface properties.
Each surface can also have several morph targets (blend shapes).

Taking into account the information given above, the scheme of world's components can be extended as follows:

Interaction of the Main Components of the World

Node Hierarchy#

All nodes are organized into a hierarchy. Each node can have multiple children.

Nodes Hierarchy List in the World Hierarchy Window

Usually coordinates and orientation of the first-level nodes are set in the global (world) coordinate system, while coordinates and orientation of their child nodes are in local coordinate systems of their parents (if not chosen otherwise). This allows easy transformation and rotation of the whole hierarchy tree branch only by transforming and rotating the root node.

The origin of the global (world) coordinate system is located at the scene center. The origin of the local coordinate system is at the pivot point of the parent node.


As it was mentioned above, nodes of object-related types can have surfaces. By default, such a node added via UnigineEditor has 1 surface.



The number of surfaces depends on how a mesh was imported into UNIGINE and cannot be changed dynamically at run time. However, you can reimport it via UnigineEditor when necessary. Each surface may add a separate DIP call to the GPU.

Identical surfaces of identical meshes with the same material are automatically instanced and drawn in one DIP call.

Surfaces also participate in culling of invisible parts of the object when it is hidden by some other objects on the foreground. Moreover, they are used to calculate collision detection with physically simulated objects.

It is strongly recommended to keep the number of surfaces in the exported art assets as low as reasonably possible to reduce the amount of computations.

Nodes share common options for their surfaces. Each surface can be enabled or disabled for rendering, as needed. Surfaces cannot be added, deleted, or otherwise altered in UnigineEditor. The reason is that surfaces are formed during the object creation in an external 3D editor. To change them, you should re-import the object.

You can assign a separate material and a property to each surface.

Surfaces often represent LODs of the same object. For the detailed description of Min parent, Max parent, Visibility and Fade distances parameters, see Levels of details.

Physical Simulation of Objects#

Besides being only a non-interactive environment, objects can take part in physical simulation. To be effective and at the same time keep the overall framerate high, physics is always a very rough approximation of the real world. Its main aim is to detect collisions between the objects.

For that, an object should be assigned a body that describes how it can behave and what physical properties it possesses. For example, whether it is a rigid body that always stays solid and undeformed or a cloth which can be folded and torn.

However, the type of the object's body is not enough for an object to start interacting. Its volume should be approximated using some kind of a physical primitive (or a set of them) — a shape. Unigine provides several types of such primitives: a box, a sphere, a capsule, a cylinder, a convex hull, or an arbitrary mesh shape. The shape is used to compute collisions between the objects.

A couple of shapes can be connected with one of the joints: fixed, ball, hinge, prismatic, cylindrical, wheel or suspension. They describe how two shapes can possibly move relative to each other.


Nodes themselves are rendered red in the scene. The information on how a node is to be correctly rendered is stored in the materials assigned to particular surfaces of the node. A material is a set of properties (states, options, parameters) and assets (2D, 3D textures), based on which surfaces are rendered.

Material Ball with No Material Assigned
Material Ball with mesh_base Material Assigned
Even if no material is assigned to the node surfaces (surfaces), it still can participate in collisions and intersections.

To manage rendering of surfaces with no materials assigned, use the viewport mask.

Though the surface isn't rendered according to the viewport mask, its shadow will still be rendered.

In Unigine, there are 2 types of materials:

  • Read-only base materials created by programmers and stored in *.basemat files. A Unigine-based project includes a set of default base materials.
  • Editable user materials inherited from the base materials or from the other user materials and stored in *.mat files. Such materials are created by 3D artists and override properties of parent materials.

A set of base material properties may include:

  • Options. The set of options is pre-defined and invariable for all materials. Each option either enables or disables some kind of behavior. Option values for base materials are hard-coded.
  • States. They define conditions, basing on which Unigine selects appropriate shaders, textures, and parameters among all defined. For example, one can define a state turning on and off drawing of foam in water simulation and provide different shaders for both states (with and without foam).
  • Textures. Usually, the base material has several textures defined. The common reasons for it are the following:
    • A shader may need more than one texture for processing.
    • Usually, different textures are used on different rendering passes.
    • States also may influence the number of textures, for example, each state may require its own texture.
  • Parameters. They are passed as arguments to shaders, which require them.
  • Shaders. They are the very core of base materials. It is shaders which actually draw the material based on different conditions.
    Only base materials can refer to shaders.
    Each base material is usually equipped with several shaders, and the appropriate one is chosen according to the current rendering pass and state.

A set of user material properties cannot differ from the base material ones: the user material inherited from the base material only overrides all its options, states, textures and parameters.

The user material cannot refer to a shader. It only can override properties sent to shaders used by the base material from which the user material is inherited.

In Unigine, there are also manual materials. Such materials are created and edited manually: changes made via Materials Editor at run time won't be saved. All base materials (both the built-in and the custom ones) are manual. However, not every manual material is the base one: the user materials can be manual too.

You can use the same name for the base (*.basemat), user (*.mat) and manual (*.basemat or *.mat) materials within one project: it won't raise any conflicts.

Material Hierarchy#

In Unigine, materials are organized in hierarchy, like nodes, but are completely independent from the node hierarchy.

A parent material passes its properties to the inherited material so that they can be overridden.

All inherited and non-overridden properties will be updated automatically, if they are updated in the parent material.

Base materials cannot be organized in hierarchy: no base material can be inherited from another base material. However, if you need to modify properties of a base material, you can create a new user material by inheriting from the required base material: the base material will pass its properties to the inherited material and you can override them. Thus, the base materials are always on the top of the material hierarchy.

Materials hierarchy is based on GUIDs. For base and manual materials, they are generated at run time by using their names stored in materials files. As for user materials, they are also generated at run time on materials' creation and stored in the *.mat files. However, in materials files, references to materials can be name-based or GUID-based.

Surfaces reference to materials by GUIDs only.

When cloning or inheriting a material, each new material becomes internal until a name is assigned to it.

The loading order of materials doesn't matter: on the engine start-up, all materials of the project are loaded, the base materials are loaded first. And since each *.mat material refers to both the parent and the base materials, the base material is used as the parent one until the parent is loaded. So, when the application is loaded, all materials existing in the project are presented in the materials hierarchy.

Hierarchy of Materials in the Materials Hierarchy Window

Look at the picture below, for example.

Material Ball with mesh_base Material Assigned
Material Ball with a User Material Inherited from mesh_base

The left material ball is rendered using one of the built-in base materials. The right material ball inherits its material from that base and simply changes 2 textures (the albedo and normal textures). There is no need to set other properties, as they are inherited. However, if necessary, you may change any property, just like we've changed the texture for the material ball.

All material properties (except shaders) can easily be overridden in UnigineEditor. However, if you need to extend the set of existing properties or override shaders, you need to create a custom material. In this case, refer also to the Materials Files section, as it contains a thorough description of material declarations in XML.


For the object to be correctly integrated into the world, defining its position, inherent characteristics and outside appearance will be insufficient. Properties specify the way the object will behave and interact with other objects and the scene environment.

A property is a "material" for application logic represented by a set of logic-related parameters. Properties can be used to build components to extend the functionality of nodes.

You can define conditions, based on which parameters of the property become available/unavailable in the UnigineEditor.

UNIGINE's Properties system includes the following:

  • Manual properties implemented and modified manually by programmers. A manual property at the top of the hierarchy is called a base property. There are 2 built-in read-only base properties: node_base and surface_base.
  • User properties inherited from the manual ones and adjusted via the UnigineEditor by 3D artists.

Properties can be assigned to both the whole node and a single surface:

  • In the first case, properties can specify additional settings that extend the built-in ones (e.g., they can be used to specify if a node is interactive and whether it is a switch). For a character, properties can be used to specify health points or gold amount.
    You can assign multiple properties to a single node.
  • In the second case, a property can specify certain parameters that can be used during physical interaction with the surface. For example, the property can indicate the type of the material assigned to the surface (wood, metal, plastic, etc.).
    Only one property can be assigned to a surface.

Thus, properties make the nodes comply with the game/application logic.

If you need to assign a property to a single surface, it must be inherited from the surface_base property.
It is recommended to inherit properties that will be assigned to nodes from the node_base property. However, you can also assign any custom base property or its children to a node.

To assign a property, use one of the available ways.

Each property is stored in a separate *.prop file, except for the internal properties.

Property Hierarchy#

Properties in UNIGINE, just like materials, are organized in their own independent hierarchy. This hierarchy is formed by inheriting one property from another. A parent property passes all its parameters to its children so that they can be overridden, much like in object-oriented programming.

All inherited and non-overridden parameters will be updated automatically, if they are updated in the parent property.

Hierarchy of Properties

Propeties hierarchy is based on GUIDs: all properties are referred to using GUIDs, even base and manual ones (the GUIDs for such properties are generated at run time and are uniquely determined by their names). However, only user properties store their GUIDs explicitly: a GUID is generated automatically on user property creation and is written to the corresponding *.prop file.

Properties in the hierarchy can be reparented, renamed, cloned, inherited or removed in a single click.

Reparenting and renaming of manual properties in the UnigineEditor is not supported. To change a parent or a name of a manual property, you should edit the *.prop file manually.
Last update: 2019-04-16