@origingame/engine 0.3.0 → 0.4.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
@@ -280,9 +288,13 @@ registered schema and refuses a model path that does not exist.
   A `.vox` with frames (MagicaVoxel's animation) cooks to clips that swap
   the frames' models: play them as skinned clips (§9). `voxFps 8` sets the
   rate (default 10), `voxClip walk 0 3` names frames 0 to 3 (repeatable;
-  without it one clip `frames` holds every frame). Each frame is centred on
+  without it one clip `frames` holds the playback range set in the editor,
+  else every frame; a node marked to loop repeats its keys over the file's
+  frames). Each frame is centred on
   its own pivot, as in the editor: give the frames one height (or pad them)
   for a character whose feet stay on the ground.
+- An `.ogt` of `type model` is a model written as text: og-geom parts by
+  their `og.render` names, placed, with materials and pivots (§18).
 - Reusable production assets come through the platform's asset catalog into
   `assets/`; record each file's licence next to it.
 
@@ -380,7 +392,13 @@ else ignores it. The stamp is world state, so a replay reproduces it.
   `flipX`, `flash`, `shadow`, nine-slice `sliceX`/`sliceY`) is drawn every
   frame at its transform, its scale multiplying the size (so squash and
   stretch is a tween of `og.Transform.scale`). `og.render.sprite` stays for
-  one-tick, immediate drawing (HUDs, debug).
+  one-tick, immediate drawing (HUDs, debug). Sprites and og.ui's frames
+  are filtered anisotropically where the device can
+  (`og.render.capabilities(world).spriteAnisotropy`: 16, or 1 on a WebGL2
+  without `EXT_texture_filter_anisotropic` and on a software rasterizer), so a sprite or a nine-slice
+  squeezed along one axis keeps the other axis's detail (a button's
+  outline stays sharp); at 1 it blurs, and og.ui bounds a frame's middle
+  at twice its art for that reason.
 - **Pixel sprites in a 3D set** stand on the ground with `og.Sprite.dropShadow`
   (or `SpriteDesc.dropShadow`): 0.5 casts the sprite's shape, darkened and
   flattened onto the ground plane (y 0) along the sun, the first
@@ -980,7 +998,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 +1008,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 +1400,10 @@ render sprite 12
   `underwaterDensity` and the surface from below shows the sky only
   straight up (on by default; set the density to 0 to see through).
 
-**Terrain** (`reference/terrain.md`) is a height field cooked from a
-`type terrain` .ogt beside a 16-bit grey PNG (or an EXR in metres):
+**Terrain** (`reference/terrain.md`, 3D projects only: a `2d` project's
+publish build has none, §2) is a height field cooked from a
+`type terrain` .ogt beside a 16-bit grey PNG (or an EXR in metres), or
+generated by the cook (below):
 
 ```text
 type terrain
@@ -1381,9 +1414,23 @@ height -20 120             # metres
 size 2048 2048             # metres along x and z, centred on the entity
 control "island-control.png"  # optional RGBA: layer 0 in R, 1 in G, 2 in B, 3 in A
 heightBlend 0.15           # sharpen the blends by each albedo's alpha (its height)
-layer { albedo "textures/grass.png" normal "textures/grass-n.png" tile 6 slope 0 30 }
-layer { albedo "textures/rock.png" tile 12 triplanar true slope 28 90 }
-layer { albedo "textures/snow.png" altitude 90 1000 altitudeFade 10 }
+layer {                    # a block's '}' stands alone on its line
+  albedo "textures/grass.png"
+  normal "textures/grass-n.png"
+  tile 6
+  slope 0 30
+}
+layer {
+  albedo "textures/rock.png"
+  tile 12
+  triplanar true
+  slope 28 90
+}
+layer {
+  albedo "textures/snow.png"
+  altitude 90 1000
+  altitudeFade 10
+}
 ```
 
 A layer shows where its control channel (1 without a map) times its slope
@@ -1398,6 +1445,151 @@ world.insert(ground, og.Terrain, { data: info.data });
 world.insert(ground, og.Collider, { shape: SHAPE_HEIGHTFIELD, mesh: info.geometry });
 ```
 
+**A generated terrain.** Instead of `heightmap`, a `generate` block makes
+the field in the cook (never both: the cook refuses the pair and names
+the lines). `height` and `size` mean what they mean for a heightmap: the
+field is stretched so its lowest sample is `height`'s low and its highest
+its high, and no sample leaves that range. Every line, with its default
+(leave out what you do not need; erosion, thermal, terraces, rivers and
+the sea are off until given):
+
+```text
+type terrain
+version 1
+---
+height -40 160             # metres
+size 1024 1024             # metres along x and z
+generate {
+  samples 257 257          # columns and rows (2 to 4097)
+  seed 1                   # another seed, another terrain of the same kind
+  noise {
+    octaves 6              # 1 to 12: more is finer detail
+    frequency 3            # features across the longer side
+    lacunarity 2           # each octave's frequency over the last's (1 to 8)
+    gain 0.5               # each octave's amplitude over the last's (0 to 1): higher is rougher
+    warp 0                 # domain warp in features: 0.3 to 1 bends ridges and coasts
+  }
+  mask island 0.4          # land fades to `height`'s low over this share of the half size
+                           # or `mask ridge 1`: sharp ridged mountains (0 to 1); default no mask
+  erosion {                # hydraulic erosion: seeded drops carve gullies and fill valleys
+    drops 40000            # ~0.5 to 1 per sample; more is deeper erosion and a slower cook
+    lifetime 30
+    radius 3               # samples each drop erodes around it
+    inertia 0.05
+    capacity 4
+    deposition 0.3
+    erosion 0.3
+    evaporation 0.01
+    gravity 4
+  }
+  thermal {                # slopes steeper than talus slump into scree
+    talus 35               # degrees
+    iterations 20
+    rate 0.5
+  }
+  terraces {
+    step 10                # metres between steps
+    blend 0.4              # 0 hard steps, 1 smooth ramps
+  }
+  sea 0                    # metres above the entity: og.terrain.load's seaLevel
+  shore 2                  # metres either side of the sea flattened into beaches (needs sea)
+  rivers {                 # carved where the flow gathers, down to the sea or the edge
+    threshold 400          # samples draining through before it is a river: lower, more rivers
+    depth 2                # metres
+    width 6                # metres
+  }
+  moisture {               # what biomes read, 0 to 1
+    flow 1                 # weight of the gathered flow (wet in valleys and by rivers)
+    scale 64               # samples draining through for half of it
+    noise 0.5              # weight of a noise
+    frequency 6
+  }
+  biome {                  # any number; each writes its layer's control channel
+    layer 0                # required: the layer (0 to 3, one the terrain has)
+    weight 1
+    altitude -1000000 1000000   # metres above the entity
+    altitudeFade 2
+    slope 0 90             # degrees
+    slopeFade 4
+    moisture 0 1
+    moistureFade 0.1
+  }
+}
+layer {
+  albedo "textures/sand.png"
+  tile 4
+}
+layer {
+  albedo "textures/grass.png"
+  tile 6
+}
+layer {
+  albedo "textures/rock.png"
+  tile 12
+  triplanar true
+}
+```
+
+An island with beaches, rivers and rock on its cliffs, for that file's
+three layers (a block's `{` ends its line):
+
+```text
+generate {
+  seed 7
+  noise {
+    warp 0.5
+  }
+  mask island 0.45
+  erosion {
+    drops 40000
+  }
+  sea 6
+  shore 3
+  rivers {
+    threshold 300
+    depth 2.5
+    width 8
+  }
+  biome {
+    layer 0
+    altitude -1000 9
+  }
+  biome {
+    layer 1
+    altitude 9 1000
+    slope 0 32
+  }
+  biome {
+    layer 2
+    slope 32 90
+  }
+}
+```
+
+With `biome` rules the generator writes the control map (a terrain with
+biomes names no `control`); a channel is the most any of its layer's
+biomes gives a sample, its `weight` times its three bands. Without biomes
+there is no control map and the layers' own `slope` and `altitude`
+place them, as for a heightmap. The same file makes the same terrain on
+every machine (the generator uses only exact arithmetic and its own
+random numbers). It is a credible terrain of a kind, never a terrain from
+a picture: move the seed, the mask and the erosion until it reads right.
+`og cook --report` gives its height histogram, the share of land above
+the sea and the rivers' length, and writes its height and control maps
+as PNGs to `og-out/terrain-maps/` to look at.
+
+Its sea is the water's level; the water is the terrain's size:
+
+```ts
+if (info.seaLevel !== null) {
+  const sea = must(world.spawn({ name: "sea", position: { x: 0, y: info.seaLevel, z: 0 } }));
+  world.insert(sea, og.Water, { size: info.size, segments: 128 });
+}
+```
+
+(on the terrain's entity's x and z, under its parent if it has one; an
+`og.WaterSurface` on the same entity makes the waves move and bodies float).
+
 It is drawn around the camera at finer detail nearby (casting and
 receiving shadows, under the fog), placed by its entity's world transform
 (turn or scale the entity and the terrain turns and scales with it), and
@@ -1747,6 +1939,35 @@ og.render.look(world)?.name;                                              // the
   stays sharper under camera motion and `taaSharpen` (0–1) restores
   detail TAA softens. `RenderCapabilities.antialias` says what the device
   resolved it to.
+- **Graphics quality** is RenderSettings' quality fields, read every
+  frame: `rectShadows`, `shadowedLights`, `shadowMapScale`,
+  `volumetricFog`, `softParticles`, `screenSpaceReflections`,
+  `ambientOcclusion`, `msaaSamples` (4, or 1 for FXAA where the
+  antialiasing multisamples). `og.render.applyQuality(world, preset)`
+  writes a preset's row of them and records it in
+  `RenderSettings.quality` (`none` before any):
+
+  | Field | low | medium | high |
+  |---|---|---|---|
+  | rectShadows | false | true | true |
+  | shadowedLights | 2 | 8 | 8 |
+  | shadowMapScale | 0.5 | 1 | 2 |
+  | volumetricFog, softParticles, screenSpaceReflections, ambientOcclusion | false | true | true |
+  | msaaSamples | 1 | 4 | 4 |
+
+  Medium is the defaults, the frame drawn before any preset. The renderer
+  reads the fields and nothing else, so `og run --commands
+  "0.5:get:og.RenderSettings"` shows what is drawn, and a field set after
+  the preset wins. The switches only take away: the scene's PostEffects
+  and lights keep their settings. The settings screen applies the
+  player's pick when given the world (`og.ui.settingsScreen(id, { world,
+  settings, ... })`); apply a saved preset yourself at start:
+
+  ```ts
+  start(world) { og.render.applyQuality(world, save.settings.quality ?? "medium"); }
+  ```
+
+  Inside a system, declare `og.RenderSettings` among its writes.
 
 ## 17. Saving progress
 
@@ -1891,6 +2112,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 +2570,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 +2592,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 +2638,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 +2690,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 +2715,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 +2772,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 +2794,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])`.
 
@@ -2450,3 +2887,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.