gamedev-skills/awesome-gamedev-agent-skills / skills/godot/godot-physics
godot-physics
VerifiedGodot 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`).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.2 KB |
| references/bodies-and-queries.md | markdown | 4.1 KB |
references/bodies-and-queries.md
View on GitHub# Physics bodies & space queries reference (Godot 4.7)
Depth companion to `godot-physics`. Use the `2D`/`3D` suffix to match your world.
## Body type cheat sheet
| Node | Moves? | Simulated? | Move it by | Use for |
|------|--------|-----------|-----------|---------|
| `StaticBody2D/3D` | No | No | (don't) | Level geometry, walls, floors |
| `AnimatableBody2D/3D` | Yes (scripted/anim) | No | animation / `position` | Moving platforms, doors |
| `RigidBody2D/3D` | Yes | Yes | forces / impulses / `linear_velocity` | Props, debris, balls |
| `CharacterBody2D/3D` | Yes (scripted) | No | `velocity` + `move_and_slide()` | Players, enemies |
| `Area2D/3D` | Yes | No (detection only) | `position` | Triggers, hurt/hitboxes, water |
## Collision layer/mask helpers
```gdscript
set_collision_layer_value(bit, enabled) # 1-based bit (matches editor checkboxes)
set_collision_mask_value(bit, enabled)
get_collision_layer_value(bit) -> bool
collision_layer = 0b0101 # raw bitmask (advanced)
```
Name layers in Project Settings > Layer Names > 2D/3D Physics so the editor checkboxes
read like `Player`, `Walls`, `Enemies`.
## RigidBody control
```gdscript
apply_central_impulse(v) # instant velocity change at center of mass
apply_impulse(v, pos) # impulse at an offset -> adds spin
apply_central_force(v) # continuous force (apply each _physics_process)
apply_torque_impulse(t) # instant angular change
linear_velocity = v # direct set (use sparingly)
freeze = true # stop simulation; freeze_mode = FREEZE_MODE_KINEMATIC|STATIC
gravity_scale = 0.0 # disable gravity for this body
```
Full control via `_integrate_forces`:
```gdscript
func _integrate_forces(state: PhysicsDirectBodyState3D) -> void:
state.linear_velocity = state.linear_velocity.limit_length(max_speed)
# To teleport safely: state.transform = new_transform; state.linear_velocity = Vector3.ZERO
```
Enable `contact_monitor` and set `max_contacts_reported > 0` to receive
`body_entered`/`body_exited` on a RigidBody.
## Space-state queries (code-driven, no node)
```gdscript
var space := get_world_3d().direct_space_state
# Ray
var rq := PhysicsRayQueryParameters3D.create(from, to)
rq.collision_mask = 0b0010
rq.exclude = [self.get_rid()]
var hit := space.intersect_ray(rq) # {position, normal, collider, collider_id, rid, shape, face_index}
# Shape overlap (e.g. "what's inside this sphere?")
var shape := SphereShape3D.new(); shape.radius = 2.0
var sq := PhysicsShapeQueryParameters3D.new()
sq.shape = shape
sq.transform = Transform3D(Basis(), global_position)
var hits := space.intersect_shape(sq, 32) # array of {collider, rid, shape}
```
`intersect_point` (point picks) and `cast_motion`/`collide_shape` (swept and contact tests)
exist on both the 2D and 3D space states. Space-state queries must run during physics (`_physics_process`) for valid data.
## RayCast node tips
- Set `target_position` (relative to the node) and `enabled = true`.
- `is_colliding()`, `get_collider()`, `get_collision_point()`, `get_collision_normal()`.
- `collide_with_areas` / `collide_with_bodies` toggle what it detects.
- After moving the ray within a frame, call `force_raycast_update()` before reading.
- `add_exception(node)` / `add_exception_rid(rid)` to skip specific colliders.
## Joints
`PinJoint`, `HingeJoint`, `SliderJoint`, `Generic6DOFJoint` (3D) and `PinJoint2D`,
`GrooveJoint2D`, `DampedSpringJoint2D` (2D) connect two bodies. Assign `node_a`/`node_b`
to the bodies' paths. Use for ragdolls, chains, vehicles, swinging platforms.
## One-way collision
On a `CollisionShape2D`/`CollisionPolygon2D`, enable **one_way_collision** so bodies pass
from one side only (platforms). The shape blocks motion along
`one_way_collision_direction` (Godot 4.7+, default `Vector2(0, 1)`: things land on top and
pass through from below); before 4.7 that local-down direction is fixed.
## Areas with physics influence
An `Area` can override gravity/damping in its region (`gravity_space_override`,
`gravity`, `linear_damp`) — useful for water, wind, or low-gravity zones affecting any
RigidBody inside.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |