Up to date

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

Géométrie procédurale

There are many ways to procedurally generate geometry in Godot. In this tutorial series, we will explore a few of them. Each technique has its own benefits and drawbacks, so it is best to understand each one and how it can be useful in a given situation.

Note

All the procedural geometry generation methods described here run on the CPU. Godot doesn't support generating geometry on the GPU yet.

Qu'est-ce que la géométrie ?

La géométrie est une façon élégante de dire la forme. En infographie, la géométrie est généralement représentée par un tableau de positions appelées "sommets(vertices)". Dans Godot, la géométrie est représentée par des mailles(Meshes).

Qu'est-ce qu'un Mesh ?

Many things in Godot have mesh in their name: the Mesh, the ArrayMesh, the ImmediateMesh, the MeshInstance3D, the MultiMesh, and the MultiMeshInstance3D. While they are all related, they have slightly different uses.

Meshes and ArrayMeshes are resources that are drawn using a MeshInstance3D node. Resources like Meshes and ArrayMeshes cannot be added to the scene directly. A MeshInstance3D represents one instance of a mesh in your scene. You can reuse a single mesh in multiple MeshInstance3Ds to draw it in different parts of your scene with different materials or transformations (scale, rotation, position etc.).

If you are going to draw the same object many times, it can be helpful to use a MultiMesh with a MultiMeshInstance3D. MultiMeshInstance3Ds draw meshes thousands of times very cheaply by taking advantage of hardware instancing. The drawback with using a MultiMeshInstance3D is that each of your mesh's surfaces are limited to one material for all instances. It uses an instance array to store different colors and transformations for each instance, but all the instances of each surface use the same material.

Qu'est-ce qu'un Mesh est

A Mesh is composed of one or more surfaces. A surface is an array composed of multiple sub-arrays containing vertices, normals, UVs, etc. Normally the process of constructing surfaces and meshes is hidden from the user in the RenderingServer, but with ArrayMeshes, the user can construct a Mesh manually by passing in an array containing the surface information.

Surfaces

Each surface has its own material. Alternatively, you can override the material for all surfaces in the Mesh when you use a MeshInstance3D using the material_override property.

Tableau de surface

The surface array is an array of length ArrayMesh.ARRAY_MAX. Each position in the array is filled with a sub-array containing per-vertex information. For example, the array located at ArrayMesh.ARRAY_NORMAL is a PackedVector3Array of vertex normals. See Mesh.ArrayType for more information.

Le tableau de surface peut être indexé ou non indexé. Créer un tableau non indexé est aussi simple que de ne pas assigner un tableau à l'index ArrayMesh.ARRAY_INDEX. Un tableau non indexé stocke des informations uniques sur les sommets de chaque triangle, ce qui signifie que lorsque deux triangles partagent un sommet, celui-ci est dupliqué dans le tableau. Un tableau de surfaces indexé ne stocke que les informations sur les sommets pour chaque sommet unique, puis stocke également un tableau d'index qui indique comment construire les triangles à partir du tableau de sommets. En général, l'utilisation d'un tableau indexé est plus rapide, mais cela signifie que vous devez partager les données des sommets entre les triangles, ce qui n'est pas toujours souhaitable (par exemple, lorsque vous voulez des normales par face).

Outils

Godot propose différentes façons d'accéder à la géométrie et de travailler avec elle. Les tutoriels suivants vous fourniront de plus amples informations sur chacune d'entre elles.

ArrayMesh

The ArrayMesh resource extends Mesh to add a few different quality of life functions and, most importantly, the ability to construct a Mesh surface through scripting.

Pour plus d'informations sur ArrayMesh, consultez le tutoriel ArrayMesh tutorial.

MeshDataTool

Le MeshDataTool est une ressource qui convertit les données de Mesh en tableaux de sommets, de faces et de bords qui peuvent être modifiés à l'exécution.

Pour plus d'informations sur le MeshDataTool, veuillez consulter le tutoriel MeshDataTool tutorial.

SurfaceTool

Le SurfaceTool permet la création de Meshes en utilisant une interface du type mode immédiat OpenGL 1.x.

Pour plus d'informations sur SurfaceTool, consultez le tutoriel SurfaceTool tutorial.

ImmediateMesh

ImmediateMesh is a mesh that uses an immediate mode style interface (like SurfaceTool) to draw objects. The difference between ImmediateMesh and the SurfaceTool is that ImmediateMesh is drawn directly with code dynamically, while the SurfaceTool is used to generated a Mesh that you can do whatever you want with.

ImmediateMesh is useful for prototyping because of its straightforward API, but it is slow because the geometry is rebuilt each time you make a change. It is most useful for adding simple geometry for visual debugging (e.g. by drawing lines to visualize physics raycasts etc.).

For more information about ImmediateMesh, please see the ImmediateMesh tutorial.

Lequel dois-je utiliser ?

Which approach you use depends on what you are trying to do and what kind of procedure you are comfortable with.

SurfaceTool et ArrayMesh sont tous deux excellents pour générer une géométrie statique (maillages) qui ne change pas avec le temps.

L'utilisation d'ArrayMesh est légèrement plus rapide que celle de SurfaceTool, mais l'API est un peu plus difficile d'utilisation. De plus, SurfaceTool possède quelques méthodes de qualité de vie comme generate_normals() et index().

ImmediateMesh is more limited than both ArrayMesh and SurfaceTool. However, if you need the geometry to change every frame anyway, it provides a much easier interface that can be slightly faster than generating an ArrayMesh every frame.

The MeshDataTool is not fast, but it gives you access to all kinds of properties of the mesh that you don't get with the others (edges, faces, etc.). It is incredibly useful when you need that sort of data to transform the mesh, but it is not a good idea to use it if that extra information is not needed. The MeshDataTool is best used if you are going to be using an algorithm that requires access to the face or edge array.