@origingame/engine 0.3.0 → 0.5.0

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

@@ -116,6 +116,7 @@ Mistakes the games made, or would have, before reading the right page:
 | **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, 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 |
@@ -155,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
@@ -205,6 +213,36 @@ export default og.game({
   channel and playtests can call (`0.5:spawn_wave:3`), with their usage in
   `GameDesc.commandHelp` for `help` (og-build §1). Add one for each state a
   test needs to reach quickly, instead of playing there.
+  - **Arguments are colon-delimited**, the fields after the name, each a
+    string (`Number(args[0])` to read a number); a space is part of its
+    field, not a separator, and `\:` writes a colon inside one. Two
+    arguments, and the usage that says so:
+
+    ```ts
+    commands: { records: (world, args) => setRecords(world, Number(args[0]), Number(args[1])) },
+    commandHelp: { records: { usage: "<berries>:<seconds>", doc: "Sets the isle's records." } },
+    ```
+
+    `0.5:records:12:34.5` hands `args` `["12", "34.5"]`; `records:12 34.5`
+    would hand one argument, `"12 34.5"`.
+  - **Reserved names.** The channel's core actions are not a game's to
+    take, and the game refuses to start on one (`'pause' is a core action;
+    register under another name`): `screenshot`, `listen`, `touch_move_to`,
+    `touch_move`, `touch_start`, `touch_end`, `touch`, `scroll`, `gamepad`,
+    `key_down`, `key_up`, `type`, `compose`, `commit`, `move_to_text`,
+    `teleport`, `frame_entity`, `dump_world`, `dump_entity`, `dump_ui`,
+    `get`, `set`, `seed`, `pause`, `resume`, `advance`, `describe`,
+    `expect`, `save_scene`, `quit` and `help`. The actions the engine's
+    modules register are refused the same way (`'view' is a registered
+    engine action; register under another name`), in every build:
+    `bake_probes`, `cover`, `debug`, `dump_ai`, `dump_desync`,
+    `dump_lanes`, `dump_nav`, `dump_platform`, `dump_pulse`,
+    `dump_render`, `dump_room`, `dump_stream`, `lanes`, `locale`,
+    `terrain_stream`, `timeline`, `turntable` and `view` (`help` marks
+    them `(registered)`). The engine's `pause`
+    freezes the tick from outside the game; the game's own pause (its menu
+    open, `Game.paused` set) is a game action under its own name,
+    `open_pause`.
 - **Facts** (`GameDesc.facts`) return a small JSON object for the probe's
   `state()`: score, phase, lives. Tests assert on facts and dumps.
 
@@ -247,7 +285,19 @@ registered schema and refuses a model path that does not exist.
   (ETC1S for colour, UASTC for normal and linear maps), WAV into QOA, fonts
   into MSDF atlases, scenes into component tables. Import settings live next
   to the source as `<file>.ogt` (`texture { kind normal }`,
-  `font { charset latin chars "开始游戏" }`).
+  `font { charset latin chars "开始游戏" }`). The prose here writes a
+  block on one line for short; in a file, as in every `.ogt`, a `{` ends
+  its key's line and a `}` stands alone on its own (the parser refuses
+  `'{' must end its line`):
+
+  ```text
+  type import
+  version 1
+  ---
+  texture {
+    kind normal
+  }
+  ```
 - At load a cooked texture reaches the GPU block-compressed in the device's
   format with its mips (BC7, and BC5 for normal maps, on desktop GPUs; ASTC
   on Apple and most Android; ETC2 and EAC elsewhere), a quarter of RGBA8's
@@ -280,9 +330,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.
 
@@ -380,7 +434,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
@@ -393,6 +453,22 @@ else ignores it. The stamp is world state, so a replay reproduces it.
   ```ts
   world.insert(hero, og.Sprite, { texture: tex, width: 1, height: 1.5, anchor: { x: 0.5, y: 0 }, dropShadow: 0.5, shadow: 0.3 });
   ```
+- **Billboards** (three.js `Sprite`): `og.Sprite.facing` (or
+  `SpriteDesc.facing`) turns a world sprite to the camera that draws it.
+  `"cameraY"` stands it upright and turns it about y (trees, characters,
+  props a looking-down camera must not tip back); `"camera"` lays it in
+  the view plane (smoke, glints, signs); `"none"`, the default, keeps the
+  xy plane. Every camera turns it to itself (og.CameraView, og.Mirror, reflection
+  probes), the turn is render-only (never read by systems or snapshots),
+  faced sprites in one layer draw back to front from the camera and are
+  culled off screen, and a faced sprite's `dropShadow` is its whole shape
+  from any angle. It is still a sprite: flash, glow, blend, 2D lighting,
+  arrays, flipbooks and `toneMapped` all apply. A billboard behind a
+  transparent mesh still draws over it (sprites draw after the 3D scene).
+
+  ```ts
+  world.insert(tree, og.Sprite, { texture: treeTex, width: 2, height: 2.6, anchor: { x: 0.5, y: 0 }, facing: "cameraY", dropShadow: 0.6 });
+  ```
 - **World UI that must not change with the light** (speech bubbles, name
   tags, markers) takes `og.Sprite.toneMapped: false` (or
   `SpriteDesc.toneMapped`), three.js's `Material.toneMapped`: still placed
@@ -699,6 +775,65 @@ strike, a bite or a fall at weight 1, back to 0 when `finished`.
 Transform by the root joint's xz travel and yaw, `full` by all of it,
 `off` (the default) leaves the hips travelling inside the model; switch it
 to `planar` for a lunge's clip and back to `off` after.
+**Look-at and joint limits.** `og.LookAt { skeleton, joint, target }`
+on its own entity turns a joint (a head, an eye, a turret's barrel) so its
+`axis` (default +Z, as three.js `lookAt`) points at `target` after the
+clips and IK, its `upAxis` (+Y) rolling towards `up` (world +Y; zero
+keeps the animated roll). `maxYaw` and `maxPitch` (radians from the
+animated forward) hold a head from turning round, `clamped` reads back
+when they did; `bones: 3` spreads the turn over neck, chest and spine;
+`weight` fades it in and out. `og.JointLimit { skeleton, joint, axis,
+swing, twistMin, twistMax }` (radians from the rest pose) limits what
+`og.IkChain` and `og.LookAt` may turn a joint to: a knee is a hinge,
+`axis` +X, `swing: 0.15`, `twistMin: 0`, `twistMax: 2.6`, so a
+foot IK target never bends it backwards; a shoulder is a cone (`swing`).
+The defaults limit nothing, and the clip's own pose is never clamped.
+
+```ts
+const look = must(world.spawn({ name: "hero-look" }));
+must(world.insert(look, og.LookAt, { skeleton: body, joint: HEAD, bones: 2, maxYaw: 1.2, maxPitch: 0.5 }));
+const knee = must(world.spawn({ name: "hero-knee-l" }));
+must(world.insert(knee, og.JointLimit, { skeleton: body, joint: SHIN_L, axis: { x: 1, y: 0, z: 0 }, swing: 0.15, twistMin: 0, twistMax: 2.6 }));
+// each tick, from a system that writes og.LookAt: world.set(look, og.LookAt, { target: playerPosition })
+```
+
+**Foot locking.** `og.FootLock { skeleton, foot }` on its own entity, one
+per foot, keeps a foot the clips plant (within 5 mm of its lowest in the
+clip, the same test retargeting uses) where it touched the ground while
+root motion carries the body on and clips cross-fade, bending the leg
+(two-bone IK, `og.JointLimit`s respected); when the clips lift it the
+foot rejoins its animation over `release` (0.15 s). `planted` and
+`locked` read back each tick; `maxDistance` (0.5 m) lets go before a leg
+would stretch. It needs clips whose feet actually rest: a foot that only
+grazes its lowest for a frame is held for that frame only.
+
+**Spring bones.** `og.SpringBone { skeleton, joint, bones }` on its own
+entity, one per chain (a tail, ears, a ponytail, a single jiggling node),
+swings `joint` and its `bones` − 1 parents after their parents' motion:
+each joint's tail is a damped spring (`frequency` 3 Hz, `damping` 0.3;
+1 settles without overshoot) towards where the animation puts it, under
+`gravity` (`{ x: 0, y: -9.8, z: 0 }` droops it), held at the bone's
+length. `space` world (default) lags behind the entity's motion; model
+ignores it (a teleport does not whip the tail). Applied last, after IK
+and look-at; `lag` reads back how far the chain trails. Deterministic and
+saved with the world. `tipFrequency` and `tipDamping` (1) scale the last
+joint's frequency and damping, the joints between in proportion: 0.25 is
+a strand soft at its tip on a stiff root.
+
+Keep hair out of the head with `og.SpringCollider { skeleton, joint,
+shape, offset, tail, radius }` on its own entity, a sphere about `offset`
+or a capsule from `offset` to `tail` in the joint's frame: every tail of
+that skeleton's springs is pushed out of it to its `radius` plus the
+spring's `radius`, keeping its bone's length. A collider's `layers` (1)
+must meet the spring's `colliders` (all) to count.
+
+```ts
+const tail = must(world.spawn({ name: "hero-tail" }));
+must(world.insert(tail, og.SpringBone, { skeleton: body, joint: TAIL_TIP, bones: 3, gravity: { x: 0, y: -4, z: 0 }, tipFrequency: 0.5, radius: 0.02 }));
+const hips = must(world.spawn({ name: "hero-hips-collider" }));
+must(world.insert(hips, og.SpringCollider, { skeleton: body, joint: HIPS, shape: "capsule", offset: { x: -0.15, y: 0, z: 0 }, tail: { x: 0.15, y: 0, z: 0 }, radius: 0.12 }));
+```
+
 `templates/archetypes/third-person` (`src/anim.ts`: a 1D blend by speed,
 a hero retargeted at cook time and sentinels at run time) is the pattern,
 and for a 3D action game as a whole: a CharacterController over a level,
@@ -752,6 +887,7 @@ animation {
   library "anims/humanoid-clips.glb"   # its clips land in this model's #anim, retargeted (repeatable)
   rig "rigs/hero.ogt"                  # how this model's bones are named (`type rig`); default: detected from the node names
   footIk true                          # retargeting solves the legs so planted feet stay planted (default true)
+  mirror "turnLeft" "turnRight"        # also write a clip mirrored to the other side, under that name (default "<clip>.mirrored"; repeatable)
   compress false                       # quantised samples and keyframe reduction (default false: f32)
   tolerance 0.0001                     # the most compression may move a sampled value (default 0.0001, at most 0.1)
 }
@@ -771,6 +907,34 @@ stride), and its legs are solved so planted feet stay on the ground
 (`footIk`, on by default). The fx-showcase `retarget` station is the
 pattern.
 
+Hands retarget too: the fingers are humanoid bones (VRM 1.0's
+`leftThumbMetacarpal` … `leftLittleDistal`, read from Mixamo's
+`LeftHandIndex1`, VRoid's `J_Bip_L_Index1`, Rigify's `DEF-f_index.01.L`,
+Unreal's `index_01_l`, plain `index.01.L`; Unity's legacy `Left Thumb
+Proximal` is the metacarpal), each turning from its hand as
+the source's does, so a fist or a grip holds on an A-posed arm whatever
+the arm does. The target's twist bones (unmapped nodes named `twist`, such
+as Unreal's `lowerarm_twist_01_l`, or Rigify's `DEF-forearm.L.001`) take a
+share of their segment's roll by where they sit along it: none at the
+segment's head, the next bone's at its end, so a forearm does not
+candy-wrap. A clip made for the rig itself that leaves its twist bones
+still gets the same shares each tick (after IK); a clip that keys them
+is played as keyed. A character whose rest pose does not stand on the ground (an
+armature lifted off it, a crouched rest) says how high its ankles stand
+in its `type rig` file, `footHeight 0.08` (or `footHeight <left>
+<right>`); planted feet then land on that ground, not at the rest pose's
+foot height.
+
+**Mirroring.** `og.anim.mirror(world, { clip, skeleton })` answers a new
+clip that plays `clip` on the other side (a left-handed swing, a limp on
+the other leg, a turn the other way): left and right nodes are paired by
+the side tokens every naming scheme writes (`LeftArm`/`RightArm`,
+`thigh.L`/`thigh.R`, `J_Bip_L_`/`J_Bip_R_`, `calf_l`/`calf_r`), each
+node takes its counterpart's motion reflected across the skeleton's
+x = 0 plane, root motion's sideways travel and turns flip. It assumes a
+symmetric rest pose; mirror a retargeted clip on the skeleton it was
+retargeted for.
+
 **Compression** shrinks a model's clips in the bundle (not in memory: they
 are rebuilt at load). In the same `animation` block, `compress true`
 quantises rotations to 48 bits and the rest to 16 and drops the keyframes
@@ -800,6 +964,9 @@ clip walk "walk" {
   speed 1                   # duration multiplier, above 0 (default 1)
   loop true                 # false: holds its last frame (default true)
 }
+clip walkOther "walk" {
+  mirror true               # plays the clip on the other side of the skeleton (default false): no og.anim.mirror needed
+}
 clip run "run"
 clip waving "wave"
 blend1d move speed {        # blend1d <motion> <param>: the two children around the value blend linearly, clamped at the ends
@@ -815,12 +982,14 @@ layer base {                # the first layer is the base: root motion and og.An
   state still idle          # state <name> <motion>
   state move move {
     speed 1                 # playback rate, 0 or more (default 1)
+    sync gait               # a sync group: states of one group play in step across layers (default none)
   }
   entry still               # the state it starts in (default: the first)
   transition still move {   # transition <from | any> <to>; in file order, the first that holds fires
     when speed gt 0.2       # when <param> gt | ge | lt | le | eq | ne <number>; every `when` must hold
     exit 0.9                # and the source has played this many cycles (a `when` or an `exit` is required)
     fade 0.25               # cross-fade seconds (default 0.2)
+    interrupt any           # what may cut this fade: any (default) | none (it completes first) | source (only the state being left) | next (only the new state's own)
   }
   transition any still {    # any: from every state but the target
     when speed le 0.2
@@ -829,7 +998,11 @@ layer base {                # the first layer is the base: root motion and og.An
 layer upper {
   mode additive             # override (default): replaces the pose below | additive: adds each clip's difference from its first frame
   weight wave               # a number 0 to 1, or a parameter clamped to it (default 1)
-  state wave waving
+  mask "spine" 0.5          # mask "<node>" [weight 0 to 1, default 1]: that node and every node under it (default: no mask, all 1)
+  mask "arm.L"              # a deeper line wins for its branch; nodes under no line take 0
+  state wave waving {
+    sync gait
+  }
 }
 ```
 
@@ -837,7 +1010,16 @@ Each state advances one phase by `dt × AnimationGraph.speed × state speed
 / duration`, the duration weighted across a blend's clips, so blended
 clips stay in step. Per tick and layer the transitions are checked first,
 then the phases advance, then the poses blend; a transition during a fade
-replaces it. `og.anim.graph` refuses a parse error naming the line, a
+replaces it unless its `interrupt` says otherwise (`none` for a
+committed attack or landing, `source` to let an idle re-target a start
+that has just begun). A layer's `mask` lines confine it to branches of the
+skeleton (by node name, the nearest named ancestor's weight; an upper-body
+layer is `mask "spine"`), so a wave or an aim plays over a walk without
+freezing the legs. In a sync group the first layer (file order) whose
+current state is in it leads: every later layer's state of that group
+plays at the leader's phase, whatever its clip's length, and a transition
+between two states of one group keeps the phase (a walk-to-run blend
+keeps the feet in step). `og.anim.graph` refuses a parse error naming the line, a
 clip name `clips` lacks, a parameter not declared and a motion that
 contains itself. Write the parameters from a system every tick
 (`world.set(body, og.AnimationGraph, { p0: speed })`); `state` and
@@ -980,7 +1162,9 @@ 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
+`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
@@ -988,15 +1172,26 @@ linearly to the next, holds with `step`, or follows `curve x1 y1 x2 y2`
 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)`
+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. A DragonBones 5.5 export is imported instead of written: a rig2d
+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 and curves included; Spine's files are not read, convert
+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
@@ -1369,8 +1564,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
@@ -1381,9 +1578,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
@@ -1398,6 +1609,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
@@ -1479,16 +1835,24 @@ there. `world.set(e, og.Velocity, ...)` refuses on
 an entity without one (a body in `start`, before its first step):
 `world.insert` it there, which adds and sets it.
 
-`og.CollisionStarted` is read on the tick after the physics step. Its
-`normal` points from `a` to `b`; the bodies' `og.Velocity` already contains
-the solver's outgoing velocity, not their incoming impact velocity. Do
-not derive impact weight from those velocities: bodies may already be
-separating. There is no contact-time velocity or impulse on this event.
-For driven bodies, retain the velocity handed to physics in a component
-and read that cache before the next drive system overwrites it (as in
-`examples/rumpus-isle/src/critters.ts`). Project `velocityA - velocityB`
-onto the event normal for closing speed. This estimates linear approach
-speed, not contact-point speed from rotation or forces during the step.
+`og.CollisionStarted` is read on the tick after the physics step, when
+the bodies' `og.Velocity` already holds the solver's answer (they may
+already be parting), so never weigh a hit from og.Velocity. The event
+carries the hit itself, taken in the step that made the contact. `a` is
+the lower id, and `normal` points from `a` to `b`. `point` is the deepest
+contact point.
+`relativeVelocity` (m/s) is `a`'s velocity relative to `b` at `point` as
+that step began: each body's linear velocity plus its spin crossed with
+the point's offset from its centre of mass. A static collider counts as
+still, and a kinematic body moves at its velocity. Its part along
+`normal` is the closing speed:
+`Math.max(0, rv.x * n.x + rv.y * n.y + rv.z * n.z)`, which is positive
+while they approach. `impulse` (N·s, at least 0) is the normal impulse the
+solver gave the pair in that step, summed over substeps and contact points:
+`b` took `impulse` along `normal` and `a` the same against it, so heavier
+bodies hitting give more. Scale feedback on the closing speed (how fast)
+or the impulse (how hard, mass included), as
+`examples/rumpus-isle/src/critters.ts` does for its bumps.
 
 ```ts
 const hit = og.physics.raycast(world, { origin: eye, direction: { x: 0, y: 0, z: -1 }, maxDistance: 30, filter: { mask: 0b10, exclude: player } });
@@ -1747,6 +2111,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
 
@@ -1891,6 +2284,201 @@ spaced along the length, as three.js spaces them. Rings and circles are one-side
 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.
@@ -2154,6 +2742,10 @@ These are the checks to use before opening frames. All of them run from
   `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
 
@@ -2172,15 +2764,21 @@ model {
 }
 ```
 
-`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.
+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
@@ -2212,8 +2810,11 @@ world.insert(probe, og.ReflectionProbe, {
     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
+  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
@@ -2261,7 +2862,8 @@ default) or `hdr`:
 `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.
+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
@@ -2285,16 +2887,18 @@ world.insert(p2, og.CameraView, { viewportX: 0.5, viewportWidth: 0.5 });
 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
+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.
-- 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.
+  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.
 
@@ -2340,8 +2944,9 @@ fn fragment(f: FragmentInput, p: Params) -> SurfaceOutput                  // f:
 // 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
+- `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
@@ -2361,11 +2966,15 @@ with up to eight `param` lines. The function reads:
 
 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.
+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])`.
 
@@ -2384,11 +2993,22 @@ door. Mark the scene's unmoving models `static true` and put an
 entity "hall" {
   model "models/hall.glb"
   static true
-  Transform { position 0 0 0 quaternion 0 0 0 1 scale 1 1 1 }
+  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 }
+  Transform {
+    position 0 2 0
+    quaternion 0 0 0 1
+    scale 1 1 1
+  }
+  LightVolume {
+    size 12 4 12
+    spacing 1
+  }
 }
 ```
 
@@ -2450,3 +3070,12 @@ textures between lanterns to stay under it.
 `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.