Procedural geometry

    Geometry is a fancy way of saying shape. In computer graphics, geometry is typically represented by an array of positions called “vertices”. In Godot, geometry is represented by Meshes.

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

    Meshes and ArrayMeshes are resources that are drawn using a MeshInstance node. Resources like Meshes and ArrayMeshes cannot be added to the scene directly. A MeshInstance represents one instance of a mesh in your scene. You can reuse a single mesh in multiple MeshInstances 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 MultiMeshInstance. MultiMeshInstances draw meshes thousands of times very cheaply by taking advantage of hardware instancing. The drawback with using a MultiMeshInstance 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.

    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 , but with ArrayMeshes, the user can construct a Mesh manually by passing in an array containing the surface information.

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

    Surface array

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

    Godot provides different ways of accessing and working with geometry. More information on each will be provided in the following tutorials.

    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.

    For more information about the ArrayMesh, please see the .

    MeshDataTool

    The MeshDataTool is a resource that converts Mesh data into arrays of vertices, faces, and edges that can be modified at runtime.

    For more information about the MeshDataTool, please see the .

    The SurfaceTool allows the creation of Meshes using an OpenGL 1.x immediate mode style interface.

    For more information about the SurfaceTool, please see the .

    ImmediateGeometry

    ImmediateGeometry is useful for prototyping because of its straightforward API, but it is slow because the geometry is rebuilt every frame. 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 ImmediateGeometry, please see the .

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

    Both SurfaceTool and ArrayMesh are excellent for generating static geometry (meshes) that don’t change over time.

    Using an ArrayMesh is slightly faster than using a SurfaceTool, but the API is a little more challenging. Additionally, SurfaceTool has a few quality of life methods such as and .

    ImmediateGeometry regenerates the mesh every frame, so it is much slower than ArrayMesh or SurfaceTool. However, if you need the geometry to change every frame anyway, it provides a much easier interface that may even be a little 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.