Table of Contents

Class MultiMesh

Namespace
Godot
Assembly
GodotSharp.dll

MultiMesh provides low-level mesh instancing. Drawing thousands of MeshInstance3D 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 from each other, performance may be reduced as every single instance will always render (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.

Note: A MultiMesh is a single object, therefore the same maximum lights per object restriction applies. This means, that once the maximum lights are consumed by one or more instances, the rest of the MultiMesh instances will not receive any lighting.

Note: Blend Shapes will be ignored if used in a MultiMesh.

public class MultiMesh : Resource, IDisposable
Inheritance
MultiMesh
Implements
Inherited Members

Constructors

MultiMesh() 

public MultiMesh()

Properties

Buffer 

public float[] Buffer { get; set; }

Property Value

float[]

ColorArray

See SetInstanceColor(int, Color).

[Obsolete("This property is deprecated.")]
public Color[] ColorArray { get; set; }

Property Value

Color[]

CustomDataArray

See SetInstanceCustomData(int, Color).

[Obsolete("This property is deprecated.")]
public Color[] CustomDataArray { get; set; }

Property Value

Color[]

InstanceCount

Number of instances that will get drawn. This clears and (re)sizes the buffers. Setting data format or flags afterwards will have no effect.

By default, all instances are drawn but you can limit this with VisibleInstanceCount.

public int InstanceCount { get; set; }

Property Value

int

Mesh

Mesh resource to be instanced.

The looks of the individual instances can be modified using SetInstanceColor(int, Color) and SetInstanceCustomData(int, Color).

public Mesh Mesh { get; set; }

Property Value

Mesh

Transform2DArray

See SetInstanceTransform2D(int, Transform2D).

[Obsolete("This property is deprecated.")]
public Vector2[] Transform2DArray { get; set; }

Property Value

Vector2[]

TransformArray

See SetInstanceTransform(int, Transform3D).

[Obsolete("This property is deprecated.")]
public Vector3[] TransformArray { get; set; }

Property Value

Vector3[]

TransformFormat

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

public MultiMesh.TransformFormatEnum TransformFormat { get; set; }

Property Value

MultiMesh.TransformFormatEnum

UseColors

If true, the MultiMesh will use color data (see SetInstanceColor(int, Color)). Can only be set when InstanceCount is 0 or less. This means that you need to call this method before setting the instance count, or temporarily reset it to 0.

public bool UseColors { get; set; }

Property Value

bool

UseCustomData

If true, the MultiMesh will use custom data (see SetInstanceCustomData(int, Color)). Can only be set when InstanceCount is 0 or less. This means that you need to call this method before setting the instance count, or temporarily reset it to 0.

public bool UseCustomData { get; set; }

Property Value

bool

VisibleInstanceCount

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

public int VisibleInstanceCount { get; set; }

Property Value

int

Methods

GetAabb()

Returns the visibility axis-aligned bounding box in local space.

public Aabb GetAabb()

Returns

Aabb

GetInstanceColor(int)

Gets a specific instance's color multiplier.

public Color GetInstanceColor(int instance)

Parameters

instance int

Returns

Color

GetInstanceCustomData(int)

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

public Color GetInstanceCustomData(int instance)

Parameters

instance int

Returns

Color

GetInstanceTransform(int)

Returns the Transform3D of a specific instance.

public Transform3D GetInstanceTransform(int instance)

Parameters

instance int

Returns

Transform3D

GetInstanceTransform2D(int)

Returns the Transform2D of a specific instance.

public Transform2D GetInstanceTransform2D(int instance)

Parameters

instance int

Returns

Transform2D

HasGodotClassMethod(in godot_string_name)

Check if the type contains a method with the given name. This method is used by Godot to check if a method exists before invoking it. Do not call or override this method.

protected override bool HasGodotClassMethod(in godot_string_name method)

Parameters

method godot_string_name

Name of the method to check for.

Returns

bool

HasGodotClassSignal(in godot_string_name)

Check if the type contains a signal with the given name. This method is used by Godot to check if a signal exists before raising it. Do not call or override this method.

protected override bool HasGodotClassSignal(in godot_string_name signal)

Parameters

signal godot_string_name

Name of the signal to check for.

Returns

bool

InvokeGodotClassMethod(in godot_string_name, NativeVariantPtrArgs, out godot_variant)

Invokes the method with the given name, using the given arguments. This method is used by Godot to invoke methods from the engine side. Do not call or override this method.

protected override bool InvokeGodotClassMethod(in godot_string_name method, NativeVariantPtrArgs args, out godot_variant ret)

Parameters

method godot_string_name

Name of the method to invoke.

args NativeVariantPtrArgs

Arguments to use with the invoked method.

ret godot_variant

Value returned by the invoked method.

Returns

bool

SetInstanceColor(int, Color)

Sets the color of a specific instance by multiplying the mesh's existing vertex colors. This allows for different color tinting per instance.

For the color to take effect, ensure that UseColors is true on the MultiMesh and VertexColorUseAsAlbedo is true on the material. If you intend to set an absolute color instead of tinting, make sure the material's albedo color is set to pure white (Color(1, 1, 1)).

public void SetInstanceColor(int instance, Color color)

Parameters

instance int
color Color

SetInstanceCustomData(int, Color)

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

For the custom data to be used, ensure that UseCustomData is true.

This custom instance data has to be manually accessed in your custom shader using INSTANCE_CUSTOM.

public void SetInstanceCustomData(int instance, Color customData)

Parameters

instance int
customData Color

SetInstanceTransform(int, Transform3D)

Sets the Transform3D for a specific instance.

public void SetInstanceTransform(int instance, Transform3D transform)

Parameters

instance int
transform Transform3D

SetInstanceTransform2D(int, Transform2D)

Sets the Transform2D for a specific instance.

public void SetInstanceTransform2D(int instance, Transform2D transform)

Parameters

instance int
transform Transform2D
Edit this page