npm - incanto - Versions diffs - 0.52.0 → 0.53.0 - Mend

incanto 0.52.0 → 0.53.0

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

Files changed (58) hide show

package/dist/2d.d.ts +51 -3
package/dist/2d.js +3 -3
package/dist/3d.d.ts +9 -3
package/dist/3d.js +4 -4
package/dist/{behavior-uPEuZrUB.d.ts → behavior-Do0Da56m.d.ts} +98 -0
package/dist/{create-game-B_e9hJf7.js → create-game-9D87XaiX.js} +26 -11
package/dist/{create-game-CGnoypjL.js → create-game-CDJ1lVqK.js} +21 -13
package/dist/debug.d.ts +1 -1
package/dist/{duplicate-B-OtSRFL.js → duplicate-MNLMAcbz.js} +1 -1
package/dist/editor.js +14 -0
package/dist/{environment-presets-DSZwsKPs.js → environment-presets-SkGanr2s.js} +2 -2
package/dist/{gameplay-B6jqvYeM.js → gameplay-CRYw_Q-T.js} +2 -2
package/dist/gameplay.d.ts +1 -1
package/dist/gameplay.js +1 -1
package/dist/index.d.ts +177 -5
package/dist/index.js +8 -8
package/dist/{loader-B-Gft32x.js → loader-BTkHYrQn.js} +54 -18
package/dist/{loader-B9iTqs27.d.ts → loader-Cu_7kJDy.d.ts} +1 -1
package/dist/{log-report-lxrQY9cH.js → log-report-CPFm4OXf.js} +0 -0
package/dist/net.d.ts +2 -2
package/dist/net.js +1 -1
package/dist/{pathfinding-CAR9DjQQ.d.ts → pathfinding-HNGFqGUZ.d.ts} +24 -1
package/dist/{physics-2d-Dns-oZlE.js → physics-2d-BhZZ-HAp.js} +2 -2
package/dist/{physics-3d-BhI0ehpe.js → physics-3d-DmyO2oaN.js} +3 -3
package/dist/react.d.ts +1 -1
package/dist/react.js +1 -1
package/dist/{register-DVwlnZAZ.js → register-BTomIiYG.js} +304 -24
package/dist/{register-Trx7WHnD.js → register-DROK2l7J.js} +2 -2
package/dist/{replay-BU1CCM15.d.ts → replay-9Fy6C10F.d.ts} +1 -1
package/dist/{replay-BicPOMX0.js → replay-DYNUL4BU.js} +2 -2
package/dist/{split-screen-CZ9ccBBQ.js → split-screen-CaF9hO7g.js} +2 -2
package/dist/{split-screen-paxkQs_q.d.ts → split-screen-DNmcX1Pz.d.ts} +1 -1
package/dist/{src-5gbZO47I.js → src-C9xyZW7M.js} +1 -1
package/dist/{teardown-ks3d5W9n.js → teardown-Bw2aeyGI.js} +30 -1
package/dist/{test-DAojuFdb.js → test-CJRsciFk.js} +11 -11
package/dist/test.d.ts +4 -4
package/dist/test.js +2 -2
package/dist/{touch-BoNg_MnF.js → touch-BnMyy9tr.js} +4 -4
package/dist/vite.js +2 -2
package/editor/assets/{agent8-CCvckvbw.js → agent8-PlFHzJsh.js} +1 -1
package/editor/assets/{debug-CLNCOnbc.js → debug-CebV7CDW.js} +1 -1
package/editor/assets/{index-Cb5Brupb.js → index-CdbsY31G.js} +91 -91
package/editor/index.html +1 -1
package/package.json +1 -1
package/schemas/scene.schema.json +213 -0
package/skills/incanto-audio.md +97 -10
package/skills/incanto-building-2d-games.md +20 -3
package/skills/incanto-hud.md +7 -0
package/skills/incanto-node-reference.md +34 -0
package/skills/incanto-physics-and-input.md +38 -0
package/skills/incanto-verifying-your-game.md +19 -1
package/skills/incanto-web-integration.md +1 -0
package/templates-app/beacon-isle-3d/index.html +3 -3
package/templates-app/beacon-isle-3d/package.json +1 -1
package/templates-app/tps-3d/index.html +3 -3
package/templates-app/tps-3d/package.json +1 -1
package/templates-app/village-quest-3d/index.html +3 -3
package/templates-app/village-quest-3d/package.json +1 -1

package/editor/index.html CHANGED Viewed

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

package/package.json CHANGED Viewed

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

package/schemas/scene.schema.json CHANGED Viewed

@@ -352,6 +352,9 @@
         {
           "$ref": "#/$defs/UiLanguageSelect"
         },
+        {
+          "$ref": "#/$defs/UiMuteToggle"
+        },
         {
           "$ref": "#/$defs/UiPanel"
         },
@@ -373,6 +376,9 @@
         {
           "$ref": "#/$defs/UiToggle"
         },
+        {
+          "$ref": "#/$defs/UiVolumeSlider"
+        },
         {
           "$ref": "#/$defs/VoxelGrid3D"
         },
@@ -6870,6 +6876,97 @@
       },
       "required": ["name", "type"]
     },
+    "UiMuteToggle": {
+      "type": "object",
+      "x-signals": ["dragStarted", "dragCancelled", "droppedOn", "dropped", "changed"],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "uid": {
+          "type": "string"
+        },
+        "type": {
+          "const": "UiMuteToggle"
+        },
+        "groups": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "tags": {
+          "type": "object"
+        },
+        "props": {
+          "type": "object",
+          "properties": {
+            "anchor": {
+              "type": "string",
+              "enum": [
+                "topLeft",
+                "top",
+                "topRight",
+                "left",
+                "center",
+                "right",
+                "bottomLeft",
+                "bottom",
+                "bottomRight"
+              ],
+              "default": "topLeft"
+            },
+            "visible": {
+              "type": "boolean",
+              "default": true
+            },
+            "focusable": {
+              "type": "boolean",
+              "default": true
+            },
+            "draggable": {
+              "type": "boolean",
+              "default": false
+            },
+            "dropTarget": {
+              "type": "boolean",
+              "default": false
+            },
+            "label": {
+              "type": "string",
+              "default": ""
+            },
+            "value": {
+              "type": "boolean",
+              "default": false
+            }
+          },
+          "additionalProperties": false
+        },
+        "script": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "props": {
+              "type": "object"
+            }
+          },
+          "required": ["name"]
+        },
+        "network": {
+          "type": "object"
+        },
+        "children": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/node"
+          }
+        }
+      },
+      "required": ["name", "type"]
+    },
     "UiPanel": {
       "type": "object",
       "x-signals": ["dragStarted", "dragCancelled", "droppedOn", "dropped"],
@@ -7580,6 +7677,122 @@
       },
       "required": ["name", "type"]
     },
+    "UiVolumeSlider": {
+      "type": "object",
+      "x-signals": ["dragStarted", "dragCancelled", "droppedOn", "dropped", "changed"],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "uid": {
+          "type": "string"
+        },
+        "type": {
+          "const": "UiVolumeSlider"
+        },
+        "groups": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "tags": {
+          "type": "object"
+        },
+        "props": {
+          "type": "object",
+          "properties": {
+            "anchor": {
+              "type": "string",
+              "enum": [
+                "topLeft",
+                "top",
+                "topRight",
+                "left",
+                "center",
+                "right",
+                "bottomLeft",
+                "bottom",
+                "bottomRight"
+              ],
+              "default": "topLeft"
+            },
+            "visible": {
+              "type": "boolean",
+              "default": true
+            },
+            "focusable": {
+              "type": "boolean",
+              "default": true
+            },
+            "draggable": {
+              "type": "boolean",
+              "default": false
+            },
+            "dropTarget": {
+              "type": "boolean",
+              "default": false
+            },
+            "label": {
+              "type": "string",
+              "default": ""
+            },
+            "value": {
+              "type": "number",
+              "default": 0.5
+            },
+            "min": {
+              "type": "number",
+              "default": 0
+            },
+            "max": {
+              "type": "number",
+              "default": 1
+            },
+            "step": {
+              "type": "number",
+              "default": 0.01
+            },
+            "width": {
+              "type": "number",
+              "default": 180
+            },
+            "color": {
+              "type": "string",
+              "default": "#6ee7dc"
+            },
+            "bus": {
+              "type": "string",
+              "enum": ["master", "sfx", "music"],
+              "default": "master"
+            }
+          },
+          "additionalProperties": false
+        },
+        "script": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "props": {
+              "type": "object"
+            }
+          },
+          "required": ["name"]
+        },
+        "network": {
+          "type": "object"
+        },
+        "children": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/node"
+          }
+        }
+      },
+      "required": ["name", "type"]
+    },
     "VoxelGrid3D": {
       "type": "object",
       "x-signals": ["blocksChanged"],

package/skills/incanto-audio.md CHANGED Viewed

@@ -33,7 +33,9 @@ Set `preset` to one of the names below and call `play()`. No files, no loading.
 ```
 ```ts
-const coin = scene.tree.root.getNode('Coin'); // an AudioPlayer
+import type { AudioPlayer } from 'incanto';
+// from a Behavior — `getNode` returns a `Node`, so name the type you asked for
+const coin = this.node.getNode('Coin') as AudioPlayer;
 coin.play();   // synthesizes + plays instantly; rapid calls OVERLAP (no cutoff)
 ```
@@ -145,8 +147,20 @@ presets are fire-and-forget one-shots: they do not emit `finished`.
 Browsers block audio before the first user gesture. `autoplay: true` (or any
 early `play()`) that gets blocked is marked pending; **`createGame2D` /
 `createGame3D` automatically retry every pending player AND resume the WebAudio
-SFX context on the first pointerdown/keydown** — you don't wire anything. A
-blocked play is not an error; it just waits for the gesture.
+SFX context on the first gesture anywhere on the page** — you don't wire
+anything, and a tap on the on-screen touch controls counts (they sit above the
+canvas, not on it). A blocked play is not an error; it just waits.
+**A file the browser CANNOT play is a different thing, and it says so.** A 404 or
+an undecodable clip used to be filed as "waiting for a gesture" too, so it
+retried forever in silence — and a quiet game looks exactly like a game with no
+sound in it. Now it lands in the engine log and in
+**`game.assetErrors()`** (which 2D games can also ask now), beside the textures
+and models that 404'd:
+```
+[incanto] AudioPlayer 'Boom' could not load '/audio/explosion.mp3' — it is silent.
+```
 ### Music: loop a `src` clip on the music bus
@@ -227,7 +241,26 @@ the node declares (default `sfx`); music-ish loops typically set `bus: "music"`.
 Changes apply to currently-playing `src` clips on the next frame and to every new
 sound immediately.
-A settings slider just writes these numbers — no per-node bookkeeping.
+A settings slider just writes these numbers — no per-node bookkeeping. And
+**the slider is a node**, so an audio menu is scene JSON like everything else:
+```json
+{ "name": "Options", "type": "UiPanel", "props": { "anchor": "center" }, "children": [
+  { "name": "Music", "type": "UiVolumeSlider", "props": { "bus": "music" } },
+  { "name": "Sound", "type": "UiVolumeSlider", "props": { "bus": "sfx" } },
+  { "name": "Mute",  "type": "UiMuteToggle" }
+] }
+```
+| node | prop | writes |
+|---|---|---|
+| `UiVolumeSlider` | `bus`: `master` (default) / `sfx` / `music` | `engine.audio[bus]` |
+| `UiMuteToggle` | — | `engine.audio.muted` (checked = silent) |
+No behavior, no `connections`, nothing to save: the buses persist themselves
+(below), and each control follows a change made anywhere else, so two menus can
+never disagree. Left unlabelled a slider names its own bus (`Volume` / `Sound` /
+`Music`, translated when the scene declares `settings.volume.*`).
 ---
@@ -312,15 +345,44 @@ clean fit; the looping-`src` `AudioPlayer` (§2) stays the right tool for a *fix
 background loop authored in scene JSON. Wire `crossfadeTo` from gameplay:
 ```ts
-// e.g. in a behavior when the boss spawns:
-this.tree.engine.music.crossfadeTo('incanto/assets/audio/boss.mp3', 3);
+// e.g. in a behavior when the boss spawns (`this.engine` is the accessor a
+// Behavior has — there is no `this.tree`):
+this.engine.music.crossfadeTo('/audio/boss.mp3', 3);
 ```
-> Large music files are NOT bundled — reference them by URL (see §4). Headless:
-> the manager's state machine still runs (`current` updates) but plays nothing.
+> Large music files are NOT bundled — reference them by URL (see §4).
+**Headless the state machine still runs and `current` still updates** — nothing
+plays, but the question a test has is answerable:
+```ts
+session.engine.music.crossfadeTo('/audio/boss.wav', 2);
+session.step(100);
+session.engine.music.current;            // '/audio/boss.wav'
+session.engine.audio.countOf('/audio/boss.wav');  // 1
+```
 ---
+## Sound stops when the thing making it goes away
+Teardown is SILENCE, and you do not wire it:
+- **A freed node stops its clip.** Swap to level 2 and level 1's looping
+  background `AudioPlayer` stops with it — it used to play on over the new level
+  forever, with its node freed and no handle left to stop it. Being *moved* is
+  not this: a reparented node keeps playing, because reparenting is not
+  destroying.
+- **`game.dispose()` stops the music and every continuous voice**, and hands the
+  AudioContexts back. An SPA that mounts the game a few times would otherwise
+  run out of them (browsers allow only a handful per page).
+So the one thing you still own is a voice you want to outlive a node — and the
+one thing you must NOT rely on is a sound stopping itself because the scene
+changed under it. `engine.music` deliberately survives a scene swap (it belongs
+to the engine, not the scene): call `engine.music.stop(1)` or `crossfadeTo` when
+the music should change.
 ## Decision guide
 - **Need a quick game sound (coin/jump/hit/explosion/…)** → set `preset`. Done.
@@ -332,8 +394,33 @@ this.tree.engine.music.crossfadeTo('incanto/assets/audio/boss.mp3', 3);
 - **3D sound that pans + fades with distance** → `spatial:true` on an
   `AudioPlayer` in a 3D scene (§2b); listener = the active `Camera3D`.
 - **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).
+- **Verifying headlessly** → read the AUDIO RECORD (below). Audio makes no sound
+  in the VM, but the calls still happen, so "did the coin sound fire when the
+  coin was collected?" is answerable there.
+## Verifying sound without hearing it
+```ts
+const session = await createPlaySession(gameJson, {});
+session.engine.audio.clearLog();
+collectACoin();
+session.step(200);
+session.engine.audio.countOf('coin');   // 1
+session.engine.audio.recent();
+// [{ kind: 'preset', name: 'coin', from: '/Game/Player/Coin', bus: 'sfx', at: 1.2 }]
+```
+`recent()` is the last 200 sounds, oldest first — `kind` is `preset` | `src` |
+`music` | `voice`, `name` is the preset name, the clip url or the track,
+`from` is the node path (or `engine.music` / `engine.sfx`), and `bus` is where
+its volume comes from. `countOf(name)` is the assertion you usually want;
+`clearLog()` resets between steps.
+This covers every path: `AudioPlayer.play()` on both the procedural and the
+`src` route, `engine.music.play`/`crossfadeTo`, and `engine.sfx.startVoice`. It
+records the INTENT to play — that the wiring fired — not that a speaker moved;
+for "the file is broken" see `assetErrors()` above.
 ## Settings that survive a reload (`engine.settings`)

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

@@ -200,9 +200,26 @@ listing the valid set. With a viewport design, UI coordinates are design px.
   **incanto-audio.md**.
 - Reference example: [examples/2d-phaser-sprite-character-gravity](https://github.com/rareboe/Incanto/tree/main/examples/2d-phaser-sprite-character-gravity) —
   spritesheet character with a walk/jump/attack behavior state machine.
-- Pointer→world mapping (the InputMap covers keyboard actions; pointer projection is
-  this one-liner):
-  `world = camera.clampedCenter(w,h) + (pointer - viewport/2) / camera.zoom`.
+- **Tap / drag / click**: `createGame2D({ pointer: true })` attaches pointer
+  input — MOUSE, FINGER and pen alike — and then
+  ```ts
+  game.engine.updated.connect(() => {
+    if (!game.engine.input.mouseJustPressed()) return;
+    const at = game.engine.input.pointerPosition();   // canvas px, null until
+    if (!at) return;                                  // a pointer has been seen
+    const world = game.renderer.worldFromScreen(at.x, at.y);   // world px
+    popAt(world);
+  });
+  ```
+  Use `renderer.worldFromScreen` — do NOT hand-roll the projection. It already
+  accounts for the design `viewport`, the letterbox bars and the camera's
+  clamped centre; a formula written against the DESIGN rect is off by
+  `(design − canvas) / 2 / zoom`, which on a 390 px-wide phone showing a 480 px
+  design measured **62 world px** — a finger-and-a-half from what the player
+  touched. Its inverse, `renderer.screenFromWorld(wx, wy)`, pins DOM to the
+  world (see incanto-web-integration).
 ## Game flow recipes

package/skills/incanto-hud.md CHANGED Viewed

@@ -151,6 +151,13 @@ so structure in the tree becomes structure on screen. Panels nest.
 | `UiSlider` | `label`, `value`, `min`, `max`, `step`, `width`, `color` | `changed(value)` |
 | `UiToggle` | `label`, `value` | `changed(bool)` |
 | `UiSelect` | `label`, `options` (`"low,medium,high"`), `value` | `changed(value)` |
+| `UiVolumeSlider` | `bus` (`master`/`sfx`/`music`), plus every `UiSlider` prop | `changed(value)` |
+| `UiMuteToggle` | `label` | `changed(bool)` |
+The last two are **already wired**: they read and write `engine.audio`, which
+persists itself. An audio menu is three nodes and no TypeScript — see
+`incanto-audio.md`. The graphics ones (`UiQualitySelect`, `UiFrameCapSelect`,
+`UiRenderScaleSelect`) and `UiLanguageSelect` work the same way.
 **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

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

@@ -1039,6 +1039,20 @@ Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped`
 Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `changed`
+## `UiMuteToggle` — `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`
 ## `UiPanel` — `incanto`
 | Prop | Default | Kind |
@@ -1155,6 +1169,26 @@ Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped`
 Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `changed`
+## `UiVolumeSlider` — `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 |
+| `bus` | `"master"` | one of: `master` `sfx` `music` |
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `changed`
 ## `VoxelGrid3D` — `incanto/3d`
 | Prop | Default | Kind |

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

@@ -142,6 +142,44 @@ disables; they overlay `touchContainer` — default the canvas's parent, give it
 `position: relative`). Manual boots call `attachTouchControls(engine, container,
 { force? })` from `incanto`. Wrong touch kinds (`"joystick"` on a button) fail at load.
+**Three things a phone needs that a desktop never shows you**, two of which the
+engine now does for you:
+- **The canvas owns its touch gestures.** `createGame2D/3D` set
+  `touch-action: none` (plus no selection/callout) on the canvas, or the browser
+  keeps pan, pinch-zoom and pull-to-refresh over the play surface — a drag meant
+  for aim or a virtual stick SCROLLS THE PAGE instead. `pageGestures: true`
+  gives them back to the browser (a small canvas inside a scrolling article).
+- **The controls clear the phone's furniture.** They sit
+  `calc(24px + env(safe-area-inset-*))` from the edges, off the iPhone home
+  indicator — whose band is also the OS's "leave the app" swipe.
+- **Your PAGE has to opt in**, and this part is yours: `env()` is 0 unless the
+  document says so, and `100vh` is the toolbar-hidden height, so the bottom strip
+  (where the controls are) hides under the browser chrome.
+  ```html
+  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+  <style>
+    html, body { margin: 0; height: 100%; overflow: hidden; }
+    canvas { display: block; width: 100%; height: 100%; }   /* NOT 100vw/100vh */
+  </style>
+  ```
+  Every `incanto-new` template and every runnable example ships exactly this.
+Two more phone facts worth knowing:
+- **Audio unlocks on ANY first gesture** — the canvas, a key, or the on-screen
+  stick and buttons. (Those controls are siblings of the canvas, so their taps
+  never reached it; a game with on-screen controls used to stay silent until the
+  player happened to touch the play area.)
+- **2D renders at `pixelRatio: 1` by default** (Phaser parity — the browser
+  upscales, edges read soft). Phones are 2–3× denser, so a text-heavy or
+  vector-heavy 2D game wants
+  `createGame2D({ pixelRatio: Math.min(devicePixelRatio, 2) })`, or
+  `"environment": { "rendering": { "pixelRatio": "device" } }` in the scene. 3D
+  already defaults to `min(dpr, 2)`; pixel art is usually happier left at 1.
 Collision layers/masks are not in v0 — everything collides with everything; use groups +
 `triggerEnter` filtering for game logic.

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

@@ -314,7 +314,9 @@ 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**
+- `game.assetErrors()` lists every asset that failed **with its reason and ref** —
+  textures, models, AND sounds (an `AudioPlayer` whose `src` the browser cannot
+  play), in 2D and 3D alike
   — the direct answer to "why is my model not there". The store itself is
   reachable as `renderer.assets` in both dimensions.
@@ -661,6 +663,22 @@ never Math.random, dt/`engine.time` never Date.now. Gamepads replay through
 the ACTIONS they were bound to, not raw pad state.
+## Sound: did the right thing sound?
+Audio makes no sound in the VM, but the calls still happen — so the wiring is
+checkable where the game can be run a thousand times:
+```ts
+session.engine.audio.clearLog();
+hitTheEnemy();
+session.step(200);
+expect(session.engine.audio.countOf('hit')).toBe(1);
+```
+`engine.audio.recent()` is the last 200 sounds with their node path, bus and
+time; `countOf(name)` counts one. A clip whose FILE is broken shows up in
+`assetErrors()` instead. Full guide: `incanto-audio.md`.
 ## Multiplayer: do the players end up in the SAME world?
 Every rung above asks about one player. A multiplayer game's first question is

package/skills/incanto-web-integration.md CHANGED Viewed

@@ -59,6 +59,7 @@ Rule of thumb: score/menus/dialogs that look like WEB UI → DOM overlay;
 anything the game itself must own (and runScript must verify) → UILayer.
 Pin a DOM element to a world position: `game.renderer.screenFromWorld(wx, wy)`
+(and `worldFromScreen(sx, sy)` the other way, for taps and clicks)
 each frame (subscribe `engine.updated`), then `transform: translate(x, y)`.
 Perf note: `useNodeProp` deep-compares per frame — subscribe to LEAF values

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

@@ -3,7 +3,7 @@
   <head>
     <meta charset="UTF-8" />
     <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><rect width=%22100%22 height=%22100%22 rx=%2220%22 fill=%22%232a4a6b%22/><text x=%2250%22 y=%2268%22 font-size=%2255%22 text-anchor=%22middle%22 font-family=%22Arial%22 font-weight=%22bold%22 fill=%22%23ffd166%22>bi</text></svg>" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
     <title>Beacon Isle — Incanto 3D template</title>
     <style>
       html,
@@ -17,8 +17,8 @@
       }
       canvas {
         display: block;
-        width: 100vw;
-        height: 100vh;
+        width: 100%;
+        height: 100%;
       }
       .loading-container {
         position: fixed;

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

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

package/templates-app/tps-3d/index.html CHANGED Viewed

@@ -3,7 +3,7 @@
   <head>
     <meta charset="UTF-8" />
     <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><rect width=%22100%22 height=%22100%22 rx=%2220%22 fill=%22%233b6ea5%22/><text x=%2250%22 y=%2268%22 font-size=%2255%22 text-anchor=%22middle%22 font-family=%22Arial%22 font-weight=%22bold%22 fill=%22%236ee7dc%22>vg</text></svg>" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
     <title>Vanguard — Incanto TPS</title>
     <style>
       html,
@@ -17,8 +17,8 @@
       }
       canvas {
         display: block;
-        width: 100vw;
-        height: 100vh;
+        width: 100%;
+        height: 100%;
       }
       .loading-container {
         position: fixed;

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

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

package/templates-app/village-quest-3d/index.html CHANGED Viewed

@@ -3,7 +3,7 @@
   <head>
     <meta charset="UTF-8" />
     <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><rect width=%22100%22 height=%22100%22 rx=%2220%22 fill=%22%234a6b3a%22/><text x=%2250%22 y=%2268%22 font-size=%2255%22 text-anchor=%22middle%22 font-family=%22Arial%22 font-weight=%22bold%22 fill=%22%23ffd166%22>eb</text></svg>" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
     <title>Emberwood — Incanto quest</title>
     <style>
       html,
@@ -17,8 +17,8 @@
       }
       canvas {
         display: block;
-        width: 100vw;
-        height: 100vh;
+        width: 100%;
+        height: 100%;
       }
       .loading-container {
         position: fixed;