@helix3/helix-mcp 0.2.2-helix3.14

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

@@ -0,0 +1,126 @@
+# Multiplayer template — `collect-a-thon`
+
+**What it is.** A 2–8 player scramble: the server spawns coins at fixed spots; run into one to score its value
+and it hides, then respawns a few seconds later. **Capability: declared state + server-authoritative *static*
+entities + attached zones + keyed timers** — the first world with real game logic, and the simplest
+*server-only* entity pattern (the client is a **pure renderer**, no client authority → cheat-proof). Lifted from
+the verified `multiplayer-collect-a-thon` world.
+
+> Read the **hub** (`get_started({ kind: "multiplayer" })`) and the **`hangout`** template first — this is
+> `hangout` (presence) **plus** the declarative layer below. Grammar reference: `read_doc({ name: "multiplayer-logic" })`.
+
+## 1. DSL used
+
+A small slice of the DSL (each links into `multiplayer-logic`):
+- **Declared state** (§2) — `roomVars.spawned` (a spawn guard) + `playerVars.score`.
+- **Entities** (§9) — one `coin` kind with `vars` (`value`, `active`) and an **attached `zone`** (§10) — a sphere
+  centered on each coin that fires `zoneEnter` when a player walks in. `authority` defaults to **server** (static,
+  cheat-proof — no `motion`, no client hosting).
+- **Timers** (§11) — `respawn`, **keyed `entity:coin`** so each coin has its own independent countdown.
+- **Rules** (§3) — three: a `tick` rule that spawns the coins **once** (guarded by `spawned < 1`); a
+  `zoneEnter` rule (binds `self` = the player, `source` = the coin) that scores + deactivates + arms the per-coin
+  timer; a `timerElapsed` rule that re-activates the coin (`self` = the keyed coin).
+
+## 2. The manifest — `public/helix.json`
+
+```json
+{
+  "helixVersion": "0.3",
+  "title": "Collect-a-thon",
+  "slug": "collect-a-thon",
+  "entry": "index.html",
+  "maxPlayers": 8,
+  "permissions": ["auth.profile", "multiplayer"],
+  "multiplayer": {
+    "authoritative": true,
+    "state": {
+      "roomVars": { "spawned": { "type": "number", "default": 0 } },
+      "playerVars": { "score": { "type": "number", "default": 0 } }
+    },
+    "entities": {
+      "coin": {
+        "vars": { "value": { "type": "number", "default": 10 }, "active": { "type": "boolean", "default": true } },
+        "zone": { "shape": "sphere", "radius": 1.5 }
+      }
+    },
+    "timers": { "respawn": { "keyed": "entity:coin" } },
+    "rules": [
+      {
+        "when": { "on": "tick", "everyN": 1 },
+        "if": { "op": "<", "a": { "var": "room.spawned" }, "b": 1 },
+        "then": [
+          { "do": "spawnEntity", "kind": "coin", "at": { "vec3": [7, 0, 0] } },
+          { "do": "spawnEntity", "kind": "coin", "at": { "vec3": [-7, 0, 0] } },
+          { "do": "spawnEntity", "kind": "coin", "at": { "vec3": [0, 0, 7] } },
+          { "do": "spawnEntity", "kind": "coin", "at": { "vec3": [0, 0, -7] } },
+          { "do": "add", "target": "room.spawned", "by": 1 }
+        ]
+      },
+      {
+        "when": { "on": "zoneEnter", "zone": "coin" },
+        "if": { "op": "==", "a": { "ref": "source", "var": "active" }, "b": true },
+        "then": [
+          { "do": "add", "target": "self.score", "by": { "ref": "source", "var": "value" } },
+          { "do": "set", "target": { "ref": "source", "var": "active" }, "to": false },
+          { "do": "startTimer", "timer": "respawn", "seconds": 5, "key": "source" }
+        ]
+      },
+      { "when": { "on": "timerElapsed", "timer": "respawn" }, "then": [{ "do": "set", "target": "self.active", "to": true }] }
+    ]
+  },
+  "supportsMobile": true,
+  "contentRating": "everyone",
+  "systems": { "humanoid-character": "^0.2" }
+}
+```
+
+`zoneEnter` binds `self` = the entering player and `source` = the coin carrying the zone. `startTimer … "key":
+"source"` arms that specific coin's instance; `timerElapsed` then binds `self` = that coin. The validator rejects
+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).
+
+```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;
+  }
+}
+```
+
+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).
+
+## 4. Build, validate, publish
+
+`npm install` → `helix install` → `npm run build` → `validate_world` on `dist/` (fix every problem; watch the
+per-tick budget + entity caps) → `whoami` → `publish_world`.

package/docs/multiplayer-templates/collections.md

@@ -0,0 +1,116 @@
+# Multiplayer template — `collections`
+
+**What it is.** Each player holds a **hand of cards**: walk onto a draw pad to add a card, onto the tally pad to
+score your hand, press keys to mark/discard, and brush past someone to peek at their hand size. **Capability:
+structured collections** — a **`list` of `record`s** with the full collection sublanguage: `append`,
+`forEachInList` (+ `setField`), `listCount`, `listIndexOf`, `removeWhere`, and a ref-addressed `listLength`. Use
+this for hands, inventories, decks, crafting, order books. Lifted from the verified `multiplayer-card-showdown`
+world.
+
+> A normal character world (presence) **plus** the collection logic — the client is a pure renderer of the synced
+> hand. Grammar: `read_doc({ name: "multiplayer-logic" })` §2 (var types), §5/§6 (collection ops), §8 (effects).
+
+## 1. DSL used
+
+- **Declared state** (§2) — `playerVars.hand` is a **`list`** whose element is a flat **`record`**
+  (`suit`/`rank`/`played`), `maxLen: 12`; plus scalar `playerVars` the rules compute (`handValue`, `redCount`,
+  `topIdx`, `peeked`).
+- **Zones** (§10) — `drawRed`/`drawBlack` (draw a card) + a `tally` box (score the hand).
+- **Actions** (§14) — `mark`, `discard`.
+- **Collection ops + effects** (§5/§6/§8) — `append` a record literal; `forEachInList … where … setField` (mutate
+  matching elements); `listCount`/`listIndexOf` (count/find by predicate); `removeWhere`; and `listLength` read
+  through a **ref** (`{ ref: "other", var: "hand" }`) for the peek.
+- **`playerContact`** (§4) — brushing another player binds `other`; read their hand length.
+
+## 2. The manifest — `public/helix.json`
+
+```json
+{
+  "helixVersion": "0.3",
+  "title": "Card Showdown",
+  "slug": "card-showdown",
+  "entry": "index.html",
+  "maxPlayers": 8,
+  "permissions": ["auth.profile", "multiplayer"],
+  "multiplayer": {
+    "authoritative": true,
+    "state": {
+      "playerVars": {
+        "hand": { "type": "list", "maxLen": 12, "of": { "type": "record", "fields": { "suit": { "type": "string" }, "rank": { "type": "number", "default": 0 }, "played": { "type": "boolean", "default": false } } } },
+        "handValue": { "type": "number", "default": 0 },
+        "redCount": { "type": "number", "default": 0 },
+        "topIdx": { "type": "number", "default": -1 },
+        "peeked": { "type": "number", "default": -1 }
+      }
+    },
+    "zones": [
+      { "id": "drawRed", "shape": "sphere", "center": [10, 0, 0], "radius": 2.2 },
+      { "id": "drawBlack", "shape": "sphere", "center": [-10, 0, 0], "radius": 2.2 },
+      { "id": "tally", "shape": "box", "center": [0, 0, -10], "size": [3.5, 4, 3.5] }
+    ],
+    "states": { "initial": "play", "phases": ["play"], "joinPolicy": { "play": { "joinable": true } } },
+    "actions": { "mark": {}, "discard": {} },
+    "rules": [
+      { "when": { "on": "zoneEnter", "zone": "drawRed" }, "then": [{ "do": "append", "target": "self.hand", "value": { "suit": "red", "rank": { "op": "+", "a": 1, "b": { "op": "*", "a": { "op": "random" }, "b": 12 } }, "played": false } }] },
+      { "when": { "on": "zoneEnter", "zone": "drawBlack" }, "then": [{ "do": "append", "target": "self.hand", "value": { "suit": "black", "rank": { "op": "+", "a": 1, "b": { "op": "*", "a": { "op": "random" }, "b": 12 } }, "played": false } }] },
+      {
+        "when": { "on": "zoneEnter", "zone": "tally" },
+        "then": [
+          { "do": "set", "target": "self.handValue", "to": 0 },
+          { "do": "forEachInList", "list": "self.hand", "as": "h", "then": [{ "do": "add", "target": "self.handValue", "by": { "ref": "h", "var": "rank" } }] },
+          { "do": "set", "target": "self.redCount", "to": { "op": "listCount", "list": "self.hand", "as": "h", "where": { "op": "==", "a": { "ref": "h", "var": "suit" }, "b": "red" } } },
+          { "do": "set", "target": "self.topIdx", "to": { "op": "listIndexOf", "list": "self.hand", "as": "h", "where": { "op": ">=", "a": { "ref": "h", "var": "rank" }, "b": 8 } } }
+        ]
+      },
+      { "when": { "on": "action", "name": "mark" }, "then": [{ "do": "forEachInList", "list": "self.hand", "as": "h", "where": { "op": "==", "a": { "ref": "h", "var": "suit" }, "b": "red" }, "then": [{ "do": "setField", "as": "h", "field": "played", "to": true }] }] },
+      { "when": { "on": "action", "name": "discard" }, "then": [{ "do": "removeWhere", "target": "self.hand", "as": "h", "where": { "op": "==", "a": { "ref": "h", "var": "played" }, "b": true } }] },
+      { "when": { "on": "playerContact", "radius": 2.5 }, "then": [{ "do": "set", "target": "self.peeked", "to": { "op": "listLength", "list": { "ref": "other", "var": "hand" } } }] }
+    ]
+  },
+  "supportsMobile": true,
+  "contentRating": "everyone",
+  "systems": { "humanoid-character": "^0.2" }
+}
+```
+
+`append`'s `value` is a record literal whose fields are expressions (here a random rank). `forEachInList … as:"h"`
+binds each element; inside, read fields with `{ ref: "h", var: "rank" }` and mutate with `setField … as:"h"`.
+`listCount`/`listIndexOf` take a `where` predicate over the same `as` binding. Stay within `maxLen` (12) and the
+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:
+
+```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'));
+
+// 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');
+});
+```
+
+**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.
+
+## 4. Build, validate, publish
+
+`npm install` → `helix install` → `npm run build` → `validate_world` on `dist/` (watch `listMaxLen`/`recordFields`
+caps + the per-tick budget) → `whoami` → `publish_world`.

package/docs/multiplayer-templates/hangout.md

@@ -0,0 +1,184 @@
+# 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*.
+
+> 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`.
+
+## 1. DSL used
+
+**None — `hangout` is pure presence.** The `multiplayer` block is just `{ "authoritative": true }`: no `state`,
+`rules`, `entities`, `zones`, `timers`, `states`, `events`, or `actions`. Players replicate automatically (the
+fixed character contract — position, facing, speed, move dir, grounded/crouched, aim, active abilities). When you
+want shared game state (scores, teams, objects, rules), read `read_doc({ name: "multiplayer-logic" })` and start
+from a logic-bearing template — `collect-a-thon` is the simplest next step.
+
+## 2. The manifest — `public/helix.json`
+
+```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" }
+}
+```
+
+`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.
+
+## 3. The client — `src/main.ts`
+
+Add `@hypersoniclabs/helix-sdk` to `package.json` for `Helix.multiplayer`; the replica primitives
+(`ReplicaScene`, `NetworkDriver`, `ReplicaBody`) come from the `humanoid-character` system you already pin.
+`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:
+
+```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 { 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 */ }
+}
+
+// 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).
+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.
+```
+
+**b. Join — guarded, so guests / standalone fall back to single-player:**
+
+```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;
+  }
+}
+```
+
+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):
+
+```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 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);                                // the driver feeds the blackboard from snapshots
+  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);                 // async build; the pool buffers snapshots until ready
+  });
+  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` → `helix install` (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.

package/docs/multiplayer-templates/obby.md

@@ -0,0 +1,84 @@
+# Multiplayer template — `obby`
+
+**What it is.** An obstacle course: run/jump across platforms, touch a checkpoint to save your spot, fall off and
+you **respawn at your last checkpoint**, reach the end to win — everyone racing in the same space. **Capability:
+zone checkpoints + the `respawn` effect (the server re-anchors a player) + a fall/kill zone + a finish broadcast.**
+Use this for parkour, races, platformers, time trials. Lifted from the verified `multiplayer-obby` world.
+
+> The smallest logic world: presence + a few zones + `respawn`. Grammar:
+> `read_doc({ name: "multiplayer-logic" })` §10 (zones), §8 (respawn/teleport).
+
+## 1. DSL used
+
+- **Declared state** (§2) — `playerVars.checkpoint` (a **`vec3`**) holds each player's saved respawn point.
+- **Zones** (§10) — **checkpoint** boxes (one per stage), a wide low **`kill`** box under the course (the
+  fall-catcher), and a **`finish`** box.
+- **`respawn`** (§8) — a server-authoritative move that **re-anchors the player's move gate** to a `vec3` (use it,
+  not `teleport`, for death/reset). The fall zone respawns to the saved `checkpoint`.
+- **Broadcast** (§13) — `win` when someone reaches `finish`.
+- **Rules** (§3) — checkpoint `zoneEnter` saves `self.position` into `self.checkpoint`; `kill` `zoneEnter`
+  respawns to `self.checkpoint`; `finish` `zoneEnter` broadcasts `win`.
+
+## 2. The manifest — `public/helix.json`
+
+```json
+{
+  "helixVersion": "0.3",
+  "title": "Multiplayer Obby",
+  "slug": "obby",
+  "entry": "index.html",
+  "maxPlayers": 8,
+  "permissions": ["auth.profile", "multiplayer"],
+  "multiplayer": {
+    "authoritative": true,
+    "state": { "playerVars": { "checkpoint": { "type": "vec3", "default": [0, 1, 0] } } },
+    "zones": [
+      { "id": "cp1", "shape": "box", "center": [10, 0, 0], "size": [4, 4, 4] },
+      { "id": "cp2", "shape": "box", "center": [45, 0, 0], "size": [4, 4, 4] },
+      { "id": "kill", "shape": "box", "center": [0, -10, 0], "size": [200, 2, 200] },
+      { "id": "finish", "shape": "box", "center": [90, 0, 0], "size": [4, 8, 4] }
+    ],
+    "events": { "win": { "payload": { "who": { "type": "ref", "of": "player" } } } },
+    "rules": [
+      { "when": { "on": "zoneEnter", "zone": "cp1" }, "then": [{ "do": "set", "target": "self.checkpoint", "to": { "var": "self.position" } }] },
+      { "when": { "on": "zoneEnter", "zone": "cp2" }, "then": [{ "do": "set", "target": "self.checkpoint", "to": { "var": "self.position" } }] },
+      { "when": { "on": "zoneEnter", "zone": "kill" }, "then": [{ "do": "respawn", "player": "self", "to": { "var": "self.checkpoint" } }] },
+      { "when": { "on": "zoneEnter", "zone": "finish" }, "then": [{ "do": "broadcast", "event": "win", "to": "all", "payload": { "who": "self" } }] }
+    ]
+  },
+  "supportsMobile": true,
+  "contentRating": "everyone",
+  "systems": { "humanoid-character": "^0.2" }
+}
+```
+
+Add a checkpoint zone per stage — each one's rule is the same `set self.checkpoint = self.position`. The fall zone
+is a single huge thin box well below the course; `respawn` re-anchors cleanly (the SDK's reconciler accepts the
+server correction). The platforms themselves are your **client-side geometry** (static colliders on the character
+body) — only the *zones* are declared.
+
+## 3. The client — `src/main.ts` (delta from `hangout`)
+
+Almost none — presence, a win banner, and **one line to wire respawn**. The respawn is server-authoritative, but to
+land it on your *local* (client-predicted) body you construct a **`LocalReconciler`** once after joining — it
+self-hooks the server's position ack and snaps your body, with no per-frame work. Build the course geometry as
+static colliders on your character body (as in the character recipe), aligned with the declared zone centers.
+
+```ts
+import { LocalReconciler } from '@helix/humanoid-character';
+
+// once, after joinRoom() succeeds — `body` is your local character's RapierBody:
+new LocalReconciler({ room, body });     // snaps the local player to the server's anchor on a respawn/teleport ack
+
+room.onMessage('win', (m) => showBanner(`🏁 ${nameOf(String(m.who))} finished!`));
+// (otherwise identical to hangout: local player + ReplicaScene + sendState)
+```
+
+**Footguns:** use `respawn` (not a client-side teleport) for death; you **must** wire `LocalReconciler` once —
+without it the server re-anchors the seat but your predicted body keeps falling; keep the platform colliders
+aligned with the declared zone centers so checkpoints fire where players land; `checkpoint` is a `vec3` default
+`[0,1,0]` (the start), so a fresh player respawns at spawn.
+
+## 4. Build, validate, publish
+
+`npm install` → `helix install` → `npm run build` → `validate_world` on `dist/` → `whoami` → `publish_world`.