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)    # I am on layer 1
    set_collision_mask_value(2, true)     # I collide with things on layer 2
    set_collision_mask_value(3, true)     # ...and layer 3
    # Bit-field forms also exist: collision_layer = 1; collision_mask = 0b110