@origingame/engine 0.2.0 → 0.3.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,7 +114,7 @@ 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-ai** | enemies and NPCs: navigation and minds as data | nav, ai |
 | **og-audio** | sound: events, presets, UI sounds, the mix, music, space | audio |
@@ -883,6 +888,276 @@ 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); 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. 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. 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 and curves 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:
@@ -1353,7 +1628,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 +1637,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 +1659,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`,
@@ -1576,7 +1851,601 @@ 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.
+
+**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.
+
+## 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
+}
+```
+
+`og cook --report` lists each model's triangles per level. The renderer
+draws each `og.Model` entity at the level its size on screen calls for,
+with hysteresis, so nothing flickers at a boundary. `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`. A field of 2,000
+trees draws about 4× fewer triangles with LOD on.
+
+**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,
+  terrain, grass, glass. 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.
+`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, 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.
+- In a view, sprites are not 2D-lit and do not glow. Trails, 2D fluids,
+  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 and spot lights
+  with their shadows, 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 handle in `PostEffects.custom1` to `custom8`
+   (`RenderCapabilities.maxCustomPosts` is 8). They run in that order, a
+   slot left 0 skipped, each over the one before it, after depth of field
+   and motion blur and before exposure, bloom and tone mapping. There is
+   no `custom` list: a resource's fields hold one value each.
+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