godot-docs/classes/class_mergegroup.rst

:github_url: hide

.. DO NOT EDIT THIS FILE!!!
.. Generated automatically from Godot engine sources.
.. Generator: https://github.com/godotengine/godot/tree/3.6/doc/tools/make_rst.py.
.. XML source: https://github.com/godotengine/godot/tree/3.6/doc/classes/MergeGroup.xml.

.. _class_MergeGroup:

MergeGroup
==========

**Inherits:** :ref:`Spatial<class_Spatial>` **<** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`

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

.. rst-class:: classref-introduction-group

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 :ref:`Spatial.merging_mode<class_Spatial_property_merging_mode>`. Be aware that :ref:`Spatial.merging_mode<class_Spatial_property_merging_mode>` will be inherited from parents and ancestors of the **MergeGroup**.

There are two ways of performing merging:

- At runtime, using :ref:`merge_meshes<class_MergeGroup_method_merge_meshes>` or :ref:`auto_merge<class_MergeGroup_property_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.

.. rst-class:: classref-reftable-group

Properties
----------

.. table::
   :widths: auto

   +-------------------------+-------------------------------------------------------------+----------+
   | :ref:`bool<class_bool>` | :ref:`auto_merge<class_MergeGroup_property_auto_merge>`     | ``true`` |
   +-------------------------+-------------------------------------------------------------+----------+
   | :ref:`bool<class_bool>` | :ref:`shadow_proxy<class_MergeGroup_property_shadow_proxy>` | ``true`` |
   +-------------------------+-------------------------------------------------------------+----------+

.. rst-class:: classref-reftable-group

Methods
-------

.. table::
   :widths: auto

   +-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`int<class_int>`   | :ref:`get_param<class_MergeGroup_method_get_param>` **(** :ref:`Param<enum_MergeGroup_Param>` param **)**                                                              |
   +-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`bool<class_bool>` | :ref:`get_param_enabled<class_MergeGroup_method_get_param_enabled>` **(** :ref:`ParamEnabled<enum_MergeGroup_ParamEnabled>` param **)**                                |
   +-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                    | :ref:`merge_meshes<class_MergeGroup_method_merge_meshes>` **(** **)**                                                                                                  |
   +-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                    | :ref:`set_param<class_MergeGroup_method_set_param>` **(** :ref:`Param<enum_MergeGroup_Param>` param, :ref:`int<class_int>` value **)**                                 |
   +-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                    | :ref:`set_param_enabled<class_MergeGroup_method_set_param_enabled>` **(** :ref:`ParamEnabled<enum_MergeGroup_ParamEnabled>` param, :ref:`bool<class_bool>` value **)** |
   +-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

Enumerations
------------

.. _enum_MergeGroup_ParamEnabled:

.. rst-class:: classref-enumeration

enum **ParamEnabled**:

.. _class_MergeGroup_constant_PARAM_ENABLED_AUTO_MERGE:

.. rst-class:: classref-enumeration-constant

:ref:`ParamEnabled<enum_MergeGroup_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 :ref:`merge_meshes<class_MergeGroup_method_merge_meshes>` to manually activate merging.

.. _class_MergeGroup_constant_PARAM_ENABLED_SHADOW_PROXY:

.. rst-class:: classref-enumeration-constant

:ref:`ParamEnabled<enum_MergeGroup_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.

.. _class_MergeGroup_constant_PARAM_ENABLED_CONVERT_CSGS:

.. rst-class:: classref-enumeration-constant

:ref:`ParamEnabled<enum_MergeGroup_ParamEnabled>` **PARAM_ENABLED_CONVERT_CSGS** = ``2``

If ``true``, ``CSG`` nodes will be converted to :ref:`MeshInstance<class_MeshInstance>`\ s. These :ref:`MeshInstance<class_MeshInstance>`\ s can then be merged if suitable matches are found.

.. _class_MergeGroup_constant_PARAM_ENABLED_CONVERT_GRIDMAPS:

.. rst-class:: classref-enumeration-constant

:ref:`ParamEnabled<enum_MergeGroup_ParamEnabled>` **PARAM_ENABLED_CONVERT_GRIDMAPS** = ``3``

If ``true``, :ref:`GridMap<class_GridMap>`\ s will be converted to :ref:`MeshInstance<class_MeshInstance>`\ s. These :ref:`MeshInstance<class_MeshInstance>`\ s can then be merged if suitable matches are found.

\ **Note:** :ref:`GridMap<class_GridMap>`\ s are usually rendered as :ref:`MultiMesh<class_MultiMesh>`\ es very efficiently, so converting these will often be counterproductive. Exceptions include when using the ``GLES2`` backend, which can be inefficient at rendering :ref:`MultiMesh<class_MultiMesh>`.

.. _class_MergeGroup_constant_PARAM_ENABLED_COMBINE_SURFACES:

.. rst-class:: classref-enumeration-constant

:ref:`ParamEnabled<enum_MergeGroup_ParamEnabled>` **PARAM_ENABLED_COMBINE_SURFACES** = ``4``

If ``true``, as a final step, matching :ref:`MeshInstance<class_MeshInstance>`\ s 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.

.. _class_MergeGroup_constant_PARAM_ENABLED_CLEAN_MESHES:

.. rst-class:: classref-enumeration-constant

:ref:`ParamEnabled<enum_MergeGroup_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**.

.. rst-class:: classref-item-separator

----

.. _enum_MergeGroup_Param:

.. rst-class:: classref-enumeration

enum **Param**:

.. _class_MergeGroup_constant_PARAM_GROUP_SIZE:

.. rst-class:: classref-enumeration-constant

:ref:`Param<enum_MergeGroup_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.

.. _class_MergeGroup_constant_PARAM_SPLITS_HORIZONTAL:

.. rst-class:: classref-enumeration-constant

:ref:`Param<enum_MergeGroup_Param>` **PARAM_SPLITS_HORIZONTAL** = ``1``

When set to a value above ``1``, mesh geometry will be *split by locality* into a grid of :ref:`MeshInstance<class_MeshInstance>`\ s.

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.

.. _class_MergeGroup_constant_PARAM_SPLITS_VERTICAL:

.. rst-class:: classref-enumeration-constant

:ref:`Param<enum_MergeGroup_Param>` **PARAM_SPLITS_VERTICAL** = ``2``

This setting acts exactly as :ref:`PARAM_SPLITS_HORIZONTAL<class_MergeGroup_constant_PARAM_SPLITS_HORIZONTAL>`, except it determines the grid split on the vertical axis.

A grid with :ref:`PARAM_SPLITS_HORIZONTAL<class_MergeGroup_constant_PARAM_SPLITS_HORIZONTAL>` ``3``, and :ref:`PARAM_SPLITS_VERTICAL<class_MergeGroup_constant_PARAM_SPLITS_VERTICAL>` ``2`` will produce a grid of 3x2x3 (on the ``x`` and ``y`` and ``z`` axes respectively).

.. _class_MergeGroup_constant_PARAM_MIN_SPLIT_POLY_COUNT:

.. rst-class:: classref-enumeration-constant

:ref:`Param<enum_MergeGroup_Param>` **PARAM_MIN_SPLIT_POLY_COUNT** = ``3``

When using *split by locality* using :ref:`PARAM_SPLITS_HORIZONTAL<class_MergeGroup_constant_PARAM_SPLITS_HORIZONTAL>` and / or :ref:`PARAM_SPLITS_VERTICAL<class_MergeGroup_constant_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.

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

Property Descriptions
---------------------

.. _class_MergeGroup_property_auto_merge:

.. rst-class:: classref-property

:ref:`bool<class_bool>` **auto_merge** = ``true``

.. rst-class:: classref-property-setget

- void **set_param_enabled** **(** :ref:`ParamEnabled<enum_MergeGroup_ParamEnabled>` param, :ref:`bool<class_bool>` value **)**
- :ref:`bool<class_bool>` **get_param_enabled** **(** :ref:`ParamEnabled<enum_MergeGroup_ParamEnabled>` param **)**

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

Alternatively you can switch this off and use :ref:`merge_meshes<class_MergeGroup_method_merge_meshes>` to manually activate merging.

.. rst-class:: classref-item-separator

----

.. _class_MergeGroup_property_shadow_proxy:

.. rst-class:: classref-property

:ref:`bool<class_bool>` **shadow_proxy** = ``true``

.. rst-class:: classref-property-setget

- void **set_param_enabled** **(** :ref:`ParamEnabled<enum_MergeGroup_ParamEnabled>` param, :ref:`bool<class_bool>` value **)**
- :ref:`bool<class_bool>` **get_param_enabled** **(** :ref:`ParamEnabled<enum_MergeGroup_ParamEnabled>` param **)**

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.

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

Method Descriptions
-------------------

.. _class_MergeGroup_method_get_param:

.. rst-class:: classref-method

:ref:`int<class_int>` **get_param** **(** :ref:`Param<enum_MergeGroup_Param>` param **)**

Returns the value of the specified :ref:`Param<enum_MergeGroup_Param>` parameter.

.. rst-class:: classref-item-separator

----

.. _class_MergeGroup_method_get_param_enabled:

.. rst-class:: classref-method

:ref:`bool<class_bool>` **get_param_enabled** **(** :ref:`ParamEnabled<enum_MergeGroup_ParamEnabled>` param **)**

Gets the value of the specified :ref:`ParamEnabled<enum_MergeGroup_ParamEnabled>` parameter.

.. rst-class:: classref-item-separator

----

.. _class_MergeGroup_method_merge_meshes:

.. rst-class:: classref-method

void **merge_meshes** **(** **)**

You can choose to either automatically merge when the **MergeGroup** enters the scene (usually during loading) using :ref:`auto_merge<class_MergeGroup_property_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.

.. rst-class:: classref-item-separator

----

.. _class_MergeGroup_method_set_param:

.. rst-class:: classref-method

void **set_param** **(** :ref:`Param<enum_MergeGroup_Param>` param, :ref:`int<class_int>` value **)**

Sets the value of the specified :ref:`Param<enum_MergeGroup_Param>` parameter.

.. rst-class:: classref-item-separator

----

.. _class_MergeGroup_method_set_param_enabled:

.. rst-class:: classref-method

void **set_param_enabled** **(** :ref:`ParamEnabled<enum_MergeGroup_ParamEnabled>` param, :ref:`bool<class_bool>` value **)**

Sets the value of the specified :ref:`ParamEnabled<enum_MergeGroup_ParamEnabled>` parameter.

.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`