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 KinematicBody2D node and show some examples of how to use it.
This document assumes you're familiar with Godot's various physics bodies. Please read 物理系統介紹 first.
What is a kinematic body?¶
KinematicBody2D is for implementing bodies that are controlled via code.
Kinematic 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.
A KinematicBody2D can be affected by gravity and other forces, but you must calculate the movement in code. The physics engine will not move a KinematicBody2D.
Movement and collision¶
When moving a
KinematicBody2D, you should not set its
directly. Instead, you use the
These methods move the body along a given vector and instantly stop if
a collision is detected with another body. After a KinematicBody2D has collided,
any collision response must be coded manually.
You should only do Kinematic 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 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_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() automatically calculates frame-based movement
delta. Do not multiply your velocity vector by
before passing it to
In addition to the velocity vector,
move_and_slide() takes a number of
other parameters allowing you to customize the slide behavior:
up_direction- default value:
Vector2( 0, 0 )
This parameter allows you to define what surfaces the engine should consider being the floor. Setting this 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 all surfaces are considered walls.
stop_on_slope- default value:
This parameter prevents a body from sliding down slopes when standing still.
max_slides- default value:
This parameter is the maximum number of collisions before the body stops moving. Setting it too low may prevent movement entirely.
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."
infinite_inertia- default value:
When this parameter is
true, the body can push RigidBody2D
nodes, ignoring their mass, but won't detect collisions with them. If it's
the body will collide with rigid bodies and stop.
This method adds some additional functionality to
move_and_slide() by adding
snap parameter. As long as this vector is in contact with the ground, the
body will remain attached to the surface. Note that this means you must disable
snapping when jumping, for example. You can do this either by setting
Vector2.ZERO or by using
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
get_slide_count() only counts times the body has collided and changed direction.
See KinematicCollision2D for details on what collision data is returned.
Which movement method to use?¶
A common question from new Godot users is: "How do you decide which movement
function to use?" Often, the response is to use
it's "simpler," but this is not necessarily the case. One way to think of it
move_and_slide() is a special case, and
is more general. For example, the following two code snippets result in
the same collision response:
Anything you do with
move_and_slide() can also be done with
but it might take a little more code. However, as we'll see in the examples below,
there are cases where
move_and_slide() doesn't provide the response you want.
In the example above, we assign the velocity that
back into the
velocity variable. This is because when the character collides
with the environment, the function recalculates the speed internally to reflect
For example, if your character fell on the floor, you don't want it to accumulate vertical speed due to the effect of gravity. Instead, you want its vertical speed to reset to zero.
move_and_slide() may also recalculate the kinematic body's velocity several
times in a loop as, to produce a smooth motion, it moves the character and
collides up to five times by default. At the end of the process, the function
returns the character's new velocity that we can store in our
variable, and use on the next frame.
To see these examples in action, download the sample project:
Movement and walls¶
If you've downloaded the sample project, this example is in "BasicMovement.tscn".
For this example, add a
KinematicBody2D with two children: a
Sprite and a
CollisionShape2D. Use the Godot "icon.png" as the Sprite's texture (drag it
from the Filesystem dock to the Texture property of the
Sprite). In the
CollisionShape2D's Shape property, select "New RectangleShape2D" and
size the rectangle to fit over the sprite image.
See 2D movement overview for examples of implementing 2D movement schemes.
Attach a script to the KinematicBody2D and add the following code:
Run this scene and you'll see that
move_and_collide() works as expected, moving
the body along the velocity vector. Now let's see what happens when you add
some obstacles. Add a StaticBody2D with a
rectangular collision shape. For visibility, you can use a sprite, a
Polygon2D, or turn on "Visible Collision Shapes" from the "Debug" menu.
Run the scene again and try moving into the obstacle. You'll see that the
can't penetrate the obstacle. However, try moving into the obstacle at an angle and
you'll find that the obstacle acts like glue - it feels like the body gets stuck.
This happens because there is no collision response.
the body's movement when a collision occurs. We need to code whatever response we
want from the collision.
Try changing the function to
move_and_slide(velocity) and running again.
Note that we removed
delta from the velocity calculation.
move_and_slide() provides a default collision response of sliding the body along the
collision object. This is useful for a great many game types, and may be all you need
to get the behavior you want.
What if you don't want a sliding collision response? For this example ("BounceandCollide.tscn" in the sample project), we have a character shooting bullets and we want the bullets to bounce off the walls.
This example uses three scenes. The main scene contains the Player and Walls. The Bullet and Wall are separate scenes so that they can be instanced.
The Player is controlled by the w and s keys for forward and back. Aiming
uses the mouse pointer. Here is the code for the Player, using
And the code for the Bullet:
The action happens in
_physics_process(). After using
move_and_collide(), if a
collision occurs, a
KinematicCollision2D object is returned (otherwise, the return
If there is a returned collision, we use the
normal of the collision to reflect
velocity with the
If the colliding object (
collider) has a
we also call it. In the example project, we've added a flashing color effect to
the Wall to demonstrate this.
Let's try one more popular example: the 2D platformer.
is ideal for quickly getting a functional character controller up and running.
If you've downloaded the sample project, you can find this in "Platformer.tscn".
For this example, we'll assume you have a level made of
They can be any shape and size. In the sample project, we're using
Polygon2D to create the platform shapes.
Here's the code for the player body:
move_and_slide(), the function returns a vector representing the
movement that remained after the slide collision occurred. Setting that value back
to the character's
velocity allows us to move up and down slopes smoothly. Try
velocity = and see what happens if you don't do this.
Also note that we've added
Vector2(0, -1) as the floor normal. This vector points
straight upward. As a result, if the character collides with an object
that has this normal, it will be considered a floor.
Using the floor normal allows us to make jumping work, using
This function will only return
true after a
where the colliding body's normal is within 45 degrees of the given floor
vector. You can control the maximum angle by setting
This angle also allows you to implement other features like wall jumps using
is_on_wall(), for example.