@origingame/engine 0.0.0-stage → 0.1.0

package/knowledge/skills/og-build/SKILL.md

@@ -0,0 +1,330 @@
+---
+name: og-build
+description: The Origin Engine build loop — og cook, og run with a scripted command channel (inputs, captures, dumps, get and set), screenshots and world dumps read as evidence, og dev hot reload, og test playtests, og polish's taste and feel scores (the one list of what it measures and where each finding is fixed), og build for publishing, og run --device for the first frame and frame times on a real browser or phone, and big games: streaming groups and what they may hold, .vox models, compressed animation, chunked music, the lanes and cross-origin isolation. Use whenever a change to a project with a project.ogt must be run, observed, scored or shipped (not a Godot project.godot).
+---
+
+The `og` tool is the whole loop: it cooks assets, runs the game headless on
+the native host with a command script, serves the probe, reloads on save,
+runs playtests, scores them and builds the publishable bundle. Nothing here
+needs a browser or a Rust toolchain. The command channel is
+`reference/commands.md`, the probe `reference/probe.md`.
+
+## What works
+
+The loop held for two whole games written from this package alone
+(`examples/lantern-vale`, `examples/hollowbell`): `og cook` took 47 and 69
+assets cold in 8.2 s and 3.6 s and under 100 ms after a change, without a
+warning, and every refusal named the line and the fix (a copied skin
+without its CJK `fallback` named the line and og-taste §1;
+`PostEffects.vignette is true or false` named the line). Scripted runs gave
+the same frames every time, `store: "keep"` relaunches and two-process
+replays worked the first time they were asked for, and `og polish` scored
+taste 99 for both and feel 90 and 92, naming the section that fixes each
+finding. The third, The Kestrel Stair (`examples/kestrel-stair`, 3D
+third-person), cooked 62 assets cold in 8.5 s (110 outputs, 9.9 MB) and
+about 0.1 s after a change, without a warning, its refusals naming the
+line; two processes of a full session (chases, bites, strikes, a rest, the
+gate, the bell) ended on one world hash, and `og polish` found every
+input answered within a tick and every damage moment with hit stop, shake,
+a number and a sound (taste 98, feel 79).
+
+## 1. The loop
+
+1. **Cook** after any change under `assets/`: `og cook`. It is incremental
+   (only changed sources re-cook) and writes `cooked/`, the only thing the
+   runtime reads. A load that names an uncooked path, or a blob whose cook
+   stamp does not match the manifest, is refused with the path; cook again.
+2. **Run with a script**: `og run . --headless --commands "<script>"`. The
+   script is `t:action[:args];...` with `t` in simulation seconds from the
+   start of the run, so the same script always lands on the same ticks:
+
+   ```sh
+   og run . --headless --seed 1 --commands "0.5:touch_move_to:Start;0.6:touch_start;0.7:touch_end;2.0:screenshot;2.2:dump_world;2.5:quit"
+   ```
+
+   Core actions: `screenshot[:path][:full|:N]`, `listen[:path][:seconds]`,
+   `touch_move_to:<ui id>`, `move_to_text:[=]text[@N]`, `touch_move:x,y`,
+   `touch_start`, `touch_end`, `touch:<id>:<down|move|up>:<x,y | ui id>`
+   (a second finger), `gamepad:<a+b+...|->[@pad][:lx,ly][:lt,rt]`, `scroll:dx,dy`,
+   `key_down:<Key>`, `key_up:<Key>`, `type:<text>`, `compose:<text>` and
+   `commit:<text>` (an input method, og-ui §7),
+   `teleport:<entity>:x,y,z`, `frame_entity:<entity>`, `dump_world[:path]`,
+   `dump_entity:<entity>[:path]`, `dump_ui[:path]`,
+   `get:<Resource>[.<field>]` or `get:<entity>[.<Component>[.<field>]]`
+   (logs the value as game code sees it, og.Time whole and a light og.DayNight
+   drives as it is drawn, and writes `get-<tick>.json`, then
+   `get-<tick>-2.json`, ... for more on one tick; a world dump lists
+   resources by name only, so `get:` is how to read one),
+   `set:<entity>.<Component>.<field>=<value>` or
+   `set:<Resource>.<field>=<value>` (`set:og.Camera.trauma=0.5`,
+   `set:Game.coins=10`, `set:og.Stylise.ink=false`: a number, `true` or
+   `false`, or `x,y,z`; a value outside the field's `min`/`max` is refused
+   naming the range, never clamped, while game code's own writes are stored
+   as given: widen the range in the field's options to try one), `seed:<n>`, `pause`, `resume`, `advance:<ticks>`,
+   `quit`, and `help` for the list. Modules add their own: `dump_ai` and
+   `dump_nav` (og-ai §5), `dump_platform` (og-platform-sdk §4), `locale:<tag>`
+   (og-i18n §6), `dump_stream` and `terrain_stream:<stream|resident>[:<MiB>]`
+   (og-game §6 and §11). Unknown actions warn and the script continues; read the
+   warnings.
+3. **Read what it wrote.** Screenshots are PNG files, dumps are JSON files
+   (`<action>-<tick>.png|json` unless the step names a path), written
+   under `og-out/` in the project (`--out <dir>` chooses); `og run`
+   prints each path. Open the frame and describe what it shows; read
+   `dump_world` for the entity count, the archetype tables and each system's
+   matched count. A system that matched 0 entities is usually a missing
+   component on the spawn, not a logic bug.
+
+   Where there is no renderer (a sandbox with no GPU: `og run --json` says
+   `"tier": "none"`, `og doctor` says the renderer is `none`), the run is
+   the same run: the same ticks, dumps and world hash. A `screenshot`
+   writes no PNG and logs "no renderer, frame unchecked" with the file it
+   would have written, not as a warning; `og run --json` lists those files in
+   `unchecked`, and the probe's `capture` answers null. Read the dumps
+   there, and look at the frames where there is a renderer (§4).
+4. **Fix and repeat** with the same script and seed. Keep the script in the
+   change so the next run is the same run.
+
+A game's own actions (`GameDesc.commands`, og-game §3) join the list; give
+each its argument form and one sentence in `GameDesc.commandHelp`
+(`{ spawn_wave: { usage: "<count>", doc: "Spawns a wave now." } }`)
+so `help` explains it (it lists `spawn_wave:<count>`: the name, then the
+usage). An entry naming no action is logged when the game
+starts.
+
+## 2. Live sessions: the probe and hot reload
+
+- `og run .` without `--headless` keeps running and serves the probe over a
+  loopback WebSocket; `og probe <method> [json]` calls it (`og probe hello`,
+  `og probe state`, `og probe dump '{"what":"world"}'`,
+  `og probe capture '{"width":640,"height":360}'`, `og probe patch …`). A
+  refusal is `false` or `null`, never an error; an error means the call was
+  malformed.
+- `og dev .` watches `src/` and `assets/`: it rebuilds the bundle, re-cooks
+  changed assets and reloads the running game through the probe, keeping the
+  world state (components migrate field by field by name). The budget is
+  300 ms from save to the first new frame; `og dev` reports each reload's
+  latency and any dropped components or fields. A reload that fails keeps
+  the old bundle running and prints why.
+
+## 3. Tests
+
+`og test .` runs the project's bun tests and every `tests/*.og.ts` playtest
+script through `og run --headless --commands`. A playtest asserts on what the
+game exposes (dumps, `state()` facts, entity fields, `get` answers), never on
+how the code is written. Each playtest writes into its own
+`og-out/test/<name>/`, emptied when it starts, and its `check` reads a
+step's file by the name the step gave (`run.json("shop.json")`,
+`run.png("title.png")`); give each step's file its own name. A test that ran no checks fails. Run it before
+claiming a change works.
+
+Put every check that reads a frame (`run.png`, a decoded screenshot, a
+comparison with `references/`) inside `t.frame(files, () => ...)`:
+
+```ts
+check(run, t) {
+  t.equal(run.json<Game>("shop.json").coins, 10, "the coin was banked");
+  t.frame(["title.png", "shop.png"], () => checkFrames(run, t, ["title.png", "shop.png"], ""));
+},
+```
+
+Without a renderer (`run.rendered` false, `run.tier` `"none"`) the scope
+does not run: `og test` prints `~ <file>: no renderer, frame unchecked` for
+each screenshot, counts them in its summary (`og test: 7 suite(s) passed;
+9 frame(s) unchecked`) and passes on every other check, which runs as it
+would with a renderer. A check that reads a frame outside `t.frame` stops
+there (the report says the checks after it did not run), so keep frames in
+the scope. Unchecked frames never change `og test`'s exit status; they are
+verified where there is a renderer: the author's machine, the
+browser-check sandbox (the published page, §6) or an executor with a GPU. A playtest runs with the host clock at
+2026-01-01 00:00 UTC (`clock` to change it) and a fresh store; `store:
+"keep"` with `then: [{ commands, clock }]` runs further processes over the
+same store, for a relaunch (og-platform-sdk §4).
+
+## 4. Evidence discipline
+
+- Every change that alters rendering, animation, physics or the tick carries
+  a scripted `og run --commands` run whose frame was opened, read and
+  described in the change: what is on screen, where, and how that differs
+  from before. A frame nobody looked at is not evidence. Where there is no
+  renderer the frame is unchecked, not seen: say so, and look at it where
+  there is one (§3) before calling a visible change done.
+- Name the exact command, seed and script with the frame and the dump, so
+  anyone can rerun it and get the same bytes.
+- Determinism is checkable: two runs with the same seed and script give the
+  same world hash in `dump_world`. When they do not, find the wall-clock
+  read or the unseeded randomness before anything else.
+- Report what ran and what did not. A build that compiled is not a game
+  that plays.
+
+## 5. Polish, measured: `og polish`
+
+This is the one list of what `og polish` measures; og-taste §10 and
+og-feel §13 are the checklists it scores, and every other skill points
+here. `og polish .` plays every playtest headless, samples every tick
+(`dump_pulse`: time scale and hit stop, camera trauma, punch and kick,
+floating texts, afterimages, tweens, particle systems, voices by bus, the
+named entities' positions and flipbook frames, step and render time), takes
+`dump_ui` beside every `screenshot` and captures the audio. It writes
+`og-out/polish/report.md`: a **taste** and a **feel** score (0 to 100 each,
+the mean of their rows; a row is n/a when no playtest exercises it), the
+frames, and for each finding the skill section that fixes it. It refuses a
+project without playtests: write them first (§3), with a `screenshot` on
+every screen that matters.
+
+| Axis | Measure | From | Passes at | Fixed in |
+|---|---|---|---|---|
+| taste | Contrast | each text element's rectangle in a shot: the ground (its median) against its ink, read over the text's own glyphs (the pixels at least half-way to the strongest ink; the farthest twentieth of them, the glyph cores) | 4.5:1 | og-taste §3 |
+| taste | Text size | the tallest run of ink rows in each text element, CSS px | 9 px, a 13 px face's capitals | og-taste §4, §10 |
+| taste | HUD occupancy | the union of leaf elements on gameplay shots, touch controls (joystick, d-pad, action buttons) left out; a shot with a dialog or loading layer, a conversation, a list over a quarter of the surface or three texts in the central third is a screen, not gameplay | at most 15 % of the surface and 5 % of the central third | og-taste §2 |
+| taste | Screen transitions | a change of three or more elements with UI motion or a tween in the 20 ticks around it | every change | og-taste §5 |
+| taste | UI sounds | a press that changed the UI and started a voice on the ui bus within 8 ticks | every press | og-taste §6, og-audio §3 |
+| taste | Locale keys | `og cook`'s warnings | none | og-i18n §1 |
+| feel | Input latency | ticks from the tick an input lands to the first thing seen or heard to change (a named entity accelerating or changing clip, the UI, a sound, a tween, a floating text, shake, hit stop, a particle burst); a press answered on its release counts from the release | 0–1 ticks | og-feel §1 |
+| feel | Hit feedback | each damage moment (a fact named `hp`, `health`, `lives`… falling, or `hits`, `damage`, `kills`… rising): hit stop, shake, floating text and a sound within 8 ticks | three of the four | og-feel §3, §4, §7, og-audio §1 |
+| feel | Idle frames | ticks after the first ten where nothing moves or animates, no UI moves, no sound starts or plays, no tween, text or particle runs | at most 10 % | og-feel §9, og-taste §5 |
+| feel | Sound on input | inputs answered by a sound within 6 ticks | every action | og-audio §1 |
+| feel | Frame time | step + render, p95, on the tier it ran on (`metal` on a Mac, `vulkan` on a GPU); the probe's own screenshots (render, read back, PNG) are not the game's step and are left out. Without a renderer the row says `n/a (no renderer)`, as do contrast, text size and HUD occupancy, which read frames | 8.3 ms (half the frame) | og-game §14 |
+
+The report also lists clipped samples in the mix (og-audio §4). Contrast and
+text size read text only: icons and images (their "text" is a picture's
+name), disabled controls and what they hold (WCAG exempts them), the
+slivers a scroll container cuts, what a dialog's or a tutorial's scrim
+dims on purpose and what is mid-transition in the shot (an element whose
+bounds differ on the ticks before and after it: a toast sliding out over
+a dialog, a panel popping in) are left out, and each element is measured
+at the pixels of the surface `dump_ui` reports, so a phone preview
+(390×844 at 3×) is read at its own size. The ink is measured over the
+glyphs, not the rectangle, so a short word in a wide label (a three-letter
+name on a 356 px leaderboard row) reads what its letters show, as a full
+line does, and not its antialiased edges diluted by the empty rest of the
+row. The ink is what the pixels show,
+so it depends on the glyphs' coverage: thin strokes cover few pixels
+whole, and a regular-weight CJK face at body sizes measures lower than
+Latin in the same colours (a 15 px "设置" 3.1:1 where "Settings" reads
+4.6:1 on one button), as it reads lower to the eye. Darken the ink in the
+skin's palette, give the CJK face a heavier weight or the label a larger
+step; the measure is not wrong there. Facts are the game's `facts`
+(og-game §3): expose `hp`, `hits` or `kills` there or the hit measures stay
+n/a. A baseline line says how often things change with no input at all;
+when it is high (a runner that always moves), read latency together with
+the frames.
+
+The numbers cannot judge a style. Read the frames before changing anything,
+fix the cause in the skin, the template or the system, never per call, and
+run it again after the fix: the report is the evidence.
+
+## 6. Shipping
+
+`og build .` bundles `src/` to `dist/game.js`, cooks, and copies the engine
+runtime and wasm next to it. `og build . --publish` produces the published
+form: the probe keeps only its player-facing members (hello, tick, state,
+pick, entity, input, capture) and the command channel is gone.
+What ships is still checked by script, through what it keeps: real input
+on the published page and the probe's `tick`, `state` and `capture`. A
+playtest written in input steps (`key_down`, `type`, `touch_move_to` an
+id, `move_to_text`, `touch_start`) and `screenshot` steps runs there as it
+runs under `og test`, each frame compared with the same references; a
+game command (warp, give) has no channel there and is refused, so keep
+the steps a published check needs free of them. The engine runs this on
+the published build of its own games (its `tests/web/published.ts`: the
+boot, the title, a press, a typed name and a frame against the metal
+reference, with a clean console).
+`og run --device chrome .` plays that publish build in a real browser
+(`android[:serial]` over adb, `iphone[:udid]` over safaridriver), passes
+the play gate and writes `og-out/device/report.md`: the first frame against
+its budget (2.0 s, 1.5 s on an iPhone), the frame-time percentiles on the
+tier the device chose, the device itself, and a fix per finding (og-game
+§6 for a slow first frame, og-game §14 for missed frames). Run it on the
+phone you ship for: og polish's native numbers are not a phone's. `og doctor`
+names each missing tool (bun, the native addon, the wasm artifact) with its
+fix, and says whether this machine has a renderer (none is not a problem:
+the playtests' frames are then unchecked, §3).
+
+## 7. Big games: what the cook packs and the page fetches
+
+What `og cook` takes is decided by the file: `.glb`/`.gltf` and MagicaVoxel
+`.vox` (meshed into a glTF: flat-shaded quads, palette colours, `model {
+voxScale voxOrigin }` for the size and origin, frames as clips; og-game §5)
+are models; `.ogt` files by their `type` (scene,
+look, environment, texture-array, flipbook, particles, terrain, shader…);
+`.cube` LUTs, `.hex` and `.gpl` palettes, images, WAVs and fonts by
+extension. A look's built-in `@canvas/…` and `@palettes/…` assets are added
+to the bundle only when a look names them; a game's own `assets/@canvas/`
+is refused.
+
+**Streaming groups** (og-game §6) are cooked into one pack each,
+`cooked/stream/<name>.ogb`, and `og build --publish` ships each as its own
+file the page fetches when the group loads. A group may hold glTF models
+without skins or morph targets, textures, texture arrays, sounds,
+environment maps, palettes, looks and LUTs:
+
+```text
+stream "night-market" {
+  asset "models/stalls.glb"
+  asset "env/night.ogt"            # an environment map
+  asset "tiles/market.ogt"         # a texture array
+  asset "palettes/neon.hex"
+  asset "looks/night-market.ogt"   # applied once resident
+  asset "grade/night.cube"
+  volume "market-gate"
+}
+```
+
+A sound cooked in chunks may join a group too: its first chunk goes in
+the pack and every other chunk stays a file of its own, read ahead of the
+playheads once the group is resident (og-audio §5). The cook refuses any
+other kind (a skinned model, a scene) in a group, naming the scene and
+the asset. Prove a group in a script:
+move the camera into its trigger (`teleport`, or the game's own command),
+`advance` a few ticks, then `dump_stream` lists each group's state,
+memory and the assets kept past an unload (`retained`), and
+`get:` of a field the game copies from `og.stream.budget` shows `used` and
+`kept` against `budget`. A run with the same script must end on the same
+world hash streamed or not: nothing a tick reads depends on what is
+resident.
+
+**Size knobs** in a model's or a sound's import settings (`<file>.ogt`,
+`type import`):
+
+```text
+animation {
+  compress true        # quantised clips, keyframes the curve rebuilds dropped
+  tolerance 0.0001     # the most a sampled value may move (og-game §9)
+}
+sound {
+  stream true          # cooked in chunks (the default past 1 MiB of QOA, about 27 s of stereo)
+  chunk 4              # seconds per chunk (og-audio §5)
+}
+```
+
+**What a player downloads** is what `og build --publish` prints under its
+size table, brotli `-q 11` per file as the size gate measures the engine:
+
+```text
+download (brotli-11, what a player fetches; a WebGPU and a WebGL2 page fetch the same files):
+  boot, lanes page (isolated)      92 files     4323854 B  (engine 2976.8 kB, cooked 1044.3 kB, shell 85.5 kB, basis 217.3 kB)
+  boot, single-threaded page       91 files     4284988 B  (engine 2937.9 kB, cooked 1044.3 kB, shell 85.5 kB, basis 217.3 kB)
+  later: 20 sound chunks 2427050 B (ahead of their playheads); the audio worklet 875 B (first gesture); the service worker and icons 32634 B
+```
+
+The boot is everything fetched before the first frame: one engine module
+(the lanes module on a cross-origin isolated page, else the
+single-threaded one), the shell, the Basis transcoder and the cooked first
+group (everything no streaming group holds). A sound cooked in chunks
+costs the boot its first chunk only (about `chunk` seconds of QOA): the
+rest are fetched ahead of its playheads, and none before it plays; in a
+streaming group it costs the boot nothing (its first chunk comes in the
+group's pack). The
+table's `total` is every file of the directory (both engine modules, the
+licences, the icons), never a download. Compare the boot line before and
+after a change; `--json` carries the same as `downloads`.
+
+**The lanes** spread physics, skinning, culling and extraction over the
+cores with results identical to one thread (og-game §14). Natively
+`OG_LANES=off` (or `1`) runs serial and `OG_LANES=<n>` uses n threads; a
+world hash must not change between them, which is a check worth a
+playtest of its own on a physics-heavy game. On the web the lanes need a
+cross-origin isolated page: `project.ogt`'s `publish { isolation
+required | preferred | off }` (`preferred` by default: lanes where the
+host serves COOP/COEP, one thread otherwise, the same game either way).
+The lanes build caps memory at 2 GiB. `dump_lanes` reports what ran where.

package/knowledge/skills/og-core/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: og-core
+description: The rules every Origin Engine game obeys — TypeScript only, a fixed deterministic tick, Results instead of throws, typed views per archetype, no wall clock, and reflection as the one schema. Read before writing or reviewing any code in a project with a project.ogt.
+---
+
+Origin Engine is a Rust engine with a TypeScript API, generated from one IDL
+(`crates/og-api/api.ogt` in the engine repository). The same game bundle runs
+in the browser (wasm in a Worker) and headless on the native host under
+`og run`. These rules are what makes that true; breaking one produces a game
+that works on one host, one seed or one machine and not the next.
+
+## What works
+
+Two games written from this package alone (`examples/lantern-vale`, a 3D
+adventure, and `examples/hollowbell`, a 2D platformer) hold these rules
+for a whole game, not a toy: each ends a full session run in two processes
+on one world hash, a player's name and a save live in `str` fields as
+world state, and a resource or column a system did not declare is refused
+with the system and the record named, so the fix is one line. A third,
+The Kestrel Stair (`examples/kestrel-stair`, 3D third-person), restored
+`world.snapshot()` after a relaunch with `world.restore()`: 93 entities
+came back with their cloth, navmesh paths and behaviour state, and a full
+session in two processes ended on one hash.
+
+## 1. Game code is TypeScript, and only TypeScript
+
+A game is `src/*.ts` against `@origingame/engine`. Never add Rust, a second
+engine, a WebGL context, DOM access or a `<canvas>` of your own: the engine
+renders, the shell owns the page. Anything that would need engine-side code
+is an engine feature request, not something to work around in the game.
+
+## 2. The tick is fixed and the world is deterministic
+
+- Simulation runs in fixed ticks (`GameDesc.tick`, 60 Hz by default). A
+  system sees `time.dt`, `time.tick` and `time.elapsed` from the `Time`
+  resource; these are functions of the tick count.
+- Never read `Date`, `performance.now()` or any other clock inside a system,
+  a command or a facts function. Two runs with the same seed and the same
+  inputs must produce the same world hash; a wall-clock read breaks that.
+- Randomness comes from the `Rng` resource (`world.resource(og.Rng)`) or a
+  stream forked from it with a label (`rng.fork("spawner")`). Never
+  `Math.random()`. The project seed lives in `project.ogt` and `GameDesc.seed`;
+  `og run --seed` overrides it for a replay. A draw (`next`, `range`,
+  `integer`, `chance`) moves the stream, so it needs `og.Rng` in `writes`;
+  `fork` reads the seed alone and moves nothing, so a system that only
+  forks declares `og.Rng` in `reads` (its forks are the same on every host
+  and in every system).
+- The wall clock reaches the game only as host input, between ticks:
+  `og.platform.now(world)` (UTC ms, the host's clock when the platform
+  attached or last answered, advanced by the ticks since) and the `time`
+  on every og.platform answer. A replay records them like a key press.
+- Rendering never feeds back into simulation: do not read camera or screen
+  state to decide game logic.
+- The engine may spread its own work over the cores (physics, skinning,
+  culling: the lanes), and it gives the same result to the bit as one
+  thread. Game systems always run on the engine thread, one after another,
+  so nothing in game code needs a lock; it needs only the rules above.
+
+### Saving progress
+
+The world is one snapshot: `world.snapshot()` returns it as text
+(`og-save:1:...`: every entity, component, name, resource, rng state,
+pending event and module state, with each type's schema hash) in every
+build, publish included, and `world.restore(save)` puts it back, so the
+restored world hashes as the saved one did, on either host. The session
+stays across a restore (input, the player's volumes, the platform's calls,
+the language, scheduled command steps); og.Time takes the saved tick.
+Inside a system the snapshot is the world in the middle of that tick, as
+that system sees it (its own queued spawns and despawns are not in it),
+and it names the system: the world restored from it completes the tick on
+its next step (the systems after that one, then the engine's, physics
+included) and then goes on tick for tick as the run that saved did, so a
+replay from it matches. Make the snapshot the system's last write of the
+tick. A restore asked for in a system applies when the tick ends. A save whose types' fields changed is refused naming them, or
+mapped by name with `{ migrate: true }`. Only what is in the world is
+saved: progress in module variables is lost. The text is a few tens of
+KiB (11 KiB for a few entities, 25 KiB for a 2D level of 189, 78 KB for a
+3D world of 93 with cloths, minds and skinned characters), often over the
+store's 64 KiB a key: save it with `og.platform.saveSlot(world, { slot,
+text, meta })`, which spreads it over as many keys as it needs and writes
+the slot's manifest last, so a save cut short leaves the last one whole,
+and read it back with `og.platform.loadSlot` (og-game §17, og-platform-sdk
+§2).
+
+### Recording, replaying and ghosts
+
+The engine has no in-game recorder: determinism is the recorder. The same
+world and the same inputs give the same run to the tick, so a game records
+its own inputs and replays them. Three things are called "replay": the
+probe's and playtests' re-runs (`og run --commands`, `--seed`: tests,
+og-build §4), a **watch replay** (the player's run driven again) and a
+**ghost** (a past run drawn beside the player). The last two are game code;
+examples/meridian-loop does both (`src/replay.ts`, `src/tape.ts`,
+`src/tapes.ts`, `src/ghost.ts`; `tests/replay.og.ts` checks the replay
+crosses the line on the race's own ticks).
+
+Watch replay: snapshot the start, tape the inputs, restore and feed the tape.
+
+```ts
+// 1. The start, taken by the FIRST system of a tick (later in a tick, the
+//    restored world skips the rest of that tick and runs a different race).
+r.replayMark = true;                       // saved set: the restored world knows it is a replay
+const snap = world.snapshot();
+r.replayMark = false;
+const asked = snap.ok ? og.platform.saveSlot(world, { slot: "replay", text: snap.value }) : snap;
+if (asked.ok) r.replaySave = asked.value;  // its answer comes on a later tick (og.platform.result)
+
+// 2. Every tick: the intent drives the car only through its quantised code,
+//    live and replayed alike, so the tape reproduces it exactly.
+const code = r.replaying ? codeAt(tape, r.runLen) : encode({ steer, throttle, brake });
+const i = decode(code);                     // steer 33 steps, throttle 17, brake 5: 12 bits
+world.set(car, og.Vehicle, { steer: i.steer, throttle: i.throttle, brake: i.brake });
+if (!r.replaying) putCode(tape, r.runLen, code);   // two characters a tick
+r.runLen += 1;
+
+// 3. At the finish: the tape beside the start.
+og.platform.storeSet(world, { key: "replay.tape", value: { ticks: r.runLen, inputs: tapeText } });
+
+// 4. Watch replay: loadSlot, then world.restore(text) when it answers (it
+//    applies when the tick ends). The next tick sees replayMark set: clear
+//    it, set replaying, read "replay.tape" back, feed it from tick 0.
+```
+
+Keep the tape and the replay's flags in components and resources (a
+restore rolls back everything else). A component has no array field and a
+`str` field holds at most 4,096 bytes, so a tape of a few thousand ticks
+is cut into `str` chunks, one entity each, written through the column's
+bytes by the system that owns them (§4). The start is the whole world:
+triangle-mesh colliders make it large (a 956 m circuit's world is 400 KB),
+so it goes through `saveSlot`, which spreads it over the store's keys.
+Request numbers are not carried across a restore: ask the store again
+after it.
+
+A ghost: record poses, draw a model. While a lap runs, tape the car's pose
+every second tick (position and yaw, pitch, roll: 15 characters); from the
+next lap draw a model with no body where the best lap's car was at the
+same time into its lap, between the two poses around it:
+
+```ts
+if (into % 2 === 0) putPose(cur, into / 2, { ...car.position, ...euler(car.quaternion) });
+const f = into / 2, i0 = Math.floor(f), u = f - i0;
+const a = poseAt(best, i0), b = poseAt(best, i0 + 1);
+world.set(ghost, og.Transform, {
+  position: { x: a.x + (b.x - a.x) * u, y: a.y + (b.y - a.y) * u, z: a.z + (b.z - a.z) * u },
+  quaternion: quat(lerpAngle(a.yaw, b.yaw, u), lerpAngle(a.pitch, b.pitch, u), lerpAngle(a.roll, b.roll, u)),
+});
+```
+
+Do not re-drive a second physics body from the tape for a ghost: it takes
+part in the simulation the player drives in (a second og.Vehicle's wheel
+rays land on whatever collider is under them, the player's car included),
+so the player's run is no longer the one taped.
+
+## 3. Every failure is a value
+
+Engine calls that can fail return `Result<T>`: `{ ok: true, value }` or
+`{ ok: false, reason }`. Check `ok` before reading `value`; the `reason` is a
+sentence that names the fix. A dead handle is a refusal, never a crash. Do not
+wrap engine calls in `try`/`catch` to hide refusals; handle the `reason`.
+
+## 4. Systems work on archetypes, never on single entities
+
+A system declares what it reads and writes and receives the matching
+archetypes once per tick:
+
+```ts
+export const Move = defineSystem("Move", { reads: [Velocity], writes: [og.Transform] }, (q, time) => {
+  for (const a of q.archetypes()) {
+    const p = a.column(og.Transform).position; // Float32Array, stride 3
+    const v = a.column(Velocity).v;
+    for (let i = 0; i < a.count; i++) {
+      p[i * 3] += v[i * 3] * time.dt;
+      p[i * 3 + 1] += v[i * 3 + 1] * time.dt;
+      p[i * 3 + 2] += v[i * 3 + 2] * time.dt;
+    }
+  }
+});
+```
+
+- Columns are typed arrays over engine memory. Write only components listed
+  in `writes`; reading needs `reads` or `writes`. An undeclared column throws
+  inside the system and fails the tick with the system's name.
+- The same holds for resources and events: `world.resource`, an event read
+  (`world.events`) and an `og.Rng` fork need the record among `reads` or
+  `writes`; a resource write, an `og.Rng` draw and `world.emit` need it in
+  `writes`. Undeclared, it throws in `og run` and `og test` (dev and
+  release builds) with the system and the record; a publish build refuses
+  it, logs it once per system and access, and the game runs on.
+- A resource handle is a typed view of the resource's packed record:
+  `world.resource(R)` hands back the same handle in a world every time, and
+  a field read or write is a typed-array access (about 0.02 µs, whatever
+  the resource's size; a 130-field run state costs what an 11-field one
+  does). The record is fetched again, in one engine call answering its
+  bytes (no JSON), only by the first read after another engine call
+  (`world.*`, `og.*`) or a system boundary, the only times the engine can
+  change it; writes are kept and written back in one call before the next
+  engine call and when the system or command returns. So two handles
+  always agree, a read after an engine call sees the engine's value, and
+  the world hash is what writing field by field gives. The rule: keep the
+  run in one resource and read and write its fields where they are used;
+  no plain copies, no handle passed around to save a fetch. What costs is
+  alternating an engine call with a read of a resource the system wrote
+  (one write-back and one fetch each time, a few µs): in a hot loop over
+  entities, read the fields into locals before the loop's engine calls.
+- Views belong to one system call. Never keep an `ArchetypeView` or a column
+  array across ticks or in module state: a stale view throws with the tick
+  and the system it belonged to.
+- Text is world state like a number: a `str(capacity)` field holds UTF-8 of
+  at most `capacity` bytes inline, zero-padded (`name: str(48)` takes any 12
+  characters, four bytes covering every script). `world.get`, `world.set`
+  and a resource's fields move it as a JS string; text over the capacity is
+  refused with the fix named (an error value from `world.insert`/`world.set`,
+  a throw from a resource's setter), never truncated. Its column is the raw
+  bytes (`Uint8Array`, stride the capacity). The probe reads it (`get:`,
+  `dump_entity`), `set:Prefs.name=Ada Lovelace` writes it (a JSON literal for
+  escapes: `set:Prefs.name=""`), a scene gives it one quoted string, and
+  snapshots and the world hash carry its bytes, so a name never lives in a
+  module variable or as numbers of code points.
+  A `str` holds 1 to 4,096 bytes: a larger capacity typechecks and is
+  refused when the game starts (`a string field holds 1 to 4096 bytes`).
+- A field holds one value: a component has no array or list field. A few
+  values are numbered fields (`p0`..`p7`, as og.CameraRail's rail points);
+  a list is an entity per element with its own component, looped over by
+  a query (a ring of skid marks, the laps of a race); a long record (a
+  lap's taped inputs) is text in `str(4096)` chunks, an entity each.
+- A handle is a 64-bit number (an `og.load` answer, a texture, a sound,
+  a geometry, a material, an entity): keep it in a field of its own kind,
+  `Asset()`, `Texture()`, `Sound()`, `Geometry()`, `Material()` or
+  `Entity()` (each handle type of the API has its factory), in a
+  component or a resource. A `u32` field refuses one (`4294967298 is not
+  a u32`).
+- Per-entity calls (`world.get`, `world.set`) are for commands, setup and
+  the few named entities a system touches (a camera, a listener, the
+  player), not for hot loops. A system's `reads` and `writes` borrow
+  nothing by themselves: a column is borrowed when the system takes its
+  view (`a.column(C)`), and held until the system returns. So `world.get`
+  and `world.set` reach any entity its declarations match until the system
+  takes that archetype's column of the component; after it, they refuse
+  (naming the view), and the entity is read and written through the view's
+  arrays at its row (`a.entities`). Take per-entity calls first, views
+  after, or keep to one of the two in a system.
+- A system has one query: every component in its `reads` and `writes`
+  together, so an entity matches only when it has all of them (and none of
+  `without`). A component declared only to `world.get` one named entity
+  (the player's car) narrows the loop to entities that also have it, often
+  to none, with no error. `world.query` is refused inside a system, by
+  design (a system reaches only what it declared): loop over each
+  archetype in a system of its own that declares only its components, and
+  pass what crosses between them through a resource.
+- Order systems with `after` and `before` by name; declaration order is the
+  default.
+
+## 5. Reflection is the one schema
+
+A component or resource is declared once with `defineComponent` /
+`defineResource` and its column factories (`f32(100, { min: 0, max: 1000,
+tunable: true })`, `Vector3()`). That one layout is what scenes, dumps, the
+probe's `bounds` and `patch`, Tune and the wiki read. Never describe the same
+data a second time (a JSON config mirroring a component, a hand-written
+schema for the inspector). Put ranges, units and `tunable` on the field where
+it is declared.
+
+## 6. Desc objects and names
+
+- Desc objects (`SpawnDesc`, `SystemDesc`, `GameDesc`) may omit any field;
+  the zero value or the documented default applies. Pass `{}` rather than
+  inventing values the engine already defaults.
+- Names follow the API: components, resources and systems PascalCase;
+  command actions snake_case; entity names are stable strings, because the
+  probe and the command channel address entities by them.
+- Vector, quaternion, matrix, colour, transform and material vocabulary is
+  three.js's (`position`, `quaternion`, `scale`, `metalness`, `roughness`).
+
+## 7. Where the API is described
+
+The generated wiki (`reference/index.md` next to the `og-game` skill, or
+`wiki/index.md` in `@origingame/engine-knowledge`) has one page per module
+with every signature quoted from the IDL, grouped by the skill that teaches
+it. This skill's are the ECS and its rules: `reference/world.md` (entities,
+queries, resources, events), `reference/system.md` (systems and their
+order), `reference/reflect.md` (components, resources and their column
+factories), `reference/rng.md` (seeded streams) and `reference/math.md`
+(vectors, quaternions, colours as data). When the wiki and memory disagree,
+the wiki is right: it is regenerated from the same IDL the engine is built
+from. The other skills, and which modules each teaches, are og-game §1.