Physics and collisions
Choosing a physics body, collision shape, layers and update step.
Start with the object's task rather than its class name. Visible geometry, collision shapes, and movement code serve different purposes; adding a sprite or mesh does not create collision.
Choose a type
| Task | 2D / 3D | Movement owner |
|---|---|---|
| Stationary floor or wall | StaticBody2D / StaticBody3D | Does not move in response to contact. |
| Player or controlled character | CharacterBody2D / CharacterBody3D | Your code with MoveAndSlide() or MoveAndCollide(). |
| Crate, ball, or simulated prop | RigidBody2D / RigidBody3D | Simulation; code applies forces and impulses. |
| Platform on a prescribed trajectory | AnimatableBody2D / AnimatableBody3D | A script or animation prescribes motion. |
| Pickup, damage, or detection zone | Area2D / Area3D | Detects overlaps; does not itself act as a solid wall. |
CharacterBody2D does not receive gravity automatically: your controller implements it. RigidBody2D is simulated automatically, so do not overwrite its Position every frame instead of using forces.
Get a first checkable result
For a simulated prop, open the Area2D example. Add both complete files, LabBody2D.cs and CollisionLab2D.cs, attach the latter to an Entity2D root in a standalone level, and run it. Example conditions: a 640×420 window, 60 physics ticks per second, and downward gravity 980.
Expected result: the crate passes through the rectangular zone, enter/exit counters increase, and the crate stops on the solid floor. This demonstrates detection versus blocking in one experiment. R resets the prop by requesting a physics-state change; the automated check calls the same reset method programmatically rather than emulating a physical keyboard.
For a player, use the complete 2D controller or 3D controller. Do not base player control on the simulated-crate example.
Configure a shape
Add a child CollisionShape2D or CollisionShape3D and assign its Shape resource. A Shape2D itself is a resource, not a child Entity. Start with a rectangle/box for a crate, a circle/sphere for a ball, and an appropriate capsule for a character.
Check shape size and placement against the image. Change resource dimensions rather than using nonuniform body scale as a substitute for collision setup. If objects share one shape resource, editing it affects all of them; see 2D shapes and 3D shapes.
Understand layers using one pair
CollisionLayer is object membership. CollisionMask filters interaction or detection. Both are uint bitmasks; layer number 3 is value 4 (1u << 2), not mask 3. SetCollisionLayerValue and SetCollisionMaskValue take a number from 1–32, not an assembled mask.
The executed example has a floor with Layer=1, Mask=0 and a crate with Layer=4, Mask=1. They collide: do not require identical reciprocal masks for every body pair. The zone has Mask=4 and detects the crate. An area's mask targets the detected body's layers; a ray has its own mask. Inspect the actual query type instead of transferring one filtering rule to every system.
Physics, navigation, and rendering layers are separate filters. Objects need the corresponding physics world: 2D collision does not stop a 3D body.
Velocity, displacement, and delta
| Action | Supply |
|---|---|
CharacterBody2D.Velocity, then MoveAndSlide() | Units-per-second velocity without multiplying by delta. |
MoveAndCollide(motion) | Displacement for the step; for constant velocity, velocity * (float)delta. |
| Controller gravity | Velocity increment acceleration * (float)delta. |
ApplyCentralForce(force) | Force for each required physics tick; do not first convert it to an impulse through delta. |
ApplyCentralImpulse(impulse) | One impulse per event. Repeating every frame applies repeated impulses. |
Move characters in _PhysicsProcess(double delta). physics/common/physics_ticks_per_second sets the frequency; 60 is an example condition, not a mandatory rate. 2D commonly uses pixels with positive Y down; 3D uses meters with positive Y up. Keep scale consistent with settings, but vectors do not enforce units.
Diagnose a wrong result
- A body falls through: check
Shape, enabled state, world, placement, filters, and movement method. - No area entry: check
Monitoring, the area mask, and the body layer; allow physics to update overlaps. - A prop jitters: remove per-frame transform assignment on the simulated body; see RigidBody control.
- Motion looks uneven between ticks: see interpolation. It does not fix collision or make physics deterministic.
- Only hit detection is needed: use a ray, not an invisible moving body.
The linked examples checked floor/prop contact, asymmetric masks, area enter/exit, reset, impulse, and mass. This does not guarantee identical simulation across platforms and backends; moving platforms, physical input devices, high-speed collisions, and performance were not evaluated by this check.