incanto 0.51.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-CUc1U7wm.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.51.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-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-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 -----------------------------------------------------------------
 

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

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

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