Documentation — a world model for the paddle game, in four tiers
Read in order. Each document is self-contained enough to be read alone, but they build on one another. New to world models? Every term is defined in the glossary.
Start here
If you have 10 minutes. Read 00 — the big picture for what a world model is and what V, M and C are, then 05 — results and lessons §1–2 for what the v1 tier actually demonstrated. That is the whole recipe, once, end to end. If a term stops you, it is in the glossary.
If you have an hour. Add the four tier summaries, which are the shortest path to what the project as a whole found:
- 05 — results and lessons — v1: the recipe works
- v2-04 — results and lessons and v2-06 — C in the fixed dream — an appearance → dynamics causal edge, and the conserved quantity that had to be fixed before the policy could use it
- v3.1-09 — results and lessons — memory that pays off in play, and the honest negative in v3-05 that forced the re-design
- v4-03 — results and retrospective — inference beats memory, and what four tiers established
Then pick whichever mechanism you want the detail on. The technical run logs
(exact commands, wall clock, every number) are indexed in
../wm/README.md.
| # | document | one line |
|---|---|---|
| 00 | The big picture | What a world model is, the V-M-C recipe, how this repo maps onto it |
| 01 | The environment and the data | The game, why it looks the way it does, how data was collected |
| 02 | V: the vision model | The VAE, posterior collapse, what the latent space actually encodes |
| 03 | M: the dynamics model | The MDN-RNN, dreams, where velocity lives, counterfactuals |
| 04 | C: the controller | Training a policy inside the dream, transfer to the real game |
| 05 | Results, lessons, next steps | Everything in one place, and the plan for v1.1 / v2 |
| — | Glossary | Every term used above |
v2 — mass from colour (an appearance → dynamics causal edge)
| # | document | one line |
|---|---|---|
| v2-00 | Design | The hypothesis, the world change, the planned experiments |
| v2-01 | Environment, data, V | Colour encodes mass; speed becomes decodable from a single frame |
| v2-02 | M and the causal tests | Cold-start speed from colour, repaint-and-redream, interpolation — against a colour-blind control |
| v2-03 | C by mass | Uniform skill across a 4× speed range; the mass-blind v1 policy ties it; colour drifts in stochastic dreams |
| v2-04 | Results and lessons | v2 in one page, and the plan for v3 |
| v2-05 | Fixing the colour drift | A conserved quantity diffuses in sampled dreams; a conservation metric and three fixes compared |
| v2-06 | C in the fixed dream | Oracle-level skill across masses; the repaint intervention shows the agent uses colour |
v3 — the occlusion band (object permanence)
| # | document | one line |
|---|---|---|
| v3-00 | Design | Hide the ball; position must be carried in memory |
| v3-01 | Environment, data, V | A frame knows the ball’s position when visible and nothing when hidden; no hallucinations |
| v3-02 | M and the permanence tests | Vertical permanence yes, horizontal no — and the mechanism |
| v3-03 | Trying to fix permanence | A privileged ceiling shows it is an objective problem; fair fixes get halfway |
| v3-04 | C: acting on memory | A memoryless oracle catches 99%: the default band does not require permanence |
| v3-05 | Results and lessons | v3 in one page, and what to change before v4 |
| v3.1-06 | Design: making memory matter | An oracle sweep first: band (0.13, 0.63), paddle 0.16 — memoryless bound 0.48 |
| v3.1-07 | Environment, V, M | Encoder confound removed; horizontal memory arrives, the exit clock is lost, the dream stops letting the ball out |
| v3.1-08 | C: does memory buy play? | +0.22 over the memoryless bound, flat across required moves; the h-ablation control sits exactly on the bound |
| v3.1-09 | Results and lessons | v3.1 in one page, the project after three tiers, and v4 |
| v3.1-10 | Exit clock and second seeds | A counter head learns the past, not the future; two seeds keep the headline and drop the details |
v4 — the gravity switch (a bit set by an event, held indefinitely)
| # | document | one line |
|---|---|---|
| v4-00 | Design | A hidden gravity sign flipped by paddle contact; LSTM vs transformer |
| v4-01 | Environment, sweeps, data | Two oracle sweeps show the sign never matters for play — with a closed form; v4 becomes a dynamics tier |
| v4-02 | M: LSTM vs transformer | Neither remembers the flip; both infer the sign from curvature; the flip counterfactual is at chance |
| v4-03 | Results and retrospective | v4 in one page, and what four tiers established |
See it live. python -m wm.live opens a window with the real game (arrow
keys) next to what the VAE sees, what the RNN predicted this frame would look
like, and a free-running dream that drifts until you re-sync it. A hands
control to the dream-trained controller. python -m wm.live --record out.gif
--autopilot produces the same thing as a GIF without pygame; an example is
runs/live_demo_autopilot.gif.
Technical run logs with exact commands and every number, written by the
implementing agents and reviewed: ../wm/README_M.md,
../wm/README_C.md; for v2: ../wm/README_V2.md, ../wm/README_M2.md, ../wm/README_C2.md, ../wm/README_FIX.md, ../wm/README_C2_FIX.md; for v3: ../wm/README_V3.md, ../wm/README_M3.md, ../wm/README_FIX3.md, ../wm/README_C3.md; for v3.1: ../wm/README_V31.md, ../wm/README_C31.md, ../wm/README_CLOCK31.md, ../wm/README_C31_SEEDS.md; for v4: ../wm/README_M4.md. The environment’s own notes:
../worldsim/worldsim.md.