incanto 0.69.0 → 0.70.0

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

@@ -33,14 +33,22 @@ wiring, and composition are all in the file. TS is for *behavior only* (attached
 ```
 
 - `format` MUST be `1`. `type` MUST be `"scene"`. `name` non-empty.
-- `dimension` is optional: `"2d"` or `"3d"` only.
+- `dimension` is optional: `"2d"` or `"3d"` only. Left out, it is INFERRED from
+  the node types in the tree (anything ending `3D` makes the scene 3D) — write
+  it anyway, because it is what the environment validator, the audit's
+  no-camera/no-light warnings and `physics: "auto"` all read.
 - `fragment` (optional, default `false`) says this file is a PIECE of another
   scene — a spawner's prefab, a sub-scene something instances — and is never
   rendered on its own. It changes nothing at runtime; it tells the checker to
-  stop asking a prefab where its camera and its sun are. Set it on any scene
-  you load from TypeScript and hand to a spawner. (A scene another scene
-  embeds with `instance` needs no key — `incanto-check` walks the project and
-  can see that for itself.)
+  stop asking a prefab where its camera and its sun are, and to stop answering
+  the two questions only the HOST can answer: a node path that leaves the file
+  (`/root/Bolts` is the fragment's own root only while the fragment is alone)
+  and a `DamageOnContact.targetGroup` whose victims live in the host scene.
+  Those two are still NAMED, with a reworded verdict — a typo is most likely in
+  exactly this file, written away from the scene that gives it meaning. Set it
+  on any scene you load from TypeScript and hand to a spawner. (A scene another
+  scene embeds with `instance` needs no key — `incanto-check` walks the project
+  and can see that for itself.)
 - `viewport` (optional) makes scene JSON own responsive layout: author the world
   in fixed `design` pixels (`[width, height]`, positive numbers) and the renderer
   maps them onto any canvas size. `fit`: `"expand"` (design rect always fully
@@ -96,12 +104,24 @@ Rules the engine enforces with **hard errors** (it never warns silently):
 3. Prop keys and value kinds are validated against the type's schema:
    unknown key → `UNKNOWN_PROP` (message lists valid keys); wrong JSON kind
    (e.g. string where the default is boolean) → `PROP_TYPE_MISMATCH`.
+   A few props accept TWO kinds — `Flowers3D.density` takes a preset name or
+   plants per m², `Water3D.underwater` takes `true`/`false` or a settings
+   object — and `incanto-node-reference.md` names both in its Kind column
+   (`one of: lush sparse none, or number`). The error names them too, so a
+   value the loader refuses tells you every shape it would have taken.
 4. Sibling names must be unique. Colliding names are auto-renamed by incrementing a
    trailing number (`Enemy` → `Enemy2` → `Enemy3`) — **write unique names yourself** so your
    connection paths stay valid (connections resolve after renaming).
 5. Node names must not contain `/` or `%` and must be non-empty.
 6. `groups` are string tags for queries (`getNodesInGroup`, connection filters).
    `tags` is free-form JSON for game-logic identity (`{"kind": "ITEM", "value": 10}`).
+   **`groups` is a LIST and `tags` is an OBJECT**, and the loader now says so:
+   `"groups": "player"` used to load clean and spread the string one CHARACTER
+   at a time (`["p","l","a","y","e","r"]`), so `player` was in no group and
+   every query and `filter: {group: "player"}` silently matched nothing. Every
+   node key is checked for its KIND now — `props`/`overrides` an object,
+   `children` a list, `uid` a non-empty string from `newUid()` — as are the
+   header's `constants`, `multiplayer` (objects) and `connections` (a list).
 7. `script` resolves to a registered Behavior at load (`incanto-behaviors-and-scripts.md`);
    `network` drives multiplayer replication (`incanto-multiplayer.md`). Both round-trip
    losslessly through export.
@@ -321,10 +341,21 @@ that do exist at the failing spot).
             never recovers.
   ```
 
-  `died → ScoreKeeper.addScore` is the natural way to score a kill and it sets the
-  score to `NaN` on the first one, with the win condition then permanently out of
-  reach. A handler that DEFAULTS what it is not given is correct and stays silent:
-  `won → GameFlow.win` works, because `win(text = 'YOU WIN')` needs nothing. On **both**, it is
+  `died → ScoreKeeper.addScore` is the natural way to score a kill and it used to
+  set the score to `NaN` on the first one, with the win condition then
+  permanently out of reach. The numeric handlers REFUSE a non-number now, so the
+  same wire fails loudly instead — and so does the one the arity check cannot
+  see: `clicked → addScore` hands the NODE, which is one argument into one
+  parameter, and `score + node` is a STRING that grows forever. A handler that DEFAULTS what it is not given is correct and stays silent:
+  `won → GameFlow.win` works, because `win(text = 'YOU WIN')` needs nothing.
+
+  Writing your OWN handler, the same rule applies to you: an optional parameter
+  is a **default**, not a `?`. `hurt(amount: number, from?: Node)` counts as
+  needing 2, because `?` is a TypeScript annotation that does not survive to
+  runtime — write `from: Node | undefined = undefined` and the wire is judged on
+  what it actually needs. Every engine method a wire can name has been corrected
+  to this; before that, four of five documented HUD wires were reported as
+  broken while working perfectly. On **both**, it is
   `AMBIGUOUS_HANDLER`: the node's method wins, so the script's would never run
   and nothing would say so. A core node answers to 62 public methods before any
   adapter adds more (`stop` `play` `show` `clear` `say` `start` `free` …), which
@@ -333,7 +364,11 @@ that do exist at the failing spot).
 - Unresolvable `from`/`to` → `DANGLING_CONNECTION` at load. Renaming a node breaks its
   connections **loudly** — update paths in the same edit.
 - `filter` gates firing on the first emitted argument: it must be a node in `filter.group`
-  and/or match every `filter.tag` entry. With `once: true`, the connection is consumed only
+  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
+  error, because a filter the matcher cannot read (`{"gruop": "player"}`, or the bare
+  string `"player"`) passes EVERYTHING, which is the opposite of what a filter is for, and
+  `"once": "no"` is truthy so it fires exactly once. With `once: true`, the connection is consumed only
   when the filter matches.
 
 ## Sub-scene composition
@@ -345,7 +380,20 @@ that do exist at the failing spot).
 - `instance` embeds another scene's tree; `overrides` deep-merge onto the sub-scene root's
   props. At the instancing site, `groups` and `children` COMPOSE (union/append), while
   `tags`/`script`/`network` REPLACE the sub-scene root's values when declared (omitted = kept).
-- The sub-scene's own `connections` are wired inside its subtree automatically.
+- The sub-scene's own `connections` are wired inside its subtree automatically,
+  and so are its `assets`, `input`, `strings`, `constants` and `orderGroups` —
+  **a prefab brings everything it declares**. (Its `orderGroups` used to come
+  through as NAMES only, so `"orderGroup": "loot"` validated and the band's
+  number was dropped: the sprite sorted in the default band and the scene loaded
+  clean.) A `coin.scene.json` with its own
+  spritesheet, or a `player.scene.json` with its own `move`/`jump` bindings, is
+  a complete, reusable thing.
+- The HOST wins any asset key, action name or string it declares itself, so a
+  level can re-point a prefab's art or rebind its controls without editing the
+  prefab. Two INSTANCED scenes declaring one asset key with different urls — or
+  one action name with different keys — is a hard error naming both:
+  first-writer-wins would hand the second prefab the first one's art in silence.
+  The same key with the same value is just two prefabs agreeing.
 - There is **no** scene inheritance — composition only.
 - Current limitation: exporting expands instances into full trees (the `instance` reference is
   not preserved on export yet).
@@ -373,6 +421,12 @@ that do exist at the failing spot).
 | `DUPLICATE_BEHAVIOR` | two classes registered under one behavior name | rename one, or `{ replace: true }` for hot reload |
 | `TREE_VIOLATION` | invalid name, re-parenting without detach, cycles, double root | follow the rule in the message |
 
+Every one of these lists what WOULD have worked, and names the nearest
+candidate when there is one — `Unknown node type 'Label2D'. Did you mean
+"Label"?`, `Unknown prop 'size' on 'Label'. Did you mean "fontSize"?`. A name
+that resembles nothing gets the list alone, because a suggestion that is not the
+answer is worse than none.
+
 Scene-load and registry errors carry structured `details` (`path`, `uid`, `nodeType`,
 `prop`, `signal`, `validOptions`) mirroring the prose — prefer those over regexing the
 message (a few runtime errors still carry prose only). Scene-load
@@ -384,7 +438,10 @@ errors append the offending node's path: `… (at '/Level/Enemies/Slime3')`.
 import { loadScene, registerCoreNodes, duplicateNode } from 'incanto';
 
 registerCoreNodes();                            // explicit — never an import side effect
-const scene = loadScene(json, { resolveScene }); // throws IncantoError on any problem
+// `{ engine }` on a manual boot: `onReady` runs during the LOAD, so a behaviour
+// that reads `this.engine` or `this.rng` there throws without it. `createGame2D`
+// /`3D` and `runScript` pass it for you.
+const scene = loadScene(json, { engine, resolveScene }); // throws IncantoError on any problem
 scene.root.getNode('Player').emit('hit', 10);
 const copy = duplicateNode(scene.root.getNode('Coin'));
 const exported = scene.toJSON();                 // lossless (delta-only props)

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.
 
@@ -779,6 +935,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 +975,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 +997,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`,
 );