Procedural geometry generation

Users often ask how to generate geometry from code. This is not very complicated, but it’s not obvious. Godot provides a few classes entirely dedicated to make it this easy. Still, the best tool for the job depends entirely on the use case.

SurfaceTool

This is the most common helper. SurfaceTool is a class you can instantiate to generate Meshes, specifically Mesh Surfaces.

It has a similar API to OpenGL 1.x, and it’s meant for static content. This means, the mesh is generated once and then used.

Here is a simple example of how to use it to add a single triangle.

GDScript

  1. var st = SurfaceTool.new()
  3. st.begin(Mesh.PRIMITIVE_TRIANGLES)
  5. # Prepare attributes for add_vertex.
  6. st.add_normal(Vector3(0, 0, 1))
  7. st.add_uv(Vector2(0, 0))
  8. # Call last for each vertex, adds the above attributes.
  9. st.add_vertex(Vector3(-1, -1, 0))
  11. st.add_normal(Vector3(0, 0, 1))
  12. st.add_uv(Vector2(0, 1))
  13. st.add_vertex(Vector3(-1, 1, 0))
  15. st.add_normal(Vector3(0, 0, 1))
  16. st.add_uv(Vector2(1, 1))
  17. st.add_vertex(Vector3(1, 1, 0))
  19. # Create indices, indices are optional.
  20. st.index()
  22. # Commit to a mesh.
  23. var mesh = st.commit()

Just explore the APIs and the possibilities.

ImmediateGeometry

Unlike SurfaceTool, ImmediateGeometry is an actual node. It’s similar in the “OpenGL 1.x” style API, but it’s actually designed to create content on the fly and modify it every frame efficiently.

Generating complex geometry (several thousand vertices) with this node is inefficient, even if it’s done only once. Instead, ImmediateGeometry is designed to generate simple geometry that changes every frame.

It’s used similar to SurfaceTool.

GDScript

  1. extends ImmediateGeometry
  3. void _process(delta):
  4.     # Clean up before drawing.
  5.     clear()
  7.     # Begin draw.
  8.     begin(Mesh.PRIMITIVE_TRIANGLES)
  10.     # Prepare attributes for add_vertex.
  11.     set_normal( Vector3(0, 0, 1))
  12.     set_uv(Vector2(0, 0))
  13.     # Call last for each vertex, adds the above attributes.
  14.     add_vertex(Vector3(-1, -1, 0))
  16.     set_normal(Vector3(0, 0, 1))
  17.     set_uv(Vector2(0, 1))
  18.     add_vertex(Vector3(-1, 1, 0))
  20.     set_normal(Vector3(0, 0, 1))
  21.     set_uv(Vector2(1, 1))
  22.     add_vertex(Vector3(1, 1, 0))
  24.     # End drawing.
  25.     end()

Arrays

Lastly, the final way to do this is to create arrays themselves. This is the most efficient way to create static geometry, and is only recommended when SurfaceTool is not fast enough.

Similar code as before, but draw a square using indices:

GDScript

  1. var arrays = []
  2. arrays.resize(Mesh.ARRAY_MAX)
  4. var normal_array = []
  5. var uv_array = []
  6. var vertex_array = []
  7. var index_array = []
  9. normal_array.resize(4)
  10. uv_array.resize(4)
  11. vertex_array.resize(4)
  12. index_array.resize(6)
  14. normal_array[0] = Vector3(0, 0, 1)
  15. uv_array[0] = Vector2(0, 0)
  16. vertex_array[0] = Vector3(-1, -1, 0)
  18. normal_array[1] = Vector3(0, 0, 1)
  19. uv_array[1] = Vector2(0,1)
  20. vertex_array[1] = Vector3(-1, 1, 0)
  22. normal_array[2] = Vector3(0, 0, 1)
  23. uv_array[2] = Vector2(1, 1)
  24. vertex_array[2] = Vector3(1, 1, 0)
  26. normal_array[3] = Vector3(0, 0, 1)
  27. uv_array[3] = Vector2(1, 0)
  28. vertex_array[3] = Vector3(1, -1, 0)
  30. # Indices are optional in Godot, but if they exist they are used.
  31. index_array[0] = 0
  32. index_array[1] = 1
  33. index_array[2] = 2
  35. index_array[3] = 2
  36. index_array[4] = 3
  37. index_array[5] = 0
  39. arrays[Mesh.ARRAY_VERTEX] = vertex_array
  40. arrays[Mesh.ARRAY_NORMAL] = normal_array
  41. arrays[Mesh.ARRAY_TEX_UV] = uv_array
  42. arrays[Mesh.ARRAY_INDEX] = index_array
  44. var mesh = ArrayMesh.new()
  46. mesh.add_surface_from_arrays(Mesh.PRIMITIVE_TRIANGLES,arrays)