This page has been translated automatically.
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
High-Level Systems
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
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
Rendering-Related Classes
Warning! This version of documentation is OUTDATED, as it describes an older SDK version! Please switch to the documentation for the latest SDK version.
Warning! This version of documentation describes an old SDK version which is no longer supported! Please upgrade to the latest SDK version.

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 of the 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).
    Notice
    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 organized in libraries.
  • Shaders and textures to which material libraries 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.

Notice
To be loaded properly, a world must be stored together with a world script UnigineScript file (*.cpp) 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 in run-time. Resources that are no longer needed are unloaded from memory.

Notice
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  thousands 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 of the objects existing in real life. For convenience, they are divided into several groups that are responsible for different kinds of operations.

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

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

Notice
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 of the corresponding libraries. Such references are created automatically when you assign a material or a property to a surface.

Notice
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 Nodes 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.

Surface Hierarchy

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

Surfaces

Hierarchy of Surfaces

The number of surfaces depends on how a mesh was exported from a 3D editor and cannot be changed dynamically in the runtime. Each surface may add a separate DIP call to the GPU.

Notice
However, 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.

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

Notice
Disabling or enabling a parent surface won't disable or enable its child surfaces.
The surfaces' hierarchal order can be freely changed (by dragging the node with ALT pressed). However, the surfaces themselves cannot be added, deleted, or otherwise altered in UnigineEditor. The reason is that surfaces are formed during object creation in an external 3D editor. So to change them, one needs to re-export the object.

The surface uses a separate material and a property, both of which are loaded from the corresponding libraries.

Clicking the icon enables to edit an instanced material or a property on the spot. That means, a child material/property is created, and only its changed parameters (if compared to the parent) are stored in the world file.

Notice
The number of instanced materials or properties should be limited, as it decreases performance.

Surfaces often represent LODs of the same object. For the detailed description of Min parent, Max parent, Visible and Fade distances parameters, see Level 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.

Materials

Nodes themselves are not visible in a scene. The information on how a node is to be 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, namely:

  • 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, which are contained in the Unigine material library by default, are hard-coded; values for all other materials can be changed.
  • 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 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 render 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 materials. It is shaders which actually draw the material based on different conditions. Each material is usually equipped with several shaders, and the appropriate one is chosen according to the current render pass and state.

Material Hierarchy

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

By default, Unigine provides a set of base materials, which are always at the top of the material hierarchy. If you need to extend properties of a base material or modify it, you can create a new material by inheriting from the required base material: the base material will pass its properties to the inherited material. Then you can add new properties or override the existing ones.

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

Hierarchy of Materials in the Materials Window

Look at the picture below, for example.

Cube Primitive with mesh_base Material Assigned
Cube Primitive with a Material Inherited from mesh_base

The left cube is rendered using one of the base materials from the standard Unigine material library. The right cube inherits its material from that base and simply changes 2 textures (a diffuse and a normal texture). There is no need to set other properties, as they are inherited. However, if one needs, they may change any property, just like we've changed the texture for the cube.

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 edit the XML file with your material definition manually. In this case, refer to the Material File Format article, as it contains a thorough description of material declarations in XML.

Material Libraries

To be used in the world, a set of materials should be organized in a library, reference to which, in turn, should be included in the .world file. Surfaces of nodes positioned in the world will directly refer materials of this library.

Notice
External .node files can also include the reference to the material library.

If you add a material library via the Materials window of UnigineEditor, the reference to this library will be added to the .world file automatically.

A material library is an XML file with the .mat extension, which simply lists required materials with their properties. By default, Unigine SDK includes a set of material libraries located in the data/core/materials/default directory.

Notice
There is no need to include the default material libraries into the world, they are included by default.

All materials in the material library should be inherited from the base materials. If for some reason you cannot find the material to inherit or you need a special post-process, there is a way of creating a brand new material.

The proper order of materials loading is important. If one library has materials that inherit from materials in another library, the second library should be included first. For example, you have two libraries, custom1.mat and custom2.mat. If a material in custom2.mat (F in the picture below) inherits from a material in custom1.mat (C in the picture below), the library custom1.mat should be loaded first.

Loading Order for Material Libraries

Notice
You can set load order, save or remove material libraries via the Materials window of UnigineEditor.

Properties

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

A property is a set of options, states and parameters:

  • Options. The set of options is pre-defined and invariable for all properties. Each option either enables or disables some kind of behavior. Option values can be changed only for custom properties; options for base properties are hard-coded.
  • States. The states define conditions, based on which parameters of the property becomes available/unavailabe for reading and editing.
  • Parameters. Logic-related parameters.

For example, they specify if the object is interactive and whether it is a switch. For a character, properties can specify the character health points or gold amount. Thus, the properties make the nodes comply with the game/application logic.

Properties are organized according to the same principles as materials.

Property Hierarchy

A property hierarchy is represented by the hierarchically organized list of the properties, which can be assigned to the nodes used in the scene. A property hierarchy is independent of node and material hierarchies.

Hierarchy of Properties

By default, Unigine provides 2 base properties which are at the top of hierarchy and cannot be changed. If you need to change a particular setting of the base property, you can create a new property by inheriting from the base one.

Notice
When inheriting from a property (the base or the custom one), the parent property passes all its settings to the child property. If the parent property (except the base one) is modified later, all inherited properties will be updated automatically.
You can also create a custom property on the same level as the base property and specify any settings for it.
Notice
If the new property is assigned to a node surface, it should be inherited from the surface_base property or from one of its children. Otherwise, the surface can behave incorrectly.

The hierarchy is easily edited in the desired way: the inheritance relations can be changed simply by dragging, properties can be cloned, assigned or removed with one button click. Apart from cloning the whole property, it is also possible to copy separately all its settings, choose another property, to which they will be applied, and merely paste them.

Property Libraries

To be used in the world, a set of properties should be organized in libraries. Property libraries describe states and parameters of properties as well as parent-child relations. They are stored in the XML file with the .prop extension that should be declared in the .world file for library preloading.

If you add a property library via the Properties window of UnigineEditor, the reference to this library will be added to the .world file automatically.

Notice
The order of properties loading is important, just like for materials.

By default, Unigine SDK includes a set of property libraries located in the data/core/properties directory.

Notice
There is no need to include the default property libraries into the world, they are included by default.
Last update: 2017-07-03
Build: ()