tosijs-3d 0.8.15 → 0.10.0

package/CHANGELOG.md

@@ -1,11 +1,355 @@
 # Changelog
 
-<!--{ "order": 3 }-->
+<!--{ "parent": "reference", "order": 20 }-->
 
 All notable changes to **tosijs-3d**. This project is pre-1.0 (`0.x`), so minor
 versions may carry breaking peer-dependency changes — each is called out in a
 **⚠️ Breaking** block in its version section below, with what a consumer must do.
 
+## 0.10.0
+
+**A quality release: the deprecated names are gone, and a long list of bugs
+with them.** No new elements; what was added is tooling for measuring and
+debugging on a device, and some defaults changed (listed under **Changed
+defaults** below). Most of what breaks was announced in 0.8 and
+0.9; three things were not, and are listed below with the rest:
+`new MersenneTwister()` without a seed, `WorldStore` queries returning copies,
+and `surface.openPanel`'s `onClose`. [Migration.md](https://3d.tosijs.net/Migration/) has every
+pair and what to do.
+
+Size: barrel (min, packages external) 970.3 KB raw / 327.2 KB gz, +2.30% on
+0.9.0.
+
+### ⚠️ Breaking
+
+- **`onX` callback options are removed.** `onChange`, `onClick`, `onSelect`,
+  `onActivate`, `onClose`, `onKey`, `onAction`, `onCaretMove`, `onEnter` and
+  `onFocus` are no longer called; use `handleX`. An old name is not dropped
+  silently: `handlerOf` warns once per name that it is ignored and names the
+  replacement.
+- **`<tosi-b3d-trigger>`'s `onEnter` / `onExit` properties** are removed; use
+  `whenEnter` / `whenExit`. **`<tosi-b3d-manipulator>`'s `handleChange` /
+  `handleCommit`** are removed; use `whenChange` / `whenCommit`.
+- **`generateGalaxy`** is removed; use `voxelGalaxy({ seed, brightBudget }).view()`.
+  **`galaxy.getStarSPS()`** is removed; use `pickStar`.
+- **`new MersenneTwister()` needs a seed.** It used to seed from the clock
+  when the argument was left out, which silently broke "same seed, same
+  result". It now throws; pass `Date.now()` if that is what you want.
+- **`WorldStore.getState()`, `getEntity()` and `query()` return copies.** A
+  driver could change the simulation by writing to what a query returned.
+  Code that relied on that (deliberately or not) must call a command instead.
+  The engine's own systems read `store.liveState`.
+  A copy is made on every call, so read once per frame, not once per entity.
+- **A store passed to the conformance kit must implement
+  `chooseOption(choiceId, optionId)`.** The kit now covers the choice
+  primitive and calls it.
+- **`surface.openPanel({ onClose })` is `handleClose`.** This one was never
+  announced: it was the last `onX` option in the library and follows the same
+  rule now (ignored, with a warning).
+
+
+### Changed defaults
+
+Nothing here removes an API, but a scene can look or behave differently
+without a line of yours changing. Each has the setting that puts it back.
+
+- **Opaque meshes are drawn nearest first, the sky last** (was material
+  order). The picture is the same for ordinary opaque meshes; one with depth
+  write off can differ. `scene.setRenderingOrder(0)` restores Babylon's order,
+  and a camera-pinned sky of your own must set `infiniteDistance`.
+- **A headset session renders at a reduced scale with foveation** on the low
+  tier (`xrRenderScale`, `xrFoveation`; `1` and `0` for full).
+- **The decorator places a tier share of its budget** (0.6 on the low tier)
+  and plant rules thin with moisture (`thirst`), so the same seed gives a
+  different layout from 0.9. `budgetScale: 1` places the whole budget.
+- **Scatter rules gather more** (`clump` 0.95, was 0.85).
+- **Water receives sun and cloud shadows.**
+- **The low tier uses the lighter ground shader** (`groundDetail`).
+- **`PerlinNoise(0)` is a seed**, not "no seed".
+
+### Docs
+
+- **The doc site is reorganised.** Sections now list the elements you put in a
+  scene, with the pure models and helpers each is built from tucked beneath
+  it (the flight model under the aircraft, the biome chart under the
+  terrain). UI was one list of 39 pages and Environment one of 37; no section
+  now has more than 12 direct children. Environment is split into Sky and
+  light, Weather and clouds, Terrain and Water; Migration and the Changelog
+  moved from second and third to a Reference section at the end. Page URLs
+  are unchanged, except the section landing pages.
+- **Getting started**: the install line with its peer dependencies, a first
+  scene that needs no model file, and where to go next. The README has the
+  same.
+- **Ten modules that other pages linked to had no page**: the flight model,
+  ballistics, guidance, warhead, destroyable, resource, Perlin noise, gradient
+  filter, terrain grid and the primitives (box, sphere, ground). 17 links were
+  dead. A test now fails on a link to a page that does not exist.
+- Every section landing page says which page you want, where most were a bare
+  list of links.
+
+### Fixed
+
+- **A headset is drawn at the device tier's resolution.** It never was: the
+  tier lowered the engine's hardware scaling for a session, and that does not
+  reach the XR layer, so every tier drew both eyes at full size. The viewport
+  is now scaled per frame (`xrRenderScale`, auto: 0.67 on the low tier, 0.83
+  on medium) and fixed foveation is set (`xrFoveation`, auto: 1 on low, 0.5 on
+  medium). Measured on a Quest in Land and Sky at 90 ms a frame: half the
+  pixels saved 19 ms and full foveation 12 ms. Both are attributes of
+  `<tosi-b3d>`; set `xrRenderScale="1" xrFoveation="0"` for the old picture.
+- **Opaque meshes are drawn nearest first, and the sky last.** Babylon draws
+  them in creation order, so a sky made first was shaded across the whole view
+  and then painted over by the land. The picture is the same; a covered pixel
+  is now rejected before its shader runs. `nearFirst(scene)` is exported for a
+  render target of your own (the water's two have it).
+- **A cheaper ground shader for a weak GPU** (`<tosi-b3d groundDetail>`:
+  `auto`, `full`, `lite`). The biome shader took eight noise samples a pixel;
+  `lite` takes three and looks nearly the same from a distance. `auto` picks
+  it on the low tier, and in a headset on the medium tier. Measured on a Quest
+  in Land and Sky, the terrain was 40 ms of a 90 ms frame. The cost sweep
+  measures the other form on your device.
+- **The ground shader reads its fine noise from a texture.** It computed 3D
+  noise four times a pixel, eight hashed corners each; it now reads a shared
+  64-texel tiling block (`noiseVolume`, exported) once per sample. Mip-mapped,
+  so the detail fades in the distance where the computed noise shimmered. On
+  every tier with WebGL 2; `setBiomeComputedNoise(scene, true)` is the way
+  back, and the cost sweep measures it. The climate noise is still computed.
+- **The water's reflection and refraction are drawn once for both eyes, and
+  every Nth frame in a headset too.** Each is the scene drawn again, and a
+  headset drew both for each eye on every frame: four extra scene passes.
+  Each is now looked up through the view it was drawn from, so one drawing is
+  in the right place from either eye and on later frames (`reflectionRefresh`,
+  from the device tier: every 3rd frame on the low tier). This also fixes the
+  refraction sliding against the seabed between redraws on a flat screen.
+- **Perf Stats reports what SVG texture repaints cost** (the HUD, panels):
+  repaints a second and main-thread milliseconds a second (`svgTextureCost`).
+  It also shows the JS heap against its first reading and the total redraw
+  count, so a leak is visible from inside a headset.
+- **Debug sink** (`debugSink.url`, `sendDebug`): a page can post its readings
+  to an endpoint, for a headset that has no console. With a URL set,
+  `<tosi-b3d>` sends each cost sweep step, the Perf Stats lines while that
+  popup is open in a session, and every `logDebug` event. Off by default.
+- **`bun run xr … --counters [--again n]`**: documents, DOM nodes, listeners
+  and JS heap before and after a script, after a collection.
+- **Cost sweep** (`b3d.costSweep()`, and a button in Perf Stats): where a
+  frame goes, measured on the device, by switching one thing off at a time.
+  Runs are numbered and the last four are kept, each saying whether it
+  finished or where it stopped, so a run that hangs does not replace the one
+  before. **Shader sweep** is a separate button: it measures the ground
+  shader's other forms, which recompiles shaders.
+- **A popup's move and close icons keep their size on a tall popup in a
+  headset.** The title bar was a fifth of the popup's height, so Perf Stats
+  with a long list got icons several times too large, over its first rows.
+- **A popup is capped in height and scrolls past the cap** (480 units, or the
+  caller's `maxHeight`). Perf Stats with a sweep listed was taller than the
+  screen flat and enormous in a headset, with no way to its lower rows.
+- **The decorator places a share of its budget set by the device tier**
+  (`budgetScale`, `0` = auto: 1, and 0.6 on the low tier, which is a Quest in
+  a session). Measured on a Quest: decorations were 16 ms of a 42 ms frame.
+  Set `budgetScale: 1` to place the whole budget everywhere.
+- **A thinned scatter loses clumps, not density** (`ScatterOptions.share`,
+  `clumpCentreFor`): the weaker clumps go and the middle of the rest stays as
+  full, in the same places as the whole scatter. The decorator's share and the
+  moisture thinning both work this way. Rules also gather more by default
+  (`clump` 0.95, was 0.85), so fewer things stand alone.
+- **The cost sweep's two headset rows measure what the resolution levers are
+  saving** (`+ full resolution`, `+ no foveation`). The old rows set the
+  values the tier already uses, so they measured nothing.
+- **Wetter country grows more.** A scatter rule's moisture band only said
+  where a kind may grow, and every plant's band reached the top, so anything
+  damp enough for a tree grew the same forest as the wettest setting. Plant
+  rules now have a `thirst`: the drier it is, the more of their places are
+  left empty (`moistureCover`). In Land and Sky, trees go from about 120 at
+  moisture 0.5 to about 240 at 1; rocks are unchanged.
+- **A headset session no longer freezes the second time your hands are
+  tracked.** Babylon's hand tracking (9.16) takes the topmost ancestor of its
+  shared hand mesh as a root and parents it to the camera's parent every
+  frame. The second time hands appear (a controller put down twice), that root
+  is the camera's parent itself, which became its own parent; the next enable
+  or dispose then recursed until the stack ran out and the picture stopped.
+  Found on a Quest with Perf Stats open (#3135). The rig now refuses such a
+  parent (`refuseOwnAncestor`, exported for anyone parenting an XR camera to
+  their own node).
+- **Underwater light rays go away when you leave the water.** They were still
+  fading on the frame you surfaced, the update read the water that was no
+  longer above you and threw, and it threw again every frame after, so the
+  rays stayed for good.
+- **A popup moved in a headset stays with its panel.** Dragging an owned popup
+  used to tear it off, so moving the panel afterwards left it behind. It now
+  moves relative to its opener and stays owned; `tearOff()` is still how a
+  caller lets one go.
+- **No second, dead copy of a popup after a panel rebuild in a headset.** The
+  rebuild dropped its popups' handles and relied on each dying with the panel
+  plane. One that was torn off, or not yet mounted, stayed in the scene: a
+  Perf Stats that never updated and could not be closed. They are now closed
+  before the plane goes, and a popup whose opener has been disposed closes
+  itself.
+- **Perf Stats refreshes every two seconds in a headset** (was 0.4 s). A
+  Quest hung within minutes with it open and ran on with it closed; the cause
+  is not known, this redraws its texture less often.
+- **Water, and the ice on it, receives shadows.** The surface never did: it
+  was not marked as a shadow receiver, so nothing cast a shadow on the sea,
+  which on a white ice sheet is obvious. `<tosi-b3d-water receiveShadows="off">`
+  restores the old behaviour and saves a shadow lookup per water pixel (the
+  cost on a headset has not been measured).
+- **Cloud shadows fall on water and ice.** They never did, on any device:
+  cloud shadows are a material plugin, and Babylon's water material runs no
+  plugins. The lookup is now in the water's own shader, fed from the scene's
+  cloud shadow map (`cloudShadowMapOf(scene)`, new). `receiveShadows="off"`
+  turns it off with the sun's shadows. Every water now uses the patched
+  shader, not only `shore="on"`.
+- `PerlinNoise(0)` uses seed 0. It was treated as "no seed" and gave a
+  different field every time.
+- `world-store.ts` compiles under `noUncheckedIndexedAccess` (the steer loop
+  read `r.portals[0]` unguarded), so a project that vendors it with strict
+  settings no longer has to pin an old copy.
+- The world contract now says what it meant: a driver must supply `spec.id` to
+  `spawn` (the return value cannot cross a worker boundary), and `setIntent`
+  is legacy (`steer` is what the sim honours).
+- The conformance kit covers the choice primitive: a pick emits exactly one
+  `choiceMade`, an option that is not on the menu emits nothing, a choice is
+  reported once, and the sim resolves nothing.
+- **A bomb that goes off on terrain now hurts what is above it.** The blast's
+  line of sight started on (or just under) the surface it hit, so the terrain
+  was cover for everything and a ground burst damaged nothing. A burst near a
+  surface now looks from a metre above it; a hill or wall in between is still
+  cover. (Only a mesh named `ground` was exempt before.)
+- **Decorator: naming the default library explicitly no longer empties the
+  scatter.** Default rules were chosen by whether `url` was set, so
+  `url="…/quaternius/libraries/nature.glb"` got the other library's rules,
+  which matched no model. The choice is now made from the library in use.
+- **Decorator: `NATURE_ROLES` applies only to the default library.** Its keys
+  are generic material names (`White`, `Wood`), so a third-party model with a
+  material of the same name had it replaced by flat biome shading. Set `roles`
+  to opt a custom library in.
+- The Perf Stats "Occlusion" button says whether occlusion is running, not
+  what was asked for (`on, not running here` when the method cannot run in
+  the current mode). Land and Sky's own occlusion select, which drifted out of
+  step with it, is gone.
+- **Lightning bolts are solid, not see-through.** The channel was faded by
+  transparency between re-strokes, so up close it was a pale translucent
+  tube. It is opaque while the stroke is live, far brighter than white (so it
+  blooms), and the glow around it fades to nothing at its edge. The flicker is
+  carried by the glow, the cloud and the ground.
+- **Thunder stops when its storm does.** Thunder is queued as far ahead as
+  sound takes to arrive, so changing world left the old storm's thunder
+  playing over the new one.
+- **In VR, the pointer no longer lands on the vehicle you are sitting in.**
+  In the aircraft's cockpit the controller ray hit the canopy first, and on a
+  Quest the panel behind it could be hovered but not pressed or dragged, so
+  there was no way out of the session from inside. Anything beneath the node
+  the XR rig rides on is no longer a pointer target; your own panels are.
+  (Reproduced and checked with the emulated headset; not yet on a device.)
+- **Sea ice: the plate pattern no longer depends on the GPU's `sin`.** The
+  plates were laid out with the classic `fract(sin(x) * 43758.5)` hash, which
+  mobile GPUs evaluate differently from desktop ones; in a headset the ice
+  showed severe mismatches that a Mac never did. The hash is arithmetic only
+  now. Plate edges are also a little softer. (The layout of plates for a given
+  place changes. Not yet confirmed on a headset.)
+- **No holes in solid sea ice near its edge.** The invisible mesh a car or a
+  shell lands on kept a triangle only if all three corners were solid, so a
+  band one cell wide (16 m and more far from the viewer) was drawn solid and
+  had nothing to stand on. A triangle is kept when it is solid on average,
+  which is where the drawn ice crosses the same line.
+- **The HUD page no longer throws 30 times a second.** Its demo still called
+  `setTraces(traces, viewer, options)`, a signature that went away when the
+  HUD started projecting through the camera. The demo passes the camera, and
+  `setTraces` warns once (and draws nothing) if it is handed anything else.
+- Three demo controls were dead because they still used an old name the
+  compiler cannot see in a doc comment: the aircraft page's "chase pitch
+  follow" and "follow lag" sliders, and the particles page's Burst button.
+  (They worked, with a warning, until the fallback was removed here.)
+
+## 0.9.0
+
+**A sea that knows its shore, and a temperature that means one.** The water
+takes the depth and the distance to land from the terrain and draws surf that
+runs in, pale shallows and sea ice; solid ice is solid for everything in the
+scene. Temperature is now a real scale (0 is 0 °C, 1 is 50 °C), so the same
+dial reaches Titan and Venus.
+
+Size: barrel (min, packages external) 948.5 KB raw / 318.9 KB gz, +1.75% on
+0.8.15 (the shore model and its shader).
+
+### ⚠️ Breaking
+
+- **`biomeTemperature` is a temperature, and `-1` no longer means
+  "default".** `0` is 0 °C and each unit is 50 °C (`1` = 50 °C, `-1` =
+  -50 °C, which warns once in the console), with no limit either way, so a world
+  can be as cold as Titan or as hot as Venus. It used to be the biome
+  chart's `0…1` axis with `-1` for "default". Convert old values with
+  `(old - 0.36) / 0.8`; the default is now `0.45` and looks the same. The
+  chart is a window onto the new scale (-22.5 °C to 40 °C) and clamps beyond
+  it. `chartTemperature` / `planetTemperature` convert. Everything inside the
+  biome shader, province climate and decorator bands is still in chart
+  units. See [Migration](https://3d.tosijs.net/Migration/).
+
+### Changed
+
+- **The deprecated `onX` callback names stay for one more minor.** They were
+  announced as "removed in 0.9"; they are removed in **0.10** instead, and
+  still work and warn once in 0.9.x. The same goes for the other names marked
+  for removal in 0.9 (`whenEnter`/`whenExit`'s old spellings on the trigger,
+  the manipulator's, `generateGalaxy`). Nothing to do yet beyond renaming at
+  your own pace.
+
+### Added
+
+- **A shoreline, and sea ice.** `<tosi-b3d-water shore="on">` gives the water
+  the depth of the ground under each vertex (from the scene's terrain) and
+  draws from it: surf (wave fronts running in to the shore one after
+  another, and a wet edge lapping at the waterline), paler water over the
+  shallows, and ice. The surf is drawn from each vertex's DISTANCE to the
+  waterline, not its depth, so it is the same width on a steep shore as on
+  a flat one. The distance is a real one, carried across the grid from
+  the waterline, so the fronts are evenly spaced whatever the bed does.
+  `shoreFine` doubles the mesh near the viewer: a vertex every 2 m out to
+  64 m (about 16,600 in all) where there is otherwise one every 4 m. The ice follows the cold and the shore: a solid sheet
+  along the beach, breaking into plates further out, open water beyond, and
+  all of it moving out to sea as the climate at sea level (season included)
+  gets colder. It is there from below as well. The sea starts to freeze at
+  -2 °C at the beach; open water stays clear to about -8 °C and is one
+  unbroken surface by -22.5 °C. `iceCover(temperature, depth)` is the rule; see [water-shore](/water-shore/). With `shore="on"` a vertex
+  colour on the water mesh is shore data, not a tint. The shader patch is
+  made once for the page, so this holds for EVERY `WaterMaterial` on a page
+  that has one `shore="on"` water: a vertex-coloured water mesh of your own
+  loses its tint there.
+- **Solid ice is solid.** Ice is water until it has knitted solid
+  (`iceBears`); where it has, the water carries an invisible collision mesh
+  (collision group `ice`), so anything that collides or picks meets it: a
+  car, a shell, a ground probe. Plates and a sheet still showing its cracks
+  are water. Wave displacement fades out under ice, so the sheet lies flat
+  where it collides. A biped swimming at the surface climbs onto solid ice;
+  one that dived first goes under it, with the ice as a ceiling.
+  `water.iceBearsAt(x, z)` asks for any point.
+
+### Fixed
+
+- **Water animates on every browser.** Babylon's `WaterMaterial` advances
+  its clock only on a frame whose duration differs from the last, so where
+  frame times are steady (a browser that rounds its timer, a display holding
+  its rate) the ripples crawled. `<tosi-b3d-water>` now writes the
+  material's time itself, once a frame, from the scene's clock. It also
+  stops when the scene is paused.
+- **Fog takes the sky's tint.** A `syncSkybox` fog fades distant ground to
+  the skybox's `horizonColor`, which ignored `horizonTint`: under a tinted
+  sky the far hills stood out as a pale blue-white band along the horizon.
+  It now keeps its brightness and takes the tint's hue, by `tintStrength`.
+- **Land and Sky: no air, no cloud.** The demo's cloud cover and orographic
+  dials are thinned by the air setting (none below a twentieth of Earth's),
+  so Mars has a clear sky. The cloud deck itself is unchanged.
+- **Negative `cirrus` had a quarter of the cloud of positive `cirrus`.** The
+  two streak directions were built differently; across-the-wind is now the
+  same field turned a quarter, so the sign changes only which way the streaks
+  run.
+- **Clouds needed exactly full air.** With `atmosphere` under about 0.8 the
+  sky dome becomes a blended mesh, and it was drawn after the cloud deck and
+  over it. It is now drawn first.
+- **A little less air cleared the haze almost completely, and a slow drag
+  back to full air never quite arrived.** The vacuum fog layer now mixes fog
+  by strength (`FogLayer.reciprocal`), and the sky's air value lands exactly
+  on 0 and 1.
+
 ## 0.8.15
 
 **Rocks and trees that belong to the land.** Procedural rocks, Quaternius
@@ -1273,7 +1617,7 @@ demo is now **Land and Sky**.
 ### ⚠️ Breaking
 
 Nothing breaks at compile time. Two behaviours change, and
-[Migration.md](./Migration.md) has the before/after for each.
+[Migration.md](https://3d.tosijs.net/Migration/) has the before/after for each.
 
 - **Aircraft guns are direct-hit, not area-effect.** `gun-mode="blast"`
   restores the old behaviour; `gunBlastRadius`/`gunFullRadius` are attributes

package/Migration.md

@@ -1,14 +1,145 @@
 # Migration
 
-<!--{ "order": 2 }-->
+<!--{ "parent": "reference", "order": 10 }-->
 
 What to change when upgrading. Only breaking changes are listed — everything
-else is additive. The full detail for each is in [CHANGELOG.md](./CHANGELOG.md).
+else is additive. The full detail for each is in [CHANGELOG.md](https://3d.tosijs.net/CHANGELOG/).
 
 This file ships **inside the package**, because a migration table you can only
 read on GitHub does not exist for someone who has already installed the thing
 and is staring at an error.
 
+## 0.9.0 → 0.10.0
+
+### 1. The deprecated callback names are gone: `onX` → `handleX`
+
+**What changed.** The `onX` callback options were deprecated in 0.8.0 and kept
+working, with a warning, through 0.9.x. They are removed. An `onX` option is
+no longer called.
+
+**Who is affected.** Anyone who saw the console warning
+"`onChange` is deprecated — use `handleChange`" and has not renamed yet.
+
+**How you will notice.** TypeScript reports the old name as an unknown
+property. At runtime the callback does not fire, and the console says so once
+per name: "`onChange` was removed in 0.10 and is IGNORED — use `handleChange`".
+Demo code in doc comments and plain JavaScript is not type-checked, so search
+for the names rather than relying on the compiler.
+
+**What to do.** Rename. Every pair:
+
+| where | removed | use |
+| --- | --- | --- |
+| `toggle3d` `slider3d` `select3d` `color3d` `vector3d` `euler3d` `angle3d` `arc3d` `picker3d` `curve3d` `footprint3d` `themeEditor` `terrainEditor3d` | `onChange` | `handleChange` |
+| `button3d`, menu actions, `addDebugSource` actions | `onClick` | `handleClick` |
+| `list3d`, `surface` `MenuItem`, `table` | `onSelect` | `handleSelect` |
+| `table`, `box` `button` / `BoxChild` | `onActivate` | `handleActivate` |
+| `showPopup` / `openPopup` / `openMenu3d` / `surface.openPanel` | `onClose` | `handleClose` |
+| `inputField` | `onChange` / `onEnter` / `onFocus` | `handleChange` / `handleEnter` / `handleFocus` |
+| `keyboard` | `onKey` / `onAction` / `onCaretMove` | `handleKey` / `handleAction` / `handleCaretMove` |
+| `curve3d` / `footprint3d` result (`field.onChange = …`) | `onChange` | `handleChange` |
+
+Components take `when*`:
+
+| component | removed | use |
+| --- | --- | --- |
+| `<tosi-b3d-trigger>` | `onEnter` / `onExit` properties | `whenEnter` / `whenExit` |
+| `<tosi-b3d-manipulator>` | `handleChange` / `handleCommit` | `whenChange` / `whenCommit` |
+
+`b3dTrigger({ onEnter })` through the element creator is unchanged: it was
+never the property, it is a listener for the `'enter'` event and receives an
+`Event`.
+
+`handlerOf(config, 'handleX', 'onX')` keeps its signature. It now returns only
+`handleX`, and warns once if it finds a function under the old name.
+
+### 2. `generateGalaxy` and `galaxy.getStarSPS()` are removed
+
+`generateGalaxy(seed, count, options)` was an adapter over the voxel galaxy.
+Call that directly:
+
+```javascript
+// before
+const galaxy = generateGalaxy(1234, 10000, options)
+// after
+const galaxy = voxelGalaxy({
+  seed: 1234,
+  brightBudget: 10000,
+  dimBudget: 0,
+  galaxyOptions: options,
+}).view({ generatePlanets: options.generatePlanets === true })
+```
+
+The result is identical. `getStarSPS()` on `<tosi-b3d-galaxy>` returned `null`
+since the stars moved to a vertex shader; use `galaxy.pickStar(x, y)`.
+
+### 3. `new MersenneTwister()` needs a seed
+
+It used to seed from `Date.now()` when you left the argument out. It now
+throws. Pass a seed, or `new MersenneTwister(Date.now())` if you want a
+different sequence each run. (`PRNG` always required one.)
+
+### 4. `WorldStore` queries return copies
+
+`getState()`, `getEntity()` and `query()` used to return the store's live
+objects, so writing to a result changed the simulation. They return copies
+now. If you were moving something by writing to a query result, call the
+command for it. Engine-side code that needs the live state every frame reads
+`store.liveState` and must not write to it. A store passed to the conformance
+kit must also implement `chooseOption(choiceId, optionId)`.
+
+### 5. Some defaults changed: a scene can look different
+
+Nothing to rename, but four things change what you see without a line of
+yours changing. The changelog's **Changed defaults** block has all of them.
+
+- **Decoration layouts differ again.** Plants thin out in drier country, things
+  gather into clumps more strongly, and a low-tier device (a Quest in a
+  session) places 60% of the budget as fewer clumps. `budgetScale: 1` places
+  the whole budget; `clump: 0.85` on the decorator is the old gathering.
+- **Opaque meshes are drawn nearest first.** Same picture for ordinary meshes.
+  `scene.setRenderingOrder(0)` puts Babylon's order back; a camera-pinned sky
+  of your own needs `infiniteDistance`.
+- **A headset on the low tier renders at reduced scale with foveation.**
+  `xrRenderScale: 1` and `xrFoveation: 0` are full resolution.
+- **Water receives sun and cloud shadows.**
+
+## 0.8.15 → 0.9.0
+
+### 1. `biomeTemperature` is in degrees now: 0 is 0 °C, 1 is 50 °C
+
+**What changed.** `<tosi-b3d-terrain biomeTemperature>` used to be the biome
+chart's own axis: `0…1`, cold to warm, with `-1` meaning "use the default".
+It is now a temperature: `0` is 0 °C and each unit is 50 °C, so `-1` is
+-50 °C, and the value is not limited to any range. The default is `0.45`
+(22.5 °C), which is the same climate as before.
+
+**Who is affected.** Anyone who sets `biomeTemperature`. An old value is read
+on the new scale and comes out much warmer: `0.3` used to be about -4 °C and
+is now 15 °C. `-1` used to mean the default and is now -50 °C.
+
+**What to do.** Convert each value: `new = (old - 0.36) / 0.8`. Replace `-1`
+with `0.45`, or delete the attribute.
+
+| Old | New | Climate |
+|-----|-----|---------|
+| `-1` (auto) | `0.45` | 22.5 °C |
+| `1` | `0.8` | 40 °C |
+| `0.72` | `0.45` | 22.5 °C |
+| `0.36` | `0` | 0 °C |
+| `0` | `-0.45` | -22.5 °C |
+
+`chartTemperature` and `planetTemperature` (from `biome-chart`) do the
+conversion in code. Only this attribute moved. `BiomePlugin.params`, the
+province climate curves and the decorator's rule bands are still in chart
+units.
+
+### 2. Nothing else is removed, including what was promised
+
+The deprecated `onX` callback names (and the other names announced as
+"removed in 0.9") still work in 0.9.x and warn once. They are removed in
+0.10. Rename when convenient.
+
 ## 0.8.14 → 0.8.15
 
 **Nothing breaks at compile time. Three defaults change what you see.**
@@ -150,7 +281,8 @@ Use **`isOff()`** from `tosijs-3d`, which accepts `'off'`, `false` and
 ### 2. Callback options: `onX` → `handleX`
 
 Every callback option in the library now takes `handleX`. The old `onX` spelling
-still works, warns **once per name**, and is **removed in 0.9**.
+kept working through 0.9.x, warning **once per name**, and was **removed in
+0.10** (see the top of this file).
 
 | widget                                   | old                                  | new                                              |
 | ---------------------------------------- | ------------------------------------ | ------------------------------------------------ |

package/README.md

@@ -24,8 +24,54 @@ b3d(
 )
 ```
 
-See the [b3d](?tosi-b3d.ts) page for that running, and every page here carries a
-live demo you can edit in place.
+The [doc site](https://3d.tosijs.net) has about a hundred live demos you can
+edit in place; the [b3d page](https://3d.tosijs.net/tosi-b3d/) is that scene
+running.
+
+## Getting started
+
+```bash
+npm install tosijs-3d tosijs @babylonjs/core @babylonjs/gui @babylonjs/loaders @babylonjs/materials
+```
+
+Babylon (`^9`) and `tosijs` (`^1.9.2`) are peer dependencies: you install
+them, so there is exactly one copy of the engine in your app. `jolt-physics`
+is an optional peer, needed only if you use `b3dPhysics`.
+
+A first scene, with no model file to find:
+
+```javascript
+import { b3d, b3dSun, b3dSkybox, b3dGround, b3dBox, b3dSphere } from 'tosijs-3d'
+
+document.body.append(
+  b3d(
+    b3dSun({ shadowCascading: true }),
+    b3dSkybox({ timeOfDay: 10 }),
+    b3dGround({ size: 24, texture: 'checker' }),
+    b3dBox({ x: -1.5, y: 0.5, color: '#c8553d' }),
+    b3dSphere({ x: 1.5, y: 1, diameter: 2, color: '#ffd166' })
+  )
+)
+```
+
+Give `tosi-b3d` a size in CSS (`tosi-b3d { width: 100vw; height: 100vh }`) and
+you have a lit scene with shadows and an orbit camera. Then:
+
+- **Your own model:** [b3d-loader](https://3d.tosijs.net/b3d-loader/) takes a
+  GLB; name suffixes on its meshes (`_collide`, `_mirror`, `_nocast`) set how
+  they behave.
+- **Something to drive:** a [character](https://3d.tosijs.net/b3d-biped/), a
+  [car](https://3d.tosijs.net/b3d-car/) or an
+  [aircraft](https://3d.tosijs.net/b3d-aircraft/), inside an
+  [input focus](https://3d.tosijs.net/b3d-input-focus/) so keyboard, gamepad,
+  touch and VR controllers all work.
+- **A world:** [terrain](https://3d.tosijs.net/b3d-terrain/),
+  [water](https://3d.tosijs.net/b3d-water/) and a
+  [sky](https://3d.tosijs.net/b3d-skybox/); [Land and
+  Sky](https://3d.tosijs.net/land-and-sky/) is all of it at once.
+- **Controls that work in a headset:** the `scenePanel` hook on
+  [b3d](https://3d.tosijs.net/tosi-b3d/) and the
+  [widget set](https://3d.tosijs.net/widgets3d/).
 
 ## Four things you may not have seen in a 3D library
 
@@ -60,33 +106,13 @@ the package**, so an agent already in a consumer project reads
 It exists because the recurring adopter failure is not a missing feature, it is
 a feature that ships, is documented, and cannot be found: three issues in one
 week turned out to be capability that was already there. One `grep water` finds
-`submersible`; reading 147 doc pages does not.
-
-**Upgrading?** See [Migration.md](./Migration.md) for the breaking changes and
-what to do about them, and [CHANGELOG.md](./CHANGELOG.md) for the full detail.
-Both ship inside the package, so they work from `node_modules` too.
-
-```javascript
-import {
-  b3d,
-  b3dSun,
-  b3dSkybox,
-  b3dLoader,
-  b3dWater,
-  b3dReflections,
-} from 'tosijs-3d'
+`submersible`; reading two hundred doc pages does not.
 
-document.body.append(
-  b3d(
-    { glowLayerIntensity: 1 },
-    b3dSun({ shadowCascading: true }),
-    b3dSkybox({ timeOfDay: 6, realtimeScale: 100 }),
-    b3dLoader({ url: './scene.glb' }),
-    b3dWater({ y: -0.2 }),
-    b3dReflections()
-  )
-)
-```
+**Upgrading?** See [Migration](https://3d.tosijs.net/Migration/) for the
+breaking changes and what to do about them, and the
+[Changelog](https://3d.tosijs.net/CHANGELOG/) for the full detail. Both ship
+inside the package as `Migration.md` and `CHANGELOG.md`, so they work from
+`node_modules` too.
 
 ## Highlights
 
@@ -137,8 +163,9 @@ performance-sensitive settings resolve to `auto` rather than to a number that is
 always wrong for something. A Quest and a workstation get different worlds.
 
 **Pure models, actually tested** — the flight model, ballistics, guidance, biome
-classification, layout and text editing are engine-free and unit-tested (1000+
-assertions run in ~2s with no GPU). If it can be a function of its inputs, it is.
+classification, layout and text editing are engine-free and unit-tested (about
+3,000 tests, run in seconds with no GPU). If it can be a function of its inputs,
+it is.
 
 ## Development
 
@@ -146,9 +173,11 @@ Requires [Bun](https://bun.sh).
 
 ```bash
 bun install
-bun start
+bun tls     # once: local HTTPS certificates (needs mkcert)
+bun start   # the doc site and dev server, rebuilding on change
+bun test
 ```
 
-Dev server runs on https://localhost:8030 with auto-rebuild on file changes.
+The dev server runs on https://localhost:8030.
 
 <!--{ "pin": "top" }-->

package/dist/aim.js

@@ -188,7 +188,7 @@ legible bad-shooter behaviour there is: the aim visibly trails the target, so a
 player can *see* they are being missed rather than merely surviving. Pair it
 with `aimWobble` for a shooter who cannot hold still.
 */
-/*{ "parent": "Vehicles", "order": 167 }*/
+/*{ "parent": "b3d-biped", "order": 40 }*/
 /**
  * Human-ish defaults, and each one is a posture rather than a round number.
  *