godot-2d-physics

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 0c0182b848c3 · 21 Oct 2026Report an issue or request a re-scan

• Publisherthedivergentai GitHub userOwner of the repository this skill is read from
• Source folderthedivergentai/gd-agentic-skills/skills/godot-2d-physicsThe exact folder we audited
• LicenceLGPL-3.0As the repository states it
• Commit pinned for this verdict0c0182b848c3A new audit runs when the source changes
• Repository statusNot archivedLast push 4 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Expert patterns for Godot 2D physics including collision layers/masks, Area2D triggers, raycasting, and PhysicsDirectSpaceState2D queries. Use when implementing collision detection, trigger zones, line-of-sight systems,…

---
name: godot-2d-physics
description: "Expert patterns for Godot 2D physics including collision layers/masks, Area2D triggers, raycasting, and PhysicsDirectSpaceState2D queries. Use when implementing collision detection, trigger zones, line-of-sight systems, or manual physics queries. Trigger keywords: CollisionShape2D, CollisionPolygon2D, collision_layer, collision_mask, set_collision_layer_value, set_collision_mask_value, Area2D, body_entered, body_exited, RayCast2D, force_raycast_update, PhysicsPointQueryParameters2D, PhysicsShapeQueryParameters2D, direct_space_state, move_and_collide, move_and_slide."
---

# 2D Physics

Expert guidance for collision detection, triggers, and raycasting in Godot 2D.

## NEVER Do

- **NEVER scale `CollisionShape2D` nodes** — Use the shape handles in the editor, NOT the Node2D scale property. Scaling causes unpredictable physics behavior and incorrect collision normals [12].
- **NEVER confuse `collision_layer` with `collision_mask`** — Layer = "What AM I?", Mask = "What do I DETECT?". Setting both to the same value is usually wrong [13].
- **NEVER multiply velocity by delta when using `move_and_slide()`** — `move_and_slide()` automatically includes timestep. Only multiply gravity/acceleration by delta [14].
- **NEVER forget `force_raycast_update()` for manual mid-frame raycasts** — Raycasts update once per physics frame. If you change target_position, you MUST force an update [15].
- **NEVER use `get_overlapping_bodies()` every frame** — It is expensive. Cache results with `body_entered`/`body_exited` signals instead [16].
- **NEVER modify `RigidBody2D` state directly in `_process`** — Use `_integrate_forces()` for safe, synchronized access to `PhysicsDirectBodyState2D` [17, 411].
- **NEVER move `PhysicsBody2D` nodes in `_process()`** — Use `_physics_process()`. Moving bodies outside the physics step causes stutter and unreliable collision detection.
- **NEVER use `RigidBody2D` for 1000+ simple entities** — Use `PhysicsServer2D` to bypass node overhead for massive performance gains (Swarms/Bullets) [18, 397].
- **NEVER use `Area2D` for high-frequency blocking (Bullets)** — Area signals can be delayed. Use `move_and_collide()` or `ShapeCast2D` for frame-perfect results [19].
- **NEVER ignore 'Physics Jitter' on high-refresh monitors** — Enable Physics Interpolation to prevent micro-stutter in motion [21, 400].
- **NEVER scale collision shapes directly at runtime** — It causes major instability. Resize the shape resource (size/radius) instead.
- **NEVER use `set_deferred` for immediate physics transform logic** — It happens at the end of the frame. Use `force_raycast_update()` or `PhysicsServer2D` instead.
- **NEVER leave Continuous CD (CCD) enabled for slow objects** — It adds significant CPU overhead. Reserve it for high-speed projectiles to prevent tunneling.
- **NEVER use a single collision layer for all tiles/entities** — Separate layers (Ground, Walls, Enemies) to allow selective filtering via masks.
- **NEVER forget to free `PhysicsServer2D` RIDs manually** — They are not garbage collected and will leak memory permanently.

---

## Available Scripts

> **MANDATORY**: Read the script matching your workflow branch before coding. Query/Area cookbook samples live in scripts — not in this body.

### Workflow router (MANDATORY / Do NOT Load)
| Branch | Load | Do NOT Load |
|--------|------|-------------|
| Layer/mask matrix setup | `collision_bitmask_helper.gd` or `collision_setup.gd`; matrix policy → `collision_layer_matrix_manager.gd` | Swarm / CCD scripts |
| LOS / vision cones | `raycast_vision_stack.gd` (+ `physics_direct_query.gd` for nodeless rays) | `shapecast_aoe*.gd`, `physics_server_swarm.gd` |
| AOE / melee volume | **Prefer** `shapecast_aoe.gd` (faction mask); ground/volume sensing → `shapecast_aoe_detection.gd` | Area2D spam + lava DoT tutorials; do not load both shapecast scripts for the same feature |
| Hitscan / point pick / one-shot shape | `physics_queries.gd` (canonical). Specialists: `physics_direct_space_query.gd` (LOS bool), `raycast_hit_prediction.gd` | Re-load all three query helpers at once |
| Bullet hell / 1000+ bodies | **MANDATORY** `physics_server_swarm.gd` (+ `physics_server_direct_body.gd` for RID shapes) | Per-bullet Area2D / RigidBody2D nodes |
| High-speed tunneling | `continuous_collision_detection.gd` + `substepping_logic.gd` | CCD on slow props |
| RigidBody safe mutate | `safe_rigidbody_state.gd` (`_integrate_forces`) | Direct transform writes in `_process` |
| Custom CharacterBody forces | `custom_physics_2d.gd` | `custom_physics.gd` (that file is RigidBody `_integrate_forces`) |
| Gravity zones | `custom_gravity_area.gd` (Area override) or `custom_gravity_override.gd` (character weight/zones) | Both unless you need Area + character paths |
| Overlap signal spam | `collision_debouncer.gd` | Polling `get_overlapping_bodies` every frame |
| Compound multi-shape RID | `compound_body_sync.gd` | Multiple nodes for one logical body |
| Debug contact normals | `collision_visual_debugger.gd` | Visible collision menu insufficient |
| High-refresh jitter | **Prefer** `jitter_interpolation_fix.gd` | `physics_interpolation_smoothing.gd` (legacy/manual; only if built-in interpolation is unavailable) |
| Precision bounce / slide | `move_and_collide_precision.gd` | — |
| Batch static movers | `performance_batch_mover.gd` | — |
| Query result cache | `physics_query_cache.gd` | Duplicate space queries same frame |

### Canonical vs overlap (dedupe guide)
- **ShapeCast AOE**: load `shapecast_aoe.gd` for combat AOE; `shapecast_aoe_detection.gd` only for grounded/volume checks — never both for one feature.
- **Space queries**: start with `physics_queries.gd`; add `physics_direct_query.gd` / `physics_direct_space_query.gd` only if that specialist matches.
- **Custom physics**: CharacterBody → `custom_physics_2d.gd`; RigidBody integrate → `custom_physics.gd`.
- **Interpolation**: `jitter_interpolation_fix.gd` wins over `physics_interp

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/thedivergentai/gd-agentic-skills
git -C gd-agentic-skills checkout 0c0182b848c3

Works in

1. 2026-10-21
   ✓SAFE B 89 / 100

   first audit · source 0c0182b848c3

Questions about godot-2d-physics

• github.com/thedivergentai/gd-agentic-skills/tree/main/skills/god — the audited source at commit 0c0182b848c3 and every finding aboveObserved · 21 Oct 2026

Spotted something wrong? Report a correction · Methodology