Up to date
This page is up to date for Godot
If you still find outdated information, please open an issue.
Godot offers several collision objects to provide both collision detection and response. Trying to decide which one to use for your project can be confusing. You can avoid problems and simplify development if you understand how each of them works and what their pros and cons are. In this tutorial, we'll look at the CharacterBody2D node and show some examples of how to use it.
While this document uses
CharacterBody2D in its examples, the same
concepts apply in 3D as well.
What is a character body?¶
CharacterBody2D is for implementing bodies that are controlled via code.
Character bodies detect collisions with other bodies when moving, but are not affected by
engine physics properties, like gravity or friction. While this means that you
have to write some code to create their behavior, it also means you have more
precise control over how they move and react.
This document assumes you're familiar with Godot's various physics bodies. Please read Physics introduction first, for an overview of the physics options.
A CharacterBody2D can be affected by gravity and other forces, but you must calculate the movement in code. The physics engine will not move a CharacterBody2D.
Movement and collision¶
When moving a
CharacterBody2D, you should not set its
directly. Instead, you use the
These methods move the body along a given vector and detect collisions.
You should handle physics body movement in the
The two movement methods serve different purposes, and later in this tutorial, you'll see examples of how they work.
This method takes one required parameter: a Vector2 indicating
the body's relative movement. Typically, this is your velocity vector multiplied by the
frame timestep (
delta). If the engine detects a collision anywhere along
this vector, the body will immediately stop moving. If this happens, the
method will return a KinematicCollision2D object.
KinematicCollision2D is an object containing data about the collision
and the colliding object. Using this data, you can calculate your collision
move_and_collide is most useful when you just want to move the body and
detect collision, but don't need any automatic collision response. For example,
if you need a bullet that ricochets off a wall, you can directly change the angle
of the velocity when you detect a collision. See below for an example.
move_and_slide() method is intended to simplify the collision
response in the common case where you want one body to slide along the other.
It is especially useful in platformers or top-down games, for example.
move_and_slide(), the function uses a number of node properties
to calculate its slide behavior. These properties can be found in the Inspector,
or set in code.
velocity- default value:
Vector2( 0, 0 )
This property represents the body's velocity vector in pixels per second.
move_and_slide()will modify this value automatically when colliding.
motion_mode- default value:
This property is typically used to distinguish between side-scrolling and top-down movement. When using the default value, you can use the
is_on_ceiling()methods to detect what type of surface the body is in contact with, and the body will interact with slopes. When using
MOTION_MODE_FLOATING, all collisions will be considered "walls".
up_direction- default value:
Vector2( 0, -1 )
This property allows you to define what surfaces the engine should consider being the floor. Its value lets you use the
is_on_ceiling()methods to detect what type of surface the body is in contact with. The default value means that the top side of horizontal surfaces will be considered "ground".
floor_stop_on_slope- default value:
This parameter prevents a body from sliding down slopes when standing still.
wall_min_slide_angle- default value:
0.261799(in radians, equivalent to
This is the minimum angle where the body is allowed to slide when it hits a slope.
floor_max_angle- default value:
0.785398(in radians, equivalent to
This parameter is the maximum angle before a surface is no longer considered a "floor."
There are many other properties that can be used to modify the body's behavior under specific circumstances. See the CharacterBody2D docs for full details.
move_and_collide() the function returns a
directly, and you can use this in your code.
move_and_slide() it's possible to have multiple collisions occur,
as the slide response is calculated. To process these collisions, use
# Using move_and_collide. var collision = move_and_collide(velocity * delta) if collision: print("I collided with ", collision.get_collider().name<