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	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

始终使用 Basis 线性插值，部分情况下可能产生扭曲问题。

PhysicsInterpolationQuality INTERP_QUALITY_HIGH = 1

尽可能使用 Basis 球面线性插值，否则回退至线性插值。

---

属性说明

PackedFloat32Array buffer = PackedFloat32Array() 🔗

• void set_buffer(value: PackedFloat32Array)

• PackedFloat32Array get_buffer()

该属性目前没有描述，请帮我们贡献一个吧！

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.

包含该网格所有实例使用的每种 Color 的数组。

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()

为该 MultiMesh 资源自定义 AABB。手动设置该项可以防止高昂的运行时 AABB 重新计算成本。

---

PackedColorArray custom_data_array 🔗

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

包含该网格的所有实例所使用的每个自定义数据值的数组，作为 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()

选择使用优先考虑速度还是优先考虑质量的插值方式。

如果使用的物理周期率较低（通常低于 20）或对象旋转率较高，则设为高质量的效果会更好。

注意：速度优先并不意味着质量较低。除了上述特殊情况之外，其质量应与选择高质量时类似。

---

PackedVector2Array transform_2d_array 🔗

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

包含该网格的所有实例所使用的每个 Transform2D 值的数组，作为 PackedVector2Array。每个变换被分为 3 个 Vector2 值，分别对应于变换的 x、y 和 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.

包含该网格的所有实例所使用的每个 Transform3D 值的数组，作为 PackedVector3Array。每个变换被分为 4 个 Vector3 值，分别对应于变换的 x、y、z 和 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) 🔗

使用物理插值时，该函数能够让你在当前物理周期中阻止对实例进行插值。

这样你就可以让实例瞬移，通常在初始放置子弹等实例时使用，防止出现图形问题。

---

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

设置 buffer 属性的替代做法，可以用于物理插值。该方法接受两个数组，可以一次性设置当前周期和上一周期的数据。渲染器每一帧都会自动插值。

适用于实例顺序每个物理周期中都经常会改变的场合，例如粒子系统。

如果实例的顺序是连贯的，插值时还是可以用更简单的设置 buffer 来代替。

---

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

设置一个特定实例的颜色，通过乘以该网格的现有顶点颜色来设置。这允许每个实例使用不同的颜色。

注意：各分量在 Forward+ 和 Mobile 渲染方法中都是使用 32 位存储的，而在 Compatibility 渲染方法中则为 16 位。

要使颜色生效，请确保该 MultiMesh 上的 use_colors 为 true，并且材质上的 BaseMaterial3D.vertex_color_use_as_albedo 为 true。如果打算设置绝对颜色而不是着色，请确保材质的反照率颜色被设置为纯白色 (Color(1, 1, 1))。

---

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

为特定的实例设置自定义数据。custom_data 是一个 Color 类型，仅为了包含 4 个浮点数。

注意：各个数字在 Forward+ 和 Mobile 渲染方法中都是使用 32 位存储的，而在 Compatibility 渲染方法中则为 16 位。

对于要使用的自定义数据，请确保 use_custom_data 为 true。

必须使用 INSTANCE_CUSTOM 在自定义着色器中，手动访问该自定义实例数据。

---

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

为指定实例设置 Transform3D。

---

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

为指定实例设置 Transform2D。