Physics: choose a body, shape and query
Start with 2D/3D collisions: body roles, layers, physics ticks and complete examples.
Choose the task
| Need | Use |
|---|---|
| A stationary wall or floor | StaticBody2D/3D with a child collision shape |
| A code-controlled character | CharacterBody2D/3D, moving through body methods in _PhysicsProcess |
| A crate that falls and reacts to a hit | RigidBody2D/3D, forces, impulses and the physics integrator |
| A moving platform | AnimatableBody2D/3D with coordinated physics movement |
| A damage, pickup or gravity region | Area2D/3D; overlap detection is separate from blocking |
| Sight checks, aiming or mouse picking | RayCast2D/3D or a DirectSpaceState query |
Entity2D/3D, sprites and MeshInstances are not automatically physics bodies. A CollisionShape does not replace a body either: it is a child entity holding a Shape resource. Configure visible models and collision geometry separately.
Start with a working level
Open the 2D collision example: it creates a floor, wall, falling body, region and ray itself. For a spatial world, use the 3D example. Both include all required C# files, the root type and expected results. No external images or models are needed.
Study character movement in the complete 2D game or complete 3D game, including input, movement, collisions and restart. In an existing project, first check physics frequency, gravity and the selected backend.
Check every object pair
A body/area needs enabled child shapes with nonzero dimensions and correct placement. Layer defines membership; Mask filters what the object detects or interacts with. Layer number 3 is bit 1 << 2, value 4, not mask 3. For editor layer numbers 1–32, use SetCollisionLayerValue/SetCollisionMaskValue; do not shift the number again.
Area detection is directed: its Mask tests the target Layer. A ray has its own Mask and body/area options. Physical bodies use both participants' filters under backend rules; do not automatically require identical reciprocal masks. The examples have a floor on Layer 1, Mask 0 and a crate on Layer 4, Mask 1, and they do contact. See areas and rays for detail.
Physics time and units
_PhysicsProcess receives the fixed tick step; _Process follows rendering. physics/common/physics_ticks_per_second sets the frequency. These examples were checked at 60 ticks/s, with downward gravity 980 in 2D and 9.8 in 3D. Those are example settings, not mandatory values for every game. 2D conventionally uses pixels and 3D metres; Vector values do not enforce your unit system. Positive Y points down in 2D and up in 3D.
Express velocity in units per second. Whether delta is needed depends on the method: do not convert CharacterBody.Velocity or ApplyCentralForce into per-frame displacement first. Apply an impulse once per event. Rigid-body control explains the differences.
Physics events and results do not update synchronously with each statement. After adding/moving a shape, allow the required physics tick. Deferred changes, physics interpolation and network synchronization solve different problems; interpolation does not improve contact accuracy. If behavior is wrong, start with diagnosing causes, rather than increasing every numeric setting.