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 collisionlayer with collisionmask — 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 moveandslide() — moveandslide() automatically includes timestep. Only multiply gravity/acceleration by delta [14].
• NEVER forget forceraycastupdate() for manual mid-frame raycasts — Raycasts update once per physics frame. If you change target_position, you MUST force an update [15].
• NEVER use getoverlappingbodies() every frame — It is expensive. Cache results with bodyentered/bodyexited 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 moveandcollide() 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 setdeferred for immediate physics transform logic — It happens at the end of the frame. Use forceraycast_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)

Canonical vs overlap (dedupe guide)

• ShapeCast AOE: load shapecastaoe.gd for combat AOE; shapecastaoe_detection.gd only for grounded/volume checks — never both for one feature.
• Space queries: start with physicsqueries.gd; add physicsdirectquery.gd / physicsdirectspacequery.gd only if that specialist matches.
• Custom physics: CharacterBody → customphysics2d.gd; RigidBody integrate → custom_physics.gd.
• Interpolation: jitterinterpolationfix.gd wins over physicsinterpolationsmoothing.gd.

Script index

• [collisionsetup.gd](scripts/collisionsetup.gd) / [collisionbitmaskhelper.gd](scripts/collisionbitmaskhelper.gd) / [collisionlayermatrixmanager.gd](scripts/collisionlayermatrixmanager.gd)
• [physicsqueries.gd](scripts/physicsqueries.gd) / [physicsdirectquery.gd](scripts/physicsdirectquery.gd) / [physicsdirectspacequery.gd](scripts/physicsdirectspacequery.gd) / [physicsquerycache.gd](scripts/physicsquerycache.gd)
• [raycastvisionstack.gd](scripts/raycastvisionstack.gd) / [raycasthitprediction.gd](scripts/raycasthitprediction.gd)
• [shapecastaoe.gd](scripts/shapecastaoe.gd) / [shapecastaoedetection.gd](scripts/shapecastaoedetection.gd)
• [physicsserverswarm.gd](scripts/physicsserverswarm.gd) / [physicsserverdirectbody.gd](scripts/physicsserverdirectbody.gd)
• [continuouscollisiondetection.gd](scripts/continuouscollisiondetection.gd) / [substeppinglogic.gd](scripts/substeppinglogic.gd)
• [saferigidbodystate.gd](scripts/saferigidbodystate.gd) / [customphysics.gd](scripts/customphysics.gd) / [customphysics2d.gd](scripts/customphysics2d.gd)
• [customgravityarea.gd](scripts/customgravityarea.gd) / [customgravityoverride.gd](scripts/customgravityoverride.gd)
• [collisiondebouncer.gd](scripts/collisiondebouncer.gd) / [jitterinterpolationfix.gd](scripts/jitterinterpolationfix.gd)
• [compoundbodysync.gd](scripts/compoundbodysync.gd) / [collisionvisualdebugger.gd](scripts/collisionvisualdebugger.gd)
• [moveandcollideprecision.gd](scripts/moveandcollideprecision.gd) / [performancebatchmover.gd](scripts/performancebatchmover.gd)
• [physicsinterpolationsmoothing.gd](scripts/physicsinterpolationsmoothing.gd) — legacy; prefer jitter fix script

Decision Tree: Collision Detection Methods

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 bodyentered once per shape — dedupe with a Set/dict or [collisiondebouncer.gd](scripts/collision_debouncer.gd).
• Mid-frame ray/shape changes require forceraycastupdate() / forceshapecastupdate().
• ready physics queries are false until after a physics frame (await gettree().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)

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 — Collision layers vs masks, body types, and the mental model every 2D setup depends on.
• Collision shapes (2D) — Correct shape sizing and why scaling CollisionShape2D nodes breaks normals and contacts.
• Using CharacterBody2D — moveandslide / moveand_collide, floor detection, and kinematic movement contracts.
• Using Area2D — Trigger monitoring, overlap signals, and space/gravity overrides for zones.
• Ray-casting — RayCast2D vs PhysicsDirectSpaceState2D rays, exclusions, and mid-frame forceraycastupdate.
• RigidBody — Safe rigid-body control via integrateforces / PhysicsDirectBodyState2D instead of fighting the solver in process.
• Troubleshooting physics issues — Tunneling, jitter, one-way platforms, and common layer/mask misconfigurations.
• Physics interpolation introduction — Why fixed physics ticks stutter on high-refresh displays and when interpolation fixes it.
• PhysicsServer2D — RID-based body/shape APIs for swarm-scale 2D physics without SceneTree overhead.
• PhysicsDirectSpaceState2D — Point, ray, and shape queries for LOS, AOE, and click-picking without permanent query nodes.
• ShapeCast2D — Volume casts for frame-perfect melee/AOE detection when Area2D signal lag is unacceptable.

Related Skills

Prerequisites

• godot-project-foundations — Project Settings layer names, physics ticks, and default gravity must be set before layer/mask matrices stay sane.
• godot-gdscript-mastery — Bitmask enums, typed dictionaries for overlap sets, and physicsprocess discipline underpin every pattern here.
• godot-signal-architecture — bodyentered / bodyexited wiring and debounce patterns need clean signal ownership to avoid spam.

Complements

• godot-characterbody-2d — Coyote time, jump buffers, and one-way platforms sit on top of the collision contracts this skill defines.
• godot-raycasting-queries — Deeper query parameter recipes (exclusions, masks, shape casts) when vision/hitscan systems grow beyond basics.
• godot-tilemap-mastery — Tile physics layers and one-way tile collisions must match the same layer matrix used by bodies and areas.
• godot-input-handling — Physics-step input sampling and vsync/latency choices couple tightly with moveandslide feel.
• godot-physics-3d — Parallel 3D body/query concepts when porting or sharing layer policy across dimensions.
• godot-performance-optimization — Profiling and batching guidance when PhysicsServer2D swarms or query caches become bottlenecks.
• godot-debugging-profiling — Visible collision shapes, contact normals, and frame-time traps when diagnosing jitter or missed hits.

Downstream / consumers

• godot-combat-system — Hitboxes/hurtboxes are Area2D + layer/mask products; damage timing inherits overlap and CCD choices.
• godot-genre-platformer — Platformer feel (floors, ledges, one-ways) consumes CharacterBody2D + collision setup from this domain.
• godot-navigation-pathfinding — Agents still need physics layers for blockers and LOS; keep nav meshes and collision worlds consistent.
• godot-monte-carlo-balancer — Jump windows, projectile speed/CCD, gravity, and hitbox size directly change win-rate and difficulty curves; simulate those physics knobs instead of guessing.

Master

• godot-master — Library router and mirrored entry point for discovering 2D physics alongside sibling domains.