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 3 ways to create a world cluster:

  • Manually by using the Create option.
  • By scanning the world for node references using the Collector.
  • By generating the cluster with randomly scattered and scaled node references baked into it.

See also

  • A WorldCluster class to edit world clusters via UnigineScript

Creating a World Cluster

To bake the required node references into the world cluster, do the following:

  1. Add a world cluster node: in the Menu Bar, choose Create -> World -> Cluster.

  2. Manually position all node references in the scene.
  3. Add the node references as child nodes to the world cluster: drag them with left mouse button pressed under the world cluster node in the World Hierarchy.
  4. Bake the nodes into the world cluster: in the World Cluster tab of the Parameters window, click using Create option.

    The world cluster will automatically load into the memory the nodes that are currently visible in the view frustum and unload all invisible ones.
    Only enabled node references will be baked into the world cluster. The disabled ones are left as simple child nodes.

To add new nodes to the world cluster, simply make them children and click the Create button once again to re-bake the cluster.

Collecting a World Cluster

There is also another way to bake node references into the world cluster. It allows baking into the world cluster all of the node references existing in the world:

  1. Add a world cluster node: in the Menu Bar, choose Create -> World -> Cluster.

  2. Manually position all node references in the world.
  3. In the World Cluster tab of the Parameters window, press Update in the References group (the last group in the tab). The list of all node reference present in the world will be shown. Moreover, for each node reference the number of instances will be displayed.

  4. In the list of node references, select those ones that should be baked into the world cluster and press. Collect. The selected nodes will become children of the world cluster (can be chaecked in the World Hierarchy).

  5. Press Create to bake the nodes into the world cluster.

Expanding a World Cluster

If it is necessary to reposition or edit the nodes, use Expand option to un-bake the nodes.

They appear in the World Hierarchy as children of the world cluster and can be transformed or otherwise edited. Do not forget to re-bake them again with the Create option.

If the same node reference as were baked into the world cluster is edited outside of it (as a stand-alone node), the saved changes will be applied to reference nodes of the world cluster only after reloading the world. To see the changes take effect, expand the world cluster and edit one of its child node references.

Clearing a World Cluster

To remove all node references that were baked into the world cluster, use the Clear option.

This option doesn't delete reference nodes when they are expanded.

World Cluster Parameters

Nodes Displays the number of node references baked into the world cluster.
Visible Visibility distance for node references baked into the world cluster. Up to this distance all node references of the world cluster are rendered.
  • If set to infinity (inf), the Fade parameter will be ignored.
  • The real range of the world cluster visibility directly depends on the object (surface) maximum visibility distance and also its fade out distance. In case node references disappear at a closer distance, further increasing of the visibility distance doesn't affect the performance.
Fade Fade distance for node references baked into the world cluster. Across this distance the number of rendered node references gradually decreases, as they disappear randomly one by one. The fade distance follows the visibility distance (Visible). Without the fade distance node references disappear abruptly, as a clearly seen line. Using fade distance allows the nodes disappearing one by one until the fade distance is reached. It makes the disappearing smooth and much less noticeable.
  • For the better result, it is also recommended to combine this effect with objects fade-out.

Randomizing Cluster Nodes

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

The random generator settings can be found in the World Cluster tab of the Parameters window.

To generate randomly scattered and scaled node references and bake them into the world cluster, do the following:

  1. Click Add to add node references to the list of the nodes of the world cluster.

    In the dialog window that opens, choose a .node file and click Ok.
    Only selected node references from the list will be baked into the world cluster.
    To clear the list of node references, click Remove.
  2. Move the probability slider for each node reference to specify the probability of their appearance in the world cluster.
  3. Specify the mask for scattering areas (optional).
  4. Adjust generation parameters.
  5. Click Generate to scatter nodes across the specified area by a mask. Scattered nodes will be automatically baked into the current world cluster.
    All nodes that has been previously baked into a World Cluster will be removed. To avoid this, expand the world cluster before using random generator.
  6. Click Expand and move node references to place, rotate them or scale as necessary.
  7. Use Create to re-bake nodes into the world cluster again.

Scattered Nodes

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

Add Add a reference node to the list of world cluster nodes that will be randomly scattered.
Remove Delete all node references from the list.
Probability slider The higher the probability, the more often the node reference can be seen if compared to other world cluster nodes. Let's say we create a mixed forest with birches and pines. If the probability slider for pines is near to 0, almost all of the forest consists of birches and only several pines will be seen among them. Changing probability does not influence the number of rendered nodes, it only specifies the proportion between several nodes.
  • If probability is set to 0, the node will not be rendered at all.
  • If there is only one node in the world cluster, the probability parameter (except when it equals 0) is ignored and the node's occurrence will depend solely on the density.

Scattering Area

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

Size X
Size Y
The size of the scattering area along X and Y axis. Within this area nodes will be scattered with the specified density.
  • The size is measured in units.
Step Cell size in units. The number of cells in the world cluster is defined in the following way: size of the cluster (both along X and Y) is divided by the step.
  • The higher the number of cells (i.e. the smaller the step), the higher the load. However, to create one large cell takes longer time. When the camera moves fast enough, small cells will be created very slow, but large ones can noticeably pop into sight and cause a small rendering lag.
Density Density specifies how many nodes there are per square unit. In case there are more than one node reference in the world cluster, probability will be taken into account, but will not change the resulting number of the rendered objects.
  • If the density value is too high, nodes can penetrate each other.

Lower Density
Lower Density
Higher Density
Higher Density
Mask Areas across which the nodes are randomly scattered and areas where there will be no nodes from the list. For example, on the terrain, the mask allows scattering stones across the rocky areas, while leaving the grassy ones free of rocks.
  • The mask is a 1-channelled texture (R8). If there are more channels in the provided mask, they will be ignored.
    • Zero color value specify the areas without cluster nodes.
    • The higher the color value is, the more nodes are presented in this area and the denser they are positioned.
    • Color value of 255 means the density value is defined by the corresponding parameter only.
  • Masking is done for all nodes that are contained in the world cluster list.

World Cluster mask for scattering

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

Minimum Threshold
Threshold = 0
Maximum Threshold
Threshold = 1
Seed The seed value for pseudo random number generator allows creating different patterns of automatic positioning. The seed can be set manually or the Editor provides a random value for a seed (the Randomize button).

Randomizing Nodes

To randomize the appearance of scattered nodes, 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 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 nodes.

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

Min and Max
The scale mean value of scattered nodes depends on the minimum and maximum scale mean values and the mask values: the mask values are used to linearly interpolate between the minimum and maximum scale values.
  • The mean scale value cannot be negative.
Sets the scale mean value for scattered nodes in the areas with low density (according to the mask). The higher the value, the bigger the nodes will be in such areas.
When the mask is not set, this parameter isn't taken into account as the default mask stores only the maximum mask values (there is no areas with low density).
Sets the scale mean value for scattered nodes in the areas with high density (according to the mask). The higher the value, the bigger the nodes will be in such areas.
Offset Height offset parameter controls whether all nodes are positioned at one height or some are found higher or lower. For example, by using the 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 randomly orienting the scattered nodes.
  • The rotation angles are set in degrees.
  • If a spread value is set to 180, nodes will be rotated by 360 degrees.

Orienting along the Relief

Unless nodes in the world 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 be made a parent of the world cluster node.

A parent for intersection can 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 axis.

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 setting a parent surface normal vector as the initial orientation for scattered nodes. It means that if the surface in some place is vertical, the "up" direction for nodes over will be actually pointing to the side.
  • They can be still randomly rotated but relative the orientation of the parent normal.
  • This parameter takes effect only if the 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 world cluster nodes are scattered.
  • The bigger the value, the flatter the place should be for nodes 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 nodes can be scattered only over perfectly horizontal surface.
  • This parameter takes effect only if the world cluster has a parent node.

Low Angle
Low Angle Value
High Angle
High Angle Value
Last update: 2018-08-10
Build: ()