incanto 0.31.0 → 0.33.0

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

@@ -562,3 +562,19 @@ if (cells) follow.setPath(cells.map(([cx, cy]) => nav.toWorld(cx, cy)));
   dense-forest frame). Use when shadow CASTERS don't move — pair moving
   characters with sprite/blob shadows. After a one-off world edit call
   `renderer.refreshShadows()`.
+
+## Before you hand it back
+
+You cannot see this game. `incanto-verifying-your-game.md` is how you find out
+whether it works — run it after every edit, not once at the end:
+
+```bash
+bunx incanto-check                       # will it load? is anything lit?
+printf 'step 500\nframing\nquit\n' | bunx incanto-play src/game.scene.json
+```
+
+`framing` tells you what the camera can actually SEE (on screen / off screen /
+behind it), what lights the scene, and which colliders intersect. Then read
+`stats().errors` (something threw and got skipped) and `assetErrors()` (a model
+404'd). All four are silent failures otherwise — the screen just looks wrong,
+or empty, and nothing throws.

package/skills/incanto-hud.md

@@ -80,3 +80,44 @@ Typewriter reveal at `charsPerSecond` (0 = instant); clicking the box
 reveals the line then advances; choice lines render buttons and wait for
 `choose(i)`. Buttons opt into pointer events — the rest of the HUD stays
 click-through.
+
+## Menus, options and inventories (UiPanel + the value widgets)
+
+The HUD widgets can SAY things. These arrange them and take a value back — which
+is what a title screen, pause menu, options panel, shop and inventory grid are.
+Before them every one of those was hand-rolled DOM, which drops the whole screen
+out of scene JSON, out of the editor, out of `incanto-check` and out of every
+headless check you have.
+
+**`UiPanel` is the box.** Widgets normally mount into the HudLayer's anchor slot
+no matter how the tree is shaped; anything under a panel mounts into the PANEL,
+so structure in the tree becomes structure on screen. Panels nest.
+
+```json
+{ "name": "Pause", "type": "UiPanel",
+  "props": { "anchor": "center", "layout": "column", "gap": 12, "padding": 20 },
+  "children": [
+    { "name": "Title", "type": "UiText", "props": { "text": "PAUSED", "size": 28 } },
+    { "name": "Volume", "type": "UiSlider", "props": { "label": "volume", "value": 0.8 } },
+    { "name": "Invert", "type": "UiToggle", "props": { "label": "invert Y" } },
+    { "name": "Quality", "type": "UiSelect", "props": { "options": "low,medium,high", "value": "high" } },
+    { "name": "Resume", "type": "UiButton", "props": { "label": "Resume" } }
+  ] }
+```
+
+| node | props | signal |
+| --- | --- | --- |
+| `UiPanel` | `layout` (column/row/**grid**), `columns`, `gap`, `padding`, `background`, `radius`, `width`, `height`, `border` | — |
+| `UiImage` | `src` (url or `$assetKey`), `width`, `height`, `fit`, `tint`, `opacity` | — |
+| `UiSlider` | `label`, `value`, `min`, `max`, `step`, `width`, `color` | `changed(value)` |
+| `UiToggle` | `label`, `value` | `changed(bool)` |
+| `UiSelect` | `label`, `options` (`"low,medium,high"`), `value` | `changed(value)` |
+
+**An inventory is a grid panel**: `"layout": "grid", "columns": 5`, one child per
+slot, each a small `UiPanel` holding a `UiImage` (`tint` greys out what you
+cannot afford) — and `Clickable` is on the world node, not the widget; for a
+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.
+

package/skills/incanto-node-reference.md

@@ -246,6 +246,17 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `jumpHeight` | `64` | number |
 | `moveAction` | `"move"` | string |
 | `jumpAction` | `"jump"` | string |
+| `coyoteSeconds` | `0` | number |
+| `jumpBufferSeconds` | `0` | number |
+| `jumpCutMultiplier` | `1` | number |
+| `maxJumps` | `1` | number |
+| `dashSpeed` | `0` | number |
+| `dashSeconds` | `0.15` | number |
+| `dashAction` | `"dash"` | string |
+| `wallSlideSpeed` | `0` | number |
+| `wallJumpImpulse` | `[0,0]` | array |
+
+Signals: `movementStateChanged(state)`
 
 ## `CharacterController3D` — `incanto/3d`
 
@@ -958,6 +969,63 @@ Signals: `pressed`
 
 Signals: `lineShown` · `choiceMade` · `dialogueFinished`
 
+## `UiImage` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `src` | `""` | string |
+| `width` | `48` | number |
+| `height` | `48` | number |
+| `fit` | `"contain"` | one of: `contain` `cover` `fill` |
+| `tint` | `""` | string |
+| `opacity` | `1` | number |
+
+## `UiPanel` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `layout` | `"column"` | one of: `column` `row` `grid` |
+| `columns` | `4` | number |
+| `gap` | `8` | number |
+| `padding` | `12` | number |
+| `background` | `"rgba(0,0,0,0.55)"` | string |
+| `radius` | `10` | number |
+| `width` | `0` | number |
+| `height` | `0` | number |
+| `border` | `""` | string |
+
+## `UiSelect` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `label` | `""` | string |
+| `options` | `""` | string |
+| `value` | `""` | string |
+
+Signals: `changed`
+
+## `UiSlider` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `label` | `""` | string |
+| `value` | `0.5` | number |
+| `min` | `0` | number |
+| `max` | `1` | number |
+| `step` | `0.01` | number |
+| `width` | `180` | number |
+| `color` | `"#6ee7dc"` | string |
+
+Signals: `changed`
+
 ## `UiText` — `incanto`
 
 | Prop | Default | Kind |
@@ -969,6 +1037,17 @@ Signals: `lineShown` · `choiceMade` · `dialogueFinished`
 | `color` | `"#ffffff"` | string |
 | `shadow` | `true` | boolean |
 
+## `UiToggle` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `label` | `""` | string |
+| `value` | `false` | boolean |
+
+Signals: `changed`
+
 ## `VoxelGrid3D` — `incanto/3d`
 
 | Prop | Default | Kind |
@@ -1084,6 +1163,16 @@ Signals: `submerged` · `surfaced`
 
 Signals: `reachedTarget` · `lostTarget`
 
+### `Clickable`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `button` | `0` | number |
+| `maxDistance` | `0` | number |
+| `enabled` | `true` | boolean |
+
+Signals: `clicked` · `hovered` · `unhovered`
+
 ### `Collector`
 
 | Prop | Default | Kind |

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

@@ -258,6 +258,56 @@ the tree says, without your scene falling over while you look at it. Use it for
 any "show me the collision geometry" tool. Do NOT use it to freeze a running
 game — that is `engine.timeScale = 0`, which keeps the world coherent.
 
+## Moving platforms carry their riders (2D **and** 3D)
+
+A `CharacterBody2D`/`CharacterBody3D` standing on a body that moves is dragged
+along by however far that body moved — elevators, patrol platforms, conveyors,
+rotating discs. It is what makes a floating-island game work.
+
+Author it the obvious way: move the platform's `position` (a behavior, a
+`PathFollow`, an `Oscillate`). Nothing else to declare.
+
+The carry stops the moment the character is no longer grounded on it, so walking
+off an edge or jumping is not "sticky", and it is vertical as well as horizontal
+— an elevator lifts you.
+
+## The mouse as gameplay input (click, hover)
+
+`pointerDelta()` answers "how far did the mouse move" — the mouse-look question.
+For match-3, tower defense, card games, point-and-click and RTS that is the
+wrong question, and it used to be the only one the engine could answer.
+
+```ts
+engine.input.pointerPosition();   // { x, y } in CANVAS pixels, or null
+engine.input.mousePressed(0);     // 0 left · 1 middle · 2 right
+engine.input.mouseJustPressed(0); // and mouseJustReleased(0)
+game.pick(x, y);                  // the node under that pixel, or null
+```
+
+A stretched canvas is handled: `pointerPosition()` scales client → canvas pixels,
+so the coordinates are the ones `pick()` wants.
+
+From scene JSON, the **`Clickable`** behavior needs no code at all:
+
+```json
+{ "name": "Tile", "type": "MeshInstance3D", "script": { "name": "Clickable" } }
+```
+
+| prop | default | |
+| --- | --- | --- |
+| `button` | `0` | 0 left · 1 middle · 2 right |
+| `maxDistance` | `0` | ignore clicks further than this (0 = any) |
+| `enabled` | `true` | stop responding without detaching |
+
+Signals: **`clicked`**, **`hovered`**, **`unhovered`** — wire them in
+`connections` like any other. `clicked` fires on RELEASE over the same node the
+press started on (a drag that ends elsewhere is not a click, the way every
+button on every platform behaves), and a hit on a CHILD counts as a hit on the
+node — the raycast lands on the visual mesh, which is usually a child.
+
+Headless there is no renderer and therefore no raycast: `Clickable` is inert
+rather than wrong, and `engine.picker` is null.
+
 ## Placement rules
 
 `CharacterController2D` MUST be a direct child of a `CharacterBody2D` — the

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

@@ -12,6 +12,20 @@ You usually cannot SEE the game (no browser in most agent environments). The
 scene state itself is your screenshot. The loop is: **edit → check → scripted
 run → read the capture → fix**. Never hand a game back without steps 2–3.
 
+**The four things to read before you call it done.** Three of them are new, and
+each answers a failure that used to look like nothing at all:
+
+| read this | when it is not clean | see |
+| --- | --- | --- |
+| `incanto-check` | the scene will not load, or renders black | §1, §5b |
+| `stats().errors` | something threw and was skipped to keep the game alive | §6b |
+| `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.
+
 ## 1. After EVERY scene edit: `incanto-check`
 
 ```bash
@@ -144,6 +158,25 @@ const res = validateScene(sceneJson);          // { ok } | { ok: false, error }
 if (!res.ok) console.error(res.error.code, res.error.details); // details.path/prop/signal/validOptions
 ```
 
+## 5b. What a green `incanto-check` now covers
+
+`validateScene` / `incanto-check` hard-fail on all of these, so they never reach
+a browser:
+
+- **Every prop's type AND its enum values** — `"mesh": "crystal"` names what is
+  valid instead of printing `ok` and throwing at boot. All 31 enum props.
+- **`input{}`** — a declaration's shape (`"keys": "Space"` instead of
+  `["Space"]`, an unknown `type`, a wrong `touch`). This used to be checked only
+  by `Engine.setScene`, i.e. never headlessly.
+- **`assets{}`** — every entry an object with a non-empty `url`.
+- **`environment.preset`** — resolved only inside Renderer3D before, so a typo
+  survived every check and died at boot.
+
+And `auditScene` (the warnings `incanto-check` prints) gained the loudest
+"why is my screen black" of all: **nothing lights this 3D scene** — no light
+node, no `environment` sky/hdri/preset, no ambient intensity. Ambient defaults to
+0, so such a scene renders nothing, throws nothing and logs nothing.
+
 ## 6. Catch broken edits at save time (vite)
 
 ```ts
@@ -161,44 +194,47 @@ ANY scene in the project — not just the one the game booted with. `incantoScen
 root })` bounds that to a directory other than vite's; nothing outside it is readable
 or writable, and none of it exists in a build (`configureServer`).
 
-## 5b. What a green `incanto-check` now covers
+## 6a. See what the camera sees — without a GPU
 
-`validateScene` / `incanto-check` hard-fail on all of these, so they never reach
-a browser:
+`describe()` tells you a gem is at `[4, 1, -2]`. It cannot tell you whether you
+can SEE it, which is the question you actually had. `framing()` answers that,
+from geometry alone — no renderer, no canvas, no browser:
 
-- **Every prop's type AND its enum values** — `"mesh": "crystal"` names what is
-  valid instead of printing `ok` and throwing at boot. All 31 enum props.
-- **`input{}`** — a declaration's shape (`"keys": "Space"` instead of
-  `["Space"]`, an unknown `type`, a wrong `touch`). This used to be checked only
-  by `Engine.setScene`, i.e. never headlessly.
-- **`assets{}`** — every entry an object with a non-empty `url`.
-- **`environment.preset`** — resolved only inside Renderer3D before, so a typo
-  survived every check and died at boot.
+```
+> framing
+camera /World/Player/Cam at [0, 2, 8] looking [0, -0.2, -0.97] fov 60
+lit by: /World/Sun (DirectionalLight3D), environment.sky
+3 on screen, 1 off screen, 2 behind the camera
+  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
+  overlap   /World/Platform ∩ /World/Gem
+```
 
-And `auditScene` (the warnings `incanto-check` prints) gained the loudest
-"why is my screen black" of all: **nothing lights this 3D scene** — no light
-node, no `environment` sky/hdri/preset, no ambient intensity. Ambient defaults to
-0, so such a scene renders nothing, throws nothing and logs nothing.
+Read it for the three visual failures that look identical from a node list:
 
-## 6c. Engine diagnostics you can actually read
+- **`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.
+- **`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.
 
-Every internal warning the engine produces — a GLB that 404'd, a body with no
-collider, a retarget that dropped bones, an exception swallowed inside a physics
-trigger handler — used to go to `console.*` and nowhere else, which is the one
-channel a headless tool cannot read. The symptom was always the same: the model
-simply never appears, and `logs` comes back empty.
+Also `incanto-play`'s `framing` command, and `describeFraming(scene)` /
+`framingText(report)` from `incanto/test` for the structured form. A node counts
+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`.
 
-They now go to **`engine.log` as well as the console**, so:
+**For actual pixels**, turn on `preserveDrawingBuffer` — WebGL clears the buffer
+the instant a frame composites, so `canvas.toDataURL()` and every screenshot
+built on it come back BLANK without it:
 
-- `runScript().logs` contains them, and `describe()` prints them under the
-  failures (`! warn: …`).
-- The debug overlay's **Logs** panel shows them live.
-- `game.assetErrors()` lists every asset that failed **with its reason and ref**
-  — the direct answer to "why is my model not there". The store itself is
-  reachable as `renderer.assets` in both dimensions.
+```ts
+createGame3D({ ..., preserveDrawingBuffer: true });
+// or in the scene: "environment": { "rendering": { "preserveDrawingBuffer": true } }
+```
 
-So the after-every-edit check is: `ok`, then **`stats().errors`**, then
-**`assetErrors()`**.
+Then drive the page with whatever browser tool you have. It costs a buffer copy
+per frame, which is why it is off by default.
 
 ## 6b. A thrown error no longer stops the game
 
@@ -223,6 +259,26 @@ stopped. It no longer can.
 
 So the check after every edit is still `ok`, plus: **read `stats().errors`**.
 
+## 6c. Engine diagnostics you can actually read
+
+Every internal warning the engine produces — a GLB that 404'd, a body with no
+collider, a retarget that dropped bones, an exception swallowed inside a physics
+trigger handler — used to go to `console.*` and nowhere else, which is the one
+channel a headless tool cannot read. The symptom was always the same: the model
+simply never appears, and `logs` comes back empty.
+
+They now go to **`engine.log` as well as the console**, so:
+
+- `runScript().logs` contains them, and `describe()` prints them under the
+  failures (`! warn: …`).
+- The debug overlay's **Logs** panel shows them live.
+- `game.assetErrors()` lists every asset that failed **with its reason and ref**
+  — the direct answer to "why is my model not there". The store itself is
+  reachable as `renderer.assets` in both dimensions.
+
+So the after-every-edit check is: `ok`, then **`stats().errors`**, then
+**`assetErrors()`**.
+
 ## 7. See inside the RUNNING game (debug overlay)
 
 ```ts

package/templates-app/beacon-isle-3d/docs/project-3d-rules.md

@@ -5,15 +5,17 @@ YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template:
    manual, version-pinned to what is installed. Start with
    `incanto-building-3d-games.md`, `incanto-3d-character.md`,
    `incanto-gameplay-behaviors.md`, `incanto-environment.md` and
-   `incanto-audio.md` — this template composes all five.
+   `incanto-hud.md` — this template composes them —
+   and FINISH with `incanto-verifying-your-game.md` (rule 11).
 2. 🧱 STRUCTURE IS JSON: scenes, nodes, props, assets, input maps and
-   replication all live in `src/game.scene.json`. Add nodes there (or with
+   replication all live in `src/*.scene.json`. Add nodes there (or with
    `npx incanto-editor`), NOT by constructing them ad-hoc in code.
 3. 🧠 LOGIC IS BEHAVIORS: gameplay code = small TypeScript Behavior classes,
    registered with `registerBehavior('Name', Class)` and attached in JSON via
    `"script": { "name": "Name" }`. Reach for a BUILT-IN gameplay behavior
-   (Health, Chase, WaveSpawner, DamageOnContact, ScoreKeeper…) before writing
-   your own — this game's only custom behaviors are `Shoot` and `HudUpdater`.
+   before writing your own — this template already uses
+   Health, DamageOnContact, Interactable, PathFollow, DayNight, and its only custom behaviors are
+   `IsleDirector` and `SwordStrike`.
 4. 🔑 UIDS ARE GENERATED: every node uid comes from
    `import { newUid } from 'incanto'`. NEVER invent readable uid strings.
 5. 📦 ASSETS ARE DECLARED: `assets` entries need `type` + `url`; reference
@@ -23,21 +25,40 @@ YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template:
    (Euler XYZ). Negative gravity falls.
 7. 🧲 COLLIDERS ARE PROPS: `"collider": { "shape": "box"|"sphere"|"capsule", … }`
    on a body node — never child shape nodes. Wrong shapes hard-fail at load.
-8. 🖥️ THE HUD IS DOM, NOT NODES: 3D scenes have no 2D `UILayer`/`Label` nodes
-   (those are `incanto/2d`). The HUD + crosshair + banner are plain HTML in
-   `index.html`; `HudUpdater` writes the live numbers into them (guarded so
-   headless runs are a no-op).
-9. 🐛 DEBUG WHEN UNSURE: `physics.debugDraw = true` (the object
-   `enablePhysics3D` returns) draws every collider in the running game; or boot
-   with `?incanto_debug=1` for the live Explorer/Inspector/Stats overlay.
+8. 🖥️ THE HUD IS NODES: this template's HUD lives in the scene as a
+   `HudLayer` with `UiText`/`UiBar` children — the engine builds the DOM for
+   them and positions them by anchor. Edit the HUD in `*.scene.json` like any
+   other node. (A DOM-in-`index.html` HUD is the other valid shape, and what
+   `tps-3d` does; both are supported — do not mix them in one screen.)
+9. 🐛 DEBUG WHEN UNSURE: `VITE_INCANTO_DEBUG=1 bun run dev` adds the ☰ debug
+   menu — Explorer/Inspector (click a node, see and edit its live props), Logs,
+   Stats and Colliders (every physics shape as a wireframe, drawn by the same
+   Rapier the game runs). There is NO `VITE_INCANTO_DEBUG=1` URL toggle: it was
+   removed as deploy-unsafe. Never ship the env flag on.
 10. 🎬 DELTA DISCIPLINE: only write props that differ from defaults — the
     loader treats unknown/garbage props as hard errors, which is your friend.
-11. ✅ VERIFY LIKE A USER: `bun run check` validates the scene, `bun run verify`
-    proves the loop headlessly, then `bun run dev` and actually PLAY what you
-    changed (move, shoot, clear a wave) before declaring it done.
-12. 🔍 X-RAY WHEN IT LOOKS WRONG: `VITE_INCANTO_DEBUG=1 bun run dev` adds a ☰
-    debug menu — Explorer/Inspector (click a node, see and edit its live props),
-    Logs, Stats (fps · tris · draw calls) and Colliders (every physics shape as
-    wireframe). Blocked in mid-air or falling through the floor is a Colliders
-    question; a mystery frame-rate is a Stats question. Never ship the flag on.
+11. ✅ VERIFY LIKE A USER, THEN READ THE FOUR SIGNALS. `bun run check` and
+    `bun run verify` are the start, not the end — you cannot SEE this game, and
+    each of these answers a failure that otherwise looks like nothing at all:
+
+    | read | it is not clean when |
+    | --- | --- |
+    | `bunx incanto-check` | the scene will not load, or renders black (no light) |
+    | `stats().errors` | something threw and was skipped to keep the game alive |
+    | `assetErrors()` | a model or texture 404'd — the thing is simply not there |
+    | `framing` | the camera points the wrong way, or nothing is lit |
+
+    ```bash
+    printf 'step 500\nframing\nquit\n' | bunx incanto-play src/game.scene.json
+    ```
+
+    `framing` reports what the camera SEES — on screen / off screen / behind it
+    — plus what lights the scene and which colliders intersect. `behind` looks
+    exactly like "my model did not load"; nothing else can tell you apart.
+    Then `bun run dev` and actually PLAY what you changed.
+12. 🧯 A THROWN ERROR NO LONGER STOPS THE GAME: a behavior that throws is
+    reported once (node, script, phase, file:line) and SKIPPED — your script
+    stops, the node it is attached to keeps running, the game plays on. So a
+    game that looks fine can still be broken: read `stats().errors`, and
+    `engine.resumeErroredNodes()` after you fix it.
 </userRequest>

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.31.0",
+    "incanto": "^0.33.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/tps-3d/docs/project-3d-rules.md

@@ -5,15 +5,17 @@ YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template:
    manual, version-pinned to what is installed. Start with
    `incanto-building-3d-games.md`, `incanto-3d-character.md`,
    `incanto-gameplay-behaviors.md`, `incanto-environment.md` and
-   `incanto-audio.md` — this template composes all five.
+   `incanto-audio.md` — this template composes them —
+   and FINISH with `incanto-verifying-your-game.md` (rule 11).
 2. 🧱 STRUCTURE IS JSON: scenes, nodes, props, assets, input maps and
-   replication all live in `src/game.scene.json`. Add nodes there (or with
+   replication all live in `src/*.scene.json`. Add nodes there (or with
    `npx incanto-editor`), NOT by constructing them ad-hoc in code.
 3. 🧠 LOGIC IS BEHAVIORS: gameplay code = small TypeScript Behavior classes,
    registered with `registerBehavior('Name', Class)` and attached in JSON via
    `"script": { "name": "Name" }`. Reach for a BUILT-IN gameplay behavior
-   (Health, Chase, WaveSpawner, DamageOnContact, ScoreKeeper…) before writing
-   your own — this game's only custom behaviors are `Shoot` and `HudUpdater`.
+   before writing your own — this template already uses
+   Health, DamageOnContact, Chase, WaveSpawner, ScoreKeeper, and its only custom behaviors are
+   `Shoot` and `HudUpdater`.
 4. 🔑 UIDS ARE GENERATED: every node uid comes from
    `import { newUid } from 'incanto'`. NEVER invent readable uid strings.
 5. 📦 ASSETS ARE DECLARED: `assets` entries need `type` + `url`; reference
@@ -23,21 +25,41 @@ YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template:
    (Euler XYZ). Negative gravity falls.
 7. 🧲 COLLIDERS ARE PROPS: `"collider": { "shape": "box"|"sphere"|"capsule", … }`
    on a body node — never child shape nodes. Wrong shapes hard-fail at load.
-8. 🖥️ THE HUD IS DOM, NOT NODES: 3D scenes have no 2D `UILayer`/`Label` nodes
-   (those are `incanto/2d`). The HUD + crosshair + banner are plain HTML in
-   `index.html`; `HudUpdater` writes the live numbers into them (guarded so
-   headless runs are a no-op).
-9. 🐛 DEBUG WHEN UNSURE: `physics.debugDraw = true` (the object
-   `enablePhysics3D` returns) draws every collider in the running game; or boot
-   with `?incanto_debug=1` for the live Explorer/Inspector/Stats overlay.
+8. 🖥️ THE HUD IS DOM HERE: this template's HUD, crosshair and banner are
+   plain HTML in `index.html`, and `HudUpdater` writes the live numbers into
+   them (guarded, so headless runs are a no-op). That is a CHOICE, not a
+   limit — `HudLayer` + `UiText`/`UiBar` nodes work in 3D scenes too (see
+   `incanto-hud.md`, and the `beacon-isle-3d` template). Do not mix them in
+   one screen.
+9. 🐛 DEBUG WHEN UNSURE: `VITE_INCANTO_DEBUG=1 bun run dev` adds the ☰ debug
+   menu — Explorer/Inspector (click a node, see and edit its live props), Logs,
+   Stats and Colliders (every physics shape as a wireframe, drawn by the same
+   Rapier the game runs). There is NO `VITE_INCANTO_DEBUG=1` URL toggle: it was
+   removed as deploy-unsafe. Never ship the env flag on.
 10. 🎬 DELTA DISCIPLINE: only write props that differ from defaults — the
     loader treats unknown/garbage props as hard errors, which is your friend.
-11. ✅ VERIFY LIKE A USER: `bun run check` validates the scene, `bun run verify`
-    proves the loop headlessly, then `bun run dev` and actually PLAY what you
-    changed (move, shoot, clear a wave) before declaring it done.
-12. 🔍 X-RAY WHEN IT LOOKS WRONG: `VITE_INCANTO_DEBUG=1 bun run dev` adds a ☰
-    debug menu — Explorer/Inspector (click a node, see and edit its live props),
-    Logs, Stats (fps · tris · draw calls) and Colliders (every physics shape as
-    wireframe). Blocked in mid-air or falling through the floor is a Colliders
-    question; a mystery frame-rate is a Stats question. Never ship the flag on.
+11. ✅ VERIFY LIKE A USER, THEN READ THE FOUR SIGNALS. `bun run check` and
+    `bun run verify` are the start, not the end — you cannot SEE this game, and
+    each of these answers a failure that otherwise looks like nothing at all:
+
+    | read | it is not clean when |
+    | --- | --- |
+    | `bunx incanto-check` | the scene will not load, or renders black (no light) |
+    | `stats().errors` | something threw and was skipped to keep the game alive |
+    | `assetErrors()` | a model or texture 404'd — the thing is simply not there |
+    | `framing` | the camera points the wrong way, or nothing is lit |
+
+    ```bash
+    printf 'step 500\nframing\nquit\n' | bunx incanto-play src/game.scene.json
+    ```
+
+    `framing` reports what the camera SEES — on screen / off screen / behind it
+    — plus what lights the scene and which colliders intersect. `behind` looks
+    exactly like "my model did not load"; nothing else can tell you apart.
+    Then `bun run dev` and actually PLAY what you changed.
+12. 🧯 A THROWN ERROR NO LONGER STOPS THE GAME: a behavior that throws is
+    reported once (node, script, phase, file:line) and SKIPPED — your script
+    stops, the node it is attached to keeps running, the game plays on. So a
+    game that looks fine can still be broken: read `stats().errors`, and
+    `engine.resumeErroredNodes()` after you fix it.
 </userRequest>

package/templates-app/tps-3d/package.json

@@ -13,7 +13,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.31.0",
+    "incanto": "^0.33.0",
     "three": "^0.184.0"
   },
   "devDependencies": {