Godot 2D Physics

Mental model (keep short)

• Layer = who I am; Mask = who I detect. Bitmask cookbook → collision-layers-masks.md.
• Area2D with multiple shapes fires body_entered once per shape — dedupe with a Set/dict or 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)

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 — move_and_slide / move_and_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 force_raycast_update.
• RigidBody — Safe rigid-body control via _integrate_forces / 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 _physics_process discipline underpin every pattern here.
• godot-signal-architecture — body_entered / body_exited 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 move_and_slide 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.