incanto 0.50.0 → 0.52.0

package/editor/index.html

@@ -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-Df5g8ofT.js"></script>
+    <script type="module" crossorigin src="./assets/index-Cb5Brupb.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/GameServer-C56iOUgF.js">
   </head>
   <body>

package/package.json

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

package/skills/incanto-assets.md

@@ -164,4 +164,7 @@ Two consequences worth knowing:
 
 A texture that 404s now shows up in `game.assetErrors()` alongside models, by the
 URL you wrote — so "why is my sprite invisible" is answerable without opening the
-network tab.
+network tab. In **2D** the same question is `renderer.assets.errors()`
+(`$ref`, url and reason per failed entry), and the scene EDITOR reads it: a
+failed asset is red in the explorer with the url in its tooltip and the
+consequence in its inspector.

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

@@ -213,8 +213,13 @@ listing the valid set. With a viewport design, UI coordinates are design px.
   ```
   `setScene` frees the old root, clears + redeclares the input map from the new
   scene's `input{}`, and emits `sceneChanged` — `createGame2D`'s touch overlay
-  rebuilds itself on that signal, and the renderer loads the new scene's assets
+  rebuilds itself on that signal, the PHYSICS world registers the new scene's
+  bodies before its first frame, and the renderer loads the new scene's assets
   on demand. Register any extra behaviors/node types BEFORE the `loadScene` call.
+
+  The input map is CLEARED by the swap, which matters for a headless drive: an
+  injected `setActionVector` does not carry into the next level — set it again
+  after the transition, the same way a player's held key is re-read.
 - **Game over / restart**: swap to a fresh load of the SAME JSON —
   `engine.setScene(loadScene(levelJson))`. `loadScene` treats the JSON as
   read-only (everything it keeps is cloned), so reloading the same imported

package/skills/incanto-editor.md

@@ -39,13 +39,17 @@ The `scenes` button opens the project as a tree, not a list of paths:
 - **The scene you are editing** is marked and revealed, and the cursor starts on it.
 - **A filter box** — type any part of a path; matches show wherever they are hiding.
   Keyboard from that box: `↑↓` move · `→` open a folder · `←` close it · `⏎` load ·
-  `Esc` close (backdrop and ✕ work too).
+  `Esc` close (backdrop and ✕ work too). The cursor always sits on a SCENE —
+  the first match while you filter, the scene you are editing when you open the
+  panel — so `⏎` loads something without arrowing first.
 - Each row carries **when it was last written and how big it is**, which is usually
   how you recognise the file you were just in.
 - **create** makes a new scene at the path in the box — left empty it uses the
   placeholder, which tracks the folder you are standing in, so a scene lands beside
   its siblings rather than at the project root. Parent dirs are created.
-- Loading another scene while you have unsaved EDITS asks first.
+- Loading another scene while you have unsaved EDITS asks first, and the answer
+  is not only *discard*: **save & open** writes the scene you are leaving and
+  then opens the other one.
 
 **The same browser opens inside a running game.** When the game's dev server serves
 the project's scenes, `☰ debug ▸ ✎ edit this scene` gives you the whole project: the
@@ -66,7 +70,12 @@ is not there. The editor still edits the scene the game booted with meanwhile.
 Opens a local page (default `http://127.0.0.1:5179/`) with three panes:
 
 - **Explorer** — two collapsible sections: **ASSETS** on top (icon rows by
-  type; keys with a `group/` prefix nest under collapsible folders (any depth),
+  type; **an asset the renderer could not FETCH turns red**, with the url in its
+  tooltip and the consequence spelled out when you select it — *"failed to
+  load — every node using $fx/coin draws nothing"* — plus a banner naming all of
+  them. A 404'd texture is otherwise the one failure with no symptom: the scene
+  is structurally perfect, the tree is full, and the viewport draws nothing where
+  the art should be; keys with a `group/` prefix nest under collapsible folders (any depth),
   each showing its recursive asset count — refs are `$group/key`; click the
   icon for a blurb, the row to edit in the inspector; DRAG asset rows onto a
   folder (or the section background = root) to move them — references rewrite
@@ -79,7 +88,14 @@ Opens a local page (default `http://127.0.0.1:5179/`) with three panes:
   to reorder before/after. Dragging a selected row moves the whole selection.
   Illegal drops (engine rules — e.g. a CharacterController2D outside a
   CharacterBody2D) are ROLLED BACK entirely with the error in the banner; the
-  tree never shows a state the engine would reject. Right-click for
+  tree never shows a state the engine would reject.
+  **A reparent does not MOVE anything**: the node keeps its world transform and
+  the editor rewrites the local `position`/`rotation`/`scale` to match (drop a
+  ball at `[3, 0.6, 0]` onto a crate at `[-3, 0.5, 0]` and the ball stays put,
+  holding `[6, 0.1, 0]`). Rotated and scaled parents are handled the same way,
+  and the values that are no longer needed disappear rather than being written
+  as defaults. This is the Godot/Unity/Blender behaviour, and it is what keeps a
+  tree edit from changing the picture. Right-click for
   duplicate / rename (or double-click the name) / cut / copy / paste-as-child /
   delete — all act on the multi-selection. **Rename REPAIRS references**: every
   `connections[].from/to` and every node-path prop pointing at the node (or into
@@ -121,6 +137,12 @@ Opens a local page (default `http://127.0.0.1:5179/`) with three panes:
   scales to 0.25 steps (the readout shows the snapped value).
   2D additionally supports click-pick, body drag, wheel zoom-at-cursor,
   right/middle/Shift-drag pan, Alt+wheel scale, and collider wireframes.
+  **HUD nodes are editable like anything else**: a `UILayer` subtree is posed in
+  screen space rather than world space, and the viewport now picks, outlines and
+  drags it there — click the widget where you SEE it, and its position moves 1:1
+  with the cursor whatever the world zoom is. (Picking used to look only at the
+  world pass, so a HUD could not be selected in the viewport at all, and its
+  outline was drawn wherever the game camera happened to be looking.)
   **`F` frames the SELECTED node** (its whole subtree; a light or empty node has
   no bounds, so the camera goes to it at a readable distance) — and the whole
   scene when nothing is selected, which is the Maya/Unity/Unreal meaning of the
@@ -136,9 +158,25 @@ Opens a local page (default `http://127.0.0.1:5179/`) with three panes:
 - **Inspector** — schema-driven from the node registry, with STRUCTURED editors for
   the hard parts: `collider` (shape dropdown + per-shape dimensions, mirrored by
   the wireframe), `network` (mode dropdown + sync-key chips + throttle),
-  `script` (attach/detach + name + props, with copy-paste Behavior boilerplate in
-  its help), `groups` (tag chips). Every one has a `?` help popover with examples.
-  Values equal to the default are removed (delta-only, like the serializer).
+  `script` — **the behaviors the engine SHIPS are a dropdown**, and picking one
+  builds a form from its own prop schema (a `Health` gets `max`/`regenPerSec`/
+  `invulnerableFor`/`freeOnDeath` with their defaults; a `Patrol`'s `mode` is a
+  `loop`/`pingpong` menu), delta-only like every other field. A name that is NOT
+  built in is your game's TypeScript: it keeps the raw-JSON props box and says
+  so, with copy-paste Behavior boilerplate in its help — and `groups` (tag
+  chips). Every one has a `?` help popover with examples. Values equal to the
+  default are removed (delta-only, like the serializer).
+  **A prop that holds a NODE PATH** (`Chase.target`, `Camera2D.follow`,
+  `Spawner.prefab`, `Joint3D.target`, `skinPath`, `terrain`…) offers every node
+  in the scene as a list — `%Name` where the name is unique, the absolute path
+  where it repeats — and free text still works for the forms a list cannot
+  enumerate (`../Skin`, a path into a subtree). A value that resolves to NOTHING
+  is marked red with the reason: `'%Playerr' matches no node in this scene. The
+  scene still loads — the prop just does nothing.` That last sentence is the
+  point: unlike a connection, a dangling path prop is not a load error, so
+  nothing else would ever have told you. A behavior's path props are checked
+  exactly like the node's own, and `incanto-check` reports the same thing from
+  the file.
 
 **3D scenes** get full camera navigation: drag orbits, right/middle/Shift-drag pans,
 wheel zooms, `F` frames the contents, and **`0` / the `game cam` button** returns to the
@@ -353,8 +391,7 @@ get normal click-select back.
 The **✦ button** beside the add-node controls opens the Generate dialog — the
 `incanto/env` generators inside the editor, driven by the same `GENERATORS`
 catalog as the `incanto-env` CLI and filtered to the open scene's dimension
-(3D: arena, terrain, meadow, forest, maze, rocks, clouds, island; 2D:
-platforms2d, maze2d, dungeon2d). The param form is built from the catalog
+(3D: arena, terrain, maze; 2D: platforms2d, maze2d, dungeon2d). The param form is built from the catalog
 metadata — numbers clamp to their min/max, option lists become dropdowns — so
 a new generator needs zero editor changes. The seed starts random (↻ rerolls);
 the same seed always generates the same level. **insert** runs the generator
@@ -395,7 +432,7 @@ trusts the surrounding network — use it only inside containers.
 The EDIT view freezes game time — nothing falls or fires until you press play;
 only ambient visuals (model animations, particles, water, foliage sway) keep
 moving. The PLAY view simulates everything engine-native but cannot execute the
-game's TypeScript behaviors. 3D scenes render and edit via the inspector; direct
-viewport manipulation is 2D-only for now. Runtime-injected textures (asset URLs
+game's TypeScript behaviors. Both dimensions have the W/E/R gizmos in the
+viewport; 2D additionally has click-pick, body drag and wheel zoom-at-cursor. Runtime-injected textures (asset URLs
 like `"GENERATED_AT_RUNTIME"`) render as a magenta checkerboard — position/size
 stay visible; the real art appears in the running game.

package/skills/incanto-gameplay-behaviors.md

@@ -58,11 +58,20 @@ Two kinds of node path resolve from DIFFERENT origins — mixing them up is the
   enemy (a child of the Spawner) reaches the player with the ABSOLUTE
   `/root/Player`, never a bare `Player` (which would look under the enemy).
 
-Renaming a node in the editor now REWRITES both kinds for you (and reports what
-it changed), so the paths above stay valid across a rename. Hand-edited JSON
-still has to be kept in sync yourself — `bunx incanto-check` catches the
-connections, but a behavior prop pointing at a name that no longer exists
-resolves to null in silence.
+Renaming a node in the editor REWRITES both kinds for you (behavior props
+included) and reports what it changed, and deleting a node lists every reference
+that still points at it before it goes. Hand-edited JSON is covered too:
+**`bunx incanto-check` now reports a node-path prop that leads nowhere** —
+
+```
+warn: World/Enemy: Chase.target — '%Playerr' matches no node in this scene.
+      The scene loads and the prop does nothing.
+```
+
+— which is the one failure that used to be completely silent (a prop path
+resolves with `getNodeOrNull`, so the scene opens and the enemy just never
+chases). `Chase.target` and `FollowCamera.target` are `required`: an EMPTY one
+is a load error naming the node, not a surprise in the browser.
 
 **Never write `/root/<RootName>/...`.** If your root node is named `Game`, the
 path is `/root/Player` — NOT `/root/Game/Player`: `/root/` already *is* the

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

@@ -1422,6 +1422,19 @@ Signals: `collected(value, other)`
 | `direction` | `null` | null |
 | `gravity` | `0` | number |
 
+### `SavePoint`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `game` | `"game"` | string |
+| `slot` | `"1"` | string |
+| `label` | `""` | string |
+| `scene` | `""` | string |
+| `restoreOnReady` | `false` | boolean |
+| `probeOnReady` | `false` | boolean |
+
+Signals: `saved` · `restored` · `noSave` · `hasSave`
+
 ### `ScoreKeeper`
 
 | Prop | Default | Kind |

package/skills/incanto-save-slots.md

@@ -47,6 +47,17 @@ restored.** You resume at the scene's start with stats, inventory, unlocks and
 quest flags intact — a checkpoint save. If your game needs a position, save it:
 `serialize()` returns anything.
 
+**What the run CONSUMED is remembered.** Reloading from the file brings back
+every gem you already picked up, which would let a collect-five-to-win run
+resume at four with five gems on the map. So the save also carries the authored
+uids that are no longer in the tree, under `#freed`, and the restore frees them
+again — collectibles, opened chests, destroyed crates, a named boss. Spawned
+clones never have uids (`duplicateNode` drops them on purpose), so the ledger is
+exactly the authored world.
+
+Those nodes go on the **next frame** (`queueFree`, not an immediate detach), so
+read `report.freed` rather than counting children the instant restore returns.
+
 ## Making a behavior saveable
 
 Two optional hooks, exactly like the other five:
@@ -82,8 +93,17 @@ lives, won/lost), `Collector` (total).
 
 The uid is the join key, because it is the one identifier that survives a rename
 or a reparent. The editor assigns one to every node it touches. A hand-written
-scene may not have them — `engine.captureState()` logs any node that has state to
-save and no uid to key it under.
+scene may not have them, and then the save is silently empty — so
+**`incanto-check` warns about it**, naming each node, long before you write a
+save:
+
+```
+warn: these carry state a save keeps and have no uid to key it under, so the
+      save comes back EMPTY and the load reports no problem: Game (ScoreKeeper),
+      Game/Player (Health). Give each one a "uid" from newUid().
+```
+
+At runtime `engine.captureState()` logs the same thing per node.
 
 Never hand-craft a uid. Use `newUid()`.
 
@@ -120,7 +140,68 @@ It never throws. A save naming a uid this build deleted reports it in
 `report.missing` and restores everything else; refusing to load would mean a
 patch that moves one node deletes everyone's progress.
 
-## A load menu
+## Many levels: the router is three lines, and they are yours
+
+The engine does not route scenes — deliberately, because only your game knows
+what a key means. What it does is record the key, so the routing is a lookup:
+
+```ts
+import { createGame2D, loadScene } from 'incanto';
+import level1 from './level1.scene.json';
+import level2 from './level2.scene.json';
+
+const SCENES: Record<string, unknown> = { level1, level2 };   // key → scene JSON
+
+// New game
+const game = await createGame2D({ canvas, scene: SCENES.level1 });
+
+// Next level — the SavePoint in the new scene writes `level2` from here on
+(game.scene.root.getNode('Flow').behavior as GameFlow).goToScene(SCENES.level2);
+
+// Continue
+const slot = new SaveSlots('chapters').read('1');
+const scene = SCENES[slot?.scene ?? 'level1'];
+const game = await createGame2D({ canvas, scene });
+// then `restoreOnReady: true` on that scene's SavePoint, or call restore()
+```
+
+A `SavePoint` records `scene` as the scene's own `name` unless you set the prop,
+so `level2.scene.json` named `level2` needs no wiring at all. Set `scene`
+explicitly when one file is entered more than one way (`"chapter-2-rescue"`).
+
+**The swap clears the input map** (the new scene declares its own `input{}`), and
+physics registers the new bodies before that scene's first frame — so a
+character walks in level two exactly as it did in level one.
+
+## A title screen, in JSON
+
+A `SavePoint` can ASK without loading. `probeOnReady` fires on the first frame
+and emits `hasSave(label, playtime, scene)` or `noSave`, so the menu wires
+itself:
+
+```json
+{ "name": "Save", "type": "Node", "uid": "n_…",
+  "script": { "name": "SavePoint",
+              "props": { "game": "chapters", "slot": "1", "probeOnReady": true } } }
+```
+```json
+{ "signal": "noSave",  "from": "Save", "to": "HUD/Menu/Continue", "handler": "hide" },
+{ "signal": "noSave",  "from": "Save", "to": "HUD/Menu/SlotInfo", "handler": "hide" },
+{ "signal": "hasSave", "from": "Save", "to": "HUD/Menu/SlotInfo", "handler": "setText" }
+```
+
+With `"format": "Continue: {}"` on that `UiText`, a fresh install shows a menu
+with no Continue button and a save shows `Continue: Chapter 2`. Every HUD widget
+takes `show`/`hide` from a wire (`visible` is a prop, and a connection needs a
+method — the same wall `setText` broke through).
+
+The label leads because that is what a menu shows; an unlabelled slot falls back
+to its scene key, so the line is never blank.
+
+**The button's press is still yours**, and rightly: `pressed → your router`. See
+the three lines above.
+
+## Several slots
 
 ```ts
 for (const slot of slots.all()) {         // newest first
@@ -130,23 +211,64 @@ slots.remove('2');
 slots.clear();                            // "delete all data"
 ```
 
+One `SavePoint` per slot is the declarative version: three nodes with
+`slot: "1" | "2" | "3"`, each probing into its own row of the menu.
+
 ## Checking your coverage
 
 ```ts
-import { behaviorsWithoutSave } from 'incanto';
-console.log(behaviorsWithoutSave(game.engine.scene.root));
+import { behaviorsWithoutSave, savesWithoutUid } from 'incanto';
+console.log(behaviorsWithoutSave(game.engine.scene.root)); // forgot serialize?
+console.log(savesWithoutUid(game.engine.scene.root)); // forgot the uid?
 ```
 
-Names every behavior in the tree that has props and no `serialize`. Not all of
-them are wrong — a behavior that derives everything from time has nothing to
+`behaviorsWithoutSave` names every behavior with props and no `serialize`. Not
+all of them are wrong — one that derives everything from time has nothing to
 save — but it is the list to read before shipping.
 
-## Autosave
+`savesWithoutUid` is the other half, and none of it is debatable: a behavior
+that DOES serialize, on a node with no uid, is state that goes nowhere.
+`incanto-check` catches the built-ins it can recognise from the JSON
+(`Health`, `ScoreKeeper`, `Collector`); a scene file cannot be asked whether
+YOUR behavior serializes, so this walks the live tree and names those too.
 
-There is no autosave node, on purpose: *when* to save is a design decision
-(checkpoint, level end, every 60s, on quit) and only your game knows. Wire it to
-whatever signal marks the moment:
+## Saving from the scene — `SavePoint`
 
+*When* to save is a design decision (checkpoint, level end, on quit) and only
+your game knows — so the scene still chooses, by picking which signal to wire.
+What it does not need any more is a method of your own to wire it to:
+
+```json
+{ "name": "Save", "type": "Node", "uid": "n_…",
+  "script": { "name": "SavePoint",
+              "props": { "game": "vault", "slot": "1", "label": "Chapter 2" } } }
+```
 ```json
-{ "from": "Level/Exit", "signal": "triggerEnter", "to": "Game", "handler": "onCheckpoint" }
+{ "signal": "triggerEnter", "from": "Level/Exit", "to": "Save", "handler": "save" },
+{ "signal": "collected",    "from": "Gems/Gem1",  "to": "Save", "handler": "save" },
+{ "signal": "won",          "from": ".",          "to": "Save", "handler": "save" }
 ```
+
+| prop | default | meaning |
+| --- | --- | --- |
+| `game` | `"game"` | slot namespace — keeps two games on one origin apart |
+| `slot` | `"1"` | which slot this node reads and writes |
+| `label` | `""` | shown in a load menu |
+| `scene` | `""` | the key a loader routes back to (empty = this scene's `name`) |
+| `restoreOnReady` | `false` | read the slot on the first frame — a "Continue" boot |
+
+Methods: `save()` · `restore()` · `clear()` — and `playtime` / `slotScene()` to
+read. Signals: `saved(slot)` · `restored(count)` · **`noSave`**, which is what
+greys out a Continue button.
+
+`restoreOnReady` lands on the **first frame**, not in `onReady`: `onReady` runs
+children-first, so restoring there would hand the score keeper its state back
+and then watch the root's own `onReady` set it to zero.
+
+**A checkpoint wired to `collected` counts that pickup.** `Pickup` queues its
+free before it announces, so a save taken from the handler records the world
+without it — otherwise the gem came back on the next run with the score that
+counted it already banked.
+
+Still your code when the moment is not a signal — every 60 s, on `visibilitychange`,
+on a quit button: call `engine.captureState()` and `slots.write()` yourself.

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

@@ -619,6 +619,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 +661,45 @@ never Math.random, dt/`engine.time` never Date.now. Gamepads replay through
 the ACTIONS they were bound to, not raw pad state.
 
 
+## 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/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 -----------------------------------------------------------------