@hypersoniclabs/helix-mcp 0.2.5 → 0.2.12

package/docs/multiplayer-world.md

@@ -6,10 +6,10 @@ Every multiplayer world builds on the **`humanoid-character`** system (read `get
 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
+> **Discover versions first.** The `CharacterMultiplayer` facade below ships in **`humanoid-character` ≥ 0.2.4**;
+> `Helix.multiplayer` + the typed state accessors are 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.
+> predates the facade, those imports won't exist; don't guess around it.
 
 ## The model — five facts
 
@@ -19,12 +19,13 @@ for `Helix.multiplayer`.
 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).
+3. **Two layers.** (a) **Presence** — players see each other move/animate, wearing their avatars, with floating
+   nameplates (ONE facade call; 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.** The facade owns this: it sets your local player up
+   unconditionally and layers 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**.
@@ -32,8 +33,11 @@ for `Helix.multiplayer`.
 ## 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).
+— you need the player identity). **Also keep `voice.proximity` — voice chat is the DEFAULT for HELIX multiplayer
+worlds** (players expect to talk; remove it only for a deliberately silent world). Cross-field rules are enforced at
+validate/publish: `maxPlayers > 1` **requires** `multiplayer`, and `multiplayer` **forces** `requiresAuth: true`
+(coerced for you). **`scaffold_world` returns the CLI scaffold command and this recipe**; the manifest
+below is what it produces for `kind: "multiplayer"`:
 
 ```json
 {
@@ -42,11 +46,11 @@ Bump `helixVersion` to `"0.3"`, set `maxPlayers > 1`, and add the **`multiplayer
   "slug": "my-hangout",
   "entry": "index.html",
   "maxPlayers": 8,
-  "permissions": ["auth.profile", "multiplayer"],
+  "permissions": ["auth.profile", "multiplayer", "voice.proximity"],
   "multiplayer": { "authoritative": true },
   "supportsMobile": true,
   "contentRating": "everyone",
-  "systems": { "humanoid-character": "^0.2" }
+  "systems": { "humanoid-character": "^0.3" }
 }
 ```
 
@@ -62,145 +66,177 @@ at 12). There is **no `tickRate` knob** — the platform owns the room tick.
 
 ## 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.
+Every multiplayer world is **presence + (optionally) declarative game logic.** Start with **`scaffold_world`**
+(returns the CLI scaffold command + recipe), 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.
+`showBanner()`, 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. |
+| a hangout / social space / co-op room — players just see each other | `hangout` | **presence**: the one facade call + what it composes ("under the hood" appendix = the eject path). The substrate every other template builds on. |
+| a collectible / scavenger world — grab items for points | `collect-a-thon` | declared room/player state + server-spawned **static** pickups (`spawnEntity`) + zones + scoring, rendered via `mp.entities()`. |
 | 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**. |
+| enemies, monsters, guards or townsfolk that are PEOPLE — a horde of humanoids, plus a shopkeeper you can talk to | `npc-wave` | **NPCs in a shared world**: the same shared/host-migrated enemies as `wave-survival`, rendered as full humanoid characters via `humanoidEntities` (the brain stays in the room — the humanoid is only the rendering), plus a client-local stand-body NPC with a proximity `Talk` prompt. The solo NPC surface (behaviours, nav, Vault bodies) is `read_doc({ name: "npc-world" })`. |
+| a ball/puck sport — soccer, hockey, air-hockey | `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. A MULTI-body set (a pool rack) needs a `group` + `claimGroup` action instead — multiplayer-logic §9a. |
+| 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`). **The facade-free template** — see its "when NOT to use the facade" note. |
+| a card game / hand / inventory / crafting | `collections` | structured **collections** — lists of records (a hand of cards), counterMaps, `forEachInList`, `append`/`removeWhere`, read via `room.me.list()`. |
+| a turn-based / board game / co-op boss fight | `turn-arena` | a **state machine** (play → win/lose) + **turn order** (`room.isMyTurn()`) + **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.
+| a shooter — deathmatch, PvE range, horde-with-guns, anything players SHOOT | `shooter-range` | **the combat loop**: guns via the `gun-control` ability (its own recipe: `read_doc({ name: "shooter-worlds" })`), `playerVars.health` + one-claim-per-trigger actions with cooldown/distance gates, gun-declared damage (`weaponItems` + the `weaponDamage` op — server-resolved, never client-named), kill credit + the `down` feed + respawn, destructible slot-respawning targets, and the death ragdoll. |
+| walkie-talkies / team radio / phone calls / voice-chat tuning | `voice-radio` | **voice channels**: the manifest `multiplayer.voice` block (ambient proximity falloff + declared frequencies) + `Helix.voice.setChannel` — exclusive channels, dynamic private-call ids, flat vs proximity render per channel. |
+| anything the world SELLS — a shop, currency packs, a VIP/season pass, cosmetics, unlocks, tips | `world-shop` | **in-world purchases**: the eight product shapes and which to pick (currency, timed/permanent pass, item, bundle, tip jar, free claim), registering products BEFORE the code that buys them, `Helix.purchases` entitlements + `consume`, and the room-side `{on:"purchase"}` rule with `hasPass`/`balanceOf`. Works single-player too. |
+| anything that must be REMEMBERED — progression, currency, a guestbook, a world record, community totals, rankings | `persistent-progress` | **durable storage**, the whole taxonomy and which shape to pick: server-owned player saves (`persistent` playerVars + `save`), the player's own client-written blob (`Helix.dataStore`), world state that outlives the room (`persistent` roomVars + `saveRoom` + merge policies), `counters` and `leaderboards`. |
+
+**Persistence also composes onto a template you already picked** — `persistent-progress` is the full taxonomy,
+but the grammar is small enough to bolt onto any world above: `read_doc({ name: "multiplayer-logic" })` §18 covers
+`persistent: true` playerVars + the `save` verb, `counters`/`increment`, and `leaderboards`/`submitScore`, each
+with a worked config. The same is true of `world-shop` — selling is a layer, not a genre.
+
+**Achievements ride on that same persistence** — §19 covers the `awardAchievement` rule effect (the unforgeable
+`room` badge), server-evaluated `criteria` badges (which work single-player too), the register-the-key-first gotcha,
+and `Helix.achievements` for reading them back.
+
+**Shooting is a template now** — `shooter-range` above, with the client half (gun-control, weapon profiles,
+FX/hit systems, ragdoll) in `read_doc({ name: "shooter-worlds" })`. Other combat shapes (melee, tag,
+capture-the-flag, tower defense) still compose from **declared `actions`** (server-validated, the
+cheat-resistant path — the same claim pattern the shooter uses) — 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)`.
+## The presence on-ramp — one call
 
-**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):
+Presence is the universal substrate, and it is **one facade call** — `CharacterMultiplayer` (from
+`@helix/humanoid-character` ≥ 0.2.4) owns the whole flow: `Helix.init()` → login prompt → your equipped
+**universal avatar** (local + every remote, `''` = default body) → the local `Character` → the guarded room join
+(guests/standalone fall back to single-player) → the **`LocalReconciler`** (server respawns/teleports land on
+your body) → remote replicas with floating **nameplates** → the wire adapters + throttled send loop:
 
 ```ts
 import { Helix } from '@hypersoniclabs/helix-sdk';
-import type { HelixRoom, PlayerState, ReplicaInput } from '@hypersoniclabs/helix-sdk';
+import { CharacterMultiplayer, RapierBody } from '@helix/humanoid-character';
+import { SYSTEM_ASSET_BASE, TRANSCODER_PATH } from './helix.runtime';
 
-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) …
+// Physics + collision geometry are YOUR code — the facade never creates floors.
+const body = await RapierBody.create({ position: SPAWN });
+body.addStaticCuboid({ x: 24, y: 0.5, z: 24 }, { x: 0, y: -0.5, z: 0 });
 
-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;
-  }
-}
+const mp = await CharacterMultiplayer.create({
+  helix: Helix, renderer, scene, camera, body,
+  assetBase: SYSTEM_ASSET_BASE, transcoderPath: TRANSCODER_PATH, spawn: SPAWN,
+});
+
+renderer.setAnimationLoop(() => {
+  const dt = Math.min(clock.getDelta(), 0.1);
+  mp.update(dt);                       // local character → remote snapshots → replica anim → upload
+  // …your world's per-frame code…
+  renderer.render(scene, camera);
+});
 ```
 
-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).
+`mp.room` is your live `HelixRoom` handle (null = single-player: not embedded, guest, or join failed) —
+`sendAction`, `onMessage`, the typed accessors, everything. `mp.count` = rendered remotes. `mp.local` = your
+`Character`. `mp.entities(cfg)` renders synced server entities (see the entity templates).
 
-> 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`).
+**Every option has a default — pass only what you change:**
 
-**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`):
+| Option | Default | Why you'd touch it |
+|---|---|---|
+| `nameplates` | `true` | `false` to hide names (PvP anonymity); or `{ color, width, occludable }` to restyle |
+| `universalAvatars` | `true` | `false` = platform default body only (bespoke player models) |
+| `reconciler` | `true` | leave it — disabling desyncs server respawns/teleports |
+| `join` | `true` | `false` for a deliberately single-player character world |
+| `maxReplicas` | `8` | a real perf budget (each replica is a full character) — keep = `maxPlayers` |
+| `abilities` | locomotion | `(clips) => [new LocomotionAbility(clips), new FlyAbility(...)]` — applied to local AND replicas so anim graphs match |
+| `replica.decorate` | — | additive per-replica extras (health bar, team tint) WITHOUT ejecting: return `{ dispose }` |
+| `replica.build` | — | full replica override; the facade keeps join/loop/adapters |
+| `character` | — | passed through to `Character.create` (camera/body/input config) |
+| `input` | — | a world-owned `InputService` forwarded to the inner `Character.create` — the world owns the DOM attach + the menu context stack; register world keys on it instead of `addEventListener` (character recipe §8c). Omitted ⇒ the character self-creates a private router |
+| `debug` | `false` | narrate body/avatar/replica decisions to the console |
+
+**If the facade fights you, drop to the primitives** — `ReplicaScene`, `NetworkDriver`, `Nameplate`,
+`LocalReconciler`, `EntityScene` are all exported and composable; the `hangout` template's **"under the hood"
+appendix** is the expanded manual equivalent (it's also where the wire-level rules live: copy live schema values
+by value, skip your own sessionId, degrees on the wire). `physics-bumper` is the canonical facade-free world
+(the player IS a physics body — no humanoid replicas at all).
+
+## Voice chat — ON by default, four lines
+
+Players talk to each other — **every HELIX multiplayer world ships voice unless it has a reason not to.**
+`scaffold_world` already declares `voice.proximity` (distance-attenuated, the natural default; `voice.room` =
+flat room-wide) and writes the join block below; a deliberately silent world (a focused puzzle, a music
+experience) OPTS OUT by removing both. The join runs after the room join succeeds:
 
 ```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); });
+if (mp.room) {
+  try {
+    if (await Helix.voice.join()) mp.attachVoice(Helix.voice, manifest.multiplayer.voice);
+  } catch (err) { console.info('voice unavailable:', err); } // fail-soft — never blocks play
 }
 ```
 
-**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.
+That's the whole integration: the facade drives per-player volume off synced positions and lights the
+nameplate mic glyph while someone talks. Mic behavior (push-to-talk **N**, pad: hold modifier+RB / open / muted, device, volumes,
+per-player mutes) belongs to the PLAYER via the platform tablet — a world never renders mic UI.
+
+**Tuning + channels live in the manifest** (`multiplayer.voice`, all optional — see `read_doc({ name:
+"manifest" })`): ambient `mode` + `refDistance`/`maxDistance` falloff, `"spatial": true` for directional
+(HRTF) ambient voice — hear WHERE a speaker stands, loudness untouched — and declared `channels` with a
+render policy each.
+
+**When to declare `"spatial": true`** (opt-in, and cheap — panning is client-side, zero bandwidth/server
+cost, degrades silently on clients without the audio hook; headphones make it shine): reach for it whenever
+*presence* is the product — realistic social spaces (cafes, bars, campfires, hangout worlds — the casual
+hang-with-friends genre), **horror** (a voice behind you IS the scare), hide-and-seek / stealth / tactical
+play where *locating* a speaker is gameplay, and any world already using positional sound design (it makes
+player voice match the world's audio). Skip it when voice is announcer/broadcast-shaped (a host addressing
+the room), when competitive callout clarity matters more than immersion, or when play happens mostly inside
+channels (radio semantics — channels never spatialize regardless). It composes with either ambient mode:
+`proximity` + spatial = full positional presence; `global` + spatial = everyone stays audible but still
+directional. **Channels are exclusive**: `Helix.voice.setChannel('freq-1')` moves the player out of ambient
+into that channel (walkie-talkie semantics); `setChannel(null)` returns; dynamic undeclared ids work and
+render flat — a private phone call is just `` setChannel(`call:${[a, b].sort().join(':')}`) `` from both
+sides. The worked world: `read_template({ name: "voice-radio" })`. Server-driven membership (teams → voice)
+is a rules recipe: a rule sets a `voiceChannel` playerVar, the client reads `room.me.str('voiceChannel')` and
+calls `setChannel` — no server code, no extra machinery.
+
+## Gestures — replicated by default
+
+World-authored JSON gestures (the pose DSL — authoring reference and worked examples in the
+**character-animation doc**; the axis table is deliberately in no doc, read it live with
+`gesture_axis_table`) replicate without any opt-in: `mp.playAnimation('wave')` plays locally the same
+frame and every other client's replica plays it too. Clips never cross the wire — every client registered the
+same JSON from the same bundle, so only NAMES replicate. A **oneshot** relays as a transient event (a late
+joiner correctly misses a wave already in flight); a **loop** enters synced state (`loopGesture`), so late
+joiners start it at replica spawn; `mp.stopAnimation()` clears it. `replicate: false` keeps a play local
+(first-person flourishes, previews). One rule: trigger gestures from input/interaction handlers — never from
+replicated-state observers, or every client fires its own copy.
+
+## Reading game state — the typed accessors
+
+Declared state (room vars, player vars, phase, turns) reads through **guarded, live views** on the room handle —
+no casts, no "did the first patch land yet" checks, safe defaults when a var is missing:
 
 ```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);
-});
+mp.room.vars.num('control')          // room var (default 0)      · .str / .bool / .vec3 / .list / .raw
+mp.room.me.num('score')              // MY player var
+mp.room.player(id).str('team')       // any player's var by session id
+mp.room.phase()                      // the state machine's phase ('' when the world declares no states)
+mp.room.isMyTurn()                   // the turnOrder/turnIndex convention (always false when unused)
 ```
 
-`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`.
+Views re-read the live schema on every call — call them fresh each frame instead of caching results.
+`list()` hands back a real Array (a Colyseus list is iterable but NOT an Array); elements are the live records.
 
 ## Beyond presence — the declarative game logic
 
@@ -210,22 +246,79 @@ collections, or ownership, declare them in the `multiplayer` block and read the
 no server code — declared rules run on the platform room; clients read `room.state` and send `sendAction` /
 `sendState`.
 
+## Converting an existing single-player world to multiplayer
+
+A world that already works solo becomes multiplayer in two moves: add the presence on-ramp (above), then move
+every piece of **authority** out of the client. The second move is where conversions go wrong — single-player
+code is full of self-authority that multiplayer must not keep. Work through this sequence:
+
+1. **Manifest.** Add the `multiplayer` block to `helix.json` (start with `{ "authoritative": true }` + a modest
+   `maxPlayers`; grow `state`/`rules` as you convert logic per `multiplayer-logic`).
+2. **Presence on-ramp** (§ above): the `CharacterMultiplayer.create` call against your existing scene/body —
+   it brings the reconciler, replicas, avatars, and nameplates with it. Your single-player setup stays
+   UNCONDITIONAL (the golden rule) — the facade layers multiplayer on only when a join succeeds.
+3. **Audit every write to your own position — the #1 conversion bug.** Search the source for `.teleport(`,
+   `.respawn(`, and anything else that sets the local character's transform outside normal movement: kill-planes,
+   checkpoints, round resets, "play again" flows, portals, out-of-bounds handlers. With a room, EACH of those must
+   become a server-side rule using the `respawn`/`teleport` effect — triggered by a declared zone, timer, phase,
+   or an explicit action (client sends `requestRespawn`, a rule respawns `self`). The facade's reconciler lands the
+   server's move on your body; keep the direct local teleport ONLY on the single-player path (`if (!mp.room)`).
+   **Why this is not optional:** the room's movement gate rejects any implausible position jump and holds the
+   seat's last plausible position — and it never self-heals. A client-side teleport therefore freezes your avatar
+   for every OTHER player (you keep playing locally; they see you stuck or vanished at the old spot). Solo testing
+   cannot surface this — it only breaks with a second client connected.
+4. **Round/lifecycle resets reset everyone server-side, in one rule.** "New round → everyone back to start" is
+   `{"do":"forEachPlayer","as":"p","then":[{"do":"respawn","player":"p","to":<spawn>}]}` on the round timer/phase —
+   never a broadcast that each client answers by teleporting itself (that's one copy of the step-3 bug per player).
+5. **Client-detected events may stay client-detected** (a finish line crossed, a collectible touched): send a
+   declared `action`; the *consequences* (score, phase change, respawn) happen in rules — guarded by an `if` on a
+   room var (or use a declared zone) so a re-fired action can't double-apply.
+6. **Shared state replaces local state.** Any value both players must agree on (score, round, winner) moves from a
+   JS variable into declared `state` mutated by rules; clients render it via the typed accessors and never mutate
+   their copy.
+7. **Verify with TWO clients** (two browser windows). Authority bugs are invisible solo — specifically: finish +
+   respawn in one window and CONFIRM the other window sees that avatar move to spawn (not freeze or vanish).
+
+> Converting a world built OUTSIDE HELIX entirely (a plain three.js/vite game)? Read
+> **`read_doc({ name: "bring-your-world" })`** first — it stages the platform adoption (become a world → adopt
+> the character → go multiplayer) and hands you this section for the final step.
+
 ## Build, validate, publish
 
-Same as the character recipe §9: `npm install` → **`install_world_packages`** (MCP tool) (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.
+**`scaffold_world`** returns the CLI scaffold command plus the applicable recipe. Run it, then:
+`npm install` → **`install_world_packages`** (MCP tool) (resolves the system pin into
+`helix_modules/`) → `npm run build` → `validate_world` on `dist/` (fix every problem; **heed the `maxPlayers`
+clamp warning**) → **`helix verify-subpath dist`** (REQUIRED — the only local gate that serves the bundle from a nested path, the way a published world is actually served; preview/validate/inspect all serve from the origin root and cannot see a root-absolute 404) → `whoami` → `publish_world`. The build contains no `.glb`/`.ktx2` — character assets stream
+from the CDN.
+
+## Verify placement and zones by measurement — see the world-inspect doc
+
+Before publishing, `inspect_world` on `dist/` measures the layout as data: placement checks
+(floating/sunk/intersecting geometry, collider-vs-visual mismatches) PLUS the zone checks — it reads the
+declared `multiplayer.json` zones and verifies each against real geometry (a kill band the pit floor misses,
+a checkpoint volume floating in empty space — zones never render, so nothing else can catch these).
+`focusNear: [x, y, z]` checks a single object; `world_metrics` sizes gaps/steps/doorways before you place
+geometry. Findings are measurements to check against your intent, never orders to change the world:
+
+```
+read_doc("world-inspect")
+```
 
 ## 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`.
+- **The server is authoritative and platform-owned.** You send input (`sendState` — the facade does this —
+  and `sendAction`); the room owns the truth. **No server code** — multiplayer is declarative.
+- **Never move your own body across the map client-side.** Teleports/respawns/round resets are server rules (the
+  `respawn`/`teleport` effects) that the facade's reconciler lands locally; a client-side teleport trips the
+  movement gate and freezes your avatar for everyone else. Converting a single-player world? Read the conversion
+  section.
+- **Keep the top-center clear for platform chrome.** The player shell overlays a bar (Exit / Save Progress /
+  helixOS) across the top-center of every world. Put your score/HUD in a corner or along the bottom, never
+  top-center (it renders behind the chrome) — the templates anchor `#hud` top-left; see the character recipe.
+- **Read state through the typed accessors, fresh each frame** (`room.vars` / `room.me` / `room.player(id)`);
+  never cache a read across frames and never mutate your copy.
+- **`maxReplicas` is a real budget** (each replica is a full character) — keep it = your `maxPlayers`.
+- **Replicate PARAMETERS, not bones.** The facade uploads position/facing/speed/anim-inputs; animation runs
+  client-side. (Only relevant if you eject — never send skeletons.)
 - **For shared game state, read `multiplayer-logic`** and start from the closest template — don't invent a wire
   format; declare it.