CollisionShape3D in Godot – Complete Guide

Collision detection is a fundamental aspect of many video games and simulations, particularly when it comes to creating a convincing 3D environment. In Godot Engine, one of the essential classes for handling collisions in 3D space is CollisionShape3D. Understanding how CollisionShape3D works can be the difference between a good and a great game experience. In this tutorial, we will explore the capabilities of CollisionShape3D, imparting you with the knowledge to fully utilize its potential in your Godot 4 projects.

What is CollisionShape3D?

CollisionShape3D is a node in the Godot Engine that allows you to define the shape of an object that can detect and respond to collisions within a 3D space. This class is typically used as a child of a CollisionObject3D, which includes Area3D and PhysicsBody3D nodes.

What is it for?

CollisionShape3D is essential for:

– Defining the interaction boundary of a 3D object.
– Providing detection shapes for areas that can trigger events.
– Enabling physics objects to collide and react to other objects.

If you’re developing a game or a simulation in a 3D environment, making use of CollisionShape3D can add that extra layer of interactivity and realism.

Why Should I Learn It?

Learning how to use CollisionShape3D will:

– Empower you to create more dynamic and responsive game worlds.
– Enable you to implement complex 3D collision detection without being overwhelmed.
– Provide you with a deeper understanding of 3D physics in game development.

Whether you’re just starting your game development journey or you’re looking to brush up on the latest techniques in Godot 4, mastering CollisionShape3D is a step towards building more engaging 3D games. Let’s get started on this adventure together, and unlock the powerful capabilities of the CollisionShape3D class.

CTA Small Image

Setting Up CollisionShape3D

To start utilizing CollisionShape3D in your Godot 4 projects, you need to follow a few steps to set it up correctly. First, you must ensure that your CollisionShape3D is a child node of an object that can make use of it, such as a PhysicsBody3D or an Area3D.

var body =
var collision_shape =

Once the CollisionShape3D is a child of the appropriate parent node, you need to define the shape. Godot provides numerous shape types, ranging from primitive shapes like spheres and boxes to more complex shapes such as convex and concave polygons.

Adding a simple box shape:

var shape =
shape.extents = Vector3(1, 1, 1)
collision_shape.shape = shape

For a sphere shape:

var shape =
shape.radius = 1.0
collision_shape.shape = shape

Positioning and Rotating the CollisionShape3D

Collision shapes often need to be accurately positioned and rotated within their parent’s local space. It’s important that the shape aligns correctly with the visible geometry of your object.

Adjusting the position of the CollisionShape3D:

collision_shape.transform = Transform3D().translated(Vector3(0, 1, 0))

Rotating the CollisionShape3D:

collision_shape.transform = Transform3D().rotated(Vector3(0, 1, 0), PI / 2)

Using CollisionShape3D with Static Bodies

StaticBody3D nodes are static in the world and do not move under simulation; they’re great for the environment or non-movable objects. Here’s how to create a floor with a StaticBody3D and attach a CollisionShape3D to it:

var static_body = = "Floor"
var floor_shape =
var shape =
shape.extents = Vector3(10, 1, 10) # size of the floor
floor_shape.shape = shape

Interacting with Area3D via CollisionShape3D

Area3D nodes provide detection areas that can trigger events. For example, you might want a certain area to trigger a game event when the player enters it. Here’s a simple code snippet on how to set this up:

var area =
var area_shape =
var shape =
shape.radius = 5.0
area_shape.shape = shape

# Connect the 'body_entered' signal to trigger an event
area.connect("body_entered", self, "_on_body_entered")

These examples cover the basics of setting up and positioning CollisionShape3D objects within the scene tree. You’re now ready to begin creating interactive and physically-driven game elements in your Godot 4 projects.Sometimes you’ll want to change the collision shape at runtime, especially if you’re dealing with objects that can transform or need to update their physical representation. Here’s how you can do that:

Change shape at runtime:

var new_shape =
new_shape.radius = 2.0
new_shape.height = 5.0
collision_shape.shape = new_shape

To ensure the collision detection is always as expected, it is essential to monitor and update the disabled property appropriately. If for some instance a shape should not be active in collision detection, you can disable it with:

Disable a collision shape:

collision_shape.disabled = true

Re-enable the shape later:

collision_shape.disabled = false

Checking for collisions can be performed in various ways. If the CollisionShape3D is a child of an Area3D, you can detect bodies entering the area:

Detect bodies entering an Area3D:

func _on_body_entered(body: Node):
    print("A body entered: ",

Moving objects that interact with the game world is a key component in game mechanics. With PhysicsBody3D, incorporating CollisionShape3D with a physical presence, you can apply forces, impulses, or direct movement commands:

Apply a force to a RigidBody3D:

func _apply_force(force_vector: Vector3):

Here is an impulse example, applying an instant force affecting the object’s velocity:

Apply an impulse to a RigidBody3D:

func _apply_impulse(impulse_vector: Vector3, position: Vector3):
    rigid_body.apply_impulse(position, impulse_vector)

Lastly, setting the collision layer and mask is vital for managing which objects will interact with each other. Collision layers define what layer the object is in, while the collision mask specifies which layers this object can collide with:

Set the collision layer for an object:

collision_object.collision_layer = 1 << 2 # Adds the object to layer 2

Set the collision mask to detect collisions with objects in certain layers:

collision_object.collision_mask = 1 << 2 # Will only collide with objects in layer 2

These examples demonstrate some of the fundamental ways CollisionShape3D can be controlled programmatically. With these techniques, you can create a fully dynamic and interactive 3D environment in your Godot Engine projects.In more advanced gameplay scenarios, you might need to adjust collision shapes in response to events. For example, if an object changes form, like a character switching between different states, the collision shape must also update to match the new form. Here’s an example of how to replace the collision shape in response to an in-game event:

Responding to a state change:

func _on_state_change(new_state):
    match new_state:
            collision_shape.shape =
            collision_shape.shape.extents = Vector3(1, 1, 1)
            collision_shape.shape =
            collision_shape.shape.radius = 1.0

Detecting when objects leave an Area3D is just as important as detecting when they enter. This might be used to determine when a player leaves a safe zone or exits the boundaries of the game world:

Detect bodies exiting an Area3D:

func _on_body_exited(body: Node):
    print("A body exited: ",

Sometimes, you might want only certain types of objects to trigger the collision event. With Godot, you can use groups to categorize objects and then check the group during the signal callback:

Detect only specific bodies in an Area3D:

func _on_body_entered(body: Node):
    if body.is_in_group("enemies"):
        print("An enemy entered: ",

Imagine a scenario where a player can pick up and move objects. In such a case, you will need to update the collision shapes to follow the picked objects:

Moving collision shapes with objects:

func _on_object_picked_up(picked_object: Spatial):
    collision_shape.global_transform = picked_object.global_transform

Collisions are not just for physical interactions; they can also be used to detect points of interest in the game for quests or triggering dialogue:

Detecting an object for a quest or interaction:

func _on_quest_item_area_entered(area: Area3D):
    if area.is_in_group("quest_items"):
        print("Quest item found: ", area.get_parent().name)

Raycasting is another powerful feature that can be used for line-of-sight checks, shooting mechanics, or interaction with objects at a distance. Here’s how you could detect hits using a raycast in 3D:

Performing a raycast:

var space_state = get_world_3d().direct_space_state
var result = space_state.intersect_ray(ray_origin, ray_end)

if result:
    print("Ray collided with: ",

Using the collision system in Godot is not limited to just detecting when things bump into each other. You can query the system at any time to get information about the objects in the 3D space:

Find all objects in a certain area:

var overlapping_bodies = area.get_overlapping_bodies()
for body in overlapping_bodies:
    print("Overlapping body: ",

These code snippets demonstrate a variety of ways that CollisionShape3D can be manipulated and queried to respond to runtime events and build sophisticated gameplay mechanics and interactions.

Where to Go Next in Your Godot Journey

Embarking on a journey with Godot can be truly eye-opening, presenting you with the tools and capabilities to bring your game development ideas to life. As you continue navigating through the intricacies of Godot 4 and CollisionShape3D, we at Zenva encourage you to keep pushing the boundaries of your knowledge and skills.

Our Godot Game Development Mini-Degree is a prime resource to help you delve deeper into game design and development. Whether you’re a newcomer or already have some experience, this comprehensive suite of courses can elevate you from basic concepts all the way through to creating your complex, cross-platform games. With a focus on hands-on learning, our curriculum is designed to guide you through the nuances of Godot’s powerful features, from GDScript to multiplayer systems, ensuring that each step of your educational journey reinforces your ability to build engaging games.

If you’re eager for even more Godot content, explore our broader collection of courses on the Zenva Academy platform. We’ve meticulously curated a range of materials to suit all learners – from the basics of 2D and 3D game development to advanced topics. You can find all of our Godot courses here. CGPointMake the most of the skills you accumulate and pursue your passion for game development with Zenva – where learning meets practical experience in a world that knows no bounds.


Understanding CollisionShape3D is a game-changer. It’s the key to making your virtual worlds feel tangible and your gameplay delightfully interactive. As you’ve seen, whether you’re manipulating shapes, responding to events, or engineering complex physics interactions, Godot 4’s powerful collision system can handle it all. With this knowledge secured, you can confidently design environments and mechanics that truly respond to your players’ actions.

Remember, what we’ve covered today is just the beginning. Embrace the adventure ahead by deepening your expertise with our Godot Game Development Mini-Degree. Create the games you’ve always wanted to play, and let your imagination run wild with the endless possibilities that Godot’s CollisionShape3D opens up for you. Join us at Zenva, and together, let’s craft experiences that gamers around the world will cherish.

Python Blog Image

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