godot-physics

Godot Physics (4.x, 2D + 3D)

Pick the right physics body, wire up collision layers/masks, detect overlaps, and cast rays. Concepts apply to both 2D and 3D (swap the 2D/3D suffix). Targets Godot 4.7.

When to use

• Use when choosing between body types, setting collision layers/masks so the right things collide, detecting overlaps (triggers, hurtboxes) with Area, applying forces/impulses to a RigidBody, or casting rays for line-of-sight/ground checks.

When not to use: kinematic character controllers (move_and_slide) → godot-2d-movement; tile collision setup → godot-tilemap; tuning the feel of physics (timestep, mass, jitter) → physics-tuning.

Core workflow

1. Choose the body type:
   • StaticBody — never moves (floors, walls). Collides, no simulation.
   • RigidBody — fully simulated (gravity, forces, bouncing). Don't set its position directly; apply forces/impulses or set linear_velocity.
   • CharacterBody — script-driven kinematic (see godot-2d-movement).
   • Area — detects overlaps and can apply gravity/damping; no solid collision. Every body needs a CollisionShape (or CollisionPolygon) child.
2. Configure layers and masks. A body is on its layers and scans for its masks. Two bodies interact only if one's layer is in the other's mask. Name layers in Project Settings > Layer Names for clarity.
3. Detect overlaps with Area signals (body_entered, area_entered).
4. Drive RigidBodies with forces/impulses, or override _integrate_forces for full control.
5. Cast rays with a RayCast2D/3D node (polled each frame) or a one-shot space-state query from code.

Patterns

1. Collision layers vs masks (set from code)

# Player is on layer 1, scans layers 2 (walls) and 3 (enemies).
func _ready() -> void:
    set_collision_layer_value(1, true)    

2. Area2D as a trigger / hurtbox

3. Applying force and impulse to a RigidBody3D

4. Raycast two ways

Pitfalls

• Layer vs mask confusion is the #1 bug. Layer = "what I am"; mask = "what I look for". For A to detect B, B's layer must be in A's mask. Detection can be one-directional.
• Moving a RigidBody by position fights the solver and causes tunneling/jitter. Use impulses/forces, set linear_velocity, or freeze it. To teleport, set position and zero the velocities inside _integrate_forces.
• Area doesn't fire when neither monitoring nor monitorable is set, or layers/masks don't overlap. monitoring must be on for the Area to detect; monitorable lets others detect it.
• RayCast2D/3D read stale or no data if enabled is false, or if you read it before physics updated — read in _physics_process, and call force_raycast_update() after moving it within the same tick.
• Forgetting a CollisionShape (or leaving it empty) means the body never collides.
• Fast objects tunnel through thin walls; enable continuous CD on the RigidBody (continuous_cd) or use a raycast-based check.
• intersect_ray excludes its own body? Pass query.exclude = [self.get_rid()] (an Array[RID], not an array of nodes) to skip self-hits.

References

• For _integrate_forces, joints, one-way collision, PhysicsServer direct access, shape queries (intersect_shape), and 3D move_and_collide, read references/bodies-and-queries.md.

Related skills

• godot-2d-movement — kinematic CharacterBody2D controllers.
• godot-tilemap — tile collision shapes and their layers.
• physics-tuning — engine-agnostic feel: timestep, mass, drag, CCD.
• godot-3d-essentials — 3D scene setup these bodies live in.