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, CollisionPolygon2

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 interpolation smoothing.gd . Script index [collision setup.gd](scripts/collision setup.gd) / [collision bitmask helper.gd](scripts/collision bitmask helper.gd) / [collision layer matrix manager.gd](scripts/collision layer matrix manager.gd) [physics queries.gd](scripts/physics queries.gd) / [physics direct query.gd](scripts/physics direct query.gd) / [physics direct space query.gd](scripts/physics direct space query.gd) / [physics query cache.gd](scripts/physics query cache.gd) [raycast vision stack.gd](scripts/raycast vision stack.gd) / [raycast hit prediction.gd](scripts/raycast hit prediction.gd) [shapecast aoe.gd](scripts/shapecast aoe.gd) / [shapecast aoe detection.gd](scripts/shapecast aoe detection.gd) [physics server swarm.gd](scripts/physics server swarm.gd) / [physics server direct body.gd](scripts/physics server direct body.gd) [continuous collision detection.gd](scripts/continuous collision detection.gd) / [substepping logic.gd](scripts/substepping logic.gd) [safe rigidbody state.gd](scripts/safe rigidbody state.gd) / [custom physics.gd](scripts/custom physics.gd) / [custom physics 2d.gd](scripts/custom physics 2d.gd) [custom gravity area.gd](scripts/custom gravity area.gd) / [custom gravity override.gd](scripts/custom gravity override.gd) [collision debouncer.gd](scripts/collision debouncer.gd) / [jitter interpolation fix.gd](scripts/jitter interpolation fix.gd) [compound body sync.gd](scripts/compound body sync.gd) / [collision visual debugger.gd](scripts/collision visual debugger.gd) [move and collide precision.gd](scripts/move and collide precision.gd) / [performance batch mover.gd](scripts/performance batch mover.gd) [physics interpolation smoothing.gd](scripts/physics interpolation smoothing.gd) — legacy; prefer jitter fix script Decision Tree: Collision Detection Methods Use Case Method Why / script Continuous trigger zone Area2D + signals Memory of occupants; debounce with collision debouncer.gd One time pickup Area2D + queue free on enter Simple cleanup Line of sight RayCast2D / direct ray raycast vision stack.gd or physics direct query.gd Click to select PhysicsPointQueryParameters2D physics queries.gd AOE spell / melee volume ShapeCast2D / shape query shapecast aoe.gd (not Area signal lag) Instant hit weapon PhysicsRayQueryParameters2D physics queries.gd / raycast hit prediction.gd Platformer ground / ledge Ray or ShapeCast down CharacterBody skill + shapecast aoe detection.gd 1000+ projectiles PhysicsServer2D RIDs MANDATORY physics server swarm.gd Mental model (keep short) Layer = who I am; Mask = who I detect. Bitmask cookbook → [collision layers masks.md](references/collision layers masks.md). Area2D with multiple shapes fires body entered once per shape — dedupe with a Set/dict or [collision debouncer.gd](scripts/collision debouncer.gd). Mid frame ray/shape changes require force raycast update() / force shapecast update() . ready physics queries are false until after a physics frame ( await get tree().physics frame ). CharacterBody2D ships with collision layer = 0 — Areas won't see it until you set a layer. Free PhysicsServer RIDs yourself — they are not GC'd. Deep recipes (on demand) Topic Reference / script Layer/mask patterns [collision layers masks.md](references/collision layers masks.md) Area2D, raycast, shape queries [area2d and queries.md](references/area2d and queries.md) Compound RID bodies [compound body sync.gd](scripts/compound body sync.gd) Contact normal debug draw [collision visual debugger.gd](scripts/collision visual debugger.gd) Reference Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing work to a peer domain — do not preload the whole lattice. Official Documentation [Physics introduction](https://docs.godotengine.org/en/stable/tutorials/physics/physics introduction.html) — Collision layers vs masks, body types, and the mental model every 2D setup depends on. [Collision shapes (2D)](https://docs.godotengine.org/en/stable/tutorials/physics/collision shapes 2d.html) — Correct shape sizing and why scaling CollisionShape2D nodes breaks normals and contacts. [Using CharacterBody2D](https://docs.godotengine.org/en/stable/tutorials/physics/using character body 2d.html) — move and slide / move and collide , floor detection, and kinematic movement contracts. [Using Area2D](https://docs.godotengine.org/en/stable/tutorials/physics/using area 2d.html) — Trigger monitoring, overlap signals, and space/gravity overrides for zones. [Ray casting](https://docs.godotengine.org/en/stable/tutorials/physics/ray casting.html) — RayCast2D vs PhysicsDirectSpaceState2D rays, exclusions, and mid frame force raycast update . [RigidBody](https://docs.godotengine.org/en/stable/tutorials/physics/rigid body.html) — Safe rigid body control via integrate forces / PhysicsDirectBodyState2D instead of fighting the solver in process . [Troubleshooting physics issues](https://docs.godotengine.org/en/stable/tutorials/physics/troubleshooting physics issues.html) — Tunneling, jitter, one way platforms, and common layer/mask misconfigurations. [Physics interpolation introduction](https://docs.godotengine.org/en/stable/tutorials/physics/interpolation/physics interpolation introduction.html) — Why fixed physics ticks stutter on high refresh displays and when interpolation fixes it. [PhysicsServer2D](https://docs.godotengine.org/en/stable/classes/class physicsserver2d.html) — RID based body/shape APIs for swarm scale 2D physics without SceneTree overhead. [PhysicsDirectSpaceState2D](https://docs.godotengine.org/en/stable/classes/class physicsdirectspacestate2d.html) — Point, ray, and shape queries for LOS, AOE, and click picking without permanent query nodes. [ShapeCast2D](https://docs.godotengine.org/en/stable/classes/class shapecast2d.html) — Volume casts for frame perfect melee/AOE detection when Area2D signal lag is unacceptable. Related Skills Prerequisites [godot project foundations](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot project foundations/SKILL.md) — Project Settings layer names, physics ticks, and default gravity must be set before layer/mask matrices stay sane. [godot gdscript mastery](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot gdscript mastery/SKILL.md) — Bitmask enums, typed dictionaries for overlap sets, and physics process discipline underpin every pattern here. [godo

godot-2d-physics