game-collision

name	game-collision
description	Make browser-game objects ACTUALLY solid — the fix for the

Game Collision — if it looks solid, it IS solid

This is the skill that exists because AI games are full of ghosts: a rock is drawn, but there's no rock — just pixels. You asked for a wall and got wallpaper. Drawing a thing is not making a thing. Every object that should block, hit, or carry the player must own a collision body that the movement code actually checks — and you must have seen that body with your own eyes in the debug overlay.

The Prime Directive

A visual is not a collider. A collider is not a visual. Every solid object needs BOTH, explicitly wired together — and verified in the debug overlay before you trust it.

If you can't point to the line that registered the rock's body, and see its box drawn on screen, the rock does not exist as far as the player is concerned. No exceptions.

BANNED (every one of these is a walk-through-the-rock bug waiting to happen)

• Drawing a sprite and calling it solid. drawImage(rock, x, y) with no body created, no collider added. This is the bug. The asset exists; the obstacle doesn't.
• Whole-sprite hitboxes in top-down. Making the entire tree/house image collidable → an invisible wall around the canopy, and the player can't walk behind it. Collision is the footprint (trunk base), not the picture.
• Collision you've never rendered. Shipping hitboxes you can't see. If the debug overlay isn't wired first, you're guessing.
• Moving both axes then testing once. Resolving X and Y together makes the player stick on walls and catch on corners. Move and resolve per axis.
• Teleporting fast objects in one step. Bullets/dashes moving farther per frame than a wall is thick → tunneling straight through. Sweep or substep.
• Checking every pair (O(n²)). Fine at 20 objects, death at 500. Broad-phase with a grid/quadtree before narrow-phase.
• Trusting overlap for solids. Detecting an overlap is not resolving it. A solid must push out, not just report.
• Physics engine for grid movement. Importing Matter/Rapier to stop a top-down player at a wall — jittery, heavy, wrong. Tilemap layer + AABB.

The mental model: three separate things

For every game object, keep these distinct and know which you're touching:

1. Sprite / mesh — what you SEE. Position is for rendering.
2. Collider / body — what COLLIDES. Often smaller than the sprite (the footprint). This is what movement checks.
3. Depth / sort key — what decides DRAW ORDER (who's in front). In top-down, this is the object's baseline Y, independent of the collider.

AI failure = collapsing these into one rectangle. A tree has a big sprite, a tiny trunk-base collider, and a sort key at its feet. Three different rectangles. Get them separate and the "walk behind the tree, but can't walk through its trunk" behaviour falls out for free.

Process (build collision before art, always)

1. Wire the debug overlay FIRST — tools/collision-debug.js. Draw every collider, every frame, before there's anything to collide. You will use this constantly; without it you're blind.
2. Give every solid a real body. Static bodies for walls/rocks/props; dynamic/kinematic for movers. In Phaser: this.physics.add.existing, setImmovable, static groups. In Rapier/3D: a Collider on a RigidBody. The rule from references/solid-bodies.md: no solid ships without a body you can see.
3. Set the footprint, not the sprite bounds — references/topdown-collision.md. Shrink and offset the body to the object's base. Player collides at the feet.
4. Pick the resolution model for the genre:
   • Top-down → footprint AABB/circle vs tilemap collision layer + static bodies, axis-separated. references/topdown-collision.md
   • Platformer → swept AABB vs solid tiles, one-way platforms, grounded check. references/platformer-collision.md
   • Physics gameplay / 3D → let Rapier/Havok own bodies; you own triggers and rules.
5. Make fast things safe — cap per-step displacement, sweep or substep so nothing tunnels. references/tunneling-ccd.md.
6. Add depth (top-down) — y-sort so tall objects draw over the player when he's above them, under when below. references/topdown-collision.md.
7. Broad-phase before it's slow — a uniform grid or quadtree so collision cost scales. references/tunneling-ccd.md + game-optimization.
8. Verify by attack, not by hope — walk into every wall from every side; sprint at the thinnest wall; stand on every platform; check you can walk behind tall props but not through their base. Toggle the overlay and confirm every collider matches its art.

Axis-separated resolution (the anti-stick rule)

Never move diagonally and resolve once. Do:

1. Move X by vx * dt. Check collisions. If overlapping a solid, push back out along X only. Zero vx if you want a hard stop.
2. Move Y by vy * dt. Check collisions. Push out along Y only. This makes the player slide along a wall he's pressing into diagonally, instead of sticking. It also makes "am I on the ground" (a Y-axis result) clean. Reference resolver: tools/aabb-resolver.js.

The collision checklist (before claiming solid)

• Debug overlay wired and toggled — every collider is visible and matches its art
• Every "solid" object has a body registered with the collision system (you can name the line)
• Top-down bodies are footprints (base of the object), not full sprites
• Resolution is per-axis — the player slides along walls, doesn't stick or catch corners
• Fastest projectile/dash cannot pass through the thinnest wall (swept/substepped)
• Tall objects y-sort: player walks behind their tops, collides only with their base
• Broad-phase in place (grid/quadtree) — collision cost doesn't explode with entity count
• Solids push out (resolve), triggers only report (overlap) — and you used the right one for each

Tools & references

• tools/collision-debug.js — drop-in overlay: draws every collider, hitbox, and velocity vector. Framework-agnostic + Phaser notes.
• tools/aabb-resolver.js — correct axis-separated swept-AABB move-and-resolve, plus a uniform-grid broad-phase.
• references/solid-bodies.md — the sprite≠body rule in Phaser, Rapier, and Three.
• references/topdown-collision.md — footprints, tilemap collision layers, y-sort depth.
• references/platformer-collision.md — swept AABB, one-way platforms, grounded, slopes.
• references/tunneling-ccd.md — fast movers, sweeping, substeps, CCD, broad-phase.