Game Physics skill for Claude Code

# Collision detection reference

Hand-rolled collision code for 2D games and custom engines. Examples are TypeScript but
translate directly to C#, C++, GDScript, or Rust. All boxes are axis-aligned unless noted.

```ts
type Vec2 = { x: number; y: number };
type AABB = { minX: number; minY: number; maxX: number; maxY: number };
```

## Overlap tests (discrete)

```ts
const aabbOverlap = (a: AABB, b: AABB) =>
  a.minX < b.maxX && a.maxX > b.minX && a.minY < b.maxY && a.maxY > b.minY;

function circleVsAabb(c: Vec2, r: number, b: AABB): boolean {
  const px = Math.max(b.minX, Math.min(c.x, b.maxX));   // closest point on box
  const py = Math.max(b.minY, Math.min(c.y, b.maxY));
  const dx = c.x - px, dy = c.y - py;
  return dx * dx + dy * dy < r * r;                     // compare squared, no sqrt
}
```

Use strict `<` so touching boxes do not count as overlapping; otherwise a character
resting exactly on the floor registers a collision every frame.

## Minimum translation vector for AABBs

```ts
function aabbMtv(a: AABB, b: AABB): Vec2 | null {
  const ox = Math.min(a.maxX, b.maxX) - Math.max(a.minX, b.minX);
  const oy = Math.min(a.maxY, b.maxY) - Math.max(a.minY, b.minY);
  if (ox <= 0 || oy <= 0) return null;
  const ac = (a.minX + a.maxX) / 2 - (b.minX + b.maxX) / 2;
  const bc = (a.minY + a.maxY) / 2 - (b.minY + b.maxY) / 2;
  return ox < oy ? { x: ac < 0 ? -ox : ox, y: 0 } : { x: 0, y: bc < 0 ? -oy : oy };
}
```

Push out along the smaller overlap axis. Resolving X and Y in separate passes (move X,
resolve X; move Y, resolve Y) avoids the classic "snag on the corner between two floor
tiles" bug that single-pass MTV resolution produces on tilemaps.

## Swept AABB (continuous, prevents tunneling)

Treat the moving box as a point by expanding the static box by the mover's half-size
(Minkowski sum), then cast a ray from the mover's center along its displacement using
the slab method.

```ts
type Hit = { t: number; normal: Vec2 };

function sweptAabb(mover: AABB, delta: Vec2, target: AABB): Hit | null {
  const hw = (mover.maxX - mover.minX) / 2, hh = (mover.maxY - mover.minY) / 2;
  const ox = mover.minX + hw, oy = mover.minY + hh;
  const minX = target.minX - hw, maxX = target.maxX + hw;
  const minY = target.minY - hh, maxY = target.maxY + hh;

  let tEnterX: number, tExitX: number, tEnterY: number, tExitY: number;
  if (delta.x === 0) {
    if (ox <= minX || ox >= maxX) return null;
    tEnterX = -Infinity; tExitX = Infinity;
  } else {
    const t1 = (minX - ox) / delta.x, t2 = (maxX - ox) / delta.x;
    tEnterX = Math.min(t1, t2); tExitX = Math.max(t1, t2);
  }
  if (delta.y === 0) {
    if (oy <= minY || oy >= maxY) return null;
    tEnterY = -Infinity; tExitY = Infinity;
  } else {
    const t1 = (minY - oy) / delta.y, t2 = (maxY - oy) / delta.y;
    tEnterY = Math.min(t1, t2); tExitY = Math.max(t1, t2);
  }

  const tEnter = Math.max(tEnterX, tEnterY);
  const tExit = Math.min(tExitX, tExitY);
  if (tEnter > tExit || tEnter < 0 || tEnter > 1) return null;   // no hit this step

  const normal = tEnterX > tEnterY
    ? { x: delta.x > 0 ? -1 : 1, y: 0 }
    : { x: 0, y: delta.y > 0 ? -1 : 1 };
  return { t: tEnter, normal };
}
```

Resolution with sliding (run up to 3 iterations per step):

1. Find the earliest hit among candidate colliders (broadphase over the swept bounds:
   union of start and end boxes).
2. Move by `delta * t` minus a small skin (e.g. 0.001 units) so you never end touching.
3. Remove the velocity component into the normal: `v -= dot(v, n) * n`.
4. Repeat with the remaining displacement `delta * (1 - t)` projected the same way.

If `tEnter < 0` and the boxes already overlap, fall back to the MTV push-out; that case
means a previous step left them interpenetrating.

## Ray vs circle

```ts
function rayCircle(o: Vec2, d: Vec2, c: Vec2, r: number): number | null {
  const mx = o.x - c.x, my = o.y - c.y;
  const a = d.x * d.x + d.y * d.y;
  const b = mx * d.x + my * d.y;
  const cc = mx * mx + my * my - r * r;
  const disc = b * b - a * cc;
  if (disc < 0) return null;
  const t = (-b - Math.sqrt(disc)) / a;   // nearest root; d need not be normalized
  return t >= 0 && t <= 1 ? t : null;     // t in units of d (one step's displacement)
}
```

For bullets, cast this per step from the previous to the next position instead of
testing overlap at the end position.

## SAT for oriented boxes and convex polygons (2D)

Two convex shapes are disjoint if and only if some axis separates their projections.
For polygons, the candidate axes are the edge normals of both shapes (a box contributes 2
unique normals).

```ts
function project(pts: Vec2[], ax: Vec2): [number, number] {
  let min = Infinity, max = -Infinity;
  for (const p of pts) { const s = p.x * ax.x + p.y * ax.y; if (s < min) min = s; if (s > max) max = s; }
  return [min, max];
}

function satMtv(a: Vec2[], b: Vec2[]): { axis: Vec2; depth: number } | null {
  let best = { axis: { x: 0, y: 0 }, depth: Infinity };
  for (const poly of [a, b]) {
    for (let i = 0; i < poly.length; i++) {
      const p = poly[i], q = poly[(i + 1) % poly.length];
      const len = Math.hypot(q.y - p.y, p.x - q.x);
      const ax = { x: (q.y - p.y) / len, y: (p.x - q.x) / len };   // edge normal
      const [a0, a1] = project(a, ax), [b0, b1] = project(b, ax);
      const overlap = Math.min(a1, b1) - Math.max(a0, b0);
      if (overlap <= 0) return null;                              // separating axis found
      if (overlap < best.depth) best = { axis: ax, depth: overlap };
    }
  }
  // orient the axis to push a away from b
  const ca = centroid(a), cb = centroid(b);
  if ((ca.x - cb.x) * best.axis.x + (ca.y - cb.y) * best.axis.y < 0) best.axis = { x: -best.axis.x, y: -best.axis.y };
  return best;
}
const centroid = (p: Vec2[]) => p.reduce((s, v) => ({ x: s.x + v.x / p.length, y: s.y + v.y / p.length }), { x: 0, y: 0 });
```

In 3D, SAT for boxes needs 15 axes (3 + 3 face normals plus 9 edge cross products); use
GJK/EPA or the engine instead of hand-writing it.

## Uniform spatial hash (broadphase)

```ts
class SpatialHash<T> {
  private cells = new Map<number, T[]>();
  constructor(private size: number) {}
  private key(cx: number, cy: number) { return ((cx & 0xffff) << 16) | (cy & 0xffff); }
  clear() { this.cells.clear(); }
  insert(item: T, b: AABB) {
    for (let cx = Math.floor(b.minX / this.size); cx <= Math.floor(b.maxX / this.size); cx++)
      for (let cy = Math.floor(b.minY / this.size); cy <= Math.floor(b.maxY / this.size); cy++) {
        const k = this.key(cx, cy);
        (this.cells.get(k) ?? this.cells.set(k, []).get(k)!).push(item);
      }
  }
  query(b: AABB, out: Set<T>) {
    for (let cx = Math.floor(b.minX / this.size); cx <= Math.floor(b.maxX / this.size); cx++)
      for (let cy = Math.floor(b.minY / this.size); cy <= Math.floor(b.maxY / this.size); cy++)
        for (const it of this.cells.get(this.key(cx, cy)) ?? []) out.add(it);
  }
}
```

- Cell size around twice the typical object size. Objects much larger than a cell land in
  many cells; keep them in a separate list or a second, coarser grid.
- Rebuild every step for moving objects (cheap) or update only movers.
- The 16-bit key packing wraps at 65,536 cells per axis; use a string or BigInt key for
  larger worlds.
- Deduplicate pairs (`a.id < b.id`) when generating pair lists.

## Choosing narrowphase shapes

| Shape pair | Test |
|---|---|
| Circle-circle, sphere-sphere | Distance squared vs (r1 + r2) squared |
| Capsule-capsule | Closest points between two segments, then radius test |
| AABB-AABB | Interval overlap per axis |
| OBB/polygon (2D) | SAT |
| Convex-convex (3D) | GJK for distance/overlap, EPA for penetration depth |
| Anything vs triangle mesh | BVH over triangles, then per-triangle test |