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...
Mesh¶
继承： Resource < RefCounted < Object
派生： ArrayMesh, ImmediateMesh, PlaceholderMesh, PrimitiveMesh
一种包含基于顶点数组的几何资源。
描述¶
网格是一种包含了基于顶点数组的几何资源。网格被分为各种平面，每一个平面包含了一个完整的、单独的顶点数组和材质用来绘制它。通过明智的设计，一个由多个面组成的网格胜过单个面的，这是因为在3D编辑软件中，一个物体通常包含多种材质。
教程¶
属性¶
|
方法¶
枚举¶
enum PrimitiveType:
PrimitiveType PRIMITIVE_POINTS = 0
将数组渲染为点（一个顶点对应一个点）。
PrimitiveType PRIMITIVE_LINES = 1
将数组渲染为线（每两个顶点创建一条连线）。
PrimitiveType PRIMITIVE_LINE_STRIP = 2
将数组渲染为线条。
PrimitiveType PRIMITIVE_TRIANGLES = 3
将数组渲染为三角形（每三个顶点创建一个三角形）。
PrimitiveType PRIMITIVE_TRIANGLE_STRIP = 4
将数组渲染为三角形条。
enum ArrayType:
ArrayType ARRAY_VERTEX = 0
顶点位置的 PackedVector3Array、PackedVector2Array 或 Array。
ArrayType ARRAY_NORMAL = 1
顶点法线的 PackedVector3Array。
ArrayType ARRAY_TANGENT = 2
顶点切线的 PackedFloat32Array。4 个浮点数为一组表示一个元素，前 3 个浮点数确定切线，最后一个是为 -1 或 1 的副法线方向。
ArrayType ARRAY_COLOR = 3
顶点颜色的 PackedColorArray。
ArrayType ARRAY_TEX_UV = 4
UV 坐标的 PackedVector2Array。
ArrayType ARRAY_TEX_UV2 = 5
第二 UV 坐标的 PackedVector2Array。
ArrayType ARRAY_CUSTOM0 = 6
包含自定义颜色通道 0。如果 (format >> Mesh.ARRAY_FORMAT_CUSTOM0_SHIFT) & Mesh.ARRAY_FORMAT_CUSTOM_MASK 为 ARRAY_CUSTOM_RGBA8_UNORM、ARRAY_CUSTOM_RGBA8_UNORM、ARRAY_CUSTOM_RG_HALF 或 ARRAY_CUSTOM_RGBA_HALF，则为 PackedByteArray。否则为 PackedFloat32Array。
ArrayType ARRAY_CUSTOM1 = 7
包含自定义颜色通道 1。如果 (format >> Mesh.ARRAY_FORMAT_CUSTOM1_SHIFT) & Mesh.ARRAY_FORMAT_CUSTOM_MASK 为 ARRAY_CUSTOM_RGBA8_UNORM、ARRAY_CUSTOM_RGBA8_UNORM、ARRAY_CUSTOM_RG_HALF 或 ARRAY_CUSTOM_RGBA_HALF，则为 PackedByteArray。否则为 PackedFloat32Array。
ArrayType ARRAY_CUSTOM2 = 8
包含自定义颜色通道 2。如果 (format >> Mesh.ARRAY_FORMAT_CUSTOM2_SHIFT) & Mesh.ARRAY_FORMAT_CUSTOM_MASK 为 ARRAY_CUSTOM_RGBA8_UNORM、ARRAY_CUSTOM_RGBA8_UNORM、ARRAY_CUSTOM_RG_HALF 或 ARRAY_CUSTOM_RGBA_HALF，则为 PackedByteArray。否则为 PackedFloat32Array。
ArrayType ARRAY_CUSTOM3 = 9
包含自定义颜色通道 3。如果 (format >> Mesh.ARRAY_FORMAT_CUSTOM3_SHIFT) & Mesh.ARRAY_FORMAT_CUSTOM_MASK 为 ARRAY_CUSTOM_RGBA8_UNORM、ARRAY_CUSTOM_RGBA8_UNORM、ARRAY_CUSTOM_RG_HALF 或 ARRAY_CUSTOM_RGBA_HALF，则为 PackedByteArray。否则为 PackedFloat32Array。
ArrayType ARRAY_BONES = 10
骨骼索引的 PackedFloat32Array 或 PackedInt32Array。每个顶点包含 4 个还是 8 个数字取决于是否存在 ARRAY_FLAG_USE_8_BONE_WEIGHTS 标志。
ArrayType ARRAY_WEIGHTS = 11
骨骼权重的 PackedFloat32Array 或 PackedInt32Array，取值范围为 0.0 到 1.0（闭区间）。每个顶点包含 4 个还是 8 个数字取决于是否存在 ARRAY_FLAG_USE_8_BONE_WEIGHTS 标志。
ArrayType ARRAY_INDEX = 12
整数的 PackedInt32Array，用作引用顶点、颜色、法线、切线、和纹理的索引。所有这些数组必须具有与顶点数组相同数量的元素。任何索引都不能超过顶点数组的大小。当该索引数组存在时，它会将函数置于“索引模式”，其中索引选择第 i 个顶点、法线、切线、颜色、UV 等。这意味着，如果想要沿着一条边有不同的法线或颜色，则必须复制这些顶点。
对于三角形，索引数组被解释为三元组，指代每个三角形的顶点。对于线条，索引数组成对表示每条线的开始和结束。
ArrayType ARRAY_MAX = 13
代表 ArrayType 枚举的大小。
enum ArrayCustomFormat:
ArrayCustomFormat ARRAY_CUSTOM_RGBA8_UNORM = 0
表示该自定义通道包含的是无符号归一化字节颜色，范围为 0 到 1，编码为 PackedByteArray。
ArrayCustomFormat ARRAY_CUSTOM_RGBA8_SNORM = 1
表示该自定义通道包含的是有符号归一化字节颜色，范围为 -1 到 1，编码为 PackedByteArray。
ArrayCustomFormat ARRAY_CUSTOM_RG_HALF = 2
表示该自定义通道包含的是半精度浮点数颜色，编码为 PackedByteArray。仅使用红、绿通道。
ArrayCustomFormat ARRAY_CUSTOM_RGBA_HALF = 3
表示该自定义通道包含的是半精度浮点数颜色，编码为 PackedByteArray。
ArrayCustomFormat ARRAY_CUSTOM_R_FLOAT = 4
表示该自定义通道包含的是全精度浮点数颜色，使用 PackedFloat32Array。仅使用红色通道。
ArrayCustomFormat ARRAY_CUSTOM_RG_FLOAT = 5
表示该自定义通道包含的是全精度浮点数颜色，使用 PackedFloat32Array。仅使用红、绿通道。
ArrayCustomFormat ARRAY_CUSTOM_RGB_FLOAT = 6
表示该自定义通道包含的是全精度浮点数颜色，使用 PackedFloat32Array。仅使用红、绿、蓝通道。
ArrayCustomFormat ARRAY_CUSTOM_RGBA_FLOAT = 7
表示该自定义通道包含的是全精度浮点数颜色，使用 PackedFloat32Array。
ArrayCustomFormat ARRAY_CUSTOM_MAX = 8
代表 ArrayCustomFormat 枚举的大小。
flags ArrayFormat:
ArrayFormat ARRAY_FORMAT_VERTEX = 1
网格数组包含顶点。所有网格都需要有顶点数组，所以这应该始终存在。
ArrayFormat ARRAY_FORMAT_NORMAL = 2
网格数组包含法线。
ArrayFormat ARRAY_FORMAT_TANGENT = 4
网格数组包含切线。
ArrayFormat ARRAY_FORMAT_COLOR = 8
网格数组包含颜色。
ArrayFormat ARRAY_FORMAT_TEX_UV = 16
网格数组包含 UV。
ArrayFormat ARRAY_FORMAT_TEX_UV2 = 32
网格数组包含第二套 UV。
ArrayFormat ARRAY_FORMAT_CUSTOM0 = 64
网格数组包含自定义通道索引 0。
ArrayFormat ARRAY_FORMAT_CUSTOM1 = 128
网格数组包含自定义通道索引 1。
ArrayFormat ARRAY_FORMAT_CUSTOM2 = 256
网格数组包含自定义通道索引 2。
ArrayFormat ARRAY_FORMAT_CUSTOM3 = 512
网格数组包含自定义通道索引 3。
ArrayFormat ARRAY_FORMAT_BONES = 1024
网格数组包含骨骼。
ArrayFormat ARRAY_FORMAT_WEIGHTS = 2048
网格数组包含骨骼权重。
ArrayFormat ARRAY_FORMAT_INDEX = 4096
网格数组使用索引。
ArrayFormat ARRAY_FORMAT_BLEND_SHAPE_MASK = 7
混合形状中允许使用的网格通道的掩码。
ArrayFormat ARRAY_FORMAT_CUSTOM_BASE = 13
第一个自定义通道的移位量。
ArrayFormat ARRAY_FORMAT_CUSTOM_BITS = 3
每个自定义通道的格式位数。请参阅 ArrayCustomFormat。
ArrayFormat ARRAY_FORMAT_CUSTOM0_SHIFT = 13
自定义通道索引 0 需要对 ArrayCustomFormat 进行的按位移动量。
ArrayFormat ARRAY_FORMAT_CUSTOM1_SHIFT = 16
自定义通道索引 1 需要对 ArrayCustomFormat 进行的按位移动量。
ArrayFormat ARRAY_FORMAT_CUSTOM2_SHIFT = 19
自定义通道索引 2 需要对 ArrayCustomFormat 进行的按位移动量。
ArrayFormat ARRAY_FORMAT_CUSTOM3_SHIFT = 22
自定义通道索引 3 需要对 ArrayCustomFormat 进行的按位移动量。
ArrayFormat ARRAY_FORMAT_CUSTOM_MASK = 7
每个自定义通道的自定义格式位掩码。必须按 SHIFT 常量之一进行移位。请参阅 ArrayCustomFormat。
ArrayFormat ARRAY_COMPRESS_FLAGS_BASE = 25
第一个压缩标志的移位。压缩标志应该被传递给 ArrayMesh.add_surface_from_arrays 和 SurfaceTool.commit。
ArrayFormat ARRAY_FLAG_USE_2D_VERTICES = 33554432
用于标记包含 2D 顶点的数组的标志。
ArrayFormat ARRAY_FLAG_USE_DYNAMIC_UPDATE = 67108864
网格数据将在 GLES 上使用 GL_DYNAMIC_DRAW 的标记索引。在 Vulkan 上未被使用。
ArrayFormat ARRAY_FLAG_USE_8_BONE_WEIGHTS = 134217728
用于标记网格每个顶点最多包含 8 个骨骼影响的标志。该标志表示 ARRAY_BONES 和 ARRAY_WEIGHTS 元素将具有双倍长度。
ArrayFormat ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY = 268435456
用于标记网格有意不包含顶点数组的标志。
ArrayFormat ARRAY_FLAG_COMPRESS_ATTRIBUTES = 536870912
用于标记网格正在使用的压缩的属性（顶点、法线、切线、UV）的标志。启用这种形式的压缩后，顶点位置将被打包到 RGBA16UNORM 属性中，并在顶点着色器中进行缩放。法线和切线将被打包到表示一个轴的 RG16UNORM 中，并在顶点的 A 通道中存储一个 16 位浮点数。UV 将使用 16 位标准化浮点数而不是完整的 32 位有符号浮点数。使用该压缩模式时，必须使用顶点、法线、和切线或仅使用顶点。你无法使用没有切线的法线。如果可以的话，导入器将自动启用这种压缩。
enum BlendShapeMode:
BlendShapeMode BLEND_SHAPE_MODE_NORMALIZED = 0
混合形状是被归一化了的。
BlendShapeMode BLEND_SHAPE_MODE_RELATIVE = 1
混合形状是相对于基础的权重。
属性说明¶
Vector2i lightmap_size_hint = Vector2i(0, 0)
设置用于光照贴图分辨率的提示。
方法说明¶
AABB _get_aabb ( ) virtual const
虚方法，能够为扩展自 Mesh 的自定义类覆盖 AABB。
int _get_blend_shape_count ( ) virtual const
虚方法，能够为扩展自 Mesh 的自定义类覆盖混合形状的数量。
StringName _get_blend_shape_name ( int index ) virtual const
虚方法，能够为扩展自 Mesh 的自定义类覆盖混合形状名称的获取过程。
int _get_surface_count ( ) virtual const
虚方法，能够为扩展自 Mesh 的自定义类覆盖表面的数量。
void _set_blend_shape_name ( int index, StringName name ) virtual
虚方法，能够为扩展自 Mesh 的自定义类覆盖混合形状的名称。
int _surface_get_array_index_len ( int index ) virtual const
虚方法，能够为扩展自 Mesh 的自定义类覆盖表面数组索引的长度。
int _surface_get_array_len ( int index ) virtual const
虚方法，能够为扩展自 Mesh 的自定义类覆盖表面数组的长度。
Array _surface_get_arrays ( int index ) virtual const
虚方法，能够为扩展自 Mesh 的自定义类覆盖表面数组。
Array[] _surface_get_blend_shape_arrays ( int index ) virtual const
虚方法，能够为扩展自 Mesh 的自定义类覆盖混合形状数组。
int _surface_get_format ( int index ) virtual const
虚方法，能够为扩展自 Mesh 的自定义类覆盖表面格式。
Dictionary _surface_get_lods ( int index ) virtual const
虚方法，能够为扩展自 Mesh 的自定义类覆盖表面 LOD。
Material _surface_get_material ( int index ) virtual const
虚方法，能够为扩展自 Mesh 的自定义类覆盖表面材质。
int _surface_get_primitive_type ( int index ) virtual const
虚方法，能够为扩展自 Mesh 的自定义类覆盖表面图元类型。
void _surface_set_material ( int index, Material material ) virtual
虚方法，能够为扩展自 Mesh 的自定义类覆盖索引为 index 的材质 material 的设置。
ConvexPolygonShape3D create_convex_shape ( bool clean=true, bool simplify=false ) const
从网格计算 ConvexPolygonShape3D。
如果 clean 为 true（默认值），则自动移除重复顶点和内部顶点。如果不需要如此的化话，可以将其设置为 false 以加快处理速度。
如果 simplify 为 true，则可以进一步简化几何体以减少顶点数。默认情况下是禁用的。
Mesh create_outline ( float margin ) const
以一定的偏移量（边距)，计算出该网格的外轮廓。
注意：这个方法实际上反序返回顶点（例如输入顺时针，返回逆时针）。
Resource create_placeholder ( ) const
创建该资源的占位符版本（PlaceholderMesh）。
ConcavePolygonShape3D create_trimesh_shape ( ) const
从该网格计算出 ConcavePolygonShape3D。
TriangleMesh generate_triangle_mesh ( ) const
从网格生成 TriangleMesh。仅考虑使用以下图元类型的表面：PRIMITIVE_TRIANGLES、PRIMITIVE_TRIANGLE_STRIP。
AABB get_aabb ( ) const
返回局部空间中包围这个网格的最小 AABB。不受 custom_aabb 的影响。
注意：只针对 ArrayMesh 和 PrimitiveMesh 进行了实现。
PackedVector3Array get_faces ( ) const
返回网格中所有构成面的顶点。每三个顶点代表一个三角形。
int get_surface_count ( ) const
返回 Mesh 中存放的表面的数量。相当于 MeshInstance3D.get_surface_override_material_count。
Array surface_get_arrays ( int surf_idx ) const
返回构成请求表面的顶点、法线、UV 等数组。（见 ArrayMesh.add_surface_from_arrays）。
Array[] surface_get_blend_shape_arrays ( int surf_idx ) const
返回请求表面的混合形状数组。
Material surface_get_material ( int surf_idx ) const
返回给定表面中的 Material。表面是使用该材质渲染的。
注意：这将返回 Mesh 资源中的材质，而不是与 MeshInstance3D 的表面材质覆盖属性关联的 Material。要获取与 MeshInstance3D 的表面材质覆盖属性关联的 Material，请改用 MeshInstance3D.get_surface_override_material。
void surface_set_material ( int surf_idx, Material material )
为给定表面设置 Material。表面将使用该材质进行渲染。
注意：这会分配 Mesh 资源中的材质，而不是与 MeshInstance3D 的表面材质覆盖属性关联的 Material。要设置与 MeshInstance3D 的表面材质覆盖属性关联的 Material，请改用 MeshInstance3D.set_surface_override_material。