MeshLibrary in Godot – Complete Guide

When diving into the world of 3D game development, one of the essential tools for creating rich environments is the management of 3D meshes. These are the building blocks of the visual aspects within the game – be it characters, terrain, or props. In Godot 4, an incredibly powerful and user-friendly game engine, developers are provided with an array of classes to manipulate and utilize 3D meshes effectively. Among these, MeshLibrary stands out as a pivotal class that serves as a repository for 3D mesh resources. Whether you’re just beginning to explore 3D game creation or you’re a seasoned coder looking to deepen your understanding of Godot 4’s capabilities, understanding MeshLibrary can be both insightful and empowering.

What Is MeshLibrary?

// Imagine a bookshelf, each book is a 3D model, and MeshLibrary is the structure holding them.
// Godot's MeshLibrary acts similarly, organizing numerous 3D models for ease of access and use.

MeshLibrary in Godot 4 is akin to a digital bookshelf of 3D models. It’s a specialized resource that holds a collection of mesh assets, each uniquely identified and optionally paired with collision and navigation shapes. If you’ve ever used a GridMap or have considered creating vast worlds with interchangeable pieces, then you’ve likely encountered or will need the MeshLibrary.

What Is It For?

The primary use of MeshLibrary is to offer a way to store and organize mesh assets for the GridMap node. GridMap allows developers to create large, grid-based environments efficiently, and MeshLibrary is what feeds it with usable content. Incorporating pre-designed 3D models into your game’s environment becomes a piece of cake, enabling rapid development and iterative design workflows.

Why Should I Learn It?

Learning to use MeshLibrary enhances your 3D game development skills by:

– **Streamlining Asset Management:** Organize and access your 3D models easily.
– **Facilitating Level Design:** Quickly populate your game worlds with pre-made meshes.
– **Encouraging Reusability:** Reuse assets across different projects without redundancy.

In addition, familiarizing yourself with MeshLibrary gives you a better grasp of resource management in Godot 4, an essential skill for any game developer. As we continue in this tutorial, we will take you through examples and practices that not only clarify MeshLibrary’s functionalities but also equip you with the knowledge to harness its full potential in your game projects. Let’s embark on this journey together into the world of 3D meshes and master an indispensable resource in Godot 4.

CTA Small Image

Creating a New MeshLibrary

Before diving into the practical examples, let’s begin by creating a fresh MeshLibrary in Godot 4. This is the first step to populating our GridMap and eventually our game world.

// Step 1: Create a new MeshLibrary resource
var mesh_lib =

// Step 2: Save the MeshLibrary resource to a file"res://my_meshes.meshlib", mesh_lib)

This code snippet establishes a new MeshLibrary instance and then saves it to a file. It’s fundamental to save our work, ensuring that we can reference these assets later as we build our levels.

Adding Meshes to the Library

Once our MeshLibrary exists, we need to fill it with actual 3D models. This involves associating each mesh with a unique item ID.

// Adding a single mesh with a unique ID
var mesh_item_id = 1
mesh_lib.set_item_mesh(mesh_item_id, preload("res://my_mesh.tres"))

// Repeat the process for additional meshes, ensuring each has a unique ID
var another_mesh_item_id = 2
mesh_lib.set_item_mesh(another_mesh_item_id, preload("res://another_mesh.tres"))

In these examples, we’re preloading specific meshes and assigning them unique IDs in our MeshLibrary. Remember, the `preload` function assumes the files are accessible and the paths are correct.

Attaching Collision and Navigation Shapes

For meshes to interact properly in the game world, we often need to add collision and navigation shapes.

// Attach a collision shape to the first mesh using a ConvexPolygonShape
var shape =
// ... Assume you've set up the shape as needed ...
mesh_lib.set_item_shape(mesh_item_id, 0, shape)

// For navigation, use a NavigationMesh instance
var navmesh =
// ... Set up the navigation mesh ...
mesh_lib.set_item_navmesh(mesh_item_id, navmesh)

Here, we’ve assigned a collision shape and a navigation mesh to our first item. Adjust these components to fit the intended functionality within your game.

Previewing Library Items in the Editor

It can be incredibly useful to visually inspect what’s inside your MeshLibrary without running the game. Here’s how to create an editor plugin script to do just that.

// Editor plugin script that loads and displays MeshLibrary items

extends EditorScript

func _run():
    var mesh_lib = preload("res://my_meshes.meshlib")
    var gridmap =
    gridmap.mesh_library = mesh_lib

By running this editor script, you’ll add a GridMap node to the currently edited scene, populated with the meshes from your MeshLibrary. This gives you an immediate preview of the assets and can save you time during the level design process.

Updating MeshLibrary Content

As your game evolves, you may need to update existing meshes or add new ones. Godot 4’s scripting API makes this seamless.

// Update an existing mesh
mesh_lib.set_item_mesh(existing_item_id, preload("res://updated_mesh.tres"))

// Add a new mesh to the library
var new_mesh_item_id = mesh_lib.get_last_unused_item_id()
mesh_lib.set_item_mesh(new_mesh_item_id, preload("res://new_mesh.tres"))

The first example shows how to update a mesh that’s already in the MeshLibrary, while the second demonstrates how to safely add a new entry by finding the next available ID. Regular maintenance of your MeshLibrary ensures that everything remains current and functions as desired within your game.

We’ve now explored how to create, populate and update a MeshLibrary in Godot 4. In the next part of this tutorial, we will delve into using this MeshLibrary with a GridMap to construct complex 3D environments efficiently. Stay tuned to elevate your understanding and application of these exciting game development tools.Understanding the basics of the MeshLibrary is just the beginning. As you develop your game, you’ll often find yourself dynamically modifying the MeshLibrary or programmatically controlling how GridMap uses it. Let’s dive into more advanced operations and delve deeper into the practical utilization of MeshLibrary within Godot 4. All set? Let’s get coding!

Programmatic Modification of the MeshLibrary

Sometimes, you want to modify your MeshLibrary at runtime. Perhaps you’re generating levels procedurally, or you’re allowing players to contribute to the world. Here’s how you can add a mesh to your MeshLibrary during gameplay:

// Adding a mesh at runtime
func add_mesh_to_library(runtime_mesh, mesh_name):
    var item_id = mesh_lib.get_last_unused_item_id()
    mesh_lib.set_item_mesh(item_id, runtime_mesh)
    mesh_lib.set_item_name(item_id, mesh_name)

In this example, you’re dynamically finding the next available ID, creating an item, setting its mesh, and giving it a human-readable name.

Let’s suppose you also want to clean up your MeshLibrary, perhaps to remove unused assets that are consuming memory:

// Removing a mesh from the MeshLibrary
func remove_mesh_from_library(item_id):
    if mesh_lib.has_item(item_id):

This method checks whether the mesh exists in the library before removing it to avoid errors.

Programmatic Usage of GridMap with MeshLibrary

GridMap, paired with MeshLibrary, allows for the composition of 3D spaces using predefined blocks or tiles. You can create or change an entire map programmatically with scripts.

Consider a scenario where you’re generating a level based on a player’s actions. Here’s how you might set a specific tile within a GridMap node:

// Set a tile at a specific grid location
var grid_position = Vector3(10, 0, 5) // x, y, and z index in the grid
var item_id_to_place = 1 // the ID of the mesh in the MeshLibrary
grid_map.set_cell_item(grid_position.x, grid_position.y, grid_position.z, item_id_to_place)

This snippet will place a mesh with the ID of `1` at the grid coordinates (10, 0, 5). You can loop this function or tie it to a particular event to dynamically change your level’s layout.

To randomize or add variability to a procedurally generated map, you could randomly select items from your MeshLibrary:

// Randomly fill a layer of the GridMap with tiles from the MeshLibrary
func populate_gridmap_layer(y_index, grid_size):
    for x in range(grid_size.x):
        for z in range(grid_size.z):
            var random_item_id = randi() % mesh_lib.get_item_count()
            grid_map.set_cell_item(x, y_index, z, random_item_id)

This would fill an entire layer (given by `y_index`) with randomly selected tiles from the MeshLibrary.

Sometimes, you might want to iterate over all the cells in a GridMap that are not empty and perform some action. Here’s an example:

// Iterating over non-empty cells in a GridMap
grid_map.get_used_cells().each(funcref(this, "process_cell"))

func process_cell(cell_vector):
    # Get the current item ID at the cell
    var current_item_id = grid_map.get_cell_item(cell_vector.x, cell_vector.y, cell_vector.z)
    # Perform an action, like checking for a property or replacing the mesh
    if current_item_id == special_mesh_id:

In this case, `process_cell` could contain logic specific to the game – maybe you’re checking for a special type of tile or you want to trigger an event based on the tile’s position and type.

Batch Updating GridMap Cells

Finally, you may find yourself in a situation where you need to update multiple cells within your GridMap. For example, a terraforming event that changes the landscape. Rather than setting each cell one by one, you can batch update them:

// Batch update cells
var cells_to_update = [, 0, 0), false, false, false, 1),
             , 0, 0), false, false, false, 2)]

The `set_cells` method takes an array of `GridMap.Cell` items, allowing you to efficiently update several cells simultaneously.

With these advanced code examples, you can push the boundaries of what’s possible with MeshLibrary and GridMap in Godot 4. You’re now equipped with the knowledge to implement dynamic and interactive 3D environments that can evolve at runtime, providing enriching experiences for your players. Continue experimenting with these snippets, integrate them into your projects, and unlock the full potential of your game worlds!As we delve deeper into the mechanics of runtime environment manipulation, it becomes essential to look at how to interact with and manage the details of each mesh within a GridMap. For example, you might want to adjust materials or shaders on the fly, react to player actions by altering the mesh, or even go as far as changing the game’s aesthetics on the go.

Let’s explore several key examples of how to work with meshes in your GridMap using Godot 4’s powerful scripting capabilities.

Adjusting Mesh Materials at Runtime

Sometimes, different situations in your game may call for the properties of a mesh to change. One common change is the material, which can alter the appearance of a mesh. Here’s how you change the material of a specific mesh item in your MeshLibrary:

// Change the material of mesh item 1 to a new material
var new_material = preload("res://my_new_material.tres")
mesh_lib.set_item_material(1, new_material)

This modifies the material used by all instances of mesh item 1. It’s perfect for global changes, such as a game mechanic that alters the state of all similar objects.

Swapping Meshes Based on Game Events

In reaction to game events, such as a character interaction or a time-based trigger, you may need to swap one mesh for another completely. Let’s see how that could be handled:

// Replace mesh item 1 with a new mesh during gameplay
var new_mesh = preload("res://my_alternative_mesh.tres")
mesh_lib.set_item_mesh(1, new_mesh)

// Update all existing instances in the GridMap

Here, we not only update the mesh in the MeshLibrary but also ensure that all existing instances of that mesh within the GridMap update to reflect the change.

Interactivity with Mesh Instances

Often in a game, clicking or interacting with a part of the environment needs to have an immediate result. Imagine a scenario where clicking on a mesh causes it to “light up.” Here’s one way to achieve this:

// Assuming you've detected a click on a GridMap cell and have the cell's position
// Change the emission color of the mesh's material to "light it up"
func highlight_mesh(cell_position):
    var item_id = grid_map.get_cell_item(cell_position.x, cell_position.y, cell_position.z)
    var mesh_instance = mesh_lib.get_item_mesh(item_id).instance()
    var new_material = mesh_instance.material_override.duplicate()
    new_material.emission_color = Color(1, 1, 0)  // Make it yellow
    mesh_instance.material_override = new_material

This example sets the emission color parameter of the material, effectively “highlighting” the clicked mesh.

Bulk Operations on GridMap Cells

It’s often more efficient to perform bulk operations on GridMap cells rather than iterating over them one by one, particularly for large maps or when many changes are needed. Here’s how you might batch process a “damage” event to a set of cells:

// Batch-processing a 'damage effect' on multiple GridMap cells
func apply_damage_to_cells(cell_positions, damage_material):
    for cell_position in cell_positions:
        var cell_item_id = grid_map.get_cell_item(cell_position.x, cell_position.y, cell_position.z)
        var mesh_instance = mesh_lib.get_item_mesh(cell_item_id).instance()
        mesh_instance.material_override = damage_material

In this function, `cell_positions` is a list of cell vectors to update, and `damage_material` is a preloaded material representing the damage effect.

To make your changes visible instantly, don’t forget to refresh your GridMap:

// Refresh the GridMap to make changes visible

This tells the engine to redraw the affected quadrants of the GridMap, updating the visuals immediately.

Performance Tip: Use call_deferred if you need to update a huge number of cells, to prevent performance hiccups:

// Deferred GridMap update for better performance

Through these code snippets, you now have several advanced techniques to manipulate and update your MeshLibrary and GridMap in Godot 4. These examples can significantly enhance interactivity and immersion in your games, making your virtual worlds feel alive and reactive to player actions. Keep experimenting with these tools and watch as the worlds you build become dynamic stages for your players’ adventures.

Continue Your Game Development Journey

As you’ve taken your first steps into mesh management and environment manipulation with Godot 4, you might wonder, “Where do I go from here?” Your journey in mastering game development has just begun, and there is an entire universe of knowledge waiting for you. To continue building on the foundation you’ve established, our Godot Game Development Mini-Degree is a treasure trove of learning material that is carefully crafted to take you from beginner to pro.

Whether you are completely new to game development or looking to sharpen your skills, Zenva’s flexible learning options, including live coding lessons and project-based learning, will guide you through a spectacular range of Godot 4 topics. The Mini-Degree covers everything from 2D and 3D assets, GDScript mastery, to intricate game mechanics found in RPGs, RTS, survival games, and platformers.

Moreover, if you’re eager to delve into even broader aspects of Godot development, our full range of Godot courses has you covered. Explore at your own pace and earn certificates which can be a stepping stone to further your career in this vibrant industry. With over 250 supported courses, Zenva is your ally, turning your passion into a profession. Get started today and be part of the thriving game development community!


Embarking on the path of game development with Godot 4 opens a realm of creative opportunities, and mastering the MeshLibrary is a testament to your growing expertise. You’ve learned not just how to store and manage 3D assets, but also how to dynamically interact with your game world, making it responsive and immersive. Remember, this is just a segment of the vast knowledge landscape that game development encompasses. As you continue to build your skill set, remember that Zenva is here to support you every click of the way.

Take the next step in your learning adventure with our comprehensive Godot Game Development Mini-Degree. Whether you’re looking to polish your fundamentals or aiming to construct intricate game mechanics, our curated courses are designed to boost your confidence and competence in the field. So, why wait? Join us at Zenva today, where your dream of becoming a game developer is not just a possibility – it’s your next achievement!

Python Blog Image

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