incanto 0.69.0 → 0.71.0

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

@@ -34,7 +34,7 @@ $ bunx incanto verify                       # finds your scene AND your behaviou
 ✓ loads — the scene is legal and its assets resolve
     ! /Game/Chest: script Chest — target '%Ke' matches nothing
 ? plays — 8 runs played without reaching a win (4 lost, 4 ran out the clock)
-✓ feels — 5 of 7 fired — silent: /Game/Boss/Roar, /Game/Boss/Boom
+? feels — 5 of 7 fired — silent: /Game/Boss/Roar, /Game/Boss/Boom
 · agrees — not run — this scene has no `multiplayer` header
 ? draws — the dev server is running on :5173, but no page answered
 
@@ -106,8 +106,17 @@ and a run without `--behaviors` reports that instead: neither is a broken game.
 `feels` is the sound-and-effects rung: it lists what the scene DECLARES against
 what actually fired during the playtest. A game whose feedback is wired but
 never triggered plays perfectly and feels dead, and every other rung calls it
-healthy. Nothing firing at all is a failure; some nodes staying silent is
-reported by name, because the bot may simply never have reached the boss.
+healthy. Nothing firing at all is a FAILURE. Some nodes staying silent is
+`unmeasured` (`?`) with the names listed — a silent emitter is either a broken
+wire or a moment random play never reached, and the two look identical from
+here. Reach it in a scripted run and this rung can tell you which. It ticks
+(`✓`) only when every declared emitter fired.
+
+`says` reads the running page's own log. Errors and failed assets fail it;
+WARNINGS are carried under it with a `!` and it still passes — a camera whose
+`follow` points at a node with no position, a `DayNight` with no sky to move, a
+body with no collider. Those leave a game running and wrong, and they are the
+lines worth reading before anything else on this list.
 
 Exit 1 only when a rung actually failed. `--behaviors src/behaviors.ts` matters:
 without it your game logic is stubbed and only the structure is played.
@@ -221,6 +230,22 @@ console.log(result.describe());        // run report + final scene, one line per
 if (!result.ok) process.exit(1);       // failures carry atMs + label + message
 ```
 
+**An assert fails on `false`, on a non-empty STRING, or on a throw.** The
+string is used as the message, which is how a harness explains itself:
+
+```ts
+assert: (ctx) => {
+  const lives = (ctx.getNode('Score').behavior as never as { lives: number }).lives;
+  if (lives <= 0) return `the keep fell — ${lives} lives`;   // the failure, in words
+  return null;                                               // nothing to say
+}
+```
+
+`true`, `null`, `undefined` and `''` are passes. Anything else — a number, an
+object — is recorded as a failure naming the contract, because a check that
+cannot fail is not a check. (It used to read only `false` and a throw, so every
+assert in the shape above passed by not being `false`.)
+
 Run it with `bunx tsx verify.ts` (or inside a vitest test). Physics enables
 automatically from the scene's `dimension`. `result.snapshots` holds periodic
 captures; `result.logs` holds everything behaviors logged via `this.log`.
@@ -232,6 +257,84 @@ into the process-global registries (hot-replacing same names). In a test
 suite, isolate with `clearRegistry()`/`clearBehaviors()` between files if
 you register conflicting classes.
 
+### Clicking, for a game the mouse plays
+
+`press`/`release`/`vector`/`key` are all ACTIONS, and `Clickable` reads the mouse
+BUTTON — so a match-3, a tower defense, a card game, a point-and-click, an RTS or
+a flip puzzle needs one more verb:
+
+```ts
+steps: [
+  { atMs: 100, click: 'Board/Tile3' },   // by node path — the usual way
+  { atMs: 400, click: [300, 100] },      // or a raw point, in the scene's units
+]
+```
+
+A click is a press and a release on two DIFFERENT frames — `clicked` fires on
+release over the node the press started on — and that is handled for you. So is
+the picker: headless there is no renderer and therefore no raycast, so a
+**geometric** one is installed for the run, answering from the same world boxes
+`framing()` measures. A game that installs a picker of its own keeps it — its
+answer always wins.
+
+2D coordinates are world pixels (the space every 2D `position` in the file is
+already written in); 3D casts a ray from the scene's current camera. A `click`
+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.
+
+**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,
+so the click goes to what a MOUSE does to that widget — a button presses, a
+toggle flips, a select advances, and a `UiDialogue` ADVANCES THE LINE without
+answering a waiting choice, exactly as clicking the box does in a browser
+(`advance()` refuses to skip choices). To answer one, do what a player does and
+press the choice, or call `talk.choose(i)` from a `do:` step. Enter and the
+pad's A are a different verb and DO answer.
+A widget that is hidden — or that sits under a hidden `UiPanel` or a hidden
+`HudLayer` — is a FAILURE naming it, because a player could not have pressed it
+either.
+
+**A drag needs the two edges apart**, and `click` puts them at one point:
+
+```ts
+steps: [
+  { atMs: 100, at: [400, 300], mouse: 'down' },   // press, here
+  { atMs: 200, at: [300, 380] },                  // and move while held
+  { atMs: 300, mouse: 'up' },                     // let go, there
+]
+```
+
+`at` on its own is a HOVER — the state a game shows for a cursor that has not
+clicked yet. `button` picks a different one (0 left · 1 middle · 2 right) for
+`mouse` and for `click` alike. Written with `click`, a drag-and-launch game
+launches with a vector of `from - to` where both are the same point: **it fires
+every shot and every shot goes nowhere**, and the run reports fine.
+
+The aiming side is on the engine, not the renderer: a behaviour reads
+`this.engine.pointerWorld()` (and `toWorld`/`toScreen`), and a `click` or `at`
+step installs a geometric one for the run alongside the picker.
+
+### Asking the game a question
+
+An assert needs to READ something, and the readable thing is often neither a
+prop nor a method. Every node type's **`Reads:`** line in
+`incanto-node-reference.md` lists its read-only accessors — the ones that exist
+for exactly this:
+
+```ts
+(ctx.getNode('Hud/Banner') as never as { showing: string }).showing   // '' when idle
+(ctx.getNode('Talk') as never as { active: boolean }).active          // mid-dialogue?
+(ctx.getNode('Gun').behavior as never as { liveCount: number }).liveCount
+(ctx.getNode('Player').behavior as never as { isDead: boolean }).isDead
+```
+
+`banner.text` does not exist and reads as `undefined`, which an assert will
+happily compare against and pass. Look the accessor up rather than guessing a
+prop name.
+
 ## 4. Read the scene like a screenshot
 
 ```ts
@@ -300,19 +403,27 @@ from geometry alone — no renderer, no canvas, no browser:
 
 ```
 > framing
-camera /World/Player/Cam at [0, 2, 8] looking [0, -0.2, -0.97] fov 60
+camera /World/Player/Cam at [0, 2, 8] looking [0, -0.2, -0.97] up [0, 1, 0] fov 60
 lit by: /World/Sun (DirectionalLight3D), environment.sky
-3 on screen, 1 off screen, 2 behind the camera
+3 on screen, 1 off screen, 2 behind the camera, 1 hidden (visible: false)
   onScreen  /World/Island (MeshInstance3D) [0, 0, 0] screen [0.02, -0.11] 8.2m
   behind    /World/Chest (ModelInstance3D) [0, 0, 40] 32m
   offscreen /World/Gem (MeshInstance3D) [80, 0, 0] screen [4.4, 0] 80.1m
+  hidden    /World/Boss (ModelInstance3D) [0, 0, -12] 20.1m
   overlap   /World/Platform ∩ /World/Gem
 ```
 
-Read it for the three visual failures that look identical from a node list:
+Read it for the five visual failures that look identical from a node list:
 
 - **`behind`** — the thing is fine, the camera has its back to it. Indistinguishable
   from "my model did not load" until you can see this line.
+- **`hidden`** — `visible: false` on the node or on any ancestor. The renderer skips
+  the whole subtree, so it is NOT in view; a screen drawing nothing used to report
+  every one of them as in view. `NOTHING IS DRAWN` when that is all of them.
+- **`up`** — which way is up on screen. Roll changes NOTHING else, so a camera rolled
+  180° prints the same `at` and the same `looking` as an upright one; the report
+  says `is UPSIDE DOWN` when `up.y` goes negative (a top-down camera measures
+  `up.y = 0` and is left alone).
 - **`lit by: NOTHING`** — the scene renders black. No error, no log, nothing wrong
   with any node.
 - **`overlap`** — two declared colliders intersect: the gem is inside the platform.
@@ -322,6 +433,13 @@ Also `incanto-play`'s `framing` command, and `describeFraming(scene)` /
 as on screen when its `size` box (or collider) is, not only its origin — so a
 200 m island whose origin sits off to the left is correctly `onScreen`.
 
+**HUD widgets are counted separately** (`report.widgets`), because asking
+whether the camera can see one is a category error — and because leaving them
+out meant a shop screen made entirely of widgets and an empty scene file both
+read `0/0 on screen`. A scene with no drawable node AND no widget now says
+`nothing on screen`, and the gate treats it as broken: a scene that draws
+nothing looks exactly like one that failed to load.
+
 **A 2D scene gets a 2D report**, in pixels: the `viewport.design` window centred
 on the current `Camera2D` and CLAMPED by its `limits`, which is the view the
 renderer actually draws. Nothing is ever `behind` a 2D camera and nothing is
@@ -334,7 +452,7 @@ the instant a frame composites, so `canvas.toDataURL()` and every screenshot
 built on it come back BLANK without it:
 
 ```ts
-createGame3D({ ..., preserveDrawingBuffer: true });
+createGame3D({ ..., preserveDrawingBuffer: true });   // createGame2D too
 // or in the scene: "environment": { "rendering": { "preserveDrawingBuffer": true } }
 ```
 
@@ -520,6 +638,44 @@ The same words `incanto-play` takes — `press`/`release ACTION`, `vector ACTION
 newlines. `--do-file` reads a longer plan from a file. One vocabulary for the
 headless gamepad and the live one.
 
+**Pointing at things**, for the games that are played that way:
+
+```
+$ bunx incanto-frame --do "at %Mole; click; step 300" --out whacked.png
+```
+
+`at X Y` puts the cursor on a canvas pixel and `at <node path>` puts it wherever
+that node is ON SCREEN — the page knows, and you cannot compute it from out
+here. **A `click` before anything has aimed is refused**, because it would land
+wherever the cursor was left, and a plan whose `at` failed would otherwise
+report the aim false and the click true. Headless, `click` also answers with
+what it HIT (`"hit": "/Game/Field/Hole11/Mole"`, or `null`) — the reason to aim
+is to hit something, and from outside the process there is no way to ask. **`incanto-play` takes the same two words**, headless, installing a
+geometric picker for them (there is no renderer to raycast with):
+
+```
+$ printf 'step 700\nat Field/Hole12/Mole\nclick\ndescribe\nquit\n' \
+    | bunx incanto-play src/game.scene.json --behaviors src/behaviors.ts
+{"ok":true,"cmd":"at","at":[560,291]}
+{"ok":true,"cmd":"click","t":733}
+… /Game/Hud/Score UiText text="Moles 1 / 12"
+``` `click` (optionally `left`/`middle`/`right`) presses and releases where the
+cursor is, with a frame in between so the game gets to show that it is being
+pressed.
+
+**A drag is `mouse` — press, move, let go**, because `click` is both edges at
+one point and a slingshot, a selection box, a swipe and an item carried between
+inventory slots are all "press here, move there, let go":
+
+```
+$ bunx incanto-frame --do "at 400 300; mouse left down; at 300 380; mouse left up; step 400"
+```
+
+`mouse` takes the same three words `click` does, and the same `0|1|2` the
+`incanto-play` REPL takes. The language used to have only `pointer DX DY`, which is a delta —
+the mouse-LOOK question — so an agent driving its own match-3, tower defense,
+card game or point-and-click could reach no state at all.
+
 `step` waits on the REAL clock: this is the running game, with its own loop, its
 own physics and its own animation, and stepping it by hand would fight all three.
 
@@ -529,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
 
 ```
@@ -779,6 +946,32 @@ rows until the orange box lands on the thing you're hunting.
 inside a `static` subtree, HUD widgets outside a HudLayer. Programmatic:
 `auditScene(json)` from `incanto` or `incanto/test` returns the warnings.
 
+**Including a HUD line that names the wrong key.** `tps-3d`'s pause menu read
+`Esc to resume · R to restart` for exactly three hours after `restart` was moved
+off `KeyR` — the binding moved and the sentence about it did not, which is the
+whole failure mode of any fact written down twice. The check is narrow on
+purpose: it fires only when a line names both a key it recognises AND a word
+that is a DECLARED ACTION in the same scene, so "Esc to resume" says nothing
+(there is no `resume` action) and prose is left alone.
+
+**Including one key bound to two actions.** `tps-3d` shipped `reload` and
+`restart` both on `KeyR`: pressing R reloaded, and `restart` — which nothing
+read — looked broken. Two actions on one key are legal, sometimes deliberate,
+so this warns rather than refuses; the sibling question ("does anything read
+this action at all?") is `input.unreadActions()`, in `incanto-playtesting.md`.
+
+**Including a `Clickable` nobody listens to.** It produces `clicked`, `hovered`
+and `unhovered` and nothing else, so attaching it and wiring none of them costs
+a pick every frame and can never do anything — the likeliest mistake a mouse
+game makes, and one with no error anywhere. A board of sixteen unwired tiles
+used to print `1/1 scene(s) valid`.
+
+```
+warn: Game/A: Clickable produces nothing but 'clicked'/'hovered'/'unhovered',
+      and no connection listens to any of them — so it can never do anything.
+      Wire one, or listen in code with `node.on('clicked', …)`.
+```
+
 **Including a node path that points at nothing.** `Chase.target`,
 `Camera2D.follow`, `Spawner.prefab`, `Joint3D.target`, `skinPath`, `terrain` —
 these hold a path to another node, and a wrong one is SILENT: a connection that
@@ -793,8 +986,12 @@ warn: World/Cam: follow — '/Level/Player' starts at 'Level', but the scene
 ```
 
 An empty value is never reported — `""` is the default of most of these and
-means "not set". A behavior of YOUR OWN is not reported either: the checker
-never loads your TypeScript, so it cannot know which of its props are paths.
+means "not set" (and `getNodeOrNull("")` returns null, so the guard you would
+write for it is unnecessary). A behavior of YOUR OWN is reported too, once you
+hand the checker the file that registers it: `incanto-check src --behaviors
+src/behaviors.ts`. Without the flag it has no schema for your behaviours and
+cannot know which of their props are paths — so pass it, the way every
+scaffolded project's `check` script does.
 
 ## Deterministic replay (record once, regression-test forever)
 
@@ -811,7 +1008,7 @@ save.set('replays/level1', rec.stop());
 
 // in a headless test:
 const engine = new Engine({ seed: SAME_SEED });
-engine.setScene(loadScene(sceneJson));
+engine.setScene(loadScene(sceneJson, { engine }));
 replay(engine, recording, { onTick(i) { /* mid-run asserts */ } });
 expect(player.position).toEqual(expected); // exact, not approximate
 ```

package/skills/incanto-web-integration.md

@@ -83,6 +83,34 @@ null when the ray misses (looking at the sky). `pick(sx, sy)` gives you the NODE
 under a pixel — a different question, and the only one 3D could answer before
 0.66.
 
+**Inside a Behavior there is no renderer**, so the same four questions are on
+the engine, installed by whichever renderer is running and cleared when it is
+disposed:
+
+```ts
+this.engine.pointerWorld()                 // where the cursor is → number[] | null
+this.engine.toWorld(sx, sy)                // any screen point → [x, y] | [x, y, z]
+this.engine.toScreen(node.position)        // → { x, y, behind } | null
+this.engine.screenRay(sx, sy)              // 3D only → { origin, dir } for castRay
+this.engine.pickAt(sx, sy)                 // which node (cached per frame)
+```
+
+The answer is the scene's own shape — `[x, y]` in 2D, `[x, y, z]` on the ground
+in 3D — so it goes straight back into a `position`. All are null with no
+renderer; a `runScript` `click` step (and `incanto-play`'s `at`) installs
+geometric `toWorld`/`toScreen`/`screenRay` for the run, so a game that AIMS is
+testable headless and not only one that clicks.
+
+**On uneven ground, cast the ray** — `toWorld` lands on a plane, which is the
+wrong answer under a hill or a crate:
+
+```ts
+const at = this.engine.input.pointerPosition();
+const ray = at && this.engine.screenRay?.(at.x, at.y);
+const hit = ray && this.engine.physics?.castRay(ray.origin, ray.dir, 100);
+if (hit) place(hit.point);          // WHERE it landed, not how far
+```
+
 Perf note: `useNodeProp` deep-compares per frame — subscribe to LEAF values
 (`'UI/Score', 'text'`), not big objects like a whole `animations` map.
 

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

@@ -40,7 +40,9 @@ the vite config and the verify harness.
 
 Pick by shape, not by subject: `tps-3d` (third-person combat), `platformer-2d`,
 `star-survivor` (top-down survivor), `village-quest-3d` (quest/NPC),
-`beacon-isle-3d` (open world).
+`beacon-isle-3d` (open world), `molehill-2d` (**played with the MOUSE** — no
+character, no keyboard: the shape a match-3, a tower defense, a card game, a
+point-and-click or an RTS starts from).
 
 ---
 

package/templates-app/beacon-isle-3d/generate-world.ts

@@ -6,6 +6,7 @@
  * (quest, enemies, HUD) — regenerate the world without touching the game.
  */
 
+import { newUid } from 'incanto';
 import { buildTerrainNav, Terrain3D } from 'incanto/3d';
 import { generateTerrain } from 'incanto/env';
 
@@ -145,6 +146,8 @@ dressing.push({
   name: 'ShoreRocks',
   type: 'InstancedMesh3D',
   props: {
+    // Sunk into the slope on purpose — see the note by the player's Catch.
+    snapToGround: false,
     mesh: 'gem',
     size: [0.6, 0.45, 0.6],
     material: { color: '#7e8590', roughness: 0.95, flatShading: true },
@@ -166,7 +169,7 @@ const ward = (i: number, [x, y, z]: [number, number, number]): unknown => ({
   name: `Ward${i}`,
   type: 'Node3D',
   groups: ['ward'],
-  props: { position: [round2(x), round2(y), round2(z)] },
+  props: { position: [round2(x), round2(y), round2(z)], snapToGround: false },
   children: [
     {
       name: 'Plinth',
@@ -228,7 +231,7 @@ const shade = (wardIdx: number, n: number, [x, y, z]: [number, number, number]):
   name: `Shade${wardIdx}_${n}`,
   type: 'Node3D',
   groups: ['shade', `shade-ward${wardIdx}`],
-  props: { position: [round2(x), round2(y + 0.9), round2(z)] },
+  props: { position: [round2(x), round2(y + 0.9), round2(z)], snapToGround: false },
   script: { name: 'PathFollow', props: { speed: 2.6, loop: true } },
   children: [
     {
@@ -411,6 +414,9 @@ const scene = {
             round2(heightAt(keeperSite[0] - 5, keeperSite[2] - 4)),
             round2(keeperSite[2] - 4),
           ],
+          // The lamp sits at the top of the tower: the ASSEMBLY owns its
+          // children's height, so `findFloatingProps` is not asked about them.
+          snapToGround: false,
           static: true,
         },
         children: [
@@ -462,7 +468,7 @@ const scene = {
       {
         name: 'Keeper',
         type: 'Node3D',
-        props: { position: keeperSite.map(round2) },
+        props: { position: keeperSite.map(round2), snapToGround: false },
         script: { name: 'Interactable', props: { action: 'interact', range: 3 } },
         children: [
           {
@@ -511,6 +517,9 @@ const scene = {
         name: 'Player',
         type: 'RigidBody3D',
         groups: ['player'],
+        // Its Health is saveable, and a save is keyed by uid — minted, pasted,
+        // and stable across regenerations for the same reason the HUD's are.
+        uid: 'n_3cqocoi9v0cvoxdv',
         script: { name: 'Health', props: { max: 100, invulnerableFor: 0.8 } },
         props: {
           position: [round2(playerSpawn[0]), round2(playerSpawn[1] + 1.2), round2(playerSpawn[2])],
@@ -519,11 +528,24 @@ const scene = {
           collider: { shape: 'capsule', radius: 0.34, height: 1 },
         },
         children: [
+          {
+            /*
+             * An open terrain has an EDGE. With no catch, walking off it falls
+             * forever — `incanto-playtest` calls that `fell` and treats it as a
+             * failure whatever the game set out to be.
+             */
+            name: 'Catch',
+            type: 'Respawn',
+          },
           {
             name: 'Controller',
             type: 'CharacterController3D',
             props: {
               view: 'free',
+              // The two `incanto-feel` prints a note about on every run, and the
+              // 3D character skill calls coyote time the single biggest one.
+              coyoteSeconds: 0.12,
+              jumpBufferSeconds: 0.15,
               camDistance: 5.2,
               eyeHeight: 1.1,
               maxSpeed: 4.4,
@@ -623,6 +645,7 @@ const scene = {
         // ROOT child (a positioned parent would double the offset on screen)
         props: {
           visible: false,
+          snapToGround: false,
           position: [
             round2(keeperSite[0] + 16),
             round2(heightAt(keeperSite[0] + 16, keeperSite[2] - 14)),
@@ -768,7 +791,10 @@ const scene = {
           {
             name: 'Quest',
             type: 'UiText',
-            uid: 'n_bi_quest',
+            // MINTED by newUid() and pasted, not invented: a save is keyed by
+            // uid and this file is regenerated, so they have to be both
+            // crypto-shaped and stable across `bun run world`.
+            uid: 'n_3txwnq8m201xbwoz',
             props: {
               text: 'Find the lighthouse keeper [E]',
               size: 16,
@@ -779,20 +805,25 @@ const scene = {
           {
             name: 'HP',
             type: 'UiBar',
-            uid: 'n_bi_hp',
+            uid: 'n_vp09cmk3syxo2lcz',
             props: { anchor: 'topRight', value: 100, max: 100, width: 170 },
           },
-          { name: 'Banner', type: 'UiBanner', uid: 'n_bi_banner', props: { anchor: 'center' } },
+          {
+            name: 'Banner',
+            type: 'UiBanner',
+            uid: 'n_xwkphpoa7ac9w451',
+            props: { anchor: 'center' },
+          },
           {
             name: 'Dialogue',
             type: 'UiDialogue',
-            uid: 'n_bi_dialogue',
+            uid: 'n_7wosfkulqmue3jpv',
             props: { anchor: 'bottom', charsPerSecond: 45 },
           },
           {
             name: 'Hint',
             type: 'UiText',
-            uid: 'n_bi_hint',
+            uid: 'n_x3funbse7a8nkfnu',
             props: {
               text: 'WASD move · Shift sprint · E interact · click/F strike',
               size: 12,
@@ -811,7 +842,44 @@ const scene = {
   ],
 };
 
-await Bun.write(`${import.meta.dir}/src/game.scene.json`, `${JSON.stringify(scene, null, 2)}\n`);
+/*
+ * A REGENERATED file keeps the identities the old one had.
+ *
+ * A uid is the key a save is written against, and this script overwrites the
+ * whole scene — so minting fresh ones every run would break every save on the
+ * next `bun run world`, and emitting none at all (which is what it used to do)
+ * left eighteen scripted nodes unkeyed, so a save could not record what the run
+ * consumed. `verify:uids` said so; nothing said it to whoever ran the command.
+ *
+ * Reused by PATH: the same seed builds the same island, so the same node is at
+ * the same place. Anything new gets a real `newUid()`.
+ */
+const scenePath = `${import.meta.dir}/src/game.scene.json`;
+const previous = new Map<string, string>();
+try {
+  const old = JSON.parse(await Bun.file(scenePath).text()) as { root?: unknown };
+  const remember = (node: Record<string, unknown>, path: string): void => {
+    const here = `${path}/${String(node.name ?? '?')}`;
+    if (typeof node.uid === 'string') previous.set(here, node.uid);
+    for (const child of (node.children ?? []) as Record<string, unknown>[]) remember(child, here);
+  };
+  if (old.root) remember(old.root as Record<string, unknown>, '');
+} catch {
+  // No previous file: every uid below is minted fresh, which is the first run.
+}
+
+const keyIdentities = (node: Record<string, unknown>, path: string): void => {
+  const here = `${path}/${String(node.name ?? '?')}`;
+  // Only what a save would write down: a node carrying a behavior.
+  if (node.script && typeof node.uid !== 'string') node.uid = previous.get(here) ?? newUid();
+  else if (typeof node.uid === 'string' && previous.has(here))
+    node.uid = previous.get(here) as string;
+  for (const child of (node.children ?? []) as Record<string, unknown>[])
+    keyIdentities(child, here);
+};
+keyIdentities(scene.root as unknown as Record<string, unknown>, '');
+
+await Bun.write(scenePath, `${JSON.stringify(scene, null, 2)}\n`);
 console.log(
   `beacon isle generated: keeper ${keeperSite.map(round2)}, wards ${wardSites.map((w) => w.map(round2)).join(' | ')}, ${placed} groves, ${grassPlaced} grass, ${flowersPlaced} flowers`,
 );

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

@@ -6,7 +6,7 @@
     "dev": "vite",
     "build": "vite build",
     "typecheck": "tsc --noEmit",
-    "check": "incanto-check src",
+    "check": "incanto-check src --behaviors src/behaviors.ts",
     "verify": "bun verify.ts",
     "world": "bun generate-world.ts"
   },
@@ -14,7 +14,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.69.0",
+    "incanto": "^0.71.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/beacon-isle-3d/src/behaviors.ts

@@ -88,6 +88,27 @@ function spawnFootDust(root: Node, at: [number, number, number], scale = 1): voi
 }
 
 export class IsleDirector extends Behavior {
+  /**
+   * The isle HAS an ending, and never said so.
+   *
+   * Three wards lit, the Shadeheart down, fireworks over the lighthouse and
+   * `BEACON ISLE SHINES` on the banner — and no `won` anywhere, so every
+   * instrument that asks the scene whether it is finishable answered no. On
+   * the template `bunx incanto-new my-game` scaffolds by DEFAULT:
+   *
+   * ```
+   * ? plays — nothing declares a win — 8 runs played without a defect,
+   *           and there was no end to reach
+   * next: if it is meant to be finishable, emit `won`
+   * ```
+   *
+   * Both sentences were true about the WIRING and wrong about the game. A
+   * signal is the cheapest of the three routes the skill offers (`GameFlow`,
+   * `ScoreKeeper`, your own behaviour) and the only one that does not also
+   * freeze the world — the isle keeps playing after you win it.
+   */
+  static readonly signals: readonly string[] = ['won'];
+
   private wind: Voice | null = null;
   private nav: TerrainNav | null = null;
   private repathClock = 0;
@@ -445,6 +466,7 @@ export class IsleDirector extends Behavior {
         (this.node.getNode('WinSfx') as AudioPlayer).play();
         this.fireworksIn = 0.4;
         this.syncQuestLine();
+        this.node.emit('won');
       });
       return;
     }