incanto 0.74.0 → 0.76.0

package/skills/incanto-performance.md

@@ -48,6 +48,38 @@ and are comparable to each other. Headless (`step()`), `fps`/`frameMs` are 0 and
 the slices are still real CPU times — a behavior that got slower shows up in a
 test.
 
+### Measuring a frame by hand: `step()` ALREADY renders
+
+The renderer subscribes to `engine.updated`, so a frame is one call:
+
+```ts
+const t0 = performance.now();
+for (let i = 0; i < 120; i++) game.engine.step(1 / 60);   // draws, too
+const frameMs = (performance.now() - t0) / 120;
+```
+
+Calling `game.renderer.render(...)` after `step()` draws the scene TWICE and
+doubles every number you take. It reads as a plausible result rather than an
+obvious mistake — the flagship template measured 24.9 ms a frame that way and
+**8.96 ms** the honest way, which is the difference between "this does not hold
+60" and "this holds 60 twice over".
+
+The same trap is why a hidden tab needs care: a tool-created tab has its
+animation frames paused, so driving `step()` yourself is the only way to get
+frames — and the one call is the whole frame.
+
+For reference, the numbers `bunx incanto-new` scaffolds (Beacon Isle, an M-class
+laptop, 220 nodes and 29 `Tree3D` groves):
+
+| tier | frame | render | draw calls | triangles |
+| --- | --- | --- | --- | --- |
+| high | 8.96 ms | 8.44 ms | 999 | 7.3 M |
+| medium | 7.75 ms | 7.04 ms | 580 | 6.2 M |
+| low | 7.17 ms | 6.68 ms | 576 | 6.2 M |
+
+The tier is doing its job — it takes 42% of the draw calls out — and the render
+is where a 3D game's frame goes, which is what the dials in this skill are for.
+
 ## The short version
 
 ```ts

package/skills/incanto-physics-and-input.md

@@ -120,7 +120,13 @@ mesh or one model and warns when the body carries more.
   enemy-hitbox Area) — neither side needs to be a Body.
 - **`CharacterBody2D/3D`** — kinematic character (Rapier KCC). Props: `collider`
   (capsule recommended), `velocity`, `stickToGround true`, `slopeLimitDeg 45`,
-  `stepHeight` (3D `0.35` m / 2D `35` px — see below), and
+  `stepHeight` (3D `0.35` m / 2D `35` px — see below), **`pushes 0`** — the
+  mass (kg) this body SHOVES dynamic bodies with. The KCC treats a dynamic
+  body as an OBSTACLE — a character walks around things — so a beam on a
+  `Patrol` slid up to the player and stopped dead against them, forever. A
+  piston, a sweeping arm, a moving wall or a bruiser enemy is a thing that
+  shoves: `pushes: 90` and it pushes what it meets, the harder the heavier
+  (`examples/tower-3d`'s beam). `0` keeps every scene as it was. And
   **`collideWithCharacters true`** — whether OTHER characters are obstacles to
   this one. Leave it on for a few enemies; turn it OFF for a horde: eighty
   chasers around a player cost 64–286 ms a STEP with it on (each slide
@@ -150,6 +156,22 @@ sword.enabled = true;    // the active window of the swing
 sword.enabled = false;   // …and done
 ```
 
+A switched-off SENSOR overlaps nothing — including a body teleported into it
+while it is off. Rapier still reports an intersection-start for a disabled
+collider in that case (measured: `isEnabled()` false, event delivered), and a
+guard's grab disarmed for a cutscene killed the player the camera had left
+standing in it; both adapters now drop any event on a node whose `enabled` is
+false, and re-arming reports what the sensor is inside of.
+
+**A child body sits where its parent's frame puts it — rotation included.** A
+hit sensor two metres down +z of a hull turned 90° is at world +x, where the
+renderer draws it. Both adapters used to sum positions up the tree and ignore
+every rotation, so a guard's grab box "in front" of a turned guard, a tank's
+barrel-tip sensor and a turret's muzzle all sat where nothing was drawn; a
+dynamic body under a turned parent keeps a LOCAL pose on the way back. The same
+composition is behind `worldPosition()` for behaviours, so `Turret`, `Sight`
+and `FollowCamera` measure from where a node IS. Scale is still not composed.
+
 **A collider's keys are CLOSED**: `shape`, `size`, `radius`, `height`, `offset`
 and (2D) `oneWay` — plus `vertices`/`indices` for a 3D trimesh. Anything else is
 a load error naming the nearest one, because
@@ -271,6 +293,21 @@ engine now does for you:
 
   Every `incanto-new` template and every runnable example ships exactly this.
 
+**A 3D game needs two more things a 2D one does not**, and both are one line:
+
+- **The camera has to turn.** The stick walks; looking around is a DRAG on the
+  play area, and that only exists when the game asks for it:
+  `createGame3D({ pointer: true })`. Without it a phone player can walk and
+  never look. (A drag on the stick or a button never turns the camera — the
+  controls are siblings of the canvas and eat their own gestures.)
+- **Portrait is a keyhole.** `Camera3D.fov` is the VERTICAL field of view, so a
+  `fov: 60` camera shows 91° across a 16:9 window and **30° across a 390×844
+  phone** — the same game, down a drinking straw. Set
+  `Camera3D.minHorizontalFov` (52 is a good floor) and the vertical fov widens
+  until that much is on screen; a window already wider keeps the fov it was
+  authored with. Pair it with `CharacterController3D.pitchStart` (about −14°) —
+  a tall screen spends its top half on sky with a level camera.
+
 Two more phone facts worth knowing:
 
 - **Audio unlocks on ANY first gesture** — the canvas, a key, or the on-screen
@@ -349,11 +386,146 @@ body B (any node path — `%Name` is typical):
   ]}
 ```
 
-Types — 2D: `fixed` (weld) · `revolute` (pin/hinge) · `rope` (max distance)
-· `spring` (pull toward `length` with `stiffness`/`damping`). 3D swaps
-`revolute` for `spherical` (ball joint). `length: 0` measures the body
-distance at creation. `anchor`/`targetAnchor` are local offsets (px / m).
-Chains work (pendulums, bridges: each link a body + joint to the previous).
+Types — 2D: `fixed` (weld) · `revolute` (pin/hinge) · `prismatic` (a SLIDE
+along `axis`) · `rope` (max distance) · `spring` (pull toward `length` with
+`stiffness`/`damping`). 3D has all of those plus `spherical` (ball joint);
+its `revolute` turns about `axis` and its `prismatic` slides along it (local
+to the joint's body, default `[0, 1, 0]`; 2D's `axis` defaults to `[0, 1]`,
+so an "up" slide in y-down 2D is `[0, -1]`). `length: 0` measures the body
+distance at creation — and a rope's or spring's `length`, `stiffness` and
+`damping` are LIVE: a write REMAKES the joint on the next step, the bodies
+keeping their motion, which is how a grapple reels its rope in
+(`rope.length -= 5 * dt` — `examples/grapple-3d`). `anchor`/`targetAnchor`
+are local offsets (px / m).
+Chains work (pendulums, bridges: each link a body + joint to the previous —
+`examples/wreck-3d` hangs a wrecking ball off six of them).
+
+**A hinge has stops and a motor; so does a slide.** On a `revolute` or a
+`prismatic` in either dimension:
+
+| prop | default | what it is |
+|---|---|---|
+| `limits` | `[]` | the stops — `[minDeg, maxDeg]` for a hinge, `[min, max]` metres (px) for a slide; empty = free. A door that opens one way: `[0, 110]`; a portcullis that lifts three metres: `[0, 3]` |
+| `motorSpeed` | `0` | the speed the motor drives it at — degrees a second (hinge) or metres a second (slide; px in 2D); `0` = no motor, the joint is free. A mill wheel: `40`; a drawbridge coming down: `-25` toward its lower limit, where the motor then HOLDS it; an elevator going up: `1.2` |
+| `motorStrength` | `20` | the motor's gain — acceleration per unit of speed error. **Against gravity the motor sags by g/motorStrength**: a lift at `20` rises at half the asked speed, at `100` within a tenth of it |
+| `angle` | read-only | a hinge's current angle in degrees: the joint's OWN body turned about the axis, relative to the target. `if (hinge.angle > 60)` is "the door is open" |
+| `travel` | read-only | a slide's current travel in metres (px): the joint's own anchor along the axis relative to the target's — `0` where the anchors coincide, which is where the scene loaded |
+
+All three props are LIVE — a lever behaviour that writes `hinge.motorSpeed = -25`
+starts the winch that frame — and `limits`/`angle` share one convention (the
+joint's body relative to the target), so a limit you read off `angle` is the
+limit you write. `examples/contraption-3d` is a gate you push, a drawbridge a
+lever lowers, a millstone that never stops and a seesaw with stops, all from
+JSON — and the portcullis at its keep is a `prismatic` a `bridgeDown` signal
+lifts.
+
+Four things a hinge taught while that example was built:
+
+- **`angle` is the ACTUAL turn, not "0 as loaded".** A drawbridge authored
+  raised at `rotation: [85, 0, 0]` reads `angle: 85` on the first frame, and
+  its limits are absolute too: `[0, 85]` is "flat to raised". Nothing is
+  measured from the pose the scene loaded in.
+- **Author a turned body about its hinge.** The two anchors must COINCIDE at
+  load (rule 5 below). A deck turned 85° about its near edge has its CENTRE
+  where that turn puts it — compute it (`sill + [0, 3.1·sin 85°, −3.1·cos 85°]`
+  for a 6.2 m deck), do not type it; a mismatch snaps the body into place and
+  the snap looks like a limit pushing it.
+- **A raised thing needs HOLDING.** A hinge with no motor is free: a deck
+  authored raised falls flat on the first frame. `motorSpeed: 25` toward the
+  upper stop holds it there; the lever writes `-25` and the same motor lowers
+  it to the lower stop and holds THAT.
+- **A jointed thing must not rest on static ground.** A millstone whose rim
+  touches the walkway slabs is jammed by friction and turns at 2°/s; a seesaw
+  whose ends rest on the landings does not tilt. Leave a gap.
+
+A grapple is a joint made at RUNTIME: `examples/grapple-3d` casts a ray from
+the eye, and on a static hit builds a `Joint3D` in code — `new Joint3D('Rope')`,
+`type: 'rope'`, `target` the hit body's path, `targetAnchor` the hit point in
+that body's frame, `length` the distance plus a little slack — and adds it
+under the player; `free()` it to let go. The adapter picks a new joint up on
+the next step and drops a freed one; gravity does the swing, and a rope has a
+little give under a swinging weight (about 4% of its length).
+
+## Vehicle3D — a car in one node
+
+`examples/buggy-3d` proves a car can be BUILT from joints, and that building
+one is a round's work with two traps in it. Every racing game, delivery game
+and open world with a road wants one in a node: `Vehicle3D`, under a
+`RigidBody3D` chassis, is Rapier's raycast vehicle — wheels on springs that
+never touch anything (a ray each), so a car cannot catch a kerb on a wheel
+body or disagree with its axle.
+
+```json
+{ "name": "Car", "type": "RigidBody3D",
+  "props": { "mass": 800, "collider": { "shape": "box", "size": [1.8, 0.6, 4] } },
+  "children": [
+    { "name": "Drive", "type": "Vehicle3D", "props": { "wheels": [
+        { "position": [-0.8, -0.1,  1.4], "steer": true },
+        { "position": [ 0.8, -0.1,  1.4], "steer": true },
+        { "position": [-0.8, -0.1, -1.4], "drive": true },
+        { "position": [ 0.8, -0.1, -1.4], "drive": true } ] } },
+    { "name": "Wheel0", "type": "Node3D", "props": { "position": [-0.8, -0.1, 1.4] },
+      "children": [ { "name": "Hub", "type": "Node3D", "children": [
+        { "name": "Tyre", "type": "MeshInstance3D",
+          "props": { "mesh": "cylinder", "size": [0.35, 0.25, 0.35], "rotation": [0, 0, 90] } } ] } ] }
+  ] }
+```
+
+| prop | default | what it does |
+|---|---|---|
+| `wheels` | `[]` | `[{ position, radius?, rest?, steer?, drive? }]` — where each spring hangs from in the CHASSIS's frame; radius 0.35, rest length 0.3; at least one |
+| `suspensionStiffness` · `suspensionCompression` · `suspensionRelaxation` · `maxTravel` | `30` · `2.3` · `3.5` · `0.3` | the springs (20 soft, 30 a car, 60 a kart) |
+| `friction` · `sideFriction` | `2.5` · `1` | tyre grip along and across the wheel (lower side friction = more drift) |
+| `maxSteerDeg` · `engineForce` · `brakeForce` | `32` · `1500` · `40` | full lock, force per driven wheel at full throttle, brake per wheel |
+| `moveAction` · `brakeAction` | `"move"` · `"brake"` | the stick (up throttle, down reverse, left/right steer) and the brake button; `moveAction: ""` = your code writes `throttle`/`steer`/`brake` (−1..1, −1..1, 0..1) |
+
+- **Forward is +z** (the +Z-forward rule, like a skin). Put the camera behind
+  at −z and turn it with the chassis (`examples/courier-3d`'s `ChaseCam`).
+- **The wheel nodes are posed for you.** A child of the chassis named
+  `Wheel<i>` is put at its mount, hanging by the spring's current length, and
+  turned to steer; its child `Hub` spins as the wheel rolls — so a tyre mesh
+  under `Hub`, rotated `[0, 0, 90]` to lie on the axle, just works.
+- **`enabled: false` is parked**: the throttle and steering read nothing and
+  the brake is held, while the suspension still settles and the wheels still
+  pose. Both the car and the character read `move`, so a game with a driver
+  who can get OUT flips this and `CharacterController3D.enabled` together
+  (`examples/errands-3d`; "Letting go" in `incanto-3d-character.md`).
+- **Readbacks.** `speed` (m/s, negative in reverse), `wheel(i)` →
+  `{ contact, suspension, rotation, steering }`.
+- The chassis is an ordinary `RigidBody3D`: `mass` is the car's weight, its
+  `collider` is what hits walls, `angularDamping` calms a flip, and a
+  `Respawn` under it catches a drive off the map. A car on its roof is a
+  stuck game — give the player a reset (the example's `R` rights the car).
+- **Zones are driven THROUGH.** The wheel rays ignore every `Area3D`, so a
+  checkpoint, a delivery bay or a speed trap is a sensor box over the road
+  and the car passes through it level — it does not climb onto the box.
+- **Lift-off is `linearDamping`.** A raycast vehicle has no rolling
+  resistance: released, it coasts at CONSTANT speed until it hits something
+  (measured 14.2 m/s, unchanged over a second). `linearDamping: 0.3` on the
+  chassis is the engine braking (a ~3 s decay) and the top speed —
+  `engineForce × driven wheels / mass ÷ damping` — in one number; the
+  errands van has none and stops on its brake, the race car has it.
+- **Online, a car is its owner's body** — `network: { mode: "owner", sync:
+  ["position", "rotation", "Wheel0.rotation", "Wheel1.rotation"] }` on the
+  chassis, and the other player's car a kinematic `CharacterBody3D` copy you
+  can bump. `examples/race-mp-3d` and "An online race" in
+  `incanto-multiplayer.md`.
+
+A vehicle is the same parts: `examples/buggy-3d` is a box chassis, four
+cylinder wheels on `revolute` axles (the rear pair motored — forward is a
+negative speed about +x), and two steering knuckles whose hinge motor is a
+servo, `motorSpeed = (target − angle) · rate`, with `limits` at full lock. A
+knuckle needs inertia (mass, a real box) and a strong motor to turn a tyre
+that is scrubbing on the ground, and a brake is a motor asked for ~0 with a
+high `motorStrength`.
+
+And two things the ENGINE learned: a motorised body no longer falls asleep
+(Rapier sleeps anything that moves slowly for a while, and a door at 30°/s is
+slow — the motor ran two seconds and froze mid-swing), and a TURNING ground
+now carries its rider round — the moving-platform carry was the ground's
+origin, which a millstone never moves, so its rider stood still while the
+floor turned under him. Both riders (a `CharacterBody3D`'s `moveAndSlide`
+and the player's `platformCarry`), both dimensions.
 
 ## Pushing a body around (the API that was in no skill)
 
@@ -381,6 +553,13 @@ the same sign as `rotation` (clockwise, because 2D is y-down). There is no
 torque call in either. Writes land on the next step — these are live props, not
 load-time constants.
 
+**An impulse composes with a velocity written the same frame.** A mirror
+steering a ball by `linearVelocity`, a magnet, a conveyor — and a kick in the
+same `update` — used to lose the kick: the write reached the solver a step
+later and overwrote it. Now `applyImpulse` lands the pending write first, then
+the impulse, and `linearVelocity` reads the result at once (a harness that
+reads it right after the kick sees the kick).
+
 `fixedRotation` is authored, not live: it locks the body's rotation when the
 body is CREATED. Changing it mid-run does nothing, and a locked body's
 `angularVelocity` is zero rather than whatever was authored.
@@ -414,6 +593,25 @@ exist on `RigidBody2D` in the same terms. "At rest" is yours to decide: read
 `physics.velocityOf(ball)` and call it stopped under ~0.05 for a few frames.
 `examples/minigolf-3d` is the composition.
 
+### A rudder: write `angularVelocity`
+
+`body.angularVelocity = [0, rate, 0]` (or `body.angularVelocity[1] = rate`)
+spins a `RigidBody3D` from that step on, in rad/s about the world axes —
+`+y` turns +z toward +x. It is how `examples/harbor-3d` steers a boat, and
+it did NOTHING in 3D until the harbor round: the adapter read the solver's
+spin back every step and never looked at a script's write (2D always had the
+path).
+A `fixedRotation` body ignores it, as it ignores an authored spin.
+
+### A crate that floats (`buoyancy`)
+
+`RigidBody3D.buoyancy: 1` and a `Water3D` under it: the body is lifted by the
+submerged part of its collider's volume at water's density, so `mass` against
+the collider decides — a 1 m³ crate at 150 kg floats, at 3000 kg it sinks, a
+wide hull rights itself, and it rides the water's waves. `Water3D.drag` slows
+it. The whole rule, with the numbers, is in `incanto-environment.md` ("Things
+that float"); `examples/harbor-3d` drives a boat with it.
+
 ## What is inside this Area right now?
 
 `triggerEnter(other)` / `triggerExit(other)` tell you about CROSSINGS. A pressure
@@ -435,10 +633,11 @@ question you usually mean.
 
 ## Joints: the three things that decide whether yours works
 
-1. **There is no hinge in 3D.** The types are `fixed | spherical | rope | spring`.
-   A hinge is **two `spherical` joints at two points along the axis** — that
-   constrains rotation to the line between them, and it is exactly how a seesaw
-   or a door is built. (2D has `revolute` and needs none of this.)
+1. **A hinge is `revolute` with an `axis`** (3D; 2D's needs no axis). Before it
+   existed the recipe was two `spherical` joints along the axis — that still
+   works, but it has no stops and no motor, and the sentence "there is no hinge
+   in 3D" was true for a year. A seesaw, a door, a wheel and a drawbridge are one
+   joint each now.
 2. **`collide` decides whether the two ends touch, and its default reads the
    type.** Rapier lets jointed bodies collide, and a hinge wants its bodies
    overlapping at the pivot — so the contact solver fights the joint and flings
@@ -460,13 +659,35 @@ question you usually mean.
    it belongs to — is now a load-time error: Rapier accepts a body jointed to
    itself and constrains nothing, and the rope fell exactly as if it were not
    there.
-4. **`anchor`/`targetAnchor` are local offsets from each body's ORIGIN**,
+4. **A joint's own bodies are not the world to the character controller.**
+   A `CharacterBody3D` crane hook with a chain of jointed links hanging off it
+   used to RISE on its own (the controller's shape-cast saw the first link
+   inside the hook's box and pushed the hook out of it, every step) and, parked
+   over the next tower with its chain, landed twice as far as asked (the
+   controller's ground ray hit that same link, so the moving-platform carry
+   dragged the hook along by however far the link had moved — which was however
+   far the hook had just moved). Now a body jointed to a character with the
+   pair's contacts off is not its obstacle, and a body jointed to it is never
+   its ground. So the natural crane — a kinematic hook you drive with
+   `moveAndSlide`, a chain and a ball on `spherical` joints — just works;
+   `examples/wreck-3d` is that crane. Both dimensions.
+5. **The two bodies must AGREE about the axis.** A hinge's or a slide's `axis`
+   is one vector, and Rapier builds a frame from it in EACH body's local space.
+   So the two bodies' rotations may differ only by a turn ABOUT that axis: a
+   drawbridge authored raised about its own hinge is fine; a wheel body turned
+   on its side to lay its cylinder along the axle is not — the chassis reads
+   `[1,0,0]` as world x and the wheel reads it as world y, and a buggy built
+   that way went onto its roof on the first frame. A joint that breaks the
+   rule is refused at creation, by name, with the fix: keep the body
+   unrotated and turn the MESH inside it (`collider: auto` follows the mesh) —
+   `examples/buggy-3d` is four wheels built exactly so.
+6. **`anchor`/`targetAnchor` are local offsets from each body's ORIGIN**,
    resolved against the bodies' positions at load. If the two disagree the solver
    snaps the body into place on the first frame, and a 4 cm typo is silent. Author
    them with arithmetic (generate the scene) rather than by hand.
 
-There are no joint limits or motors yet: bound a lever's travel with static
-collision geometry in its way.
+Limits and motors live on `revolute` (see the table above) — a lever's travel
+is `limits`, not static geometry in its way.
 
 ## Raycasts
 
@@ -539,6 +760,13 @@ and physics rebuilds the body that step. In-place mutation of the existing
 collider object (`body.collider.size[0] = w`) is NOT watched (the per-step
 change scan was removed for performance).
 
+**To switch a body OFF, write `enabled = false`** — not `collider = null`. The
+prop is an object and a non-object used to reach the physics sync and throw
+`null is not an object (evaluating 'node.collider.shape')` out of the frame
+loop, with no node path: the loader refuses `"collider": null` in JSON with a
+typed error, and a runtime write was checked nowhere. It is now refused with
+that sentence, naming the node, and the collider it had is kept.
+
 ## Debug drawing
 
 `physics.debugDraw = true` (the instance `enablePhysics2D/3D` returns) renders

package/skills/incanto-playtesting.md

@@ -71,10 +71,10 @@ the hazards and the destinations down with it.
 | `stuck` | the clock ran out AND the player never got more than 3 m (96 px) from its spawn — it is wedged, or nothing moves it |
 | `swapped` | the game changed scene. The bot binds player, destinations and the win/lose oracle ONCE, from the tree it started in, so nothing after a `goToScene` is measured — the run stops there and says so. It is not a defect, and the destinations it never got to are reported as unmeasured rather than missed. Judge a multi-scene game with a scripted `runScript`. The bot's own KEYS are re-read on the swap: it used to hold the first scene's buttons into the second, and letting go of one the new scene never declared threw the whole playtest away. |
 | `unfinished` | the clock ran out on a player that was getting around. Not a defect: a win that needs a SEQUENCE (talk to the NPC, then fetch, then return) is out of reach of a random walker, forever |
-| `never reached` | destinations the bot never came within `--reach-radius` of (default 2 m in 3D, 32 px in 2D) |
+| `never reached` | destinations the bot never came within `--reach-radius` of (default 2 m in 3D, 32 px in 2D) — of the node's EXTENT, not its origin, so standing on a 30 m quay counts as reaching it. A node earns a place on this list by carrying a group, running a behaviour, or being a trigger volume; measured against origins, every tagged floor in every 3D game reported as unreached while the player stood on it |
 | `never fired` | signals a `connections[]` entry listens to that never happened |
 | `declared and never read` | actions in the scene's `input{}` that NOTHING asked about, in any run — a key the control list promises and no code implements. Measured as a read, not a press, so the bot pressing it does not clear it. Two shipped starters had one: `tps-3d` declared `restart` (on `KeyR`, already the reload key) and `MISSION FAILED` was a dead end you left with F5. An action polled only on a screen no run reached lands here honestly — read it, do not gate on it |
-| `danger` | how many times the player's `Health` emitted `damaged` — and when that is ZERO, WHICH zero it is: a scene with no hazard wired at all is a walkabout and worth shouting about; a scene full of them that never landed one is a report about the BOT, which a real player would outrun less easily. Hazards are counted from the scene FILE, because a `Spawner` detaches its prefab at ready and a wave game's hazards are not in the tree yet. |
+| `danger` | how many times the player's `Health` emitted `damaged` — and when that is ZERO, WHICH zero it is. A scene with no `DamageOnContact` AND no player-side `Health` is a walkabout and worth shouting about; one with a Health but no hits says so WITHOUT claiming the scene is harmless, because damage that comes from a behaviour calling `Health.damage()` has no hazard node to count and this cannot see it; a scene full of hazards that never landed one is a report about the BOT, which a real player would outrun less easily. Hazards are counted from the scene FILE, because a `Spawner` detaches its prefab at ready and a wave game's hazards are not in the tree yet. **Put the player's `Health` under the player** — on it or on a child, the way `star-survivor` composes `/Game/Player/Vitals` — or none of this counts it: the oracle asks whether the damaged node is player-SIDE. |
 
 **The bot presses the HUD.** Every focusable widget a player can currently see —
 `UiButton`, `UiToggle`, `UiSelect`, `UiSlider` — gets pressed occasionally,

package/skills/incanto-save-slots.md

@@ -100,10 +100,19 @@ readable if you want it for something else.
 `deserialize` is defensive on purpose: that data may come from a build of your
 game that shipped six weeks ago. Check what you read.
 
-Built-ins that already save: `Collector` (total), `Currency` (amount),
-`DayNight` (hour, paused), `Health` (current, dead), `SavePoint` (playtime),
+Built-ins that already save: `Checkpoint` (which one was lit),
+`Collector` (total), `Currency` (amount), `DayNight` (hour, paused),
+`Health` (current, dead), `Phases` (which phase the fight reached),
+`SavePoint` (playtime, and the poses it `keep`s),
 `ScoreKeeper` (score, lives, won/lost), `WaveSpawner` (which wave).
 
+`Checkpoint` restores the `Respawn` redirect as well as its own `lit` flag, and
+when a run lit several it comes back to the one it reached LAST — the order they
+announce in does not decide where you land. Without that, a continued run's
+first fall went back to the level's START, past every checkpoint the session had
+reached, and the report was green because a behaviour with no `serialize` is not
+counted as saveable in the first place.
+
 `WaveSpawner` RESTARTS the wave you were on rather than resuming mid-spawn —
 spawned entities are never restored, so resuming "four enemies into wave 3"
 would resume a wave whose enemies do not exist. `waveStarted` fires again, so a
@@ -196,6 +205,24 @@ At runtime `engine.captureState()` logs the same thing per node.
 
 Never hand-craft a uid. Use `newUid()`.
 
+## The two-button version
+
+For a game whose save is "this scene, right now", `GameFlow` has the verbs and
+you write no TypeScript at all:
+
+```json
+{ "from": "/root/HUD/PauseMenu/Save",     "signal": "pressed", "to": "/root/Flow", "handler": "save" },
+{ "from": "/root/HUD/PauseMenu/Continue", "signal": "pressed", "to": "/root/Flow", "handler": "continueFrom" }
+```
+
+with `"script": { "name": "GameFlow", "props": { "saveSlots": "beacon-isle" } }`
+naming where the slots live. `save(slot)` writes `captureState()` under the
+scene's own name; `continueFrom(slot)` reloads the scene and restores AFTER
+`onReady`, which is the ordering everything below is about; `hasSave(slot)` is
+what a CONTINUE button asks before it offers itself. A slot written by ANOTHER
+scene is refused with a sentence — routing between levels is yours, and the rest
+of this page is how to do it. Composed in `examples/beacon-isle-3d`.
+
 ## Saving and loading
 
 ```ts
@@ -284,6 +311,38 @@ const game = await createGame2D({ canvas, scene });
 // then `restoreOnReady: true` on that scene's SavePoint, or call restore()
 ```
 
+## Where the player was standing: `keep`
+
+A save is behavior state keyed by uid and deliberately not a snapshot of the
+tree, so **mid-level positions do not come back**. That is right for a
+checkpoint save and wrong for a Continue: pressing it should put you on the
+street you quit on, not at the depot. The escape hatch was one sentence —
+"a game that wants a position saves it" — and every game wrote the same
+behaviour whose only job is to hold a transform.
+
+The scene says it instead:
+
+```json
+{ "name": "Save", "type": "Node3D", "uid": "n_…",
+  "script": { "name": "SavePoint",
+              "props": { "game": "longhaul", "slot": "1",
+                         "keep": ["/root/Courier", "/root/Van"] } } }
+```
+
+Each named node's `position` and `rotation` go into the slot alongside the
+playtime, and come back in `announce()` — after the whole restore pass, so a
+camera rig or a controller restoring on the same frame cannot overwrite them.
+
+- **Each kept node needs a `uid`**, the same join key as the rest of the save,
+  so a rename or a reparent survives. A path that names nothing, a node with no
+  uid, and a node with no position each say so through `engine.log` on the way
+  IN — at save time, when you can still fix it — rather than restoring quietly
+  to the wrong place months later.
+- A slot written before a node was added to `keep` restores everything else and
+  leaves that node where the scene file puts it.
+- It is a POSE, not physics: velocity is not kept, so a continued run starts at
+  rest. Save a velocity yourself if a game needs one.
+
 A `SavePoint` records `scene` as the scene's own `name` unless you set the prop,
 so `level2.scene.json` named `level2` needs no wiring at all. Set `scene`
 explicitly when one file is entered more than one way (`"chapter-2-rescue"`).

package/skills/incanto-scene-json-authoring.md

@@ -367,6 +367,19 @@ that do exist at the failing spot).
   registered (`registerBehavior`) before `loadScene` → `UNKNOWN_BEHAVIOR` otherwise.
 - Unresolvable `from`/`to` → `DANGLING_CONNECTION` at load. Renaming a node breaks its
   connections **loudly** — update paths in the same edit.
+- `args` calls the handler with THOSE values instead of whatever the signal
+  emitted — `Function.bind` for a wire:
+
+  ```json
+  { "signal": "phase2", "from": "Boss/Mood", "to": "HUD/Banner", "handler": "show",
+    "args": ["THE CINDERS CATCH", { "color": "#ffb454", "seconds": 1.6 }] }
+  ```
+
+  Without it, "when this happens, say that" needed a two-line behaviour whose
+  whole job was calling one method with one constant. Bound arguments REPLACE
+  the emitted ones — a wire that half-carried would be ambiguous, and the
+  emitted values are still one connection away (the same wire without `args`).
+  It must be a LIST: `"args": "ENRAGED"` is a load error.
 - `filter` gates firing on the first emitted argument: it must be a node in `filter.group`
   and/or match every `filter.tag` entry. **A filter's keys are `group` and `tag`, and a
   connection's are `[signal, from, to, handler, once, filter]`** — anything else is a load

package/skills/incanto-verifying-your-game.md

@@ -22,9 +22,17 @@ each answers a failure that used to look like nothing at all:
 | `assetErrors()` | a model/texture 404'd — the thing is simply not there | §6c |
 | `framing` | the camera is pointed the wrong way, or nothing is lit | §6a |
 
-A run that finishes is not a run that worked. `runScript()` fails the run when
-`stats().errors` is non-zero, and prints the engine's warnings under the
-failures — but `framing` and `assetErrors()` you have to ASK for.
+A run that finishes is not a run that worked. `runScript()` fails the run on
+BOTH halves of "the engine stayed alive": behaviours the loop quarantined after
+a throw (`stats().errors`), and anything the engine itself reported as an
+**error** — a sentence it wrote precisely because it chose to keep going. Each
+distinct one is a failure quoting what was said, deduped, so a per-frame
+complaint is one fault rather than six hundred. Measured on a boat whose
+`Buoyancy` hung on a plain `Node` instead of the hull: the engine said
+`needs a body it can push … it will never float` by name every frame, and the
+run used to report `ok: true` while the boat sank through the sea. Warnings are
+printed and do NOT fail; `framing` and `assetErrors()` you still have to ASK
+for.
 
 ## 0. The whole ladder, one command: `incanto-verify`
 
@@ -187,6 +195,42 @@ Script steps' `do:`/`assert:` callbacks receive the full RunContext —
 work inside runScript: `do: (ctx) => ctx.engine.input.setActionVector('move',
 chase(ctx), 0)`.
 
+**A sound can be asked where it came from.** `engine.audio.recent()` entries
+carry `pan`, `gain` and `distance` for spatial sounds, computed from the scene's
+camera when nothing has rendered — so a game whose mechanic is a noise in the
+dark is checkable (`examples/earshot-3d`).
+
+**A HUD widget can be asked where it is.** Every headless run arms the camera's
+projection (`engine.toScreen` / `toWorld`), so `UiWaypoint.screen()` answers
+instead of returning null — a marker that pins to the screen edge when its
+target is behind you is now something a harness can check.
+
+**A two-player game is driven by two hands.** The bot finds every
+`CharacterController2D`/`3D` in the scene and drives each one on the action set
+it declares (`moveAction`, `jumpAction`), so a couch co-op game gets both
+characters walking. It used to drive the first `vector2` action it found:
+measured on a two-player scene, player one walked 17.3 m and player two walked
+0.0 m, and the report said the game could never be won.
+
+**Watching every frame: `onFrame`.** Steps fire at named times, which is the
+wrong shape for anything continuous — the APEX of a jump, the CLOSEST a chaser
+ever got, whether a shell cleared the wall between two named moments:
+
+```ts
+let apex = 0;
+await runScript(scene, {
+  durationMs: 4000,
+  onFrame: (ctx) => {
+    apex = Math.max(apex, (ctx.getNode('Ball') as { position: number[] }).position[1] ?? 0);
+  },
+});
+```
+
+It runs after every simulated frame with the live context, and a throw inside it
+is a reported failure like a throw in a step. Before it existed every harness in
+this repo wrote the same workaround — one `do:` that stepped the engine by hand
+in a loop, which moves the clock out from under the script's own steps.
+
 **Reaching nodes & state from a step (the gotchas a sim hit):**
 - `ctx.getNode(path)` and `ctx.scene.root.getNode(path)` resolve from the ROOT.
   When the root node IS named `Game`, the root is `ctx.scene.root` (or
@@ -301,6 +345,16 @@ naming a path that resolves to nothing is a FAILURE, not a click into space.
 `geometricPicker(scene)` from `incanto/test` is the same thing on its own, for a
 harness that wants to ask "what is under this point" directly.
 
+**Click the THING, not one of its triangles.** Anything bigger than a cube is a
+grouping node with meshes under it and the behaviour on the group — so
+`click: 'Keep/Ballista'` aims at whatever that subtree DRAWS, and a click that
+lands on a different part of the same clickable is not a miss. Both of those
+used to be failures: the group answered `resolves to no node — nothing to point
+at` (a grouping node has no framing entry of its own), and naming a child was
+reported as a miss whenever the ray met its sibling first, while the click had
+already gone through the real `Clickable` and fired it. A click is wrong when it
+reaches a different HANDLER — a wall in the way still says so.
+
 **A `click` naming a HUD widget PRESSES it** — `click: 'Hud/Shop/Buy'` is the
 whole verb for a menu, a shop, a settings screen, an idle game or a card game.
 There is no cursor involved: a widget lives in the DOM overlay, not the world,
@@ -1034,6 +1088,35 @@ Rules that make it hold (the engine's own rules anyway): use `engine.rng`
 never Math.random, dt/`engine.time` never Date.now. Gamepads replay through
 the ACTIONS they were bound to, not raw pad state.
 
+### The same machinery is a REWIND
+
+Determinism means a rewind needs no snapshot: cut the tape, load the scene
+again, and re-run the ticks that are left. A crate that was mid-air comes back
+mid-air, because it is the same simulation and not a recording of where things
+were.
+
+```ts
+const tape = startRecording(game.engine);
+
+function takeBack(seconds: number): void {
+  const upTo = tape.rewind(tape.take().ticks.length - Math.round(seconds * 60));
+  game.engine.setScene(loadScene(structuredClone(sceneJson), { engine: game.engine }));
+  replay(game.engine, upTo);          // …and the tape keeps recording from the cut
+}
+```
+
+- `tape.take()` reads the recording WITHOUT ending it — `stop()` detaches the
+  taps, so reading used to mean stopping, and the next recording's tick indices
+  restarted at zero.
+- `tape.rewind(n)` drops everything after tick `n`, returns the tape up to it,
+  and keeps recording from there — so a game can rewind, play on, and rewind
+  again.
+- `replay(engine, recording, { until })` stops where you say, for a scrub or a
+  mid-run assertion.
+
+Measured in `examples/back-3d`: a 150-tick prefix replayed into a freshly
+loaded scene reproduces both crates and the walker to the millimetre.
+
 
 ## Sound: did the right thing sound?
 

package/templates-app/beacon-isle-3d/PROJECT/Status.md

@@ -44,3 +44,15 @@ and `Walker` (CharacterBody3D + `Chase` on a child, `slopeLimitDeg 50`, `stepHei
 the west slope, `loseRange 25` so it never joins the quest. `verify.ts` measures the rebound
 (2.4 m of 3), the chase up the slope (8.5 m of 10, +1.75 m) and that the walker stays on the
 terrain (0.97 m over `heightAt`).
+
+## Pausing, saving, continuing
+
+ESC pauses and shows the pause menu; SAVE writes the run into a slot and
+CONTINUE reloads the isle and hands every behaviour its state back — both are
+`GameFlow` handlers (`save`, `continueFrom`) wired from buttons, so there is no
+save code in this game at all.
+
+ESC pauses and shows the pause menu; OPTIONS opens the settings over it and
+BACK returns to the menu that asked. All of it is `GameFlow` (`pausePanelPath`,
+`screen(path)`, `back()`) wired with `connections` — there is no TypeScript for
+any screen in this game.

package/templates-app/beacon-isle-3d/package.json

@@ -14,7 +14,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.74.0",
+    "incanto": "^0.76.0",
     "three": "^0.184.0"
   },
   "devDependencies": {