Godot 2d Physics

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)

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 / collision_bitmask_helper.gd / collision_layer_matrix_manager.gd
• physics_queries.gd / physics_direct_query.gd / physics_direct_space_query.gd / physics_query_cache.gd
• raycast_vision_stack.gd / raycast_hit_prediction.gd
• shapecast_aoe.gd / shapecast_aoe_detection.gd
• physics_server_swarm.gd / physics_server_direct_body.gd
• continuous_collision_detection.gd / substepping_logic.gd
• safe_rigidbody_state.gd / custom_physics.gd / custom_physics_2d.gd
• custom_gravity_area.gd / custom_gravity_override.gd
• collision_debouncer.gd / jitter_interpolation_fix.gd
• compound_body_sync.gd / collision_visual_debugger.gd
• move_and_collide_precision.gd / performance_batch_mover.gd
• physics_interpolation_smoothing.gd — legacy; prefer jitter fix script

Decision Tree: Collision Detection Methods