godot-2d-physics

Files (26)

• SKILL.md
• collision_bitmask_helper.gd · scripts/
• collision_debouncer.gd · scripts/
• collision_layer_matrix_manager.gd · scripts/
• collision_setup.gd · scripts/
• continuous_collision_detection.gd · scripts/
• custom_gravity_area.gd · scripts/
• custom_gravity_override.gd · scripts/
• custom_physics.gd · scripts/
• custom_physics_2d.gd · scripts/
• jitter_interpolation_fix.gd · scripts/
• move_and_collide_precision.gd · scripts/
• performance_batch_mover.gd · scripts/
• physics_direct_query.gd · scripts/
• physics_direct_space_query.gd · scripts/
• physics_interpolation_smoothing.gd · scripts/
• physics_queries.gd · scripts/
• physics_query_cache.gd · scripts/
• physics_server_direct_body.gd · scripts/
• physics_server_swarm.gd · scripts/
• raycast_hit_prediction.gd · scripts/
• raycast_vision_stack.gd · scripts/
• safe_rigidbody_state.gd · scripts/
• shapecast_aoe.gd · scripts/
• shapecast_aoe_detection.gd · scripts/
• substepping_logic.gd · scripts/

SKILL.md (first lines)

# 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.

---

## Godot 4.7: 2D Physics

- `body_set_shape_as_one_way_collision` adds **direction** parameter — set relative to shape orientation for one-way platforms.
- `CollisionShape2D` supports one-way collision **direction relative to the shape** (not just global up).

## Available Scripts

> **MANDATORY**: Read the script matching your use case before implementation.

### [collision_setup.gd](scripts/collision_setup.gd)
Programmatic layer/mask management with named layer constants and debug visualization.

### [physics_query_cache.gd](scripts/physics_query_cache.gd)
Frame-based caching for PhysicsDirectSpaceState2D queries - eliminates redundant expensive queries.

### [custom_physics.gd](scripts/custom_physics.gd)
Custom physics integration patterns for CharacterBody2D. Covers non-standard gravity, forces, and manual stepping. Use for non-standard physics behavior.

### [physics_queries.gd](scripts/physics_queries.gd)
PhysicsDirectSpaceState2D query patterns for raycasting, point queries, and shape queries. Use for line-of-sight, ground detection, or area scanning.

### [physics_server_swarm.gd](scripts/physics_server_swarm.gd)
Low-level `PhysicsServer2D` usage for thousands of moving objects. Bypasses node overhead for massive performance gains in bullet hells or swarms.

### [substepping_logic.gd](scripts/substepping_logic.gd)
Manual physics sub-stepping for high-velocity projectiles. Ensures frame-perfect collision for objects moving faster than the physics tick.

### [safe_rigidbody_state.gd](scripts/safe_rigidbody_state.gd)
Thread-safe `RigidBody2D` modification using `_integrate_forces`. Ideal for teleporting bodies or applying custom impulses without jitter.

### [physics_direct_query.gd](scripts/physics_direct_query.gd)
Lighweight environment sensing using `PhysicsDirectSpaceState2D`. Performs ray queries without the overhead of RayCast2D nodes.

### [collision_bitmask_helper.gd](scripts/collision_bitmask_helper.gd)
Clean architectural pattern for managing complex collision layers/masks using bitwise Enums and helpers.

### [raycast_vision_stack.gd](scripts/raycast_vision_stack.gd)
Optimized multicasting vision system for AI. Reuses a single RayCast2D to check multiple angles in one physics frame.

### [shapecast_aoe.gd](scripts/shapecast_aoe.gd)
Robust AOE detection using `ShapeCast2D`. Provides instant collision information without the signal-lag of Area2D.

### [custom_gravity_override.gd](scripts/custom_gravity_override.gd)
Logic for localized gravity zones (Water, Space, Wind) and manual character-weight simulation.

### [collision_debouncer.gd](scripts/collision_debouncer.gd)
Expert pattern for preventing signal spam when multi-shape bodies enter triggers.

### [jitter_interpolation_fix.gd](scripts/jitter_interpolation_fix.gd)
Standard configuration and runtime adjustments to ensure smooth character movement on high-refresh-rate monitors.

### [physics_server_direct_body.gd](scripts/physics_server_direct_body.gd)
Direct PhysicsServer2D RID management for peak performance in massive physics simulations.

### [move_and_collide_precision.gd](scripts/move_and_collide_precision.gd)
Expert bounce and friction logic implementation for precision-critical movement.

### [continuous_collision_detection.gd](scripts/continuous_collision_detection.gd)
Advanced CCD management for preventing bullet tunneling at extremely high velocities.

### [performance_batch_mover.gd](scripts/performance_batch_mover.gd)
Optimized batch movement for multiple static/animatable bodies using riders-aware logic.

---

## Collision Layers & Masks (Bitmask Deep Dive)

### The Mental Model

```gdscript
# collision_layer (32 bits): What broadcast channels am I transmitting on?
# collision_mask (32 bits): What broadcast channels am I listening to?

# Example: Player vs Enemy
# Player:
#   layer = 0b0001 (Channel 1: "I am a player")
#   mask  = 0b0110 (Channels 2+3: "I listen for enemies and walls")
# Enemy:
#   layer = 0b0010 (Channel 2: "I am an enemy")
#   mask  = 0b0101 (Channels 1+3: "I listen for players and walls")
```

### Bitmask Helpers

```gdscript
# ✅ GOOD: Use helper functions for clarity
func setup_player_collision() -> void:
    # I am layer 1
    set_collision_layer_value(1, true)
    
    # I detect layers 2 (enemies) and 3 (world)
    set_collision_mask_value(2, true)
    set_collision_mask_value(3, true)

# ✅ GOOD: Bit shift for programmatic layer math

From bgrenat/godot-game-dev-studio, LGPL-3.0.

More from bgrenat/godot-game-dev-studio