Up to date
This page is up to date for Godot
If you still find outdated information, please open an issue.
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
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.
Area2Dnodes provide detection and influence. They can detect when objects overlap and can emit signals when bodies enter or exit. An
Area2Dcan 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.
A body that provides collision detection, but no physics. All movement and collision response must be implemented in code.
Static bodies and rigid bodies can be configured to use a PhysicsMaterial. This allows adjusting the friction and bounce of an object, and set if it's absorbent and/or rough.
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.
In order to detect collisions, at least one
Shape2D must be
assigned to the object.
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
Node2D scale handles. Scaling a shape can result in unexpected
Physics process callback¶
The physics engine runs at a fixed rate (a default of 60 iterations per second). This rate is typically different from the frame rate which fluctuates based on what is rendered and available resources.
It is important that all physics related code runs at this fixed rate. Therefore Godot differentiates between physics and idle processing. Code that runs each frame is called idle processing and code that runs on each physics tick is called physics processing. Godot provides two different callbacks, one for each of those processing rates.
The physics callback, Node._physics_process(),
is called before each physics step. Any code that needs to access a body's properties should
be run in here. This method will be passed a
parameter, which is a floating-point number equal to the time passed in
seconds since the last step. When using the default 60 Hz physics update rate,
it will typically be equal to
0.01666... (but not always, see below).
It's recommended to always use the
delta parameter when relevant in your
physics calculations, so that the game behaves correctly if you change the
physics update rate or if the player's device can't keep up.
Collision layers and masks¶
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 32 different physics layers
it can interact with.
Let's look at each of the properties in turn:
This describes the layers that the object appears in. By default, all bodies are on layer
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
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.
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:
In function calls, layers are specified as a bitmask. Where a function enables
all layers by default, the layer mask will be given as
0xffffffff. Your code
can use binary, hexadecimal, or decimal notation for layer masks, depending
on your preference.
The code equivalent of the above example where layers 1, 3 and 4 were enabled would be as follows:
# Example: Setting mask value for enabling layers 1, 3 and 4 # Binary - set the bit corresponding to the layers you want to enable (1, 3, and 4) to 1, set all other bits to 0. # Note: Layer 32 is the first bit, layer 1 is the last. The mask for layers 4,3 and 1 is therefore 0b00000000_00000000_00000000_00001101 # (This can be shortened to 0b1101) # Hexadecimal equivalent (1101 bi