@hypersoniclabs/helix-mcp 0.2.4 → 0.2.12

package/docs/multiplayer-templates/chrono-orchard.md

@@ -30,7 +30,7 @@ farming, idle/incremental, day-cycle, anything where elapsed real time matters.
   "slug": "chrono-orchard",
   "entry": "index.html",
   "maxPlayers": 8,
-  "permissions": ["auth.profile", "multiplayer"],
+  "permissions": ["auth.profile", "multiplayer", "voice.proximity"],
   "multiplayer": {
     "authoritative": true,
     "state": {
@@ -80,7 +80,7 @@ farming, idle/incremental, day-cycle, anything where elapsed real time matters.
   },
   "supportsMobile": true,
   "contentRating": "everyone",
-  "systems": { "humanoid-character": "^0.2" }
+  "systems": { "humanoid-character": "^0.3" }
 }
 ```
 
@@ -90,29 +90,43 @@ thresholds are all plain expressions. `season` re-arms itself, so the weather to
 
 ## 3. The client — `src/main.ts` (delta from `hangout`)
 
-Presence + a crop render-proxy (server entities, like `collect-a-thon`) **scaled by `growth`**, plus the two
-actions and the weather banner:
+Presence + a crop `mp.entities()` proxy (server entities, like `collect-a-thon`) **scaled by `growth`**, plus the
+two actions and the weather banner:
 
 ```ts
-const crops = new Map<string, { mesh: THREE.Object3D; state: EntityState }>();
-if (room) {
-  room.onAdd('entities', (e, id) => { const m = makeSprout(); scene.add(m); crops.set(id, { mesh: m, state: e }); });
-  room.onRemove('entities', (_e, id) => { const c = crops.get(id); if (c) { scene.remove(c.mesh); crops.delete(id); } });
-}
+const entities = mp.entities({
+  build: () => {
+    const mesh = makeSprout(); scene.add(mesh);
+    return {
+      object3d: mesh,
+      // per-frame: grow each crop visually from its live synced `growth` (clamped to a ripe size at ~15s)
+      onUpdate: (e) => {
+        const g = Math.min(1, Number((e.vars as Record<string, unknown>)?.growth ?? 0) / 15);
+        mesh.scale.setScalar(0.2 + 0.8 * g);              // sprout → ripe
+      },
+      dispose: () => scene.remove(mesh),
+    };
+  },
+});
 
-// frame loop (inside `if (room)`): grow each crop visually from its synced `growth` (clamped to a ripe size at ~15s)
-for (const [, c] of crops) {
-  if (c.state.position) c.mesh.position.set(c.state.position.x, c.state.position.y, c.state.position.z);
-  const g = Math.min(1, Number((c.state.vars as Record<string, unknown>)?.growth ?? 0) / 15);
-  c.mesh.scale.setScalar(0.2 + 0.8 * g);                 // sprout → ripe
-}
+// World-owned input router (character-world §8c): plant is the STANDARD `interact` (E / face-left),
+// water is a custom action on genre-freed reload real estate (KeyF + faceUp) with a `label`.
+const input = new InputService();
+input.attach(window as never);
+input.attachPointer(renderer.domElement as never, undefined, { dragLook: true });
+registerStandardActions(input, { only: ['interact'] });
+input.registerAction('world.water', { kind: 'button', keys: ['KeyF'], pad: 'faceUp', label: 'Water' }, 'world');
+const mp = await CharacterMultiplayer.create({ /* …, */ input });
 
-addEventListener('keydown', (e) => {
-  if (e.key === 'e') room.sendAction('plant');
-  else if (e.key === 'q') room.sendAction('water');       // server enforces the 3s cooldown
-});
-room.onMessage('weatherChanged', (m) => showBanner(Number(m.reward) > 1 ? '☀ Bumper crop! (reward up)' : '☁ Lean season'));
-room.onMessage('watered', () => showBanner('💧 Watered — crops sped up'));
+// each frame, AFTER mp.update(dt): input action → declared action
+if (input.wasPressed('interact')) mp.room?.sendAction('plant');
+if (input.wasPressed('world.water')) mp.room?.sendAction('water');   // server enforces the 3s cooldown
+
+mp.room?.onMessage('weatherChanged', (m) => showBanner(Number(m.reward) > 1 ? '☀ Bumper crop! (reward up)' : '☁ Lean season'));
+mp.room?.onMessage('watered', () => showBanner('💧 Watered — crops sped up'));
+
+// HUD control hints render through tokens (E/F on keyboard, X/Y on pad), never hardcoded key names:
+hud.innerHTML = `…<small>${input.format('{interact} plant where you stand · {world.water} waters')}</small>`;
 ```
 
 **Footguns:** time is **server** time (`{op:now}`) — never compute elapsed from a client clock; read each crop's
@@ -120,4 +134,4 @@ live `growth` per frame; the `water` cooldown is server-enforced (the client jus
 
 ## 4. Build, validate, publish
 
-`npm install` → **`install_world_packages`** (MCP tool) → `npm run build` → `validate_world` on `dist/` → `whoami` → `publish_world`.
+`npm install` → **`install_world_packages`** (MCP tool) → `npm run build` → `validate_world` on `dist/` → **`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`.

package/docs/multiplayer-templates/collect-a-thon.md

@@ -30,7 +30,7 @@ A small slice of the DSL (each links into `multiplayer-logic`):
   "slug": "collect-a-thon",
   "entry": "index.html",
   "maxPlayers": 8,
-  "permissions": ["auth.profile", "multiplayer"],
+  "permissions": ["auth.profile", "multiplayer", "voice.proximity"],
   "multiplayer": {
     "authoritative": true,
     "state": {
@@ -70,7 +70,7 @@ A small slice of the DSL (each links into `multiplayer-logic`):
   },
   "supportsMobile": true,
   "contentRating": "everyone",
-  "systems": { "humanoid-character": "^0.2" }
+  "systems": { "humanoid-character": "^0.3" }
 }
 ```
 
@@ -80,47 +80,37 @@ a typo'd verb/var with a did-you-mean — run `validate_world` and read the path
 
 ## 3. The client — `src/main.ts` (delta from `hangout`)
 
-Same presence wiring as `hangout` (join, replicas, `sendState`). The **new part** is the *entity render-proxy*:
-spawn a mesh per synced server entity and render it off its **live** state each frame — the client never writes
-entity state (the server owns it).
+Presence is the facade (hangout §3). The **new part** is rendering the synced server entities —
+**`mp.entities()`**: a mesh per entity, positioned off EntityScene's source-time interpolation (a kind with no
+`motion` fn is server-authoritative: render only, never uploaded). The client never writes entity state.
 
 ```ts
-import type { EntityState } from '@hypersoniclabs/helix-sdk';
-
-const coins = new Map<string, { mesh: THREE.Mesh; state: EntityState }>();
-const isActive = (e: EntityState) => (e.vars as Record<string, unknown> | undefined)?.active !== false;
-
-if (room) {
-  // Spawn a coin mesh on add, drop it on destroy. `entity` is a LIVE ref colyseus mutates in place —
-  // stash it and read .position / .vars each frame (no per-entity subscription needed).
-  room.onAdd('entities', (entity, id) => {
-    const mesh = makeCoin(); scene.add(mesh);            // makeCoin(): your spinning-disc THREE.Mesh
-    coins.set(id, { mesh, state: entity });
-  });
-  room.onRemove('entities', (_entity, id) => {
-    const c = coins.get(id);
-    if (c) { scene.remove(c.mesh); c.mesh.geometry.dispose(); coins.delete(id); }
-  });
-}
-
-// …in the frame loop, inside `if (room) { … }`, after replicas.update(dt):
-for (const [, c] of coins) {
-  const active = isActive(c.state);
-  c.mesh.visible = active;                                // hidden after pickup until the respawn timer fires
-  if (active && c.state.position) {
-    const p = c.state.position;
-    c.mesh.position.lerp(target.set(p.x, p.y + 0.8, p.z), 0.25);   // interpolate toward the synced position
-    c.mesh.rotation.y += dt * 2.6;
-  }
-}
+const entities = mp.entities({
+  build: (kind, id) => {
+    // EntityScene positions the GROUP at the entity's networked point — bake the visual float into a child.
+    const group = new THREE.Group();
+    const coin = makeCoin();                              // makeCoin(): your spinning-disc THREE.Mesh
+    coin.position.y = 0.8;
+    group.add(coin); scene.add(group);
+    return {
+      object3d: group,
+      onUpdate: (e, dt) => {                              // per-frame: read the LIVE vars, drive the visual
+        coin.visible = (e.vars as Record<string, unknown>)?.active !== false;  // hidden until the respawn timer fires
+        if (coin.visible) coin.rotation.y += dt * 2.6;
+      },
+      dispose: () => { scene.remove(group); coin.geometry.dispose(); },
+    };
+  },
+});
+// mp.update(dt) drives the interpolation + onUpdate — nothing to add in your frame loop.
 ```
 
-Read each player's `score` off `room.state.players[id].vars.score` for a HUD/leaderboard. **Footguns:** read the
-live `state` each frame (don't snapshot `.vars` once); guard `room.state.entities` until the first patch (empty on
-frame 0). This *server-only* proxy is for entities the **server** drives — for entities a **client** simulates
-(`authority:'owner'`), use `EntityScene` instead (see the `relic-bearers` / physics templates).
+Read scores through the typed accessors — `mp.room.me.num('score')` for your HUD,
+`mp.room.player(id).num('score')` for a leaderboard. Count live coins via `entities.entries()`.
+**Footgun:** this render-only shape is for entities the **server** drives — for entities a **client** simulates
+(`authority:'owner'`), add a `motion` fn (see the `relic-bearers` / physics templates); same `mp.entities()` call.
 
 ## 4. Build, validate, publish
 
 `npm install` → **`install_world_packages`** (MCP tool) → `npm run build` → `validate_world` on `dist/` (fix every problem; watch the
-per-tick budget + entity caps) → `whoami` → `publish_world`.
+per-tick budget + entity caps) → **`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`.

package/docs/multiplayer-templates/collections.md

@@ -31,7 +31,7 @@ world.
   "slug": "card-showdown",
   "entry": "index.html",
   "maxPlayers": 8,
-  "permissions": ["auth.profile", "multiplayer"],
+  "permissions": ["auth.profile", "multiplayer", "voice.proximity"],
   "multiplayer": {
     "authoritative": true,
     "state": {
@@ -69,7 +69,7 @@ world.
   },
   "supportsMobile": true,
   "contentRating": "everyone",
-  "systems": { "humanoid-character": "^0.2" }
+  "systems": { "humanoid-character": "^0.3" }
 }
 ```
 
@@ -81,36 +81,36 @@ per-tick budget — list scans are charged at the declared `maxLen`.
 ## 3. The client — `src/main.ts` (delta from `hangout`)
 
 A normal presence world; the new part is **reading the synced hand** and binding the actions. The hand is a
-Colyseus list of record objects — read it off `room.state.players[id].vars.hand` and render a HUD:
+declared list of records — `room.me.list()` hands you a real Array (live elements), no casts, no index loops.
+(The engine-repo template predates the typed accessors and hand-rolls these reads; write NEW worlds the
+accessor way shown here.)
 
 ```ts
 type CardRec = { suit: string; rank: number; played: boolean };
-function handOf(p: PlayerState | undefined): CardRec[] {
-  const list = (p?.vars as { hand?: { length: number; [i: number]: unknown } } | undefined)?.hand;
-  const out: CardRec[] = [];
-  for (let i = 0; i < (list?.length ?? 0); i++) {
-    const r = list![i] as { suit?: string; rank?: number; played?: boolean };
-    out.push({ suit: String(r?.suit ?? '?'), rank: Number(r?.rank ?? 0), played: Boolean(r?.played) });
-  }
-  return out;
-}
 
-// each frame, render your hand + the computed scalars:
-const me = room.state.players[room.sessionId];
-renderHandHud(handOf(me), numVar(me, 'handValue'), numVar(me, 'redCount'));
+// World-owned input router (character-world §8c). A card game has no gunplay or crouching — the
+// genre frees interact's faceLeft and crouch's faceRight for the two card verbs (gate-disable the
+// always-on owner first: config `character.locomotion.allowCrouch: false`). Customs carry labels.
+const input = new InputService();
+input.attach(window as never);
+input.attachPointer(renderer.domElement as never, undefined, { dragLook: true });
+input.registerAction('world.mark',    { kind: 'button', keys: ['KeyM'], pad: 'faceLeft',  label: 'Mark card' }, 'world');
+input.registerAction('world.discard', { kind: 'button', keys: ['KeyH'], pad: 'faceRight', label: 'Discard' },  'world');
+const mp = await CharacterMultiplayer.create({ /* …, */ input, character: { locomotion: { allowCrouch: false } } });
+const room = mp.room!;
 
-// input → actions (the server mutates the list authoritatively):
-addEventListener('keydown', (e) => {
-  if (e.key === 'm') room.sendAction('mark');
-  else if (e.key === 'g') room.sendAction('discard');
-});
+// each frame, AFTER mp.update(dt) — render the hand + send intents (the server mutates the list):
+renderHandHud(room.me.list<CardRec>('hand'), room.me.num('handValue'), room.me.num('redCount'));
+if (input.wasPressed('world.mark')) room.sendAction('mark');
+if (input.wasPressed('world.discard')) room.sendAction('discard');
+// hint the verbs via tokens (M/H on keyboard, X/B on pad), never hardcoded key names:
+hintEl.innerHTML = input.format('{world.mark} mark red · {world.discard} discard played');
 ```
 
-**Footguns:** the hand is a live `ArraySchema` (read length + index per frame, don't cache the array); guard
-`vars` until the first patch; drawing/marking/discarding are all server writes via zones/actions — the client only
-reads + sends intents.
+**Footguns:** call `list()` fresh each frame (it materializes the current list; the elements stay live);
+drawing/marking/discarding are all server writes via zones/actions — the client only reads + sends intents.
 
 ## 4. Build, validate, publish
 
 `npm install` → **`install_world_packages`** (MCP tool) → `npm run build` → `validate_world` on `dist/` (watch `listMaxLen`/`recordFields`
-caps + the per-tick budget) → `whoami` → `publish_world`.
+caps + the per-tick budget) → **`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`.

package/docs/multiplayer-templates/hangout.md

@@ -1,13 +1,15 @@
 # Multiplayer template — `hangout`
 
 **What it is.** A 2–8 player social space: everyone sees everyone else move, animate, jump, and look around in
-one shared world. **Capability: presence** — the see-each-other-move substrate every other multiplayer template
-builds on. Lifted from the verified `multiplayer-hangout` world; this is the reference `src/main.ts` the other
-templates *delta from*.
+one shared world, wearing their universal avatars, with floating nameplates. **Capability: presence** — the
+see-each-other substrate every other multiplayer template builds on. Lifted from the verified
+`multiplayer-hangout` world; the whole substrate is ONE `CharacterMultiplayer` call (the appendix below shows
+what it composes — the eject path when a world outgrows the defaults).
 
 > Read the multiplayer **hub** first (`get_started({ kind: "multiplayer" })`) for the model + the manifest opt-in,
 > and the **character recipe** (`get_started({ kind: "character" })`) — a hangout is the character world plus the
-> layer below. This template is publish-shaped: a real `systems` pin + `helix install`.
+> layer below. This template is publish-shaped: a real `systems` pin + `helix install`. **`scaffold_world` with
+> `kind: "multiplayer"` writes exactly this world** — the sections below explain what it wrote.
 
 ## 1. DSL used
 
@@ -26,159 +28,170 @@ from a logic-bearing template — `collect-a-thon` is the simplest next step.
   "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" }
 }
 ```
 
+`voice.proximity` opts the hangout into proximity voice chat (hear who's near you) — natural for a social
+space; drop it for a silent world. Falloff tuning + channels live in an optional `multiplayer.voice` block —
+see the `voice-radio` template.
+
 `maxPlayers > 1` **requires** the `multiplayer` permission; `multiplayer` **forces** login (coerced for you). The
 `humanoid-character` pin is resolved by `helix install` into `helix_modules/` (the `@helix/humanoid-character`
-vite alias from the character recipe). Keep `maxPlayers` modest — `validate_world` warns if you exceed the
-per-room cap.
+vite alias from the character recipe) — the `CharacterMultiplayer` facade needs **≥ 0.2.4**. Keep `maxPlayers`
+modest — `validate_world` warns if you exceed the per-room cap.
 
 ## 3. The client — `src/main.ts`
 
-Add `"@hypersoniclabs/helix-sdk": "{{SDK_DEP_SPEC}}"` to `package.json` dependencies for `Helix.multiplayer`; the replica primitives
-(`ReplicaScene`, `NetworkDriver`, `ReplicaBody`) come from the `humanoid-character` system you already pin.
+Add `"@hypersoniclabs/helix-sdk": "{{SDK_DEP_SPEC}}"` to `package.json` dependencies for `Helix.multiplayer`.
 `index.html`, `vite.config.ts`, `tsconfig.json`, `src/loading.ts`, `src/helix.runtime.ts` are **identical to the
-character recipe** — only `src/main.ts` + `public/helix.json` differ. Build your local player exactly as in the
-character recipe, then layer multiplayer on:
-
-**a. Init FIRST, then load bodies — every player renders THEIR universal avatar.** The character body is
-bind-once, so the session (and with it the local player's equipped avatar) must resolve *before* assets load:
+character recipe** (start with scaffold_world for the CLI command and recipe). Build your scene + physics as usual, then the whole
+multiplayer substrate is one call:
 
 ```ts
 import { Helix } from '@hypersoniclabs/helix-sdk';
-import type { HelixRoom, PlayerState, ReplicaInput } from '@hypersoniclabs/helix-sdk';
-import { AvatarModelCache, createCharacterAssetIO, loadCharacterAssets,
-  UNIVERSAL_AVATAR_SKELETON } from '@helix/humanoid-character';
+import { CharacterMultiplayer, InputService, RapierBody } from '@helix/humanoid-character';
 import { SYSTEM_ASSET_BASE, TRANSCODER_PATH } from './helix.runtime';
 
+// …three.js scene/camera/ground as in the character recipe. LIGHTING: the verified hangout world this
+// template lifts from is RUNTIME-LIT and ships BAKED — no hand-placed lights; it pins the `visual` system,
+// fetches public/helix.visuals.json, hands its canvas to createVisualRuntime (renderer = visuals.renderer),
+// and bakes its light field at publish (a hangout is the bounded-static poster child). The scaffold still
+// writes the classic hand-lit starter; converting is five steps — read_doc({ name: "lighting-world" })…
+
+// 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 }); // flat floor, top at y=0
+
+// ONE world-owned input router, shared with the character (character-world §8c). A pure hangout
+// registers NO world actions on it — it's pre-wired so game verbs land on input.registerAction
+// (never raw addEventListener) the moment the world grows any.
+const input = new InputService();
+input.attach(window as never);
+input.attachPointer(renderer.domElement as never, undefined, { dragLook: true });
+
+// init → login → avatars (yours + everyone's) → local Character → guarded join → LocalReconciler →
+// replicas with nameplates → wire adapters + throttled send loop. Every option has a default; see the
+// hub's options table for the opt-outs (nameplates/universalAvatars: false) and hooks (abilities,
+// replica.decorate/build).
+const mp = await CharacterMultiplayer.create({
+  helix: Helix, renderer, scene, camera, body, input,
+  assetBase: SYSTEM_ASSET_BASE, transcoderPath: TRANSCODER_PATH, spawn: SPAWN,
+});
+
+// Proximity voice (this world declares voice.proximity): fail-soft — false (voice off for this
+// environment) and errors both leave the world fully playable. The facade drives per-player volume
+// off synced positions + lights the nameplate mic glyph; mic behavior (push-to-talk N, pad modifier+RB / open /
+// muted, device, mutes) is the PLAYER's via the platform tablet — render no mic UI.
+if (mp.room) {
+  try {
+    if (await Helix.voice.join()) mp.attachVoice(Helix.voice);
+  } catch (err) {
+    console.info('voice unavailable:', err);
+  }
+}
+
+const clock = new THREE.Clock();
+renderer.setAnimationLoop(() => {
+  const dt = Math.min(clock.getDelta(), 0.1);
+  mp.update(dt); // local character → remote snapshots → replica anim → upload
+  hud.textContent = mp.room
+    ? `Hangout — ${mp.count + 1} here (you + ${mp.count})`
+    : mp.embedded
+      ? 'Single-player (log in for multiplayer)'
+      : 'Standalone dev — open inside HELIX for multiplayer';
+  renderer.render(scene, camera);
+});
+```
+
+That's the whole presence surface. `mp.room` is your live `HelixRoom` (null = single-player) for `sendAction` /
+`onMessage` / the typed accessors when you add game logic; `mp.local` is your `Character`.
+
+## 4. Build, validate, publish
+
+`npm install` → **`install_world_packages`** (MCP tool) (resolves the `humanoid-character` pin) → `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.
+
+## Appendix — under the hood (the eject path)
+
+What `CharacterMultiplayer.create` composes, expanded — **you don't write this**; it's here so you can reason
+about the substrate, and it's the starting point if a world outgrows the facade (all these primitives stay
+exported). The wire-level rules live here because only this code touches the wire.
+
+**a. Init FIRST, then load bodies** — the session (and with it your equipped avatar) must resolve *before*
+assets load; the character body is bind-once:
+
+```ts
 const { embedded, user } = await Helix.init();
 if (embedded && !user) {
   try { await Helix.auth.requestLogin(); } catch { /* declined → guest, default body, single-player */ }
 }
-
-// One shared IO = one KTX2 transcoder; one AvatarModelCache fetches each distinct avatar GLB once
-// (your own + every remote's — rejoins and repeat wearers are free).
+// One shared IO = one KTX2 transcoder; one AvatarModelCache fetches each distinct avatar GLB once.
 const io = createCharacterAssetIO({ renderer, transcoderPath: TRANSCODER_PATH });
 const avatarCache = new AvatarModelCache({ io });
 const { model: baseModel, clips } = await loadCharacterAssets(SYSTEM_ASSET_BASE, { io }); // the DEFAULT body
-
-// Local player: my equipped avatar when it's converted for this rig, else a clone of the default body.
-// Worlds that opt OUT of universal avatars delete these three lines (see character.universalAvatar.enabled).
-const equipped = await Helix.avatar.getEquipped();  // null for guests / no avatar / any failure
-const ownAvatarUrl = equipped?.glbUrl && equipped.skeleton === UNIVERSAL_AVATAR_SKELETON ? equipped.glbUrl : null;
-const localModel = (ownAvatarUrl !== null ? await avatarCache.load(ownAvatarUrl) : null)?.model ?? cloneSkinned(baseModel);
-// …scene.add(localModel) and Character.create({ model: localModel, … }) exactly as the character recipe.
+// Local body: my equipped avatar when it's converted for this rig, else a clone of the default body.
+const equipped = await Helix.avatar.getEquipped();
+const ownUrl = equipped?.glbUrl && equipped.skeleton === UNIVERSAL_AVATAR_SKELETON ? equipped.glbUrl : null;
+const localModel = (ownUrl ? await avatarCache.load(ownUrl) : null)?.model ?? cloneSkinned(baseModel);
+// …scene.add(localModel), Character.create({ model: localModel, camera, domElement, body }), register abilities.
 ```
 
-**b. Join — guarded, so guests / standalone fall back to single-player:**
+**b. Join — guarded, so guests / standalone fall back to single-player; then wire the `LocalReconciler`**
+(mandatory in EVERY multiplayer world — the room acks gate-rejected uploads with the held authoritative
+position, and the reconciler snaps your local body to it; that's how a server `respawn`/`teleport` rule lands on
+YOUR client-predicted body, and how a reconnect/F5 re-syncs):
 
 ```ts
 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;
-  }
+  try { room = await Helix.multiplayer.joinRoom(); }
+  catch (err) { console.info('multiplayer unavailable — running single-player:', err); }
 }
+if (room) new LocalReconciler({ room, body });
 ```
 
-The `HelixRoom` handle (Colyseus, re-exposed under `Helix.*`): `room.state` (`players`) · `room.sessionId` (yours
-— skip it in `onAdd`) · `room.onAdd('players', …)` / `onRemove` (fires for present players too) ·
-`room.sendState(input)` (throttled + seq-tagged for you) · `room.sendAbility(id, active)` · `room.onStateChange` /
-`onMessage` / `leave` · `room.onDrop` / `onReconnect` / `onLeave` (auto-reconnect).
-
-> 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`).
-
-**c. Render remotes — `ReplicaScene` + `NetworkDriver`** (each remote is a headless `Character` driven off the
-wire, wearing **their** avatar — the room replicates each player's backend-resolved `avatarUrl`, `''` = none):
+**c. Remote replicas — `ReplicaScene` + `NetworkDriver`** (each remote is a headless `Character` driven off the
+wire, wearing THEIR avatar, with a `Nameplate`):
 
 ```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> {
-  // THEIR avatar via the shared cache; any failure (or '') falls back to the DEFAULT body — never yours.
-  const avatarUrl = remote.get(id)?.avatarUrl;
+  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 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);                                // the driver feeds the blackboard from snapshots
+  character.abilities.register(new LocomotionAbility(clips));  // same anim graph as the local player
+  let active = new Set<string>();
+  const driver = new NetworkDriver({
+    body: rbody, blackboard: character.blackboard,
+    onActiveAbilitiesChanged: (next) => { active = syncActiveAbilities(character.abilities, active, next); },
+  });
+  character.setDriver(driver);
+  const plate = new Nameplate(nameplateLabel(remote.get(id)?.displayName, id)).attachTo(character);
   return { pushSnapshot: (p) => driver.pushSnapshot(p), update: (dt) => character.update(dt),
-           dispose: () => { character.dispose(); scene.remove(model); } };
+           dispose: () => { plate.dispose(); character.dispose(); scene.remove(model); } };
 }
-
-const replicas = new ReplicaScene({ build: buildReplica, maxReplicas: 8 });  // maxReplicas is a real perf budget
+const replicas = new ReplicaScene({ build: buildReplica, maxReplicas: 8 }); // 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);                 // async build; the pool buffers snapshots until ready
+    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); });
 }
 ```
 
-**d. 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
-aliasing it collapses the `NetworkDriver` 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],
-  };
-}
-
-// Build your local wire state from the blackboard (the engine's live param bus) + body, in DEGREES.
-function localState(): ReplicaInput {
-  const bb = local.blackboard;
-  return {
-    position: body.position,
-    facingYawDeg: (body.facingYaw * 180) / Math.PI,
-    speed: bb.get<number>('speed'), moveDirectionDeg: bb.get<number>('direction'),
-    verticalVelocity: bb.get<number>('verticalVelocity'), grounded: bb.get<boolean>('isGrounded'),
-    crouched: body.isCrouched, aimYawDeg: bb.get<number>('cameraYaw'), aimPitchDeg: bb.get<number>('cameraPitch'),
-  };
-}
-
-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());                              // coalesced + throttled to the room rate
-    hud.textContent = `${replicas.count + 1} here (you + ${replicas.count})`;
-  }
-  renderer.render(scene, camera);
-});
-```
-
-That's the whole presence surface: build local **unconditionally** → join when logged in → spawn replicas off
-`onAdd` → each frame, snapshot the remotes + `sendState` yourself. **Never send bone transforms** — you replicate
-the *inputs* to the animation system; each remote animates client-side.
-
-## 4. Build, validate, publish
-
-`npm install` → **`install_world_packages`** (MCP tool) (resolves the `humanoid-character` pin) → `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.
+**d. The adapters + send loop.** The wire is all-degrees (`*Deg`); the body wants `facingYaw` in radians (the one
+conversion — `toReplicatedParams`/`buildLocalState` are exported if you eject). **Copy `position` /
+`activeAbilities` BY VALUE** — a player object from `onAdd` is a live schema object mutated in place each patch;
+aliasing it collapses the `NetworkDriver` jitter buffer and the remote snaps instead of interpolating. Each
+frame: `local.update(dt)` → push `toReplicatedParams(player)` per remote → `replicas.update(dt)` →
+`room.sendState(buildLocalState(local.blackboard, body))` (coalesced + throttled for you). **Never send bone
+transforms** — you replicate the *inputs* to the animation system; each remote animates client-side.