Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Utilisation de 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 fournit également quelques fonctions d'aide utiles comme index() et generate_normals().

Les attributs sont ajoutés avant l'ajout de chaque sommet :

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.

Lorsque vous avez fini de générer votre géométrie avec SurfaceTool, appelez commit() pour finir de générer le maillage. Si un ArrayMesh est passé à commit() alors il ajoute une nouvelle surface à l'extrémité de l'ArrayMesh. Alors que si rien n'est passé, commit() renvoie un ArrayMesh.

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

Le code crée un triangle avec des indices

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

Vous pouvez éventuellement ajouter un tableau d'index, soit en appelant add_index() et en ajoutant des sommets au tableau d'index, soit en appelant index() qui réduit le tableau de sommets pour supprimer les sommets en double.

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

De même, si vous avez un tableau d'index, mais que vous voulez que chaque sommet soit unique (par exemple parce que vous voulez utiliser des normales ou des couleurs uniques par face au lieu de par vertex), vous pouvez appeler deindex().

st.deindex()

Si vous n'ajoutez pas les normales personnalisées vous-même, vous pouvez les ajouter en utilisant generate_normals(), qui doit être appelé après avoir généré la géométrie et avant de valider le maillage en utilisant commit() ou commit_to_arrays(). L'appel à generate_normals(true) inversera les normales résultantes. En remarque, generate_normals() ne fonctionne que si le type de primitive est défini sur 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.

st.generate_normals()
st.generate_tangents()

Par défaut, lors de la génération des normales, elles seront calculées par face de base. Si vous voulez des normales de vertex lisses, lors de l'ajout de vertex, appelez add_smooth_group(). add_smooth_group() doit être appelé pendant la construction de la géométrie, par exemple avant l'appel à add_vertex() (si non indexé) ou add_index() (si indexé).