ConcavePolygonShape3D in Godot – Complete Guide

Embarking on a journey to master game development is akin to stepping into a world of endless possibilities, where your imagination becomes the blueprint for captivating interactive experiences. With the vast array of game engines available today, one particularly stands out for its ease of use, diversity of features, and robust community: Godot. Within Godot, the art of creating these experiences largely hinges on understanding its core components – one such being the ConcavePolygonShape3D class, a powerful tool in the arena of 3D collision shapes in Godot 4. If you’re looking to add complexity and realism to your game’s physics, you’ve come to the right place. Let’s delve into what makes the ConcavePolygonShape3D class indispensable for crafting intricate 3D environments.

What Is ConcavePolygonShape3D?

ConcavePolygonShape3D is a component within Godot Engine tailored for defining the physical boundaries of complex 3D objects. It’s a type of Shape3D specifically used in physics calculations to create non-convex meshes, which can represent virtually any shape imaginable, no matter how irregular. They’re the go-to for level designers when mapping out expansive, static environments or structures.

What Is It For?

This versatile shape has its primary purpose in serving as a collision mesh for various static objects within your game world. Whether you’re constructing the detailed exterior of a medieval castle or the undulating terrain of an alien landscape, ConcavePolygonShape3D is your digital chisel, shaping the virtual stone.

Why Should I Learn It?

By learning how to wield the ConcavePolygonShape3D, developers arm themselves with the capacity to create more intricate and interactive game environments. These shapes offer more than just visual aesthetics; they define how players and objects interact with the game world on a physical level. With proper understanding and application, you can ensure your game not only looks the part but plays the part, delivering a realistic and engaging experience to your audience. Understanding this tool opens the gates to crafting truly immersive 3D worlds, and with Godot’s accessible scripting and scene-building, it’s a skill within your reach. Let’s step forward and discover how you can incorporate ConcavePolygonShape3D into your game development toolkit.

CTA Small Image

Creating a ConcavePolygonShape3D in Godot

To begin working with ConcavePolygonShape3D, we first need to create it within our scene. Here’s how you can add a ConcavePolygonShape3D to a static body in Godot.

# First, create a StaticBody3D node
var body =
# Then, create a ConcavePolygonShape3D
var shape =
# Finally, add the shape to the static body

With a collision shape added, the next step is defining its faces. Unlike ConvexPolygonShape3D, the ConcavePolygonShape3D uses an array of planes (each plane being defined by a normal and a distance) to describe its surfaces.

# Assuming you have vertices for your shape, define the faces like this:
var faces = PoolVector3Array([Vector3(0, 0, 0), Vector3(1, 0, 0), Vector3(1, 1, 0), ...])
# Assign the faces to the shape
shape.faces = faces

Initializing Geometry for ConcavePolygonShape3D

Typically, you’d get the vertices for your concave shape from a Mesh instance, such as when exporting a model from a 3D modelling software. Here’s how you set up the ConcavePolygonShape3D using faces from a mesh:

# Load your mesh
var mesh = preload("res://path_to_your_mesh.tres")
# Get the array of faces
var faces = mesh.get_faces()
# Apply to your concave shape
shape.faces = faces

It is important to remember that this array should contain a sequence of points that form individual triangles, so the number of vertices must be a multiple of 3. These triangles will then define the collision boundaries of your object.

# Here, we arrange vertices in groups of three to form triangles
shape.faces = PoolVector3Array([Vector3(0, 0, 0), Vector3(1, 0, 0), Vector3(0, 1, 0),\
                                Vector3(1, 0, 0), Vector3(1, 1, 0), Vector3(0, 1, 0),\
                                ... # more triangles here

Configuring a ConcavePolygonShape3D for Terrain

ConcavePolygonShape3D shapes are ideal for creating more complex, non-moving terrain shapes. Let’s see a basic example of setting up such a terrain collision shape in Godot:

# Create a StaticBody3D for the terrain
var terrain_body =
# Create the shape
var terrain_shape =
# Assuming 'terrain_mesh' is a MeshInstance node with your terrain mesh
var terrain_mesh = $TerrainMesh
# Extract faces from the mesh and set them as the shape's geometry
terrain_shape.faces = terrain_mesh.mesh.get_faces()
# Add the shape to the terrain body
# Add the terrain body to the scene

This setup will allow your terrain to interact with the rest of the physics world, such as affecting player movement or interacting with other rigid bodies.

Optimization Tips for Using ConcavePolygonShape3D

ConcavePolygonShape3D can be quite demanding in terms of performance, especially for complex shapes. Therefore, it is important to keep the number of vertices as low as possible while maintaining the desired level of detail.

For instance, if your terrain has a flat area, you don’t need to have many vertices there. Simplify the mesh in areas that don’t contribute to the collision complexity to ensure better performance:

# Simplify your faces array by removing unnecessary vertices in flat areas
shape.faces = PoolVector3Array([Vector3(0, 0, 0), Vector3(10, 0, 0), Vector3(0, 0, 10),\
                                ... # fewer triangles in flat areas

Another practice is to split up your environment into several ConcavePolygonShape3Ds rather than one massive collision shape. This can help with collision detection performance as Godot can better optimize culling smaller collision segments compared to a single, large one.

# Splitting up a large environment into smaller segments
var segment1 =
segment1.faces = ... # Some part of the mesh

var segment2 =
segment2.faces = ... # Another part of the mesh

# And so on...

In our next section, we’ll look at how to effectively use ConcavePolygonShape3D in static and dynamic contexts and explore collision interactions.

Incorporating ConcavePolygonShape3D into your Godot projects requires understanding how it interacts with other physics bodies. For a static environment, like a terrain, you’re all set with the collision shape attached to a StaticBody3D. But what about dynamic objects, such as destructible terrain or movable structures? It’s crucial to use these shapes appropriately to maintain performance and game playability.

Leverage Godot’s native tools to monitor and optimize shape complexity during development. The Godot editor’s “Visible Collision Shapes” feature allows you to see collision shapes overlaid on your game during runtime, helping you fine-tune the physics interactions.

# Toggle the visibility of collision shapes in your debug settings or via code like this:

When dealing with movable objects, you’ll typically use RigidBody3D instead of StaticBody3D. Here’s how you might add a collision shape to a dynamic object:

var dynamic_body =
var dynamic_shape =
# ... initialization of your shape

However, it is important to note that dynamic bodies with ConcavePolygonShape3D can be more processor-intensive. Godot recommends using simplified collision shapes or compound shapes made of primitives for movable objects to achieve better performance.

For moving platforms or complex movable structures in your world, consider segmenting the model into parts with simpler collision primitives, such as boxes or cylinders, that fit the model’s general outline.

var moving_platform =
var box_shape =
box_shape.extents = Vector3(2, 0.5, 2)

Collision interactions can offer feedback to the player. For example, you might want to trigger an event when the player enters a particular area. This is where Area3D nodes come in. They can be combined with ConcavePolygonShape3D to detect such scenarios:

var area =
var area_shape =
# ... initialization of your shape

# Connect a signal to respond to bodies entering the area
area.connect("body_entered", self, "_on_body_entered")

func _on_body_entered(body):
    if == "Player":
        # Handle player entering the area, such as triggering a cutscene or dialogue

For an instance where you are implementing a destructible environment, you may want to create ConcavePolygonShape3D shapes at runtime. By splitting a larger object into smaller parts, you can simulate destruction by enabling and disabling collision shapes as needed.

# For a destructible wall
var wall =
var whole_shape =
# ... initialization of your whole shape

func destroy_wall():
    # Replace the whole shape with broken parts
    var broken_shape_part1 =
    var broken_shape_part2 =
    # ... initialize shapes for broken parts
    # Add logic to animate and disperse the parts

Remember, for destructible environments, performance can quickly degrade if too many complex shapes are used or if too many dynamic rigid bodies are created at once. Use pooling, limiting the number of active dynamic bodies, and opt for simpler collision primitives where appropriate.

Lastly, always test your physics interactions on various hardware to ensure they work smoothly across all platforms. Performance optimization is an ongoing process and will need to be adjusted as your project grows in complexity.

Through these examples, you can see that ConcavePolygonShape3D is a highly versatile tool for sculpting the interactive parts of your game world. Whether for complex static environment shapes or specialized dynamic objects, understanding and using this shape effectively can enrich the gameplay experience and bring a professional level of polish to your game environments.

Delving deeper into utilizing ConcavePolygonShape3D, let’s consider scenarios where optimizing collision detection can drastically improve the performance. For example, when we need to update collision shapes during runtime, such as a terrain that gets modified by player actions. Here’s how to update the ConcavePolygonShape3D dynamically:

var modifiable_terrain = $ModifiableTerrain
var new_faces = PoolVector3Array()
# ... populate 'new_faces' array with updated geometry

func update_terrain_collision():
    # Assume 'shape' is the ConcavePolygonShape3D you want to update
    modifiable_terrain.shape_owner_get_shape(shape_owner, 0).faces = new_faces

Additionally, within a densely populated scene, you might find it advantageous to activate and deactivate collision shapes based on the player’s proximity to improve performance:

func _process(delta):
    for static_body in get_children():
        if static_body.is_in_group("collidable"):
            var distance_to_player = static_body.global_transform.origin.distance_to(player.global_transform.origin)
            static_body.shape_owner_set_disabled(0, distance_to_player > MAX_COLLISION_DISTANCE)

While Godot allows you to set individual triangles for the ConcavePolygonShape3D, it’s also possible to feed entire arrays for faces at once, allowing for batch updates. This can come in handy when constructing complex objects:

var complex_structure_faces = PoolVector3Array([
    # Define triangles composing your complex structure
    # Triangle 1
    Vector3(0, 0, 0), Vector3(1, 0, 0), Vector3(0, 1, 0),
    # Triangle 2
    Vector3(1, 0, 0), Vector3(1, 1, 0), Vector3(0, 1, 0),
    # ... more triangles
complex_structure.shape.faces = complex_structure_faces

When interacting with other moving objects, it’s not always about rigid body collisions. Sometimes you’ll want to create triggers that activate certain actions or events when something enters or exits its space, without affecting the physics directly:

var trigger_area =
var area_shape =
# ... initialize your area_shape with the correct geometry, as previously shown
trigger_area.connect("body_entered", self, "_on_body_entered")

func _on_body_entered(body):
    # Handle logic for when a body enters the trigger

To further streamline scene creation with ConcavePolygonShape3D, you can script automated construction of collision shapes based on meshes, making level design more efficient. Below, we create a helper function that does just that:

func create_collision_shape_from_mesh(mesh_instance):
    var shape =
    shape.faces = mesh_instance.mesh.get_faces()
    var static_body =

# To use the helper function:
var your_mesh_instance = preload("res://path_to_your_mesh_instance.tscn").instance()

If you’re implementing fragmentable objects, pre-creating individual fragments with their own ConcavePolygonShape3D might be beneficial. When the object breaks, swap the intact shape for the fragments:

var intact_shape =
# ... initialize the intact shape
var fragment_shape1 =
# ... initialize fragment shapes
var fragment_shape2 =

# Logics to swap the intact shape with fragment shapes
func break_object():
    # ... Additional logic to make the fragments behave as desired

The flexibility of updating and manipulating ConcavePolygonShape3D ensures that your game can contain a dynamic, responsive environment that lends itself to a highly interactive experience for the player. Careful consideration of performance implications, thoughtful use of helper functions, and strategic shape manipulation will allow you to build worlds with rich collision detection and physics interactions.

Furthering Your Game Development Journey with Godot

You’ve unleashed the foundations of working with ConcavePolygonShape3D in Godot, and the path to mastery is one of continual learning and practice. If you’re eager to broaden your skills further and delve deeper into the universe of Godot game development, our Godot Game Development Mini-Degree is the perfect next step. This comprehensive collection of courses is designed with both beginners and advanced developers in mind, covering a rich array of topics from 2D and 3D asset creation to complex game mechanics across various genres. Best of all, you can learn at your own pace, anytime, anywhere, with interactive lessons that ensure you’re able to apply your newfound knowledge to your personal projects.

For those who seek even broader horizons, Zenva’s full library of Godot tutorials provides an extensive assortment of learning materials to elevate your game development abilities. Whether you’re just starting out, sharpening your existing skills, or exploring new possibilities, our Godot courses offer the perfect platform to grow your expertise. Dive into this exciting, ever-evolving field, create captivating gaming experiences, and join the ranks of professional game developers who started their journey with Zenva.

Your creativity is boundless, and the tools to bring your vision to life are within reach. Continue building, continue learning, and turn your passion for game development into reality with Zenva.


In the realm of game development, mastering the intricacies of collision shapes like ConcavePolygonShape3D is a testament to your dedication to craft immersive worlds. From the rolling hills of terrains to the labyrinthine corridors of ancient ruins, you possess the ability to breathe life into your imagination. We at Zenva are thrilled to be part of your journey, providing you with the knowledge and tools to translate your visions into interactive realities. Remember, every great game begins with the first line of code, and with our Godot Game Development Mini-Degree, that first line is already within your reach.

Let your creativity soar and your games captivate. With the insights gleaned from our expert-curated courses, you’re well on your way to becoming a game development maestro. Embrace the challenge, enjoy the process, and continue to forge unforgettable experiences for players around the world. The future of gaming is in your hands, so let’s make it extraordinary. Embark on your next quest with us at Zenva, where your game development adventure awaits. Click here to start!

Python Blog Image

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