Game Physics skill for Codex

Done well means: physics steps at a fixed rate, bodies use the simplest shape that plays right, fast movers cannot tunnel, collision filtering is declared in one table, characters use a controller designed for game feel rather than a pushed rigid body, and the result is the same on every machine that needs it to be.

Before changing anything

1. Read AGENTS.md; identify the physics in use (engine built-in, library version, or custom).
2. Find the step: what rate, fixed or variable, how many substeps or solver iterations.
3. Check units. Most engines are tuned for metres, kilograms and seconds with objects 0.1-10 m. A world built in pixels (64 px = 1 tile) must be scaled into metres for Box2D, Rapier, Matter-like tuning, or bodies behave like giant slow objects.
4. Turn on the debug draw before touching parameters. Most “physics bugs” are shapes that do not match the art.

Choosing physics

Need	Choice
Platformer, top-down, tile-based movement with tight feel	Custom AABB vs tilemap or a kinematic character controller; no rigid bodies for the player
2D rigid bodies (stacking, ragdolls, joints)	Box2D v3 (C), Rapier2D (Rust/WASM JS), engine built-in
3D rigid bodies	Engine built-in: Unity PhysX, Unreal Chaos, Godot Jolt (built in from 4.4; check which engine the project selects) or GodotPhysics; Rapier3D or Jolt standalone
Browser 2D with simple needs	Phaser Arcade (AABB), Matter.js for rotation and joints
Browser 3D	Havok (Babylon), Rapier (WASM), cannon-es for light needs
Cross-platform determinism (lockstep, rollback)	Rapier with enhanced-determinism feature, or custom fixed-point; never assume the engine is deterministic across platforms

Collision pipeline

1. Broad phase prunes pairs: uniform grid or spatial hash for similar-size objects, dynamic AABB tree (what engines use) for mixed sizes, sweep-and-prune for mostly 1D spread.
2. Narrow phase tests actual shapes: AABB, circle, capsule, convex polygon (SAT or GJK).
3. Resolution: compute contact normal and penetration, separate along the minimum translation vector, then resolve velocity along the normal.

Custom AABB vs tiles, resolved one axis at a time (the platformer standard):

function moveAndCollide(body: Body, dt: number, solid: (tx: number, ty: number) => boolean) {
  body.x += body.vx * dt;
  for (const t of tilesOverlapping(body)) {
    if (!solid(t.x, t.y)) continue;
    if (body.vx > 0) body.x = t.x * TILE - body.w;
    else if (body.vx < 0) body.x = (t.x + 1) * TILE;
    body.vx = 0;
  }
  body.y += body.vy * dt;
  body.grounded = false;
  for (const t of tilesOverlapping(body)) {
    if (!solid(t.x, t.y)) continue;
    if (body.vy > 0) { body.y = t.y * TILE - body.h; body.grounded = true; }
    else if (body.vy < 0) body.y = (t.y + 1) * TILE;
    body.vy = 0;
  }
}

Resolving X then Y separately avoids the corner-snagging that happens when resolving both axes from one penetration vector. Cap per-tick movement below one tile size, or sweep in substeps, so a fast body cannot skip a tile.

Tunnelling

A body moving more than its own thickness per step can pass through thin walls.

Fix	Use when
Enable CCD on the fast body (Unity CollisionDetectionMode.ContinuousDynamic, Box2D isBullet, Rapier ccd_enabled, Godot continuous_cd)	Bullets, fast balls; costs per body
Raycast / shape cast along the motion for projectiles	Hitscan or very fast projectiles; cheaper than CCD
Thicker static colliders	Level geometry, always good practice
Smaller fixed step or substeps	Whole simulation unstable; costs everything

Layers and masks

Declare the matrix once, as a table in code or the engine’s project settings, and name layers:

Layer	Collides with
World	Player, Enemy, PlayerProjectile, EnemyProjectile
Player	World, Enemy, EnemyProjectile, Pickup (trigger)
Enemy	World, Player, PlayerProjectile
PlayerProjectile	World, Enemy
EnemyProjectile	World, Player

Projectiles that do not collide with their own side remove whole categories of bugs and halve pair counts. Triggers/sensors detect overlap without a physical response.

Character controllers

Do not drive a player by applying forces to a dynamic rigid body unless the game is physics-driven (rolling ball, ragdoll party game). Use:

• Unity: CharacterController or a kinematic Rigidbody with your own sweep (Rigidbody.SweepTest, Physics.CapsuleCast).
• Godot: CharacterBody2D/3D with move_and_slide(), tune floor_max_angle, floor_snap_length.
• Unreal: UCharacterMovementComponent.
• Rapier: KinematicCharacterController (slopes, steps, snap to ground).

Game-feel rules to implement in the controller, not in physics materials: acceleration and deceleration curves, variable jump height (cut upward velocity on release), coyote time, jump buffering, ground snapping on slopes and steps, and zero friction against walls (or wall contacts stop gravity and the player “sticks”).

Stability

Symptom	Fix
Stacks jitter or creep	More solver iterations (or substeps in Box2D v3), allow bodies to sleep, avoid extreme mass ratios (> 1:10 between touching bodies)
Objects explode apart on spawn	Spawned overlapping; spawn in free space or enable over time
Joints stretch	Mass ratio too high, too large step; increase iterations or substeps
Small objects vibrate	Shapes too small for the units; scale the world into metres
Bouncing never stops	Restitution near 1 plus solver error; lower restitution, raise sleep thresholds

Mesh colliders on moving bodies are slow and unstable; use convex hulls or compound primitives.

Determinism

• Same binary, same platform, same inputs, same step order: most engines are deterministic.
• Across CPUs, compilers or OSes: floating point differs (FMA contraction, -ffast-math, SIMD paths, transcendental functions). Use a library with an explicit cross-platform determinism mode, or fixed-point math in your own simulation.
• Never step physics with a variable dt; never iterate bodies from an unordered set; seed every RNG.

Verification

• Debug draw on: every collider matches its art; trigger volumes are where design expects.
• Fire the fastest projectile at the thinnest wall at max speed 100 times: zero pass-throughs.
• Stack 10 boxes and leave it 60 seconds: no creep, bodies fall asleep.
• Run the same input recording twice (and on two machines if determinism is claimed): position hashes match at every 60th tick.
• Profile physics step time at peak body count against the frame budget.

Hand-off summary

**Physics:** Godot 4 with Jolt, 60 Hz physics ticks, world in metres (1 tile = 0.5 m)
**Changes:** CCD on bullets; layers World/Player/Enemy/PlayerShot/EnemyShot matrix; player on CharacterBody3D with 8-tick coyote time
**Fixed:** crates jittering (mass ratio 1:50 -> 1:5, sleep enabled)
**Checks:** 100/100 bullets stopped by 0.1 m wall; 10-box stack stable 60 s; physics 1.8 ms at 300 bodies