incanto 0.74.0 → 0.75.0

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
@@ -882,6 +1028,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 +1235,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,7 +1312,7 @@ 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" |

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