incanto 0.51.0 → 0.53.0

package/skills/incanto-multiplayer.md

@@ -58,13 +58,22 @@ Authority rules:
   applies onto the spawned scene's root; `position` lerps when `interpolate: true`
   (remote entities render slightly in the past — that's correct). Emits
   `spawned(node, key)` / `despawned(node, key)`. `source: "collection:<id>"` mirrors a
-  room collection by `__id`.
+  room collection by `__id` — a collection ENTITY applies as your server wrote it
+  (`addCollectionItem('coins', { position: [x, y] })` lands on the spawned node;
+  the `{sync: {…}}` envelope an owner state uses is accepted too). A key whose
+  node PATH resolves to nothing (`Skin.animation` on a scene with no `Skin`) is
+  reported once rather than dropped — that value replicates to nowhere.
 
 ## Boot
 
 ```ts
+import { registerNodes2D } from 'incanto/2d';   // or registerNodes3D for a 3D game
 import { NetworkManager, registerNodesNet, LoopbackHub } from 'incanto/net';
 
+// REGISTRARS COMPOSE and you need BOTH: `registerNodesNet()` adds NetworkSpawner
+// and nothing else, so a 2D scene loaded after it alone dies on its own root
+// node (`Unknown node type 'Node2D'`).
+registerNodes2D();
 registerNodesNet();
 const scene = loadScene(json);
 engine.setScene(scene);
@@ -147,8 +156,12 @@ the whole N-panel harness — one LocalGameServer, one engine + NetworkManager
 per player — so you only supply the per-panel renderer/input:
 
 ```ts
+import { registerNodes2D } from 'incanto/2d';   // the dimension your scene uses
 import { createSplitScreen, registerNodesNet } from 'incanto/net';
 
+registerNodes2D();
+registerNodesNet();
+
 const canvases = [document.getElementById('p1'), document.getElementById('p2')];
 const { players, server, dispose } = await createSplitScreen({
   scene: gameJson,                       // shared scene (each panel gets its own copy)
@@ -163,8 +176,13 @@ const { players, server, dispose } = await createSplitScreen({
 });
 ```
 
-The first panel's clock pumps `server.tick` (so `$roomTick` runs) — don't add
-your own. `dispose()` tears every panel down. Going live is unchanged: ONE
+Each panel gets physics on the same terms `createGame2D` gives it (`'auto'`:
+Rapier when the scene has bodies; `physics: false` opts out) — without it a
+`CharacterBody2D` never moves. The first panel's clock pumps `server.tick` (so
+`$roomTick` runs) — don't add your own. Every panel joins ONE room: a shared scene usually says
+`multiplayer: { room: "auto" }`, and "auto" means a server-ASSIGNED room, so the
+harness pins panels 1..N to the room panel 0 got (`room: 'lobby'` overrides).
+`dispose()` tears every panel down. Going live is unchanged: ONE
 client per browser with `createAgent8Server()` as the transport.
 
 It runs the SAME class body the cloud runs: the v2 globals (`$sender`/`$global`/
@@ -172,6 +190,24 @@ It runs the SAME class body the cloud runs: the v2 globals (`$sender`/`$global`/
 (so `this.*` never persists), and calls are serialized (no global leaks across
 `await`s). `$roomTick(deltaMS, roomId)` runs only while a room has users.
 
+**Verifying a whole match**: `playMultiplayer` from `incanto/test` runs N clients
+against one in-memory server for a fixed number of simulated seconds and reports
+what they ended up sharing — rooms, who saw whom, what each `NetworkSpawner`
+materialised, per-client frame errors, the final room state. See
+`incanto-verifying-your-game.md`.
+
+**Driving one by hand**: server calls are QUEUED and only run when the event loop
+turns, so a synchronous frame loop enqueues a thousand ticks that never execute —
+the match clock stands still and every `call()` result arrives after your
+assertions.
+
+```ts
+for (let f = 0; f * 16.7 < ms; f++) {
+  for (const p of players) p.engine.tick(f * 16.7);
+  if (f % 6 === 0) await new Promise((r) => setTimeout(r, 0)); // let the server run
+}
+```
+
 It is a FUNCTIONAL emulator, NOT the platform: no isolated-vm sandbox, no rate
 limits, and no DURABLE persistence (global state lives only for the preview process
 — it is not saved across runs, and rooms still clear when empty). It proves your

package/skills/incanto-node-reference.md

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

@@ -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.
 
@@ -619,6 +621,23 @@ rows until the orange box lands on the thing you're hunting.
 inside a `static` subtree, HUD widgets outside a HudLayer. Programmatic:
 `auditScene(json)` from `incanto` or `incanto/test` returns the warnings.
 
+**Including a node path that points at nothing.** `Chase.target`,
+`Camera2D.follow`, `Spawner.prefab`, `Joint3D.target`, `skinPath`, `terrain` —
+these hold a path to another node, and a wrong one is SILENT: a connection that
+dangles is a hard load error, but a prop resolves with `getNodeOrNull`, so the
+scene opens and the enemy simply never chases.
+
+```
+warn: World/Enemy: Chase.target — '%Playerr' matches no node in this scene.
+      The scene loads and the prop does nothing.
+warn: World/Cam: follow — '/Level/Player' starts at 'Level', but the scene
+      root is 'World' (or write '/root/…'). The scene loads and the prop does nothing.
+```
+
+An empty value is never reported — `""` is the default of most of these and
+means "not set". A behavior of YOUR OWN is not reported either: the checker
+never loads your TypeScript, so it cannot know which of its props are paths.
+
 ## Deterministic replay (record once, regression-test forever)
 
 The engine is fully deterministic under a seed + injected clock, so a
@@ -644,6 +663,61 @@ 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
+whether there are two of them in the same room at all — and when there are not,
+nothing throws, nothing logs, and each browser looks perfectly fine on its own.
+
+```ts
+import { playMultiplayer, multiplayText } from 'incanto/test';
+import { Server } from '../server/src/server';   // your real server class
+
+const report = await playMultiplayer({
+  scene: gameJson,
+  server: Server,                                 // optional: runs YOUR rules
+  scenes: { 'remote-player': remoteJson },
+  players: 2,
+  seconds: 5,
+  drive: ({ engine, manager, account }, frame) => {
+    engine.input.setActionVector('move', 1, 0);   // steer each client
+  },
+});
+console.log(multiplayText(report));
+```
+
+```
+multiplayer: 2 clients, 5s, room room1
+  p1: sees [p2] spawned Remotes=1
+  p2: sees [p1] spawned Remotes=1
+  ✓ every client in one room, seeing the others
+```
+
+`report.problems` names the silent ones: clients in different rooms, a client
+that never saw another account's state, a `NetworkSpawner` that materialised
+nothing, frame errors per client. `report.roomState` is the shared state at the
+end, so a `$roomTick` match clock is checkable too.
+
+It runs the whole match on ONE in-memory server (`LocalGameServer`), so it also
+pays the trap a hand-rolled harness has to know about: those server calls are
+QUEUED, and a synchronous frame loop enqueues a thousand ticks that never run.
+
 ## The fifth question: is it a GAME?
 
 The four signals above answer *will it load*, *did something throw*, *did the art

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/agent8-server.ts

@@ -32,27 +32,104 @@
  */
 
 // These globals are injected by the agent8 isolated-vm runtime (see gameserver-sdk-v2).
-declare const $sender: { account: string; roomId: string };
+declare const $sender: { account: string; roomId: string; isGuest?: boolean };
+
+/**
+ * Room membership, PERSISTENT global state, global collections, room management
+ * and global messaging. Room data is ephemeral — anything that must outlive an
+ * empty room is written here.
+ */
 declare const $global: {
   joinRoom(roomId?: string): Promise<string>;
   leaveRoom(): Promise<string>;
+  getGlobalState(): Promise<Record<string, unknown>>;
+  updateGlobalState(patch: Record<string, unknown>): Promise<Record<string, unknown>>;
+  getMyState(): Promise<Record<string, unknown>>;
+  updateMyState(patch: Record<string, unknown>): Promise<Record<string, unknown>>;
+  getUserState(account: string): Promise<Record<string, unknown>>;
+  updateUserState(account: string, patch: Record<string, unknown>): Promise<Record<string, unknown>>;
+  addCollectionItem(collectionId: string, item: Record<string, unknown>): Promise<{ __id: string }>;
+  updateCollectionItem(
+    collectionId: string,
+    item: Record<string, unknown>,
+  ): Promise<{ __id: string }>;
+  deleteCollectionItem(collectionId: string, itemId: string): Promise<{ __id: string }>;
+  deleteCollection(collectionId: string): Promise<string>;
+  getCollectionItem(collectionId: string, itemId: string): Promise<Record<string, unknown>>;
+  getCollectionItems(
+    collectionId: string,
+    options?: CollectionQuery,
+  ): Promise<Record<string, unknown>[]>;
+  countCollectionItems(collectionId: string, options?: CollectionQuery): Promise<number>;
+  countRooms(): Promise<number>;
+  getAllRoomIds(): Promise<string[]>;
+  getAllRoomStates(): Promise<Record<string, unknown>[]>;
+  getRoomUserAccounts(roomId: string): Promise<string[]>;
+  countRoomUsers(roomId: string): Promise<number>;
+  getRoomState(roomId: string): Promise<Record<string, unknown>>;
+  updateRoomState(roomId: string, patch: Record<string, unknown>): Promise<Record<string, unknown>>;
+  getRoomUserState(roomId: string, account: string): Promise<Record<string, unknown>>;
+  updateRoomUserState(
+    roomId: string,
+    account: string,
+    patch: Record<string, unknown>,
+  ): Promise<Record<string, unknown>>;
+  broadcastToAll(type: string, message: unknown): void;
+  sendMessageToUser(account: string, type: string, message: unknown): void;
 };
+
+/** Query options for a collection read (`filters` / `orderBy` / `limit`). */
+interface CollectionQuery {
+  filters?: Record<string, unknown>;
+  orderBy?: { field: string; direction?: 'asc' | 'desc' };
+  limit?: number;
+}
+
+/** The CURRENT room: shared state, per-user state, collections, messaging. */
 declare const $room: {
+  getMyState(): Promise<Record<string, unknown>>;
   updateMyState(patch: Record<string, unknown>): Promise<Record<string, unknown>>;
+  getRoomState(): Promise<Record<string, unknown>>;
   updateRoomState(patch: Record<string, unknown>): Promise<Record<string, unknown>>;
   getUserState(account: string): Promise<Record<string, unknown>>;
   updateUserState(account: string, patch: Record<string, unknown>): Promise<Record<string, unknown>>;
+  getAllUserStates(): Promise<Record<string, unknown>[]>;
+  countUsers(): Promise<number>;
   addCollectionItem(collectionId: string, item: Record<string, unknown>): Promise<{ __id: string }>;
   updateCollectionItem(
     collectionId: string,
     item: Record<string, unknown>,
   ): Promise<{ __id: string }>;
   deleteCollectionItem(collectionId: string, itemId: string): Promise<{ __id: string }>;
+  deleteCollection(collectionId: string): Promise<string>;
+  getCollectionItem(collectionId: string, itemId: string): Promise<Record<string, unknown>>;
+  getCollectionItems(
+    collectionId: string,
+    options?: CollectionQuery,
+  ): Promise<Record<string, unknown>[]>;
+  countCollectionItems(collectionId: string, options?: CollectionQuery): Promise<number>;
   broadcastToRoom(type: string, message: unknown): void;
-  countUsers(): Promise<number>;
+  sendMessageToUser(account: string, type: string, message: unknown): void;
 };
+
+/**
+ * Serialize a read-modify-write against concurrent requests.
+ *
+ * The preview runs calls one at a time, so a FORGOTTEN lock still passes
+ * locally — live, parallel requests race (double-award, last-write-wins).
+ */
 declare function $lock<T>(key: string, fn: () => T | Promise<T>): Promise<T>;
 
+/** Per-account currency ledger. `burn`/`transfer` throw on an insufficient balance. */
+declare const $asset: {
+  mint(assetId: string, amount: number): Promise<Record<string, unknown>>;
+  burn(assetId: string, amount: number): Promise<Record<string, unknown>>;
+  has(assetId: string, amount: number): Promise<boolean>;
+  get(assetId: string): Promise<number>;
+  getAll(): Promise<Record<string, number>>;
+  transfer(toAccount: string, assetId: string, amount: number): Promise<Record<string, unknown>>;
+};
+
 export class Server {
   // ---- rooms -----------------------------------------------------------------
 

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