npm - incanto - Versions diffs - 0.70.0 → 0.71.0 - Mend

incanto 0.70.0 → 0.71.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (67) hide show

package/bin/incanto-verify.mjs +36 -98
package/dist/2d.d.ts +18 -3
package/dist/2d.js +3 -3
package/dist/3d.d.ts +3 -3
package/dist/3d.js +6 -6
package/dist/{agent8-CmNF01gA.js → agent8-Cfmd3ar_.js} +1 -1
package/dist/{audio-player-DaMxqfNE.d.ts → audio-player-L8yccdMP.d.ts} +1 -1
package/dist/{behavior-DZExDn9o.d.ts → behavior-Dcz0fr1S.d.ts} +11 -0
package/dist/{create-game-Bwvh6q8A.js → create-game-CH4kt78v.js} +7 -7
package/dist/{create-game-C7ffQWW7.js → create-game-LCHBLfA4.js} +7 -7
package/dist/debug.d.ts +1 -1
package/dist/editor.js +29 -25
package/dist/{environment-presets-D6Q5BxeE.js → environment-presets-99BzP_L-.js} +3 -3
package/dist/{frame-report-Dlq13Gyj.js → frame-report-D-_7YF2G.js} +1 -1
package/dist/{gameplay-BfHkuzVb.js → gameplay-CNULJvwh.js} +108 -6
package/dist/gameplay.d.ts +68 -4
package/dist/gameplay.js +2 -2
package/dist/index.d.ts +27 -4
package/dist/index.js +4 -4
package/dist/{loader-Cff09LMm.d.ts → loader-8-IHvbKD.d.ts} +1 -1
package/dist/net.d.ts +2 -2
package/dist/net.js +2 -2
package/dist/{physics-2d-CE0Qvy3V.js → physics-2d-FhrXUc6B.js} +2 -2
package/dist/{physics-3d-CpH-2gn5.js → physics-3d-CFEGxBXZ.js} +3 -3
package/dist/{picking-CQJ_PJKh.js → picking-DVo7fI13.js} +3 -3
package/dist/react.d.ts +1 -1
package/dist/react.js +1 -1
package/dist/{register-Bkk0wSDB.js → register-BYQCBySi.js} +100 -8
package/dist/{register-6DYnKZcy.js → register-DuVdzxbq.js} +49 -15
package/dist/{replay-DjAkAzMq.js → replay-DEvp3kyV.js} +2 -2
package/dist/{replay-Dmw-PKQu.d.ts → replay-F7IZHdFR.d.ts} +1 -1
package/dist/{save-slots-BXVg148r.js → save-slots-Bvuh2p_r.js} +56 -3
package/dist/{split-screen--k-XpBjr.d.ts → split-screen-CIYf1zSf.d.ts} +2 -2
package/dist/{split-screen-PL78oVXP.js → split-screen-eULetcg-.js} +3 -3
package/dist/{src-Cxfiv1Hg.js → src-_jk0qLsS.js} +1 -1
package/dist/{test-iHYVUcDK.js → test-CmN54kWv.js} +252 -24
package/dist/test.d.ts +113 -5
package/dist/test.js +3 -3
package/dist/vite.js +3 -3
package/editor/assets/{agent8-D0MS174y.js → agent8-yLIEYHbd.js} +1 -1
package/editor/assets/{debug-BnXkKuYu.js → debug-u31w_yhq.js} +1 -1
package/editor/assets/{index-CIu3uc3l.js → index-DK9xMGpW.js} +94 -94
package/editor/index.html +1 -1
package/package.json +1 -1
package/schemas/scene.schema.json +4 -0
package/skills/incanto-behaviors-and-scripts.md +30 -9
package/skills/incanto-building-2d-games.md +20 -2
package/skills/incanto-gameplay-behaviors.md +63 -1
package/skills/incanto-hud.md +14 -0
package/skills/incanto-node-reference.md +18 -2
package/skills/incanto-playtesting.md +34 -0
package/skills/incanto-save-slots.md +56 -1
package/skills/incanto-verifying-your-game.md +11 -0
package/templates-app/beacon-isle-3d/package.json +1 -1
package/templates-app/beacon-isle-3d/src/game.scene.json +44 -226
package/templates-app/molehill-2d/package.json +1 -1
package/templates-app/molehill-2d/src/game.scene.json +10 -60
package/templates-app/platformer-2d/package.json +1 -1
package/templates-app/platformer-2d/src/game.scene.json +80 -416
package/templates-app/star-survivor/package.json +1 -1
package/templates-app/star-survivor/src/game.scene.json +5 -24
package/templates-app/tps-3d/package.json +1 -1
package/templates-app/tps-3d/src/game.scene.json +13 -71
package/templates-app/village-quest-3d/package.json +1 -1
package/templates-app/village-quest-3d/src/behaviors.ts +21 -4
package/templates-app/village-quest-3d/src/grove.scene.json +16 -87
package/templates-app/village-quest-3d/src/village.scene.json +5 -27

package/editor/index.html CHANGED Viewed

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Incanto Scene Editor</title>
     <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'><rect width='16' height='16' rx='3' fill='%236ee7dc'/><text x='8' y='12' text-anchor='middle' font-size='11' font-family='monospace' fill='%230e1018'>i</text></svg>" />
-    <script type="module" crossorigin src="./assets/index-CIu3uc3l.js"></script>
+    <script type="module" crossorigin src="./assets/index-DK9xMGpW.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/GameServer-C56iOUgF.js">
   </head>
   <body>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "incanto",
-  "version": "0.70.0",
+  "version": "0.71.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",

package/schemas/scene.schema.json CHANGED Viewed

@@ -6757,6 +6757,10 @@
               "type": "object",
               "default": {}
             },
+            "colors": {
+              "type": "object",
+              "default": {}
+            },
             "solid": {
               "type": "array",
               "default": []

package/skills/incanto-behaviors-and-scripts.md CHANGED Viewed

@@ -177,7 +177,7 @@ What behavior code actually calls at runtime — all instance methods, no global
 | `engine.stop()` / `engine.start()` | pause / resume the loop — stop resets the clock and accumulator, so no banked sim time leaks into the resume |
 | `engine.step()` | advance exactly ONE fixed step + one update (both dt = the fixed step) — the unit of time for headless tests |
 | `engine.tick(timestampMs)` | manual frame advance — takes an **absolute** ms timestamp (rAF-style), NOT a dt; the first call after (re)start only primes the clock |
-| `engine.setScene(scene)` | swap scenes: the previous root is freed, the input map is cleared and redeclared from the new scene's `input{}`, the clock resets (`time`, `unscaledTime`, and **`timeScale` back to 1** — a level restarted out of a frozen game-over must not boot frozen), then `sceneChanged` fires |
+| `engine.setScene(scene)` | swap scenes: the previous root is freed, the input map is cleared and redeclared from the new scene's `input{}`, the clock resets (`time`, `unscaledTime`, and **`timeScale` back to 1** — a level restarted out of a frozen game-over must not boot frozen), then `sceneChanged` fires. It fires with **null** at `dispose()` too — a handler that reads `scene.root` has to check, or teardown says so and continues without it |
 | `node.off(signal, fn)` | disconnect ONE listener you connected with `on` — pass the same function reference. (`free()` disconnects everything a node owns, so this is for a listener that must stop while the node lives on) |
 | `node.signal('died')` | the `Signal` object itself, for `connect`/`disconnect` by hand; undeclared names throw, like `emit` |
 | `node.listenerCount('died')` | how many are listening — a test's way to prove a wire was made, or dropped |
@@ -187,19 +187,40 @@ The recurring traps: `duplicateNode` does NOT insert the clone anywhere — a
 "spawner that does nothing" usually forgot `addChild`.
 **The template you clone FROM is a live node.** Its behaviors run, its timers
-tick, its turret shoots — `visible: false` hides a node, it does not switch it
-off. `Spawner` and `WaveSpawner` sidestep this by DETACHING their `prefab` at
-ready; a shelf of templates you clone yourself is still in the tree, so author
-their scripts `"enabled": false` and wake the clone:
+tick, its turret shoots, its `autoplay` audio plays — `visible: false` hides a
+node, it does not switch it off. `Spawner` and `WaveSpawner` sidestep this by
+DETACHING their `prefab` at enter. For a shelf of templates you clone yourself,
+put `PrefabShelf` on the shelf node and it does the same for all of them:
+```json
+{ "name": "Prefabs", "type": "Node2D", "script": { "name": "PrefabShelf" },
+  "children": [ { "name": "Tower", "type": "Node2D", "children": [] } ] }
+```
 ```ts
-const tower = duplicateNode(this.node.getNode('/Game/Prefabs/Tower'));
-tower.behavior?.enable();          // the template stays asleep, this one works
+const shelf = this.node.getNode('/Game/Prefabs').behavior as PrefabShelf;
+const tower = shelf.make('Tower');    // detached, awake all the way down
+tower.position = at;                  // set it up BEFORE it readies
 this.node.getNode('/Game/Towers').addChild(tower);
 ```
-Without it an invisible tower at the origin defends your map, and the game looks
-fine. **And look the template up by PATH, not `%Name`**: a clone keeps its
+Its children never ENTER the tree, so nothing has to be hidden and nothing has
+to be asleep. `make()` returns the clone DETACHED, like `duplicateNode` — not a
+formality: `onReady` fires on attach, and a behavior that banks its node's
+position there (`FloatAway`) would bank the wrong one. `names()` lists what the
+shelf holds, and asking for anything else fails saying so.
+**Why not just author the templates `"enabled": false`?** That was the old
+advice and it half-works: `enabled` is a per-behavior pause switch, so
+`clone.behavior?.enable()` wakes ONE node — while the shape this same skill
+teaches (one behavior per node, so a prefab's parts live on children) leaves
+every child asleep, silently and for good. Measured on a shipped tower defense:
+the bolt's root `Projectile` was woken and its sibling `Lifetime` was not, so
+every bolt that MISSED flew forever — five still in the tree at 69 seconds. And
+`enabled` never silenced the template's `autoplay` audio at all, which is how
+that game's `feels` rung read `every one of the 4 emitters fired` while two of
+the four were templates going off on the shelf. `enabled: false` is for a state
+a node deliberately starts in (a `Chase` waiting on `spotted`), not for hiding a
+template from the tree. **And look the template up by PATH, not `%Name`**: a clone keeps its
 template's name, so `%Tower` is unambiguous exactly until the first one is
 placed, and then it throws `DUPLICATE_UNIQUE_NAME` from inside your build
 handler — a game that works once. `engine.tick(16)` does

package/skills/incanto-building-2d-games.md CHANGED Viewed

@@ -105,8 +105,26 @@ stop hand-placing dozens of ColorRect walls:
 - Cell (0,0) hangs its TOP-LEFT on the node's origin; position the node to
   place the level. `columns: 0` (default) derives atlas columns from the
   texture width.
-- No texture yet? Colliders still work — pair with ColorRect2D placeholders or
-  just leave it invisible while you block out the level.
+- **No art yet? Paint with `colors`.** A char → `#rrggbb` map draws that cell as
+  a flat quad, in the same single draw call, with no atlas at all:
+  ```jsonc
+  { "name": "Walls", "type": "TileMap2D", "props": {
+      "tileSize": 56,
+      "cells": ["########", "#......#", "########"],
+      "colors": { "#": "#3a4356" },
+      "solid": ["#"]
+  } }
+  ```
+  Exclusive with `texture` (one material, one draw call — a half-textured level
+  that loads clean is exactly the silence this engine fails loudly about), and
+  `solid` takes the CHAR you painted as well as an atlas index, because that is
+  the thing an author knows. Everything else is unchanged: `cellAt`, `tileAt`,
+  `setTile`, `worldAt` and the merged colliders work the same. It exists because
+  a sokoban built from the published package came out as 24 hand-placed
+  `ColorRect2D` walls — the one node that answers every question a grid game
+  asks could not be SEEN.
 - Change the map at runtime by REPLACING `cells` (mutations are not watched):
   `map.cells = [...rows]` — geometry and colliders rebuild next frame. For ONE
   cell use `setTile` below, which does that correctly.

package/skills/incanto-gameplay-behaviors.md CHANGED Viewed

@@ -803,6 +803,44 @@ a `draft` that puts the waterline on it:
 For the water's own height anywhere (jetties, spawn heights, an AI deciding
 where the shore is), `Water3D.heightAt(x, z)` answers the same surface.
+## PrefabShelf
+The shelf of templates the GAME clones itself — a tower the player places, a
+bolt that tower fires, the `+14` a kill pays. `Spawner` owns its one prefab and
+detaches it; this owns a whole shelf of them and detaches all of them.
+```json
+{ "name": "Prefabs", "type": "Node2D", "script": { "name": "PrefabShelf" },
+  "children": [
+    { "name": "Tower", "type": "Node2D", "children": [] },
+    { "name": "Bolt", "type": "Node2D", "children": [] }
+  ] }
+```
+```ts
+const shelf = this.node.getNode('/Game/Prefabs').behavior as PrefabShelf;
+const tower = shelf.make('Tower');    // detached, awake all the way down
+tower.position = at;                  // set it up BEFORE it readies
+this.node.getNode('/Game/Towers').addChild(tower);
+```
+| Prop | Default | Meaning |
+|---|---|---|
+| `prefabs` | `""` | comma-separated child names to take; empty takes them ALL |
+Methods: `make(name)` · `names()`
+- **Its children never enter the tree.** Claimed in `onEnterTree` (parent-first,
+  so a template carrying its own shelf is taken intact), so nothing has to be
+  `visible: false` and nothing has to be `"enabled": false`. A template left in
+  the tree is a live node: its behaviors tick, and its `autoplay` audio plays.
+- **`make()` returns the clone DETACHED**, like `duplicateNode` — `onReady`
+  fires on attach, and a behavior that banks its node's position there
+  (`FloatAway`) would bank the wrong one. Set it up, then `addChild`.
+- **A clone is reported as the template it came from.** `wiringPath()` answers
+  with the authored address wherever the clone lands, so a hundred towers are
+  one emitter in the audio/effects logs and in the `feels` rung — the promise
+  those logs already made for a spawner's waves, now true for a shelf too.
 ## Spawner
 Drip-feed clones of a TEMPLATE into the scene on a timer — enemy generators,
@@ -854,7 +892,17 @@ also frees timed spawns.
 | `waves` | `[]` | array of `{ prefab, count, interval, delayBefore }` (required) |
 | `autoStart` | `true` | begin the first wave at ready |
-Signals: `waveStarted(index)` · `waveCleared(index)` · `allCleared`
+Signals: `spawned(node)` · `waveStarted(index)` · `waveCleared(index)` ·
+`allCleared`
+`spawned` hands you the clone itself, before it has been stepped — the route to
+anything PER-ENEMY that the template cannot say: a difficulty setting that
+raises health, an elite that gets a tint, a list your own code keeps, a target
+handed over on arrival.
+```json
+{ "signal": "spawned", "from": "Waves", "to": "Game", "handler": "onRaider" }
+```
 ```json
 { "name": "Waves", "type": "Node2D",
@@ -1290,6 +1338,20 @@ 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.
+**The line after a swap runs in a node that no longer exists.** `goToScene` and
+`setScene` FREE the tree they replace, and `this.engine` is
+`this.node.tree.engine` — so a Continue button that swaps and then talks to what
+arrived throws on its second line. Hold the engine first:
+```ts
+const engine = this.engine;                     // BEFORE the swap
+goToScene(engine, villageJson, { fadeSeconds: 0 });
+(engine.scene?.root.behavior as Hold).continueGame();
+```
+The engine says so by name (`has been FREED — a scene swap frees the tree it
+replaces`), and `node.freed` answers the same question in code.
 ## DayNight (live 24-hour cycle)
 Drives the scene `environment` (needs an atmosphere sky): sun elevation/

package/skills/incanto-hud.md CHANGED Viewed

@@ -259,6 +259,20 @@ widget use `UiButton`'s `pressed`.
 Setting `.value` from a behavior updates the control and does **NOT** re-emit
 `changed` — restoring a saved setting must not fire the handler that saved it.
+**`choose(value)` is the other half**: set it as a PERSON would, and say so.
+`UiButton` has always had `press()`; the value widgets had nothing, so a preset
+button, a "reset to defaults", a tutorial that moves a slider for you, or a
+harness checking its own options screen had no public route at all.
+```ts
+(hud.getNode('%Volume') as UiSlider).choose(0.25);      // clamped, emits changed
+(hud.getNode('%Invert') as UiToggle).choose(true);
+(hud.getNode('%Quality') as UiSelect).choose('high');   // an option it does not
+                                                        // offer is refused
+```
+Both are silent when nothing changes.
 **Every prop is live.** `color`, `size`, `width`, `background`, `label` and
 `anchor` are re-read each frame, so flashing the score red, growing a health bar
 or moving a widget to another corner all work from a behavior — and from the

package/skills/incanto-node-reference.md CHANGED Viewed

@@ -656,7 +656,7 @@ _No props (structural fields only)._
 Methods: `addChild(child)` · `removeChild(child)` · `reparent(newParent)` · `findChild(name, recursive?)` · `getRoot()` · `getNodeByUid(uid)` · `getNodesByName(name)` · `getPath()` · `wiringPath()` · `getNode(path)` · `getNodeOrNull(path)` · `addToGroup(group)` · `removeFromGroup(group)` · `isInGroup(group)` · `declareSignal(name)` · `declaredSignalNames()` · `signal(name)` · `on(signal, fn, opts?)` · `off(signal, fn)` · `listenerCount(signal)` · `emit(signal, ...args)` · `queueFree()` · `free()`
-Reads: `uid: string | null` · `name: string` · `parent: Node | null` · `children: readonly Node[]` · `groups: ReadonlySet<string>` · `tree: SceneTree | null` · `isReady: boolean`
+Reads: `uid: string | null` · `name: string` · `parent: Node | null` · `children: readonly Node[]` · `groups: ReadonlySet<string>` · `tree: SceneTree | null` · `isReady: boolean` · `freed: boolean`
 ## `Node2D` — `incanto/2d`
@@ -1009,6 +1009,7 @@ Methods: `heightAt(x, z)` · `resolvedLayers()` · `free()`
 | `columns` | `0` | number |
 | `cells` | `[]` | array |
 | `legend` | `{}` | object |
+| `colors` | `{}` | object |
 | `solid` | `[]` | array |
 | `opacity` | `1` | number |
@@ -1295,6 +1296,8 @@ Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `change
 Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `changed`
+Methods: `choose(value)`
 ## `UiSlider` — `incanto`
 | Prop | Default | Kind |
@@ -1314,6 +1317,8 @@ Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `change
 Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `changed`
+Methods: `choose(value)`
 ## `UiText` — `incanto`
 | Prop | Default | Kind |
@@ -1349,6 +1354,8 @@ Reads: `shown: string`
 Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `changed`
+Methods: `choose(value)`
 ## `UiVolumeSlider` — `incanto`
 | Prop | Default | Kind |
@@ -1712,6 +1719,15 @@ Signals: `reachedPoint(index)`
 Signals: `collected(value, other)`
+### `PrefabShelf`
+| Prop | Default | Kind |
+|---|---|---|
+| `enabled` | `true` | boolean |
+| `prefabs` | `""` | string |
+Methods: `names()` · `make(name)`
 ### `Projectile`
 | Prop | Default | Kind |
@@ -1789,7 +1805,7 @@ Reads: `liveCount: number`
 | `waves` | `[]` | array · **required** |
 | `autoStart` | `true` | boolean |
-Signals: `waveStarted(index)` · `waveCleared(index)` · `allCleared`
+Signals: `spawned(node)` · `waveStarted(index)` · `waveCleared(index)` · `allCleared`
 Methods: `start()`

package/skills/incanto-playtesting.md CHANGED Viewed

@@ -42,6 +42,24 @@ find a door, not enough to solve a puzzle.
 No renderer is involved, so twenty minutes of simulated play takes a second or
 two.
+**Two buttons it will stop pressing.** The bot drives every declared button
+action, then notices what a player would notice. If pressing one STOPS THE
+CLOCK, that is a pause menu, and a run spent inside one measures nothing — it
+lets go and never presses that button again. If pressing one replaces the scene
+with THAT SAME SCENE, that is a restart, and it does not just waste the run, it
+ends it: the bot is bound to the tree it started in. One run of the set pays for
+that lesson and the rest play the game. Both are reported (`the bot stopped
+pressing …`), both are OBSERVED rather than read off the words "pause" and
+"restart" — your game may call them anything, or nothing — and neither is a
+defect in your game.
+The second one matters more than it sounds: mid-run retry is ordinary in puzzle,
+racing and tower-defense games, and `GameFlow` restarts only from a terminal
+state, so the games that reload mid-play are the ones that call `restartScene`
+themselves. Every one of them used to report `8 runs played without reaching a
+win (8 changed scene)` — and each run died a second in, which took the emitters,
+the hazards and the destinations down with it.
 ## What it reports, and where each answer comes from
 | line | source |
@@ -138,6 +156,22 @@ lifted out of the tree at load, so the check reads the scene FILE as well as the
 loaded tree, and a wave of forty enemies is reported as its one authored
 emitter, not forty.
+**`made and still held`** counts the clones alive when the run ended, grouped by
+the TEMPLATE they came from, with what the count was at the halfway mark:
+```
+· made and still held: 12 × /Game/Prefabs/Bolt (3 at halfway),
+                        6 × /Game/Prefabs/Tower (3 at halfway)
+```
+Six towers from three is a player who kept building; twelve projectiles from
+three is a projectile that never learned to stop. **Furniture holds steady; a
+leak climbs** — and nothing in the engine can tell them apart, so both are
+printed and the judgement is yours. It exists because a shipped tower defense
+kept every bolt that MISSED alive forever (its `Lifetime` was asleep on the
+prefab shelf) and no instrument said a word: the playtest was green, the audit
+was green, the harness was green, every rung of the ladder was green.
 **`nothing here can hurt you`** is a design report, not an error. Sometimes it
 is exactly right (a walking simulator). Usually it means the hazards are not
 wired up.

package/skills/incanto-save-slots.md CHANGED Viewed

@@ -292,6 +292,49 @@ explicitly when one file is entered more than one way (`"chapter-2-rescue"`).
 physics registers the new bodies before that scene's first frame — so a
 character walks in level two exactly as it did in level one.
+## State that outlives a SCENE, not just a session
+A save and a scene swap are different mechanisms and the word "persist" covers
+both, so this is the one thing a two-scene quest game has to be told: **the
+three hooks above carry state across a SAVE and nothing across a SWAP.**
+`goToScene` replaces the tree. The new scene's behaviors are new objects with
+`onReady` starting values — a quest flag set in the village is gone when the
+cellar loads, and nothing reports it, because nothing went wrong.
+A quest that has to survive both is three parts, and each one alone fails
+differently. Measured on a two-scene game built for this:
+| | swap | save |
+| --- | --- | --- |
+| a module object in YOUR code | ✅ crosses | ❌ `captureState()` cannot see it — `restored: 0`, and the report is clean |
+| `serialize`/`deserialize` alone | ❌ the new scene's behavior starts fresh | ✅ `restored: 1` |
+| …plus `announce()` | — | the HUD, which otherwise reads the old value over restored state |
+So: keep the truth in a module object, and give ONE behavior that exists in
+every scene the job of writing it in and out.
+```ts
+/** Not engine state — YOUR game's, and a module is where a swap cannot reach. */
+export const quest = { accepted: false, carrying: false, done: false };
+export class Hold extends Behavior {
+  static signals = ['questChanged'];
+  override serialize() { return { ...quest }; }
+  override deserialize(d: JsonValue) { Object.assign(quest, d as object); }
+  override announce() { this.emit('questChanged', quest.stage); }  // the screen
+}
+```
+**Give that node the same `uid` in every scene it appears in.** The save is keyed
+by uid, so `village.scene.json` and `cellar.scene.json` sharing one uid on their
+root is what lets a save taken in either one restore into either one. Generate it
+once with `newUid()` and paste it into both files — this is the single case where
+one uid legitimately appears in two scenes, because it is one thing.
+`behaviorsWithoutSave()` finds the behavior you forgot: on the game above it
+named `/Village (Hold)` first, out of 46% of the scripted nodes it lists.
 ## A title screen, in JSON
 A `SavePoint` can ASK without loading. `probeOnReady` fires on the first frame
@@ -318,7 +361,19 @@ The label leads because that is what a menu shows; an unlabelled slot falls back
 to its scene key, so the line is never blank.
 **The button's press is still yours**, and rightly: `pressed → your router`. See
-the three lines above.
+the three lines above. `examples/lanternhold-2d` ships this exact menu — a fresh
+install with no Continue, and a returning player whose slot line reads what the
+game SAVED (`last saved: Village` — the SavePoint's own label, not something the
+title screen guessed).
+Two things that cost a run each to learn there:
+- **A hand-written slot with `state: {}` restores nothing.** The engine says so
+  — `restored 0 of 2 saveable behaviour(s)` — but a menu built on one looks
+  perfectly green. Write the slot the way the game writes it.
+- **Hold the engine before you route.** `goToScene` frees the tree the button
+  lives in, so `this.engine` on the next line throws. See "Game flow" in
+  `incanto-gameplay-behaviors.md`.
 ## Several slots

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

@@ -685,6 +685,17 @@ then land on a game that never advances: the capture comes back UNCHANGED and
 looks perfectly healthy. `drove 0 frames` is refused with an error rather than
 handed over as a picture.
+**A PLAIN capture works on a hidden page.** Only a DRIVE needs the window in
+front. `captureFrame` waits ~120 ms for the game loop and then draws a frame
+itself, exactly because a hidden tab gets none — so the pixels are current, the
+world is simply paused. Measured, hiding every node from the console and
+capturing again: 2D `luminance 0.09 → 0.00 BLACK SCREEN`, 3D `0.64 → 0.96,
+subject 44.3% → 22.0%`.
+That is the whole point for an agent: **your terminal is in front and the game
+is behind it, and `draws` still answers.** The report says the world is paused,
+and the `draws` rung carries that as a note under a pass.
 #### Look at it
 ```

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

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