incanto 0.1.0

package/skills/incanto-multiplayer.md

@@ -0,0 +1,264 @@
+---
+name: incanto-multiplayer
+description: Incanto multiplayer over a pluggable NetworkTransport — NetworkManager, owner replication via scene-JSON network blobs, NetworkSpawner, the built-in Loopback transport, the @agent8/gameserver adapter, and custom transports for any backend. Use when adding multiplayer to a game.
+---
+
+# Multiplayer with Incanto
+
+> Shipped inside the `incanto` npm package — this document always matches the
+> installed engine version. Sibling skills live in `node_modules/incanto/skills/`.
+
+## Mental model
+
+Incanto multiplayer is **transport-agnostic**: the engine speaks one small
+`NetworkTransport` interface, and ANY backend plugs in behind it —
+
+| Transport | When |
+|---|---|
+| `LoopbackTransport` (built in) | offline dev, tests, local split-screen — built-in protocol only, zero infra |
+| `LocalGameServer` (built in) | **PREVIEW**: run your REAL `server/src/server.ts` (custom rules + `$roomTick`) in memory — no cloud, no auth |
+| `createAgent8Server()` (built in) | the agent8/Verse8 platform (`@agent8/gameserver`) — production |
+| your own implementation | any server: Socket.IO, Colyseus, Supabase Realtime, custom WebSocket… |
+
+Three rungs, same game code: **Loopback** (movement/co-presence, no server logic) →
+**LocalGameServer** (your actual server-authoritative `Server` class, run locally) →
+**Agent8** (that same `Server` deployed live). You climb rungs by swapping ONE line —
+the transport — never the game or the server file.
+
+The replication model is **data-authoritative, not simulation-authoritative**: clients own
+their state; the backend stores/relays it (cadence ≥ tens of ms). Design for **casual
+sync** — co-presence, turn-based, racing-with-tolerance. Fast-paced fairness (fighting
+games, physics duels) needs a simulation-authoritative server, which is out of scope.
+
+Authority rules:
+- movement/cosmetics → **owner-authoritative** (the replication below)
+- score/economy/inventory → **server-function-authoritative** (extend `server.js`;
+  `$sender.account` is trustworthy, args are NOT; guard with `$lock`)
+- physics/AI run client-side; one-simulator needs (NPC waves) use the host-client pattern
+
+## Scene JSON
+
+```json
+"multiplayer": { "room": "auto" },
+"root": { ..., "children": [
+  { "name": "Player", "type": "CharacterBody2D",
+    "network": { "mode": "owner", "sync": ["position", "Skin.animation"], "throttleMs": 50 },
+    "children": [ ... ] },
+  { "name": "Remotes", "type": "NetworkSpawner",
+    "props": { "source": "users", "scene": "remote-player" } }
+] }
+```
+
+- **ONE owner node per player.** Its `sync` keys are relative to ITSELF
+  (`position` = own prop, `Skin.animation` = child path + prop). Changed values coalesce
+  into one throttled `setMyState({sync: {...}})` per window. Spawned entities (bullets,
+  pickups) go through **collections**, never extra owner nodes.
+- **`NetworkSpawner`** (register with `registerNodesNet()`): `source: "users"` spawns one
+  instance of the registered scene per OTHER account (self skipped); the flat `sync` patch
+  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`.
+
+## Boot
+
+```ts
+import { NetworkManager, registerNodesNet, LoopbackHub } from 'incanto/net';
+
+registerNodesNet();
+const scene = loadScene(json);
+engine.setScene(scene);
+
+// DEV / offline / split-screen: zero infrastructure, built-in protocol only
+const hub = new LoopbackHub();
+const manager = await NetworkManager.create(engine, { transport: hub.createClient('p1') });
+
+// PREVIEW with YOUR server logic (custom rules + $roomTick), still no cloud:
+// const local = createLocalGameServer({ server: Server });   // see "Preview" below
+// const manager = await NetworkManager.create(engine, { transport: local.createClient('p1') });
+
+// LIVE on agent8 (install the optional peer dep `@agent8/gameserver`):
+// const manager = await NetworkManager.create(engine);          // verse/account/auth auto-resolve
+// …and run the server/ init flow below ("Going live on agent8 v2").
+
+// ANY OTHER BACKEND: implement the NetworkTransport interface (see below) and
+// pass it the same way: NetworkManager.create(engine, { transport: myTransport }).
+
+manager.registerScene('remote-player', remotePlayerSceneJson);
+engine.start();
+```
+
+`NetworkManager` API:
+- ROOM signals `roomState`, `allUserStates`, `userJoined/Left`, `message(type)`,
+  `collection(id)`; snapshots `latestUserStates`/`latestRoomState`/`latestCollection(id)`.
+- GLOBAL signals `globalState`, `globalMyState`, `asset` (the local account's `$asset`
+  ledger — wire a HUD straight to it, no polling), `globalCollection(id)`,
+  `globalMessage(type)`; snapshots `latestGlobalState`/`latestGlobalMyState`/
+  `latestAsset`/`latestGlobalCollection(id)`. These fire only on a transport with a
+  global tier (LocalGameServer, the agent8 adapter); they stay quiet on raw Loopback.
+- Outbound `setMyState`, `patchRoomState`, `addEntity/updateEntity/removeEntity`,
+  `sendEvent(type, payload)`; **`call(fn, ...args)`** to invoke a CUSTOM server function
+  (your `server/src/server.ts` method — roomId is prepended automatically, e.g.
+  `manager.call('claimCoin', id)` → server `claimCoin(roomId, id)`, returns the server's
+  result). Global state is server-authoritative — the client READS it via the signals
+  above and WRITES it only through `call(...)`. `dispose()` leaves the room.
+
+The agent8 adapter (`createAgent8Server`) deep-imports the framework-free
+`GameServer` class from `@agent8/gameserver` (skipping its React/zustand index) and
+converts the v2 wire shapes to incanto's: `subscribeRoomAllUserStates` arrives as a
+delta-merged ARRAY `[{...state, account, __updated}]` → an account-keyed Record;
+`subscribeRoomCollection` arrives as `{items:[{__id,…}], changes}` → a `__id`-keyed
+Record. It also re-issues every subscription after a reconnect.
+
+## Writing a custom transport (any backend)
+
+Implement `NetworkTransport` (exported from `incanto/net`): `connect`/`disconnect`,
+`remoteFunction(fn, args)` answering the room protocol
+(`joinRoom`/`leaveRoom`/`setMyState` shallow-merge/`patchRoomState`/
+`addEntity`/`updateEntity`/`removeEntity`/`sendEvent`), and the subscription methods
+(`subscribeRoomState`, `subscribeRoomMyState`, `subscribeRoomAllUserStates`,
+`subscribeRoomCollection`, `onRoomMessage`, `onRoomUserJoin/Leave`). `LoopbackTransport`'s source is the reference
+implementation — anything that behaves like it works with the whole engine.
+
+## Preview: run your REAL server locally (no cloud, no auth)
+
+`LoopbackHub` answers only the FIXED built-in protocol — it cannot run your
+server-authoritative rules (`claimCoin`, `castSpell`) or your `$roomTick`. To
+PLAY the whole game — client + the actual `server/src/server.ts` `Server` class —
+in dev, use `LocalGameServer`:
+
+```ts
+import { createLocalGameServer, NetworkManager, registerNodesNet } from 'incanto/net';
+import { Server } from '../server/src/server';   // your deployable v2 Server class
+
+const local = createLocalGameServer({ server: Server });   // runs Server in memory
+const manager = await NetworkManager.create(engine, { transport: local.createClient('p1') });
+// …a second client: local.createClient('p2') — split-screen on one page.
+
+// $roomTick is server-DRIVEN: pump it from the engine ONCE (clamp dt so a
+// backgrounded tab can't fast-forward the match):
+engine.updated.connect((dt) => void local.tick(Math.min(dt, 0.05) * 1000));
+```
+
+It runs the SAME class body the cloud runs: the v2 globals (`$sender`/`$global`/
+`$room`/`$lock`) are injected per call, a FRESH `Server` instance runs per request
+(so `this.*` never persists), and calls are serialized (no global leaks across
+`await`s). `$roomTick(deltaMS, roomId)` runs only while a room has users.
+
+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
+game logic; deploy for the rest. Omitting `server` (`createLocalGameServer()`) gives
+the built-in kernel only — identical to a raw `LoopbackHub`.
+
+The preview injects `$sender`, `$room`, `$lock`, `$global`, and `$asset`, so
+SERVER-side economy and persistence logic runs locally:
+- `$room` — full room state/user-state/collections: `getMyState`/`updateMyState`,
+  `getRoomState` (always carries the `roomId` + `$users` defaults) / `updateRoomState`,
+  `getUserState`/`updateUserState`, `getAllUserStates` (array, each with `account`),
+  `countUsers`, room collections (`add`/`get`/`getCollectionItems`/`countCollectionItems`/
+  `delete`/`deleteCollection`), and `broadcastToRoom`.
+- `$global` — `joinRoom`/`leaveRoom`, process-lifetime global state (`getGlobalState`/
+  `updateGlobalState`), per-account global user state (`getMyState`/`updateMyState`/
+  `getUserState`/`updateUserState`), global collections (`add`/`update`/`delete`/
+  `get`/`getCollectionItems`/`countCollectionItems` with `filters`/`orderBy`/`limit`
+  query options), and room management (`countRoomUsers`/`getAllRoomIds`/
+  `getRoomUserAccounts`/`getRoomState`/`updateRoomState`/…).
+- `$asset` — a per-account currency ledger: `mint`/`burn`/`has`/`get`/`getAll`/
+  `transfer` (`burn`/`transfer` throw on an insufficient balance, and all amounts
+  must be non-negative & finite — surfacing economy bugs just as live would).
+
+Client-side GLOBAL subscriptions ARE emulated: the preview client reacts to
+`globalState`/`globalMyState`/`asset`/`globalCollection`/`globalMessage` (surfaced as
+NetworkManager signals above), and `$global.broadcastToAll`/`sendMessageToUser` deliver
+to `onGlobalMessage` (account-targeted for the latter).
+
+Still NOT emulated (use these only LIVE): `$room.sendMessageToUser` targeted ROOM
+delivery (the preview room message bus isn't account-scoped — a callable no-op;
+`$room.broadcastToRoom` DOES deliver) and system handlers like `$onItemPurchased`
+(VX shop). And the platform's hard constraints (isolated-vm, real concurrency, rate
+limits, durable persistence) are still not enforced — a game green in preview must be
+re-tested live.
+
+Runnable reference: `examples/arena-preview` (Coin Dash — server-authoritative
+`$lock`'d coin claim + `$roomTick` match clock, two clients split-screen). Going
+live is the one-line transport swap below.
+
+## Going live on agent8 (gameserver-sdk v2)
+
+The agent8 platform exposes NOTHING client-callable by default — every function
+NetworkManager calls (`joinRoom`/`leaveRoom`/`setMyState`/`patchRoomState`/
+`addEntity`/`updateEntity`/`removeEntity`/`sendEvent`) must be defined in YOUR
+server code. incanto ships that body for both server styles:
+
+**Structured project (v2, recommended).** Server code lives in `server/src/server.ts`.
+NEVER hand-create `server/package.json`, `server/tsconfig.json`, or `server/src/server.ts`
+— the init command generates them:
+
+```bash
+npx -y @agent8/gameserver-node init        # only if server/ does not exist yet
+# then replace server/src/server.ts with the incanto kernel body:
+#   node_modules/incanto/templates/agent8-server.ts   (export class Server { … })
+npx -y @agent8/gameserver-node test        # write + run server tests
+npx -y @agent8/gameserver-node build       # generates server/dist/server.js
+# then DEPLOY = push to the repository — the platform auto-builds + deploys.
+```
+
+**Legacy (root `server.js`).** Only for projects that already ship one. Body:
+`node_modules/incanto/templates/agent8-server.js` (`class Server`, NO `export`).
+
+The client side is unchanged — `await NetworkManager.create(engine)` uses the
+built-in `createAgent8Server()` transport (verse/account/auth auto-resolve via the
+SDK). Develop against `LoopbackHub`, then drop the `{ transport }` option to go live.
+
+> **Cross-links — defer server-code specifics to the service skills, don't duplicate them here:**
+> - **`gameserver-sdk-v2`** — the authoritative server AND client reference: the
+>   `$global`/`$room`/`$sender`/`$asset`/`$lock` contexts, `$roomTick`, collection/state
+>   APIs, the init/test/build/deploy flow, the isolated-vm limits, AND client connection +
+>   auth/identity (`useGameServer`, `server.connect`, `$sender.isGuest`/`isFollower`/
+>   `isSubscriber`, Verse8 identity). Read it before editing `server/src/server.ts` and for
+>   how the live client connects.
+> - **`gameserver-sdk`** — legacy v1 single-file `server.js` reference.
+
+How incanto's model maps onto v2 rooms:
+- **`network: {mode:'owner', sync:[...]}`** → throttled `setMyState(roomId, {sync:{…}})`
+  → server `$room.updateMyState(patch)` (shallow merge) → surfaces to every other
+  client through v2's `subscribeRoomAllUserStates` (account-keyed after the adapter).
+- **`NetworkSpawner` `source:'users'`** consumes `manager.latestUserStates` (the
+  account-keyed snapshot), spawning one instance per OTHER account; `onRoomUserJoin/Leave`
+  drive `userJoined`/`userLeft`. A user leaving simply disappears from the next
+  all-user-states array, so the spawner despawns them.
+- **`source:'collection:<id>'`** consumes `addEntity`→`$room.addCollectionItem` etc.,
+  mirrored by v2's `subscribeRoomCollection` (keyed by `__id` after the adapter).
+
+Kernel constraints (agent8 platform facts — don't fight them):
+- a NEW Server instance per request: `this.*` never persists; use `$global`/`$room`,
+  and `$roomTick` (100–1000ms) for timed logic — NO setTimeout/setInterval/Node builtins/fetch
+- `updateMyState`/`updateRoomState` are SHALLOW merges — keep state maps flat; you can't delete by omission
+- room data is ephemeral — persist to `$global` before rooms empty
+- never expose unthrottled per-frame remoteFunction (rapid calls are rejected); guard score/economy with `$lock`
+
+## State rules
+
+- JSON-safe by construction: vectors as arrays, no `undefined`/`NaN`/typed arrays
+- Reserved names (never use as keys): `$users`, `roomId`, `account`, `__id`, `__roomId`,
+  `__updated`, `__leaved`, anything `$`-prefixed
+- `LoopbackHub` implements the SAME room protocol as the agent8 server templates,
+  so passing locally proves your game LOGIC + data flow are right — necessary, but
+  NOT sufficient. The preview does NOT enforce the platform's hard constraints, so a
+  game that's green locally can still misbehave live; you MUST re-test live for:
+  - **isolated-vm limits** — `setTimeout`/`setInterval`/`fetch`/Node builtins run
+    fine in preview but are REJECTED live (timed logic must be `$roomTick`);
+  - **concurrency** — the preview serializes every call, so a FORGOTTEN `$lock`
+    still passes locally; live, parallel requests race (double-award, last-write-wins);
+  - **rate limits** — unthrottled per-frame `remoteFunction` passes locally, throttled live;
+  - **persistence/ephemerality** — preview state lives forever in a Map; live, room
+    data is cleared when the last user leaves (persist to `$global` before then);
+  - **wire shapes & auth** — array/delta conversions and `$sender.account` trust
+    exist only on the live adapter.
+- Runnable references: `examples/arena-loopback` (two clients on one `LoopbackHub`)
+  and `examples/arena-preview` (the real `server/src/server.ts` run locally via
+  `LocalGameServer` — server-authoritative scoring + `$roomTick`). Going live = the
+  client transport swap (for a normal single-client game, just omit `{transport}`;
+  a split-screen demo like arena-preview also drops its local-only scaffolding) PLUS
+  deploying `server/` (the "Going live on agent8" section above) — not literally one line.