Skip to content

gamedev-skills/awesome-gamedev-agent-skills / skills/godot/godot-physics

godot-physics

Verified

Godot 4.7 physics API in 2D and 3D: body and Area types, collision_layer and mask bits, Area signals for hurtboxes, RayCast and space queries, and Jolt (3D default since 4.6). Use when objects pass through each other, body_entered never fires or a raycast hits itself. Not for engine-neutral jitter and tunnelling (`physics-tuning`) or CharacterBody movement (`godot-2d-movement`).

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

Pick the body type, wire collision layers and masks, detect overlaps, cast rays, and know where Jolt differs. Swap the 2D/3D suffix as needed. Targets Godot 4.7 (see Version notes). 2D always uses Godot's own 2D engine.

When to use

  • Choosing a body type, setting layers/masks so the right things collide, overlap detection (triggers, hurtboxes) with Area, forces/impulses on a RigidBody, or rays for line-of-sight and ground checks.

When not to use: move_and_slide controllers → godot-2d-movement; tile collision setup → godot-tilemap; engine-neutral feel (timestep, mass, jitter, CCD strategy) → physics-tuning.

Core workflow

  1. For 3D, read which engine runs before debugging behavior. In project.godot, [physics] 3d/physics_engine="Jolt Physics" means Jolt; no line (DEFAULT) means GodotPhysics3D. New 4.6+ projects write the Jolt line. The API is the same, but joints, ray face indices, kinematic contacts and margins differ (see Gotchas).

  2. Choose the body type: StaticBody never moves; AnimatableBody is moved by code or animation and pushes others (platforms, doors); RigidBody is simulated (move it with forces, impulses or linear_velocity, never position); CharacterBody is script-driven; Area only detects and can override gravity/damping. Every body needs a non-empty CollisionShape/CollisionPolygon child.

  3. Configure layers and masks. Layers are what a body is; masks are what it scans. A detects B only if B's layer bit is in A's mask. Name the bits in project.godot so the .tscn values are readable:

    [layer_names]
    2d_physics/layer_1="player"
    2d_physics/layer_2="walls"
    2d_physics/layer_3="enemies"
    

    In a .tscn, collision_layer = 1 and collision_mask = 6 (bits 2 and 3) are plain integers; bit n is 1 << (n - 1). In code, set_collision_mask_value(3, true) uses the same 1-based numbers as the editor checkboxes.

  4. Detect overlaps with Area signals (body_entered, area_entered); monitoring on the detecting Area, monitorable on the detected one.

  5. Cast rays with a RayCast2D/3D node (polled each physics frame) or a one-shot direct_space_state query (Pattern 2).

  6. Check before you finish. Physics runs normally under --headless, so prove the behavior with a test runner instead of describing it (Pattern 3). Run godot --headless --path . --script res://tests/test_physics.gd and read the exit code and any SCRIPT ERROR/ERROR: lines. With no Godot binary (godot, godot4 or $GODOT_BIN), ask the user to run it and paste the output. For a visual check, ask the user to run godot --path . --debug-collisions and report what overlaps. If you edited .tscn files by hand, also run the godot-nodes-scenes skill's scripts/check_godot_project.py <project-dir>.

Patterns

1. RigidBody: impulse, force, and a safe teleport

extends RigidBody3D

var _teleport_to: Variant = null

func push(direction: Vector3) -> void:
    apply_central_impulse(direction * 8.0)      # one-off velocity change

func teleport(to: Transform3D) -> void:
    _teleport_to = to                           # applied inside the solver step

func _integrate_forces(state: PhysicsDirectBodyState3D) -> void:
    if _teleport_to != null:
        state.transform = _teleport_to
        state.linear_velocity = Vector3.ZERO
        state.angular_velocity = Vector3.ZERO
        _teleport_to = null

2. One-shot ray that skips the caster

func ground_under(from: Vector2) -> Dictionary:
    var space := get_world_2d().direct_space_state
    var query := PhysicsRayQueryParameters2D.create(from, from + Vector2(0, 64))
    query.collision_mask = 0b10                  # layer 2 only ("walls")
    query.exclude = [get_rid()]                  # Array[RID], not nodes
    return space.intersect_ray(query)            # {} on miss, else collider/position/normal

Call it from _physics_process; space-state data is only valid during the physics step.

3. Headless test that an Area sees a body

# res://tests/test_physics.gd
extends SceneTree

func _initialize() -> void:
    var level: Node = load("res://levels/test_arena.tscn").instantiate()
    root.add_child(level)
    for _i in 3:
        await physics_frame                      # overlap lists update once per step
    var hurtbox: Area2D = level.get_node("Hurtbox")
    var player: Node2D = level.get_node("Player")
    var ok := hurtbox.overlaps_body(player)
    print("hurtbox sees player: ", ok)
    quit(0 if ok else 1)

Place the two nodes so they overlap in the test scene. The same shape works for "the crate lands on the floor" (compare global_position.y after N frames) or "the ray hits the wall". Add counters as in godot-gdscript-headless-testing once there is more than one assertion.

Gotchas

  • Layer vs mask confusion is the most common bug. Detection can be one-directional: A sees B if B's layer is in A's mask, whatever B's mask says.
  • Moving a RigidBody by position fights the solver and causes tunnelling or jitter. Use impulses, forces, linear_velocity, freeze, or set state.transform in _integrate_forces (Pattern 1).
  • A RigidBody's own body_entered never fires unless contact_monitor = true and max_contacts_reported > 0.
  • Area doesn't fire when monitoring is off on it, monitorable is off on the other Area, or the bits don't overlap. Toggling monitoring from inside an enter/exit signal handler is blocked ("Function blocked during in/out signal"); use set_deferred("monitoring", false).
  • get_overlapping_bodies() is empty right after spawning → the list updates once per physics step. Await a physics_frame or use the signals.
  • RayCast2D/3D read stale or no data if enabled is false or you read before physics ran. Read in _physics_process; call force_raycast_update() after moving it in the same tick.
  • Fast objects tunnel through thin walls → enable continuous_cd on the RigidBody or sweep with a ray/shape cast. Tuning strategy belongs to physics-tuning.
  • "Can't change this state while flushing queries" → you added/removed bodies or shapes inside a physics callback. Use call_deferred / set_deferred.

Jolt Physics (3D) differences

  • face_index is always -1 in intersect_ray() / RayCast3D results. Set physics/jolt_physics_3d/queries/enable_ray_cast_face_index=true in project.godot if you need it (roughly 25% more memory for ConcavePolygonShape3D).
  • A joint with only one body gets inverted limits after switching engines. Jolt treats the lone body as node_b with node_a as the world; GodotPhysics3D treats it as node_a. Move the body to the slot Jolt expects, or set physics/jolt_physics_3d/joints/world_node for compatibility with an older project.
  • Joint soft-limit properties do nothing under Jolt: bias/damping/impulse_clamp on PinJoint3D; bias/softness/relaxation on HingeJoint3D and ConeTwistJoint3D; angular_* and limit softness/restitution/damping on SliderJoint3D; limit softness/restitution/damping/erp on Generic6DOFJoint3D. Godot warns when they are set to non-default values.
  • A frozen kinematic RigidBody3D reports no contacts with static or kinematic bodies, even with max_contacts_reported > 0. Enable physics/jolt_physics_3d/simulation/generate_all_kinematic_contacts if gameplay needs them.
  • Shape margin shrinks the shape instead of padding it, so sizes stay true but shape queries can return odd normals on small shapes; the effective margin comes from physics/jolt_physics_3d/collisions/collision_margin_fraction.
  • Area3D fires body_entered for SoftBody3D under Jolt. Filter soft bodies with layers/masks if the old behavior is expected.
  • A WorldBoundaryShape3D floor sits at the wrong height after upgrading to 4.7 → under Jolt, 4.7 reads plane.d with Godot's sign convention, the opposite of 4.6; flip the sign of d in projects tuned on 4.6. Jolt also caps the plane's effective size (physics/jolt_physics_3d/limits/world_boundary_shape_size), so bodies far from the origin can fall off an "infinite" floor.

References

  • Read references/bodies-and-queries.md when you need the body-type table, the full RigidBody control API, shape queries (intersect_shape, cast_motion), RayCast node options, joints, one-way collision, or Area gravity/damping overrides.
  • Read the Godot docs page Using Jolt Physics when a Jolt difference is not in the list above.

Related skills

  • godot-2d-movement for CharacterBody2D controllers.
  • godot-tilemap for tile collision shapes and their layers.
  • physics-tuning for engine-neutral feel: timestep, mass, drag, CCD, jitter.
  • godot-3d-essentials for the 3D scene these bodies live in.
  • godot-gdscript-headless-testing to keep Pattern 3 tests in CI.

Version notes

Last verified: 2026-11-11 against Godot 4.7.2-stable (released 2026-08-18).

  • Jolt Physics is the default 3D engine for projects created in 4.6 or later; older projects keep GodotPhysics3D until someone switches them.
  • 4.7 flipped how Jolt reads WorldBoundaryShape3D plane.d and added one_way_collision_direction on 2D collision shapes.
  • The physics/jolt_physics_3d/* settings named above exist in 4.7.2.

Sources: Godot 4.6 release, Upgrading from 4.6 to 4.7, ProjectSettings @ 4.7.2-stable, Area2D @ 4.7.2-stable.

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall