CapsuleShape3D in Godot – Complete Guide

Welcome to a journey through the use of the CapsuleShape3D class in the Godot 4 game engine. As you delve into this tutorial, you will find yourself equipped with the tools and knowledge necessary to implement collisions that are both effective and performant in your 3D games. The CapsuleShape3D is an essential tool for game developers, and understanding its functionalities can greatly enhance the realism and interactivity of your game environments. So whether you’re starting out or refining your skills, this overview is your launchpad to mastering this class in Godot 4 and advancing your game development expertise.

What is CapsuleShape3D?

CapsuleShape3D is a type of Shape3D in Godot intended primarily for physics collision detection. This 3D shape is structured like a capsule – think of it like a pill or a shortened cylinder with hemispherical ends. In the context of game physics, it’s generally used alongside a CollisionShape3D node to provide a collision boundary for character controllers or other dynamic objects.

What is it Used For?

In game development, collision shapes are paramount for detecting and responding to physical interactions between objects. CapsuleShape3D can serve as an ideal collision boundary for many entities, particularly character models – its rounded ends permit smoother movement and less snagging on the environment compared to boxier shapes. Developers favor it for player characters, NPCs, or any object that demands a refined collision response when interacting with the world.

Why Should I Learn It?

Understanding how to implement and utilize CapsuleShape3D is beneficial for a few reasons:

– **Performance**: Capsule shapes are fast for collision detection, striking a balance between computational efficiency and form-fitting collision boundaries.
– **Utility**: Capsule shapes are incredibly versatile, suitable for a broad range of entities within your game.
– **Control**: By mastering CapsuleShape3D, you gain more control over the physics of your game, allowing you to fine-tune the interaction experience.

Taking the time to understand how to effectively use CapsuleShape3D shapes will undoubtedly enhance your game’s physics and character interactions, making your projects feel more polished and professional.

CTA Small Image

Creating a CapsuleShape3D in Godot

Let’s begin by creating our very first CapsuleShape3D. This usually starts by attaching a CollisionShape3D node to your character or object.

var collision_shape =
var capsule_shape =
collision_shape.shape = capsule_shape

This snippet creates a new CollisionShape3D instance, then creates a CapsuleShape3D and assigns it to the collision shape’s shape property. Lastly, it adds the collision shape as a child to the node you want to have collision detection.

Configuring the CapsuleShape3D Properties

After you have your basic shape attached, you may want to configure its properties like radius and height to better fit your character’s dimensions. Here’s how you could do it:

capsule_shape.radius = 0.5
capsule_shape.height = 2.0

This will set the radius of the capsule’s cylindrical part to 0.5 units and the total height of the capsule to 2 units. Remember that the height is the distance between the centers of the spherical caps, not including the caps themselves.

To further facilitate character movement and to provide a better fit for a typical humanoid shape, we may want to adjust the capsule to be vertical. By default, the capsule is vertical, but if ever needed, you can change the orientation like this:

# Assuming 'capsule_shape' is your CapsuleShape3D instance
capsule_shape.set_axis(1) # 0 for X, 1 for Y, 2 for Z

Using CapsuleShape3D with KinematicBody3D or Rigidbody3D

CapsuleShape3D shapes are usually used with KinematicBody3D for character controllers or Rigidbody3D for physics-based objects.

Here’s an example of how to set it up with a KinematicBody3D:

var player_body =

For a Rigidbody3D setup, the process is similar, but you may want to also adjust the mass, friction, and bounce parameters.

var rigid_body =
rigid_body.mass = 10
rigid_body.friction = 1.0
rigid_body.bounce = 0.1

In both cases, `collision_shape` refers to the CollisionShape3D node that contains your CapsuleShape3D. Adding it as a child to a body effectively attaches the collision shape to that body.When it comes to creating interactive 3D environments with smooth character movements, collision detection is crucial. The CapsuleShape3D is an excellent choice for player characters, but we can also use it for non-player characters and other dynamic entities within the game.

# Create a CapsuleShape3D for an NPC's collision body
var npc_body =
var npc_collision_shape =
var npc_capsule_shape =

npc_capsule_shape.radius = 0.4
npc_capsule_shape.height = 1.8

npc_collision_shape.shape = npc_capsule_shape

In this example, the NPC has its own collision shape, and just like a player character, it’s configured to have relevant dimensions.

In many situations, you might want to move or rotate your collision shape within a parent body to better align with the 3D model. Here’s how we can offset a CapsuleShape3D within a KinematicBody3D:

# Offset the capsule shape to align with the character's geometry
npc_collision_shape.translation = Vector3(0, 1, 0)

Adjusting the collision shape’s translation property allows for precise alignment with the character model, so the collision detection behaves as expected.

Moreover, if you want to animate the properties of CapsuleShape3D during gameplay, like adjusting the radius during a character’s action, you can do this:

# Animate the capsule's radius for a character's action
var anim_player =
var animation =
animation.set_length(1.0) # Set the animation's length to 1 second

# Animate the radius increase
animation.track_insert_key(0, 0, 0.5) # Start from radius 0.5
animation.track_insert_key(0, 1, 0.7) # Increase to radius 0.7 over 1 second

anim_player.add_animation("Expand", animation)"Expand")

This animation could correspond to a character puffing up as part of a defense mechanism, illustrating the dynamic capabilities of the CapsuleShape3D.

When debugging or fine-tuning collisions, you may want to visualize the collision shapes. In Godot, you can easily toggle the visibility of collision shapes during runtime:

# Toggle the visibility of collision shapes during runtime
if Input.is_action_pressed("ui_debug"):

This snippet checks if a debug input action (like a keyboard key press) is triggered and toggles the visibility of collision shapes accordingly.

Lastly, it’s crucial to clean up and remove collision shapes if they’re no longer needed, for example, when an object is removed from the scene:

# Remove the collision shape from the scene
if object_should_be_removed:

By removing the collision shape and calling `queue_free()`, you make sure that the resources used by the collision shape are released, preventing memory leaks or unnecessary calculations for non-existent objects.When we’re working with CapsuleShape3D in our games, we often have to handle collisions and interactions between different game objects. This requires not just setting up the shape, but also scripting the behavior that ensues when different objects come into contact.

Let’s look at some scenarios where we interact with the CapsuleShape3D through code:

For instance, if you’re using a KinematicBody3D, you’ll be often using the `move_and_slide` or `move_and_collide` methods. Here’s an example of handling simple collisions:

# Handle simple collisions with move_and_slide
func _physics_process(delta):
    var velocity = Vector3(0, -9.8, 0) # Apply gravity
    velocity = move_and_slide(velocity, Vector3.UP)

In scenarios where you need to know more about the collisions, like which object you’ve collided with, you can retrieve this information from the returned KinematicCollision3D object:

# Retrieve collision information
func _physics_process(delta):
    var velocity = Vector3(0, -9.8, 0)
    var collision = move_and_collide(velocity)
    if collision != null:
        print("Collided with: ",

On the chance that you’re working with Rigidbody3D instead of KinematicBody3D, you would handle collisions using Godot’s signals system. For example:

# Connect the 'body_entered' signal for Rigidbody3D in the editor
# or through code like this:
func _ready():
    $CollisionShape3D.connect("body_entered", self, "_on_body_entered")

func _on_body_entered(body):
    print("Rigidbody has collided with: ",

The `body_entered` signal is emitted when another body enters the collision shape. By connecting this signal to a method, we can handle the event and access the body that entered the collision shape.

Handling changes in collision shapes during runtime can be important for gameplay mechanics such as characters that can shrink or grow. Here’s how you’d program a character to grow temporarily, affecting the capsule collision shape:

# Temporarily increase a capsule collision shape's size
func grow_character(temporary: bool = true, reset_time: float = 5.0):
    npc_capsule_shape.height = 3.0
    npc_capsule_shape.radius = 0.6
    if temporary:
        # Set a timer to reset the dimensions
        var reset_timer =
        reset_timer.one_shot = true
        reset_timer.wait_time = reset_time
        reset_timer.connect("timeout", self, "_reset_capsule_size")

func _reset_capsule_size():
    npc_capsule_shape.height = 1.8
    npc_capsule_shape.radius = 0.4

In this example, a character grows for a temporary period of time and then reverts back to its original size thanks to the timed callback `_reset_capsule_size`.

If you’re looking to enable and disable collisions under certain conditions – for instance, if a character has a ‘ghost’ mode where it can pass through walls – you can handle this through the collision layer and mask:

# Enable and disable collisions through layers and masks
func toggle_ghost_mode(enable: bool):
    if enable:
        collision_shape.set_collision_layer_bit(1, false) # Disable collisions in layer 1
        collision_shape.set_collision_mask_bit(1, false) # Disable detection in layer 1
        collision_shape.set_collision_layer_bit(1, true) # Re-enable collisions
        collision_shape.set_collision_mask_bit(1, true) # Re-enable detection

Manipulating the collision layers and masks dynamically can give you fine-grained control over how and when objects collide.

Finally, if your CapsuleShape3D is to be interacted with only under certain conditions – like a character able to activate a machine only when powered up – you can use conditional checks:

# Example of conditional collision handling
func _on_body_entered(body):
    if body.has_method("apply_power_up") and body.is_powered_up:
        print("Power-up applied to: ",
        # Apply specific interaction logic here

With the `has_method` and a custom property check, you can ensure that your collisions not only detect contact but also interact in context-sensitive ways. This adds depth to how players experience your game and the actions that occur within it.

Continue Your Game Development Journey

Now that you’ve gotten a taste of how to utilize CapsuleShape3D in Godot Engine, don’t let the momentum stop here! Dive deeper into game development with our comprehensive Godot Game Development Mini-Degree, where you can build a strong foundation and advance your skills in creating cross-platform games. Explore topics ranging from 2D and 3D game mechanics to GDScript, and work on real projects that will showcase your growing expertise.

Whether you’re starting out or expanding your knowledge, Zenva Academy offers a treasure trove of learning opportunities. You can easily access over 250 courses tailored to boost your career in programming and game development. And for a broader exploration, check out our full selection of Godot courses, crafted to guide you step by step, from beginner to professional. Transform your passion into a portfolio with Zenva, and unlock new possibilities in the world of game development.


Mastering the CapsuleShape3D in Godot Engine is more than just a step in game development—it’s a leap towards creating more dynamic, realistic, and engaging games. With the knowledge you’ve gained today, you’re well on your way to building the immersive experiences that players crave. Remember that every new skill you add opens the door to a realm of possibilities in your game creation journey.

Are you eager to keep learning and developing your game programmer toolkit? Join us at Zenva Academy and let’s turn your dreams into a reality. Take the next step with our Godot Game Development Mini-Degree, where you’ll find yourself in a vibrant community of creators, armed with the resources to bring your most imaginative game ideas to life!

Python Blog Image

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