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

使用 SurfaceTool

The SurfaceTool provides a useful interface for constructing geometry. The interface is similar to the ImmediateMesh node. You set each per-vertex attribute (e.g. normal, uv, color) and then when you add a vertex it captures the attributes.

SurfaceTool 还提供了一些有用的辅助函数，如 index() 和 generate_normals()。

属性是在添加每个顶点之前添加的：

GDScript

st.set_normal() # Overwritten by normal below.
st.set_normal() # Added to next vertex.
st.set_color() # Added to next vertex.
st.add_vertex() # Captures normal and color above.
st.set_normal() # Normal never added to a vertex.

当使用 SurfaceTool 完成生成几何体后，调用 commit() 完成生成网格。如果将一个 ArrayMesh 传递给了 commit()，那么它就会在这个 ArrayMesh 的末尾附加一个新的表面。而如果没有传递任何信息，commit() 则返回一个 ArrayMesh。

GDScript

st.commit(mesh)
# Or:
var mesh = st.commit()

代码创建一个有索引的三角形

GDScript

var st = SurfaceTool.new()

st.begin(Mesh.PRIMITIVE_TRIANGLES)

# Prepare attributes for add_vertex.
st.set_normal(Vector3(0, 0, 1))
st.set_uv(Vector2(0, 0))
# Call last for each vertex, adds the above attributes.
st.add_vertex(Vector3(-1, -1, 0))

st.set_normal(Vector3(0, 0, 1))
st.set_uv(Vector2(0, 1))
st.add_vertex(Vector3(-1, 1, 0))

st.set_normal(Vector3(0, 0, 1))
st.set_uv(Vector2(1, 1))
st.add_vertex(Vector3(1, 1, 0))

# Commit to a mesh.
var mesh = st.commit()

你可以选择添加一个索引数组, 可以通过调用 add_index() 将顶点添加到索引数组中, 也可以通过调用 index() 将顶点数组缩小以删除重复的顶点.

GDScript

# Creates a quad from four corner vertices.
# Add_index does not need to be called before add_vertex.
st.add_index(0)
st.add_index(1)
st.add_index(2)

st.add_index(1)
st.add_index(3)
st.add_index(2)

# Alternatively:
st.index()

同样, 如果你有一个索引数组, 但希望每个顶点都是唯一的(例如, 因为想在每个面而不是每个顶点使用唯一的法线或颜色), 可以调用 deindex() .

GDScript

st.deindex()

如果你不想自行添加自定义法线，那么可以使用 generate_normals() 来添加，调用时机应该是在生成几何体之后、使用 commit() 或 commit_to_arrays() 提交网格之前。调用 generate_normals(true) 会将最终的法线翻转。另外请注意，generate_normals() 只有在图元类型为 Mesh.PRIMITIVE_TRIANGLES 时有效。

You may notice that normal mapping or other material properties look broken on the generated mesh. This is because normal mapping requires the mesh to feature tangents, which are separate from normals. You can either add custom tangents manually, or generate them automatically with generate_tangents(). This method requires that each vertex have UVs and normals set already.

GDScript

st.generate_normals()
st.generate_tangents()

默认情况下, 当生成法线时, 它们将以每个面为基础进行计算. 如果想要平滑的顶点法线, 在添加顶点时, 调用 add_smooth_group() . add_smooth_group() 需要在建立几何体时调用, 例如在调用 add_vertex() (如果没有索引)或 add_index() (如果有索引)之前.