nage/workshop/README.md

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 throwing.
• 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:

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):

• 01-vectors — vectors as pairs of numbers: add, sub, scale
• 02-vectors-length — length, normalize (and the zero-vector trap), dot
• 03-integration — pos += vel * delta, and why framerate independence matters
• 04-aabb — axis-aligned boxes, point-in-box, box overlap (the discrete test)
• 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):

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

Batch 3 — response (these files exist now):

• 08-resolve — stop at the moment of contact (t), not after
• 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):

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

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

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