This skill helps an agent get Godot 4.7 physics right: picking a body type, wiring collision layers and masks, detecting overlaps with Area nodes, casting rays and knowing where the Jolt 3D engine behaves differently. It starts by reading project.godot to see which 3D engine runs.
It includes patterns for a safe RigidBody teleport, a one-shot ray that skips the caster and a headless test that proves a hurtbox sees a body. A gotcha list covers layer versus mask confusion, signals that never fire and fast objects that tunnel.
What You Get
- A core workflow from reading the physics engine setting in project.godot to choosing bodies, layers, masks, Area signals and rays
- GDScript patterns for a RigidBody impulse and safe teleport, a one-shot ray that excludes the caster, and a headless Area overlap test
- A gotcha list for layer versus mask confusion, missing body_entered signals, empty overlap lists after spawn, stale raycasts and tunnelling
- A list of Jolt differences, including ray face indices, joint limits, kinematic contacts and the world boundary plane sign change in 4.7
Common Use Cases
- Debugging objects that pass through each other
- Finding out why body_entered or area_entered never fires
- Building a hurtbox or pickup trigger with Area nodes
- Fixing a raycast that hits the object casting it
What Makes It Unique
The skill reads which 3D physics engine the project uses before any debugging, because Jolt and GodotPhysics3D differ in joints, ray results and contacts. It proves behaviour with a headless test runner and an exit code, and hands off movement, tile collision and engine-neutral tuning to sibling skills.
Under The Hood
The agent loads the SKILL.md and, when needed, a reference on body types, shape queries and joints. It reads project.godot and scene files, writes small GDScript test files into your project, and runs the Godot binary headless on them, then reads the exit code and log. If you edited scene files by hand it also runs the Python project checker from a sibling skill. It fetches no web pages and calls no APIs; if there is no Godot binary it asks you to run the command and paste the output.