This page has been translated automatically.
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
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.

World Cluster

World Cluster is a convenient and performance-friendly method to manage a great number of objects (node references) that are placed in the scene. Whether it is five objects or fifty thousand, World Cluster bakes them and stores in the memory only those objects that are inside a specified range.

It is also a handy tool to automatically scatter randomly sized objects across a definite area. Unlike a World Clutter, a World Cluster objects can be moved and rotated after they were randomly scattered. It means though that as a result Cluster is less memory-efficient, because it stores coordinates transformations for each of the node.

World Cluster is used only with reference nodes. If a baked node reference contains skinned animation or is simulated physically, the animation or simulation will start anew every time they are out of the World Cluster visible range.

There are two ways to create a World Cluster:

  • Using the Create option.
  • Scan the world for node references using the Collector.

See also

  • A WorldCluster class to edit world clusters via UnigineScript

Creating a World Cluster

Create To use a World Cluster for managing a number of objects, you will simply need to do the following:
  • Manually position all node references in the scene.
  • Add a world cluster node: in the Menu Bar, choose Create -> World -> Cluster.
  • Make them child nodes of the added world cluster (by dragging them with left mouse button pressed under the world cluster node).
  • Bake nodes into one Cluster using Create option. The world cluster will automatically load into the memory objects that are currently visible in the view frustum and unload all invisible ones. The world cluster is very efficient performance-wise and allows to handle a lot of objects without any performance drop.
    Only enabled node references will be baked into the world cluster. The disabled ones are left as simple child nodes.
  • To add new objects to the same world cluster, simply make them child nodes and click Create button once again to re-bake the cluster.
Expand If it is necessary to reposition or edit the nodes, use Expand option to un-bake the nodes. They will appear in the list as children and can be transformed or otherwise edited. Do not forget to use rebake them again with Create option.
  • If the same node reference as were baked into a World Cluster is edited outside of it (as a stand-along node), the saved changes will be applied to World Cluster reference nodes only after the world is reloaded. To see the changes take effect, expand a World Cluster and edit one of its child node references.
Clear To remove all node references that were baked into a World Cluster, use Clear option.
  • This option does not delete reference nodes when they are expanded into a list of child nodes of the World Cluster.

World Cluster Parameters

Visible distance Up to the visible distance all node references are rendered that were baked into a World Cluster and are found within this range.
  • If set to infinity (inf), Fade distance parameter will be ignored.
  • The real range of Cluster visibility directly depends on the object (surface) maximum visible distance and also its fade out distance. In case node references disappear at a closer distance, further increase of the visible distance does not any affect the performance in any way.
Fade Distance Across the fade distance the number of rendered node references gradually decreases, as they disappear randomly one by one. The fade distance follows the Visible distance. Without the fade distance node references disappear abruptly, as a clearly seen line. Using fade distance allows the objects to disappear one by one until up to the fade distance only a few left. It makes the disappearing smooth and much less noticeable.
  • For the best result, it is also recommended to combine this effect with objects fade-out.
Shadow The distance to draw objects outside the view frustum. This option allows to eliminate popping of shadows at the edges of the screen when the camera is turning.
  • Choose the smallest possible Shadow distance when there is no popping of shadows.
  • The shadow range to set depends on the mesh size, how high meshes are positioned and also the angle of the sun (which determines how long the shadows from them would be).

Random Generator

The generator helps to randomly scatter and scale node references. After they were automatically positioned, objects that do not fit into a right place can be moved to a better position or deleted. If no manual editing is not planned, it is better to use more memory-efficient World Clutter instead.

To use random generator, simply do the following:

  1. Add node references to be scattered.
  2. Specify the mask for scattering areas.
  3. Adjust generation parameters.
  4. Click Generate button to scatter nodes.
    All nodes that has been previously baked into a World Cluster will be removed. To avoid this, expand the nonempty World Cluster before using random generator.
  5. Click Expand and move nodes to place, rotate them or scale as necessary.
  6. Use Create to rebake nodes into a World Cluster again.

Scattered Objects

Node references that will be scattered throughout a definite area appear in the list. For each of them the probability of appearing is controlled.

Add Add a reference node to the list of Cluster objects that will be randomly scattered.
Remove Delete all selected node references from the list. To select an object, a box near it should be checked.
Probability slider The higher the probability, the more often the node reference can be seen if compared to other Cluster object. Let's say we create a mixed forest with birches and pines. If the probability slider for pines is near to zero, almost all of the forest consists of birches and only several pines will be seen among them. Changing appearing probability does not influence the number of rendered objects, it only specifies the proportion between several objects.
  • If probability is set to zero, the object will not be rendered at all.
  • If there is only one object in the Cluster, the probability parameter (except when it equals zero) is ignored and the object occurrence will depend solely on the density.
Generate Randomly position objects across a specified area by a mask. Each time this button is clicked a random seed value is used. Scattered objects are automatically baked into the current World Cluster.

Scattering Area

Random generator scatters objects across a 2D grid with a pre-defined step. Cluster objects is randomly placed (in a new pattern each time generation is performed, because a random seed value is used) depending on the density and above mentioned probability of appearing.

Size X
Size Y
The size of the scattering area along X and Y axis. Within this area objects will be scattered with specified density.
  • The size is measured in units.
Density Density specifies how many objects there are per square unit. In case there are more than one object in the Cluster, probability will be taken into account, but will not change the resulting number of all rendered objects.
  • If the density value is too high, objects can be penetrating each other.

Lower Density
Lower Density
Higher Density
Higher Density
Mask Areas across which the objects are randomly scattered and areas where there will be no objects from the list. For example, on the terrain a mask allows to scatter stones across the rocky areas, while leaving the grassy ones rock free.
  • The mask is one-channel texture (R8). If there are more channels in the provided mask, they will be ignored.
    • Zero color value specify the areas without Cluster objects.
    • The higher the color value is, the more objects there are in this area and the denser they are positioned.
    • Color value of 255 means the density is as specified in by the corresponding parameter.
  • Masking is done for all objects that are contained in the Cluster list.

World Clutter mask for scattering

Threshold To control the strength of masking, a mask threshold is used. It checks the masked density for an area and if a threshold value is higher than the color value of the mask, objects are scattered across it. If the masked density is not enough, the places is left bare.
  • With the minimum value of 0, the mask is applied as it is.
  • With higher threshold value, the objects will be scattered only in areas marked by the mask as dense. Instead of sparse distribution, objects scattered here and there, they are likely to be rendered in dense isolated groups.
  • With the maximum value of 1, there will be no objects scattered at all.

Minimum Threshold
Threshold = 0
Maximum Threshold
Threshold = 1

Randomizing Objects

To randomize the appearance of scattered objects, two types of values are used:

  • Mean value (i.e.Scale, Offset, Rotation) defines the average value. This is the basic value that will be randomly made higher or lower.
  • Spread value defines the range for possible variation of the parameter. The higher the value, the more diverse the final result will be.
    Spread value is optional: if set to 0, it will not influence the simulation process and only the mean value will be used for all objects.

After these values are specified, each parameter is calculated according to the following formula:

Result = Mean + Random * Spread
where Random is a random value in range from -1 to 1. For example, if a mean value of the parameter equals 3 and a spread value equals 1, the final result will be any in range from 2 to 4.

Scale This parameter allows to randomly scale all scattered objects making some bigger and some smaller.
  • The mean scale value cannot be negative.
Offset Height offset parameter controls whether all objects are positioned at one height or some are found higher or lower. For example, with offset stones can be dug deep into the ground so that only a small top is visible, or placed higher and look bigger.
  • The offset is measured in units.
Rotation X
Rotation Y Rotation Z
These parameters allow to randomly orient the scattered objects.
  • The rotation is set in angles.
  • If a spread value is set to 180, objects will be rotated by 360 degrees.

Orienting along the Relief

Unless objects in the Cluster list are scattered over a completely flat and non-tilted surface, they can be automatically positioned to precisely repeat ups and downs of the relief without any effort. For that, an underlying surface should me made a parent of the World Cluster node.

A parent for intersection can only be a terrain or a mesh object. The mesh should be terrain-like, i.e. it should have only one surface vertically, along the Z coordinate.

World Cluster performs only one vertical intersection testing with parent mesh geometry. If there are surfaces underneath the upper surface, they will be ignored. For example, to scatter reference nodes across the whole sphere, two hemisphere meshes need to be used.

Orientation This option allows to set a parent surface normal vector as the initial orientation for scattered objects. It means, if the surface in some place is vertical, the "up" direction for objects over will be actually pointing to the side.
  • They can be still randomly rotated but relative the orientation of the parent normal.
  • This parameter is enabled only if a world Cluster has a parent node.

Orientation enabled
Orientation enabled
Orientation disabled
Orientation disabled
Angle Just like in the case with grass, the scattering can take into account how steep the slope is.
  • By the minimum value of 0, it makes no difference how flat or how tilted the surface over which the Cluster objects are scattered.
  • The bigger the value is, the flatter the place should be for objects to be scattered over it. As the value increases, at first steep slopes are ignored and then flatter ones become bare.
  • By the maximum value of 1, the objects can be scattered only over perfectly horizontal surface.
  • This parameter is enabled only if a world Cluster has a parent node.

Low Angle
Low angle value
High Angle
High angle value


The collector makes adding of node references as easy as a click of the mouse button. To bake a World Cluster, simply do the following:

  1. Add node references into the world.
  2. Press Update button on the Collector tab. The list of all node reference present in the world (and how many instances of them there are) will be shown.
  3. Select node references to bake by checking corresponding boxes.
  4. Hit Collect button to make the selected nodes children of World Cluster.
  5. Go to the Cluster tab and choose Create.
Last update: 2018-06-04
Build: ()