incanto 0.68.0 → 0.70.0

package/skills/incanto-building-3d-games.md

@@ -81,7 +81,7 @@ All 3D nodes extend `Node3D` and therefore have the transform props:
 ### `MeshInstance3D`
 | Prop | Default | Notes |
 |---|---|---|
-| `mesh` | `"box"` | `box \| sphere \| capsule \| plane \| cylinder \| gem` — `gem` is a faceted crystal (icosahedron); with `material.flatShading: true` + low `roughness` it reads as a sparkling jewel (spin/tumble it for the sparkle) |
+| `mesh` | `"box"` | `box \| sphere \| capsule \| plane \| cylinder \| gem` — `gem` is a faceted crystal (icosahedron); with `material.flatShading: true` + low `roughness` it reads as a sparkling jewel (spin/tumble it for the sparkle). **This list is the whole list**: for a CURVED hull — a car body, a boat, a canopy, a fuselage — there is no primitive, and stacking boxes never gives you one. Use `LoftMesh3D` (below) |
 | `size` | `[1,1,1]` | box: extents · sphere/gem: radius = x · capsule: radius = x, height = y · plane: x·z ground (laid FLAT on XZ) · cylinder: radius = x, height = y |
 | `material` | `{}` | `{color: '#hex', metalness: 0..1, roughness: 0..1, opacity: 0..1, clearcoat: 0..1, clearcoatRoughness: 0..1, envMapIntensity: >=0, wireframe, flatShading, depthTest, depthWrite, emissive, emissiveIntensity, map, normalMap, repeat: [u,v]}` — the object IS the material state: omitted keys reset to defaults (`#ffffff`, 0, 1, 1, false, false, depthTest/Write true). `opacity < 1` turns on transparency; `flatShading` gives faceted per-face glints (the gem sparkle). `depthTest: false` (+ a high `renderOrder`) makes a flat `plane`/`cylinder` an ALWAYS-ON-TOP ground decal — AoE telegraphs, selection/spawn rings — that never z-fights with or is hidden by bumpy terrain (`depthWrite: false` keeps it from occluding later effects). `map`/`normalMap` are texture URLs (lazy-loaded, headless-safe; map samples sRGB, normalMap linear), tiled `repeat` times across each face — box/plane UVs span 0..1 per face, so for worldspace density use `repeat: [length/tile, height/tile]` (e.g. a 6×2.5 m brick wall at one tile per 2 m → `[3, 1.25]`). `color` tints the map (near-white keeps the texture's own color). CAR PAINT: `clearcoat: 1` adds a glossy lacquer layer with its own reflection over a metallic base (`clearcoatRoughness` ~0.05-0.1 = mirror lacquer) — THE premium vehicle-paint look; `envMapIntensity` scales how strongly the surface mirrors the scene's sky/HDRI (glass windows want ~2, matte surfaces <1; needs a `sky`/`hdri` environment to reflect — at night with no sky there is nothing to mirror). NB: under ACES a very bright `emissiveIntensity` blows out to white — keep it modest (~1–2) + a saturated color for a vivid GLOWING look. Unknown keys, malformed `repeat`, or `repeat` without a map hard-fail at load |
 | `castShadow` / `receiveShadow` | `false` | |
@@ -270,10 +270,43 @@ and `Fill.position = [-(1 - frac) / 2, 0, 0.01]`. The offsets stay local to the
 (rotated) bar, so the drain always hugs the bar's left edge.
 
 ### `Camera3D`
-`fov: 60`, `near: 0.1`, `far: 1000`, `current: false`.
+`fov: 60`, `near: 0.1`, `far: 1000`, `current: false`, `lookAt: ""`.
 Mark exactly ONE camera `current: true` (otherwise the first camera in tree order is used).
-Aspect ratio is automatic. To frame an origin-centered scene, a good default is
-`position: [7, 6, 9]`, `rotation: [-26, 36, 0]`.
+Aspect ratio is automatic.
+
+**Point it with `lookAt`, not with a `rotation` you worked out.**
+
+```json
+{ "name": "Cam", "type": "Camera3D",
+  "props": { "current": true, "position": [7, 6, 9], "lookAt": "%Player" } }
+```
+
+`lookAt` is a node path, re-aimed every frame, so it also tracks a target that
+moves. It orients with WORLD UP, which is the part you cannot write yourself in
+scene JSON — and cannot write in game code either without importing three, which
+this engine's own guardrail forbids ("mutate node props — never touch three.js
+objects").
+
+This is not a convenience. A hand-written `rotation` for a camera is
+**wrong at every heading but one**, and the way it is wrong is invisible from
+inside the frame:
+
+- The one published direction→rotation formula (`incanto-3d-character.md`, "the
+  +Z-FORWARD rule", *"There is ONE facing formula"*) is derived for a SKIN — a rod,
+  which has no meaningful up. Measured over 72 look headings, applying it to a
+  camera aims perfectly (dot 1.000 in all 72) and puts the world **upside down in
+  36 of them**. Its own published check, `rodAxis · (target − eye) ≈ 1`, scores
+  1.000 on every upside-down one.
+- **No two-angle recipe can be right.** `rotation` is Euler XYZ, so
+  `[pitch, yaw, 0]` is Rx·Ry while a level camera is Ry·Rx: an upright camera's
+  third angle is NON-ZERO. The `[-26, 36, 0]` this document recommended for years
+  aims at 0.9924 and tilts the horizon **16°**; the level answer is
+  `[-33.69, 32.91, 19.91]`, which nobody would write by hand.
+- A camera looks down its own local **−Z**, unlike every skin in the engine.
+
+`framing()` now prints `up [x, y, z]` and the roll in degrees, so a tilted or
+inverted camera is something you can SEE in a report rather than something you
+notice in a screenshot.
 
 ### Lights
 - `DirectionalLight3D` — `color: '#ffffff'`, `intensity: 1`, `castShadow: false`.
@@ -320,8 +353,66 @@ atmosphere recipe below).
 
 ## Reference example
 
-A minimal 3D scene — ground plane + 3 orbiting primitives + sun +
-lamp + camera, verified rendering. Copy it as a starting point.
+The smallest 3D scene that renders something you can see. Every line matters:
+without the light it is black, without `current: true` the camera is a guess,
+and without `ambient` the unlit faces are pitch dark.
+
+```json
+{
+  "format": 1,
+  "type": "scene",
+  "dimension": "3d",
+  "name": "Hello",
+  "environment": {
+    "sky": { "type": "atmosphere", "elevationDeg": 35, "azimuthDeg": 140 },
+    "ambient": { "color": "#ffffff", "intensity": 0.2 },
+    "shadows": true
+  },
+  "root": {
+    "name": "World",
+    "type": "Node3D",
+    "children": [
+      { "name": "Sun", "type": "DirectionalLight3D",
+        "props": { "position": [6, 10, 4], "intensity": 2, "castShadow": true } },
+      { "name": "Camera", "type": "Camera3D",
+        "props": { "position": [7, 6, 9], "rotation": [-26, 36, 0], "current": true } },
+      { "name": "Ground", "type": "MeshInstance3D",
+        "props": { "mesh": "plane", "size": [40, 1, 40], "receiveShadow": true,
+                   "material": { "color": "#6b8f3a", "roughness": 1 } } },
+      { "name": "Pivot", "type": "Node3D", "script": { "name": "Spin" },
+        "children": [
+          { "name": "Cube", "type": "MeshInstance3D",
+            "props": { "mesh": "box", "position": [2, 0.5, 0], "castShadow": true,
+                       "material": { "color": "#e0563f", "roughness": 0.4 } } },
+          { "name": "Ball", "type": "MeshInstance3D",
+            "props": { "mesh": "sphere", "size": [0.6, 0.6, 0.6], "position": [-2, 0.6, 0],
+                       "castShadow": true,
+                       "material": { "color": "#4f8fe0", "metalness": 0.6, "roughness": 0.2 } } },
+          { "name": "Gem", "type": "MeshInstance3D",
+            "props": { "mesh": "gem", "size": [0.5, 0.5, 0.5], "position": [0, 0.8, 2],
+                       "castShadow": true,
+                       "material": { "color": "#ffd166", "flatShading": true, "roughness": 0.1 } } }
+        ] }
+    ]
+  }
+}
+```
+
+Rotating the PIVOT orbits all three children — no maths in the behaviour:
+
+```ts
+import { Behavior } from 'incanto';
+
+export class Spin extends Behavior {
+  override update(dt: number): void {
+    const node = this.node as unknown as { rotation: number[] };
+    node.rotation = [0, (node.rotation[1] ?? 0) + 40 * dt, 0];
+  }
+}
+```
+
+Check it before you open a browser: `bunx incanto-check` says the scene is legal
+and lit, and `bunx incanto-verify` walks the whole ladder.
 
 ## Atmosphere (sky, fog, shadows, exposure)
 
@@ -466,6 +557,13 @@ for (const o of off) console.error(`  ${o.path}: ${o.gap > 0 ? 'floats' : 'burie
 Put it in your `verify.ts` next to `auditScene`. It costs nothing and it is the
 difference between shipping a floating bridge and not.
 
+**Mark what is not meant to touch the ground.** `snapToGround: false` is the
+escape and it INHERITS, so one mark exempts a whole assembly: a cloud made of
+puffs, a palm made of trunk segments, a lamp at the top of a lighthouse, a rock
+sunk into the slope on purpose. Put it on the group, not on its parts — before
+0.73 it read the node's own prop only, and this repo's own flagship template
+reported 64 floating cloud puffs.
+
 ## The loading screen has to cover the WHOLE boot
 
 Downloading the assets is the first half. Building a dressed scene and
@@ -511,6 +609,20 @@ previous explosion across the level) as
 point sprites in meters: preset distances auto-scale ÷100 (presets are authored
 in 2D px). See incanto-building-2d-games for the full prop list.
 
+**Firing one from a behaviour is `replay()`** — move the emitter, then replay:
+
+```ts
+const dust = this.node.getNode('Dust') as Particles3D;
+dust.position = [x, 0.2, z];
+dust.replay();                 // `emitting: false` stays false; this is the game asking
+```
+
+Not `play`, not `burst`, not `emit` (that one belongs to signals). The 2D skill
+has always named it and this one did not, so a 3D game built from this page
+alone had a one-shot it could not fire. `particles()` is the same node's test
+hook — the live particle list, for a harness asking whether anything came out.
+`engine.effects.countOf('explosion')` is the cheaper question.
+
 Points render through a built-in soft sprite with a SOLID opaque core (not hard
 squares), so colours read even at small sizes, and `'normal'` blend fades cleanly
 to transparent (per-particle RGBA alpha). `paletteColors` (per-particle

package/skills/incanto-editor.md

@@ -18,8 +18,20 @@ bunx incanto-editor level.scene.json --output build/level.scene.json --port 5179
 
 **Project mode** (no file argument — the usual way) scans the current directory for
 `*.scene.json` (skipping node_modules/dist/hidden dirs): one scene auto-opens; several
-open the scene browser. The page can only ever address `*.scene.json` files under the
-launch directory.
+open the scene browser.
+
+**What the server will and will not touch**, since the browser lists every
+`.json` and the answer comes from the server:
+
+| | |
+| --- | --- |
+| reads | any `.json` **under the launch directory** — but only sends it if it IS a scene; anything else comes back with the reason and its contents never leave |
+| writes | a scene, over a file that is already a scene, or to a file that does not exist yet |
+| refuses | a path outside the project, a non-scene body, and **overwriting a file that is not a scene** — `?file=package.json` gets a 409 naming what it found |
+
+That last row used to be missing: the write path checked the body and never what
+it was about to land on, so one query parameter could replace a manifest with a
+scene. The GET on the same endpoint already refused it.
 
 ### The scene browser (`scenes`)
 
@@ -108,7 +120,13 @@ Opens a local page (default `http://127.0.0.1:5179/`) with three panes:
   changed. A prop is rewritten only if its type declares `nodePath: true`, so a
   text prop that merely reads "Player" is never touched. `+` adds a child of any registered
   type, `✕` deletes the selection. Selecting the ⚙ scene row edits the header
-  (dimension, gravity with real inputs, environment/input/assets/multiplayer/strings).
+  (dimension, gravity with real inputs, environment/input/assets/multiplayer),
+  including a **STRINGS table** — one row per `@t:` key, one column per
+  language. It shows the two things raw JSON cannot: an untranslated cell shows
+  the English it will silently fall back to (greyed, because that fallback is
+  the design), and a key the BASE locale is missing is marked in red, because
+  that one has nothing to fall back to and paints the raw key on screen.
+  `+ key`, `+ language`, and deleting a key that a prop still says asks first.
 - **CONNECTIONS on the selected node** — the inspector's last section shows what
   the node **emits** and what it **receives**, each row being signal → target →
   handler with a ✕ to remove and `+ connect` to add. Signals come from the node
@@ -116,8 +134,12 @@ 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`, `once`,
-  bound args — the scene header still has `connections` as raw JSON.
+  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.)
   **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
@@ -167,8 +189,11 @@ Opens a local page (default `http://127.0.0.1:5179/`) with three panes:
   `invulnerableFor`/`freeOnDeath` with their defaults; a `Patrol`'s `mode` is a
   `loop`/`pingpong` menu), delta-only like every other field. A name that is NOT
   built in is your game's TypeScript: it keeps the raw-JSON props box and says
-  so, with copy-paste Behavior boilerplate in its help — and `groups` (tag
-  chips). Every one has a `?` help popover with examples. Values equal to the
+  so, with copy-paste Behavior boilerplate in its help — `groups` (name chips)
+  and `tags` (the node's free-form identity JSON: what
+  `connections[].filter.tag` matches on, and where a chart, a card or a loot
+  entry lives; a value the loader would reject is marked invalid rather than
+  written). Every one has a `?` help popover with examples. Values equal to the
   default are removed (delta-only, like the serializer).
   **A prop that holds a NODE PATH** (`Chase.target`, `Camera2D.follow`,
   `Spawner.prefab`, `Joint3D.target`, `skinPath`, `terrain`…) offers every node
@@ -358,6 +383,20 @@ 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.
 
+**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
+a stale `openEditor()` both do nothing — but if your app keeps using the handle,
+take the live one:
+
+```ts
+let game = await createGame3D({
+  scene, canvas,
+  debug: DEBUG,
+  editor: DEBUG && { library: true, onReboot: (next) => { game = next; } },
+});
+```
+
 ## Animating a model from the inspector
 
 Select a `ModelInstance3D` and everything about what it is DOING sits in one

package/skills/incanto-environment.md

@@ -201,6 +201,24 @@ template). Options: `seed`, `size` (32 blocks), `height` (8), `water`. The
 voxel `generateIsland` (radial dome falloff, sandy shore) also remains for
 the same use case.
 
+**Digging and building** is the node's own API, and for a long time none of it
+was written down here — the whole point of a voxel world is that it changes:
+
+```ts
+const world = this.node.getNode('World') as VoxelGrid3D;
+world.tileAt(x, y, z);              // the tile there, or undefined
+world.removeBlockAt(x, y, z);       // dig — true if there was one
+world.addBlock({ x, y, z, tile: 3 });
+world.setBlocks(blocks);            // replace the lot (emits `blocksChanged`)
+world.blockCount();                 // how many are standing
+world.blocks();                     // every one of them, to save or inspect
+```
+
+Grid coordinates, not world ones — multiply by the node's `blockSize` to place
+something on a block. `TileMap2D` answers the same questions in two dimensions
+(`cellAt`/`tileAt`/`worldAt`/`setTile`), and that one takes WORLD coordinates
+because a flat world has a cursor in it.
+
 ## Library
 
 ```ts
@@ -609,7 +627,7 @@ is radians of `atan(|∇h|)`. Default textures stream from the live agent8 CDN
 | `theme` | `"island"` | see table — `custom` requires `layers` |
 | `roughness` | `0.5` | detail-octave persistence (higher = more rugged) |
 | `detail` | `4` | detail octave count |
-| `flatThreshold` | `0.95` | snap-flatten heights within ±0.6 m of `maxHeight·flatThreshold` |
+| `flatThreshold` | `0.95` | snap-flatten heights within ±0.6 m of `maxHeight·flatThreshold` — a fraction of the SCALE, not of the peak, so the default plateau lands around 18% of the realized height (measured: maxHeight 28 → band at 26.6, peak 150). Read `heightAt` before choosing one |
 | `islandEdge` | `null` | `null` = theme decides; force the rim wrap on/off with a boolean |
 | `layers` | `[]` | custom splat layers (theme `custom` only) |
 | `textureBase` | agent8 CDN | base URL: `<base>/<name>.png` + `<base>/<name>_normal.png` |

package/skills/incanto-game-feel.md

@@ -14,6 +14,7 @@ bunx incanto-feel src/game.scene.json
 ```
 feel of /Game/Player
 
+  pushed           'move' [1, 0]
   top speed        5.62 u/s
   to full speed    383 ms
   to a stop        133 ms
@@ -28,12 +29,58 @@ feel of /Game/Player
   jump buffer      150 ms
 ```
 
+A `✗` or `!` line above the numbers is what the ENGINE said while they were
+being taken — a script that threw and was quarantined, a camera following a node
+with no position. The measurements below it are still real (a behaviour is
+quarantined, the node is not), but a page of confident numbers taken while a
+script was dying reads as a healthy character, so read those lines first.
+
 ## Why this exists
 
+**`top speed` is what the character SUSTAINS, not its fastest frame.** The probe
+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
+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:
+
+```
+top speed        250 u/s
+to full speed    17 ms
+peak             300 u/s   ← SOMETHING ELSE moved it
+```
+
+Measure feel somewhere nothing can hit you.
+
+**A character that jumps in MID-AIR has no coyote window to measure.** The probe
+lifts the body, waits, presses, and reads "vertical velocity went up" as a jump —
+so a double jump answers yes at any delay, and so does any behaviour that pushes
+the body up while `jump` is held (a glide, a jetpack, an updraft). It used to
+print `coyote window always (no window)`, which reads as the opposite of the
+truth, on two of the six shipped starters — one of which declares
+`coyoteSeconds: 0.12` five lines from its glide. It says
+
+```
+coyote window    not measurable — this character jumps in MID-AIR
+jump buffer      33 ms   (suspect — see above)
+```
+
+and names the declared value it cannot confirm. To measure the window, probe a
+build with the air jump off.
+
 **`jumpVelocity: 4` is not a height.** It is an impulse, and what it produces
 depends on gravity, mass, drag and `fallGravity`. The apex in world units and the
 hang time in milliseconds are what you are actually choosing.
 
+**It says what it pushed.** The `pushed` line names the action AND the direction
+that produced every number under it. The probe used to hold `(1, 0)` and only
+`(1, 0)`, so a game whose movement reads the OTHER axis of the same action —
+`-v.y`, which is this engine's own documented forward, `getVector` being y-down —
+measured nothing and printed the nothing as `top speed 0 u/s` with four blank
+rows and exit 0. A racer that its own harness clocked at 41 m/s reported 0.
+
 **The windows are MEASURED, not read.** `coyoteMs` comes from probing — lift the
 character clear of its support, wait, press, see whether it launched, binary
 search the boundary. A `coyoteSeconds: 0.12` that the controller never consults
@@ -52,6 +99,29 @@ reports **0 ms**. That was a real bug in this engine's own 3D controller until
 | `coyote window` | **0 reads to players as "the controls are broken"**, not as a missing feature. |
 | `jump buffer` | 0 throws away a press made a few frames before landing. |
 
+## When it cannot move your player
+
+If the default push finds no motion, the tool SEARCHES: every declared `vector2`
+action, each pushed ±x and ±y, and it keeps whichever moved the body furthest.
+That is a fallback, never a replacement — a scene that already answered cannot
+have its numbers changed by it. Two real games it rescues: a throttle on `-v.y`,
+and a game where an unrelated `aim` happened to be declared FIRST in the input
+map (the default move action is "the first `vector2`").
+
+When nothing moves it says so instead of printing a zero:
+
+```
+  pushed           'move', 'aim' every way (±x, ±y) — the player did not move
+
+  could not move /Game/Turret: no motion in 300 frames with 'move', 'aim' pushed
+  ±x and ±y. Either the movement is not wired to a vector action, or it is
+  driven by buttons. Nothing below was measured.
+```
+
+`--move <action>` pins the action explicitly, and pinning it turns the search
+OFF — you asked about that action, so a silent answer about a different one
+would be worse than no answer.
+
 ## It reports, it does not grade
 
 There are no PASS/FAIL bands here on purpose. A twitch platformer and a survival

package/skills/incanto-gameplay-behaviors.md

@@ -71,7 +71,15 @@ warn: World/Enemy: Chase.target — '%Playerr' matches no node in this scene.
 
 — which is the one failure that used to be completely silent (a prop path
 resolves with `getNodeOrNull`, so the scene opens and the enemy just never
-chases). `Chase.target` and `FollowCamera.target` are `required`: an EMPTY one
+chases). It works for a behaviour of YOUR OWN too, given the file that registers it:
+`incanto-check src --behaviors src/behaviors.ts` prints the identical sentence
+for `Archer.arrowTemplate`. Without the flag the checker has no schema for your
+behaviours and their node-path props are invisible to it — which is why every
+scaffolded project's `check` script passes it, and why a hand-written one that
+does not loses the check silently. `auditScene` from `incanto/test` is the same
+audit from inside your harness, once your behaviours are registered.
+
+`Chase.target` and `FollowCamera.target` are `required`: an EMPTY one
 is a load error naming the node, not a surprise in the browser.
 
 **Never write `/root/<RootName>/...`.** If your root node is named `Game`, the
@@ -99,6 +107,7 @@ Hit points with regen and post-hit invulnerability (i-frames). The universal
 | `regenPerSec` | `0` | HP regained per second (0 = off) |
 | `invulnerableFor` | `0` | seconds of immunity after a hit (i-frames; 0 = off) |
 | `freeOnDeath` | `false` | `queueFree()` this node when it dies (clone-safe) |
+| `freeParent` | `false` | with `freeOnDeath`, free the PARENT — the enemy, when `Health` rides a child node |
 
 Signals: `damaged(amount, current)` · `healed(amount, current)` ·
 `healthChanged(current, max)` · `died` · `revived(current)`
@@ -143,6 +152,13 @@ still while the character heals. Use `damaged`/`healed` for reacting to the HIT
 > node-local, so it clones perfectly and frees the whole enemy with no wiring.
 > (Connections are still the right tool for NON-cloned nodes, e.g. the player's
 > `died → ScoreKeeper.loseLife`.)
+>
+> A node carries ONE script, so if the root is already taken — a `Patrol` you
+> did not give `moveParent`, an `Area2D` with a `Clickable` — put `Health` on a
+> child and add **`freeParent: true`**. Without it the child frees ITSELF and
+> the body walks on with no health at all: an immortal enemy that takes damage
+> from nothing and reports nothing. Same prop, same reason, as `Lifetime` and
+> `DamageOnContact`.
 
 ## Lifetime
 
@@ -175,7 +191,10 @@ once; reaching 0 lives emits `lost` once.
 | `lives` | `0` | starting lives (0 = lives disabled) |
 | `scoreToWin` | `0` | score that triggers `won` (0 = disabled) |
 
-Signals: `scoreChanged(score)` · `won` · `lost` · `lifeLost(lives)`
+Signals: `scoreChanged(score)` · `won` · `lost` · `lifeLost(lives)` ·
+`livesChanged(lives)` — the EVENT and the COUNT: `lifeLost` fires when a life is
+spent (flash, respawn), `livesChanged` also fires when a save is restored, so a
+lives counter belongs on that one.
 Methods: `addScore(n)` · `setScore(n)` · `loseLife()`
 
 ```json
@@ -377,7 +396,7 @@ author markers). Emits `reachedPoint(index)` on arrival.
 
 | Prop | Default | Meaning |
 |---|---|---|
-| `points` | `[]` | waypoints: position arrays or node-path strings (required) |
+| `points` | `[]` | waypoints: position arrays (LOCAL to the moved node) or node-path strings (that marker's WORLD position) — required |
 | `speed` | `60` | units per second along the path |
 | `loop` | `true` | wrap to the first point after the last (loop mode) |
 | `mode` | `"loop"` | `'loop'` wraps · `'pingpong'` reverses at the ends |
@@ -388,6 +407,18 @@ author markers). Emits `reachedPoint(index)` on arrival.
 
 Signals: `reachedPoint(index)`
 
+**The two waypoint forms are in different frames, on purpose.** An array is a
+LOCAL offset — the only thing numbers typed into a prop can mean. A node path
+means *where that marker actually is*, so markers under `/root/Path` and
+walkers under a spawn container work, which is how a lane is organised. Before
+0.71 a node path was read as a local offset too, so a walker whose parent was
+not at the markers' origin walked a shifted copy of the path in silence.
+
+Need to CHANGE the route at runtime rather than author it? That is
+`PathFollow` and its `setPath()` (see *Pathfinding*, below) — `Patrol.points` is read live
+but the index and direction are not re-derived, so writing points mid-route
+moves the corners under a walker that is still heading for the old one.
+
 ```json
 { "name": "Guard", "type": "Node2D",
   "script": { "name": "Patrol", "props": { "points": [[100, 0], [300, 0]], "speed": 80, "mode": "pingpong" } } }
@@ -569,6 +600,13 @@ placeTower(pad);
 "you cannot afford that" is one wire to a banner. It saves through `serialize()`
 like `Health` and `ScoreKeeper`.
 
+A NON-POSITIVE amount is ignored, the way `Health.damage`/`heal` have always
+ignored one — and a negative is reported, because it is a sign flip in the
+caller rather than an offer. `spend(-5)` used to PAY you five (any negative
+passes the affordability test, and the subtraction then added) and `earn(-5)`
+to take five, going round `canAfford` and `refused` entirely. `spend(0)` returns
+`true`: you can always afford nothing.
+
 ## Wander
 
 Seeded random roaming inside a circle around the spawn point — idle critters,
@@ -658,6 +696,15 @@ are NOT cloned):
 - **(B) scene `connection`** (fine for a single authored entity, NOT for clones):
   `{ "signal": "movementStateChanged", "from": "Enemy/AI", "to": "Enemy/Skin", "handler": "setClip" }`.
 
+**Subscribing in `onReady` is safe to do to anything, including a node that
+outlives you.** A connection made there is owned by the node making it, so
+`free()` takes it with the node — you do not have to keep the returned
+disconnect and call it yourself. That matters most for the shape this pattern
+invites: every enemy subscribing to the score keeper or the player, where the
+emitter outlives thousands of listeners. (Wiring a signal from a `update()` or
+from outside a lifecycle method still hands ownership to you — keep the
+disconnect, or pass `{ owner: someNode }`.)
+
 Same `ZombieSkin` is the place to also FACE the heading and GROUND the body each frame
 (see incanto-3d-character.md "+Z-FORWARD rule" and incanto-3d-models.md "Grounding").
 
@@ -715,7 +762,7 @@ all a raft, a buoy, a crate or a body needs to bob, settle and ride the swell.
 
 | Prop | Default | Meaning |
 |---|---|---|
-| `water` | `""` | Water3D node path; empty = the first Water3D in the tree (a wrong path fails hard) |
+| `water` | `""` | Water3D node path; empty = the first Water3D in the tree (a wrong path fails hard; NO water in the scene is an `incanto-check` warning) |
 | `draft` | `0.35` | where the resting WATERLINE sits below the body origin, in meters — the hull floats with its origin that far above the water |
 | `stiffness` | `3` | how stiffly it returns to that waterline (extra g of lift per draft of submersion): 1 wallows, 3 is a firm dinghy, 8 is a cork |
 | `damping` | `3.5` | vertical damping (1/s) — how fast the bobbing settles |
@@ -775,7 +822,7 @@ later clones get `EnemyTemplate2`, `EnemyTemplate3`, …)
 | Prop | Default | Meaning |
 |---|---|---|
 | `prefab` | `""` | node path of the template to clone (required) |
-| `interval` | `1` | seconds between spawns |
+| `interval` | `1` | seconds between spawns — `0` is one clone per FRAME and is refused unless `max` or `total` caps it |
 | `max` | `0` | max LIVE instances (0 = unlimited) |
 | `at` | `[]` | where the clone appears, as an offset from the spawner ([x,y(,z)]) |
 | `autoStart` | `true` | begin ticking at ready |
@@ -855,19 +902,55 @@ union-typed prop so its default is `null` (= `'forward'`).
 
 In 3D, `'forward'` is the engine's ONE facing convention — **+Z**, the same
 `atan2(dx, dz)` basis `CharacterController3D` uses and `incanto-3d-character.md`
-spells out under "the +Z-FORWARD rule". So aim the bullet (or its shooter) with
-that formula and it flies at what you aimed at; do not add 180°. (Before 0.62
-this returned three.js's −Z instead, so every `'forward'` shot left the muzzle
-pointing at the shooter's back — at the right speed, with no error, which reads
-as a gun that simply never hits anything.) In 2D `rotation` is a scalar and
-`'forward'` is +x turned clockwise by it, unchanged.
+spells out under "the +Z-FORWARD rule". So aim the BULLET with that formula and
+it flies at what you aimed at; do not add 180°. (Before 0.62 this returned
+three.js's −Z instead, so every `'forward'` shot left the muzzle pointing at the
+shooter's back — at the right speed, with no error, which reads as a gun that
+simply never hits anything.) In 2D `rotation` is a scalar and `'forward'` is +x
+turned clockwise by it, unchanged.
+
+**Aim the bullet, not the shooter.** Turning a turret does not turn a bullet
+parented under it: world position is composed TRANSLATION-ONLY, so a bolt under
+a turret at `rotation: 90` still lands at world `[100, 0]`, not `[0, 100]`. Set
+the heading on the projectile itself.
 
 | Prop | Default | Meaning |
 |---|---|---|
-| `speed` | `300` | units per second along `direction` |
-| `direction` | `null` | a vector `[x,y(,z)]` OR `'forward'` (`null` = forward) |
+| `speed` | `300` | units per second along `direction` — **live**, rescales in flight |
+| `direction` | `null` | a vector `[x,y(,z)]` OR `'forward'` (`null` = forward) — **live** |
 | `gravity` | `0` | constant +y (downward, 2D y-down) pull for arcing shots |
 
+### Aiming a bullet you just spawned
+
+Every prop above is LIVE, and the heading is resolved on the projectile's FIRST
+STEP — which is after `spawned(node)` fires. That window is the whole point:
+`SpawnSource.spawn` ends with `addChild(clone)` and `Spawner` emits `spawned`
+afterwards, so a handler is by definition "too late" for anything baked at
+`onReady`.
+
+```ts
+spawner.on('spawned', (bolt) => {
+  // either spelling works — set the node's rotation…
+  (bolt as { rotation: number }).rotation = (Math.atan2(dy, dx) * 180) / Math.PI;
+  // …or hand the behavior a vector
+  (bolt.behavior as Projectile).direction = [dx / len, dy / len];
+});
+```
+
+Mid-flight, writing `direction` or `speed` re-bakes immediately (the fall
+`gravity` has accumulated is kept — it is a fact about the world, not about the
+shot). What is deliberately NOT live is `rotation` after that first step: a
+projectile that spins for looks must not have its spin become its trajectory.
+Call **`aim()`** to re-derive from the current rotation on purpose:
+
+```ts
+bolt.rotation = newHeadingDeg;
+(bolt.behavior as Projectile).aim();        // or aim([dx, dy]) to pass a vector
+```
+
+Before 0.70 all of this was dead: `direction` accepted the write, READ BACK the
+new value, and the bolt kept flying the old way.
+
 ```json
 { "name": "Bullet", "type": "Area2D", "props": { "rotation": 0 },
   "script": { "name": "Projectile", "props": { "speed": 600, "direction": "forward" } } }
@@ -1168,6 +1251,14 @@ The panel is hidden while playing and shown while paused — `GameFlow` owns its
 `visible`, so do not set it yourself. `pauseAction` and `pausePanelPath` rename
 either half; `pausePanelPath: ""` turns it off.
 
+While the panel is up its `HudLayer` gets `focusNavigation` — arrow keys, d-pad
+and A — and the ring starts on the first widget. The layer's own value is put
+back on resume, so a game that navigates by pad all the time keeps doing so —
+unless the game CHANGED it during the pause, in which case the game had the last
+word and keeps it.
+That is the one thing every pause menu needs and nobody remembers: a menu you
+can only click is not playable on a controller.
+
 The pause key is polled in `update()`, which still runs at `timeScale 0` — a
 menu that cannot be closed by the key that opened it is worse than no menu.
 
@@ -1181,7 +1272,7 @@ physics, input. Listen to the `flowChanged(state)` signal for custom UI.
 `restartScene(engine)` is exported standalone.
 
 **Any scene swap thaws.** The freeze lives on the engine, not on the flow, so
-leaving a game-over screen by your own route — `engine.setScene(loadScene(next))`
+leaving a game-over screen by your own route — `engine.setScene(loadScene(next, { engine }))`
 from a menu button — puts `timeScale` back to 1 as surely as `flow.restart()`
 does. You cannot restart into a frozen level.
 
@@ -1189,11 +1280,27 @@ Multi-scene games: `flow.goToScene(nextSceneJson, { fadeSeconds: 0.4 })`
 fades to black, swaps, fades back (headless = instant). Title → level →
 next level is three JSON files and this one call.
 
+**A swap builds the physics world the incoming scene needs.** `physics: 'auto'`
+can only look at the scene the game BOOTS with, and a title screen has no
+bodies — so this used to leave the level with no physics at all: it rendered
+perfectly, nothing fell, nothing collided, nothing could be collected or hurt.
+`createGame2D`/`createGame3D` now hand the engine a way to build one, and the
+swap asks. It is asynchronous (Rapier is WASM), so the first frames after a
+swap into a physics scene run unsimulated — imperceptible, and the alternative
+was a game that never simulated. `physics: false` stays off across swaps, and a
+scene with no bodies still pays for nothing.
+
 ## DayNight (live 24-hour cycle)
 
 Drives the scene `environment` (needs an atmosphere sky): sun elevation/
 azimuth arc, ambient + exposure ramps with a moonlight floor.
 
+**No `sky` in the scene environment = nothing to drive.** The clock still runs
+and `dayPhaseChanged` still fires, so the signals look right and the screen
+never changes; the behaviour says so once, in the engine log. Add
+`"sky": { "type": "atmosphere" }` to the scene's `environment` — or set it at
+runtime, which it keeps looking for.
+
 ```jsonc
 { "script": { "name": "DayNight", "props": { "daySeconds": 240, "startHour": 9 } } }
 ```