Getting Started

When you create an application in UNIGINE, it is represented by a project. A project is a "container" for the application's code, content, and meta-data.

A project can consist of one or several complex 3D scenes, which are called worlds.

All projects are managed via the UNIGINE SDK browser.

A UNIGINE-based virtual world is a 3D scene that contains a set of different scene graph nodes (e.g. static meshes, lights, cameras, etc.) placed into specified positions, and global settings (rendering, physics, etc.) applied to the whole scene.

A scene graph in UNIGINE is a multi-root tree (hierarchy) of nodes.

Each world is represented by an XML file with the .world extension.

When you create a new project via the SDK Browser, a new world is also created with the same name as your project.

To edit your existing worlds and create new ones use the UnigineEditor. You can create and use as many worlds as you need.

In terms of UNIGINE, all objects added to the scene are called nodes. Nodes can be of different types, determining their visual representation and behavior.

There is a rich set of built-in node types. Though the set covers almost all of required cases, it can be manually extended by the user.

You can also extend basic functionality of any node by adding components to it.

Every node has a transformation matrix, which encodes position, rotation, and scale of the node in the world.

There are node types which appear visually: Objects, Decals, and Effects. All of them have surfaces to represent their geometry (mesh). Other node types (Light Sources, Players, etc.) are invisible.

Node parameters are regularly stored in the .world file, but also can be saved into a separate XML file with the .node extension (and later be referenced from the .world file via the special nodes called Node References, which is used for node instancing).

A mesh is a collection of polygons defining object's geometry. It has the following properties:

• Each mesh has one or several surfaces.
• Maximum number of polygons per surface is 2147483647 (ObjectMeshStatic, ObjectMeshSkinned) or 65535 (ObjectMeshDynamic).
• There are 2 UV channels for texturing.
• Mesh supports vertex colors.

Animation in UNIGINE can be performed by skinned meshes (bone-based), morph targets (keyframe) or dynamic meshes (code-controlled).

At run time, meshes are stored in proprietary UNIGINE formats with .mesh (static mesh + optional animation data) and .anim (external animation data) extensions.

When importing an FBX model to the Engine, it is automatically converted to the .mesh format.

A surface is a named non-overlapping subset of the object geometry (i.e. object mesh). Each surface can have its own material or property assigned. It is also possible to enable/disable surfaces independently from each other.

Surfaces can be organized in a hierarchy within a mesh (it can be used for LOD switching).

At the picture below, a soldier 3D mesh consists of 4 surfaces: eyes, skin, bags (body armor, radio set, bag), and body (overalls, shoes, hard hat, gloves).

In terms of UNIGINE, a material is a rule defining how the surface will look like: its interaction with lights, reflection parameters, etc. It is based on:

• Vertex, fragment and geometry shaders that actually draw the material based on different conditions.
• User-defined textures passed to shaders.
• States that specify conditions, basing on which the appropriate shaders will be applied.
• Parameters defining how shaders will be used.

UNIGINE provides a rich set of built-in base materials out of the box. The recommended way is to inherit a new user material from a base one and tweak it. You can also create custom shaders either using UUSL (Unified UNIGINE Shader Language) or HLSL/GLSL, but in the latter case you would need to migrate your custom shaders with every SDK release by yourself.

In addition to regular materials applied to certain surfaces, there is a special type of materials called post materials, that are applied above the final screen composition (e.g. to create a night or thermal vision effect). You can also create your own post-effects with your custom post-materials and custom shaders.

Material Hierarchy#

A property is a "material" for application logic. It specifies the way the object will behave and interact with other objects and the scene environment. Properties can have parameters of various types - from a simple integer representing your character's hit points, to node, material, file (for textures, meshes, sounds, etc.), or property, which simplifies access to various resources.

Properties can be used to build components to extend the functionality of nodes.

Properties, like materials, are organized in a hierarchy with parameter inheritance. But, unlike materials, they can be applied either per-surface or per-node.

UnigineEditor allows you to assemble a virtual world: import and set nodes, assign materials and properties to them, setup lighting, adjust global settings (physics, rendering, etc.) and more. It features What You See Is What You Get approach: you can instantly see the scene with final quality (as at run time).

Watch the tutorial below to learn how to import 3D models to UNIGINE:

Lighting in your worlds is created by placing Light Sources. These nodes contain parameters, which determine various light characteristics, such as brightness, color, etc. You can also use physically-based parameters, like color temperature and illuminance, to set up your lights.

There are different kinds of lights and they emit light in different ways. A light bulb, for example, emits light in all directions - in UNIGINE it is represented by the omni light. A projector, or car headlights emit a cone of light in certain direction - projected light. Light beams that come from the sun appear to be parallel, as their source is located so far away. To simulate this type of lighting in UNIGINE the world light is used.

To learn more about lighting in UNIGINE, see the Lighting Video Tutorial.

UNIGINE has a combination of full deferred renderer with forward rendering techniques:

• All opaque (non-transparent) geometry is rendered in the deferred pass.
• Transparent geometry is rendered in the forward pass.

To learn more about the applied rendering techniques, see the Rendering Sequence article.

All rendering settings (such as global illumination, shadows, environment, anti-aliasing, post-effects, etc.) can be adjusted via the Rendering Settings section in the UnigineEditor and saved to a *.render file to be used later. Each new project contains settings for low, medium, high and ultra quality presets as well as settings optimized for best performance in VR. You can now simply double-click on any of them in the Asset Browser to apply corresponding settings.

To assign some physical properties to an object, so that it could participate in interactions between objects or external physical forces, it should have a body. There are several types of bodies: Rigid, Rag Doll, Fracture, Rope, Cloth, Water, Path.

Almost like in the real world, virtual physics of the body follows the concepts of velocity, force, mass, density and so on.

While a body simulates various types of physical behavior, a shape represents the volume (sphere, capsule, cylinder, box, convex hull) that a rigid body occupies in space. A physically simulated object usually has a single body and one or several shapes which allow objects to collide with each other.

Collision Detection#

Joints are used to connect several objects with respect to the mass balance and represent constraints removing certain degrees of freedom. There are different types of joints: Fixed, Hinge, Ball, Prismatic, Cylindrical, Suspension.

There are global physics settings (gravity, penetration factor, etc.) affecting all physical objects present in the world.

To implement your project's logic in UNIGINE, you can use the following programming languages:

• C++ for maximum performance and seamless integration with the existing code base.
• C# for a good balance between speed and ease of use.
• UnigineScript, fast iterative scripting language featuring instant compilation and thousands of useful functions.

All the APIs are unified: every class, method, and constant are accessible via any API. However, there are minor language-specific differences.

To learn more, see the following usage examples articles:

• UnigineScript API, C++ API and C# API usage examples
• Examples of UnigineScript extension using C++ API
• Examples of UnigineScript extension using C# API

Mixing Languages#

Every UNIGINE-based application has its life cycle, that consists of certain stages, some of them are performed once, others are repeated each frame. In short, these stages are as follows:

UNIGINE has three main logic components, Each of them has a set of functions (named init(), update(), render(), etc.) that contain actions to be performed at corresponding stages of the Engine's working cycle. These components are:

• System Logic is the code that is run during the whole application life cycle (its scope exists even when switching worlds).

  • For applications written using UnigineScript, the system logic is written to the system script file (unigine.usc).
  • For applications that use C++ AppSystemLogic.cpp is created, and for C# applications — AppSystemLogic.cs. This file is stored in the source/ folder of your project. It has implemented methods to put your logic code inside.

• World Logic is the logic of the virtual world. The logic takes effect only when the world is loaded.

  • For applications written using UnigineScript, the world logic is written to the world script file (*.usc named after your project) and is loaded and unloaded together with the corresponding world.
  • For applications that use C++ AppWorldLogic.cpp is created, and for C# applications — AppWorldLogic.cs. This file is stored in the source/ folder of your project and stays loaded during the whole engine runtime. It has implemented methods to put your logic code inside.

• Editor Logic is the logic of the Editor. The logic takes effect only when the UnigineEditor is loaded.

  • You should create an editor logic file to put your logic code inside and add it using the command-line argument.

It is highly recommended that you familiarize yourself with the execution sequence to know the details, including the multi-threaded mode.

Component System#

UNIGINE features a fast intersection detection algorithm. It can be used for ray casting, calculating line-of-sight (LOS), calculating height above terrain (HOT), etc.

Intersections can also be found between the node's bounding volume and another bounding volume of the specified size.

UNIGINE provides a rich set of built-in samples and demo projects covering basic principles of working with the Engine (operations with the built-in nodes, output rendering, GUI setting, etc.). There are different samples for each of the 3 programming languages. All samples come with the full source code. To check them out, go to SDK browser -> Samples tab.

An extended set of content samples is also included for your convenience to illustrate various aspects of working with content: you can learn how to use UNIGINE's built-in objects with different settings, set up LODs and materials, adjust rendering settings, or work with vegetation. These content samples are available via UNIGINE SDK Browser as a demo: go to Samples -> Demos and install the Samples demo.

Smooth alpha-blended levels of details (LODs) are used to decrease geometry complexity of 3D objects, when these objects move away from the camera, making it possible to lighten the load on the renderer.

Usually, LODs are used for:

• Switching high-polygonal surfaces of the mesh to low-polygonal ones.
• Switching surfaces with complex materials to surfaces with simplified optimized ones.
• Switching several high-polygonal surfaces to a single simplified surface.
• Switching one node type to the other (for example, switching a high-polygonal mesh to a billboard, a two-polygonal object that always faces the camera)

Switching between LODs can depend not only on the distance from the camera, but also from the distance from the certain object.

UNIGINE offers two mechanisms of LODs switching:

• Disable one LOD and enable another at the specified distance defined by two values: maximum visibility distance of the first LOD (Max Visibility) and minimum visibility distance of the second LOD (Min Visibility).

  

• Smoothly fade one LOD into another at the specified interval defined by two values: minimum fade distance of the first LOD (Min Fade) and maximum fade distance of the first LOD/minimum fade distance of the second LOD (Max Fade).

  

See the Setting up object LODs article for the details.

Bit masking defines whether two entities affect each other or not. It can be used to:

• Render some objects to the viewport and not to render others.
• Apply collision to some bodies and not to apply to others.
• Render shadows for some objects and not to render for others.
• Apply physics interaction for some objects and ignore others.

The bit masking algorithm compares 32-bit masks of each of two nodes using binary operator and. If masks match, one object will influence another object; if they don't, the objects won't interact.

If two masks have at least one matching bit, the masks match. E.g. the following two masks match, as they have 4 matching bits: