Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

MultiMesh

繼承： Resource < RefCounted < Object

使用 GPU 實例提供單一網格的高性能多次繪製。

說明

MultiMesh 提供了低級別的網格產生實體功能。繪製數以千計的 MeshInstance3D 節點可能會很慢，因為每個物件都要提交給 GPU 然後單獨繪製。

MultiMesh 要快得多，因為它可以通過一次繪製呼叫來繪製成千上萬的實例，從而減少 API 的開銷。

缺點是，如果實例之間的距離太遠，性能可能會降低，因為每一個實例總是會被算繪（對於整個物件，它們在空間上被索引為一個）。

由於實例可能具有任何行為，因此用於可見性的 AABB 必須由使用者提供。

注意：MultiMesh 是單個物件，因此適用相同的對每個物件的最大燈光限制。這意味著，一旦最大燈光被一個或多個實例消耗了，其餘的 MultiMesh 實例將不會接收任何光照。

注意：在 MultiMesh 中使用的 Blend Shape 將被忽略。

教學

• 使用 MultiMeshInstance

• 使用 MultiMesh 進行優化

• 使用 MultiMeshInstance 動畫化數千條魚

屬性

PackedFloat32Array	buffer	PackedFloat32Array()
PackedColorArray	color_array
AABB	custom_aabb	AABB(0, 0, 0, 0, 0, 0)
PackedColorArray	custom_data_array
int	instance_count	0
Mesh	mesh
PhysicsInterpolationQuality	physics_interpolation_quality	0
PackedVector2Array	transform_2d_array
PackedVector3Array	transform_array
TransformFormat	transform_format	0
bool	use_colors	false
bool	use_custom_data	false
int	visible_instance_count	-1

方法

AABB	get_aabb() const
Color	get_instance_color(instance: int) const
Color	get_instance_custom_data(instance: int) const
Transform3D	get_instance_transform(instance: int) const
Transform2D	get_instance_transform_2d(instance: int) const
void	reset_instance_physics_interpolation(instance: int)
void	reset_instances_physics_interpolation()
void	set_buffer_interpolated(buffer_curr: PackedFloat32Array, buffer_prev: PackedFloat32Array)
void	set_instance_color(instance: int, color: Color)
void	set_instance_custom_data(instance: int, custom_data: Color)
void	set_instance_transform(instance: int, transform: Transform3D)
void	set_instance_transform_2d(instance: int, transform: Transform2D)

---

列舉

enum TransformFormat: 🔗

TransformFormat TRANSFORM_2D = 0

使用 2D 變換時使用此選項。

TransformFormat TRANSFORM_3D = 1

使用 3D 變換時使用此選項。

---

enum PhysicsInterpolationQuality: 🔗

PhysicsInterpolationQuality INTERP_QUALITY_FAST = 0

Always interpolate using Basis lerping, which can produce warping artifacts in some situations.

PhysicsInterpolationQuality INTERP_QUALITY_HIGH = 1

Attempt to interpolate using Basis slerping (spherical linear interpolation) where possible, otherwise fall back to lerping.

---

屬性說明

PackedFloat32Array buffer = PackedFloat32Array() 🔗

• void set_buffer(value: PackedFloat32Array)

• PackedFloat32Array get_buffer()

There is currently no description for this property. Please help us by contributing one!

Note: The returned array is copied and any changes to it will not update the original property value. See PackedFloat32Array for more details.

---

PackedColorArray color_array 🔗

已棄用： Accessing this property is very slow. Use set_instance_color() and get_instance_color() instead.

Array containing each Color used by all instances of this mesh.

Note: The returned array is copied and any changes to it will not update the original property value. See PackedColorArray for more details.

---

AABB custom_aabb = AABB(0, 0, 0, 0, 0, 0) 🔗

• void set_custom_aabb(value: AABB)

• AABB get_custom_aabb()

Custom AABB for this MultiMesh resource. Setting this manually prevents costly runtime AABB recalculations.

---

PackedColorArray custom_data_array 🔗

已棄用： Accessing this property is very slow. Use set_instance_custom_data() and get_instance_custom_data() instead.

Array containing each custom data value used by all instances of this mesh, as a PackedColorArray.

Note: The returned array is copied and any changes to it will not update the original property value. See PackedColorArray for more details.

---

int instance_count = 0 🔗

• void set_instance_count(value: int)

• int get_instance_count()

將被繪製的實例數。這會清除緩衝區，並（重新）調整其大小。之後設定的資料格式或旗標將無效。

預設情況下，所有實例都會被繪製，但可以使用 visible_instance_count 來限制它。

---

Mesh mesh 🔗

• void set_mesh(value: Mesh)

• Mesh get_mesh()

要被產生實體的 Mesh 資源。

各個實例的外觀可以通過 set_instance_color() 和 set_instance_custom_data() 來修改。

---

PhysicsInterpolationQuality physics_interpolation_quality = 0 🔗

• void set_physics_interpolation_quality(value: PhysicsInterpolationQuality)

• PhysicsInterpolationQuality get_physics_interpolation_quality()

Choose whether to use an interpolation method that favors speed or quality.

When using low physics tick rates (typically below 20) or high rates of object rotation, you may get better results from the high quality setting.

Note: Fast quality does not equate to low quality. Except in the special cases mentioned above, the quality should be comparable to high quality.

---

PackedVector2Array transform_2d_array 🔗

已棄用： Accessing this property is very slow. Use set_instance_transform_2d() and get_instance_transform_2d() instead.

Array containing each Transform2D value used by all instances of this mesh, as a PackedVector2Array. Each transform is divided into 3 Vector2 values corresponding to the transforms' x, y, and origin.

Note: The returned array is copied and any changes to it will not update the original property value. See PackedVector2Array for more details.

---

PackedVector3Array transform_array 🔗

已棄用： Accessing this property is very slow. Use set_instance_transform() and get_instance_transform() instead.

Array containing each Transform3D value used by all instances of this mesh, as a PackedVector3Array. Each transform is divided into 4 Vector3 values corresponding to the transforms' x, y, z, and origin.

Note: The returned array is copied and any changes to it will not update the original property value. See PackedVector3Array for more details.

---

TransformFormat transform_format = 0 🔗

• void set_transform_format(value: TransformFormat)

• TransformFormat get_transform_format()

用於變換網格的變換格式，可以是 2D 或 3D。

---

bool use_colors = false 🔗

• void set_use_colors(value: bool)

• bool is_using_colors()

如果為 true，則該 MultiMesh 將使用顏色資料（參見 set_instance_color()）。只有在 instance_count 為 0 或更少時才能被設定。這意味著需要在設定實例計數之前呼叫該方法，或者暫時將實例計數重設為 0。

---

bool use_custom_data = false 🔗

• void set_use_custom_data(value: bool)

• bool is_using_custom_data()

如果為 true，則該 MultiMesh 將使用自訂資料（參見 set_instance_custom_data()）。只有在 instance_count 為 0 或更少時才能被設定。這意味著需要在設定實例計數之前呼叫該方法，或者暫時將實例計數重設為 0。

---

int visible_instance_count = -1 🔗

• void set_visible_instance_count(value: int)

• int get_visible_instance_count()

限制繪製的實例數量，-1 會繪製所有的實例。改變這一點並不改變緩衝區的大小。

---

方法說明

AABB get_aabb() const 🔗

返回局部空間中的可見性軸對齊包圍框。

---

Color get_instance_color(instance: int) const 🔗

獲取特定實例的顏色倍數。

---

Color get_instance_custom_data(instance: int) const 🔗

返回已經為特定實例設定的自訂資料。

---

Transform3D get_instance_transform(instance: int) const 🔗

返回指定實例的 Transform3D。

---

Transform2D get_instance_transform_2d(instance: int) const 🔗

返回指定實例的 Transform2D。

---

void reset_instance_physics_interpolation(instance: int) 🔗

When using physics interpolation, this function allows you to prevent interpolation on an instance in the current physics tick.

This allows you to move instances instantaneously, and should usually be used when initially placing an instance such as a bullet to prevent graphical glitches.

---

void reset_instances_physics_interpolation() 🔗

When using physics interpolation, this function allows you to prevent interpolation for all instances in the current physics tick.

This allows you to move all instances instantaneously, and should usually be used when initially placing instances to prevent graphical glitches.

---

void set_buffer_interpolated(buffer_curr: PackedFloat32Array, buffer_prev: PackedFloat32Array) 🔗

An alternative to setting the buffer property, which can be used with physics interpolation. This method takes two arrays, and can set the data for the current and previous tick in one go. The renderer will automatically interpolate the data at each frame.

This is useful for situations where the order of instances may change from physics tick to tick, such as particle systems.

When the order of instances is coherent, the simpler alternative of setting buffer can still be used with interpolation.

---

void set_instance_color(instance: int, color: Color) 🔗

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

Note: Each component is stored in 32 bits in the Forward+ and Mobile rendering methods, but is packed into 16 bits in the Compatibility rendering method.

For the color to take effect, ensure that use_colors is true on the MultiMesh and BaseMaterial3D.vertex_color_use_as_albedo 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)).

---

void set_instance_custom_data(instance: int, custom_data: Color) 🔗

Sets custom data for a specific instance. custom_data is a Color type only to contain 4 floating-point numbers.

Note: Each number is stored in 32 bits in the Forward+ and Mobile rendering methods, but is packed into 16 bits in the Compatibility rendering method.

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

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

---

void set_instance_transform(instance: int, transform: Transform3D) 🔗

為指定實例設定 Transform3D。

---

void set_instance_transform_2d(instance: int, transform: Transform2D) 🔗

為指定實例設定 Transform2D。