# Physics Kernel Workshop

A from-scratch, test-driven path to a working 2D **swept collision** engine —
the same kind that lives in `nage`, but stripped of rendering, scenes, ECS, and
every other distraction. Just the physics, one tiny step at a time.

## How it works (LeetCode style)

Each folder under `steps/` is one self-contained kata:

- `README.md` — the concept (taught from zero) and the task.
- a stub file — the function(s) **you** implement. They start by `throw`ing.
- a `*.test.ts` file — the validator. Red until you implement it, green when
  you're done.
- sometimes a `given.ts` — prerequisites from earlier steps, already finished,
  so you only ever implement the **one new idea** of this step.

### Run one step

From the project root:

```sh
bun test workshop/steps/01-vectors
```

Red (failing) is the starting state. Implement the stub until it goes green,
then ping me and I'll validate + unlock the next batch.

> Skip nothing silently, but blast through what you already know — the early
> steps are deliberately trivial so the test loop becomes muscle memory before
> the hard rungs.

## The ladder

Each rung is a concept that the real `nage` physics depends on. We climb until
the top rung _is_ a working engine.

**Batch 1 — foundations (these files exist now):**

- [x] `01-vectors` — vectors as pairs of numbers: add, sub, scale
- [x] `02-vectors-length` — length, normalize (and the zero-vector trap), dot
- [x] `03-integration` — `pos += vel * delta`, and why framerate independence
      matters
- [x] `04-aabb` — axis-aligned boxes, point-in-box, box overlap (the _discrete_
      test)
- [x] `05-sweep-1d` — the **entry/exit time** of a moving point against an
      interval. The seed of everything.

**Batch 2 — the swept core (these files exist now):**

- [x] `06-ray-vs-aabb` — combine two 1D sweeps into one: ray vs box, with the
      surface **normal**
- [x] `07-swept-aabb` — the **Minkowski** trick: shrink the moving box to a
      point, reuse step 06

**Batch 3 — response (these files exist now):**

- [x] `08-resolve` — stop at the moment of contact (`t`), not after
- [x] `09-slide` — subtract the into-the-wall part of velocity and keep going
      along the wall

**Batch 4 — the real loop + payoff (these files exist now):**

- [x] `10-move-and-slide` — the full loop: multiple obstacles, iteration cap
      (relative velocity explained)
- [x] `11-capstone` — a canvas demo (no test — just run it and play)

**Batch 5 — hardening (unlocked by your own capstone finds):**

- [x] `12-overlap` — the overlap trap: why positions go `NaN` when you start
      inside a collider, and the depenetration (minimum-translation-vector) fix
- [ ] `13-crush` — when one push lands you in the next wall: iterative
      depenetration, and the honest answer for gaps narrower than the hero

When step 11 is green you'll have re-derived your own engine's heart — and
walking back into `sweptAABB` should feel like reading your own handwriting
again.