@origingame/engine 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,386 @@
+---
+name: og-ai
+description: Enemies and NPCs on Origin Engine — navigation with og.nav (grids from costs or a tilemap's collision, cooked navmeshes, flow fields, agents that plan and steer) and minds with og.ai (behaviour trees and state machines as .ogt data, sight cones and hearing, blackboards, the game's commands), and how to prove them with dump_ai, dump_nav and playtests. Use when a game needs anything that chases, patrols, flees, guards or wanders, or when an enemy's behaviour is wrong.
+---
+
+An enemy on Origin Engine is three records on an entity and one data file:
+`og.NavAgent` (where it goes, moved by `og.nav`), `og.AiAgent` (which
+behaviour it runs, ticked by `og.ai`), `og.Perception` (what it sees and
+hears), and a behaviour in `assets/ai/<name>.ogt`. Game code does not move
+enemies or switch their states by hand; it sets facts (components,
+resources) the behaviour checks, and handles the commands it raises. The
+API is in `reference/nav.md` and `reference/ai.md`; this skill is how to
+use them.
+
+## What works
+
+The Kestrel Stair (`examples/kestrel-stair`, a 3D third-person action
+game written from this package alone) baked its navmesh from the level's
+glTF with one `model` line (§1), and five agents ran on it: imps on a
+behaviour tree (patrol, chase, a 0.25 s wind-up and a bite, flight when
+hurt) and wardens on a machine (patrol, alert, chase, slam, search), each
+raising the game's commands, with sight occluded by the level,
+`og.Steering` separation and avoidance, and `og.nav.setObstacle` closing
+the summit gate until it rose. Two processes of a full session of chases
+end on one world hash.
+
+## 1. Pick the navigation
+
+| World | Navigation | How |
+|---|---|---|
+| A tilemap (top-down, dungeon) | a grid from its collision | `og.nav.gridFromTilemap(world, { entity: map })` (`inflate` blocks cells around walls for wide agents) |
+| An open 2D or 3D arena | a grid from costs | `og.nav.grid(world, { width, height, cellSize, origin, costs })`; costs 0 blocked, 1 normal, up to 255 to avoid |
+| Rooms, slopes, floors in 3D | a navmesh baked at cook time | `assets/nav/<level>.ogt` of `type navmesh` (every line below) gives the agent, the cell and tile sizes, the bounds and the geometry; `og cook` voxelises it; `og.nav.load(world, "nav/<level>.ogt")` answers `{ mesh }` |
+| Many units to one goal (crowds, tower defence) | a flow field | `og.nav.flowField(world, { grid, targets })`; one field serves every agent |
+
+Doors and crates that block for a while are navmesh obstacles
+(`og.nav.setObstacle`): only the tiles under them rebuild. Never bake a
+navmesh at run time; the wasm does not carry the voxeliser.
+
+### The navmesh file
+
+The geometry is every `scene`, `model`, `terrain` and `box` entry
+together (at least one must give triangles); every other line tunes the
+bake. Every line, with its default:
+
+```text
+type navmesh
+version 1
+---
+agent {                        # the agent the mesh is for
+  radius 0.4                   # metres kept from walls: the floor is eroded by it
+  height 1.8                   # headroom: floor under a lower ceiling is left out
+  climb 0.4                    # the highest step or ledge walked up or down
+  slope 45                     # degrees: a steeper triangle is not floor
+}
+cellSize 0.2                   # metres across a voxel column (half the radius or less keeps narrow doors open)
+cellHeight 0.1                 # metres of a voxel's height
+tileSize 32                    # cells per tile side, 8 to 256: an obstacle rebuilds only the tiles it touches
+maxError 1.3                   # cells a simplified wall outline may stray from the voxels
+scene "scenes/level.ogt"       # a scene's static geometry: its models, and its static colliders as boxes
+model "models/level.glb" {     # every triangle of a glTF's default scene (repeatable)
+  position 0 0 0               # where the level places it (default 0 0 0)
+  quaternion 0 0 0 1           # x y z w (default 0 0 0 1)
+  scale 1 1 1                  # (default 1 1 1)
+}
+terrain "terrain/vale.ogt" {   # a terrain's surface (repeatable)
+  position 0 0 0               # where its entity stands (default 0 0 0)
+  step 1                       # every step-th height sample (default 1: all of them)
+}
+box {                          # a solid box the level lacks: a plinth, a crate (repeatable)
+  center 0 0.5 0               # (default 0 0 0)
+  size 1 1 1                   # whole sizes (default 1 1 1)
+  quaternion 0 0 0 1           # (default 0 0 0 1)
+}
+bounds {                       # the box baked; left out: the triangles' own bounds
+  min -10 -10 -10              # (default -10 -10 -10 inside the block)
+  max 10 10 10                 # (default 10 10 10)
+}
+```
+
+- Floors are triangles facing up (glTF's counter-clockwise front faces);
+  give the agent the body's radius and height, and `climb` the stair's
+  riser or more.
+- A scene's dynamic bodies are left out; its sphere and capsule colliders
+  bake as their bounding boxes, convex and mesh colliders only through
+  their model. A terrain bakes only the cells inside `bounds`.
+- `bounds` cuts what the agents may reach: a min y a little over a lake's
+  surface leaves the lake a hole they walk round.
+- The cook refuses any other line (naming it), a scene, model or terrain
+  missing under `assets/`, no triangles at all, and a level over 16
+  million columns (raise `cellSize` or bound it); its report notes the
+  triangles, cells, polygons and tiles it baked.
+
+The Kestrel Stair's, baked from its glTF level (`tools/level.ts` writes it
+beside the model):
+
+```text
+type navmesh
+version 1
+---
+agent {
+  radius 0.5
+  height 2.6
+  climb 0.3
+  slope 36
+}
+cellSize 0.25
+cellHeight 0.1
+tileSize 32
+model "models/stair.glb" {
+  position 0 0 0
+}
+bounds {
+  min -23 -1 -67
+  max 23 14 45
+}
+```
+
+Before writing a mind, prove the mesh: load it in `start` and check
+`og.nav.nearest(world, mesh, spawn)` at every spawn point and route
+point (null, or a point far from it, is a place the agents cannot stand;
+og-game's order, step 5).
+
+## 2. The agent
+
+```ts
+const post = og.nav.nearest(world, yard.mesh, spawn) ?? spawn; // on the mesh
+world.set(guard, og.Transform, { position: post });
+world.insert(guard, og.NavAgent, { nav: yard.mesh, target: post, seeking: true, speed: 1.5, acceleration: 12, radius: 0.4, faceMovement: true, turnSpeed: 8 });
+world.insert(guard, og.AiAgent, { behaviour: mind.behaviour });
+world.insert(guard, og.Perception, { sight: 9, fov: 120, eyeHeight: 1.6, team: 2 });
+world.insert(hero, og.Perceivable, { team: 1, eyeHeight: 1 });
+```
+
+- Place every agent on the mesh, at its `og.nav.nearest` point (idle, or
+  seeking a target there: an agent that has not planned yet stays where
+  it was put, and a teleported one walks on from where it lands), and
+  prove it in a playtest: a few ticks in, each agent stands where it was
+  put (its height too) and its `status` is not `NAV_UNREACHABLE`.
+- `radius` keeps grid paths clear of walls; set it to the body's.
+- `faceMovement` turns the body to where it walks (3D +Z forward, 2D +X).
+- `drive: false` keeps planning and reporting but leaves the motion to the
+  game: set it during a knock-back or a stun, back to true after.
+- og.nav re-plans when the target moves past `repathDistance`, every
+  `repathTicks`, and when the agent is pushed more than 1.5 m (or four
+  radii) off its path. `status` says `NAV_ARRIVED` or `NAV_UNREACHABLE`;
+  read it rather than measuring distances.
+
+## 3. Write the mind as data
+
+```text
+type behaviour
+version 1
+---
+name "slime"
+route beat {
+  point 11 6.5 0
+  point 16 6.5 0
+}
+tree {
+  selector {
+    sequence flee {
+      check Slime.hp below 30        # a component field of the agent
+      flee {
+        distance 6
+      }
+    }
+    sequence bite {
+      check sees
+      check targetDistance below Tuning.slimeReach   # compared with a resource field, read every think
+      command bite {                 # the game's command, the agent's handle first
+        cooldown 1
+      }
+    }
+    sequence chase {
+      check sees
+      chase {
+        speed Tuning.slimeSpeed      # a resource field, read every think
+      }
+    }
+    patrol beat {
+      wait 0.6
+    }
+  }
+}
+```
+
+- A **tree** for reactive enemies (re-checked from the top every think, so
+  a higher branch that becomes true takes over); a **machine** (below) for
+  NPCs whose mode should stick (patrol, alert, search), with enter and
+  exit actions and timed transitions.
+- Checks read the blackboard's built-in keys, your own keys (`key alert
+  0`, `set alert 1`), `Component.field` of the agent and `Resource.field`,
+  compared with a literal or with another key or field read each time
+  (`check Foe.hp below Tuning.fleeHp`). An unknown operand fails its check
+  and logs one warning naming the fix: read the run's warnings.
+- Keep damage, death, loot and knock-back in the game: a behaviour raises
+  `command bite` and the game's command handler applies it. Tune numbers
+  live in components and resources (`speed Tuning.slimeSpeed`, `check
+  targetDistance below Tuning.slimeReach`), never as copies in the .ogt.
+- A new run or a respawn: put the agent back (its Transform, its
+  NavAgent's target with `seeking: false`) and call
+  `og.ai.restart(world, agent)`: a machine starts again in its initial
+  state, a tree at its root, timers, cooldowns and the blackboard reset.
+- Telegraph attacks: a `wait 0.3` or a wind-up state before the command
+  (og-feel §2). An enemy that hits on the tick it arrives feels unfair.
+- `thinkEvery 2` or `3` for crowds: agents are staggered, so the cost
+  spreads across ticks.
+
+### The behaviour file
+
+A file holds a name, its keys, its routes and one `tree` or one
+`machine`. Every line of a tree, with its default:
+
+```text
+type behaviour
+version 1
+---
+name "slime"                   # what dump_ai shows (default "behaviour")
+key alert 0                    # a blackboard key of yours and its start: a number, x y z, or true/false (repeatable)
+# og.ai's own keys, written every think, which checks read and `key` or `set` may not name: self,
+# position, sees, heard, target, targetPosition, targetDistance, lastSeen, sinceSeen, heardAt,
+# sinceHeard, elapsed (seconds in the machine's state)
+route beat {                   # a patrol route, declared before the tree names it (repeatable)
+  point 11 6.5 0               # x y z (at least one)
+}
+tree {                         # one root node; or a `machine` (below), never both
+  selector main {              # children in order: the first that does not fail decides; re-checked from the top every think
+    sequence hurt {            # children in order while they succeed; re-checked from the first every think
+      check Slime.hp below 30  # <operand> [is | not | below | above | atMost | atLeast <value>]; no operator: truthy; the value may be a key or field
+      flee {                   # flee [key]: away from the key's position (default target)
+        distance 6             # until this far (default 6)
+        speed 3                # metres per second, or a key or field read every think (default: the NavAgent's speed)
+      }
+    }
+    steps attack {             # a sequence that resumes at its running child
+      move_to lastSeen {       # move_to <key> | <x y z>: succeeds on arrival, fails when unreachable
+        speed Tuning.slimeSpeed
+      }
+      wait 0.3                 # runs this many seconds, then succeeds
+      command bite 2 {         # the game's command: the agent's handle, then the words after the name
+        cooldown 1             # fails for this long after it ran (default 0)
+      }
+    }
+    parallel watch {           # every child every think
+      policy all               # all (default): succeeds when all do, fails when one does | one: the reverse
+      chase {                  # chase [key]: after an entity key's position (default target)
+        reach 0.5              # succeeds within this (default 0.5)
+      }
+      repeat 0 {               # its one child, N times while it succeeds (0: forever)
+        cooldown 2 {           # after its child succeeds, fails for this many seconds
+          timeout 5 {          # fails when its child runs longer than this
+            invert {           # success is failure and failure success
+              succeed {        # success whatever the child answers (running stays running)
+                set alert 1    # a key of yours to a value; succeeds
+              }
+            }
+          }
+        }
+      }
+    }
+    patrol beat {              # round a route, resuming at the nearest point
+      wait 0.6                 # seconds at each point (default 0)
+      loop true                # false: succeeds at the route's end (default true)
+    }
+    wander {                   # to random points round where it started
+      radius 4                 # (default 4)
+      wait 1                   # seconds at each (default 0)
+    }
+    stop                       # stops moving; succeeds
+  }
+}
+```
+
+- An action without `speed` moves at its og.NavAgent's `speed`. A value
+  in `key`, `set` and `check` is a number, three numbers (a point) or
+  `true`/`false`; a `check`'s may also be a key, `Component.field` or
+  `Resource.field`, read every time the check runs (`check Foe.hp below
+  Tuning.fleeHp`). Command names are snake_case.
+- The cook refuses an unknown entry, node or option, a route that is not
+  declared, a decorator without exactly one child and a malformed value,
+  naming the line.
+
+A machine replaces the tree. Every think it checks the current state's
+transitions in order and takes the first that holds (running the exit
+actions, then the new state's enter actions), then ticks the state's
+nodes as one sequence. The Kestrel Stair's warden:
+
+```text
+type behaviour
+version 1
+---
+name "warden-0"
+route round {
+  point 6 4 -2
+  point 6 4 -14
+  point -4 4 -12
+}
+machine {
+  initial patrol               # the state it starts in (default: the first)
+  state patrol {
+    patrol round {             # a state's nodes, ticked while in it
+      wait 1.6
+      speed Tuning.wardenPatrol
+    }
+    to alert {                 # to <state>: when every check holds ...
+      check sees
+      check Game.phase is 1
+    }
+  }
+  state alert {
+    enter {                    # instant actions on entering: set, stop, command (an `exit { }` block: on leaving)
+      command alert
+    }
+    chase {
+      speed Tuning.wardenChase
+      reach 1.6
+    }
+    to slam {
+      check targetDistance below Tuning.wardenReach
+    }
+    to search {
+      check sees is false
+    }
+    to patrol {
+      check Game.phase not 1
+    }
+  }
+  state slam {
+    enter {
+      command slam
+    }
+    stop
+    to alert {
+      after 1.8                # ... and the state has lasted this many seconds (default 0)
+    }
+  }
+  state search {
+    move_to lastSeen {
+      speed Tuning.wardenPatrol
+    }
+    to alert {
+      check sees
+      check Game.phase is 1
+    }
+    to patrol {
+      after 4
+    }
+  }
+}
+```
+
+## 4. Perception
+
+- `fov` 90–140 for guards (360 for things that sense all round), `sight`
+  a little past the screen's half width, `occlude: true` so walls hide.
+  Before an agent first moves its cone points the way its Transform faces.
+- Hearing: spatial `og.AudioSource`s that start within `hearing × volume`
+  are heard, except the agent's own (its entity's and its children's: an
+  imp's chitter does not alert the imp); `og.ai.noise(world, { position,
+  loudness, source })` for silent events (a thrown rock, a door).
+- `memory` is how long a lost target stays the target; `lastSeen` lets a
+  search state walk to where it was.
+
+## 5. Prove it
+
+- `dump_ai:<entity>[:file]` writes the behaviour, state, running node, the
+  path from the root, status, blackboard and perception;
+  `dump_nav:<entity>[:file]` the path, the corner it heads for and status.
+- A playtest per behaviour beat (`templates/archetypes/topdown/tests/ai.og.ts`
+  and `flee.og.ts`, `templates/game/tests/guard.og.ts`): place the hero with
+  a command, advance, dump, assert `node`, `state`, `sees` and positions.
+  `templates/archetypes/roguelike/tests/foes.og.ts` proves a turn-based
+  hunt (a tree that acts only on `Game.foesTurn`) and
+  `templates/archetypes/tower-defense/tests/maze.og.ts` a flow field
+  re-routed round placements and a placement refused because `findPath`
+  no longer reaches the goal.
+  `templates/archetypes/third-person` is the 3D action pattern: sentinels on
+  a cooked navmesh with behaviour machines (patrol, alert, grab) raising
+  the game's commands, restarted for a new run (`tests/sentinels.og.ts`,
+  `tests/restart.og.ts`).
+  Include the negative: a wall that hides the hero, a target outside the
+  cone.
+- Determinism: a playtest with `runs: 2` over a chase must end on one hash.
+- `og polish` reports damage moments without hit feedback and inputs nobody
+  answered (og-build §5); enemies that bite with no hit stop show up there.

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

@@ -0,0 +1,191 @@
+---
+name: og-audio
+description: Sound on Origin Engine — one-shot voices for game events, the procedural sound presets og cook synthesises (coin, jump, hit, click and more), UI sounds, the four buses and their effects (filters, reverb send, compressor or limiter, ducking), music with stems, bar-aligned starts, crossfades and stingers on og.Music's clock, spatial sources with occlusion and distance dulling, voice priority and the cap, and proving it all headless with listen and og run --audio. Use when a game is silent, when adding any sound or music, or when the mix is muddy, clipping or wrong.
+---
+
+Audio on Origin Engine is world state: an entity with `og.AudioSource`
+plays while `playing` is true, the tick sends commands to the mixer, and
+the same script renders the same samples on every host. The API is in
+`reference/audio.md`; this skill is how much of each to use.
+
+## What works
+
+Two games written from this package alone (`examples/lantern-vale`,
+`examples/hollowbell`) put this skill to work: Lantern Vale's four-minute
+track, cooked in 4-second chunks, streams from the title screen under the
+effects' duck, Hollowbell's music streams the same way, flipbook frame
+events put Hollowbell's footsteps, strikes and bell on their exact frames,
+and `og polish` heard a sound on every damage moment. In The Kestrel Stair
+(`examples/kestrel-stair`, a 3D third-person game) spatial sources (the
+braziers, the imps' chitter, the crypt's drip, the bell) were heard from a
+listener on the camera with distance, pan, distance dulling and occlusion
+behind walls, each read back exactly through `og.AudioPlayback` with
+`get:`; its 2:40 track streamed in 4-second
+chunks on the music bus. Its crypt is an `og.ReverbZone` (a box with a
+1.5 m `fade`, the sfx bus sending 0.55 to a room of 0.92 at damping 0.25;
+§4, §6): a playtest read the zone's `weight` 0 from the door and 1 inside,
+while og.Audio and the bus kept the open air's room 0.5 and send 0.12.
+
+## 1. Every event sounds
+
+A game with no sound feels broken, whatever it shows. Before anything else,
+give each of these a sound: the player's actions (jump, attack, dash), hits
+given and taken, pickups, a door, a death, a win and a loss, every UI press.
+
+- One voice entity per sound, spawned in `start` with `playing: false`, and
+  a `Voices` system that plays each requested one: systems set bits of a
+  game resource (`Sounds.sfx |= Sound.Jump`), Voices sets `playing` on the
+  matching voice (a voice already playing is stopped this tick and
+  restarted the next). Every archetype in `templates/archetypes` does
+  this; copy a `Voices`.
+- Vary repeated sounds: `pitch` 0.92–1.08 from the world's `og.Rng` for
+  footsteps, hits and coins, so a stream of them does not machine-gun.
+- A hit's sound starts on the hit's tick, with its hit stop and flash
+  (og-feel §3): the three together sell the contact.
+
+## 2. Presets: sounds without files
+
+`og sfx` lists the procedural presets (`coin`, `pickup`, `powerup`, `jump`,
+`land`, `footstep`, `hit`, `hurt`, `explosion`, `laser`, `whoosh`, `door`,
+`death`, `click`, `select`, `back`, `error`, `levelup`). `og sfx jump --out
+assets/audio/jump.ogt` writes an asset `og cook` synthesises into a normal
+sound; `og.load.sound(world, "audio/jump.ogt")` plays it like a WAV. Tune
+`seed` (another take), `pitch`, `length` and `volume` in the file; `og sfx
+jump --out jump.wav` renders it to listen to. `og sfx library <dir>` writes
+all of them. Replace a preset with a recorded or generated sound when the
+game's style needs it; presets are a floor, not a style.
+
+## 3. UI sounds
+
+`og.ui.configure(world, { sounds: { hover, press, open, close, success, error } })`
+(or the skin's `sound` lines) plays them on the `ui` bus: `click` for
+press, `select` for success, `back` for close, `error` for a refused press
+(and for `og.ui.shake({ sound: true })`, og-ui §6). Each starts in the
+tick of its input. `hover` also answers keyboard and gamepad focus moving
+to a control, and `press` a press by Enter, Space or the pad's A, so a
+menu walked with a pad is heard step by step; keep `hover` short and quiet
+(volume ≤ 0.3). `configure` changes only the fields it is given: setting
+the sounds after a skin (or a look that brings one) keeps the skin and its
+fonts, and `sounds: null` silences them again.
+
+## 4. Buses and the mix
+
+Four buses: `master`, `music`, `sfx`, `ui`. Set levels with the sources'
+`volume` and each bus's `og.AudioBusFx` (one entity per bus):
+
+| Need | AudioBusFx |
+|---|---|
+| Music under effects | on music: `duck: true`, `duckBus` sfx, `duckDepth` 8–12 (dB), `duckRelease` 0.3–0.6 (s) |
+| Dialogue or a stinger above everything | duck music and sfx by the ui or a dialogue bus |
+| Muffled (underwater, pause menu) | `lowpass` 600–1200 Hz on sfx and music |
+| Thin radio or phone | `highpass` 400 Hz plus `lowpass` 3 kHz |
+| Space and room | `reverb` 0.1–0.3 on sfx (og.Audio `reverbRoom`, `reverbDamping`); keep music dry |
+| A room that sounds like a room (a crypt, a cave, a hall) | an `og.ReverbZone` on an entity at the room's centre (§6), not code that eases the bus |
+| Even out loud and quiet effects | compressor: `threshold` −18 (dB), `ratio` 3–4, `attack` 0.005 and `release` 0.15 (s), `makeup` 3 (dB) |
+| Never clip | a limiter on master: `threshold` −1, `ratio` 20, `attack` 0.001 |
+
+`og polish` reports clipped samples in the run's mix (og-build §5); a peak
+at 1.0 is a mix bug, not loudness.
+
+## 5. Music
+
+- Loop a track with `AudioSource.loop` (`loop: true`, with `loopStart` and
+  `loopEnd` for an intro that plays once) and `bus: "music"`.
+- Stems: start every layer at the same `startAt` (world seconds) and bring
+  layers in and out with `volume` and `fade` (0.5–2 s), never by starting
+  them late: they stay sample-aligned.
+- `og.Music` (`bpm`, `beatsPerBar`, `start`) is the clock: `nextBar` and
+  `nextBeat` are world times, so `startAt: music.nextBar` starts a stinger
+  or the next section on the bar line, sample-accurately, and `og.MusicBeat`
+  events drive beat-synced visuals.
+- Bar-length stems started bar by bar: on the last beat of each bar
+  `og.MusicBeat` brings, start the next bar's stems at that event's `time`
+  plus a beat. og.audio runs on the world's ticks, which keep going at
+  time scale 0, so a pause stops the stems and a resume starts them again.
+  `templates/archetypes/rhythm` (its `Band` system, and
+  `tests/band.og.ts`, which asserts every `startAt`) does this.
+- Part-way starts: `startOffset` (seconds into the clip) with `startAt`
+  starts a source that far in, to the sample, so a resume carries on from
+  the beat it paused on: each stem sounding then starts at the count-in's
+  end with `startOffset` how far into it that beat is (the rhythm's
+  `tests/pause.og.ts` asserts both).
+- What the player hears lags the mix by the device's output latency:
+  `og.audio.outputLatency(world)` (seconds; the Web Audio context's
+  `outputLatency` or `baseLatency` plus the engine's buffer on the web, the
+  device's callback-to-playback time natively, 0 headless; the system
+  declares `og.Audio` among its reads). A rhythm game judges a press at
+  its tick's time plus its event's `at` (og-game, input) less this and a
+  calibrated offset for the rest of the chain (the rhythm's `Play` system,
+  `tests/timing.og.ts`).
+- A crossfade: the new track `startAt: nextBar` with `fade: 2`, the old one
+  `playing: false` with the same `fade`.
+- Long tracks stream in chunks: a sound whose cooked file passes 1 MiB
+  (about 27 s of 48 kHz stereo) is cooked in chunks of whole frames, and
+  the engine keeps only from half a second behind each playhead to four
+  seconds ahead (on the web each chunk is fetched as it nears). Set it in
+  the track's import settings:
+
+  ```text
+  # assets/music/theme.wav.ogt
+  type import
+  version 1
+  ---
+  sound {
+    stream true   # true, or false to keep a long track whole
+    chunk 4       # seconds per chunk, 1 to 60
+  }
+  ```
+
+  Nothing changes in code: loops, `startOffset`, crossfades and stems play
+  sample-identical to the whole file, and the world hash is the same.
+  `og.load.soundInfo(world, sound)` answers `chunks`, how many (0: whole).
+  A chunk that has not arrived plays silence, so start a long track a beat
+  before it must be heard rather than on the first frame of a scene.
+  What a page downloads: a chunked sound in the first group costs the boot
+  its first chunk only (its other chunks are fetched ahead of the
+  playheads, none before it plays). In a streaming group (og-game §6) it
+  costs the boot nothing: its first chunk comes in the group's pack, it
+  plays silence of its own length until the group is resident, and only
+  then are its other chunks read ahead of the playheads, each a file of
+  its own, never in the pack; when the group unloads it is silent again
+  and nothing more is read. Put a level's or a region's music in that
+  level's group; keep the title's music in the first group, since a group
+  wanted at boot loads right after it anyway.
+
+## 6. Space, occlusion, priority
+
+- `spatial: true` sources pan and attenuate by their world transform
+  against the `og.AudioListener` (on the camera or the player);
+  `refDistance` 1–3, `maxDistance` 20–50. A parented source follows its
+  parent: put the footstep or the engine hum on a child entity
+  (`SpawnDesc.parent`) and it is heard where the parent carries it; a
+  listener on a child of the camera rig hears from the rig.
+- `distanceCutoff` (e.g. 2000 Hz) dulls far sounds; `occlude: true` plays a
+  source behind a collider at og.Audio's `occlusionGain` through
+  `occlusionCutoff`: enemies behind walls sound behind walls.
+- A room of its own: `og.ReverbZone` (a box `size` along the entity's
+  axes, or `radius`) eases the shared reverb towards its `room`,
+  `damping` and its `bus`'s `send` while the listener is inside, fading
+  over `fade` metres past the walls (2–4 m reads as walking through a
+  door). A stone crypt: `room` 0.9, `damping` 0.25, `send` 0.5 on sfx;
+  a small wooden room: `room` 0.4, `damping` 0.6. og.Audio and the
+  bus's og.AudioBusFx stay the open air's; read `weight` to know where
+  the listener is. It follows the listener's world transform, so put the
+  og.AudioListener where the ears are (the camera, or the player); a zone
+  on a child of a moving room moves with it.
+- `og.Audio.maxVoices` (32) caps voices; past it the lowest `priority`,
+  then the quietest, then the oldest is culled (`SOUND_CULLED`). Give the
+  player's own sounds and the music a high priority (200+), ambient props a
+  low one.
+
+## 7. Prove it
+
+- `listen[:file][:seconds]` in a command script writes the last seconds of
+  the mix as a WAV; a playtest reads it with `run.wav(file)` (`peak`,
+  `rms`): silence where it should be silent, sound after the event.
+- `og run --audio out.wav --json` captures the whole run and prints its
+  SHA-256: two runs of the same script give the same hash.
+- `dump_entity:<voice>` shows `og.AudioPlayback` while it plays; a counter
+  on the voice (`Sfx.plays`) proves a short sound played at all.
+- `og polish` scores inputs answered by a sound, UI presses with a ui-bus
+  sound and hits with a sound (og-build §5).