Index of every page on this site: llms.txt
All skills
Run it yourself

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`).

Use this Skill: https://skilld.dev/gh/gamedev-skills/awesome-gamedev-agent-skills/godot-physics

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈99 tokens for metadata: the name and description. ≈2.5k when used: this file. ≈1k more on demand in 1 file.

Description uses 5.0% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈397 characters, or 5.0%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts8d3 checks · Risk SAFE
  • Gen Agent Trust Hub9d

    The skill provides instructional content for Godot 4.7 physics. It processes local project configuration files and executes scripts, which introduces a surface for indirect prompt injection common in development tools.

  • Socket8d

    No alerts

  • Snyk9d

    Risk: LOW · No issues

Signed by skilld at c6ca6c4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated last week

README badge

README badge for gamedev-skills/awesome-gamedev-agent-skills/godot-physics