MergeGroup

Inherits: Spatial < Node < Object

MergeGroups allow merging of suitable meshes, which can enhance performance.

Description

MergeGroup is a way of grouping nodes into logical blocks that contain meshes that are suitable for joining together, in order to increase rendering efficiency and reduce the number of nodes to simplify the scene.

Only children and descendants will be considered for merging. MergeGroup has no effect on parents or siblings.

Meshes must be static (non-moving) in relation to one another to be joined. For instance, a level background is often intended to be static. However, logical blocks that move together, such as a ship, or car, are also good candidates for merging.

Within these blocks you will often want to prevent certain nodes or branches from being merged, because they are intended to move, or change visibility, in relation to the main block. An example might be a steering wheel on a ship. You can finely control this with Spatial.merging_mode. Be aware that Spatial.merging_mode will be inherited from parents and ancestors of the MergeGroup.

There are two ways of performing merging:

  • At runtime, using merge_meshes or auto_merge.

  • Baking at design time to a separate scene, using the bake button in the Editor inspector.

Merging at runtime is usually best, because it is non-destructive, and will minimize the binary size of the pck file. It can however take a small amount of time to merge the meshes (usually during level load), but this will usually be well under a second.

Baking ahead of time allows fastest possible load times, but it is by nature a destructive operation - you should keep a copy of the source scene for later editing, because you cannot reconstruct an unmerged scene from a baked scene. It can also bloat the size of the pck file considerably, as for example storing 10 merged trees will have 10x the geometry of the scene before merging.

On the other hand, baking ahead of time is very useful for previewing what will happen after merging, and diagnosing problems. It is also convenient for some workflows such as constructing a scene out of merged modular units.

Properties

bool

auto_merge

true

bool

shadow_proxy

true

Methods

int

get_param ( Param param )

bool

get_param_enabled ( ParamEnabled param )

void

merge_meshes ( )

void

set_param ( Param param, int value )

void

set_param_enabled ( ParamEnabled param, bool value )

Enumerations

enum ParamEnabled:

ParamEnabled PARAM_ENABLED_AUTO_MERGE = 0

Activates merging automatically when the MergeGroup enters the scene (usually during loading).

Alternatively you can switch this off and use merge_meshes to manually activate merging.

ParamEnabled PARAM_ENABLED_SHADOW_PROXY = 1

If true, a shadow proxy will be generated. This is a merged mesh that is a duplicate of the existing opaque geometry, set to cast shadows only. The source meshes will have shadow casting switched off.

This can be more efficient for rendering shadows, because the requirements for merging a shadow mesh are far lower than for regular merging. Providing materials are opaque, meshes with different materials can often be merged together for the purposes of shadow casting. This can reduce drawcalls.

Tip: Try running with and without a shadow proxy and measure performance, sometimes it will be faster, sometimes not.

ParamEnabled PARAM_ENABLED_CONVERT_CSGS = 2

If true, CSG nodes will be converted to MeshInstances. These MeshInstances can then be merged if suitable matches are found.

ParamEnabled PARAM_ENABLED_CONVERT_GRIDMAPS = 3

If true, GridMaps will be converted to MeshInstances. These MeshInstances can then be merged if suitable matches are found.

Note: GridMaps are usually rendered as MultiMeshes very efficiently, so converting these will often be counterproductive. Exceptions include when using the GLES2 backend, which can be inefficient at rendering MultiMesh.

ParamEnabled PARAM_ENABLED_COMBINE_SURFACES = 4

If true, as a final step, matching MeshInstances can be joined by combining their surfaces to form an "uber mesh instance".

While this is convenient, it does have the downside that all the constituent meshes will be culled as one unit, which can make culling less efficient in some situations.

ParamEnabled PARAM_ENABLED_CLEAN_MESHES = 5

Cleans and removes degenerate triangles from meshes, which can make them more suitable for later processing, such as generating secondary UVs for lightmapping.

Note: This step can be slow and should typically only be used when baking the MergeGroup.

enum Param:

Param PARAM_GROUP_SIZE = 0

When set to 0, all matching meshes will be merged within the MergeGroup.

If set to 1 or above, only groups of a maximum of group_size meshes will be merged together. These groups will be chosen by locality. This enables getting some of the benefits of merging, while still allowing some culling to take place.

Tip: Use baking to preview what the scene will look like after merging.

Param PARAM_SPLITS_HORIZONTAL = 1

When set to a value above 1, mesh geometry will be split by locality into a grid of MeshInstances.

For instance a value of 2 will split meshes into a grid of 2x2 (on the x and z axes), for greater culling efficiency.

Note: Greater culling efficiency must be balanced against a greater number of drawcalls.

Param PARAM_SPLITS_VERTICAL = 2

This setting acts exactly as PARAM_SPLITS_HORIZONTAL, except it determines the grid split on the vertical axis.

A grid with PARAM_SPLITS_HORIZONTAL 3, and PARAM_SPLITS_VERTICAL 2 will produce a grid of 3x2x3 (on the x and y and z axes respectively).

Param PARAM_MIN_SPLIT_POLY_COUNT = 3

When using split by locality using PARAM_SPLITS_HORIZONTAL and / or PARAM_SPLITS_VERTICAL, you can specify that the split will only occur for meshes above this specified poly count.

There is often little to gain by splitting meshes with low poly count.

Property Descriptions

bool auto_merge = true

Activates merging automatically when the MergeGroup enters the scene (usually during loading).

Alternatively you can switch this off and use merge_meshes to manually activate merging.

bool shadow_proxy = true

If true, a shadow proxy will be generated. This is a merged mesh that is a duplicate of the existing opaque geometry, set to cast shadows only. The source meshes will have shadow casting switched off.

This can be more efficient for rendering shadows, because the requirements for merging a shadow mesh are far lower than for regular merging. Providing materials are opaque, meshes with different materials can often be merged together for the purposes of shadow casting. This can reduce drawcalls.

Tip: Try running with and without a shadow proxy and measure performance, sometimes it will be faster, sometimes not.

Method Descriptions

int get_param ( Param param )

Returns the value of the specified Param parameter.

bool get_param_enabled ( ParamEnabled param )

Gets the value of the specified ParamEnabled parameter.

void merge_meshes ( )

You can choose to either automatically merge when the MergeGroup enters the scene (usually during loading) using auto_merge, or you can manually trigger merging by calling this function.

Manually activating merging is especially useful when you are procedurally generating your level, and when you want to set advanced parameters prior to merging at runtime.

void set_param ( Param param, int value )

Sets the value of the specified Param parameter.

void set_param_enabled ( ParamEnabled param, bool value )

Sets the value of the specified ParamEnabled parameter.