TriangleMesh in Godot – Complete Guide

Understanding the intricacies of game development can open up a universe of possibilities for creative expression and technical achievement. Throughout this tutorial, you’ll discover the powerful role that the TriangleMesh class plays within the Godot 4 engine, and how it forms the backbone of collision calculations—an essential component for any game. Allow yourself to be carried on a project-independent journey through code, examples, and clear explanations designed to enlighten both beginners and experienced developers alike.

What is TriangleMesh?

TriangleMesh is a Godot 4 construct that serves as a type of mesh specifically designed for internal collision calculations. But what exactly is a mesh? In 3D graphics, a mesh is a collection of vertices, edges, and faces that defines the shape of a polyhedral object. In the context of Godot, a TriangleMesh is composed of triangles, which are the simplest form of polygons that can define a 3D shape.

What is it used for?

The use of TriangleMesh is particularly important for accurately simulating the physical interactions between objects in a game environment. Here are some common use cases:

  • Collision detection between objects or characters
  • Physics simulations where the exact shape of objects impacts the outcome
  • Raycasting to determine whether a point in space intersects with the mesh
  • Generating navigable areas for AI pathfinding

Why should I learn it?

Learning how to work with TriangleMesh can significantly impact the polish and realism of your game. By mastering this aspect of the Godot engine, you’re equipping yourself with the skills to:

  • Create intricate and realistic game worlds with proper physics
  • Enhance gameplay mechanics that rely on collision detection
  • Optimize your game’s performance by understanding the internals of mesh use
  • Broaden your toolkit for solving complex game development challenges

It’s not just about making things work—it’s about making them work beautifully and efficiently. Let’s dive in and explore the capabilities of TriangleMesh together!

CTA Small Image

Initializing a TriangleMesh

To start using the TriangleMesh, you must first understand how to create and initialize it within the Godot engine. We’ll create a simple TriangleMesh and attach it to a MeshInstance node for visualization purposes:

var triangle_mesh =
var mesh_instance =
mesh_instance.mesh = triangle_mesh

This snippet creates a new TriangleMesh object and a MeshInstance to hold it. The TriangleMesh is then assigned to the MeshInstance, which is added as a child to the current node.

Defining Vertices and Triangles

Before your TriangleMesh becomes tangible in the game world, you need to define its vertices and how they’re connected to form triangles:

var vertices = PoolVector3Array([
    Vector3(0, 0, 0),
    Vector3(0, 1, 0),
    Vector3(1, 0, 0)

var triangles = PoolIntArray([0, 1, 2])

triangle_mesh.create(triangles, vertices)

In this code, we’ve defined a set of vertices that represent the corners of a single triangle. We then specify how these vertices are connected using an array of index positions, which in this case forms one triangle.

Adding Collision to TriangleMesh

To add collision capabilities to our TriangleMesh, we can use a StaticBody and a CollisionShape node. The StaticBody provides the necessary physical properties, and the CollisionShape is how we assign a shape for collision detection:

var static_body =
var collision_shape =
collision_shape.shape = triangle_mesh


Here, the CollisionShape’s shape property is set to our TriangleMesh, making it possible for Godot’s physics engine to detect collisions with our mesh.

Importing Mesh Data from an Array

If you have a more complex set of vertices and indices representing your mesh, you can import them directly into your TriangleMesh:

var complex_vertices = PoolVector3Array([#... your vertices here])
var complex_triangles = PoolIntArray([#... your triangle indices here])

triangle_mesh.create(complex_triangles, complex_vertices)

This would replace the simple triangle with a more complex mesh structure, based on the arrays of vertices and indices you provide.

Transforming and Translating TriangleMesh

You might want to move or rotate your TriangleMesh within your scene. You can do this by applying a transformation to the MeshInstance node:

mesh_instance.transform = Transform(Basis(), Vector3(5, 0, 0))

This moves the MeshInstance, and thereby the associated TriangleMesh, 5 units along the x-axis. You can adjust the transformation to translate, rotate, or scale the mesh within the game world.

Using TriangleMesh with Shaders

Lastly, you can also use TriangleMesh in combination with shaders for added visual effects. Here’s how you can assign a shader material to your MeshInstance:

var shader_material =
shader_material.shader = preload("res://path_to_your_shader.shader")

mesh_instance.material_override = shader_material

By applying a shader to the mesh, you can create a wide range of visual effects, from simple color changes to complex texture animations.

Stick with us as we continue to delve into more advanced manipulation of TriangleMesh in the next part of our tutorial. The more you practice, the more confidently you can incorporate this powerful tool into your Godot projects.When working with TriangleMesh in Godot 4, you may encounter situations where you need to add even more functionality to your 3D models. Let’s build on our previous examples and introduce additional ways to manipulate and interact with TriangleMesh objects.

Updating TriangleMesh Data

As your game progresses, you might need to modify the mesh data. You can update the vertices or triangles of your TriangleMesh to reflect new shapes and forms dynamically:

var new_vertices = PoolVector3Array([
    Vector3(0, 5, 0),
    Vector3(5, 0, 0),
    Vector3(0, 0, 5)

var new_triangles = PoolIntArray([0, 1, 2])

triangle_mesh.create(new_triangles, new_vertices)

This code demonstrates how to change the triangle’s vertices to a new position, effectively updating the TriangleMesh geometry.

Handling Mesh Collision Events

Detecting collisions is crucial, but responding to them is where you can add significant interactivity to your game. Connect a function to the `body_entered` signal of the StaticBody to respond to collisions:

static_body.connect("body_entered", self, "_on_StaticBody_body_entered")

func _on_StaticBody_body_entered(body):
    print("Collision with: ",

This code connects the collision signal to a custom function that will print the name of the colliding body.

Optimizing TriangleMesh Creation

Efficiency matters in game development. Let’s look at how we can optimize TriangleMesh creation by using `SurfaceTool` and `MeshDataTool`:

var surface_tool =
var mesh_data_tool =

surface_tool.add_vertex(Vector3(0, 0, 0))
surface_tool.add_vertex(Vector3(0, 1, 0))
surface_tool.add_vertex(Vector3(1, 0, 0))

mesh_data_tool.create_from_surface(surface_tool.commit(), 0)
mesh_instance.mesh = mesh_data_tool.get_mesh()

`SurfaceTool` and `MeshDataTool` offer a more advanced and controlled way to construct meshes, which can lead to better performance in complex scenes.

Applying Textures to TriangleMesh

Textures can greatly enhance the visual appeal of your meshes. You can apply textures to a TriangleMesh by setting the material’s albedo texture:

var texture = preload("res://path_to_your_texture.png")
var material =
material.albedo_texture = texture

mesh_instance.set_surface_material(0, material)

This will wrap the specified texture around the TriangleMesh, providing it with more detailed surface features.

Morphing TriangleMesh at Runtime

For dynamic effects, you can morph your TriangleMesh during gameplay. Here’s how you can animate the vertices of your mesh over time to create effects like waves or explosions:

func _process(delta):
    for i in range(len(vertices)):
        var vertex = vertices[i]
        vertex.y += sin(vertex.x * 10 + vertex.z * 10 + time) * delta
        vertices[i] = vertex
    time += delta
    triangle_mesh.create(triangles, vertices)

This code will move each vertex in the y-axis based on a sine wave, creating a wavy effect.

Exporting TriangleMesh as a MeshResource

Sometimes, you may want to reuse or share your TriangleMesh as an asset. You can export the TriangleMesh as a `.mesh` resource file for easy portability and reuse:

var mesh_resource =
mesh_resource.add_surface_from_arrays(Mesh.PRIMITIVE_TRIANGLES, Mesh.ARRAY_FORMAT_VERTEX, [vertices, triangles])"res://your_triangle_mesh.mesh", mesh_resource)

This snippet takes the vertices and triangles information and saves it as a `.mesh` file within your project, accessible for use in other scenes or projects.

These additional capabilities empower you to craft intricate 3D experiences. As you become more comfortable with TriangleMesh in Godot, you’ll find endless ways to use this tool to shape the physical and interactive elements within your virtual world. Join us at Zenva as we guide you further into the realms of Godot game development, helping you reach your creative goals with expert tutorials and high-quality content.Revising the terrain under your game’s characters’ feet can be as dramatic as it is technical. To create landscapes that shift and transform, you’d control each vertex’s position over time with code akin to sculpting in motion. Here’s a step into the world of dynamic terrain manipulation using the TriangleMesh in your Godot projects:

func _process(delta):
    for i in range(0, vertices.size(), 3):
        var vertex = vertices[i]
        vertex.y = get_terrain_height(vertex.x, vertex.z)
        vertices[i] = vertex
    triangle_mesh.create(triangles, vertices)

func get_terrain_height(x, z):
    return noise.get_noise_2d(x, z)  # Assuming 'noise' is an OpenSimplexNoise instance

In this example, a noise function modulates the y-coordinate of each vertex, which could generate hills and valleys for a more natural landscape. The efficiency of this process is paramount in maintaining performance, so consider how often and over how many vertices you apply such transformations.

But maybe you want to venture into more-than-natural phenomena, creating a gaming universe where the terrain responds to player actions or in-game events. Check out how you can dynamically create craters upon impact:

func create_crater_at_position(position, radius, depth):
    var local_pos = global_transform.affine_inverse().xform(position)
    for i in range(0, vertices.size()):
        var vertex = vertices[i]
        var distance_to_impact = vertex.distance_to(local_pos)
        if distance_to_impact < radius:
            vertex.y -= depth * (1 - distance_to_impact / radius)
            vertices[i] = vertex
    triangle_mesh.create(triangles, vertices)

This code calculates a vertex’s distance from an impact point and depresses it proportionally to create a crater effect. When applying such dynamic changes, remember to recreate the TriangleMesh to reflect the alteration in the mesh data.

Yet, games aren’t just about the ground. Let’s skyrocket for a moment and devise a space where your game’s skyscape—the very heavens themselves—wraps the players in an immersive dome.

var sky_dome =
var dome_mesh =
dome_mesh.radius = 100
dome_mesh.height = 50
dome_mesh.radial_segments = 64
dome_mesh.rings = 32

sky_dome.mesh = dome_mesh

This elegantly places a hemisphere about your world, awaiting stellar textures or a shifting day-to-night shader. The sky’s the limit when manipulating 3D space through Godot’s robust mesh system.

Bringing elements of your game to life isn’t solely about grand vistas; the minutiae deserve their due as well. Imagine your characters traversing a wooden bridge that realistically creaks and sways with each step:

func _physics_process(delta):
    for i in range(0, vertices.size()):
        var vertex = vertices[i]
        var force = calculate_force(vertex)
        vertex.y += force * delta
        vertices[i] = vertex
    triangle_mesh.create(triangles, vertices)

func calculate_force(vertex):
    var distance_to_center = abs(vertex.x - bridge_center_x)
    return -sin(distance_to_center) * sway_amplitude

Here, a simple sin wave, influenced by a vertex’s distance from the bridge center, simulates a sway, with `sway_amplitude` dictating the strength of the effect.

Whether terraforming worlds or engineering bridges, the control you wield over 3D meshes in Godot is powerful and inviting. Through Zenva, we aim to illuminate the path to mastery in crafting these virtual realms, offering guidance, insight, and the coding know-how you need to bring your game development visions to fruition.

Continue Your Game Development Journey

With the foundations of TriangleMesh in Godot 4 fresh in your mind, your journey into game development is just beginning. Transforming that initial spark of creativity into a fully-fledged game is an adventure that requires dedication, passion, and, most importantly, continued learning.

We at Zenva understand the thrill of bringing your virtual worlds to life, which is why we encourage you to explore our Godot Game Development Mini-Degree. With an expansive curriculum that covers everything from 2D and 3D game creation to in-depth scripting with GDScript, you’ll be well-equipped to tackle a variety of projects and refine your skills at your own pace, whether you’re a beginner or an experienced developer looking to enhance your toolkit.

For those eager to broaden their Godot expertise, browse our comprehensive collection of Godot courses. Here, you can deepen your understanding of the engine’s capabilities and elevate your game development abilities. Each course is designed to be flexible, accommodating your schedule and learning style, as you work on real projects that bolster your portfolio and showcase your progress.

Keep learning, keep creating, and remember that with Zenva, your next game development milestone is always within reach.


Whether you’re casting spells in a fantasy realm or charting the stars in a sci-fi galaxy, mastering TriangleMesh and the wider world of Godot 4 is a quest worthy of any game developer’s mettle. From collision detection and in-game physics to the creation of dynamic and responsive environments, your new skills stand as a testament to your commitment to crafting extraordinary gaming experiences.

Continue to shape your destiny in the realm of game development with Zenva’s Godot Game Development Mini-Degree. Soak in the knowledge, apply it to your creations, and watch as your games jump from mere ideas to interactive adventures that enrapture players around the world. At Zenva, we are honored to be part of your journey and can’t wait to see the worlds you’ll build.

Python Blog Image

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