incanto 0.32.0 → 0.34.0

package/skills/incanto-audio.md

@@ -330,3 +330,46 @@ this.tree.engine.music.crossfadeTo('incanto/assets/audio/boss.mp3', 3);
 - **Global volume / mute / settings** → `engine.audio.master/sfx/music/muted`.
 - **Verifying headlessly** → audio is a no-op in the VM; assert `play()` doesn't
   throw and check your gameplay/score logic instead (see incanto-verifying).
+
+## Settings that survive a reload (`engine.settings`)
+
+Every player's volume used to reset on every page load: `createSaveStore` was
+good and had zero callers, and eight examples set `engine.audio.music = 0.5` at
+boot without reading a saved value.
+
+`createGame2D/3D` now binds them, so **a slider that writes `engine.audio.music`
+has already saved it** — no extra call, which is the promise this skill was
+already making.
+
+```ts
+engine.settings.get('quality');            // 'low' | 'medium' | 'high'
+engine.settings.set('sensitivity', 1.4);
+engine.settings.all();                     // the whole options screen at once
+engine.settings.reset();
+engine.settings.changed.connect((k) => …); // k is the key that changed
+```
+
+Stored keys: `master`, `sfx`, `music`, `muted`, `quality`, `sensitivity`,
+`invertY`, `reduceMotion`. Setting a value that has not changed does NOT emit,
+and a corrupt/hand-edited `quality` falls back to the default instead of
+bricking the game.
+
+### Quality tiers
+
+```ts
+import { qualityEnvironment, readDeviceHints, suggestQuality, setEnvironment3D } from 'incanto';
+
+const tier = engine.settings.get('quality') ?? suggestQuality(readDeviceHints());
+setEnvironment3D(engine, qualityEnvironment(tier));
+```
+
+`qualityEnvironment(tier)` is an **environment patch**, not a second rendering
+pipeline: `setEnvironment3D` already applies one live and validated. `low` turns
+off shadows/bloom/post/clouds and pins pixelRatio to 1; `medium` keeps shadows
+but makes them static (measured ~42% of a dense-forest frame); `high` is
+everything at device pixel ratio.
+
+`suggestQuality(readDeviceHints())` picks a STARTING point from cores, memory and
+a coarse pointer — the options menu is the real answer, and a `UiSelect` bound to
+`quality` is the whole options row (see `incanto-hud.md`).
+

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

@@ -293,3 +293,39 @@ 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.
+
+## Platformer game feel (CharacterController2D)
+
+A jump that only fires while `isOnFloor()` is true feels BROKEN, and players do
+not report it as "the coyote time is missing" — they report the game as
+unresponsive. These are the constants `examples/platformer-2d` hand-rolls in a
+541-line behavior, as props. **Every one defaults to off**, so an existing scene
+behaves exactly as before.
+
+| prop | default | what it buys |
+| --- | --- | --- |
+| `coyoteSeconds` | `0` | jump for this long AFTER walking off a ledge — the single biggest one |
+| `jumpBufferSeconds` | `0` | a press just BEFORE landing still fires on touchdown |
+| `jumpCutMultiplier` | `1` | release early → rise less (variable jump height) |
+| `maxJumps` | `1` | `2` = double jump. Walking off a ledge spends the ground jump |
+| `dashSpeed` / `dashSeconds` / `dashAction` | `0` / `0.15` / `dash` | a straight-line dash |
+| `wallSlideSpeed` | `0` | capped fall while against a wall |
+| `wallJumpImpulse` | `[0, 0]` | `[away, up]` push off a wall |
+
+```json
+{ "name": "Controller", "type": "CharacterController2D",
+  "props": { "coyoteSeconds": 0.12, "jumpBufferSeconds": 0.15,
+             "jumpCutMultiplier": 0.45, "maxJumps": 2,
+             "wallSlideSpeed": 60, "wallJumpImpulse": [260, 380] } }
+```
+
+**`movementStateChanged(state)`** fires on every change — `idle` · `run` ·
+`jump` · `fall` · `wallSlide` · `dash` — so an `AnimatedSprite2D` follows the
+character from scene JSON instead of a behavior polling velocities. The 3D
+sibling has had this signal since it shipped.
+
+Wall moves need to know there IS a wall: `CharacterBody2D` now answers
+`isOnWall()`, `wallSide()` (-1 left / +1 right) and `isOnCeiling()` as well as
+`isOnFloor()`. Before, the floor was the only surface a character could report,
+which is why a wall jump was not awkward to write but impossible.
+

package/skills/incanto-hud.md

@@ -80,3 +80,100 @@ 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": { "text": "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.
+
+## Playable on a controller (focus navigation)
+
+A menu you can only click is not playable on a gamepad, and "add controller
+support" was not something a JSON scene could express at all.
+
+```json
+{ "name": "Hud", "type": "HudLayer", "props": { "focusNavigation": true }, "children": [ … ] }
+```
+
+Arrow keys / d-pad move the focus between the **focusable** widgets under that
+layer, `Enter` / `A` activates, and the focused one wears a ring.
+`UiButton`/`UiSlider`/`UiToggle`/`UiSelect` are focusable by default;
+`UiText`/`UiBar`/`UiImage`/`UiPanel` are not, so arrowing never lands on a label.
+
+What activation MEANS is per widget: a button presses, a toggle flips (left/right
+sets it explicitly, which reads better on a pad), a select walks its list, a
+slider nudges by one `step`.
+
+**It is OFF by default**, deliberately: a game whose HUD happens to contain a
+button must not lose its arrow keys the moment one exists. Turn it on for the
+screens that ARE menus and off again when play resumes —
+`hud.focusNavigation = false`. `hud.focus(widget)` sets the starting item, since
+opening a menu should land somewhere rather than nowhere.
+
+The gamepad codes are the ones the engine already produces from a pad
+(`Pad12`–`Pad15` d-pad, `Pad0` = A), so nothing extra is declared.
+
+## Dragging things between slots (inventory)
+
+An inventory is the one screen where "click it" is not enough, and every game
+that wanted one dropped out of scene JSON to hand-roll pointer handlers. Two
+props and four signals, on the widgets you already have — no new node type:
+
+```json
+{ "name": "SlotA", "type": "UiPanel", "props": { "dropTarget": true }, "children": [
+  { "name": "Potion", "type": "UiImage", "props": { "src": "$potion", "draggable": true } }
+] },
+{ "name": "SlotB", "type": "UiPanel", "props": { "dropTarget": true } }
+```
+
+| signal | on | args |
+| --- | --- | --- |
+| `dragStarted` | the dragged widget | itself |
+| `droppedOn` | the dragged widget | the target it landed on |
+| `dropped` | the drop target | the widget that landed |
+| `dragCancelled` | the dragged widget | itself (landed on nothing) |
+
+Both ends are told, because both usually have work to do: the item leaves its old
+slot, the slot takes it. **Who owns the item is your game's business** — these
+report the GESTURE, not a model, so an inventory that stacks, swaps or refuses is
+your `connections` and a behavior, not a prop nobody could have guessed.
+
+A drop on a CHILD of a slot counts as a drop on the slot (the cursor lands on the
+icon inside it, which is the normal case), a drop on nothing cancels, and a
+widget never drops onto itself.
+

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`
 
@@ -383,6 +394,7 @@ Signals: `movementStateChanged(state)`
 |---|---|---|
 | `zIndex` | `100` | number |
 | `visible` | `true` | boolean |
+| `focusNavigation` | `false` | boolean |
 
 ## `InstancedMesh3D` — `incanto/3d`
 
@@ -912,10 +924,13 @@ Signals: `timeout`
 |---|---|---|
 | `anchor` | `"center"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
 | `visible` | `true` | boolean |
+| `focusable` | `false` | boolean |
+| `draggable` | `false` | boolean |
+| `dropTarget` | `false` | boolean |
 | `size` | `42` | number |
 | `seconds` | `2` | number |
 
-Signals: `bannerShown`
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `bannerShown`
 
 ## `UiBar` — `incanto`
 
@@ -923,6 +938,9 @@ Signals: `bannerShown`
 |---|---|---|
 | `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
 | `visible` | `true` | boolean |
+| `focusable` | `false` | boolean |
+| `draggable` | `false` | boolean |
+| `dropTarget` | `false` | boolean |
 | `value` | `100` | number |
 | `max` | `100` | number |
 | `width` | `180` | number |
@@ -933,19 +951,24 @@ Signals: `bannerShown`
 | `background` | `"rgba(0,0,0,0.5)"` | string |
 | `label` | `""` | string |
 
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped`
+
 ## `UiButton` — `incanto`
 
 | Prop | Default | Kind |
 |---|---|---|
 | `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
 | `visible` | `true` | boolean |
+| `focusable` | `true` | boolean |
+| `draggable` | `false` | boolean |
+| `dropTarget` | `false` | boolean |
 | `text` | `"OK"` | string |
 | `size` | `16` | number |
 | `color` | `"#ffffff"` | string |
 | `background` | `"rgba(255,255,255,0.14)"` | string |
 | `disabled` | `false` | boolean |
 
-Signals: `pressed`
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `pressed`
 
 ## `UiDialogue` — `incanto`
 
@@ -953,10 +976,86 @@ Signals: `pressed`
 |---|---|---|
 | `anchor` | `"bottom"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
 | `visible` | `true` | boolean |
+| `focusable` | `false` | boolean |
+| `draggable` | `false` | boolean |
+| `dropTarget` | `false` | boolean |
 | `charsPerSecond` | `40` | number |
 | `width` | `520` | number |
 
-Signals: `lineShown` · `choiceMade` · `dialogueFinished`
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `lineShown` · `choiceMade` · `dialogueFinished`
+
+## `UiImage` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `focusable` | `false` | boolean |
+| `draggable` | `false` | boolean |
+| `dropTarget` | `false` | boolean |
+| `src` | `""` | string |
+| `width` | `48` | number |
+| `height` | `48` | number |
+| `fit` | `"contain"` | one of: `contain` `cover` `fill` |
+| `tint` | `""` | string |
+| `opacity` | `1` | number |
+
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped`
+
+## `UiPanel` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `focusable` | `false` | boolean |
+| `draggable` | `false` | boolean |
+| `dropTarget` | `false` | 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 |
+
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped`
+
+## `UiSelect` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `focusable` | `true` | boolean |
+| `draggable` | `false` | boolean |
+| `dropTarget` | `false` | boolean |
+| `label` | `""` | string |
+| `options` | `""` | string |
+| `value` | `""` | string |
+
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `changed`
+
+## `UiSlider` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `focusable` | `true` | boolean |
+| `draggable` | `false` | boolean |
+| `dropTarget` | `false` | boolean |
+| `label` | `""` | string |
+| `value` | `0.5` | number |
+| `min` | `0` | number |
+| `max` | `1` | number |
+| `step` | `0.01` | number |
+| `width` | `180` | number |
+| `color` | `"#6ee7dc"` | string |
+
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `changed`
 
 ## `UiText` — `incanto`
 
@@ -964,11 +1063,30 @@ Signals: `lineShown` · `choiceMade` · `dialogueFinished`
 |---|---|---|
 | `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
 | `visible` | `true` | boolean |
+| `focusable` | `false` | boolean |
+| `draggable` | `false` | boolean |
+| `dropTarget` | `false` | boolean |
 | `text` | `""` | string |
 | `size` | `16` | number |
 | `color` | `"#ffffff"` | string |
 | `shadow` | `true` | boolean |
 
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped`
+
+## `UiToggle` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `focusable` | `true` | boolean |
+| `draggable` | `false` | boolean |
+| `dropTarget` | `false` | boolean |
+| `label` | `""` | string |
+| `value` | `false` | boolean |
+
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `changed`
+
 ## `VoxelGrid3D` — `incanto/3d`
 
 | Prop | Default | Kind |
@@ -1084,6 +1202,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/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.32.0",
+    "incanto": "^0.34.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.32.0",
+    "incanto": "^0.34.0",
     "three": "^0.184.0"
   },
   "devDependencies": {