The SurfaceTool provides a useful interface for constructing geometry. The interface is similar to the ImmediateGeometry 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() などの便利なヘルパー関数も提供します。


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

When finished generating your geometry with the SurfaceTool call commit() to finish generating the mesh. If an ArrayMesh is passed to commit() then it appends a new surface to the end of the ArrayMesh. While if nothing is passed in, commit() returns an ArrayMesh.

# Or:
var mesh = st.commit()


var st =


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

st.add_normal(Vector3(0, 0, 1))
st.add_uv(Vector2(0, 1))
st.add_vertex(Vector3(-1, 1, 0))

st.add_normal(Vector3(0, 0, 1))
st.add_uv(Vector2(1, 1))
st.add_vertex(Vector3(1, 1, 0))

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

オプションで add_index() を呼び出して頂点をインデックス配列に追加するか、頂点配列を縮小して重複する頂点を削除する index() を呼び出すことで、インデックス配列を追加できます。

# Creates a quad from four corner vertices.
# Add_index does not need to be called before add_vertex.


# Alternatively:

同様に、インデックス配列があるが、各頂点を一意にしたい場合(たとえば、頂点ごとではなく面ごとに一意の法線または色を使用するため)、deindex() を呼び出すことができます。


If you don't add custom normals yourself, you can add them using generate_normals(), which should be called after generating geometry and before committing the mesh using commit() or commit_to_arrays(). Calling generate_normals(true) will flip the resulting normals. As a side note, generate_normals() only works if the primitive type is set to 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 with generate_tangents(). This method requires that each vertex have UVs and normals set already.


デフォルトでは、法線を生成するとき、それらは面ごとに計算されます。滑らかな頂点法線が必要な場合、頂点を追加するときに add_smooth_group() を呼び出します。ジオメトリの構築中に add_smooth_group() を呼び出す必要があります。例えば、`` add_vertex()`` (インデックス化されていない場合)または add_index() (インデックス化されている場合)の呼び出しの前にです。