CharacterBody2D in Godot – Complete Guide

When venturing into the world of game development, one of the most thrilling moments is bringing characters to life. Imagine you’ve just sketched out a quirky protagonist with a penchant for hopping across fantastical platforms. You’re ready to see this character scurry and leap within your very own creation. To do this, you need to breathe physics into them, allowing their interaction with the world to be as authentic and engaging as their design. Enter the realm of Godot’s CharacterBody2D—a tool designed to effortlessly animate your characters within a 2D space.

What is CharacterBody2D?

CharacterBody2D is a class in Godot Engine, specifically tailored for 2D game development. It’s a Godot node that serves as a physics body, which is explicitly meant for characters that are controlled by scripts or user input. Unlike other physics bodies that fully obey the laws of physics, CharacterBody2D provides both control and interaction, enabling characters to move with finesse and react to the environment authentically.

What is it for?

The role of CharacterBody2D is foundational to creating dynamic and responsive gameplay. It facilitates complex movements such as running, jumping, and interacting with various surfaces. This class uses robust methods like move_and_slide for motion with built-in slope and wall detection. For those creating platformers, side scrollers, or any game where character movement is crucial, CharacterBody2D is the go-to resource.

Why Should I Learn It?

Learning how to use CharacterBody2D in Godot not only broadens your game development skills but also empowers you to create more polished and fun experiences for players. It enables your game characters to move organically and interact with their surroundings realistically, which enhances the overall quality and engagement of your game. Moreover, understanding CharacterBody2D opens the door to effectively using Godot’s physics engine, a skill that is highly valuable in the game development community.

CTA Small Image

Setting Up CharacterBody2D

To start implementing CharacterBody2D in your game, you first need to create the node within your scene. Here’s how you can add it to your character:

var character =

After creating the CharacterBody2D node, you’ll typically want to configure its properties to fit your game’s requirements. Let’s set the gravity scale and maximum slide count, which are important for movement and collision detection:

character.gravity_scale = 1.0 
character.max_slides = 4

Assigning a collision shape is essential for detection and interaction within the game world. Here’s an example of attaching a ‘CollisionShape2D’ node with a ‘RectangleShape2D’ as its shape:

var collision_shape =
collision_shape.shape =
collision_shape.shape.extents = Vector2(10, 20)

Handling Movement with CharacterBody2D

Now let’s move on to controlling the character. We’re going to create a simple script to enable movement based on player input. Attach a script to the CharacterBody2D node and add the following code for a simple left and right movement:

extends CharacterBody2D

const SPEED = 200

func _physics_process(delta):
    var motion = Vector2()
    if Input.is_action_pressed("ui_right"):
        motion.x = SPEED
    elif Input.is_action_pressed("ui_left"):
        motion.x = -SPEED

Remember to set up the input actions ‘ui_right’ and ‘ui_left’ in the Godot project settings if you haven’t done so yet. Additionally, let’s enable the character to jump:

extends CharacterBody2D

const SPEED = 200
const JUMP_FORCE = -600
var on_ground = false

func _physics_process(delta):
    var motion = Vector2()
    if Input.is_action_pressed("ui_right"):
        motion.x = SPEED
    elif Input.is_action_pressed("ui_left"):
        motion.x = -SPEED
    motion = move_and_slide(motion, Vector2.UP)
    on_ground = is_on_floor()

    if on_ground and Input.is_action_just_pressed("ui_up"):
        motion.y = JUMP_FORCE
        motion = move_and_slide(motion, Vector2.UP)

‘move_and_slide’ automatically calculates the character’s motion, applying gravity and handling floor detection. By checking if we are ‘on_ground’ using the ‘is_on_floor()’ method, we can determine if the character is capable of jumping.

Adding Slope and Wall Interaction

Godot’s CharacterBody2D is excellent for handling slopes and walls with ease. Modify your movement logic to react suitably when encountering slopes:

extends CharacterBody2D

const SPEED = 200
const JUMP_FORCE = -600
var on_ground = false

func _physics_process(delta):
    var motion = Vector2()
    # Existing movement code here

    # Slope slide modification
    if on_ground and motion.x != 0:
        move_and_slide_with_snap(motion, Vector2.DOWN, Vector2.UP, true)
        motion = move_and_slide(motion, Vector2.UP)

Using ‘move_and_slide_with_snap’ allows the character to stick to the ground when moving along slopes. The snapping vector ‘Vector2.DOWN’ ensures that the character maintains contact with the slope.

Finally, to prevent characters from sticking to walls when jumping, we use ‘stop_on_slope’ as true:

character.move_and_slide(motion, Vector2.UP, true)

A combination of ‘stop_on_slope’, ‘snap’, and other CharacterBody2D properties provides a comprehensive set of tools for creating robust and responsive movement in our 2D games.

In the next part, we’ll explore more advanced features of the CharacterBody2D node, like handling collisions, detecting edges, and more refined control over character physics.

Delving deeper into CharacterBody2D functionality in Godot, we can find numerous features that enable our 2D characters to behave in complex ways. Let’s explore how to handle collisions, detect edges, and exert more refined control over character physics.

Handling collisions is crucial for character interactions with the game world. You can use ‘get_slide_collision()’ to get information about what the character is colliding with:

# Inside _physics_process function after move_and_slide
for i in range(get_slide_count()):
    var collision = get_slide_collision(i)
    # Use collision information here 
    # e.g., if collision.collider is an Enemy, character takes damage

Now suppose we want our character to detect edges and prevent it from walking off platforms. By using raycasting, we can achieve this:

# Add a RayCast2D node as a child of CharacterBody2D in the editor or via code
var raycast =
raycast.cast_to = Vector2(0, 10)
raycast.enabled = true

# Inside your _physics_process function, check if the RayCast2D is colliding
if on_ground and !raycast.is_colliding():
    # Stop the character from moving forward, we're at an edge!

Let’s look at how to implement a dash mechanic that lets our character move quickly in a direction for a short period. This requires us to manipulate velocities directly:

extends CharacterBody2D

var dash_speed = 1000
var dashing = false

func _physics_process(delta):
    var motion = Vector2()
    # Existing movement and jumping code here

    # Start dashing
    if Input.is_action_just_pressed("ui_select") and on_ground:
        dashing = true
        motion.x = dash_speed * sign(motion.x)  # Dash in the direction of movement

    # Perform the dash
    if dashing:
        motion = move_and_slide(motion, Vector2.UP)
        # Stop dashing after a short time or condition here 
        # e.g., when a certain duration has passed or the character collides with something

For making the character climb ladders or move on vertical platforms, we can use a similar approach to jumping, but without the jump force:

extends CharacterBody2D

const LADDER_SPEED = 100

func _physics_process(delta):
    var motion = Vector2()
    # Existing movement code here

    # Climbing logic
    if is_on_ladder():  # is_on_ladder is a function you would define to check ladder collisions
        if Input.is_action_pressed("ui_up"):
            motion.y = -LADDER_SPEED
        elif Input.is_action_pressed("ui_down"):
            motion.y = LADDER_SPEED
        move_and_slide_with_snap(motion, Vector2.ZERO, Vector2.UP)

Character animation synchronization with movement can enhance the gaming experience. Here’s a simple example of how to integrate animation with movement:

extends CharacterBody2D

onready var animation_player = $AnimationPlayer

func _physics_process(delta):
    var motion = Vector2()
    # Existing movement code here

    # Animation logic
    if motion.x > 0:"walk_right")
    elif motion.x < 0:"walk_left")
    elif on_ground:"idle")

We’ve covered just a snippet of what CharacterBody2D can do. There’s still more to explore, like applying knockback effects, integrating more robust damage systems, and much more. Remember, the secret sauce of any great game character lies in the details. Fine-tune these physics properties, polish your collision handling, and synchronize those animations to bring your visions to life in the Godot engine.

At Zenva, we understand the intricacies of game development and aim to provide you with the tools and knowledge to turn your creative concepts into reality. Keep experimenting, keep learning, and watch your digital dreams play out on the screen.

With a basic understanding of how CharacterBody2D can handle movement, collisions, and animations, we’ll now delve deeper into other functionalities. Game development often requires custom mechanics to distinguish your game – Godot’s CharacterBody2D is flexible enough to accommodate such intricacies.

For instance, let’s make the character able to push objects. We’ll check for collisions with objects that can be pushed and apply a force to them:

extends CharacterBody2D

func _physics_process(delta):
    var motion = Vector2(200, 0)  # Example motion to the right
    motion = move_and_slide(motion)

    for i in range(get_slide_count()):
        var collision = get_slide_collision(i)
        if collision.collider.has_method("push"):
            collision.collider.push(motion.normalized() * 50)  # Push the object with a force

Next, let’s implement a knockback effect. When the character takes damage, we can make them move involuntarily in the opposite direction:

extends CharacterBody2D

var is_knockbacked = false
var knockback_velocity = Vector2()

func take_damage(damage_source_position):
    is_knockbacked = true
    knockback_velocity = (global_position - damage_source_position).normalized() * 300
    # The character will now be in knockback state

func _physics_process(delta):
    if is_knockbacked:
        knockback_velocity = move_and_slide(knockback_velocity, Vector2.UP)
        # Reduce the knockback over time
        knockback_velocity = knockback_velocity.linear_interpolate(Vector2.ZERO, 0.1)
        if knockback_velocity.length() < 10:
            is_knockbacked = false  # End knockback when the velocity is low enough

In a game involving equipped items or power-ups, adjusting the character’s properties dynamically is pivotal. Here’s how to increase jump force when a power-up is collected:

extends CharacterBody2D

var jump_force = -600

func collect_powerup(powerup):
    if powerup.type == "jump_boost":
        jump_force -= 200  # Increase the jump force
        # Remember to reset this value when the power-up's effect expires

Let’s go even further and create a grappling hook mechanic, where the character can swing from certain points:

extends CharacterBody2D

var grappling = false
var grapple_point = Vector2()
var grapple_distance = 0

func _physics_process(delta):
    var motion = Vector2()
    # Existing movement code here
    # Grappling logic
    if grappling:
        motion += (grapple_point - global_position).normalized() * 10
        if global_position.distance_to(grapple_point) > grapple_distance:
            motion = global_position.direction_to(grapple_point) * 100

Sometimes, we want our character to interact with switches or buttons that activate in-game mechanisms. Here’s how to handle interaction with such objects:

extends CharacterBody2D

func _physics_process(delta):
    if Input.is_action_just_pressed("ui_accept"):
        var interaction_ray =
        interaction_ray.cast_to = Vector2(50, 0)  # Cast the ray to the right
        interaction_ray.enabled = true

        if interaction_ray.is_colliding():
            var collider = interaction_ray.get_collider()
            if collider.has_method("activate"):
                collider.activate()  # Call the activate method on the collider

Following this approach, always keep in mind that methods like ‘activate’, ‘push’, or ‘take_damage’ are not built into Godot. You would need to define these methods within the interactable objects in your game.

These examples showcase the depth and versatility of the CharacterBody2D node in Godot. With these tools, you’re well on your way to creating a character that can engage with the game world in a multitude of interesting ways. Code samples like these are what you can expect to learn and implement with our courses at Zenva, where we pride ourselves on teaching the most up-to-date and in-demand skills in tech and game development. Keep tweaking these systems and you’ll see that the only limit to what you can create is your imagination.

Continuing Your Game Development Journey

Mastering Godot’s CharacterBody2D is just the beginning of your game development journey. The next steps are critical – it’s time to refine your skills, challenge your understanding, and build a portfolio of impressive games. To help you on this path, we at Zenva encourage you to explore our Godot Game Development Mini-Degree, a meticulously crafted series of courses that cover a broad range of Godot 4 capabilities.

Our Mini-Degree starts from the basics and scales up to advanced topics, ensuring a comprehensive understanding of game development within the Godot engine. You’ll tackle concepts like 2D and 3D art, GDScript, gameplay mechanics, combat systems, and much more. Designed for both beginners and experienced devs, the courses fit comfortably with your pace and schedule, enhanced by quizzes and coding challenges to cement your knowledge. Whether you’re aiming to hobbyist creativity or professional aspiration, these courses are a stepping stone to success.

If you’re looking to expand your horizons within Godot further or to focus on specific areas, check out our broader selection of Godot courses. Together, we can turn your game development aspirations into reality, one frame at a time.


By diving into the mechanics of CharacterBody2D in Godot and exploring the endless possibilities of gameplay you can create, you’re building a foundation for game development that can lead to thrilling and engaging experiences for players around the world. Don’t let the momentum stop here! Zenva’s Godot Game Development Mini-Degree awaits to take your skills to new heights—further, faster, and more fun than doing it on your own.

Join our community of learners, where each line of code gets you closer to becoming the game developer you aspire to be. Let’s keep the game development journey going – bring your ideas to life, share your creations, and be part of the new wave of innovative game developers making an impact in the digital world. Your adventure is just beginning, and we’re excited to see where it takes you!

Python Blog Image

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