@helix3/helix-mcp 0.2.2-helix3.14

package/docs/multiplayer-templates/team-control.md

@@ -0,0 +1,98 @@
+# Multiplayer template — `team-control`
+
+**What it is.** Two teams (red/blue) fight for a hill — **no combat, just presence**: whichever team has more
+players standing on the hill drags a tug-of-war control meter their way; hit the end and they score a point, then
+it resets. **Capability: non-combat teams + zone-presence scoring + a win condition.** Teams are a `playerVar`
+enum; scoring is a per-team `aggregate count` over a zone; the meter is a `varReached` threshold. Use this for
+king-of-the-hill, domination, territory control, capture points, objective races. Lifted from the verified
+`multiplayer-team-control` world.
+
+> The competitive scaffold **without** combat (combat templates are deferred to the character pass). Grammar:
+> `read_doc({ name: "multiplayer-logic" })` §2 (vars), §6 (aggregate), §4 (`varReached`).
+
+## 1. DSL used
+
+- **Teams** (§2/§14) — `playerVars.team` (a `string`, `red`/`blue`); `joinRed`/`joinBlue` actions set it. (You
+  could auto-balance on `playerJoin` instead.)
+- **Zone-presence scoring** (§6/§10) — a `hill` zone + `aggregate count … where team == "red"/"blue"` each tick to
+  count each team on the hill.
+- **The tug-of-war idiom** — a `control` number in `[-100, 100]`; every 10 ticks the team with more players on the
+  hill pushes it ±5 (and sets `holder`).
+- **Win condition** (§4) — `varReached room.control >= 100` → red scores + reset; `<= -100` → blue scores. (Swap
+  for a first-to-N + `transitionTo "results"` if you want a match end — see `turn-arena`.)
+
+## 2. The manifest — `public/helix.json`
+
+```json
+{
+  "helixVersion": "0.3",
+  "title": "Team Control",
+  "slug": "team-control",
+  "entry": "index.html",
+  "maxPlayers": 8,
+  "permissions": ["auth.profile", "multiplayer"],
+  "multiplayer": {
+    "authoritative": true,
+    "state": {
+      "roomVars": {
+        "redOnHill": { "type": "number", "default": 0 },
+        "blueOnHill": { "type": "number", "default": 0 },
+        "control": { "type": "number", "default": 0 },
+        "redScore": { "type": "number", "default": 0 },
+        "blueScore": { "type": "number", "default": 0 },
+        "holder": { "type": "string", "default": "none" }
+      },
+      "playerVars": { "team": { "type": "string", "default": "blue", "enum": ["red", "blue"] } }
+    },
+    "zones": [{ "id": "hill", "shape": "sphere", "center": [0, 0, 0], "radius": 6 }],
+    "states": { "initial": "playing", "phases": ["playing"] },
+    "actions": { "joinRed": {}, "joinBlue": {} },
+    "rules": [
+      { "when": { "on": "action", "name": "joinRed" }, "then": [{ "do": "set", "target": "self.team", "to": "red" }] },
+      { "when": { "on": "action", "name": "joinBlue" }, "then": [{ "do": "set", "target": "self.team", "to": "blue" }] },
+      {
+        "when": { "on": "tick", "everyN": 10 },
+        "then": [
+          { "do": "set", "target": "room.redOnHill", "to": { "op": "aggregate", "scope": "zone:hill", "agg": "count", "as": "p", "where": { "op": "==", "a": { "ref": "p", "var": "team" }, "b": "red" } } },
+          { "do": "set", "target": "room.blueOnHill", "to": { "op": "aggregate", "scope": "zone:hill", "agg": "count", "as": "p", "where": { "op": "==", "a": { "ref": "p", "var": "team" }, "b": "blue" } } }
+        ]
+      },
+      { "when": { "on": "tick", "everyN": 10 }, "if": { "op": ">", "a": { "var": "room.redOnHill" }, "b": { "var": "room.blueOnHill" } }, "then": [{ "do": "add", "target": "room.control", "by": 5 }, { "do": "set", "target": "room.holder", "to": "red" }] },
+      { "when": { "on": "tick", "everyN": 10 }, "if": { "op": ">", "a": { "var": "room.blueOnHill" }, "b": { "var": "room.redOnHill" } }, "then": [{ "do": "add", "target": "room.control", "by": -5 }, { "do": "set", "target": "room.holder", "to": "blue" }] },
+      { "when": { "on": "varReached", "scope": "room", "var": "control", "cmp": ">=", "value": 100 }, "then": [{ "do": "add", "target": "room.redScore", "by": 1 }, { "do": "set", "target": "room.control", "to": 0 }, { "do": "set", "target": "room.holder", "to": "none" }] },
+      { "when": { "on": "varReached", "scope": "room", "var": "control", "cmp": "<=", "value": -100 }, "then": [{ "do": "add", "target": "room.blueScore", "by": 1 }, { "do": "set", "target": "room.control", "to": 0 }, { "do": "set", "target": "room.holder", "to": "none" }] }
+    ]
+  },
+  "supportsMobile": true,
+  "contentRating": "everyone",
+  "systems": { "humanoid-character": "^0.2" }
+}
+```
+
+The whole contest is `aggregate count … where team == X` over the hill + a tug-of-war number — **no hit detection,
+no health**. `varReached` fires once on the edge (false→true), so each point scores exactly once before the reset.
+
+## 3. The client — `src/main.ts` (delta from `hangout`)
+
+Presence + team selection + a control-meter HUD (read the `roomVars`):
+
+```ts
+addEventListener('keydown', (e) => {
+  if (e.key === '1') room.sendAction('joinRed');
+  else if (e.key === '2') room.sendAction('joinBlue');
+});
+
+// each frame: tint your character by your team, draw the meter from room.state.roomVars
+const myTeam = String((room.state.players[room.sessionId]?.vars as Record<string, unknown> | undefined)?.team ?? 'blue');
+const control = numRoomVar('control');                 // -100 (blue) … +100 (red)
+hud.innerHTML = `Hill: ${numRoomVar('redOnHill')}🔴 vs ${numRoomVar('blueOnHill')}🔵 · control ${control} · ${numRoomVar('redScore')}–${numRoomVar('blueScore')}`;
+drawControlBar(control);
+```
+
+**Footguns:** read `roomVars` live each frame (guard until the first patch); team is a server-written `playerVar`
+(the client sends the `joinRed`/`joinBlue` intent, the server sets it); `enum` on `team` makes the validator reject
+any value other than `red`/`blue`.
+
+## 4. Build, validate, publish
+
+`npm install` → `helix install` → `npm run build` → `validate_world` on `dist/` → `whoami` → `publish_world`.

package/docs/multiplayer-templates/turn-arena.md

@@ -0,0 +1,159 @@
+# Multiplayer template — `turn-arena`
+
+**What it is.** A co-op turn-based siege: players take turns striking a pit of monsters; run out of health or
+surrender and you're eliminated; clear the monsters to win, lose everyone to lose, then reset. **Capability: a state
+machine + turn order + elimination.** Phases (`play → won/defeat`), a **turn queue** (`advanceTurn` over a
+list-of-ref, gated by "is it my turn?"), `eliminate`/`revive`, and broadcast events. Use this for board games,
+co-op boss fights, round-based battlers. Lifted from the verified `multiplayer-turn-arena` world.
+
+> A character world (presence) **plus** turn/phase logic. Grammar: `read_doc({ name: "multiplayer-logic" })` §8
+> (turns/elimination), §12 (state machine), §13 (broadcasts), §6 (aggregate).
+
+## 1. DSL used
+
+- **State machine** (§12) — `states.phases: ["play","won","defeat"]`; `transitionTo` moves between them; rules read
+  `room.phase`.
+- **Turn order** (§2/§8) — `roomVars.turnOrder` (a **`list` of player refs**) + `turnIndex`. `advanceTurn` bumps
+  the index (skipping eliminated players, wrapping). A rule gates an action to the current player with
+  `sameRef(self, listAt(turnOrder, turnIndex))`.
+- **Elimination** (§8) — `eliminate` / `revive`; `forEachPlayer … includeEliminated: true` to reset everyone.
+- **Broadcast events** (§13) — `turnChanged` / `gameOver`, fired with `broadcast` (client reads via `onMessage`).
+- **Aggregate** (§6) — `sum`/`count` over `zone:pit` (monster HP + count), `argmax` over players (the winner by
+  health), `playerCount`.
+- **`varReached`** (§4) — entity/self/room scopes drive monster death, elimination, and the win/lose transitions.
+- **Entities + a zone** — `monster` (hp) inside the `pit` zone (`tracks:'entity:monster'`).
+
+## 2. The manifest — `public/helix.json`
+
+```json
+{
+  "helixVersion": "0.3",
+  "title": "Turn-Based Siege",
+  "slug": "turn-arena",
+  "entry": "index.html",
+  "maxPlayers": 8,
+  "permissions": ["auth.profile", "multiplayer"],
+  "multiplayer": {
+    "authoritative": true,
+    "state": {
+      "roomVars": {
+        "turnOrder": { "type": "list", "maxLen": 8, "of": { "type": "ref", "of": "player" } },
+        "turnIndex": { "type": "number", "default": 0 },
+        "monstersSpawned": { "type": "number", "default": 0 },
+        "monstersAlive": { "type": "number", "default": 0 },
+        "zoneHp": { "type": "number", "default": 0 },
+        "alive": { "type": "number", "default": 0 },
+        "killTarget": { "type": "number", "default": 0 },
+        "winner": { "type": "ref", "of": "player" }
+      },
+      "playerVars": { "health": { "type": "number", "default": 100 } }
+    },
+    "entities": { "monster": { "vars": { "hp": { "type": "number", "default": 64 } } } },
+    "zones": [{ "id": "pit", "shape": "sphere", "center": [0, 0, 0], "radius": 8, "tracks": "entity:monster" }],
+    "states": { "initial": "play", "phases": ["play", "won", "defeat"], "joinPolicy": { "play": { "joinable": true } } },
+    "actions": { "strike": {}, "surrender": {}, "reset": {} },
+    "events": {
+      "turnChanged": { "payload": { "current": { "type": "ref", "of": "player" } } },
+      "gameOver": { "payload": { "winner": { "type": "ref", "of": "player" } } }
+    },
+    "rules": [
+      { "when": { "on": "playerJoin" }, "then": [{ "do": "append", "target": "room.turnOrder", "value": "self" }] },
+      {
+        "when": { "on": "tick" },
+        "if": { "op": "<", "a": { "var": "room.monstersSpawned" }, "b": 6 },
+        "then": [
+          { "do": "spawnEntity", "kind": "monster", "at": { "op": "randomPoint", "min": [-5, 0, -5], "max": [5, 0, 5] } },
+          { "do": "add", "target": "room.monstersSpawned", "by": 1 }
+        ]
+      },
+      {
+        "when": { "on": "tick" },
+        "then": [
+          { "do": "set", "target": "room.zoneHp", "to": { "op": "aggregate", "scope": "zone:pit", "agg": "sum", "field": "hp" } },
+          { "do": "set", "target": "room.monstersAlive", "to": { "op": "aggregate", "scope": "zone:pit", "agg": "count" } },
+          { "do": "set", "target": "room.alive", "to": { "op": "playerCount" } }
+        ]
+      },
+      {
+        "when": { "on": "action", "name": "strike" },
+        "if": { "op": "sameRef", "a": "self", "b": { "op": "listAt", "list": "room.turnOrder", "index": { "var": "room.turnIndex" } } },
+        "then": [
+          { "do": "forEachEntity", "kind": "monster", "as": "m", "then": [{ "do": "add", "target": { "ref": "m", "var": "hp" }, "by": -8 }] },
+          { "do": "add", "target": "self.health", "by": -6 },
+          { "do": "advanceTurn", "order": "room.turnOrder", "index": "room.turnIndex" },
+          { "do": "broadcast", "event": "turnChanged", "to": "all", "payload": { "current": { "op": "listAt", "list": "room.turnOrder", "index": { "var": "room.turnIndex" } } } }
+        ]
+      },
+      { "when": { "on": "varReached", "scope": "entity", "kind": "monster", "var": "hp", "cmp": "<=", "value": { "var": "room.killTarget" } }, "then": [{ "do": "destroyEntity", "entity": "self" }] },
+      { "when": { "on": "action", "name": "surrender" }, "then": [{ "do": "eliminate", "player": "self" }, { "do": "advanceTurn", "order": "room.turnOrder", "index": "room.turnIndex" }] },
+      { "when": { "on": "varReached", "scope": "self", "var": "health", "cmp": "<=", "value": 0 }, "then": [{ "do": "eliminate", "player": "self" }, { "do": "advanceTurn", "order": "room.turnOrder", "index": "room.turnIndex" }] },
+      {
+        "when": { "on": "varReached", "scope": "room", "var": "monstersAlive", "cmp": "<=", "value": 0 },
+        "if": { "op": ">=", "a": { "var": "room.monstersSpawned" }, "b": 6 },
+        "then": [
+          { "do": "setRef", "target": "room.winner", "to": { "op": "aggregate", "scope": "players", "agg": "argmax", "field": "health" } },
+          { "do": "broadcast", "event": "gameOver", "to": "all", "payload": { "winner": { "var": "room.winner" } } },
+          { "do": "transitionTo", "phase": "won" }
+        ]
+      },
+      {
+        "when": { "on": "varReached", "scope": "room", "var": "alive", "cmp": "<=", "value": 0 },
+        "if": { "op": ">=", "a": { "var": "room.monstersSpawned" }, "b": 6 },
+        "then": [{ "do": "broadcast", "event": "gameOver", "to": "all", "payload": { "winner": { "var": "room.winner" } } }, { "do": "transitionTo", "phase": "defeat" }]
+      },
+      {
+        "when": { "on": "action", "name": "reset" },
+        "if": { "op": "!=", "a": { "var": "room.phase" }, "b": "play" },
+        "then": [
+          { "do": "set", "target": "room.monstersSpawned", "to": 0 },
+          { "do": "setRef", "target": "room.winner", "to": null },
+          { "do": "forEachPlayer", "as": "p", "includeEliminated": true, "then": [{ "do": "revive", "player": "p" }, { "do": "set", "target": { "ref": "p", "var": "health" }, "to": 100 }] },
+          { "do": "transitionTo", "phase": "play" }
+        ]
+      }
+    ]
+  },
+  "supportsMobile": true,
+  "contentRating": "everyone",
+  "systems": { "humanoid-character": "^0.2" }
+}
+```
+
+The turn gate is the key idiom: `if sameRef(self, listAt(turnOrder, turnIndex))` — only the current player's
+`strike` applies. `advanceTurn` then rotates (skipping eliminated). Eliminated players stay connected + rendered
+(`active:false`) but drop out of the turn rotation.
+
+## 3. The client — `src/main.ts` (delta from `hangout`)
+
+Presence + a turn/phase HUD. Read `room.state.phase` + the current player, bind the three actions, and react to
+the broadcasts:
+
+```ts
+// whose turn? — read turnOrder[turnIndex] off room.state
+function currentTurnId(): string {
+  const order = (room.state.roomVars as { turnOrder?: { length: number; [i: number]: { toString(): string } } } | undefined)?.turnOrder;
+  const idx = numRoomVar('turnIndex');
+  return order && order.length ? String(order[idx]) : '';
+}
+const myTurn = () => currentTurnId() === room.sessionId;
+
+addEventListener('keydown', (e) => {
+  if (e.key === ' ' && myTurn()) room.sendAction('strike');   // only on your turn
+  else if (e.key === 'x') room.sendAction('surrender');
+  else if (e.key === 'r') room.sendAction('reset');           // after won/defeat
+});
+
+room.onMessage('turnChanged', (m) => showBanner(`Turn: ${nameOf(String(m.current))}`));
+room.onMessage('gameOver', (m) => showBanner(m.winner ? `🏆 ${nameOf(String(m.winner))} wins` : 'Defeat'));
+
+// each frame: render room.state.phase, currentTurnId(), your health.
+```
+
+**Footguns:** read `room.state.phase` (a reserved built-in) + `roomVars` (incl. `turnIndex`) live each frame; gate
+`strike` on `myTurn()` client-side for UX, but the **server** re-checks `sameRef` (never trust the client). Refs
+on the wire stringify to a session id — compare with `room.sessionId`.
+
+## 4. Build, validate, publish
+
+`npm install` → `helix install` → `npm run build` → `validate_world` on `dist/` (watch the cascade depth + the
+per-tick budget — `forEachEntity` × monsters) → `whoami` → `publish_world`.

package/docs/multiplayer-templates/wave-survival.md

@@ -0,0 +1,141 @@
+# Multiplayer template — `wave-survival`
+
+**What it is.** A co-op horde: every few seconds a wave of enemies spawns and chases the players; touch one and you
+take damage; shoot them to clear the wave. **Capability: SHARED (game-owned) entities with DISTRIBUTED,
+host-migrated local-authority AI** — the enemies belong to the *game*, not a player; the server hands **each enemy
+to the least-loaded client at spawn**, so the swarm's simulation **spreads across the whole room** (no single
+machine bears the entire horde), and any enemy whose host drops is **re-elected** to another client (so it never
+stalls). That distribution is exactly why it suits a co-op / Vampire-Survivors-style horde. Lifted from the
+verified `multiplayer-wave-survival-2` world.
+
+> **The lesson here is shared-entity host migration + client-driven AI**, *not* combat — the damage/shoot is
+> ordinary rule logic (a contact zone + a validated action), independent of the character system. Read
+> `relic-bearers` first (this builds on `EntityScene`); grammar: `read_doc({ name: "multiplayer-logic" })` §9.
+
+## 1. DSL used
+
+- **Entities** (§9) — one `enemy` kind, **`shared: true`** + `authority:'owner'` + `ownerLifecycle:'hostMigrate'`:
+  each enemy is hosted by the **least-loaded connected client at spawn**, so a swarm of them **distributes across
+  the clients** (not all on one host) — and any enemy **re-elects** to another client if its host leaves.
+  `idleTimeout: 4` despawns an enemy left hostless for 4 s. `maxSpeed` (required for owner kinds) bounds the upload;
+  an **attached zone** damages players on contact.
+- **Timers** (§11) — `wave`, **self-rearming** (a `timerElapsed` rule restarts it) → a steady spawn cadence.
+- **Actions** (§14) — `shoot` (arg `target`: an enemy ref); the server validates range before destroying.
+- **Declared state** (§2) — `roomVars.wave` + `playerVars.health`.
+- **Rules** (§3) — arm the wave timer on `stateEnter`; on `timerElapsed` re-arm **and** (if `aggregate count < 6`)
+  `spawnEntity`; enemy-zone `zoneEnter` (binds `self` = the player) subtracts health; `shoot` validates `distance`
+  then `destroyEntity`; `varReached self.health <= 0` respawns + heals.
+
+## 2. The manifest — `public/helix.json`
+
+```json
+{
+  "helixVersion": "0.3",
+  "title": "Wave Survival",
+  "slug": "wave-survival",
+  "entry": "index.html",
+  "maxPlayers": 8,
+  "permissions": ["auth.profile", "multiplayer"],
+  "multiplayer": {
+    "authoritative": true,
+    "state": {
+      "roomVars": { "wave": { "type": "number", "default": 0 } },
+      "playerVars": { "health": { "type": "number", "default": 100 } }
+    },
+    "entities": {
+      "enemy": {
+        "authority": "owner",
+        "shared": true,
+        "ownerLifecycle": "hostMigrate",
+        "idleTimeout": 4,
+        "maxSpeed": 6,
+        "zone": { "shape": "sphere", "radius": 1.2 }
+      }
+    },
+    "timers": { "wave": {} },
+    "actions": { "shoot": { "args": { "target": { "type": "ref", "of": "entity:enemy" } } } },
+    "states": { "initial": "playing", "phases": ["playing"] },
+    "rules": [
+      { "when": { "on": "stateEnter", "phase": "playing" }, "then": [{ "do": "startTimer", "timer": "wave", "seconds": 3 }] },
+      { "when": { "on": "timerElapsed", "timer": "wave" }, "then": [{ "do": "startTimer", "timer": "wave", "seconds": 3 }] },
+      {
+        "when": { "on": "timerElapsed", "timer": "wave" },
+        "if": { "op": "<", "a": { "op": "aggregate", "scope": "entities:enemy", "agg": "count" }, "b": 6 },
+        "then": [
+          { "do": "spawnEntity", "kind": "enemy", "at": { "vec3": [0, 0, 14] } },
+          { "do": "add", "target": "room.wave", "by": 1 }
+        ]
+      },
+      { "when": { "on": "zoneEnter", "zone": "enemy" }, "then": [{ "do": "add", "target": "self.health", "by": -10 }] },
+      {
+        "when": { "on": "action", "name": "shoot" },
+        "if": { "op": "<", "a": { "op": "distance", "a": { "var": "self.position" }, "b": { "ref": { "var": "action.args.target" }, "var": "position" } }, "b": 50 },
+        "then": [{ "do": "destroyEntity", "entity": { "var": "action.args.target" } }]
+      },
+      {
+        "when": { "on": "varReached", "scope": "self", "var": "health", "cmp": "<=", "value": 0 },
+        "then": [
+          { "do": "respawn", "player": "self", "to": { "vec3": [0, 1, 0] } },
+          { "do": "set", "target": "self.health", "to": 100 }
+        ]
+      }
+    ]
+  },
+  "supportsMobile": true,
+  "contentRating": "everyone",
+  "systems": { "humanoid-character": "^0.2" }
+}
+```
+
+The two `timerElapsed` rules fire in declared order: the first re-arms `wave`, the second spawns. `shoot` is the
+cheat-resistant input — the **server** checks range, so a client can't destroy an enemy across the map.
+
+## 3. The client — `src/main.ts` (delta from `relic-bearers`)
+
+Same `EntityScene`, but the entities are **shared**: `EntityScene` runs your `motion` fn only for enemies **you
+host** (`controller === sessionId`), interpolates the rest, and freezes orphans (`controller === ''`) until the
+server re-elects a host. The motion fn is the **AI** — chase the nearest player:
+
+```ts
+import { EntityScene } from '@helix/humanoid-character';
+const ENEMY_MAX_SPEED = 6;            // MUST mirror the DSL maxSpeed (reconcile clamp)
+
+const entities = new EntityScene({
+  room,
+  maxSpeed: { enemy: ENEMY_MAX_SPEED },
+  motion: {
+    // Chase the nearest player. ctx.seekNearest(speed, stopAt) returns the gate-safe next position: it caps the
+    // per-frame step internally (≤ speed × dt) so it stays inside the reconcile clamp, and stops ~0.9m short.
+    // Runs only for enemies YOU host. (ctx also has nearestPlayer(from): Vec3 | null if you want the raw target.)
+    enemy: (_e, _dt, ctx) => ctx.seekNearest(ENEMY_MAX_SPEED * 0.83, 0.9),
+  },
+  build: () => {
+    const mesh = makeEnemy(); scene.add(mesh);
+    return {
+      object3d: mesh,
+      onUpdate: (e) => { mesh.visible = true; tintByController(mesh, e.controller, room!.sessionId); },  // host / orphan tint
+      dispose: () => scene.remove(mesh),
+    };
+  },
+});
+// frame loop (inside `if (room)`): entities.update(dt);
+
+// Shoot the nearest enemy in front of you — client picks the id, server validates range + destroys:
+function shootNearest() {
+  let best = '', bestD = Infinity;
+  for (const { id, object3d, state } of entities.entries()) {
+    if (state.kind !== 'enemy') continue;
+    const d2 = object3d.position.distanceToSquared(body.position);
+    if (d2 < bestD) { bestD = d2; best = id; }
+  }
+  if (best) room.sendAction('shoot', { target: best });
+}
+```
+
+Read your `health` off `room.state.players[sessionId].vars.health`. **Footguns:** mirror `maxSpeed`; keep each
+motion step `≤ maxSpeed × 0.83 × dt`; you won't host every enemy (shared) — never assume you control one, check
+`e.controller`.
+
+## 4. Build, validate, publish
+
+`npm install` → `helix install` → `npm run build` → `validate_world` on `dist/` → `whoami` → `publish_world`.

package/docs/multiplayer-world.md

@@ -0,0 +1,231 @@
+# HELIX Instant — Multiplayer (the hub)
+
+Build worlds where players share a space **and** a game. HELIX multiplayer is **server-authoritative and
+declarative**: a platform-owned room holds the shared state and runs your rules — **you write no server code.**
+Every multiplayer world builds on the **`humanoid-character`** system (read `get_started({ kind: "character" })`
+first — same project layout, build config, loading screen, character config) plus **`@hypersoniclabs/helix-sdk`**
+for `Helix.multiplayer`.
+
+> **Discover versions first.** The replica primitives (`ReplicaScene`, `NetworkDriver`, `ReplicaBody`) ship inside
+> the **`humanoid-character`** system; `Helix.multiplayer` is in **`@hypersoniclabs/helix-sdk`**. Run
+> `get_package_manifest("humanoid-character")` + `check_for_updates` before you build — if a pinned version
+> predates multiplayer, those imports won't exist; don't guess around it.
+
+## The model — five facts
+
+1. **The server is authoritative and platform-owned.** A generic room (the "HelixRoom") holds shared state and
+   validates input. **There is no server file in your project** — you opt in via the manifest; the platform runs
+   the room.
+2. **Multiplayer is declarative — game logic is DATA.** You declare state + a `when`/`if`/`then` rule pipeline in
+   your `helix.json` `multiplayer` block; the room interprets it at a fixed **20 Hz**. The full grammar is its own
+   reference: **`read_doc({ name: "multiplayer-logic" })`.**
+3. **Two layers.** (a) **Presence** — players see each other move/animate (the on-ramp below; this alone is a full
+   hangout). (b) **Declarative game logic** — shared scores/teams/state, server- and client-hosted entities, zones,
+   timers, a state machine, collections, ownership. Most worlds are presence **plus** some logic.
+4. **Login required; single-player must still work.** Set up your local player + scene **unconditionally**, then
+   *layer* multiplayer on only when a room join succeeds (**the golden rule** — the standalone/guest path never
+   breaks).
+5. **`maxPlayers` is a platform-enforced cap.** The room locks at `maxPlayers` and spills extras into a fresh
+   instance; the platform also clamps it to its per-room ceiling. Keep it modest (2–8 is the sweet spot;
+   `validate_world` warns if you exceed the cap). Note: the `uploadHz: 20` fast tier caps `maxPlayers` at **12**.
+
+## Opt in — the manifest (`public/helix.json`, v0.3)
+
+Bump `helixVersion` to `"0.3"`, set `maxPlayers > 1`, and add the **`multiplayer`** permission (keep `auth.profile`
+— you need the player identity). Cross-field rules are enforced at validate/publish: `maxPlayers > 1` **requires**
+`multiplayer`, and `multiplayer` **forces** `requiresAuth: true` (coerced for you).
+
+```json
+{
+  "helixVersion": "0.3",
+  "title": "My Hangout",
+  "slug": "my-hangout",
+  "entry": "index.html",
+  "maxPlayers": 8,
+  "permissions": ["auth.profile", "multiplayer"],
+  "multiplayer": { "authoritative": true },
+  "supportsMobile": true,
+  "contentRating": "everyone",
+  "systems": { "humanoid-character": "^0.2" }
+}
+```
+
+The `multiplayer` block above is the **presence minimum**: `authoritative` (leave `true`) + an optional advisory
+`interestRadius`. The same block also carries the full declarative game-logic surface (`state`, `rules`,
+`entities`, `zones`, `timers`, `states`, `events`, `actions` — see `multiplayer-logic`), and an optional
+`uploadHz: 20` (the fast client→server tier for twitchy/physics worlds; default is 10, and 20 caps `maxPlayers`
+at 12). There is **no `tickRate` knob** — the platform owns the room tick.
+
+> **Two independent version axes — don't try to "align" them.** `helixVersion: "0.3"` is the **manifest schema**
+> version; `@hypersoniclabs/helix-sdk` is an **npm package** on its own line. A mismatch in the numbers is
+> expected, not a bug.
+
+## Pick your starting point — the template index
+
+Every multiplayer world is **presence + (optionally) declarative game logic.** Find the closest template, read it
+with **`read_template({ name })`**, and adapt it — each template is a complete, publish-shaped world that links
+into `multiplayer-logic` per construct. Templates 2→7 walk the full entity-**authority** spectrum (static →
+server-moving → client-owned → shared → physics), which is the most footgun-prone area — skim them in order.
+
+Each template's §3 client code is a **delta** from the presence on-ramp below; unshown helpers (`makeMesh()`,
+`showBanner()`, `numRoomVar()`, your `body`/`scene`) are **your own code**, not SDK APIs.
+
+| Building… | Template | What it teaches |
+|---|---|---|
+| a hangout / social space / co-op room — players just see each other | `hangout` | **presence**: join flow, `ReplicaScene`/`NetworkDriver` replicas, `sendState`. The substrate every other template builds on (it's the on-ramp below). |
+| a collectible / scavenger world — grab items for points | `collect-a-thon` | declared room/player state + server-spawned **static** pickups (`spawnEntity`) + zones + scoring. |
+| roaming NPCs, moving platforms, patrolling guards, homing pickups | `server-motion` | **server-authoritative** entity motion (`seek`/`waypoints`) — deterministic, cheat-proof, never freezes. The **preferred** entity default (a roaming bot vacuum that hoovers up coins). |
+| a pet/familiar that follows you, or a single-owner carryable | `relic-bearers` | **client-hosted** single-owner entities (`authority:'owner'`) + ownership reads + owner-leave migration. The **escape hatch** — only when the server genuinely can't compute the motion. |
+| co-op survival / horde / Vampire-Survivors-style enemy swarms | `wave-survival` | **shared** game-owned entities **distributed** across clients (each enemy hosted by the least-loaded client, re-elected if its host leaves) — the swarm's sim spreads across the room — plus timed waves. |
+| a ball/puck sport — soccer, hockey, pool | `physics-football` | networked physics, **authority-transfer**: one shared dynamic body whose control hands off to whoever touches it (`claimOnContact`) and reverts to the server at rest. |
+| bumper cars / derby / sumo — players **are** physics bodies | `physics-bumper` | networked physics, **dual-sim**: each player owns their own body and collisions reconcile favor-local, on the `uploadHz: 20` fast tier (so `maxPlayers ≤ 12`). |
+| a card game / hand / inventory / crafting | `collections` | structured **collections** — lists of records (a hand of cards), counterMaps, `forEachInList`, `append`/`removeWhere`. |
+| a turn-based / board game / co-op boss fight | `turn-arena` | a **state machine** (play → win/lose) + **turn order** (`advanceTurn`) + **elimination**. |
+| farming / growth / idle / day-cycle — things change over real time | `chrono-orchard` | the **time axis**: timers + the `{op:now}` wall-clock + dynamic durations; entities (crops) that ripen over time. |
+| an obstacle course / parkour / race | `obby` | ordered zone **checkpoints** + **respawn**-to-checkpoint on a fall + a per-player saved checkpoint + a finish line. |
+| king-of-the-hill / domination / territory / capture points | `team-control` | **teams** (a player var) + zone-**presence** scoring (red vs blue on the hill) + a tug-of-war capture/scoring loop — **no combat**. |
+
+**Combat is not yet a template** (shooting, melee, tag, capture-the-flag, tower defense) — it depends on
+character abilities still in progress. Until then, players affect each other through **declared `actions`**
+(server-validated, the cheat-resistant path) — see `multiplayer-logic` §14 + the cross-player firewall in §17.
+
+**Nothing fits exactly?** Most real worlds are a blend (e.g. a collect-a-thon with teams, or a turn game with
+physics). Templates are starting points, not a menu — read `read_doc({ name: "multiplayer-logic" })` and compose
+from the primitives.
+
+## The presence on-ramp — every multiplayer world starts here
+
+Presence is the universal substrate (and the whole of the `hangout` template). The pattern: build your local
+player **unconditionally**, then join + render remotes only `if (room)`.
+
+**1 — Init first, then join (guarded so guests/standalone fall back to single-player).** Call `Helix.init()`
+(and settle login) BEFORE loading character assets: the body is bind-once, and every player renders their
+equipped **universal avatar** — resolved at load time (see the `hangout` template §3a for the full body-selection
+code; the room replicates each player's `avatarUrl`, `''` = default body):
+
+```ts
+import { Helix } from '@hypersoniclabs/helix-sdk';
+import type { HelixRoom, PlayerState, ReplicaInput } from '@hypersoniclabs/helix-sdk';
+
+const { embedded, user } = await Helix.init();
+if (embedded && !user) {
+  try { await Helix.auth.requestLogin(); } catch { /* declined → guest, default body, single-player */ }
+}
+// … load assets + build the local player (character recipe / hangout §3a: their universal avatar) …
+
+let room: HelixRoom | null = null;
+if (embedded) {
+  try {
+    room = await Helix.multiplayer.joinRoom();     // defaults to the current world; resolves + connects
+  } catch (err) {
+    console.info('multiplayer unavailable — running single-player:', err);
+    room = null;
+  }
+}
+```
+
+The `HelixRoom` handle (Colyseus, re-exposed under `Helix.*` — you never import the Colyseus client):
+`room.state` (authoritative shared state: `players`, plus `entities` once you declare them) · `room.sessionId`
+(**your** id — skip it in `onAdd`) · `room.onAdd('players', …)` / `onRemove` (fires for present players too) ·
+`room.sendState(input)` (your per-frame state, throttled + seq-tagged for you) · `room.sendAbility(id, active)` ·
+`room.sendAction(name, args)` (declared actions — see `multiplayer-logic`) · `room.onStateChange` /
+`onMessage(type, cb)` (broadcasts) / `leave` · `room.onDrop` / `onReconnect` / `onLeave` (SDK auto-reconnects).
+
+> Player objects from `onAdd` are **live references** Colyseus mutates in place each patch — stash them and read
+> per frame. Don't iterate `room.state.players` as a plain object (it's a `MapSchema`, not a `Record`).
+
+**2 — Render remotes with `ReplicaScene` + `NetworkDriver`** (each remote is a headless `Character` driven off
+the wire, wearing **their** avatar via the shared `AvatarModelCache`; the fallback clone source is the DEFAULT
+body — see hangout §3a for `io`/`avatarCache`/`baseModel`):
+
+```ts
+import { clone as cloneSkinned } from 'three/examples/jsm/utils/SkeletonUtils.js';
+import { Character, LocomotionAbility, NetworkDriver, ReplicaBody, ReplicaScene,
+  type ReplicaHandle, type ReplicatedParams } from '@helix/humanoid-character';
+
+const remote = new Map<string, PlayerState>();
+
+async function buildReplica(id: string): Promise<ReplicaHandle> {
+  const avatarUrl = remote.get(id)?.avatarUrl;                // room-replicated, backend-resolved ('' = none)
+  const model = (avatarUrl ? await avatarCache.load(avatarUrl) : null)?.model ?? cloneSkinned(baseModel);
+  scene.add(model);
+  const rbody = new ReplicaBody(SPAWN);                       // inert, no-physics body — pose comes from the wire
+  const character = await Character.create({ model, body: rbody });
+  character.abilities.register(new LocomotionAbility(clips)); // same anim graph as the local player
+  const driver = new NetworkDriver({ body: rbody, blackboard: character.blackboard });
+  character.setDriver(driver);
+  return { pushSnapshot: (p) => driver.pushSnapshot(p), update: (dt) => character.update(dt),
+           dispose: () => { character.dispose(); scene.remove(model); } };
+}
+
+const replicas = new ReplicaScene({ build: buildReplica, maxReplicas: 8 });  // maxReplicas is a real perf budget
+if (room) {
+  room.onAdd('players', (player, id) => {
+    if (id === room!.sessionId) return;                       // that's me — I render my own local player
+    remote.set(id, player); replicas.add(id);
+  });
+  room.onRemove('players', (_p, id) => { remote.delete(id); replicas.remove(id); });
+}
+```
+
+**3 — The adapter + send loop.** The wire is all-degrees (`*Deg`); the body wants `facingYaw` in radians (the one
+conversion). **Copy `position`/`activeAbilities` BY VALUE** — `p` is a live schema object mutated in place, so
+passing it by reference collapses the jitter buffer and the remote snaps instead of interpolating.
+
+```ts
+function toReplicatedParams(p: PlayerState): ReplicatedParams {
+  return {
+    position: { x: p.position.x, y: p.position.y, z: p.position.z },   // copy, don't alias
+    facingYaw: (p.facingYawDeg * Math.PI) / 180,                       // the one unit conversion
+    speed: p.speed, moveDirectionDeg: p.moveDirectionDeg, verticalVelocity: p.verticalVelocity,
+    grounded: p.grounded, crouched: p.crouched, aimYawDeg: p.aimYawDeg, aimPitchDeg: p.aimPitchDeg,
+    activeAbilities: [...p.activeAbilities],
+  };
+}
+
+const clock = new THREE.Clock();
+renderer.setAnimationLoop(() => {
+  const dt = Math.min(clock.getDelta(), 0.1);
+  local.update(dt);                                            // local player always runs (single-player safe)
+  if (room) {
+    for (const [id, player] of remote) replicas.pushSnapshot(id, toReplicatedParams(player));
+    replicas.update(dt);
+    room.sendState(localState());                              // build from the blackboard in DEGREES; throttled for you
+    hud.textContent = `${replicas.count + 1} here (you + ${replicas.count})`;
+  }
+  renderer.render(scene, camera);
+});
+```
+
+`localState()` reads your live params off the blackboard (`speed`, `direction`, `cameraYaw`/`cameraPitch` as
+`aimYawDeg`/`aimPitchDeg`, `grounded`, …) + the body, in **degrees**. **Never send bone transforms** — you
+replicate the *inputs* to the animation system; each remote animates client-side. The complete runnable version
+is the **`hangout` template** (`read_template({ name: "hangout" })`); use it as the reference `src/main.ts`.
+
+## Beyond presence — the declarative game logic
+
+When the world needs shared state (scores, teams), server/owned objects, zones, timers, a state machine,
+collections, or ownership, declare them in the `multiplayer` block and read the reference:
+**`read_doc({ name: "multiplayer-logic" })`.** Then start from whichever template above is closest. You still write
+no server code — declared rules run on the platform room; clients read `room.state` and send `sendAction` /
+`sendState`.
+
+## Build, validate, publish
+
+Same as the character recipe §9: `npm install` → `helix install` (resolves the system pin into `helix_modules/`)
+→ `npm run build` → `validate_world` on `dist/` (fix every problem; **heed the `maxPlayers` clamp warning**) →
+`whoami` → `publish_world`. The build contains no `.glb`/`.ktx2` — character assets stream from the CDN.
+
+## The rules that matter (multiplayer)
+
+- **The server is authoritative and platform-owned.** You send input (`sendState`, `sendAction`); the room owns
+  the truth. **No server code** — multiplayer is declarative (the manifest opts in; game logic is data).
+- **Replicate PARAMETERS, not bones.** Position/facing/speed/anim-inputs go on the wire; animation runs
+  client-side. Never send skeletons.
+- **Login required; single-player must still work.** Build local + scene unconditionally; layer multiplayer on
+  only when `joinRoom` succeeds.
+- **Skip your own `sessionId`** in `onAdd` — the server includes you in `players`; render your own local player.
+- **Copy live schema values by value** before caching them (don't alias) — the #1 presence bug.
+- **`maxReplicas` is a real budget** (each replica is a full character) — cap it to `maxPlayers`.
+- **For shared game state, read `multiplayer-logic`** and start from the closest template — don't invent a wire
+  format; declare it.