MeshConvexDecompositionSettings in Godot – Complete Guide

Welcome to this comprehensive tutorial on using the MeshConvexDecompositionSettings class in Godot 4. This versatile class is packed with parameters that will greatly enhance your game’s physics by allowing for dynamic generation of convex decomposition of meshes. Whether you’re a seasoned game developer or just starting your journey, understanding how to harness the power of mesh decomposition can elevate your game creation skills to the next level. So, join us as we delve into the intricate world of mesh convex decomposition and explore the possibilities it unlocks in Godot 4.

What is MeshConvexDecomposition?

MeshConvexDecomposition, represented in Godot 4 by the MeshConvexDecompositionSettings class, is an advanced technique used in 3D games and simulations. It involves breaking down complicated mesh shapes into simpler convex shapes that can be more easily managed by a physics engine. Imagine a complex object like a rocky terrain or a fragmented sculpture; by decomposing it into convex pieces, your game can efficiently handle collisions, physics simulations, and other real-time interactions.

What is it for?

The process of mesh convex decomposition is crucial for creating realistic physical interactions within a game environment. Each complex object is divided into a series of smaller, convex shapes, making it possible for the physics engine to provide accurate collision detection and response. This is especially important for dynamic objects that break apart upon impact or interact with other elements in the game world.

Why Should I Learn It?

Understanding how to implement MeshConvexDecompositionSettings in Godot 4 is a vital skill for any game developer. It enables you to:

– Optimize your game for better performance during physics calculations.
– Achieve more realistic and responsive game behavior, creating an immersive player experience.
– Expand your toolkit for game development, laying the foundation for complex and interactive 3D environments.

By mastering mesh convex decomposition, you’ll be expanding not only the capabilities of your game but also your own skills as a developer. It’s a win-win endeavor that can only enhance your game’s depth and your expertise.

CTA Small Image

Getting Started with MeshConvexDecompositionSettings

To kick things off, let’s set the stage by creating an instance of the MeshConvexDecompositionSettings class. This will be our foundation for configuring and handling our mesh decomposition.

var decomposition_settings =

Once we have our settings object, we can begin to tweak the various parameters that control the decomposition process. A key parameter to start with is the accuracy.

decomposition_settings.accuracy = 0.1  # Adjust to set the accuracy of the decomposition

The accuracy parameter plays a crucial role in determining the precision of the decomposition. Lower values result in finer detail but may increase computation time.

Configuring Convex Decomposition Settings

The beauty of the MeshConvexDecompositionSettings class lies in its flexibility. It offers a range of parameters to fine-tune the decomposition to fit your specific needs. Let’s look at a few of them in detail:

– **Max Hull Vertices**: The maximum number of vertices allowed for each generated convex hull.

decomposition_settings.max_hull_vertices = 32  # Limits the complexity of each convex hull

– **Decomposition Depth**: Controls how deeply the algorithm should decompose the mesh.

decomposition_settings.decomposition_depth = 3  # Defines the depth of the convex decomposition

– **Decomposition Count**: Sets the maximum number of convex hulls to generate.

decomposition_settings.decomposition_count = 10  # Determines the number of convex hulls created

Each of these settings can be balanced to manage the trade-off between accuracy and performance, ensuring that you can tailor the physics to match the unique requirements of your game.

Applying MeshConvexDecompositionSettings to a Mesh

Now that we’ve configured our decomposition settings, it’s time to apply them to a mesh. In Godot, meshes are represented by the Mesh class, and we can decompose them by calling the `create_convex_shape()` method.

First, let’s get our mesh ready for decomposition:

var mesh_instance =
var my_mesh = load("res://path_to_my_mesh.mesh")
mesh_instance.mesh = my_mesh

Next, we perform the decomposition operation on the mesh using the settings we configured earlier.

var shape = my_mesh.create_convex_shape(decomposition_settings)

Finally, we could add this newly created shape to a physics body for collision detection:

var rigid_body =
var collision_shape =
collision_shape.shape = shape

With these examples, you can see how to configure the decomposer settings, apply them to your mesh, and integrate the result into a physics body. These steps are foundational for creating complex, interactive 3D worlds with realistic physics. Stay tuned, as in the next part, we’ll dive into more advanced usages and provide further examples to solidify your understanding.

Advanced Mesh Convex Decomposition Techniques

Moving forward, let’s explore some advanced techniques for using the MeshConvexDecompositionSettings class. Your games can benefit greatly from these additional features, enabling more sophisticated physics interactions.

First, we might want to adjust the **simplification rate**. This setting controls how much the algorithm simplifies the mesh before the decomposition starts, potentially speeding up the process for complex meshes.

decomposition_settings.simplification_rate = 0.05  # Simplifies the mesh to speed up decomposition

Another important aspect is the **gaps filling**. This defines how the algorithm fills gaps in the mesh to ensure all spaces are decomposed properly.

decomposition_settings.gaps_filling = true  # Enable filling gaps to ensure proper decomposition

Complex shapes might contain internal structures that present additional challenges. Enabling **internal structure detection** can help address this.

decomposition_settings.use_internal_structure_detection = true  # Helps in decomposing meshes with internal structures

If you are dealing with terrain or objects where players will walk or interact with, the **flat primitive detection** can be a valuable feature. This detects and optimizes flat surfaces to behave more consistently under physics.

decomposition_settings.use_flat_primitive_detection = true  # Optimizes for flat surfaces

Now, let’s combine these settings into a scene where we can actually witness the results. Suppose we are decomposing a landscape for a more realistic interaction when a character walks over it.

// Set up your landscape MeshInstance here as 'mesh_instance'

// Configure decomposition settings
decomposition_settings.max_hull_vertices = 64
decomposition_settings.decomposition_depth = 4
decomposition_settings.decomposition_count = 20
decomposition_settings.simplification_rate = 0.05
decomposition_settings.gaps_filling = true
decomposition_settings.use_internal_structure_detection = true
decomposition_settings.use_flat_primitive_detection = true

// Decompose the mesh
var shape = mesh_instance.mesh.create_convex_shape(decomposition_settings)

// Create a physics body and apply the shape
var landscape_body =
var landscape_shape =
landscape_shape.shape = shape

Finally, let’s not forget about the **bevel amount**. Adding a bevel can help smooth out the collision shapes, preventing characters from getting stuck on sharp edges.

decomposition_settings.bevel_amount = 0.1  # Adds a bevel to smooth sharp edges

Once the shapes are generated, if you wish to instantiate them as individual physics bodies, you can loop through the array of shapes and add them to the scene:

var shapes_array = my_mesh.create_multiple_convex_shapes(decomposition_settings)

for shape in shapes_array:
    var body =
    var col_shape =
    col_shape.shape = shape

Through this knowledge, your game can now showcase environments with detailed physics interactions that not only look great but behave realistically. With efficient convex decomposition, your players can enjoy smooth gameplay experiences without unnecessary hiccups. Keep experimenting with these settings to achieve the perfect balance for your project and lead your game development journey with expertise.Let’s now delve deeper into optimizing the mesh decomposition process for collision shapes, and explore how we can visualize the results to adjust our settings efficiently in Godot 4.

Optimization is key when generating collision shapes for your game, as too many shapes can impact performance. Using the **convex decomposition mode** setting, you can specify the level of optimization you desire.

decomposition_settings.convex_decomposition_mode = MeshConvexDecompositionSettings.VXM_QUICK  # Use a faster, less detailed decomposition mode

It’s also worth noting that in Godot, you may want to visualize the generated convex hulls to ensure they align with your mesh correctly. You could do this by scripting a simple debug visualization:

func visualize_convex_hulls(mesh_instance, decomposition_settings):
    var mesh = mesh_instance.mesh
    var hulls = mesh.create_multiple_convex_shapes(decomposition_settings)
    for hull in hulls:
        var debug_mesh_instance =
        var debug_mesh = Mesh.create_trimesh_shape(hull)
        debug_mesh_instance.mesh = debug_mesh
        debug_mesh_instance.material_override = create_debug_material()

func create_debug_material():
    var material =
    material.albedo_color = Color(1, 0, 0, 0.5)
    material.flags_transparent = true
    return material

Using this script, you can visually inspect the generated convex hulls directly within the Godot editor, by calling `visualize_convex_hulls` with a mesh instance and the decomposition settings you’ve chosen.

In some scenarios, you might find that your mesh decomposes into too many or too few hulls, resulting in either performance issues or unrealistic physics. You can adjust the **minimum volume to surface ratio** setting to fine-tune this balance:

decomposition_settings.min_volume_to_surface_ratio = 0.1  # Adjusts the balance between volume and surface area in the resulting hulls

Additionally, if you want to prioritize creating a lower number of convex shapes, sometimes at the expense of fitting accuracy, you can use the **priority mode** setting:

decomposition_settings.priority_mode = MeshConvexDecompositionSettings.PRIORITY_MIN_HULLS  # Prioritizes generating fewer hulls

In contrast, if you value accuracy over the number of shapes, you could configure the settings to prioritize detail:

decomposition_settings.priority_mode = MeshConvexDecompositionSettings.PRIORITY_BALANCE  # Balances between count and detail

Lastly, don’t forget about setting the **convex decomposition seed**, which can be useful if you’re looking to reproduce consistent decomposition results across different runs of the same mesh:

decomposition_settings.convex_decomposition_seed = 42  # Set a fixed seed for reproducible decompositions

By using these code examples, you’ll gain finer control and can calibrate your convex decomposition to align perfectly with the physics requirements of your game. Tuning these parameters may require some iteration to get just right, but once dialed in, your game will boast solid and optimized collision detection, contributing to a polished gameplay experience. Keep experimenting and refining to achieve an optimal setup that brings your 3D world to life with both efficiency and realism.

Where to Go Next in Your Game Development Journey

Having delved into the intricate process of mesh convex decomposition with Godot 4, you’ve taken an important step towards mastering game creation. But the journey doesn’t end here. There’s a whole universe of game development concepts waiting to be explored, and we at Zenva are here to guide you every step of the way.

To continue sharpening your skills and expanding your knowledge, we highly recommend checking out our Godot Game Development Mini-Degree. This comprehensive collection of courses is designed to take you from a beginner to a proficient game developer, covering a wide array of topics and projects that will help cement your understanding and give you practical experience.

And if you’re eager to dive even deeper into Godot, be sure to explore our broader collection of Godot courses at Zenva Academy. With over 250 supported courses across various topics, including programming and AI, there’s no limit to what you can achieve. Whether you’re just starting out or looking to upgrade your existing skills, our courses are tailored to help you learn at your own pace and create games that captivate players. Let your creativity flow, and continue to build your game development career with Zenva – your next level awaits!


With the MeshConvexDecompositionSettings class in Godot 4 at your disposal, you are now equipped to give your games a physics-based edge that will set them apart. Remember, the best games often have nuanced interactions that make the world feel alive and responsive, and utilizing mesh convex decomposition is a decisive step in that direction. As you continue to build and refine your creations, let this knowledge become a cornerstone of your game physics and collision detection systems.

Our journey at Zenva doesn’t stop here. We encourage you to keep the momentum going by diving into our Godot Game Development Mini-Degree, where even more professional expertise and engaging projects await. Let these lessons be the catalyst for your growth as a developer, and always remember – the games you dream of creating are well within your reach with Zenva by your side. Game on!

Python Blog Image

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