incanto 0.52.0 → 0.54.0

package/skills/incanto-node-reference.md

@@ -613,6 +613,7 @@ _No props (structural fields only)._
 | `visible` | `true` | boolean |
 | `preset` | `"custom"` | one of: `custom` `fire` `smoke` `sparks` `fireworks` `explosion` `flash` `lightning` `rain` `snow` `magic` |
 | `emitting` | `true` | boolean |
+| `worldSpace` | `false` | boolean |
 | `rate` | `40` | number |
 | `burst` | `0` | number |
 | `lifetime` | `[0.6,1.2]` | array |
@@ -648,6 +649,7 @@ Signals: `finished`
 | `snapToGround` | `null` | null |
 | `preset` | `"custom"` | one of: `custom` `fire` `smoke` `sparks` `fireworks` `explosion` `flash` `lightning` `rain` `snow` `magic` |
 | `emitting` | `true` | boolean |
+| `worldSpace` | `false` | boolean |
 | `rate` | `40` | number |
 | `burst` | `0` | number |
 | `lifetime` | `[0.6,1.2]` | array |
@@ -1039,6 +1041,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 +1171,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-performance.md

@@ -13,6 +13,37 @@ You do not implement any of this. You decide whether to expose it.
 
 ---
 
+## First: where did the frame go?
+
+A settings menu is what you offer a PLAYER. This is what you ask the game.
+
+```ts
+game.stats();
+// { fps: 31, frameMs: 32.1, nodes: 4210, triangles: 890_000, drawCalls: 340,
+//   phases: { fixedMs: 21.4, updateMs: 2.2, renderMs: 6.1, otherMs: 2.4 } }
+```
+
+`fps` and `frameMs` are a total, and a total has no next question. The four
+slices say which part of the frame to look at:
+
+| slice | what is in it | what to do about it |
+| --- | --- | --- |
+| `fixedMs` | physics and everything on `fixedUpdate` | fewer/simpler colliders, `fixedHz`, sleep distant bodies |
+| `updateMs` | behaviors, node logic, tweens | the per-frame work your game does — profile it in your own code |
+| `renderMs` | the renderer, reported by itself | quality tier, `renderScale`, draw calls, shadows |
+| `otherMs` | the frame MINUS the three above | GC, browser layout, your own rAF work. **Allocations show up here.** |
+
+`otherMs` is the one worth knowing about. A frame drop that everyone reads as a
+GPU problem is often garbage collection, and it looks identical from the outside
+— this engine lost a day to exactly that. A big `otherMs` with small everything
+else means you are allocating per frame: replace arrays and objects created in
+`update()` with reused ones.
+
+Averages over the same rolling window as `frameMs`, so the numbers add up to it
+and are comparable to each other. Headless (`step()`), `fps`/`frameMs` are 0 and
+the slices are still real CPU times — a behavior that got slower shows up in a
+test.
+
 ## The short version
 
 ```ts
@@ -32,6 +63,22 @@ Every one of those is written to the save store and comes back on the next launc
 
 ---
 
+## Leaks: a level swap has to give the GPU back
+
+`stats().geometries` and `stats().textures` are the leak witnesses — they count
+what three is holding right now. Swap levels a few times and read them again:
+
+```ts
+const before = game.stats().geometries;
+await loadLevel(2);
+await loadLevel(1);
+game.stats().geometries; // should be ~before, not 2x before
+```
+
+Every node that builds geometry releases it when it is freed, and a scene swap
+frees the old tree. If your own code holds a three object (a custom behavior
+that built a mesh), dispose it in the behavior's `onExitTree`.
+
 ## The four levers, and what each actually costs
 
 | setting | values | costs | changes live |

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

@@ -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

@@ -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,53 @@ 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`.
+
+## Speed: which part of the frame is expensive?
+
+```ts
+game.stats().phases;
+// { fixedMs: 21.4, updateMs: 2.2, renderMs: 6.1, otherMs: 2.4 }
+```
+
+Physics, behaviors, the renderer, and everything else. The last one is where GC
+and per-frame allocation hide, and it is the slice a screenshot can never show.
+See `incanto-performance.md`.
+
+## Sight: did the right thing SHOW?
+
+The same question as sound, about the other half of a game's feedback. Nothing
+renders in the VM, so shake, flash and freeze frames are no-ops and a particle
+system that never fired sits at exactly the same coordinates as one that fired a
+hundred times — `framing()` reports WHERE an emitter is, never whether it went
+off.
+
+```ts
+session.engine.effects.clearLog();
+smashTheCrystal();
+session.step(200);
+expect(session.engine.effects.countOf('explosion')).toBe(1);
+```
+
+`engine.effects.recent()` is the last 200 effects — `kind` (`burst` · `emit` ·
+`shake` · `flash` · `hitstop`), the preset or colour, the node path, and how big.
+`countFrom(path)` asks about one emitter, which is usually the wiring question.
+A particle node's `aliveCount` answers the other one: is it running right now.
+
 ## 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

@@ -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

@@ -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

@@ -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.54.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

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

@@ -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

@@ -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.54.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

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

@@ -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;

package/templates-app/village-quest-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.52.0",
+    "incanto": "^0.54.0",
     "three": "^0.184.0"
   },
   "devDependencies": {