ImmediateMesh in Godot – Complete Guide

Welcome to this expansive tutorial where we dive into the realm of ImmediateMesh in Godot 4, a game engine celebrated for its versatility and ease of use among developers. Understanding ImmediateMesh can enhance your ability to create dynamic, mutable geometry in your games, making this a valuable skill in your developing toolkit. Whether you’re a budding game designer or a seasoned coder, this guide promises to enrich your understanding of ImmediateMesh and how it can be applied in Godot 4 for stunning visual effects and intriguing gameplay elements.

What is ImmediateMesh?

ImmediateMesh is a Mesh class in Godot 4, designed for manually creating geometry within the game engine. It operates similarly to the classic OpenGL 1.x immediate mode, granting developers precise control over the creation of their 3D mesh.

What is it for?

The primary use of ImmediateMesh is to construct simple geometric shapes within Godot. It’s not meant for complex models but rather for objects that need to be dynamically changed or updated often, such as particles or procedural content.

Why Should I Learn It?

By mastering ImmediateMesh, you will gain the ability to program dynamic geometric structures directly within your game’s runtime. This skill is particularly useful for creating special effects, experimental visuals, or dynamic in-game interactions. With ImmediateMesh, the only limit is your imagination, as you’ll be able to tweak and manipulate your meshes in real-time.

CTA Small Image

Creating a Basic ImmediateMesh

First, let’s start with how to create a simple ImmediateMesh in Godot 4. Here we will create our ImmediateMesh instance and prepare it to accept vertices.

var imesh =
imesh.begin(Mesh.PRIMITIVE_TRIANGLES, null)

We have created a new ImmediateGeometry object and attached it to our node. The `begin` function initializes the drawing of triangles without using any material.

Adding Vertices to ImmediateMesh

Next, we’ll add vertices to our ImmediateMesh to form a triangle. This will demonstrate how to define points in 3D space and create simple shapes.

# Define the vertices of a triangle
var vertex1 = Vector3(0, 1, 0)
var vertex2 = Vector3(1, 0, 0)
var vertex3 = Vector3(-1, 0, 0)

# Add the vertices to the ImmediateMesh

With the vertices defined and added, we’ve now created the geometry for a single triangle in ImmediateMesh.

Completing the Mesh

After adding the vertices, we need to call the `end` function to let ImmediateMesh know we are done defining the mesh.


Calling `end` completes the process, and if you run the scene now, you should see a white triangle appear on the screen.

Setting up a Simple Material

Let’s take another step and apply a basic material to our ImmediateMesh. This will allow us to change its color and visual appearance.

var material =
material.albedo_color = Color(1, 0, 0) # Red
imesh.mesh.surface_set_material(0, material)

This code creates a new `SpatialMaterial`, sets its color to red, and then applies it to the ImmediateMesh’s surface.

Adding Normals and UVs

To make our mesh work properly with lighting and textures, we’ll add normals and UV coordinates to our vertices.

# Add normals to each vertex
imesh.add_normal(Vector3(0, 0, 1))
imesh.add_normal(Vector3(0, 0, 1))
imesh.add_normal(Vector3(0, 0, 1))

# Add UV coordinates to each vertex
imesh.add_uv(Vector2(0.5, 1.0))
imesh.add_uv(Vector2(1.0, 0.0))
imesh.add_uv(Vector2(0.0, 0.0))

Here, each normal is set to face forward, and UVs are mapped to the vertices of the triangle, which could then be used to texture the mesh.

Rendering Multiple Shapes

Lastly, let’s look at how to use ImmediateMesh to render multiple shapes within a single draw call.

# Start a new mesh for rendering a square
imesh.begin(Mesh.PRIMITIVE_TRIANGLES, null)

# Define and add the vertices for the first triangle of the square
imesh.add_vertex(Vector3(-1, 1, 0))
imesh.add_vertex(Vector3(1, 1, 0))
imesh.add_vertex(Vector3(-1, -1, 0))

# Define and add the vertices for the second triangle of the square
imesh.add_vertex(Vector3(1, 1, 0))
imesh.add_vertex(Vector3(1, -1, 0))
imesh.add_vertex(Vector3(-1, -1, 0))


By calling `begin` and `end` again, we’ve told ImmediateMesh to draw a new set of triangles, which together form a square.

With these examples, we’ve covered setting up a basic ImmediateMesh, rendering simple shapes, applying materials, and using normals and UVs to create more complex and visually rich objects. These fundamental skills will serve as the building blocks for creating dynamic and procedurally generated meshes in your Godot projects.To further explore the potentials of ImmediateMesh, let’s delve into more complex examples. Now you’ll learn how to manipulate vertices, create lines and curves, and handle more advanced material properties.

Manipulating Vertices in Real-Time

ImmediateMesh can also be used to modify vertices in real-time. This is particularly useful for animations or interactive elements within your game.

# Assume 'imesh' is already defined and is an ImmediateGeometry

func _process(delta):
    # Make sure to clear the previous geometry

    # Begin drawing point primitives
    imesh.begin(Mesh.PRIMITIVE_POINTS, null)
    # Add a moving vertex
    var time = OS.get_ticks_msec() / 1000.0
    var vertex = Vector3(sin(time * 2.0) * 2.0, 0, 0)
    # End the draw call

In this example, a single vertex moves back and forth along the X-axis. This could represent a dynamic element within your game, such as a bouncing ball or a character’s position indicator.

Creating Lines and Curves

ImmediateMesh isn’t limited to just points and triangles; you can also create lines and curves. The following example illustrates how to draw a simple line between two points.

# Begin drawing line primitives
imesh.begin(Mesh.PRIMITIVE_LINES, null)

# Define two points and draw a line between them
imesh.add_vertex(Vector3(-1, 0, 0))
imesh.add_vertex(Vector3(1, 0, 0))

# End the draw call

Drawing curves follows a similar approach but requires more vertices to convey the curvature smoothly. You can create a simple sine wave pattern using lines:

# Begin drawing line strip primitives
imesh.begin(Mesh.PRIMITIVE_LINE_STRIP, null)

# Add vertices to form a sine wave
for i in range(-10, 10):
    var x = i * 0.1
    var y = sin(x * PI * 2.0)
    imesh.add_vertex(Vector3(x, y, 0))

# End the draw call

This code will create a wavy line, which could represent anything from terrain to an energy field in your game.

Handling Transparency and More Complex Materials

Let’s look at how to handle transparency by tweaking the material properties of our ImmediateMesh to create effects like ghosting or glass.

# Set the material's transparency flag and albedo color's alpha
material.flags_transparent = true
material.albedo_color = Color(1, 1, 1, 0.5) # Semi-transparent white
imesh.mesh.surface_set_material(0, material)

Handling more complex materials involves setting properties such as emissive colors, metallic, and roughness values:

# Adjust other material properties
material.emission = Color(0.0, 0.8, 1.0) # Emissive blue
material.metallic = 0.5
material.roughness = 0.1

# Update the material on the mesh
imesh.mesh.surface_set_material(0, material)

The mesh will now have a semi-transparent look with a metallic sheen and a bright blue glow, perfect for futuristic or magical elements.

Optimizing ImmediateMesh Usage

While ImmediateMesh is a powerful tool, it’s important to use it judiciously for performance reasons. Here is a way to reduce the draw calls by batching the drawing of multiple geometries.

# Assume 'imesh' is already defined and is an ImmediateGeometry
# Begin drawing triangles
imesh.begin(Mesh.PRIMITIVE_TRIANGLES, null)

# Add multiple triangles in one batch
for i in range(5):
    imesh.add_vertex(Vector3(-1 * i, 1, 0))
    imesh.add_vertex(Vector3(1 * i, 0, 0))
    imesh.add_vertex(Vector3(-1 * i, -1, 0))

# End the draw call

This example adds five triangles using a single `begin` and `end` pair, making the call much more efficient than drawing each triangle separately.

Remember that ImmediateMesh is best utilized for dynamic and procedural content where meshes cannot be pre-compiled. For static content, traditional static meshes are typically more performant.

And with that, you have a stronger foundation for utilizing ImmediateMesh in Godot 4 to create dynamic, real-time geometry within your game projects. As you embrace these techniques, remember that the art of game design intertwines both the imagination of the creator and the tools at their disposal. Enjoy crafting your worlds with the power of ImmediateMesh, and may your game development journey be filled with endless possibilities and innovative creations.Continuing with our exploration of ImmediateMesh, let’s further our understanding with additional examples, highlighting different use cases and rendering techniques. These examples aim to provide a solid grasp of ImmediateMesh’s flexibility.

Drawing a Bezier Curve

ImmediateMesh can be applied to complex tasks such as drawing Bezier curves, useful for path visualizations and dynamic objects. Below, we generate a simple quadratic Bezier curve with ImmediateMesh.

# Define three control points for the Bezier curve
var p0 = Vector3(-2, -1, 0)
var p1 = Vector3(0, 2, 0)
var p2 = Vector3(2, -1, 0)

# Begin drawing line strip primitives for the curve
imesh.begin(Mesh.PRIMITIVE_LINE_STRIP, null)

# Tesselate the Bezier curve
for t in range(0, 11):
    var u = t / 10.0
    var point = (1 - u) * (1 - u) * p0 + 2 * u * (1 - u) * p1 + u * u * p2

# End the draw call

The points `p0`, `p1`, and `p2` define the control points of the Bezier curve, and we create a smooth curve by interpolating these points.

Rendering a Colored Circle

A circle is a useful shape in games and can indicate areas of effect, targets, or simply serve as a visual element. Here’s how to render a colored circle:

# Define the center and radius of the circle
var center = Vector3(0, 0, 0)
var radius = 1.0
var points_count = 32

# Begin drawing triangle fan to create a circle
imesh.begin(Mesh.PRIMITIVE_TRIANGLE_FAN, null)

# Center vertex for the triangle fan

# Add vertices for the circle
for i in range(points_count + 1):
    var angle = i * 2 * PI / points_count
    var x = center.x + sin(angle) * radius
    var y = center.y + cos(angle) * radius
    imesh.add_vertex(Vector3(x, y, center.z))

# End the draw call

This creates a circle by drawing triangles from the center to points along the circle’s circumference.

Animating Vertex Colors

Vertices can also be assigned colors, leading to many creative effects, such as pulsating energy fields or color-shifting surfaces.

# Assume 'imesh' is already defined and is an ImmediateGeometry

# Initialize a counter variable outside of the process function
var counter = 0.0

func _process(delta):
    # Increment counter
    counter += delta

    # Clear the ImmediateGeometry

    # Begin drawing triangle primitives
    imesh.begin(Mesh.PRIMITIVE_TRIANGLES, null)

    # Define the vertices of the triangle
    var vertex1 = Vector3(0, 1, 0)
    var vertex2 = Vector3(1, 0, 0)
    var vertex3 = Vector3(-1, 0, 0)

    # Calculate color based on the counter
    var color = Color(abs(sin(counter)), abs(cos(counter)), abs(sin(counter * 0.5)), 1)

    # Set colors for each vertex

    # End the draw call

This simple animation changes the color of all triangle vertices over time, creating a pulsating effect.

Creating a Grid of Points

A grid of points can illustrate spatial data or serve as a debug tool to visualize concepts like pathfinding grids or terrain heightmaps.

# Define the size of the grid
var grid_size = 10
var step = 1.0

# Begin drawing points primitives
imesh.begin(Mesh.PRIMITIVE_POINTS, null)

# Generate the grid of points
for x in range(-grid_size, grid_size + 1):
    for y in range(-grid_size, grid_size + 1):
        imesh.add_vertex(Vector3(x * step, 0, y * step))

# End the draw call

This code generates a flat grid of points where you can, for instance, visualize terrain elevation by modifying the Y component based on some function.

Through these diverse code snippets, you can appreciate the capabilities of ImmediateMesh in Godot 4. Whether you’re using it to create dynamic visual elements, debug tools, or interactive components, ImmediateMesh offers developers the control and flexibility needed to breathe life into their creative visions. Learning to harness these features effectively will no doubt elevate the quality and rich detail of your game design projects.

Continue Your Game Development Journey with Zenva

Mastering ImmediateMesh in Godot 4 is just the beginning of what you can achieve with this powerful game engine. If you’re eager to expand your knowledge and create your own captivating games, we encourage you to explore our Godot Game Development Mini-Degree. This comprehensive program is designed to take you from the basics to building complete games in genres like platformers, RPGs, RTS, and more.

At Zenva, we’ve curated a selection of courses that cater to both beginners and experienced developers, ensuring you can continue growing your skills at your own pace. Our Godot courses cover a broad range of topics, ensuring there’s always something new to learn. You’ll gain hands-on experience with 2D and 3D assets, GDScript, gameplay control flow, and much more.

Take the plunge and seize the opportunities in the thriving game market with the skills you’ll acquire through Zenva. Whether you’re looking to polish your game development prowess or start a brand-new adventure, our courses are a reliable bridge to your professional aspirations in the gaming industry. Start your learning today and turn your game concepts into reality!


With the power and flexibility of Godot’s ImmediateMesh at your fingertips, you’re now equipped to create innovative and dynamic game elements that can truly set your projects apart. As you practice and apply the techniques covered in this tutorial, remember that every step taken is a stride towards mastery in game development. We’re excited to see the worlds you’ll craft and the stories you’ll tell through your games.

Don’t stop here – continue building on your newfound skills by exploring our Godot Game Development Mini-Degree. It’s an ideal next step for anyone looking to delve deeper into Godot and game creation. With Zenva’s support, you’re not just learning; you’re making your mark in the gaming world. Unleash your creativity and let your imagination run wild – the game development journey awaits you!

Python Blog Image

FINAL DAYS: Unlock coding courses in Unity, Godot, Unreal, Python and more.