incanto 0.74.0 → 0.76.0

package/skills/incanto-editor.md

@@ -134,12 +134,23 @@ Opens a local page (default `http://127.0.0.1:5179/`) with three panes:
   node in the scene; the handler is a dropdown of real methods when the target
   has no script, and free text when it does (those handlers live in your
   TypeScript, which the editor never loads). An end that no longer resolves is
-  marked red with the reason. For what a row cannot express — `filter` and `once`
-  — the scene header still has `connections` as raw JSON. (It used to say "bound
-  args" as well: a connection has never had them. Its keys are exactly
-  `[signal, from, to, handler, once, filter]`, and since they became a closed
-  set an invented one is a load error rather than a key that quietly does
-  nothing.)
+  marked red with the reason. For what a row cannot express — `filter`, `once`
+  and `args` — the scene header still has `connections` as raw JSON. A
+  connection's keys are exactly `[signal, from, to, handler, once, filter,
+  args]`, a closed set, so an invented one is a load error rather than a key
+  that quietly does nothing. **`args` survives editing but is not shown**: a row
+  whose wire carries bound arguments reads as `phase2 → HUD/Banner.show` with no
+  hint of the words it says.
+
+  **Re-pointing a target keeps your handler.** A handler the new target does not
+  have is replaced (the row would otherwise stay green here and hard-fail at
+  load), and the row remembers what it started with — so changing your mind and
+  putting the target back puts the handler back. Before that, a round trip left
+  `phase2 → HUD/Banner.show` as `HUD/Banner.childNames`: the replacement took
+  the target's first offer, and the offers included the tree plumbing every node
+  inherits. They do not any more — the node base class is read the way the
+  behavior base class always was, so `queueFree` stays and `childNames`,
+  `wiringPath` and the rest are gone.
   **Validation now runs WITH connections**: the editor used to strip them before
   loading, so it reported green for a scene the game hard-fails to open.
 - **Viewport with DIRECT MANIPULATION** — a mode toolbar (top left) + the
@@ -378,8 +389,10 @@ transport instead. With neither, the buttons are simply absent.
 
 From that game, the ☰ debug menu's **✎ edit this scene** switches straight back
 to the editor — same window, no reload, and the edit camera picks up the pose
-the player was looking from. **✕ exit** in the editor returns to the game
-without playing. The pair is one loop you can ride all session:
+the player was looking from. **✕ exit** returns to the game WITH the scene as
+the editor has it — you were editing it, and half the time you saved it, so
+handing back the json the page booted with would show you your own edit
+disappearing on the way out. The pair is one loop you can ride all session:
 
 ```
 game  --(☰ debug ▸ ✎ edit this scene)-->  editor
@@ -392,6 +405,14 @@ editing wherever the simulation happened to be. Games hosting the editor
 themselves (`createGame3D({ editor: … })`) get a **save** button only when they
 pass `editor.save` — otherwise edits live as long as the session does.
 
+**Saving keeps you in the editor.** It used to throw you out of it: the save
+writes the scene through `incantoScenes()`'s `PUT /api/scene`, vite saw its own
+watched file change, and a JSON module imported by `main.ts` cannot be
+hot-swapped — so vite full-page-RELOADED, the page came back as the game, and
+the selection, the camera and the panel you were working in were gone. The
+plugin now recognises a write it just made and lets the page be. A hand edit in
+a text editor is news the page does not have, and still reloads.
+
 **The handle you booted with does not survive the round trip.** ▶ builds a NEW
 game, so after one ✎→▶ the `game` your app is holding refers to something that
 no longer exists. It is inert rather than destructive — a stale `dispose()` and

package/skills/incanto-environment.md

@@ -509,6 +509,7 @@ Every instance in a grove also gets a deterministic per-instance color jitter (
 | `leafFadeEnd` | `0` | leaf LOD — cards fully collapsed (zero overdraw) by here; tune ≈ the scene `fog.far` so the thinning hides in fog (load-time check: `> leafFadeStart`) |
 | `leafShadows` | `true` | `false` keeps trunk/branch shadows but drops the expensive alpha-cutout LEAF shadow pass — big FPS in dense forests |
 | `drape` | `null` | AUTO by default: each scattered instance roots at the ground height under it (instead of the node's single Y) whenever the scene has a Terrain3D — a `count > 1` grove on rolling/carved terrain never floats or buries. `true` forces, `false` opts out |
+| `avoidWater` | `true` | keep trunks out of standing and running water — a valley a rill runs through has a grove on its BANKS. A wet draw is re-rolled (up to eight times) rather than dropped, so a grove keeps the `count` you asked for even over a lake. `false` is the mangrove |
 | `terrain` | `""` | drape target node path; empty = auto-find the first Terrain3D (a wrong path fails at load) |
 
 > **Tree LOD / forest FPS.** Leaf overdraw + the leaf shadow pass dominate a
@@ -517,6 +518,14 @@ Every instance in a grove also gets a deterministic per-instance color jitter (
 > leaf cards (branch silhouette stays), and `leafShadows: false` to drop the leaf
 > shadow pass. Both default off → existing scenes are unchanged.
 
+**`grove.trunks()`** answers where every trunk of this grove stands, in world
+coordinates — recomputed from the seed, so it works headless where there is no
+mesh at all. It is how a harness asks whether the drape happened:
+`Math.abs(y - terrain.heightAt(x, z)) < 0.01` for every trunk. (Until it
+existed, nothing could: `Tree3D` read the tri-state `drape` as a boolean, so
+AUTO — the documented default, and what this table has said since 0.14 — meant
+FLAT, and no check in the repo could see it.)
+
 > **Floating trees?** Since 0.14 groves drape automatically whenever the scene
 > has a Terrain3D — each instance roots on the ground under it. The drape is a
 > pure heightAt lookup — no rng draw, so the seed/grove layout is
@@ -524,6 +533,19 @@ Every instance in a grove also gets a deterministic per-instance color jitter (
 > single-Y placement.
 
 ## Terrain3D
+
+**Putting things on it.** `snapToGround: true` (a `Node3D` prop) sets a node's Y
+from the terrain under it at load — and on a node with a COLLIDER it places the
+collider's FOOT on the ground, not the origin. That is what every hand-written
+lift in this repo already computed (`beacon-isle-3d`'s walker says `0.95` for a
+capsule of radius 0.4 and height 1.1). It matters more than tidiness: a body
+whose origin sits on the surface starts half INSIDE the heightfield, and a
+penetrating body is ejected the nearest way out — which is down, through the
+world, forever. A number still means "place the origin and lift by this".
+
+And a terrain is not SOLID on its own: put it under a `StaticBody3D` with
+`collider: { shape: "heightfield" }`, which pulls the terrain's own grid.
+
 Procedural heightfield terrain with biome texture splatting (in `incanto/3d`,
 registered by `registerNodes3D`), ported from the agent8 starter terrain:
 seeded simplex octaves displace a plane grid ONCE on the CPU, and a patched
@@ -637,9 +659,25 @@ is radians of `atan(|∇h|)`. Default textures stream from the live agent8 CDN
 | `layers` | `[]` | custom splat layers (theme `custom` only) |
 | `textureBase` | agent8 CDN | base URL: `<base>/<name>.png` + `<base>/<name>_normal.png` |
 | `basins` | `[]` | lake/pond bowls — `[{ x, z, radius, depth }]` (centered meters) carved into the surface (smooth, 0-slope rim); **negative `depth` RAISES a smooth dome mound instead** (a hill, an islet); `heightAt`, the collider AND draped grass all see them |
-| `channels` | `[]` | river/road TRENCHES carved along polylines — `[{ path, width, depth, taper? }]` (the line counterpart of `basins`). This is what gives a `River3D` a bed to sit in; `heightAt`, the collider and draped vegetation all see it |
+| `channels` | `[]` | river/road TRENCHES carved along polylines — `[{ path, width, depth, taper? }]` (the line counterpart of `basins`). Points are `[x, z]` **or `[x, y, z]`** (the y ignored), the same as `River3D.path`, so one array feeds both. This is what gives a `River3D` a bed to sit in; `heightAt`, the collider and draped vegetation all see it |
 | `wetline` | `null` | WET SAND band — `{ y, band? }` darkens + glosses the splat in a noisy, breathing band just above height `y` (a waterline): the trace of the last swash runup. `band` (default `1.1` m) caps how high above `y` reads wet. `null` = off |
 
+**A `Terrain3D` DRAWS a landscape; it is SOLID only under a body.** Colliders are
+props on bodies in this engine, never implicit, so a bare terrain is scenery the
+player falls through — while it renders perfectly, `heightAt` answers, and
+`snapToGround` puts the whole scene on it. Wrap it:
+
+```json
+{ "name": "Floor", "type": "StaticBody3D", "props": { "collider": { "shape": "heightfield" } },
+  "children": [ { "name": "Ground", "type": "Terrain3D", "props": { "size": [180, 180] } } ] }
+```
+
+`auditScene` (and so `incanto-check`) says so now, naming the node — a game
+spent an hour falling through the world before it did. It only speaks when
+NOTHING in the scene is solid: a decorative terrain beside a solid one (a lagoon
+bed under the waves, a far ridge) is ordinary.
+
+
 **Wet sand at a shoreline.** Set `wetline.y` to the SAME world height as the
 adjoining `Water3D` surface and the beach keeps a damp, glossy apron that
 breathes with the swash — sell any beach/lakeshore in one prop:
@@ -721,6 +759,114 @@ every rim cliff top and inside the sand band, and auto-fits `maxHeight`
 down for seeds whose rim is too tall. Hand-author only when you need a
 non-default composition.
 
+## Weather3D — rain and snow that follow the camera
+
+The scene had a sky, a fog, a cloud deck and a sun, and no weather: rain was
+forty lines of `Particles3D` tuning an author had to know, plus a script to
+keep the emitter over the camera. One node now:
+
+```json
+{ "name": "Rain", "type": "Weather3D",
+  "props": { "kind": "rain", "intensity": 0.7, "wind": [2, 0] } }
+```
+
+| prop | default | what it does |
+|---|---|---|
+| `kind` | `"rain"` | `rain` — fast, straight, a shower · `snow` — slow, drifting flakes |
+| `intensity` | `0.6` | how much of it, 0..1; scales the rate LIVE (a storm that builds, a shower that passes); `0` = a dry sky |
+| `radius` | `20` | half-width (m) of the box the drops are born in, around what is followed |
+| `height` | `12` | how far above it they are born (m) |
+| `wind` | `[0, 0]` | a steady drift, m/s, on the ground plane `[x, z]` — every drop is born with it |
+| `follow` | `""` | what to follow; `""` = the current `Camera3D` |
+
+- It is a `Particles3D`: every particle prop is still there to override (a
+  colour, a size, `maxParticles`), but `kind` sets them all and the drops
+  fall in WORLD space, so what fell stays where it fell when the camera
+  moves on. Headless it simulates like any emitter (`aliveCount`), so a
+  harness can assert that it rains.
+- **A raindrop is a STREAK.** The particle system draws soft round dots, which
+  is right for smoke and sparks and reads as a dirty lens for rain: measured in
+  a browser at `intensity: 1`, 2,600 dots the size of dust and nothing that
+  looked like weather. Rain now draws with its own stamp — a bright vertical
+  line with soft ends — and the drop is 55 px long (0.55 m) instead of 10.
+  Snow keeps the flake.
+- **The sun goes BEHIND the camera in rain.** Lit from ahead the streaks wash
+  into a bright sky and vanish; from behind they read against it. The rest of a
+  storm is the atmosphere block, written live as the weather builds:
+
+  ```ts
+  env.sky = { type: 'atmosphere', elevationDeg: mix(30, 13), azimuthDeg: 10,
+              turbidity: mix(5, 14), rayleigh: mix(1.8, 0.65) };
+  env.ambient = { color: '#9fb0cc', intensity: mix(0.62, 0.3) };
+  fog.far = mix(120, 34);
+  ```
+
+  Every one of those is picked up per frame, so a storm is a behaviour writing
+  numbers — there is no weather state machine to learn.
+- **`intensity` is what a game holds on to.** Nothing else about the weather is
+  gameplay: whether the rain MEANS anything is the game's own wiring. In
+  `examples/moor-3d` it drives the fog, the sky and how far a hound's `Sight`
+  reaches — the same hound closes 4.1 m on the player in the clear and 0.0 m in
+  the downpour.
+- Composed in `examples/rooftops-3d` (a shower over the run) and
+  `examples/moor-3d` (a storm that IS the game).
+
+**It OWNS the emitter it inherits.** `Weather3D` extends `Particles3D` and tunes
+the whole thing from `kind` and `intensity` on the first frame — `rate`,
+`speed`, `lifetime`, `drift`, `emitBox`, the colours, the sizes, the blend. Those
+props are inherited, so the loader takes them and the editor offers them, and
+they are DISCARDED. `kind`, `intensity`, `radius`, `height`, `wind` and `follow`
+are what steer it; `auditScene` names any of the others you write.
+
+Two props `Weather3D` needed became general: **`emitBox`** on
+`Particles2D/3D` (half-extents of a box the particles are born in — a
+cloud, a dusty field, sparks along a bench; `[0,0,0]` = a point) and
+**`drift`** (a steady velocity every particle is born with — wind on smoke,
+a current in water).
+
+## Flock3D — birds and fish
+
+Forty-eight examples and not one flock — no gulls over the harbor, no fish
+under the boat — because a flock was a behaviour per bird and a body per
+bird, and nobody paid that. `Flock3D` is an `InstancedMesh3D` that flies its
+own instances:
+
+```json
+{ "name": "Gulls", "type": "Flock3D",
+  "props": { "position": [0, 14, 0], "count": 40, "radius": 30, "height": 6,
+             "mesh": "box", "size": [0.5, 0.08, 0.3],
+             "material": { "color": "#f4f4f4" }, "follow": "/root/Boat" } }
+```
+
+| prop | default | what it does |
+|---|---|---|
+| `count` | `30` | how many; live — a change reseeds |
+| `radius` / `height` | `20` / `8` | the bound: an ellipsoid this wide and this tall around the centre, which they turn back inside of. A flat one (`height` 1.5 at y −2) keeps fish under the surface |
+| `speed` | `6` | every bird's pace, m/s — always, so a flock never stalls |
+| `turn` | `2.5` | the sharpest turn, rad/s; lower is lazier, gull-like |
+| `separation` | `1.5` | closer than this and two birds push apart |
+| `sight` | `5` | how far a bird sees neighbours for the next two |
+| `alignment` / `cohesion` | `1` / `1` | match the neighbours' heading; drift toward their centre. `0` switches one off |
+| `follow` | `''` | a node the centre follows, offset by this node's `position` — gulls 14 m over the boat, wherever it sails |
+
+Plus everything `InstancedMesh3D` has (`mesh`, `size`, `material`, shadows);
+`transforms` is driven for you and `collider` is refused — birds are not
+solid. Each instance faces +z along its flight, so a mesh longer in z reads
+as a body with a beak. One draw call; forty birds cost forty-squared distance
+checks a frame, so keep `count` in the dozens, not the thousands.
+
+Seeded from `engine.rng`: a seeded run flies the same flight. **`boids()`**
+answers headless — `{x, y, z, vx, vy, vz}` per bird in world metres — so a
+harness can ask that the fish stayed under the water and the gulls over it
+(`examples/harbor-3d` does).
+
+**It owns `transforms`.** `Flock3D` extends `InstancedMesh3D` and rewrites them
+every frame from the boids, so authoring a row there does nothing — `count`,
+`radius`, `height`, `speed`, `turn`, `separation`, `sight`, `alignment`,
+`cohesion` and `follow` are what steer it, and `auditScene` says so if you write
+the other. `boids()` answers where every one of them is, in world metres and
+m/s, which is how a harness asks whether they kept station.
+
 ## Water3D
 
 ### The player's graphics setting reaches this node
@@ -761,15 +907,29 @@ A commercial-quality water surface (in `incanto/3d`, registered by
 `examples/water-*-3d` templates stage one each (cove pier, resort pool,
 mirror-lake dock, walled garden pond). The default `quality: 'fancy'` is a
 real water shader:
-9-iteration simplex-FBM wave displacement with analytic normals, optional
+9-iteration simplex-FBM wave displacement with analytic normals — or, with
+`wind` > 0, a real JONSWAP SPECTRUM inverse-FFT'd on the GPU every frame (the
+ocean preset: 65 536 waves, each at its own deep-water speed, choppy crests,
+whitecaps where the surface folds, and a per-pixel slope texture whose mips
+hand a far pixel the slope VARIANCE it integrates — the roughness of a distant
+sea, measured rather than guessed) — plus optional
 DIRECTIONAL TRAVELING SWELL trains + open-water whitecaps (`swell` /
 `whitecaps` — the open-ocean look; see the prop table), a DISPERSION-TIMED
 micro-ripple spectrum — four octaves (λ 6 m → 0.38 m), each advected at its
 REAL deep-water phase speed so short ripples flicker ~2×/s (slow fine ripple
 is what makes water read as syrup), the fine octaves interference-PAIRED so
-the surface churns instead of sliding, each octave distance-faded — sun
-glitter straight off that spectrum (facets align for only a flash — natural
-grain, weighted toward the sun's azimuth path and grazing views), per-channel
+the surface churns instead of sliding, each octave distance-faded, plus a
+16 cm "spark" octave inside arm's reach — the SUN as a real GGX microfacet
+highlight off that spectrum (near the camera every resolved facet
+that faces the sun flashes, HDR so the bloom pass reads it; with distance
+the roughness grows and the same lobe widens into the continuous sun path a
+far sea shows — no azimuth gate, no hand-shaped powers), a SEA-STATE
+fresnel (the far, wind-roughened field reflects the sky at the ~0.5-0.6 a
+rough mirror really does at grazing angles, so the ocean stays a darker band
+under its sky instead of whiting out into the horizon haze; calm near water
+is untouched), light THROUGH the crest (with `swell`: looking toward the sun
+the thin crests glow translucent turquoise — lit from inside, the one cue
+that says water rather than painted lumps), per-channel
 Beer's-law depth `absorption` (red dies first — turquoise shallows fade
 WIDE into deep teal-blue, like a real sea), CRYSTAL shallows (inside the
 first ~1.5 m of water the refracted bottom dominates, ripple-distorted —
@@ -814,24 +974,28 @@ hue reads grey.
 | `reflection` | `true` | live CubeCamera reflections (fancy only; needs a renderer) |
 | `reflectionInterval` | `1000` | ms between CubeCamera reflection re-renders |
 | `mirror` | `false` | TRUE planar reflection (see below) — the only way the dock, the boat and the player appear IN the water. One extra scene render per frame |
+| `ssr` | `true` | screen-space reflections (fancy only): the scene ABOVE the waterline is rendered once at half res and every water pixel marches its reflected ray through that image — a rock, a pier, a wader, a boat mirrored on the water with NO planar pass. What the screen cannot see (behind the camera, past its edges) falls back to the sky cube, so a mirror-calm lake still wants `mirror: true`; with `mirror` on this is skipped as redundant, and a tier that forbids the mirror pass forbids this too (same cost class: one more half-res scene submission). `false` keeps the cube-only sky reflection |
 | `mirrorInterval` | `33` | ms between planar-mirror re-renders. A reflection seen through a rippling surface does not need 60 Hz; 33 halves the pass's cost. 0 = every frame |
 | `swellSteepness` | `0.35` | GERSTNER pinch on the swell: 0 = height-only trains, 1 = maximum trochoid (crests narrow to a peak, troughs broaden). It also decides where whitecaps break — the surface's Jacobian collapses on a folding crest, and that is where foam belongs |
 | `foam` | `true` | noise-broken shoreline foam band + crest foam near shores |
 | `interaction` | `true` | character interaction: bodies (CharacterBody3D/RigidBody3D) inside the XZ footprint whose FEET dip below the surface count as in-water — so a WADING character (origin above water, feet below, sized from its collider) splashes, not only a fully-submerged one. Entry/exit emit `entered`/`exited` + a splash ripple; striding through water trails a WAKE (a ripple every ~0.45 m); floating bodies bob gently. Ripples drive both shaders' `uRipples[8]` (fancy) and CPU-displace the mesh (`simple`) |
 | `splash` | `true` | built-in splash WHITEWATER (needs `interaction`): the shaders paint expanding **surface foam** where bodies interact — a **"풍덩"** froth bloom when a body plunges in (bigger the faster it falls) and a **foam trail ("물살")** behind a body wading/running through. Real frothy whitewater on the surface, not flying droplets; works on both `fancy` and `simple` quality. `false` keeps the ripples/waves but paints no foam. No wiring needed; for an extra custom burst add your own `Particles3D` on the `entered` signal |
 | `sunDirection` | `[0.5, 0.8, 0.3]` | TOWARD the sun, for the specular glint — match the scene's key light (non-zero, load-time check) |
-| `sunColor` | `"#fff5d6"` | glint/sheen tint |
-| `sunIntensity` | `1` | glint/sheen strength (≥ 0; 0 = off) |
-| `detailStrength` | `0.26` | animated detail-normal strength (≥ 0; 0 = vertex normals only) |
+| `sunColor` | `"#fff5d6"` | sun highlight tint |
+| `sunIntensity` | `1` | sun highlight strength (≥ 0; 0 = off). The highlight is a GGX lobe over the detail normal and runs HDR on purpose — the sun's reflection is the brightest thing on any water and is what `environment.bloom` catches; 0.7-1.25 is the presets' range |
+| `detailStrength` | `0.26` | animated detail-normal strength (≥ 0; 0 = vertex normals only). Under it runs a LIVE ripple FFT (a second 6 m spectrum patch, 4.7 cm texels, inverse-transformed every frame): the wind ripple every fancy surface wears — real churn with a mip chain for distance instead of scrolling noise — normalized so its rms slope is 0.8 × this value; three short procedural octaves stay on at reduced weight for the sub-pixel facets that flash (a filtered texture alone hands the sun one soft lobe). Without float render targets the noise octaves carry it all, as before |
 | `absorption` | `0.15` | Beer's-law constant per meter of water depth (≥ 0; lower = clearer/wider turquoise band; red absorbs ~3× faster than blue under the hood) |
 | `refraction` | `true` | screen-space refraction of the submerged scene |
-| `preset` | `"custom"` | **THE one-choice water type** (0.16.0): `ocean` \| `pool` \| `lake` \| `pond` bundles every wave/color/clarity/caustics knob into a hand-tuned sea state. A preset value applies ONLY where a prop still sits at its schema default — pick the type, then override any detail prop and your value wins. ocean = traveling swell + whitecaps + wide turquoise→deep absorption · pool = near-flat crystal water + strong above-water caustics · lake = calm high-reflectivity mirror, green-teal murk · pond = still, mossy, opaque quickly. `custom` (default) changes nothing |
+| `preset` | `"custom"` | **THE one-choice water type** (0.16.0): `ocean` \| `pool` \| `lake` \| `pond` bundles every wave/color/clarity/caustics knob into a hand-tuned sea state. A preset value applies ONLY where a prop still sits at its schema default — pick the type, then override any detail prop and your value wins. ocean = traveling swell + whitecaps + wide turquoise→deep absorption · pool = near-flat crystal water + strong above-water caustics · lake = calm high-reflectivity mirror, green-teal murk, short low wind chop (a 9 m set at 3 cm — a lake has no swell, and the 24 m one it used to ship was the single strongest source of the 꿀렁꿀렁 gel read) · pond = still, mossy, opaque quickly. `custom` (default) changes nothing |
 | `shoreWaves` | `0` | **traveling shore BREAKERS** 0–1 (fancy + depth pre-pass, 0.17.0): foam fronts that roll down the depth gradient and break toward every beach — fronts follow the shore's depth contours automatically (bays curve them, points wrap them, zero wiring). Sharp collapsing face + long noisy wash, alive in the 0.1–3.2 m shoaling band. Ocean preset ships 0.7 |
 | `causticsAbove` | `0` | above-water CAUSTICS intensity 0–3 (fancy + `refraction` only): the dancing light web on the submerged bottom seen THROUGH the surface — the pool / tropical-shallows look. Reconstructed on the real refracted bottom position, strongest through the first meters of water, distance-faded. Presets set it (pool 1.0); override freely |
 | `swell` | `0` | **THE open-ocean dial** (fancy only, 0.15.0): directional traveling swell amplitude in meters. Three peaked wave trains (primary + two crossing sets) march across the surface at real deep-water speeds; crests light up toward the peak color and wave FACES get sun-lit/shadow shading, so the swell reads at any distance. 0.15 = lively lake chop, 0.4 = coastal sea, 0.7 = heavy weather. `0` (default) keeps the legacy calm look byte-identical |
 | `swellDirectionDeg` | `0` | compass direction the swell TRAVELS toward (0 = +z, 90 = +x) |
 | `swellWavelength` | `30` | primary swell wavelength, meters (≥ 2, load-time check); the crossing trains derive from it |
-| `whitecaps` | `0` | open-water whitecap foam on the tallest crests, 0–1 (fancy only; load-time check). Pairs with `swell` — the caps ride its crest lines and fade with distance so the horizon stays clean |
+| `whitecaps` | `0` | open-water whitecap foam on the tallest crests, 0–1 (fancy only; load-time check). Pairs with `swell` — the caps ride its crest lines and fade with distance so the horizon stays clean. With `wind` on, the caps are born where the FFT sea's surface actually FOLDS (its Jacobian) and fade over seconds |
+| `bed` | `""` | node path to the Terrain3D under this water (fancy only). With it the swell KNOWS the beach: once the water is shallower than a quarter wavelength a wave RISES by Green's law (depth^-1/4, capped 2×) and its crest peaks; at 0.78× the depth it BREAKS — the height is capped there and the crest turns to torn whitewater — and the FFT sea shoals and breaks the same way. Spray sprites burst on the 0.3–0.9 m break line when the `shoreWaves` foam fronts pass (needs `shoreWaves` > 0; a few hundred camera-facing puffs, one draw). Sampled once into a 256² depth grid over the terrain's footprint; beyond it the water is assumed 12 m deep. The ocean template points it at its island |
+| `wind` | `0` | **THE realistic-sea dial** (fancy only; m/s; ≥ 0, load-time check). Above 0 the surface stops being a noise field and becomes a JONSWAP SPECTRUM — thousands of waves at every wavelength and heading, each moving at the speed deep water gives it — inverse-FFT'd on the GPU every frame (256², ~37 tiny passes) into a 200 m tiling patch with real crest shapes, choppy horizontal drag and fold-born whitecaps. Blows toward `swellDirectionDeg`. 4 = a light breeze (20 cm ripple), 6.5 = the ocean preset's fresh breeze (Hs ≈ 1.4 m), 12 = rough. `waveHeight` is inert while wind > 0 (the FBM is replaced, not added); `swell` still rides underneath as the long-period set a 200 m patch cannot hold. `heightAt` / buoyancy / waders sum the strongest 2048 modes of the SAME spectrum on the CPU (~8% of the rms height, ~45 µs a call). Needs float render targets (every WebGL2 desktop, iOS 15+) — without them the analytic waves stay and the CPU twin follows |
+| `choppiness` | `0.85` | horizontal drag of the FFT sea toward its crests (≥ 0): 0 = pure height field, ~0.9 = narrow crests over broad troughs, past ~1.2 the surface folds and foams everywhere |
 | `underwater` | `true` | submerged-camera look: ONLY when the camera EYE is below this surface (inside its XZ footprint) — wading with the camera above the water never tints the view — the scene switches to short-range underwater fog + tint, the sky is hidden, and animated **caustics** (depth-aware, projected onto the submerged floor/props) play. `false` disables it; an object `{ color?, visibility?, caustics? }` overrides the murk hue / view distance (m, default 22) / caustics. `caustics` is `true` (default) \| `false` \| `{ color?, intensity?, scale?, speed? }`. The murk color defaults to a darkened shade of `color`. Works for both qualities (the caustics composite runs only while the camera is genuinely underwater) |
 
 Performance notes (fancy): beyond drawing the surface, each rendered frame
@@ -882,6 +1046,26 @@ plane and samples it per fragment, so those things appear in the water:
 - Geometry below the waterline is clipped out of the mirror pass, and the whole
   pass is skipped while the camera is submerged.
 
+### Asking how deep something is — `depthAt(x, y, z)`
+
+```ts
+const pool = game.scene.root.getNode('Pool') as Water3D;
+const under = pool.depthAt(...player.position);   // metres below the surface, 0 above
+if (under > 0.5) breath -= dt;
+```
+
+Metres BELOW this water's surface, `0` above it — and `0` outside the pool's
+footprint, because a point that is not over the water is not in it. That last
+part is the whole reason it exists: `heightAt(x, z)` answers the surface height
+EVERYWHERE, so the obvious spelling of "am I under water"
+(`y < water.heightAt(x, z)`) calls a player standing in a cellar a hundred
+metres inland submerged. The wave is included, so a swimmer bobbing under a
+trough and under a crest get different answers, which is what they feel.
+
+A breath meter, muffled audio, a "you surfaced" banner and an enemy that only
+strikes below are all this one call. With several pools, ask the one the player
+is over — or take the largest answer.
+
 ### Under the surface
 
 Swimming down is a different optical world, and the engine renders it as one:
@@ -1069,8 +1253,67 @@ emitter to the body first — the signal hands you the node:
 that emitter `"worldSpace": true`, or the second splash drags the first one to
 the new spot.)
 
+### Things that float — `RigidBody3D.buoyancy`
+
+Two ways to float a body, and the difference is who decides the waterline.
+The **`Buoyancy` behaviour** (`incanto-gameplay-behaviors.md`) is the one
+you AUTHOR: a `draft`, a hull `size`, a `stiffness`, and `drift` — a wave
+face is a slope and a raft slides down it — which is what a raft, a cast
+bobber or a boat with a tuned feel wants (`beacon-isle-3d`, `fishing-3d`,
+`water-ocean-3d`). The **`buoyancy` prop** below is the one PHYSICS decides:
+Archimedes on the collider, so `mass` against its volume says whether it
+floats and how deep — a crate that sinks when it is heavy, a hull that sits
+lower with cargo, an anchor that goes down by the same rule as the crates
+that do not. Use one, never both on one body.
+
+```json
+{ "name": "Crate", "type": "RigidBody3D",
+  "props": { "position": [4, 2, 0], "mass": 150, "buoyancy": 1,
+             "collider": { "shape": "box", "size": [1, 1, 1] } } }
+```
+
+- **`buoyancy: 1` is water's own upthrust** — the submerged part of the
+  collider's volume at 1000 kg/m³ — so `mass` against the collider decides
+  everything: a 1 m³ crate at 200 kg floats a fifth under (its centre 0.3 m
+  over the surface), at 600 kg it sits deeper, at 3000 kg it sinks to the bed.
+  A boat is a box hull at a third to a half of its volume in kg: `[2.2, 0.8,
+  4.4]` at 3000 kg sits 0.3 m in. `0` (the default) is air. Under 1 lifts
+  less for the same mass; nothing needs it, and mass is the honest knob.
+- **It rides the waves.** The upthrust reads `heightAt` under eight sample
+  points across the collider, so the surface it floats on is the one the
+  player sees — and a tilted hull's low corners push harder, which is what
+  rights it. A CUBE a fifth under has a metacentric height of 1.7 cm, all but
+  neutral, so it rolls easily; a wide flat hull rights itself firmly. Author
+  crates light (150 kg for 1 m³) and hulls wide.
+- **It settles in about one bob whatever it weighs**: the vertical motion is
+  damped to 0.7 of critical for the hull's own spring (a crate dropped from
+  3 m bounced out of the water and back for half a minute before that).
+- **`Water3D.drag`** (1.5) holds travel and spin back, per second, in full
+  once a quarter of the hull is under: a pushed crate coasts a few lengths and
+  stops; `0` is ice, `6` is syrup. Spin loses three times that — a hull turning
+  drags its whole wetted side.
+- The shape is what Rapier built: a box, sphere, capsule or cylinder by its
+  own volume; an `auto` fit as the box it made; a hull or mesh as the box
+  around its vertices. The swimmer's body (a `CharacterController3D` under
+  it) is never lifted here — the controller's swim spring owns that one.
+- Any footprint works: a body beside the lake, over dry ground, is not lifted;
+  one over the water is, from the moment its lowest sample dips under.
+
+Thrust and steering are yours — `applyImpulse` along the hull's +z and a
+written `angularVelocity[1]` for the rudder are all `examples/harbor-3d`
+needs to drive a boat, push six crates into a pen and lose one to the rocks.
+
 ## River3D — running water
 
+**A river with no `path` is not a river.** `path` defaults to `[]` and one point
+is a hard load error, so the shape that is checked is the one nobody writes: with
+NO points the node builds no channel — it draws nothing, carves nothing and
+pushes nothing, whatever `width`, `flowSpeed` and `flowForce` say. It warns once
+on its first frame now, rather than being an inert node in a scene that audits
+clean. Give it at least two `[x, z]` control points, source → mouth, in the
+node's own local frame.
+
+
 `Water3D` is a *surface*; `River3D` is a *current*. A river is authored as a
 line, not a shape: give it a centerline `path` and a width, and the terrain
 underneath decides everything else.
@@ -1087,21 +1330,21 @@ underneath decides everything else.
 
 | prop | default | meaning |
 |---|---|---|
-| `path` | `[]` | centerline `[[x, z], …]` in NODE-LOCAL meters, Catmull-Rom smoothed (2+ points) |
+| `path` | `[]` | centerline `[[x, z], …]` in NODE-LOCAL meters, Catmull-Rom smoothed (2+ points). **`[x, y, z]` is accepted too** and the y is ignored — a course has no height of its own, and every other world coordinate in a 3D scene is three numbers, so one array can feed both this and `Terrain3D.channels` |
 | `width` | `6` | channel width in meters |
 | `widths` | `[]` | width profile lerped source→mouth (e.g. `[2.5, 5, 9]`); empty = constant `width` |
 | `depth` | `0.8` | water column at the centerline — also the scale foam thresholds read as "shallow" |
 | `flowSpeed` | `1.6` | reference current in m/s (the mean; reaches speed up and slow down) |
-| `colors` | `{}` | `{ shallow, deep, sky, horizon, bank }` — the body ramp plus what the surface mirrors |
+| `colors` | `{}` | `{ shallow, deep, sky, horizon, bank }` — the body ramp plus what the surface mirrors. In a live renderer the river keeps its OWN sky cube (the world beyond its banks, refreshed every 2 s, near-clipped so the banks never smear across it) and mirrors THAT through a sea-state fresnel; `sky`/`horizon` are then the headless fallback and `bank` is still what the lowest rays meet. A 6 m ripple FFT rides the current in the ribbon's own frame under `ripples` |
 | `absorption` | `0.5` | how fast the water hides its bed (Beer's law) |
 | `opacity` | `0.85` | upper bound on the body's opacity |
 | `foam` | `1` | whitewater dial — 0 = a glassy canal, 2 = raging |
-| `ripples` | `1` | surface-detail dial (ripple relief + glitter) |
+| `ripples` | `1` | surface-detail dial (ripple relief, the fine near-field wavelets, and how much sun the water throws) |
 | `terrain` | `""` | drape target path; empty = auto-find the first Terrain3D (a wrong path fails at load) |
 | `carve` | `true` | cut the bed. The river trenches its own channel into the terrain it drapes on — see below |
 | `flowForce` | `1` | how hard the current sweeps bodies downstream (0 = visual only) |
 | `spray` | `1` | mist at the foot of every drop the course turns out to contain — the node finds them and hangs a Particles3D plume on each (0 = off) |
-| `sunDirection` / `sunColor` / `sunIntensity` | sky / `#fff6e0` / `1` | glint (the environment sun wins while `sunDirection` is default) |
+| `sunDirection` / `sunColor` / `sunIntensity` | sky / `#fff6e0` / `1` | the sun highlight — a GGX lobe over the wavelet normal, HDR so the bloom pass reads it (the environment sun wins while `sunDirection` is default) |
 
 **What the node derives for you**, all from `path` + the ground:
 

package/skills/incanto-game-feel.md

@@ -42,7 +42,8 @@ script was dying reads as a healthy character, so read those lines first.
 holds `move` for five seconds and takes the 90th percentile of the run, because
 the maximum belongs to whatever hit the character last. Measured on the shipped
 `platformer-2d`, whose `RUN_SPEED` is 250: it reported `top speed 300 u/s` —
-that is `KNOCK_X`, from an enemy the probe walked into — and `to full speed
+that is the knockback (then a hand-written `KNOCK_X`, now the player Health's
+`knockback`), from an enemy the probe walked into — and `to full speed
 2367 ms`, which was the walk to the enemy, on a character that reaches its speed
 in ONE frame. Four numbers, all about a character being attacked. When the peak
 and the sustained speed disagree the report says so:
@@ -127,6 +128,64 @@ When nothing moves it says so instead of printing a zero:
 OFF — you asked about that action, so a silent answer about a different one
 would be worse than no answer.
 
+## It presses your title screen first
+
+A game with a title screen boots PAUSED — `GameFlow.pause()` from the shell's
+`onReady` is what holds the world behind the menu — and a probe that drives a
+stopped world measures nothing. Three of this repo's own examples ship that
+shell, and so does every game scaffolded from one.
+
+So before measuring, the probe presses what a player can reach: the HUD's
+`focusables()` (which already excludes hidden panels and disabled buttons),
+buttons labelled PLAY / START / RESUME first, until `engine.timeScale` stops
+being 0. Nothing is pressed in a game that was already running.
+
+When even that does not start it, the report says so instead of printing zeros:
+
+```
+  the clock never ran: this game was PAUSED for the whole measurement
+  (`engine.timeScale` 0), and it stayed that way after pressing every button on
+  screen. …
+
+  coyote window    not measured — the clock was stopped   (the scene declares 120 ms)
+  jump buffer      not measured — the clock was stopped   (the scene declares 150 ms)
+```
+
+**A window nobody could measure is not a window of zero.** Before this, a shipped
+starter that declares `coyoteSeconds: 0.12` reported `coyote window 0 ms` and
+advised its author to set `coyoteSeconds: 0.12`. The advice below only ever fires
+on a number that was actually taken.
+
+It also sits out an opening **cutscene**. That is the other way a game holds the
+player still, and it looks nothing like a pause: the clock runs, the world moves,
+and only `controller.enabled` is false while a camera flies around. The probe
+waits up to fifteen seconds for control and says so if it never comes.
+
+## The windows are searched by JUMPING
+
+`coyote window` and `jump buffer` are measured by lifting the body and pressing —
+so a character that never leaves the ground fails every step of that search, and
+that failure came back as `0`. Three shipped examples printed
+`jump apex — (nothing left the ground)` and then `coyote window 0 ms` with advice
+attached, one of them declaring `coyoteSeconds: 0.12` in the same file.
+
+When nothing jumps in any of the four probes (standing, held, walking,
+sprinting), both windows read `not measured — nothing ever jumped` and the report
+says the thing worth saying instead:
+
+```
+  note: this scene declares 'jump' and NOTHING left the ground in any
+        of the four jump probes — standing, held, walking, sprinting. Check that the
+        controller reads 'jump', that its `jumpVelocity` is not 0, and that it is `enabled`.
+```
+
+**In a two-player scene, the player it drives and the buttons it presses are the
+same character's.** They were not: the props were read from whichever controller
+a stack-walk reached first, which is the LAST one in the file, so a local co-op
+game's player one was sent player two's jump button and reported a jump apex of
+nothing. Move survived it — the move probe has a fallback SEARCH — and jump has
+none, which is why the whole jump half of that report was dashes.
+
 ## It reports, it does not grade
 
 There are no PASS/FAIL bands here on purpose. A twitch platformer and a survival