@origingame/engine 0.2.0 → 0.4.0

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

@@ -1,6 +1,6 @@
 ---
 name: og-game
-description: Building a game on Origin Engine — the project layout, components and systems on the ECS, the game entry, scenes as .ogt text, assets cooked from assets/ to cooked/ (glTF and MagicaVoxel models), the og.load loaders, streaming groups, sprites, texture arrays and drop shadows, skeletal and stepped animation, effects and physical materials, looks (the frame's art direction as data: og.Stylise, og.MaterialStyle, presets), tone mapping, exposure, environment maps, shadows and antialiasing, fog, sky, day and night, weather and water, terrain, material shaders in WGSL, physics beyond rigid bodies (joints, character and platformer controllers, vehicles, ropes, cloth, 2D and 3D fluids, ragdolls) and its queries, and the performance budget; the entry point, with the map of the other nine skills and the modules each teaches. Use first, and when creating, structuring or extending a TypeScript Origin Engine game (a project with a project.ogt; not a Godot project.godot).
+description: Building a game on Origin Engine — the project layout, components and systems on the ECS, the game entry, scenes as .ogt text, assets cooked from assets/ to cooked/ (glTF and MagicaVoxel models), the og.load loaders, streaming groups, sprites, texture arrays and drop shadows, skeletal and stepped animation, effects and physical materials, looks (the frame's art direction as data: og.Stylise, og.MaterialStyle, presets), tone mapping, exposure, environment maps, shadows and antialiasing, fog, sky, day and night, weather and water, terrain, material shaders in WGSL, physics beyond rigid bodies (joints, character and platformer controllers, vehicles, ropes, cloth, 2D and 3D fluids, ragdolls) and its queries, footage and og render's videos, and the performance budget; the entry point, with the map of the other nine skills and the modules each teaches. Use first, and when creating, structuring or extending a TypeScript Origin Engine game (a project with a project.ogt; not a Godot project.godot).
 ---
 
 An Origin Engine project is plain files: TypeScript in `src/`, source assets
@@ -64,8 +64,13 @@ The order the games found productive:
 6. **Run with commands** (og-build §1, §4): `og run . --headless
    --commands "...;screenshot:x.png;...;quit"`, then open each frame and
    say what it shows. Do this after every change that shows on screen.
+   Add `describe:frame.json` beside a screenshot to get the frame as data:
+   the visible entities nearest first, each with its screen box, pick point,
+   depth and the fraction hidden; the UI elements with rects and text; the
+   camera (§21).
 7. **Playtests with reference frames** (og-build §3): `tests/*.og.ts`
-   asserting on facts, `get:` answers and dumps, one per feature, and a
+   asserting on facts, `get:` answers and dumps, or written as `expect:`
+   steps alone, which `og run` itself checks (§21), one per feature, and a
    frames playtest comparing screenshots with `references/<tier>/`, its
    frame reads inside `t.frame`: in a sandbox without a renderer each
    screenshot is reported "no renderer, frame unchecked" and passes while
@@ -109,8 +114,9 @@ Mistakes the games made, or would have, before reading the right page:
 | **og-game** (this one) | the project, scenes, assets and loading, input, 2D, animation, effects, atmosphere, terrain, shaders, physics, performance, looks, light and shadows | game, transform, input, load, stream, render, physics, atmosphere, anim, tilemap, terrain |
 | **og-build** | the loop: cook, run with a script, read frames and dumps, hot reload, playtests, `og polish` (§5 there: the one list of what it scores), shipping | commands, probe |
 | **og-feel** | how much: hit stop, shake, squash, easing, floating text, the camera, frame rates, sorting, parallax, controller tunables | time, tween, camera, systems |
-| **og-ui** | screens and HUDs: templates, widgets, focus, phones, skins and motion | ui |
+| **og-ui** | screens and HUDs: templates, widgets, focus, phones, UI styles and motion | ui |
 | **og-taste** | the look: a style from the premise, composition, colour, type, motion, feedback, atmosphere by intent, the done checklist | — (it uses ui and atmosphere) |
+| **og-model** | a 3D model built as code from a reference image: the detail inventory, eight gated passes, the generators' recipes (§18 has their fields), budgets, the review frames and `og compare` | — (it uses render and shapes) |
 | **og-ai** | enemies and NPCs: navigation and minds as data | nav, ai |
 | **og-audio** | sound: events, presets, UI sounds, the mix, music, space | audio |
 | **og-i18n** | languages: string tables, messages, fonts, line breaking, right to left | i18n |
@@ -150,7 +156,14 @@ beside the rebuild: the reload still happens, the `reload` event carries a
 and a `check` event with the diagnostics follows; `og test --json` ends
 with a `test` event whose `check` object has the same three. Read the
 diagnostics and fix them before anything else; `--no-check` skips the
-check (never for `og build --publish`). A created project's
+check (never for `og build --publish`). A `2d` project's publish build
+leaves the 3D world out (terrain, planar water, scattered copies, the 3D
+fluids, volumetric fog: `og.render.capabilities(world).world3d` is false
+there), so `og build --publish` refuses one whose scenes hold `Terrain`,
+`TerrainScatter`, `Water`, `WaterSurface` or `Fluid3D`, naming each
+`scene.ogt:line`, and there `og.terrain.*` and a `SHAPE_HEIGHTFIELD`
+collider answer a refusal naming `world3d`: remove them, or make the
+project `profile "3d"`. A created project's
 `tsconfig.json` resolves `@origingame/engine` (the generated
 `types/index.d.ts`) and `@origingame/engine/playtest` from `node_modules`.
 An example inside the engine repository has no `node_modules`: its
@@ -275,9 +288,13 @@ registered schema and refuses a model path that does not exist.
   A `.vox` with frames (MagicaVoxel's animation) cooks to clips that swap
   the frames' models: play them as skinned clips (§9). `voxFps 8` sets the
   rate (default 10), `voxClip walk 0 3` names frames 0 to 3 (repeatable;
-  without it one clip `frames` holds every frame). Each frame is centred on
+  without it one clip `frames` holds the playback range set in the editor,
+  else every frame; a node marked to loop repeats its keys over the file's
+  frames). Each frame is centred on
   its own pivot, as in the editor: give the frames one height (or pad them)
   for a character whose feet stay on the ground.
+- An `.ogt` of `type model` is a model written as text: og-geom parts by
+  their `og.render` names, placed, with materials and pivots (§18).
 - Reusable production assets come through the platform's asset catalog into
   `assets/`; record each file's licence next to it.
 
@@ -375,7 +392,13 @@ else ignores it. The stamp is world state, so a replay reproduces it.
   `flipX`, `flash`, `shadow`, nine-slice `sliceX`/`sliceY`) is drawn every
   frame at its transform, its scale multiplying the size (so squash and
   stretch is a tween of `og.Transform.scale`). `og.render.sprite` stays for
-  one-tick, immediate drawing (HUDs, debug).
+  one-tick, immediate drawing (HUDs, debug). Sprites and og.ui's frames
+  are filtered anisotropically where the device can
+  (`og.render.capabilities(world).spriteAnisotropy`: 16, or 1 on a WebGL2
+  without `EXT_texture_filter_anisotropic` and on a software rasterizer), so a sprite or a nine-slice
+  squeezed along one axis keeps the other axis's detail (a button's
+  outline stays sharp); at 1 it blurs, and og.ui bounds a frame's middle
+  at twice its art for that reason.
 - **Pixel sprites in a 3D set** stand on the ground with `og.Sprite.dropShadow`
   (or `SpriteDesc.dropShadow`): 0.5 casts the sprite's shape, darkened and
   flattened onto the ground plane (y 0) along the sun, the first
@@ -883,6 +906,289 @@ world.insert(body, og.AnimationGraph, { asset: graph });
 // every tick: world.set(body, og.AnimationGraph, { p0: groundSpeed, p1: airborne ? 1 : 0 });
 ```
 
+### 2D skeletons: the rig2d grammar
+
+A cut-out character (bones, a cape that bends, feet that stay on a slope)
+is an `.ogt` of `type rig2d` beside its PNG, loaded with
+`og.load.rig2d(world, "rigs/hero.ogt")` (`reference/anim.md`). Pixels,
++y up, degrees counter-clockwise, `unit` pixels per world unit; bones
+parent first, slots draw in file order:
+
+```text
+type rig2d
+version 1
+---
+texture "hero.png"
+filter nearest
+unit 20
+bone root {
+}
+bone hip {
+  parent root
+  at 0 22
+  rotation 90
+  length 16
+}
+slot torso {
+  bone hip
+  attachment torso
+  color 1 1 1 1
+  offset 0 0 0 0
+}
+region torso {
+  slot torso
+  rect 0 0 12 20
+  at 8 0
+  rotation -90
+  size 12 20
+}
+mesh cape {
+  slot cape
+  vertex 0 32 hip 16 9 1
+  vertex 6 40 hip 8 4 0.4 cape-1 7 0 0.6
+  triangles 0 1 2
+}
+box hurt {
+  slot torso
+  polygon -6 0 6 0 6 20 -6 20
+}
+child flame {
+  slot lantern
+  armature fire
+  clip burn
+  at 15 0
+}
+ik leg {
+  bones thigh shin
+  target foot
+  bend clockwise
+}
+armature fire {
+  bone base {
+  }
+  # slots, regions, meshes, boxes, ik and clips, as at the top
+}
+clip idle {
+  duration 2
+  loop true
+  bone hip {
+    translate 0 0 0 curve 0.42 0 0.58 1
+    translate 1 0 -1.5
+    skew 0 0
+  }
+  slot torso {
+    offset 0 0 0 0 0
+    offset 1 0.2 0.1 0 0
+  }
+  deform cape {
+    key 0 0 0 0 0
+    key 1 0 -3 0 -6
+  }
+  order 1.5 cape torso
+  ik leg {
+    key 0 1 clockwise
+    key 1 0.5 clockwise
+  }
+  event 0 "inhale"
+}
+```
+
+`rect` is pixels from the image's top left; a mesh `vertex` is `u v` in
+pixels then, per bone, `bone x y weight` in that bone's space (weights
+summing to 1), or plain `x y` in the slot's bone. A bone's or region's
+`skew` turns its y axis that many degrees past its x axis. A slot draws
+`texel × color + offset`. Bone keys add to the setup pose (`rotate` and
+`skew` degrees, `translate` pixels, `scale` multiplies); a `rotate` key
+turns the shorter way to the next, or `rotate 0 0 clockwise 1` (or
+`counterclockwise n`) that way through n more whole turns; every key eases
+linearly to the next, holds with `step`, or follows `curve x1 y1 x2 y2`
+(a cubic Bézier from 0,0 to 1,1, x time and y value; more segments as
+`x y x1 y1 x2 y2`). A `deform` key offsets every influence in order, one
+`x y` pair each; `order <time> <every slot>` redraws back to front from
+then (alone, the file's order); an `ik` key sets the constraint's weight
+and bend. An `ik`'s `bones` are a chain of any length, root first: one
+bone points, two bend at the joint, three or more (a tail, a tentacle, a
+three-joint leg) are solved by FABRIK and curl to the `bend` side. After the IK, a
+`transform t { bones a; target b; mix 1 1 1 1 }` pulls bones towards
+another bone's world rotation, origin, scale and shear by its mix, and an
+`along s { path rail; bones s1 s2; position 0 percent; spacing 0 length;
+rotate tangent 0; mix 1 1 }` lays bones along a `path` attachment (a
+cubic spline, `vertex x y` three per knot, drawn as nothing) while its
+slot shows it. A `skin armor { swap torso torso-armor; swap hat none }`
+block shows other attachments of the same slots wherever the default ones
+would show; `og.Skeleton2D.skin` picks it (`rig.skins.indexOf("armor")`,
+`default` is 0). A `box` draws nothing: `og.anim.skeleton2dBoxes(world, hero)`
+answers its polygon (in the Transform's frame) while its slot shows it,
+for hit and hurt boxes a clip switches. A `child` shows an `armature`
+block (a rig of its own on the same texture) in its slot; it plays the
+parent's clip by name when it has one, else its `clip`, at the parent's
+time; its events arrive as og.Skeleton2DEvent with `armature` its name
+(empty for the skeleton's own clip). A DragonBones 5.5 export is imported instead of written: a rig2d
+`.ogt` with `dragonbones "hero_ske.json"` and `atlas "hero_tex.json"`
+(skew, colour offsets, zOrder and IK timelines, armature displays,
+bounding boxes, path displays and constraints, every skin, curves and `clockwise`
+turns included; Spine's files are not read, convert
+them to this text).
+
+```ts
+const rig = must(og.load.rig2d(world, "rigs/hero.ogt"));
+const hero = must(world.spawn({ name: "hero", position: { x, y, z: 0 } }));
+must(world.insert(hero, og.Skeleton2D, { rig: rig.rig, clip: og.anim.clip(rig, "idle"), layer: 1 }));
+// A foot planted on the ground: one og.IkTarget2D per constraint, moved every tick.
+const foot = must(world.spawn({ name: "hero-foot" }));
+must(world.insert(foot, og.IkTarget2D, { skeleton: hero, constraint: rig.constraints.indexOf("leg"), target: { x, y: groundY } }));
+```
+
+`og.Skeleton2D` plays `clip` at `speed` (`time` is written each tick;
+setting it seeks), wraps when `loop`, mirrors with `flipX` and draws at
+sprite `layer`, lit by `og.Lighting2D` like a sprite there. Clip events
+arrive as `og.Skeleton2DEvent` (`entity`, `clip`, `name`); an
+`og.IkTarget2D` writes `reached` and `error` (its `weight` multiplies the
+constraint's own). The pose is a function of the component, the
+Transform and the targets, so a snapshot carries only the playback
+position and the boxes. `templates/game-2d`'s lamp keeper
+(`assets/rigs/keeper.ogt`, `spawnKeeper`, `Walk`, `Plant`) shows all of
+it. A walk is the walk clip played while a system moves the entity, with
+the feet's targets stepping in time: each planted for half the cycle
+(sliding back as fast as the body goes), then swung a stride ahead, so
+the feet stay on the ground the IK finds.
+
+### Cutscenes: timelines and paths
+
+A cutscene, an intro, a scripted beat or a fly-through is a `type timeline`
+file, not code (`reference/timeline.md`, `reference/path.md`;
+`templates/game`'s `assets/timelines/intro.ogt` and `tests/intro.og.ts`
+are the pattern). Tracks of keys at seconds: between two keys the later
+key's `ease` (og.tween's names: `cubicInOut`, `quadIn`, ...) mixes them,
+outside them the value is held. Every value is evaluated at the
+timeline's time, never accumulated, so a seek lands exactly where playing
+would (a playtest or a video can start at any second).
+
+```text
+type timeline
+version 1
+---
+name "Intro"
+duration 10
+path "flyby" {
+  kind catmullRom          # or bezier (p0 c0 c1 p1 ...) or linear; closed true wraps
+  point -5 3.2 9
+  point -1.5 2.4 7.5
+  point 2 2 7
+  point 5 2.8 8.5
+}
+track camera {
+  rail "flyby"             # or position/target keys, or follow "<entity>"
+  key 0 {
+    at 0
+    target 0 1 0
+    fov 50
+  }
+  key 9.5 {
+    at 1
+    target 1.5 1 0
+    fov 42
+    ease cubicInOut
+  }
+}
+track transform "trickster" {
+  key 2 {
+    position 2 0 0
+  }
+  key 5 {
+    position 0.5 0 1.5
+    rotation 0 90 0
+    ease cubicInOut
+  }
+}
+track animation "trickster" {     # the entity's og.Model's clips (or `model "<glb>"`)
+  key 0 {
+    clip "idle"
+    loop true
+  }
+  key 2 {
+    clip "walk"
+    loop true
+    blendIn 0.3
+  }
+}
+track caption {
+  captions "narration.srt"   # beside the timeline; or word timestamps .json
+  style lg                   # a UI type step
+  anchor bottom
+}
+track audio {
+  key 1 {
+    sound "audio/blip.wav"
+    volume 0.6
+    bus sfx
+  }
+}
+track music {
+  key 0 {
+    sound "audio/theme.ogg"
+    fadeIn 1
+    fadeOut 2
+    end 9
+  }
+}
+track event {
+  key 5.5 {
+    do "spawn_wave:2"
+    retroactive true
+  }
+}
+track transition {
+  key 0 {   # cut, fade, wipe, dissolve, iris, slide
+    kind fade
+    mode in
+    duration 1
+  }
+  key 9 {
+    kind fade
+    mode out
+    duration 1
+  }
+}
+track marker {
+  key 5.5 {
+    name "drop"
+  }
+}
+```
+
+The cook checks
+the sounds and models it names and imports the captions, so an `.srt`
+edit recooks the timeline. Play it from code or from the command channel:
+
+```ts
+const intro = must(og.load.timeline(world, "timelines/intro.ogt"));
+const e = world.spawn({ name: "intro" });
+world.insert(e, og.Timeline, { asset: intro });
+og.timeline.play(world, e);         // pause, seek(world, e, 4), stop
+// a system reading og.TimelineMarker (name "drop") or og.TimelineEnded reacts to it
+```
+
+`og run . --commands "0:timeline:play:intro;4:screenshot;8:screenshot"`
+plays `timelines/intro.ogt` on an entity named `timeline-intro`;
+`timeline:seek:4`, `timeline:pause`, `timeline:resume`, `timeline:stop`
+take an optional `:<name>`. While a timeline with a camera track plays
+(or is paused) it owns `og.Camera`; it hands back the camera it found
+when it stops or ends. Event keys run their action at the start of the
+next tick; a seek skips the events it passes unless they are
+`retroactive`, and markers are sent only by playing past them. A capture
+at `t:` shows the world after the ticks before t: the play's first tick
+is the timeline's time 0, so the frame at `4:` shows 3.983 s at 60 Hz.
+
+Paths on their own: `og.path.create(world, { points, kind, closed,
+tension })` or `og.path.find(world, "<name>")` for one a scene declares
+(the same `path` block in a `type scene`); `og.path.sample(world, p, t)`
+gives position, tangent and up at arc-length t 0..1, `length` and
+`nearest` the rest. `og.PathFollower { path, speed, loop, align, offset }`
+moves an entity along one each tick (`distance` is its own field, so a
+snapshot keeps it); `og.CameraRail { path }` rides one instead of its
+inline points.
+
 ## 10. Effects
 
 Every effect is off until the game turns it on, as data:
@@ -1094,8 +1400,10 @@ render sprite 12
   `underwaterDensity` and the surface from below shows the sky only
   straight up (on by default; set the density to 0 to see through).
 
-**Terrain** (`reference/terrain.md`) is a height field cooked from a
-`type terrain` .ogt beside a 16-bit grey PNG (or an EXR in metres):
+**Terrain** (`reference/terrain.md`, 3D projects only: a `2d` project's
+publish build has none, §2) is a height field cooked from a
+`type terrain` .ogt beside a 16-bit grey PNG (or an EXR in metres), or
+generated by the cook (below):
 
 ```text
 type terrain
@@ -1106,9 +1414,23 @@ height -20 120             # metres
 size 2048 2048             # metres along x and z, centred on the entity
 control "island-control.png"  # optional RGBA: layer 0 in R, 1 in G, 2 in B, 3 in A
 heightBlend 0.15           # sharpen the blends by each albedo's alpha (its height)
-layer { albedo "textures/grass.png" normal "textures/grass-n.png" tile 6 slope 0 30 }
-layer { albedo "textures/rock.png" tile 12 triplanar true slope 28 90 }
-layer { albedo "textures/snow.png" altitude 90 1000 altitudeFade 10 }
+layer {                    # a block's '}' stands alone on its line
+  albedo "textures/grass.png"
+  normal "textures/grass-n.png"
+  tile 6
+  slope 0 30
+}
+layer {
+  albedo "textures/rock.png"
+  tile 12
+  triplanar true
+  slope 28 90
+}
+layer {
+  albedo "textures/snow.png"
+  altitude 90 1000
+  altitudeFade 10
+}
 ```
 
 A layer shows where its control channel (1 without a map) times its slope
@@ -1123,6 +1445,151 @@ world.insert(ground, og.Terrain, { data: info.data });
 world.insert(ground, og.Collider, { shape: SHAPE_HEIGHTFIELD, mesh: info.geometry });
 ```
 
+**A generated terrain.** Instead of `heightmap`, a `generate` block makes
+the field in the cook (never both: the cook refuses the pair and names
+the lines). `height` and `size` mean what they mean for a heightmap: the
+field is stretched so its lowest sample is `height`'s low and its highest
+its high, and no sample leaves that range. Every line, with its default
+(leave out what you do not need; erosion, thermal, terraces, rivers and
+the sea are off until given):
+
+```text
+type terrain
+version 1
+---
+height -40 160             # metres
+size 1024 1024             # metres along x and z
+generate {
+  samples 257 257          # columns and rows (2 to 4097)
+  seed 1                   # another seed, another terrain of the same kind
+  noise {
+    octaves 6              # 1 to 12: more is finer detail
+    frequency 3            # features across the longer side
+    lacunarity 2           # each octave's frequency over the last's (1 to 8)
+    gain 0.5               # each octave's amplitude over the last's (0 to 1): higher is rougher
+    warp 0                 # domain warp in features: 0.3 to 1 bends ridges and coasts
+  }
+  mask island 0.4          # land fades to `height`'s low over this share of the half size
+                           # or `mask ridge 1`: sharp ridged mountains (0 to 1); default no mask
+  erosion {                # hydraulic erosion: seeded drops carve gullies and fill valleys
+    drops 40000            # ~0.5 to 1 per sample; more is deeper erosion and a slower cook
+    lifetime 30
+    radius 3               # samples each drop erodes around it
+    inertia 0.05
+    capacity 4
+    deposition 0.3
+    erosion 0.3
+    evaporation 0.01
+    gravity 4
+  }
+  thermal {                # slopes steeper than talus slump into scree
+    talus 35               # degrees
+    iterations 20
+    rate 0.5
+  }
+  terraces {
+    step 10                # metres between steps
+    blend 0.4              # 0 hard steps, 1 smooth ramps
+  }
+  sea 0                    # metres above the entity: og.terrain.load's seaLevel
+  shore 2                  # metres either side of the sea flattened into beaches (needs sea)
+  rivers {                 # carved where the flow gathers, down to the sea or the edge
+    threshold 400          # samples draining through before it is a river: lower, more rivers
+    depth 2                # metres
+    width 6                # metres
+  }
+  moisture {               # what biomes read, 0 to 1
+    flow 1                 # weight of the gathered flow (wet in valleys and by rivers)
+    scale 64               # samples draining through for half of it
+    noise 0.5              # weight of a noise
+    frequency 6
+  }
+  biome {                  # any number; each writes its layer's control channel
+    layer 0                # required: the layer (0 to 3, one the terrain has)
+    weight 1
+    altitude -1000000 1000000   # metres above the entity
+    altitudeFade 2
+    slope 0 90             # degrees
+    slopeFade 4
+    moisture 0 1
+    moistureFade 0.1
+  }
+}
+layer {
+  albedo "textures/sand.png"
+  tile 4
+}
+layer {
+  albedo "textures/grass.png"
+  tile 6
+}
+layer {
+  albedo "textures/rock.png"
+  tile 12
+  triplanar true
+}
+```
+
+An island with beaches, rivers and rock on its cliffs, for that file's
+three layers (a block's `{` ends its line):
+
+```text
+generate {
+  seed 7
+  noise {
+    warp 0.5
+  }
+  mask island 0.45
+  erosion {
+    drops 40000
+  }
+  sea 6
+  shore 3
+  rivers {
+    threshold 300
+    depth 2.5
+    width 8
+  }
+  biome {
+    layer 0
+    altitude -1000 9
+  }
+  biome {
+    layer 1
+    altitude 9 1000
+    slope 0 32
+  }
+  biome {
+    layer 2
+    slope 32 90
+  }
+}
+```
+
+With `biome` rules the generator writes the control map (a terrain with
+biomes names no `control`); a channel is the most any of its layer's
+biomes gives a sample, its `weight` times its three bands. Without biomes
+there is no control map and the layers' own `slope` and `altitude`
+place them, as for a heightmap. The same file makes the same terrain on
+every machine (the generator uses only exact arithmetic and its own
+random numbers). It is a credible terrain of a kind, never a terrain from
+a picture: move the seed, the mask and the erosion until it reads right.
+`og cook --report` gives its height histogram, the share of land above
+the sea and the rivers' length, and writes its height and control maps
+as PNGs to `og-out/terrain-maps/` to look at.
+
+Its sea is the water's level; the water is the terrain's size:
+
+```ts
+if (info.seaLevel !== null) {
+  const sea = must(world.spawn({ name: "sea", position: { x: 0, y: info.seaLevel, z: 0 } }));
+  world.insert(sea, og.Water, { size: info.size, segments: 128 });
+}
+```
+
+(on the terrain's entity's x and z, under its parent if it has one; an
+`og.WaterSurface` on the same entity makes the waves move and bodies float).
+
 It is drawn around the camera at finer detail nearby (casting and
 receiving shadows, under the fog), placed by its entity's world transform
 (turn or scale the entity and the terrain turns and scales with it), and
@@ -1353,7 +1820,7 @@ cloth's points (about 1 ms per 1,000) are the ones to count (§13).
 A **look** is an `.ogt` of `type look` under `assets/looks/` that sets the
 whole treatment of the frame at once: the resources `RenderSettings`,
 `PostEffects`, `Stylise`, `MaterialStyle`, `Fog`, `Sky` and `Environment`
-(one block each, fields by name), the UI `skin` and the `antialias`.
+(one block each, fields by name), the UI style (`ui`) and the `antialias`.
 Choosing one for a premise is og-taste §1 and §12; this is the mechanism.
 
 ```text
@@ -1362,7 +1829,7 @@ version 1
 ---
 name "Harbour"
 extends "anime-cel-3d"           # a built-in preset (templates/looks/<slug>.ogt) or another look's id
-skin "skins/harbour/skin.ogt"
+ui "styles/harbour/style.ogt"     # the game's own UI style, or a built-in by slug (ui "fantasy")
 Stylise {
   ink true
   inkWidth 1.5
@@ -1384,14 +1851,14 @@ og.render.look(world)?.name;                                              // the
 - Applying a look replaces each resource it names **whole** (the fields it
   sets, the rest their defaults; `PostEffects.flash` and `shakeTrauma`
   keep theirs) and leaves the others alone, then configures the UI with
-  its skin. Write per-game tweaks in `start` after it, or in the look. A
+  its style. Write per-game tweaks in `start` after it, or in the look. A
   system that applies one declares those resources among its writes.
 - `extends` flattens at cook time, field by field (a field written wins);
   `assets/looks/<slug>.ogt` of the game's own replaces the preset of that
   slug for every look that extends it. The cook refuses an unknown field,
   a value out of range and an asset not in the bundle, naming the line.
 - `og.load.lookInfo` (and `og.render.look`) answer `LookInfo`: `name`,
-  `extends`, `resources`, `skin`, `antialias`. A look's `antialias` (tier,
+  `extends`, `resources`, `style`, `antialias`. A look's `antialias` (tier,
   off, msaa4 or taa) is the renderer's when `GameDesc.render` names none.
 - **`og.Stylise`** moves the frame away from the photographic, every
   primitive off at zero: the pixel grid (`pixelHeight`, `pixelUpscale`,
@@ -1472,6 +1939,35 @@ og.render.look(world)?.name;                                              // the
   stays sharper under camera motion and `taaSharpen` (0–1) restores
   detail TAA softens. `RenderCapabilities.antialias` says what the device
   resolved it to.
+- **Graphics quality** is RenderSettings' quality fields, read every
+  frame: `rectShadows`, `shadowedLights`, `shadowMapScale`,
+  `volumetricFog`, `softParticles`, `screenSpaceReflections`,
+  `ambientOcclusion`, `msaaSamples` (4, or 1 for FXAA where the
+  antialiasing multisamples). `og.render.applyQuality(world, preset)`
+  writes a preset's row of them and records it in
+  `RenderSettings.quality` (`none` before any):
+
+  | Field | low | medium | high |
+  |---|---|---|---|
+  | rectShadows | false | true | true |
+  | shadowedLights | 2 | 8 | 8 |
+  | shadowMapScale | 0.5 | 1 | 2 |
+  | volumetricFog, softParticles, screenSpaceReflections, ambientOcclusion | false | true | true |
+  | msaaSamples | 1 | 4 | 4 |
+
+  Medium is the defaults, the frame drawn before any preset. The renderer
+  reads the fields and nothing else, so `og run --commands
+  "0.5:get:og.RenderSettings"` shows what is drawn, and a field set after
+  the preset wins. The switches only take away: the scene's PostEffects
+  and lights keep their settings. The settings screen applies the
+  player's pick when given the world (`og.ui.settingsScreen(id, { world,
+  settings, ... })`); apply a saved preset yourself at start:
+
+  ```ts
+  start(world) { og.render.applyQuality(world, save.settings.quality ?? "medium"); }
+  ```
+
+  Inside a system, declare `og.RenderSettings` among its writes.
 
 ## 17. Saving progress
 
@@ -1576,8 +2072,827 @@ Test either across a relaunch with a playtest's `store: "keep"` and
 tape of inputs) and a ghost (a tape of poses) are og-core §2's
 "Recording, replaying and ghosts".
 
-## 18. Where to look things up
+## 18. Geometry made at run time, lines, points and debug draw
+
+Meshes need not come from a file. `og.render.bufferGeometry(world, desc)`
+takes three.js BufferGeometry's attributes: `positions` (a Float32Array of
+x y z), and optionally `normals`, `uvs` (v down the image), `colors`
+(r g b or r g b a, multiplied into the material), `tangents` and `indices`
+(a Uint32Array, counter-clockwise from the front). Missing normals are
+computed as `computeVertexNormals` does. The geometry draws as any other
+through `og.Mesh`, and it is a `Collider.mesh` at once (`physics` is true by
+default), so a procedural level collides with what is drawn:
+
+```ts
+const terrain = must(og.render.bufferGeometry(world, { positions, colors, indices, dynamic: true }));
+world.insert(e, og.Mesh, { geometry: terrain, material });
+world.insert(e, og.RigidBody, { kind: BODY_STATIC });
+world.insert(e, og.Collider, { shape: 5 /* SHAPE_MESH */, mesh: terrain });
+// Each tick (water, a deforming surface): every attribute again.
+must(og.render.updateGeometry(world, terrain, { positions, colors, indices }));
+```
+
+Only a geometry made with `dynamic: true` can be updated. The same vertex
+and index counts rewrite it in place, and other counts reallocate it. Its
+physics mesh is re-registered, and its colliders are rebuilt at the next
+step. `og.render.geometryInfo` answers the counts and bounds of any
+geometry.
+
+Beside `boxGeometry`, `planeGeometry` and `sphereGeometry`, three.js's
+primitives keep their parameters and defaults: `cylinderGeometry`,
+`coneGeometry`, `capsuleGeometry` (an og.Collider capsule of the same
+radius and `height` matches it), `torusGeometry`, `ringGeometry`,
+`circleGeometry` and `tubeGeometry`. A tube follows a centripetal
+Catmull-Rom curve through `points`, for pipes, rails and cables; give it
+`path` instead (an og.path from `og.path.create`, or a scene's `path`
+block found by `og.path.find`) and it follows that path's own curve,
+Bezier or linear included, closed when the path is. Its rings are evenly
+spaced along the length, as three.js spaces them. Rings and circles are one-sided, so use
+`side: "double"` to see them from behind. `wireframe: true` on a
+standard material draws the triangle edges instead of the faces, one pixel
+wide on every tier.
+
+**Shapes, extrusions, lathes and solids.** Three.js's modelling classes
+keep their names, parameters and defaults, so a three.js extrusion is a
+paste. `og.Shape` and `og.Path2` are three.js's Shape and Path:
+`moveTo`, `lineTo`, `quadraticCurveTo`, `bezierCurveTo`, `splineThru`,
+`arc`, `absarc`, `ellipse`, `absellipse`, `closePath`, `holes` and
+`getPoints(divisions)`. They flatten to points before they cross to the
+engine, so a points array works wherever a shape does
+(`reference/shapes.md`).
+- `shapeGeometry` is a flat shape with holes, one-sided like a circle.
+- `extrudeGeometry` pushes shapes along +Z (`depth`, `steps`) or along an
+  og.path (`extrudePath`). `bevelEnabled`, `bevelThickness`, `bevelSize`,
+  `bevelOffset` and `bevelSegments` round its edges, as in three.js.
+- `latheGeometry` turns a profile of `points` round +Y (`segments`,
+  `phiStart`, `phiLength`), for vases, bottles and columns.
+- `polyhedronGeometry` takes `vertices`, `indices`, `radius` and `detail`.
+  `icosahedronGeometry`, `dodecahedronGeometry`, `octahedronGeometry` and
+  `tetrahedronGeometry` take `radius` and `detail`.
+- `sweepGeometry` sweeps a 2D `section` along an og.path. Its `scale` and
+  `twist` are keyed over the path's length from 0 to 1, for horns, tusks,
+  handles and twisted columns.
+- `mergeGeometries` places `parts` (each a geometry with `position`,
+  `quaternion`, `scale` and a `mirror` axis) into one draw. Write an
+  array as the same part at several placements.
+- `csgGeometry` is `union`, `subtract` or `intersect` of two placed
+  closed geometries. Chain calls for more operands.
+
+Every result is a geometry like `bufferGeometry`'s, with a BVH, `physics`
+and `dynamic`, and answered by `geometryInfo`:
+
+```ts
+const gear = new og.Shape().absarc(0, 0, 1, 0, Math.PI * 2, false);
+gear.holes.push(new og.Path2().absarc(0, 0, 0.3, 0, Math.PI * 2, true));
+const disc = must(og.render.extrudeGeometry(world, {
+  shapes: gear, depth: 0.2, bevelEnabled: true, bevelThickness: 0.05, bevelSize: 0.05,
+}));
+const vase = must(og.render.latheGeometry(world, {
+  points: [{ x: 0, y: 0 }, { x: 0.5, y: 0.1 }, { x: 0.3, y: 1 }, { x: 0.4, y: 1.4 }],
+  segments: 32,
+}));
+const cube = must(og.render.boxGeometry(world, { width: 1, height: 1, depth: 1 }));
+const ball = must(og.render.sphereGeometry(world, { radius: 0.15 }));
+const dice = must(og.render.csgGeometry(world, {
+  op: "subtract", a: { geometry: cube }, b: { geometry: ball, position: { x: 0, y: 0, z: 0.5 } },
+}));
+```
+
+The generators and the CSG decide every cut with exact predicates and use
+no platform trigonometry, so every host makes the same triangles. A CSG
+operand must be closed (every edge shared by two triangles). Its cost
+grows with the product of the two triangle counts where their boxes
+overlap, so cut low-poly operands at load, not every tick.
+
+Every generator above takes `uvRepeat` as `boxGeometry` does (its uvs
+scaled, so a texture tiles). `bevelSize` left out (or null) is
+`bevelThickness - 0.1`, as in three.js: 0.1 at the default thickness.
+
+**Models written as text: `type model`.** A prop made of these parts
+belongs in an asset, not in `start`: an `.ogt` of `type model` under
+`assets/` names each part's geometry by its `og.render` call, with the
+desc's field names and defaults, places it as `mergeGeometries` places a
+part, gives it a material and hangs it from a named pivot. `og cook`
+builds it into the same model blob a glTF cooks to: meshopt, levels of
+detail with their measured errors, the raycast BVH, the nodes. Load it
+with `og.load.gltf(world, "models/clockwork.ogt")` and `world.instantiate`,
+or name it in a scene (`model "models/clockwork.ogt"`), as any model.
+
+```
+type model
+version 1
+---
+material "brass" {
+  color 0.78 0.52 0.16       # linear, as glTF's baseColorFactor
+  metalness 1
+  roughness 0.32
+}
+material "glaze" {
+  color 0.12 0.34 0.72
+  roughness 0.3
+}
+pivot "axle" {               # a node: code and animation find it by name
+  position 0 1.25 0
+}
+part "gear" {
+  pivot "axle"               # hangs from the pivot (default: the root)
+  material "brass"
+  position 0 0 -0.1
+  extrudeGeometry {
+    shape {                  # og.Shape's calls, one a line
+      moveTo 1 0
+      absarc 0 0 1 0 6.283185307179586 false
+      hole {
+        absarc 0 0 0.28 0 6.283185307179586 true
+      }
+    }
+    depth 0.16
+    bevelThickness 0.04
+    bevelSize 0.03
+  }
+}
+part "bolt" {                # one mesh under three nodes: drawn instanced
+  pivot "axle"
+  material "brass"
+  cylinderGeometry {
+    radiusTop 0.06
+    radiusBottom 0.06
+    height 0.36
+  }
+  at {
+    position 0.55 0 0
+    quaternion 0.7071068 0 0 0.7071068
+  }
+  at {
+    position -0.275 0.476 0
+    quaternion 0.7071068 0 0 0.7071068
+  }
+  at {
+    position -0.275 -0.476 0
+    quaternion 0.7071068 0 0 0.7071068
+  }
+}
+part "vase" {
+  material "glaze"
+  position -2.2 0 0
+  latheGeometry {
+    points 0 0 0.32 0.04 0.42 0.4 0.24 0.95 0.3 1.25
+    segments 40
+  }
+}
+part "horn" {
+  position 2.2 0 0
+  sweepGeometry {
+    section {
+      absarc 0 0 0.22 0 6.283185307179586 false
+    }
+    path {                   # og.path's lines: kind, closed, tension, point
+      kind catmullRom
+      point 0 0 0
+      point 0.15 0.6 0
+      point -0.45 1.35 0.15
+    }
+    scale 0 1                # t value, repeatable (twist the same)
+    scale 1 0.05
+  }
+}
+part "dice" {
+  position 1.1 0.3 0.55
+  csgGeometry {
+    op subtract
+    a {                      # an operand: a geometry block, placed
+      boxGeometry {
+        width 0.6
+        height 0.6
+        depth 0.6
+      }
+    }
+    b {
+      position 0 0 0.3
+      icosahedronGeometry {
+        radius 0.08
+        detail 1
+      }
+    }
+  }
+}
+```
+
+- Geometries: `boxGeometry`, `planeGeometry`, `sphereGeometry`,
+  `cylinderGeometry`, `coneGeometry`, `capsuleGeometry`, `torusGeometry`,
+  `shapeGeometry`, `extrudeGeometry` (`extrudePath { }` a path block),
+  `latheGeometry` (`points x y x y ...`), `polyhedronGeometry`, the four
+  solids, `sweepGeometry`, `csgGeometry` (`a { }`, `b { }`) and
+  `mergeGeometries` (`part { }` blocks), each with `uvRepeat u v`. A
+  part holds exactly one; combine more with `csgGeometry` or
+  `mergeGeometries`.
+- Shapes: `moveTo`, `lineTo`, `quadraticCurveTo`, `bezierCurveTo`,
+  `splineThru x y ...`, `arc`, `absarc`, `ellipse`, `absellipse` (angles in
+  radians, then `true` for clockwise), `closePath`, `points x y ...`
+  (setFromPoints) and `hole { }`. They flatten to the points og.Shape
+  gives in TypeScript, bit for bit.
+- Placement: `position`, `quaternion x y z w`, `scale`, `mirror x|y|z`,
+  on the part or in `at { }` blocks, one node each. The same part at
+  several placements is one mesh drawn instanced; a mirrored placement is
+  baked into a mesh of its own.
+- Materials: `color`, `opacity`, `metalness` (default 0), `roughness`
+  (default 1), `emissive`, `emissiveIntensity`, `doubleSided`,
+  `alphaTest`. A part without one draws glTF's grey default.
+- `og cook --report` lists the model's `triangles`, `parts`, `draws` (the
+  distinct meshes; instanced placements are one) and `bvhBytes`/`bvhShare`.
+  Past `budgets.triangles` or `budgets.vertices` in project.ogt the cook
+  refuses it, so lower `segments`, `curveSegments`, `steps` or `detail`.
+  Import settings (`models/clockwork.ogt.ogt`, `model { lods ... raycast
+  false }`) apply as to a glTF.
+- `og dev` re-cooks it on an edit and the running game draws the edit
+  under the same asset handle.
+
+**Lines and points.** `og.render.lines(world, desc)` and
+`og.render.points(world, desc)` are immediate mode, like
+`og.render.sprite`: submit them every tick they should show.
+- Lines: `mode` is `strip`, `segments` or `loop`. `width` is in CSS
+  pixels, or in world units with `worldUnits`. They also take `colors` per
+  point, `depthTest` (false draws over the scene), `dashed` with `dashSize`
+  and `gapSize`, and `screen: true`. Screen lines use CSS pixels from the
+  top left of the play surface and draw over the finished frame, under
+  the UI.
+- Points: `sizeAttenuation` makes `size` a size in world units; without it
+  `size` is a fixed size in CSS pixels.
+- A static set is data: the `og.Lines` and `og.Points` components draw a
+  geometry's vertices in order at the entity's transform. Make the
+  geometry with `bufferGeometry({ positions, colors, physics: false })`,
+  unindexed, any count.
+
+**What is under the cursor.** `og.render.raycast(world, ray, desc)` tests
+what is drawn (every og.Mesh and og.Model at its world transform), not the
+colliders. It goes through a BVH per geometry and answers every hit,
+nearest first; `first: true` answers only the nearest. Each hit has
+`entity`, `geometry`, `distance`, `point`, `normal` (the face's, in world
+space), `uv` and `faceIndex`. Inside a system it reads the meshes as the
+tick started, as `og.physics.raycast` does. Use it for picking, decals on
+detailed meshes, and line of sight against geometry without colliders.
+
+A model's BVH is cooked: `og cook` builds each primitive's into the
+model's `.ogb` (about 6 to 9 bytes per triangle compressed, listed as
+`bvhBytes` in `og cook --report`), and it loads with the mesh, so the
+first raycast never stalls. A model no ray is cast at can leave it out
+with import settings; its first raycast then builds it:
+
+```
+type import
+version 1
+---
+model {
+  raycast false
+}
+```
+
+Leave it on for anything a player can click, aim at or stand a decal on.
+Turn it off for a large model that is only scenery (templates/game's
+16,512-triangle dropship gains 108 KB, 64 % of its blob). Geometries made
+at run time (`bufferGeometry`, the primitives) build theirs when made or
+updated.
+
+**Debug draw.** `og.debug.line`, `box`, `sphere`, `arrow`, `axes` and
+`text` (a label above a world point, in the UI's body font; every field is
+in `reference/debug.md`) each take
+`{ color, width, duration, rotation }`. `duration` is in ticks; 0 shows the
+shape this frame only, so draw it every tick. Debug draws show over the
+finished frame and never hide behind geometry, so they read in every
+capture. The command channel switches the views:
+- `debug:physics` shows the colliders, joints and contacts.
+- `debug:nav` shows the grids' blocked cells, the navmesh polygons and
+  every agent's path.
+- `debug:bounds` shows every drawn mesh's box.
+- `debug:none` shows only the draws; `debug:off` and `debug:on` hide and
+  show everything.
+
+`og.debug.setView` does the same from code, and `RenderOptions.debugView`
+picks a view from the first frame. A publish build drops all of it, so
+debug draws may stay in the code. Debug draws are not world state:
+snapshots and replays do not carry them.
+
+## 19. Video: footage in, videos out
+
+**Footage in.** An `.ogt` of `type video` names an `.mp4`, `.webm` or
+`.mov`; `og cook` turns it with ffmpeg (`og doctor` says whether ffmpeg
+and ffprobe are there) into a texture array of its frames and its sound:
+
+```text
+type video
+version 1
+---
+source "clips/intro.mp4"   # beside this file, or under assets/
+fps 30                     # frames kept per second (default 30)
+maxSeconds 8               # what is kept from the start (default 8)
+size 320 180               # each frame's size (default the source's, at most 1024 wide)
+kind color                 # or pixel: nearest, lossless
+audio true                 # its sound track (default true)
+```
+
+At most 256 frames (fps × seconds): the cook refuses more, naming the
+`maxSeconds` that fits, and warns past 64 MiB of cooked frames. Keep
+footage small: a 320×180 clip of 8 s at 30 fps is about 2 MiB cooked.
+Load it in `start`, then play it with `og.VideoPlayer`; its frame is a
+plain `Texture`, so a sprite, a material map or a UI image shows it:
+
+```ts
+const info = must(og.load.video(world, "clips/intro.ogt"));
+const screen = must(world.spawn({ name: "screen", position: { x: 0, y: 0, z: 0 } }));
+must(world.insert(screen, og.Sprite, { texture: info.texture, width: 16, height: 9 }));
+must(world.insert(screen, og.VideoPlayer, { video: info.video, loop: true }));
+must(world.insert(screen, og.AudioSource, {})); // its sound, kept in step
+```
+
+The `og.video` system plays it by the tick (not the time scale, so the
+picture stays with its sound): with a 30 Hz tick, tick 90 shows the
+frame 3 s in, the same in every run and after a restore. Write
+`VideoPlayer.time` to seek (the sound starts again there on the next
+tick), `playing` to pause, `speed` for slow motion (the pitch follows).
+`frame` and `finished` are written for you, and so is `texture`: each
+player of a video has a texture of its own (the first takes
+`info.texture`, each further one a texture made for it over the same
+frames), so two players at different times show different frames. With
+more than one player, draw each player's `VideoPlayer.texture`. Every field and the loaders are in `reference/video.md`.
+
+**Videos out.** `og render` plays a command script headless and makes a
+video of it: a frame every `tick / fps` ticks (the fps divides the tick
+rate; the error names the nearest that do), read back without the
+probe's round trip.
+
+```sh
+og render . --commands "0.5:type:s;2:key_down:Space" --fps 30 --to 8 \
+  --size 1280x720 --out og-out/intro.mp4 --audio --contact-sheet 6 --jobs 4
+```
+
+It writes `intro.mp4` (H.264; `.webm` is VP9) with the run's audio,
+`intro.frames.json` (each frame's tick, time and SHA-256, and the
+audio's), and `intro.contact-sheet.png`: a grid of frames over the range,
+each labelled with its time and tick. **Review the contact sheet first**:
+one image shows whether the scene moves as the script meant, without
+playing anything. `--out <dir>` (or `--frames png|jpg`) writes the
+frames too; without ffmpeg the frames are what you get. Two runs of one
+script give the same SHA-256s, so a frame that changed is a change you
+made. `--jobs N` splits the range over processes (each starts from a
+snapshot of the world) and gives the same frames, faster.
+`--timeline <name>` renders a timeline (`type timeline`) over its
+duration once timelines exist (stream S2 of docs/depth.md); until then
+use `--commands`. On a CPU-only machine (lavapipe) a 1280×720 frame of the
+3D template takes about 0.4 s in one job, 2.6× less with `--jobs 4`:
+render at 640×360 (about 0.1 s) to iterate, full size once.
+
+## 20. Two players over a room: lockstep
+
+To play together, every peer runs the whole world and only inputs cross
+the room (`reference/net.md`; the rooms themselves are og.platform's, taught by
+the og-platform-sdk skill). Follow three rules:
+
+1. In `start`, set `og.Lockstep`: `enabled = true`, `players`,
+   `inputDelay` (2 on a LAN, 4 to 6 over the internet) and `hashEvery`
+   (10). Spawn one entity per player with `og.PlayerInput { player: seat }`.
+2. Read `og.Input`, `og.Gamepad` and the UI's touch controls in **one**
+   system, and hand them over with
+   `og.net.submit(world, { x, y, buttons, aimX, aimY })` every tick.
+3. Every system that changes the world reads `og.PlayerInput` (its `x`,
+   `y` and `buttons` bits), the world and `og.Rng`, and nothing else: no
+   `Math.random()`, no `Date.now()`, no module variables, no
+   `og.RoomMessage`. Draw per-peer things (whose turn it is, "waiting")
+   with og.ui only, and keep them out of the world.
+
+```ts
+const Submit = defineSystem("Submit", { reads: [og.Input] }, (_q, _t, world) => {
+  const input = must(world.resource(og.Input));
+  must(og.net.submit(world, { x: input.axis("KeyA", "KeyD"), y: input.axis("KeyS", "KeyW"), buttons: input.down("Space") ? 1 : 0 }));
+});
+const Move = defineSystem("Move", { reads: [og.PlayerInput], writes: [og.Transform] }, (q, time) => {
+  for (const a of q.archetypes()) {
+    const pin = a.column(og.PlayerInput);
+    const p = a.column(og.Transform).position;
+    for (let i = 0; i < a.count; i++) p[i * 3] += pin.x[i]! * 6 * time.dt;
+  }
+});
+```
+
+Alone, or with lockstep off, `submit` drives the local player on the next
+tick, so the same code plays single-player. Natively, run `og relay` and
+then `og run . --room ws://127.0.0.1:47900/<room>` in two terminals; on
+the web the shell carries the platform's rooms, and a Play link with
+`?room=<id>` puts the page in that room at load (the game hears
+og.RoomJoined as for its own roomJoin; `og.platform.roomInfo(world).link`
+names the link's room), so a game that plays over a room need not ask for
+one when the link named it. A playtest plays itself in
+a room with `room: { players: 2, commands: [...] }`: its runs are `run`
+and `run.peers`, and each has `netHash` and `lockstep`. Equal `netHash`
+values at the same tick mean the peers stayed in step. Once lockstep runs
+a script's steps are on the room's shared ticks (a peer that took the
+authority's snapshot keeps its steps on theirs), so end each script with
+`quit` (or give `room.ticks`) and every place stops on one tick; a `then`
+step relaunches every place at once into a room of its own, its runs in
+`run.then[n]` and `run.then[n].peers`.
+
+When the worlds part, `og.Desync { tick, peer }` fires once and
+`og.net.status(world).desync` holds the tick. Then
+`--commands "...:dump_desync:d.json"` names the first divergent tick and
+the entity, component and field that differ, with both values: fix the
+system that writes that field. The archetype `templates/archetypes/arena`
+(Coin Duel) is the worked example.
+
+## 21. Checking a run: describe, expect, trace, write-back, budgets
+
+These are the checks to use before opening frames. All of them run from
+`og run --commands`, a playtest's steps or the live probe (`og probe`).
+
+- **`describe[:path]`** (probe `describe`) writes the current frame as
+  JSON. `entities` holds every visible entity, nearest first (`order`):
+  `id` (the probe's id), `name`, `archetype`, `labels`, `box` {x, y, width,
+  height} of its visible pixels and `point` (a pixel `pick` answers it at),
+  both in CSS pixels of the play surface, `drawn` (its box drawn alone),
+  `depth`, `coverage` and `occlusion` (0–1, the share of it others hide).
+  `ui` lists the UI elements with `box`, `kind` and `text`, and `camera`
+  the camera. The boxes come from an entity-id pass over the
+  extracted frame on the CPU, so a run without a renderer describes the
+  same frame. `pick` at an entity's `point` answers that entity.
+- **`expect:<op>`** asserts at its tick. A failure is logged with the tick
+  and the observed value, `og run --json` lists it under `expectations`,
+  and the run exits 1:
+
+  ```text
+  expect:entity:crate:within:380,360,280,240    its described box inside the screen box
+  expect:entity:crate:within:-3,0.4,-1,1,0.6,2  its position inside the world box (x0,y0,z0,x1,y1,z1)
+  expect:event:og.CollisionStarted[:2]          at least one (or exactly 2) since the script began
+  expect:ui:text:=Started                       a UI element shows the text (= exact, else a substring)
+  expect:region:560,16,64,24:color:#9da5b1:24   the region's mean colour within 24 per channel
+  expect:frame:references/start.png:rmse:<=6    the frame against a reference PNG
+  expect:state:score>=3                         a fact of GameDesc.facts by dotted path (== != < <= > >=)
+  ```
+
+  A playtest may be expect steps alone: `templates/game/tests/smoke.og.ts`
+  is. Each expectation counts as a check. Without a renderer a frame or
+  region expectation is unchecked, never failed. Take screen boxes from a
+  `describe` of a good run, with a margin.
+- **`og run --trace out.json`** writes the run in the Chrome trace format;
+  open it in Perfetto (ui.perfetto.dev). Every span lies where it ran.
+  The engine thread holds each tick with its systems, render each frame
+  with its render passes (CPU encoding), gpu the same passes as the GPU
+  ran them (where `og.render.capabilities(world).gpuTimestamps`), load
+  each cooked file read, cook the cook and each output on the cook thread
+  that made it, and `lane N` the jobs og-lanes ran on pool thread N
+  (physics, cull, anim, extract). The probe's `state().timings.systems`,
+  `.passes` and `.gpuPasses` give the last tick's and frame's numbers
+  live.
+- **`save_scene[:path][:spawned]`** (probe `saveScene(write, spawned)`)
+  writes the scenes back after `teleport`, `set` or the Tune panel moved
+  things: the boot scene and every scene `world.instantiate` made, each
+  to its own `.ogt`. Only the lines whose values changed are rewritten;
+  comments and order stay, and a tuned field the text lacks gets a line.
+  Resources are scene text (`resource Run { chimed true }` at the top
+  level of a scene); a tuned resource no scene sets gets a block in the
+  boot scene. `spawned` also writes the entities your code spawned under
+  `# ── spawned at run time ──` at the end of the boot scene; if you keep
+  them, guard their spawn (`if (world.find("bolt") === null)`) so the next
+  run does not make them twice. With a path, the texts go under `--out`
+  to diff first; without one, they replace `assets/<scene>.ogt`. `set`
+  names engine components by their registered name
+  (`set:marker.og.Transform.scale=0.5,0.5,0.5`).
+- **`og cook --report`** writes `og-out/cook-report.json`: per asset its
+  triangles per LOD, vertices, textures (size, format), bones, clips,
+  bytes cooked and flags, and for every other asset its figures under its
+  kind (`sound` seconds/channels/sampleRate/chunks, `font`
+  glyphs/kerningPairs/pages, `scene` entities/instances/components,
+  `navmesh` tiles/polygons/vertices, `timeline` tracks/seconds, `strings`
+  locale/keys, `style`, `behaviour`, `tileset`, `tilemap`, `rig`,
+  `rig2d`, `flipbook`, `shader`, `post`, `emitter`, `look`, `palette`,
+  `lut`, `environment`, `video`, `terrain`, `streamPack`). **`og doctor
+  --project . [--json]`** checks it against `budgets { }` in project.ogt
+  and exits 1 on an over-budget asset, naming the asset, the limit, the
+  value and the fix. The keys are `triangles` 100000, `vertices` 65536,
+  `textureSize` 2048, `bones` 128, `clips` 64, `assetBytes` 8 MiB,
+  `totalBytes` 64 MiB, `soundSeconds` 600, `videoSeconds` 300,
+  `fontGlyphs` 8192, `navPolygons` 65536, `sceneEntities` 10000 and
+  `emitterParticles` 16384, each a default a project may move.
+  `bvhShare` 30 is a warning, not a limit: a model whose cooked raycast
+  BVH is over 30 % of its blob (and at least 16 KiB) is named by `og cook
+  --report` and `og doctor`; write `model { raycast false }` in its .ogt
+  when nothing raycasts against it.
+
+## 22. Levels of detail, reflection probes and screen-space reflections
+
+**Levels of detail.** Every model the cook reads is simplified into
+levels: by default `lods 1 0.5 0.25`, each level a fraction of the full
+mesh's triangles. A glTF's own `MSFT_lod` levels are kept instead. Import
+settings change them per model, and `lods 1` keeps only the full mesh:
+
+```
+type import
+version 1
+---
+model {
+  lods 1 0.4 0.15
+  lodError 0.08
+}
+```
+
+The cook measures each level's error, the largest distance between the
+level and the full mesh in the model's units, and `og cook --report`
+lists each model's triangles (`lods`) and error (`lodErrors`) per level.
+The renderer draws each `og.Model` entity at the coarsest level whose
+error covers less than a pixel at the entity's distance, with
+hysteresis, so nothing flickers at a boundary: a small prop keeps its
+full mesh until it is far away, a large tree drops levels sooner. A
+level whose error is too large for its purpose (a hard-surface model
+melting at a distance) is cooked tighter with `lodError`, or the model
+keeps more detail with `lodBias`. `og.Model.lodBias` (per entity) and
+`RenderSettings.lodBias` (the frame) scale that choice: 2 keeps the full
+mesh twice as far, and 0 always draws it. Check the choice with
+`debug:lod`, which tints models green, yellow, orange and red by level,
+with `dump_entity:<name>` (`render.lod`), and with the triangles in
+`ProbeTimings.triangles` or `dump_render`.
+
+**Reflection probes.** Smooth surfaces reflect the environment map, which
+is the sky. Indoors that is wrong: a chrome sphere in a room would show
+the sky. Put an `og.ReflectionProbe` in the room, and lit surfaces inside
+its box reflect a cube captured from its position instead, box-projected
+so the walls reflect where they are:
+
+```ts
+const probe = must(world.spawn({ name: "hall-probe", position: { x: 0, y: 1.6, z: 0 } }));
+world.insert(probe, og.ReflectionProbe, {
+  size: { x: 10, y: 4.2, z: 10 }, // the room's extents, centred on the entity
+  resolution: 128,                // texels per cube face
+  mode: "baked",                  // or "realtime", every `interval` ticks
+  blendDistance: 0.5,             // fade into the environment at the box's faces
+});
+```
+
+- Choose the probe's mode by what moves in the room:
+  - A `baked` probe is captured once, on its first frame. For a static
+    room, run `og bake probes [project] --commands "0:station:hall"` (the
+    commands reach the scene). It writes the captures into
+    `cooked/probes/`, and runs then load them instead of drawing them.
+    A bake is keyed by the probe's place and size and by its room's
+    content: moving the probe or changing what is in its box (a mesh,
+    a material, a texture, a light) needs a new bake, and until then it
+    draws its own capture. `og doctor --project` lists stale bakes
+    (`stale-probe`).
+  - A `realtime` probe redraws six faces every `interval` ticks. Keep
+    the interval high.
+- Size the box to the room. Each object takes the smallest box holding
+  its centre, so two rooms that share a model each reflect their own.
+  The capture shows everything in the room: characters in their pose
+  (and each one takes the probe of the room its pose stands in), terrain,
+  grass, water (refracting what lies below it), 3D fluids, glass,
+  particles (soft ones fading as in the frame), lines and world sprites
+  and text. Terrain, grass and water inside the box are lit
+  by it too. At most 8 probes (`MAX_REFLECTION_PROBES`) are used,
+  nearest the camera first.
+- `dump_render` lists the frame's probes and whether each was loaded from
+  the cache. In a playtest, assert what the sphere shows with
+  `expect:region:x,y,w,h:color:#rrggbb:tol`, and a model's level of
+  detail and the frame's triangles with `expect:entity:<name>:render.lod==1`
+  and `expect:timings:triangles<=1500000`.
+
+**Screen-space reflections.** On the full tier, `PostEffects.ssr` adds the
+frame's own reflections to smooth surfaces: a wet street, a polished
+floor. They show what is on screen, including moving things:
+
+```ts
+const post = must(world.resource(og.PostEffects));
+post.ssr = true;
+post.ssrMaxDistance = 12; // metres a ray travels
+post.ssrSteps = 48;       // more for long, thin reflections
+post.ssrThickness = 0.3;  // how far behind a surface a ray still hits it
+post.ssrFade = 0.15;      // fade at the screen's edges
+```
+
+SSR is weighted by roughness as the surface is shaded, its roughness map
+and a terrain layer's roughness included (`roughness` 0.05 reflects
+sharply; above 0.75 it reflects nothing), and by Fresnel. What it misses (off screen,
+behind objects) falls back to the probes and the environment, so use SSR
+together with a probe. WebGL2 draws no SSR: check
+`og.render.capabilities(world).ssr`, and on that tier the probe is the
+whole reflection.
+
+## 23. Render targets, second cameras, layers, custom shaders and post passes
+
+**Render to a texture.** `og.render.renderTarget(world, { width, height,
+format, depth })` makes a target, as three.js `WebGLRenderTarget`. It
+answers `{ target, texture, depthTexture, width, height }`. `texture` is
+an ordinary Texture: a material's `map` or `emissiveMap`, an og.Sprite, an
+`og.render.sprite` or an og.ui image shows it. `format` is `ldr` (the
+default) or `hdr`:
+- `ldr`: 8-bit and finished (exposed with the view's `exposure`, tone
+  mapped). Use it for a monitor, a minimap or a portrait, shown through an
+  unlit material's `map`.
+- `hdr`: linear radiance, exposed once with the frame that shows it. Use
+  it for a mirror or a portal, shown as `emissiveMap` on a material whose
+  `color` is black.
+
+`depth: true` also keeps the view's linear depth, from near (0) to far
+(1), of its opaque meshes, on every tier, WebGL2 included. It costs a
+second draw of the view's opaque meshes, so ask for it only when a
+material reads it. (A scene with soft particles, `softDistance` above 0,
+pays that draw in every view anyway: its particles fade against it.)
+`RenderCapabilities.maxRenderTargetSize` is the largest side.
+
+**A second camera.** `og.CameraView` on an entity is a camera with
+og.Camera's fields (`fov`, `near`, `far`, `zoom`, `orthographic`,
+`height`, `exposure`). It looks down the entity's local -Z:
+```ts
+const screen = must(og.render.renderTarget(world, { width: 480, height: 270 }));
+world.insert(monitorMesh, og.Mesh, { geometry: plane, material: must(og.render.standardMaterial(world, { map: screen.texture, unlit: true })) });
+const cam = must(world.spawn({ name: "cctv", position: eye, quaternion: og.transform.lookAt(eye, target) }));
+world.insert(cam, og.CameraView, { target: screen.target, fov: 60, every: 2 });
+// Split-screen: no target, a rect of the frame (fractions from the top left).
+world.insert(p2, og.CameraView, { viewportX: 0.5, viewportWidth: 0.5 });
+```
+- `every: n` draws it on every n-th tick, and the target keeps its last
+  image in between.
+- `order` sorts the views. Every view draws before the frame, so a
+  material shows this frame's image.
+- `clear` with `clearColor` replaces the sky or background colour.
+- `active: false` stops it.
+
+A view draws what the main camera draws, from its own eye and on its own
+`layers`: meshes and models (skinned meshes and custom shaders included),
+opaque then transparent back to front, the terrain and the sky, particle
+systems, trails, og.Lines and og.Points, and world sprites and text, lit and
+shadowed by the frame's lights. Each view is a second draw of everything
+its layers admit, so keep it cheap with `layers` and `every`.
+- An `ldr` target and a viewport are exposed with the view's `exposure`
+  and tone mapped with the frame's curve. An `hdr` target holds linear
+  radiance and is exposed by the frame that shows it.
+- Bloom, AO, SSR, depth of field, colour grading and custom post passes
+  run on the main frame only (the 2D glow, `PostEffects.glow`, is the
+  exception: a view adds its own).
+- In a view, sprites are 2D-lit and glow and 2D fluids and soft
+  particles draw as in the main frame. Screen sprites, the UI and debug
+  draw stay on the main frame.
+
+A viewport view draws over the finished image and under the UI.
+
+**A mirror.** Put `og.Mirror` on the glass's entity. It reflects the main
+camera in the entity's xy plane (its +Z faces the room) and fits the image
+to a `width` × `height` rect:
+```ts
+const rt = must(og.render.renderTarget(world, { width: 512, height: 384, format: "hdr" }));
+world.insert(glass, og.Mesh, { geometry: must(og.render.planeGeometry(world, { width: 4, height: 2.4 })),
+  material: mat({ color: { r: 0, g: 0, b: 0 }, emissive: { r: 1, g: 1, b: 1 }, emissiveMap: rt.texture }) });
+world.insert(glass, og.Mirror, { target: rt.target, width: 4, height: 2.4 });
+```
+
+**Layers.** `layers` on og.Mesh, og.Model, og.Sprite, og.ParticleSystem,
+og.Lines, og.Points and og.Camera (and on og.CameraView and og.Mirror) is a
+three.js bit mask:
+bit n is layer n, and the default 1 is layer 0. A camera draws an object
+when `object.layers & camera.layers` is not 0. `og.render.raycast`'s
+`layers` uses the same test. Some uses:
+- A first-person body on layer 1 (mask 2) is hidden from the player's
+  camera (mask 1) and shown on a third-person monitor (mask 3).
+- A minimap marker only the minimap camera draws.
+
+Shadow maps take every caster whatever its layers, so a hidden object
+still casts a shadow. Give it `castShadow: false` if it should not.
+
+The probe's `describe` lists what the main camera shows, and each
+og.CameraView and og.Mirror under `views` with what its own image shows,
+on its layers. An entity on a layer only a view sees is found under that
+view, not in `entities`. A main-camera entity names the views that also
+show it in its `views`. `pick` and `expect:entity:...:within` read the
+main camera.
+
+**Full custom shaders.** `mode full lit` (or `mode full unlit`) in a `type
+shader` asset replaces the lit shader's stages with your own entries:
+```wgsl
+fn vertex(v: VertexInput, model: mat4x4<f32>, p: Params) -> VertexOutput   // v: position normal uv color tangent (object space; skin and morphs applied)
+fn fragment(f: FragmentInput, p: Params) -> SurfaceOutput                  // f: world local normal uv color data view pixel time
+// VertexOutput: world (projected by the engine), normal, uv, color, data (free, interpolated)
+// SurfaceOutput: color (albedo + alpha; unlit: the colour), normal, metallic, roughness, emissive
+// camera(): view_proj, position, forward, time. tex0(uv)..tex7(uv): the material's map, metalnessMap,
+// roughnessMap, normalMap, emissiveMap, aoMap, gradientMap, dissolveMap. Helpers: standard_vertex(v, model),
+// standard_surface(f), noise3(p).
+```
+An entry you leave out is the standard one.
+- `lit` surfaces are lit by the sun's cascades, the point, spot and rect
+  lights with their shadows and cookies (a rect light as an area, as on a
+  standard material), the environment and the fog. `unlit` surfaces draw
+  as returned.
+- The depth prepass, every shadow pass and every view run the same
+  entries, and alpha under the material's `alphaTest` is cut in each of
+  them. A dissolve's shadow therefore has its holes.
+- Make the material with `og.render.shaderMaterial` and set parameters with
+  `og.render.setShaderParam`, as for hooks (§12).
+- `templates/fx-showcase/assets/shaders/dissolve-full.*` is the example.
+
+**Custom post passes.** A `type post` asset declares
+`fn post(f: PostInput, p: Params) -> vec4<f32>` in its `code` or `source`,
+with up to eight `param` lines. The function reads:
+- `previous(uv)`: the pass before it, linear HDR;
+- `scene_color(uv)`: the lit image;
+- `depth(uv)`: view depth in metres;
+- `normal(uv)`: the world normal;
+- `f.uv`, `f.pixel`, `f.size` and `f.time`.
+
+It returns linear HDR. To use one:
+1. Load it with `og.load.post(world, "post/crt.ogt")`.
+2. Put the handles in the list `PostEffects.custom`, at most
+   `RenderCapabilities.maxCustomPosts` (8) of them. They run in its order,
+   each over the one before it, after depth of field and motion blur and
+   before exposure, bloom and tone mapping. Write the list whole:
+   `post.custom = [grade, crt]`, `post.custom = [...post.custom, h]`,
+   `post.custom = []`. Reading it answers a frozen copy, so
+   `post.custom.push(h)` throws instead of changing nothing; nine passes
+   are refused, never cut to eight. A look gives it on one line:
+   `custom "post/tint.ogt" "post/crt.ogt"`.
+3. Set its parameters with `og.render.setPostParam(world, post, "curve",
+   [0.1])`.
+
+The cook compiles it for every back end. A pass that a device still fails
+to compile is skipped and listed by `og.render.postErrors(world)`.
+`templates/fx-showcase/assets/post/crt.*` is a CRT example.
+
+## 24. Baked lighting, volumetric fog, area lights and cookies
+
+**Baked lighting.** Use it for light that bounces around a static space,
+such as a red wall tinting the floor beside it or a room lit through its
+door. Mark the scene's unmoving models `static true` and put an
+`og.LightVolume` box over the space where dynamic objects move:
+
+```
+entity "hall" {
+  model "models/hall.glb"
+  static true
+  Transform { position 0 0 0 quaternion 0 0 0 1 scale 1 1 1 }
+}
+entity "hall-probes" {
+  Transform { position 0 2 0 quaternion 0 0 0 1 scale 1 1 1 }
+  LightVolume { size 12 4 12 spacing 1 }
+}
+```
+
+Then run `og bake lightmaps` in the project. Its options are
+`--samples 256`, `--bounces 3`, `--texels-per-metre 16`, `--max-size 1024`,
+`--sky r,g,b`, `--seconds S` and `--scene <id>`; the fx-showcase Cornell
+box takes 1.4 s at 512 samples. The bake is a CPU path tracer and needs
+no GPU. It writes `<scene>.lightmap.ogt` and `.ktx2` beside the scene;
+commit both.
+
+A static entity needs a name. The bake holds the light that bounces, the
+sky and emissive surfaces; lights still shine and cast shadows live on
+top. Static models draw with their lightmap, and everything else inside a
+LightVolume takes its ambient light from the probes. After you change the
+scene's text or a static model's geometry, the bake is stale and the scene
+renders unbaked until you bake again; a re-cook that keeps the geometry
+(a cooker update, a texture or raycast option) keeps the bake. `og doctor
+--project` warns `unbaked`, and
+`og.render.bakedLighting(world)` lists each scene with `baked` and a
+`reason`. `RenderSettings.bakedLighting = false` draws everything unbaked,
+which is useful to compare. Every instantiated scene draws its own bake,
+so baked scenes loaded together or streamed in side by side all keep
+their light.
+
+**Volumetric fog.** Set `Fog.volumetric = true` to light the fog as a
+medium, which gives shafts through windows and the cones of spots. Tune it
+with `density`, `heightDensity` and `falloff` (thicker low down),
+`scattering` (how bright) and `anisotropy` (towards 1, bright looking into
+the light), up to `volumetricDistance`. Fog of 0.03 to 0.1 per metre reads
+well indoors. With `og.DayNight`, the shafts move with the sun.
+`RenderCapabilities.volumetricFog` is `froxel` on the full tier or
+`raymarch` on WebGL2. On both, the sun, spots, points and rect lights light
+the fog, so a lantern glows in it on WebGL2 too.
+`RenderCapabilities.volumetricLights` is how many local lights light one
+sample (64 for the froxel grid, 8 for the raymarch, brightest first).
+
+**Area lights.** `og.RectLight { width, height, color, intensity,
+twoSided }` emits from a rectangle facing the entity's -Z. Aim it with
+`og.transform.lookAt`, as you would a spot. A glossy floor shows the
+rectangle's shape in its highlight. Pair one with an emissive slab for
+the fixture. Set `castShadow` for a soft shadow: sharp where a caster
+touches the floor, widening with the panel's size away from it. It takes
+one shadow layer (two when `twoSided`) from the same budget as shadowed
+spots and points, and is drawn from the panel's centre, so a caster right
+against a large panel is shadowed as from its middle.
+
+**Cookies.** `SpotLight.cookie` is a texture projected along the cone,
+like a window's lattice or stained glass. `PointLight.cookie` is six
+square faces stacked top to bottom (+X, -X, +Y, -Y, +Z, -Z), like a
+pierced lantern. A cookie multiplies the light and its colour. A frame
+draws at most `og.render.capabilities(world).maxLightCookies` (24) cookie
+layers: a spot cookie takes one, a point cookie six, and a texture shared
+by lights of one kind counts once. Past that, the later lights shine
+without their cookies and the log warns, naming them; share cookie
+textures between lanterns to stay under it.
+
+## 25. Where to look things up
 
 `reference/index.md` (the generated wiki shipped with this skill) maps every
 module (grouped by skill, as in §1), type and function to its page, with the IDL text, defaults, ranges
 and units of every field.
+
+`guides/three-to-og.md` (beside this skill) maps three.js's classes and
+idioms to the engine's: the scene graph to entities and og.Parent,
+Object3D to og.Transform, the geometry classes to §18's generators, the
+materials to StandardMaterialDesc, the loaders to og.load, the render
+loop to systems on the tick, Raycaster to `og.render.raycast`, and the
+gaps by name. `og migrate three <file.ts>` rewrites a three.js file's
+mechanical part with those mappings and marks every line it cannot,
+citing the guide's section.