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

一種包含基於頂點陣列的幾何資源。

說明

Mesh is a type of Resource that contains vertex array-based geometry, divided in surfaces. Each surface contains a completely separate array and a material used to draw it. Design wise, a mesh with multiple surfaces is preferred to a single surface, because objects created in 3D editing software commonly contain multiple materials. The maximum number of surfaces per mesh is RenderingServer.MAX_MESH_SURFACES.

教學

屬性

Vector2i

lightmap_size_hint

Vector2i(0, 0)

方法

AABB	_get_aabb() virtual required const
int	_get_blend_shape_count() virtual required const
StringName	_get_blend_shape_name(index: int) virtual required const
int	_get_surface_count() virtual required const
void	_set_blend_shape_name(index: int, name: StringName) virtual required
int	_surface_get_array_index_len(index: int) virtual required const
int	_surface_get_array_len(index: int) virtual required const
Array	_surface_get_arrays(index: int) virtual required const
Array[Array]	_surface_get_blend_shape_arrays(index: int) virtual required const
int	_surface_get_format(index: int) virtual required const
Dictionary	_surface_get_lods(index: int) virtual required const
Material	_surface_get_material(index: int) virtual required const
int	_surface_get_primitive_type(index: int) virtual required const
void	_surface_set_material(index: int, material: Material) virtual required
ConvexPolygonShape3D	create_convex_shape(clean: bool = true, simplify: bool = false) const
Mesh	create_outline(margin: float) const
Resource	create_placeholder() const
ConcavePolygonShape3D	create_trimesh_shape() const
TriangleMesh	generate_triangle_mesh() const
AABB	get_aabb() const
PackedVector3Array	get_faces() const
int	get_surface_count() const
Array	surface_get_arrays(surf_idx: int) const
Array[Array]	surface_get_blend_shape_arrays(surf_idx: int) const
Material	surface_get_material(surf_idx: int) const
void	surface_set_material(surf_idx: int, material: Material)

列舉

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 of vertex normals.

Note: The array has to consist of normal vectors, otherwise they will be normalized by the engine, potentially causing visual discrepancies.

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

Contains custom color channel 0. PackedByteArray if (format >> Mesh.ARRAY_FORMAT_CUSTOM0_SHIFT) & Mesh.ARRAY_FORMAT_CUSTOM_MASK is ARRAY_CUSTOM_RGBA8_UNORM, ARRAY_CUSTOM_RGBA8_SNORM, ARRAY_CUSTOM_RG_HALF, or ARRAY_CUSTOM_RGBA_HALF. PackedFloat32Array otherwise.

ArrayType ARRAY_CUSTOM1 = 7

Contains custom color channel 1. PackedByteArray if (format >> Mesh.ARRAY_FORMAT_CUSTOM1_SHIFT) & Mesh.ARRAY_FORMAT_CUSTOM_MASK is ARRAY_CUSTOM_RGBA8_UNORM, ARRAY_CUSTOM_RGBA8_SNORM, ARRAY_CUSTOM_RG_HALF, or ARRAY_CUSTOM_RGBA_HALF. PackedFloat32Array otherwise.

ArrayType ARRAY_CUSTOM2 = 8

Contains custom color channel 2. PackedByteArray if (format >> Mesh.ARRAY_FORMAT_CUSTOM2_SHIFT) & Mesh.ARRAY_FORMAT_CUSTOM_MASK is ARRAY_CUSTOM_RGBA8_UNORM, ARRAY_CUSTOM_RGBA8_SNORM, ARRAY_CUSTOM_RG_HALF, or ARRAY_CUSTOM_RGBA_HALF. PackedFloat32Array otherwise.

ArrayType ARRAY_CUSTOM3 = 9

Contains custom color channel 3. PackedByteArray if (format >> Mesh.ARRAY_FORMAT_CUSTOM3_SHIFT) & Mesh.ARRAY_FORMAT_CUSTOM_MASK is ARRAY_CUSTOM_RGBA8_UNORM, ARRAY_CUSTOM_RGBA8_SNORM, ARRAY_CUSTOM_RG_HALF, or ARRAY_CUSTOM_RGBA_HALF. PackedFloat32Array otherwise.

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

Flag used to mark that the mesh data will use GL_DYNAMIC_DRAW on GLES. Unused on 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

Flag used to mark that a mesh is using compressed attributes (vertices, normals, tangents, UVs). When this form of compression is enabled, vertex positions will be packed into an RGBA16UNORM attribute and scaled in the vertex shader. The normal and tangent will be packed into an RG16UNORM representing an axis, and a 16-bit float stored in the A-channel of the vertex. UVs will use 16-bit normalized floats instead of full 32-bit signed floats. When using this compression mode you must use either vertices, normals, and tangents or only vertices. You cannot use normals without tangents. Importers will automatically enable this compression if they can.

enum BlendShapeMode: 🔗

BlendShapeMode BLEND_SHAPE_MODE_NORMALIZED = 0

混合形狀是被正規化了的。

BlendShapeMode BLEND_SHAPE_MODE_RELATIVE = 1

混合形狀是相對於基礎的權重。

屬性說明

Vector2i lightmap_size_hint = Vector2i(0, 0) 🔗

void set_lightmap_size_hint(value: Vector2i)
Vector2i get_lightmap_size_hint()

設定用於光照貼圖解析度的提示。

方法說明

AABB _get_aabb() virtual required const 🔗

虛方法，能夠為擴充自 Mesh 的自訂類覆蓋 AABB。

int _get_blend_shape_count() virtual required const 🔗

虛方法，能夠為擴充自 Mesh 的自訂類覆蓋混合形狀的數量。

StringName _get_blend_shape_name(index: int) virtual required const 🔗

虛方法，能夠為擴充自 Mesh 的自訂類覆蓋混合形狀名稱的獲取過程。

int _get_surface_count() virtual required const 🔗

虛方法，能夠為擴充自 Mesh 的自訂類覆蓋表面的數量。

void _set_blend_shape_name(index: int, name: StringName) virtual required 🔗

虛方法，能夠為擴充自 Mesh 的自訂類覆蓋混合形狀的名稱。

int _surface_get_array_index_len(index: int) virtual required const 🔗

虛方法，能夠為擴充自 Mesh 的自訂類覆蓋表面陣列索引的長度。

int _surface_get_array_len(index: int) virtual required const 🔗

虛方法，能夠為擴充自 Mesh 的自訂類覆蓋表面陣列的長度。

Array _surface_get_arrays(index: int) virtual required const 🔗

虛方法，能夠為擴充自 Mesh 的自訂類覆蓋表面陣列。

Array[Array] _surface_get_blend_shape_arrays(index: int) virtual required const 🔗

虛方法，能夠為擴充自 Mesh 的自訂類覆蓋混合形狀陣列。

int _surface_get_format(index: int) virtual required const 🔗

虛方法，能夠為擴充自 Mesh 的自訂類覆蓋表面格式。

Dictionary _surface_get_lods(index: int) virtual required const 🔗

虛方法，能夠為擴充自 Mesh 的自訂類覆蓋表面 LOD。

Material _surface_get_material(index: int) virtual required const 🔗

虛方法，能夠為擴充自 Mesh 的自訂類覆蓋表面材質。

int _surface_get_primitive_type(index: int) virtual required const 🔗

虛方法，能夠為擴充自 Mesh 的自訂類覆蓋表面圖元型別。

void _surface_set_material(index: int, material: Material) virtual required 🔗

虛方法，能夠為擴充自 Mesh 的自訂類覆蓋索引為 index 的材質 material 的設定。

ConvexPolygonShape3D create_convex_shape(clean: bool = true, simplify: bool = false) const 🔗

從網格計算 ConvexPolygonShape3D。

如果 clean 為 true（預設值），則自動移除重複頂點和內部頂點。如果不需要如此的化話，可以將其設定為 false 以加快處理速度。

如果 simplify 為 true，則可以進一步簡化幾何體以減少頂點數。預設情況下是禁用的。

Mesh create_outline(margin: float) 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 🔗

返回表面覆蓋材質的數量。相當於 get_surface_count()。

Array surface_get_arrays(surf_idx: int) const 🔗

返回構成請求表面的頂點、法線、UV 等陣列。（見 ArrayMesh.add_surface_from_arrays()）。

Array[Array] surface_get_blend_shape_arrays(surf_idx: int) const 🔗

返回請求表面的混合形狀陣列。

Material surface_get_material(surf_idx: int) const 🔗

傳回給定表面中的Material。表面是使用此材質算繪的。

注意： 這將傳回 Mesh 資源中的材質，而不是與 MeshInstance3D 的表面材質覆蓋屬性關聯的 Material。若要取得與 MeshInstance3D 的表面材質覆蓋屬性相關的 Material，請改用 MeshInstance3D.get_surface_override_material()。

void surface_set_material(surf_idx: int, material: Material) 🔗

設定為給定表面Material。表面將使用此材質算繪。

注意： 這會分配 Mesh 資源中的材質，而不是與 MeshInstance3D 的表面材質覆蓋屬性關聯的 Material。若要設定與 MeshInstance3D 的表面材質覆蓋屬性相關的 Material，請使用 MeshInstance3D.set_surface_override_material()。