Provides high-performance mesh instancing.
    public class MultiMesh : Resource

MultiMesh provides low-level mesh instancing. Drawing thousands of MeshInstance nodes can be slow, since each object is submitted to the GPU then drawn individually.

MultiMesh is much faster as it can draw thousands of instances with a single draw call, resulting in less API overhead.

As a drawback, if the instances are too far away of each other, performance may be reduced as every single instance will always rendered (they are spatially indexed as one, for the whole object).

Since instances may have any behavior, the AABB used for visibility must be provided by the user.

Inheritance Chain

Constructors

    public MultiMesh()

Properties

    public Color[] ColorArray { get; set; }

    public ColorFormatEnum ColorFormat { get; set; }

Format of colors in color array that gets passed to shader.

    public Color[] CustomDataArray { get; set; }

    public CustomDataFormatEnum CustomDataFormat { get; set; }

Format of custom data in custom data array that gets passed to shader.

    public int InstanceCount { get; set; }

Number of instances that will get drawn. This clears and (re)sizes the buffers. By default, all instances are drawn but you can limit this with VisibleInstanceCount.

    public Mesh Mesh { get; set; }

Mesh to be drawn.

    public Vector2[] Transform2dArray { get; set; }

    public Vector3[] TransformArray { get; set; }

    public TransformFormatEnum TransformFormat { get; set; }

Format of transform used to transform mesh, either 2D or 3D.

    public int VisibleInstanceCount { get; set; }

Limits the number of instances drawn, -1 draws all instances. Changing this does not change the sizes of the buffers.

Methods

    public AABB GetAabb()

Returns the visibility axis-aligned bounding box.

    [Obsolete("GetColorFormat is deprecated. Use the ColorFormat property instead.")]
    public ColorFormatEnum GetColorFormat()

Getter for ColorFormat

    [Obsolete("GetCustomDataFormat is deprecated. Use the CustomDataFormat property instead.")]
    public CustomDataFormatEnum GetCustomDataFormat()

Getter for CustomDataFormat

    public Color GetInstanceColor(int instance)

Gets a specific instance’s color.

    [Obsolete("GetInstanceCount is deprecated. Use the InstanceCount property instead.")]
    public int GetInstanceCount()

Getter for InstanceCount

    public Color GetInstanceCustomData(int instance)

Returns the custom data that has been set for a specific instance.

    public Transform GetInstanceTransform(int instance)

Returns the Transform of a specific instance.

    public Transform2D GetInstanceTransform2d(int instance)

Returns the Transform2D of a specific instance.

    [Obsolete("GetMesh is deprecated. Use the Mesh property instead.")]
    public Mesh GetMesh()

Getter for Mesh

    [Obsolete("GetTransformFormat is deprecated. Use the TransformFormat property instead.")]
    public TransformFormatEnum GetTransformFormat()

Getter for TransformFormat

    [Obsolete("GetVisibleInstanceCount is deprecated. Use the VisibleInstanceCount property instead.")]
    public int GetVisibleInstanceCount()

Getter for VisibleInstanceCount

    public void SetAsBulkArray(float[] array)

Sets all data related to the instances in one go. This is especially useful when loading the data from disk or preparing the data from GDNative.

All data is packed in one large float array. An array may look like this: Transform for instance 1, color data for instance 1, custom data for instance 1, transform for instance 2, color data for instance 2, etc…

Transform is stored as 12 floats, Transform2D is stored as 8 floats, COLOR_8BIT / CUSTOM_DATA_8BIT is stored as 1 float (4 bytes as is) and COLOR_FLOAT / CUSTOM_DATA_FLOAT is stored as 4 floats.

    [Obsolete("SetColorFormat is deprecated. Use the ColorFormat property instead.")]
    public void SetColorFormat(ColorFormatEnum format)

Setter for ColorFormat

    [Obsolete("SetCustomDataFormat is deprecated. Use the CustomDataFormat property instead.")]
    public void SetCustomDataFormat(CustomDataFormatEnum format)

Setter for CustomDataFormat

    public void SetInstanceColor(int instance, Color color)

Sets the color of a specific instance.

For the color to take effect, ensure that ColorFormat is non-null on the MultiMesh and SpatialMaterial.VertexColorUseAsAlbedo is true on the material.

    [Obsolete("SetInstanceCount is deprecated. Use the InstanceCount property instead.")]
    public void SetInstanceCount(int count)

Setter for InstanceCount

    public void SetInstanceCustomData(int instance, Color customData)

Sets custom data for a specific instance. Although Color is used, it is just a container for 4 numbers.

    public void SetInstanceTransform(int instance, Transform transform)

Sets the Transform for a specific instance.

    public void SetInstanceTransform2d(int instance, Transform2D transform)

Sets the Transform2D for a specific instance.

    [Obsolete("SetMesh is deprecated. Use the Mesh property instead.")]
    public void SetMesh(Mesh mesh)

Setter for Mesh

    [Obsolete("SetTransformFormat is deprecated. Use the TransformFormat property instead.")]
    public void SetTransformFormat(TransformFormatEnum format)

Setter for TransformFormat

    [Obsolete("SetVisibleInstanceCount is deprecated. Use the VisibleInstanceCount property instead.")]
    public void SetVisibleInstanceCount(int count)

Setter for VisibleInstanceCount

Inner Types

ColorFormatEnum

Name Value Description
None 0 Use when you are not using per-instance [Color]s.
Color8bit    
Float 2 The [Color] passed into [method set_instance_color] will use 4 floats. Use this for highest precision [Color].

CustomDataFormatEnum

Name Value Description
None 0 Use when you are not using per-instance custom data.
Data8bit    
Float 2 The [Color] passed into [method set_instance_custom_data] will use 4 floats. Use this for highest precision.

TransformFormatEnum

Name Value Description
Transform2d    
Transform3d    
Tags: