In game development, you often need to know when two objects in the game
intersect or come into contact. This is known as collision detection.
When a collision is detected, you typically want something to happen. This
is known as collision response.

Godot offers a number of collision objects in 2D and 3D 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 works
and what their pros and cons are.

In this guide, you will learn:

Godot’s four collision object types

How each collision object works

When and why to choose one type over another

Note

This document’s examples will use 2D objects. Every 2D physics object
and collision shape has a direct equivalent in 3D and in most cases
they work in much the same way.

Area2D nodes provide detection and influence. They can detect when
objects overlap and can emit signals when bodies enter or exit. An Area2D
can also be used to override physics properties, such as gravity or damping,
in a defined area.

A static body is one that is not moved by the physics engine. It participates
in collision detection, but does not move in response to the collision. They
are most often used for objects that are part of the environment or that do
not need to have any dynamic behavior.

This is the node that implements simulated 2D physics. You do not control a
RigidBody2D directly, but instead you apply forces to it (gravity, impulses,
etc.) and the physics engine calculates the resulting movement. Read more about using rigid bodies.

A physics body can hold any number of Shape2D objects
as children. These shapes are used to define the object’s collision bounds
and to detect contact with other objects.

Note

In order to detect collisions, at least one Shape2D must be
assigned to the object.

The most common way to assign a shape is by adding a CollisionShape2D
or CollisionPolygon2D as a child of the object.
These nodes allow you to draw the shape directly in the editor workspace.

Important

Be careful to never scale your collision shapes in the editor.
The “Scale” property in the Inspector should remain (1,1). When changing
the size of the collision shape, you should always use the size handles, not
the Node2D scale handles. Scaling a shape can result in unexpected
collision behavior.

The physics engine may spawn multiple threads to improve performance, so
it can use up to a full frame to process physics. Because of this, the value
of a body’s state variables such as position or linearvelocity
may not be accurate for the current frame.

In order to avoid this inaccuracy, any code that needs to access a body’s properties should
be run in the Node._physics_process()
callback, which is called before each physics step at a constant frame rate
(60 times per second by default).

One of the most powerful, but frequently misunderstood, collision features
is the collision layer system. This system allows you to build up complex
interactions between a variety of objects. The key concepts are layers
and masks. Each CollisionObject2D has 20 different physics layers
it can interact with.

Let’s look at each of the properties in turn:

collision_layer

This describes the layers that the object appears in. By default, all
bodies are on layer 1.

collision_mask

This describes what layers the body will scan for collisions. If an
object isn’t in one of the mask layers, the body will ignore it. By default,
all bodies scan layer 1.

These properties can be configured via code, or by editing them in the Inspector.

Keeping track of what you’re using each layer for can be difficult, so you
may find it useful to assign names to the layers you’re using. Names can
be assigned in Project Settings -> Layer Names.

Example:

You have four node types in your game: Walls, Player, Enemy, and Coin. Both
Player and Enemy should collide with Walls. The Player node should detect
collisions with both Enemy and Coin, but Enemy and Coin should ignore each
other.

Start by naming layers 1-4 “walls”, “player”, “enemies”, and “coins” and
place each node type in its respective layer using the “Layer” property.
Then set each node’s “Mask” property by selecting the layers it should
interact with. For example, the Player’s settings would look like this:

Area nodes provide detection and influence. They can detect when
objects overlap and emit signals when bodies enter or exit. Areas can also
be used to override physics properties, such as gravity or damping, in a
defined area.

A static body is one that is not moved by the physics engine. It participates
in collision detection, but does not move in response to the collision. However,
it can impart motion or rotation to a colliding body as if it were moving,
using its constant_linear_velocity and constant_angular_velocity properties.

StaticBody2D nodes are most often used for objects that are part of the environment
or that do not need to have any dynamic behavior.

This is the node that implements simulated 2D physics. You do not control a
RigidBody2D directly. Instead, you apply forces
to it and the physics engine calculates the resulting movement, including
collisions with other bodies, and collision responses, such as bouncing,
rotating, etc.

You can modify a rigid body’s behavior via properties such as “Mass”,
“Friction”, or “Bounce”, which can be set in the Inspector.

The body’s behavior is also affected by the world’s properties, as set in
Project Settings -> Physics, or by entering an Area2D
that is overriding the global physics properties.

When a rigid body is at rest and hasn’t moved for a while, it goes to sleep.
A sleeping body acts like a static body, and its forces are not calculated by
the physics engine. The body will wake up when forces are applied, either by
a collision or via code.

One of the benefits of using a rigid body is that a lot of behavior can be had
“for free” without writing any code. For example, if you were making an
“Angry Birds”-style game with falling blocks, you would only need to create
RigidBody2Ds and adjust their properties. Stacking, falling, and bouncing would
automatically be calculated by the physics engine.

However, if you do wish to have some control over the body, you should take
care - altering the position, linear_velocity, or other physics properties
of a rigid body can result in unexpected behavior. If you need to alter any
of the physics-related properties, you should use the _integrate_forces()
callback instead of _physics_process(). In this callback, you have access
to the body’s Physics2DDirectBodyState,
which allows for safely changing properties and synchronizing them with
the physics engine.

Note that we are not setting the linear_velocity or angular_velocity
properties directly, but rather applying forces (thrust and torque) to
the body and letting the physics engine calculate the resulting movement.

Note

When a rigid body goes to sleep, the _integrate_forces()
function will not be called. To override this behavior, you will
need to keep the body awake by creating a collision, applying a
force to it, or by disabling the can_sleep
property. Be aware that this can have a negative effect on performance.

By default, rigid bodies do not keep track of contacts, because this can
require a huge amount of memory if many bodies are in the scene. To enable
contact reporting, set the contacts_reported
property to a non-zero value. The contacts can then be obtained via
Physics2DDirectBodyState.get_contact_count()
and related functions.

Contact monitoring via signals can be enabled via the contact_monitor
property. See RigidBody2D for the list of available
signals.

KinematicBody2D bodies detect collisions with
other bodies, but are not affected by physics properties like gravity or friction.
Instead, they must be controlled by the user via code. The physics engine will
not move a kinematic body.

When moving a kinematic body, you should not set its position directly.
Instead, you use the move_and_collide() or move_and_slide() methods.
These methods move the body along a given vector, and it will instantly stop
if a collision is detected with another body. After the body has collided,
any collision response must be coded manually.

After a collision, you may want the body to bounce, to slide along a wall,
or to alter the properties of the object it hit. The way you handle collision
response depends on which method you used to move the KinematicBody2D.

When using move_and_collide(), the function returns a
KinematicCollision2D object, which contains
information about the collision and the colliding body. You can use this
information to determine the response.

For example, if you want to find the point in space where the collision
occurred:

Sliding is a common collision response; imagine a player moving along walls
in a top-down game or running up and down slopes in a platformer. While it’s
possible to code this response yourself after using move_and_collide(),
move_and_slide() provides a convenient way to implement sliding movement
without writing much code.

Warning

move_and_slide() automatically includes the timestep in its
calculation, so you should not multiply the velocity vector
by delta.

For example, use the following code to make a character that can walk along
the ground (including slopes) and jump when standing on the ground: