@hypersoniclabs/helix-mcp 0.2.5 → 0.2.12

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

@@ -0,0 +1,310 @@
+# Multiplayer template — `npc-wave`
+
+**What it is.** `wave-survival` with **people** instead of orbs: every few seconds a wave of enemies spawns and
+hunts the players, touch one and you take damage, shoot them down — real gun damage, headshots included — to
+clear the wave, and each enemy is a full humanoid character that walks, turns and runs like a player. A
+**stand-body shopkeeper** waits in the safe zone with a `Talk` prompt. **Capability: SHARED (game-owned)
+entities with DISTRIBUTED, host-migrated local-authority AI, rendered as humanoids and SHOOTABLE — their
+damage is gun-declared and server-resolved.** The authority story is `wave-survival`'s, unchanged: the enemies
+belong to the *game*, the server hands **each enemy to the least-loaded client at spawn** so the swarm's
+simulation **spreads across the whole room**, and any enemy whose host drops is **re-elected** to another client.
+
+> **The lesson here is that the humanoid is only the RENDERING** — the brain stays exactly where
+> `wave-survival` put it. Read `read_template({ name: "wave-survival" })` first: this page is a delta from it,
+> and the manifest below is its manifest. The NPC surface (`NpcScene`, `InteractionSpots`, behaviours, nav) is
+> `read_doc({ name: "npc-world" })`; grammar: `read_doc({ name: "multiplayer-logic" })` §9. The gun half of the
+> client — installing `gun-control`, the FX/hit systems, the crosshair — is `read_doc({ name: "shooter-worlds" })`,
+> and the claim lane below is `read_template({ name: "shooter-range" })`'s, aimed at an entity instead of a player.
+
+## 1. DSL used
+
+`wave-survival`'s, unchanged by the humanoid body — plus the shooter's claim lane, which is the whole delta:
+
+- **Entities** (§9) — one `enemy` kind, **`shared: true`** + `authority:'owner'` + `ownerLifecycle:'hostMigrate'`:
+  each enemy is hosted by the **least-loaded connected client at spawn**, so a swarm **distributes across the
+  clients** — and any enemy **re-elects** to another client if its host leaves. `idleTimeout: 4` despawns an
+  enemy left hostless for 4 s. `maxSpeed` (required for owner kinds) bounds the upload; an **attached zone**
+  damages players on contact; an **`hp` var** is the enemy's health — the room writes it and nothing else does.
+- **Timers** (§11) — `wave`, **self-rearming** (a `timerElapsed` rule restarts it) → a steady spawn cadence, plus
+  a per-player `cooldown`: the server-side fire-rate ceiling on the shoot claim.
+- **Actions** (§14) — `shoot` is the hit CLAIM: `target` (an enemy ref) + `bodyPart` (`head`|`body`). It carries
+  no damage number — the client names WHAT it hit, never how hard.
+- **`weaponItems` + `weaponDamage`** — the room resolves the shot off the gun the shooter is actually holding
+  (`shooter-range` teaches the lane). `target` may be an **entity**, which applies the definition's distance
+  falloff shooter→enemy, and `part: "head"` applies its `headMultiplier` — the world names the part, never the factor.
+- **Declared state** (§2) — `roomVars.wave` + `roomVars.cleared` (the score) + `playerVars.health`.
+- **Rules** (§3) — arm the wave timer on `stateEnter`; on `timerElapsed` re-arm **and** (if `aggregate count < 6`)
+  `spawnEntity`; enemy-zone `zoneEnter` (binds `self` = the player) subtracts health; `shoot` gates on `distance`
+  + `cooldown` then subtracts `weaponDamage` from the target's `hp`; an entity-scope `varReached hp <= 0`
+  destroys the enemy and scores; `varReached self.health <= 0` respawns + heals.
+- **The shopkeeper declares NOTHING.** It is a client-local `NpcScene` NPC on the `stand` tier: it never moves,
+  so every client's copy agrees for free and no state has to cross the wire. That is the dividing line this
+  template teaches — **a moving NPC belongs to the room, a standing one does not.**
+
+## 2. The manifest — `public/helix.json` *(the shoot lane needs the `weaponDamage` entity-target widening)*
+
+```json
+{
+  "helixVersion": "0.3",
+  "title": "NPC Wave",
+  "slug": "npc-wave",
+  "entry": "index.html",
+  "maxPlayers": 8,
+  "permissions": ["auth.profile", "multiplayer", "voice.proximity"],
+  "multiplayer": {
+    "authoritative": true,
+    "weaponItems": ["11111111-2222-4333-8444-555555555555@1"],
+    "state": {
+      "roomVars": { "wave": { "type": "number", "default": 0 }, "cleared": { "type": "number", "default": 0 } },
+      "playerVars": { "health": { "type": "number", "default": 100 } }
+    },
+    "entities": {
+      "enemy": {
+        "authority": "owner",
+        "shared": true,
+        "ownerLifecycle": "hostMigrate",
+        "idleTimeout": 4,
+        "maxSpeed": 6,
+        "vars": { "hp": { "type": "number", "default": 60 } },
+        "zone": { "shape": "sphere", "radius": 1.2 }
+      }
+    },
+    "timers": { "wave": {}, "cooldown": { "keyed": "player" } },
+    "actions": {
+      "shoot": { "args": { "target": { "type": "ref", "of": "entity:enemy" }, "bodyPart": { "type": "string", "enum": ["head", "body"] } } }
+    },
+    "states": { "initial": "playing", "phases": ["playing"] },
+    "rules": [
+      { "when": { "on": "stateEnter", "phase": "playing" }, "then": [{ "do": "startTimer", "timer": "wave", "seconds": 3 }] },
+      { "when": { "on": "timerElapsed", "timer": "wave" }, "then": [{ "do": "startTimer", "timer": "wave", "seconds": 3 }] },
+      {
+        "when": { "on": "timerElapsed", "timer": "wave" },
+        "if": { "op": "<", "a": { "op": "aggregate", "scope": "entities:enemy", "agg": "count" }, "b": 6 },
+        "then": [
+          { "do": "spawnEntity", "kind": "enemy", "at": { "vec3": [0, 0, 14] } },
+          { "do": "add", "target": "room.wave", "by": 1 }
+        ]
+      },
+      { "when": { "on": "zoneEnter", "zone": "enemy" }, "then": [{ "do": "add", "target": "self.health", "by": -10 }] },
+      {
+        "when": { "on": "action", "name": "shoot" },
+        "if": { "op": "and", "of": [
+          { "op": "<", "a": { "op": "distance", "a": { "var": "self.position" }, "b": { "ref": { "var": "action.args.target" }, "var": "position" } }, "b": 60 },
+          { "op": "==", "a": { "op": "timerRemaining", "timer": "cooldown", "key": "self" }, "b": 0 }
+        ] },
+        "then": [
+          { "do": "add", "target": { "ref": { "var": "action.args.target" }, "var": "hp" },
+            "by": { "op": "*", "a": -1, "b": { "op": "weaponDamage", "of": "self", "target": { "var": "action.args.target" }, "part": { "var": "action.args.bodyPart" }, "default": 20 } } },
+          { "do": "startTimer", "timer": "cooldown", "seconds": 0.08, "key": "self" }
+        ]
+      },
+      {
+        "when": { "on": "varReached", "scope": "entity", "kind": "enemy", "var": "hp", "cmp": "<=", "value": 0 },
+        "then": [
+          { "do": "add", "target": "room.cleared", "by": 1 },
+          { "do": "destroyEntity", "entity": "self" }
+        ]
+      },
+      {
+        "when": { "on": "varReached", "scope": "self", "var": "health", "cmp": "<=", "value": 0 },
+        "then": [
+          { "do": "respawn", "player": "self", "to": { "vec3": [0, 1, 0] } },
+          { "do": "set", "target": "self.health", "to": 100 }
+        ]
+      }
+    ]
+  },
+  "supportsMobile": true,
+  "contentRating": "everyone",
+  "systems": { "humanoid-character": "^0.3" }
+}
+```
+
+The two `timerElapsed` rules fire in declared order: the first re-arms `wave`, the second spawns. The
+`aggregate count < 6` cap is doing double duty here: **every live enemy is a full skinned character**, so it is
+a frame budget as much as a difficulty knob (the same reason `NpcScene` caps itself at 16).
+
+`shoot` is the cheat-resistant input, and the two gates are the anti-cheat floor — keep both: the **server**
+checks the 60 m range, and the per-player `cooldown` is the fire-rate ceiling (claims inside 0.08 s are
+ignored). Nothing about the damage is the client's: it names the target and the part, the room reads the gun
+off the shooter's replicated grip attachment, applies the definition's falloff at shooter→enemy range, and
+multiplies by `headMultiplier` when `part` is `"head"`. `default: 20` covers a player holding no declared gun.
+**Death is a consequence, never a claim** — `hp` crossing 0 is what destroys the enemy, on an entity-scope
+`varReached` that binds `self` to the enemy that crossed (one latch per live instance). Replace the
+`weaponItems` example id with a supported, existing package-backed weapon definition pin (`assetId@version`).
+
+**Version gate.** The shoot lane needs the platform's **`weaponDamage` entity-target widening** on BOTH halves:
+the manifest validator (an older one rejects an entity ref in `target`, so the world fails publish) and the
+room, which resolves the entity's position for falloff — an older room still applies the damage but silently
+skips falloff, so every hit reads point-blank. **The room deploys before worlds use it** (the platform's
+standing release-order rule); the rest of the template runs on any room. The humanoid rendering in §3 needs
+`humanoid-character ≥ 0.3.13`.
+
+### Optional variant — a RANGED enemy (an interval rule, not a projectile)
+
+An enemy that shoots instead of touching is **one timer and three rules**, and it stays entirely inside the
+DSL: a per-player `volley` timer re-arms itself every **N** seconds, and when it elapses the player takes
+**D** hp if the nearest enemy is inside **R** metres. Merge into §2's block:
+
+```json
+{
+  "timers": { "volley": { "keyed": "player" } },
+  "rules": [
+    { "when": { "on": "playerJoin" }, "then": [{ "do": "startTimer", "timer": "volley", "seconds": 2, "key": "self" }] },
+    { "when": { "on": "timerElapsed", "timer": "volley" }, "then": [{ "do": "startTimer", "timer": "volley", "seconds": 2, "key": "self" }] },
+    {
+      "when": { "on": "timerElapsed", "timer": "volley" },
+      "if": { "op": "and", "of": [
+        { "op": ">", "a": { "op": "aggregate", "scope": "entities:enemy", "agg": "count" }, "b": 0 },
+        { "op": "<", "a": { "op": "distance", "a": { "var": "self.position" }, "b": { "ref": { "op": "nearestEntity", "from": { "var": "self.position" }, "kind": "enemy" }, "var": "position" } }, "b": 18 }
+      ] },
+      "then": [{ "do": "add", "target": "self.health", "by": -8 }]
+    }
+  ]
+}
+```
+
+**The three numbers are the whole design surface:** `seconds: 2` is the cadence, `b: 18` is the range, `by: -8`
+is the damage. The two `timerElapsed` rules fire in declared order (§2's `wave` pair, again): the first re-arms
+unconditionally, the second is the one the `if` gates — so a player out of range simply takes nothing this beat.
+Keep the **`count > 0` guard**: reading through a dangling ref yields the typed zero, so with no enemies alive
+`nearestEntity` would measure everyone's distance to the origin and shoot whoever stands near it.
+
+**The trust model, stated plainly: this is distance-only and fully server-side by deliberate design** — no
+client claim, no `bodyPart`, and **no line of sight** (LoS attestation is future machinery, so cover does not
+stop these shots; keep `R` tight enough that the range itself is the cover). The `shoot` lane above is the
+opposite trade and both can coexist: players claim what they hit, the room shoots back on its own clock.
+Nothing on the client changes: whether the enemy visibly holds a gun is a LOOK decision (the arming recipe is
+`read_doc({ name: "npc-world" })` §4a), and the damage still comes from this rule, never from the animation.
+
+## 3. The client — `src/main.ts` (delta from `wave-survival`) *(humanoid-character ≥ 0.3.13)*
+
+**The only change to the entity wiring is `build`.** `humanoidEntities(...)` returns an `EntityScene` build fn
+whose `object3d` is a full headless `Character`: it clones the shared body, registers locomotion, and derives
+speed / heading / grounded state from the motion the transport already wrote — no driver, no behaviour, no
+`seek` on the client. Authority, interpolation, hosting and host migration stay exactly where they were. Wrap
+it to keep an `id → handle` map: the gun chain needs each enemy's BODY, which only the handle can reach.
+
+```ts
+import { humanoidEntities, InteractionSpots, NpcScene, type AIBehaviour, type HumanoidEntityHandle } from '@helix/humanoid-character';
+
+const ENEMY_MAX_SPEED = 6;            // MUST mirror the DSL maxSpeed (reconcile clamp)
+const room = mp.room!;
+
+const buildEnemy = humanoidEntities({
+  scene,
+  assets: mp.assets,                                   // the facade's already-loaded base model + clips
+  gestures: mp.gestures,                               // optional: lets a world gesture play on an enemy
+  name: (kind) => (kind === 'enemy' ? 'Zombie' : null),   // null (or no fn) = no nameplate
+});
+const enemies = new Map<string, HumanoidEntityHandle>();  // the shot candidates, and the claim router
+
+const entities = mp.entities({
+  maxSpeed: { enemy: ENEMY_MAX_SPEED },
+  motion: {
+    // Unchanged from wave-survival — the AI is still the host's motion fn, and it still runs only for
+    // enemies YOU host. seekNearest caps the per-frame step internally and stops 0.9 m short, which parks
+    // the enemy inside the 1.2 m damage zone rather than inside the player.
+    enemy: (_e, _dt, ctx) => ctx.seekNearest(ENEMY_MAX_SPEED * 0.83, 0.9),
+  },
+  // THE DELTA: a humanoid per entity instead of an orb mesh, registered so the hit chain can find it.
+  build: (kind, id) => {
+    const handle = buildEnemy(kind, id);
+    const free = handle.dispose?.bind(handle);   // capture BEFORE shadowing it: a wrapper that called
+    enemies.set(id, handle);                     // handle.dispose() would then call ITSELF, forever
+    void handle.ready.then(() => handle.character?.playAnimation('zombie-walk'));  // optional: a gait, once the body exists
+    return Object.assign(handle, { dispose: () => { enemies.delete(id); free?.(); } });
+  },
+});
+// mp.update(dt) drives the sim/interpolation — nothing to add in your frame loop.
+```
+
+Two placement facts that change when the render is a humanoid: the handle's `object3d` origin is the entity's
+networked point, which for a humanoid is its **feet** — so `spawnEntity … "at": [0, 0, 14]` puts it correctly on
+a floor at `y = 0` (an orb at that height would be half-buried), and the attached `zone` is centred at the
+floor, so size its radius to reach the player's capsule rather than picturing a chest-height sphere.
+
+**Shooting them — the enemies are hit candidates like any replica.** The gun itself (install, profile, FX,
+crosshair, the frame order) is `shooter-worlds` §1–3 unchanged; the npc-wave delta is what you CHAIN into the
+`players` generator and where the claim goes. `entities.entries()` yields `{ id, state, object3d }` — the live
+set and the synced `hp` — and the map above turns an id into the body whose head socket arms the headshot:
+
+```ts
+const scratch = new THREE.Vector3();          // ONE shared scratch — each head read is consumed before the next
+
+const gunHit = new GunHitSystem({
+  camera, body, muzzle: (out) => gunFx.muzzleWorld(out),
+  walkSpeedMps: mp.local.services.config.get('locomotion.walkSpeed'),
+  maxSpeedMps: mp.local.services.config.get('locomotion.runSpeed'),
+  players: function* () {
+    for (const [id, r] of replicaFx) yield { id, position: r.character.model.position };   // your existing PLAYER replicas
+    for (const e of entities.entries()) {                                                  // …then the enemies
+      const handle = enemies.get(e.id);
+      if (handle?.character == null || Number(e.state.vars.hp ?? 0) <= 0) continue;   // still building, or already dead
+      yield {
+        id: e.id,
+        position: e.object3d.position,        // the networked point = the humanoid's FEET, which is what the capsule wants
+        // getWorldPosition, not .position: the character tick leaves matrixWorld stale, so a raw read aims
+        // the headshot sphere at last frame's head. No head thunk at all = every hit is 'body'.
+        head: () => handle.character?.services.sockets?.anchorOf('head')?.getWorldPosition(scratch) ?? null,
+      };
+    }
+  },
+  onPlayerHit: ({ id, point, claim, part }) => {
+    tracers.spawn(tracerFrom(point), point);
+    if (!claim) return;                                                     // exactly ONE claim per trigger pull
+    if (enemies.has(id)) room.sendAction('shoot', { target: id, bodyPart: part });
+    // else it is a player id — this template has no friendly fire, so nothing is claimed. A PvP world sends
+    // its own claimHit here instead; entity ids and session ids are disjoint, so membership IS the router.
+  },
+  onWorldHit: ({ point }) => tracers.spawn(tracerFrom(point), point),
+  onMiss: ({ end }) => tracers.spawn(tracerFrom(end), end),
+});
+gunHit.attachTo(mp.local);
+```
+
+The client never decides an enemy died: it claims the hit, the room subtracts `hp`, and the enemy simply
+despawns out of `entities.entries()` when the room's `varReached` destroys it — which is also why the
+generator skips `hp <= 0` (a corpse is unshootable for the frame or two before the despawn arrives).
+
+**The shopkeeper is pure client-side decoration** — no manifest, no rules, no wire traffic:
+
+```ts
+const npcs = new NpcScene({ scene, assets: mp.assets });        // no staticsFrom needed: 'stand' runs no physics
+const COUNTER = { x: 0, y: 1, z: -2 };
+const watch: AIBehaviour = (npc) => {
+  const self = npc.position;
+  const near = Math.hypot(body.position.x - self.x, body.position.z - self.z) <= 6;
+  npc.face(near ? body.position : COUNTER);
+};
+const shop = await npcs.add({ id: 'shopkeeper', at: { x: 0, y: 0, z: -3 }, body: 'stand', behaviour: watch, name: 'Quartermaster' });
+
+const spots = new InteractionSpots({ body, input, scene, suppressed: () => mp.sitPrompt !== null });
+spots.register({
+  id: 'shopkeeper-talk',
+  label: 'Talk',
+  at: () => { const p = shop.driver.position; return { x: p.x, y: p.y + 2.1, z: p.z }; },   // live anchor, head height
+  onInteract: () => showBanner('Quartermaster: keep them off the spawn pad.'),
+});
+
+renderer.setAnimationLoop(() => {
+  const dt = Math.min(clock.getDelta(), 0.1);
+  mp.update(dt);      // local character + replicas + entities — shots latch here…
+  gunFx.update(dt);   // …and resolve after it: the gun frame order is a contract (shooter-worlds §3)
+  gunHit.update(dt);  // the ray fires against THIS frame's enemy transforms
+  npcs.update(dt);    // then the client-local NPCs
+  spots.update(dt);   // then the spots — the interact edge advanced inside mp.update
+  renderer.render(scene, camera);
+});
+```
+
+Read your `health` off `room.state.players[sessionId].vars.health`, the score off `room.vars.num('cleared')`.
+**Footguns:** mirror `maxSpeed`; keep each motion step `≤ maxSpeed × 0.83 × dt`; you won't host every enemy
+(shared) — never assume you control one, check `e.controller`; **never publish `hp` from the handle's
+`controls()`** — that channel is uploaded by the enemy's HOST client, and `hp` is the room's alone; keep the
+concurrent-enemy cap low, because each one is a full character; and never give the shopkeeper a `seek` — a
+`stand` NPC ignores movement intent by design (`read_doc({ name: "npc-world" })` §1).
+
+## 4. Build, validate, publish
+
+`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/obby.md

@@ -28,7 +28,7 @@ Use this for parkour, races, platformers, time trials. Lifted from the verified
   "slug": "obby",
   "entry": "index.html",
   "maxPlayers": 8,
-  "permissions": ["auth.profile", "multiplayer"],
+  "permissions": ["auth.profile", "multiplayer", "voice.proximity"],
   "multiplayer": {
     "authoritative": true,
     "state": { "playerVars": { "checkpoint": { "type": "vec3", "default": [0, 1, 0] } } },
@@ -48,7 +48,7 @@ Use this for parkour, races, platformers, time trials. Lifted from the verified
   },
   "supportsMobile": true,
   "contentRating": "everyone",
-  "systems": { "humanoid-character": "^0.2" }
+  "systems": { "humanoid-character": "^0.3" }
 }
 ```
 
@@ -59,26 +59,23 @@ 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.
+Almost none — presence + a win banner. The respawn is server-authoritative, and landing it on your *local*
+(client-predicted) body is the **`LocalReconciler`**, which the facade wires **by default** — nothing to add.
+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)
+mp.room?.onMessage('win', (m) => showBanner(`🏁 ${nameOf(String(m.who))} finished!`));
+// read your saved checkpoint for the HUD off the typed accessors:
+const cp = mp.room?.me.vec3('checkpoint');
+// (otherwise identical to hangout: the one facade call)
 ```
 
-**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
+**Footguns:** use `respawn` (not a client-side teleport) for death — the facade's reconciler lands the server's
+move on your body (never pass `reconciler: false` in a world with respawns); 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` → **`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/persistent-progress.md

@@ -0,0 +1,218 @@
+# Multiplayer template — `persistent-progress`
+
+**What it is.** A workshop world that **remembers**. Your level, gems and title come back when you rejoin;
+the community's donation total climbs across every instance and every day; the leaderboards keep the best
+level and the fastest run; a guestbook holds the last ten notes anyone left; and a world-record time survives
+the room shutting down. **Capability: durable storage** — every persistence primitive the platform has, and
+(the part that actually matters) **which one to reach for**. Lifted from the verified
+`multiplayer-persistent-progress` world.
+
+> A normal character world (presence) **plus** storage. Grammar:
+> `read_doc({ name: "multiplayer-logic" })` §18 (saves, room state, counters, leaderboards) and §2 (var types).
+
+## 1. Pick the shape FIRST — this is the whole template
+
+Storage bugs here are almost never syntax; they are picking the wrong shape and discovering it in production.
+Keys are authority boundaries, JSON is everything else: **one writer per key.**
+
+| What you are storing | Shape | Reach for |
+|---|---|---|
+| Player progression you must not let players forge (currency, XP, unlocks) | one document per player, server-written | `persistent: true` playerVars + `save` |
+| Player preferences, cosmetic choices, a single-player save | one JSON blob per player, client-written | `Helix.dataStore.set` on the player's own key |
+| This round's score, who is `it`, the current phase | room memory | plain roomVars — they SHOULD die with the room |
+| Guestbooks, galleries, player-built things everyone sees | one bounded document, room-written | persistent roomVar, `list of record`, `merge: "append"` |
+| A community total, boss HP, a vote count | atomic accumulator | `counters` + `increment` |
+| Rankings | one bounded document per board, keep-best | `leaderboards` + `submitScore` |
+| A world record, a high-water mark | a single monotone number | persistent roomVar, `merge: "max"` / `"min"` |
+
+**Two shapes that look interchangeable and are not.** A `counter` is write-only-ish shared arithmetic read
+back through the data store; a **`sum` roomVar is replicated state** you can render every frame without a
+fetch. Use a counter for a number nobody looks at continuously (lifetime donations); use a `sum` roomVar when
+the HUD shows it live. And **anything a player PAID for belongs on `save` or `submitScore`, never on
+`saveRoom`** — see the durability window in §5.
+
+## 2. DSL used
+
+- **Persistent playerVars + `save`** (§18) — scalars marked `persistent: true`, flushed on the beat that
+  changed them. Hydrated before join rules run, so a `playerJoin` rule reads restored values.
+- **Persistent roomVars + `saveRoom`** (§18) — world state that outlives the room. Every persistent roomVar
+  declares a **`merge`** policy, and may declare a **`key`** routing it to its own document.
+- **`counters` + `increment`** (§18) — commutative totals batched by the room.
+- **`leaderboards` + `submitScore`** (§18) — keep-best per player, decided by the backend.
+- **`awardAchievement`** (§19) — fire-and-forget, idempotent.
+- **Zones + actions + `varReached`** — the beats that trigger the writes.
+
+## 3. The manifest — `public/helix.json` (the storage block)
+
+```json
+{
+  "helixVersion": "0.3",
+  "title": "Persistent Progress",
+  "slug": "persistent-progress",
+  "entry": "index.html",
+  "maxPlayers": 8,
+  "permissions": ["auth.profile", "multiplayer"],
+  "contentRating": "everyone",
+  "multiplayer": {
+    "authoritative": true,
+    "state": {
+      "playerVars": {
+        "level": { "type": "number", "default": 1, "min": 1, "max": 99, "integer": true, "persistent": true },
+        "gems":  { "type": "number", "default": 0, "min": 0, "max": 9999, "integer": true, "persistent": true },
+        "title": { "type": "string", "default": "bronze", "enum": ["bronze", "silver", "gold"], "persistent": true },
+        "runStart": { "type": "number", "default": 0 },
+        "lastRun":  { "type": "number", "default": 0 }
+      },
+      "roomVars": {
+        "notes": {
+          "type": "list",
+          "of": { "type": "record", "fields": { "author": { "type": "string", "maxLen": 24 }, "text": { "type": "string", "maxLen": 80 } } },
+          "maxLen": 10,
+          "persistent": true, "merge": "append", "key": "guestbook"
+        },
+        "bestRun": { "type": "number", "default": 999999, "min": 0, "max": 999999, "persistent": true, "merge": "min" },
+        "tally":   { "type": "counterMap", "keys": ["visits", "notes"], "persistent": true, "merge": "sum" },
+        "motd":    { "type": "string", "default": "welcome to the workshop", "maxLen": 80, "persistent": true, "merge": "lastWrite" }
+      }
+    },
+    "counters": { "donations": {} },
+    "leaderboards": { "main": { "size": 10 }, "bestTime": { "order": "asc", "size": 10 } },
+    "zones": [
+      { "id": "runStart",  "shape": "sphere", "center": [-14, 0, -10], "radius": 2 },
+      { "id": "runFinish", "shape": "sphere", "center": [14, 0, -10], "radius": 2 }
+    ],
+    "actions": {
+      "levelUp": {},
+      "donate": {},
+      "postNote": { "args": { "text": { "type": "string", "maxLen": 80 }, "author": { "type": "string", "maxLen": 24 } } }
+    },
+    "rules": [
+      { "when": { "on": "playerJoin" },
+        "then": [ { "do": "addCount", "target": "room.tally", "key": "visits", "by": 1 }, { "do": "saveRoom" } ] },
+
+      { "when": { "on": "action", "name": "levelUp" },
+        "if": { "op": ">=", "a": { "var": "self.gems" }, "b": 5 },
+        "then": [
+          { "do": "add", "target": "self.gems", "by": -5 },
+          { "do": "add", "target": "self.level", "by": 1 },
+          { "do": "save", "player": "self" },
+          { "do": "submitScore", "board": "main", "player": "self", "score": { "var": "self.level" } }
+        ] },
+
+      { "when": { "on": "action", "name": "donate" },
+        "if": { "op": ">=", "a": { "var": "self.gems" }, "b": 1 },
+        "then": [
+          { "do": "add", "target": "self.gems", "by": -1 },
+          { "do": "increment", "counter": "donations", "by": 1 }
+        ] },
+
+      { "when": { "on": "action", "name": "postNote" },
+        "if": { "op": ">=", "a": { "op": "listLength", "list": "room.notes" }, "b": 10 },
+        "then": [ { "do": "removeAt", "target": "room.notes", "index": 0 } ] },
+      { "when": { "on": "action", "name": "postNote" },
+        "then": [
+          { "do": "append", "target": "room.notes", "value": { "author": { "var": "action.args.author" }, "text": { "var": "action.args.text" } } },
+          { "do": "addCount", "target": "room.tally", "key": "notes", "by": 1 },
+          { "do": "saveRoom", "key": "guestbook" },
+          { "do": "saveRoom" }
+        ] },
+
+      { "when": { "on": "varReached", "scope": "self", "var": "level", "cmp": ">=", "value": 5 },
+        "then": [
+          { "do": "set", "target": "self.title", "to": "silver" },
+          { "do": "save", "player": "self" },
+          { "do": "awardAchievement", "key": "level-5-champion", "player": "self" }
+        ] },
+
+      { "when": { "on": "zoneEnter", "zone": "runStart" },
+        "then": [ { "do": "set", "target": "self.runStart", "to": { "op": "now" } } ] },
+      { "when": { "on": "zoneEnter", "zone": "runFinish" },
+        "if": { "op": ">", "a": { "var": "self.runStart" }, "b": 0 },
+        "then": [
+          { "do": "set", "target": "self.lastRun", "to": { "op": "-", "a": { "op": "now" }, "b": { "var": "self.runStart" } } },
+          { "do": "submitScore", "board": "bestTime", "player": "self", "score": { "var": "self.lastRun" } },
+          { "do": "set", "target": "self.runStart", "to": 0 }
+        ] },
+      { "when": { "on": "zoneEnter", "zone": "runFinish" },
+        "if": { "op": "and", "of": [
+          { "op": ">", "a": { "var": "self.lastRun" }, "b": 0 },
+          { "op": "<", "a": { "var": "self.lastRun" }, "b": { "var": "room.bestRun" } } ] },
+        "then": [ { "do": "set", "target": "room.bestRun", "to": { "var": "self.lastRun" } }, { "do": "saveRoom" } ] }
+    ]
+  },
+  "systems": { "humanoid-character": "^0.3" }
+}
+```
+
+**The ring buffer is two rules, not one.** `append` is a no-op at `maxLen`, so a bounded board drops its
+oldest first (`removeAt` index 0) and then appends. Rules fire in declaration order, so the guard rule must
+come first.
+
+**`merge` is REQUIRED on every persistent roomVar.** Many instances of your world run at once and all write
+the same document, so the policy decides who wins: `lastWrite` (scalars) is **racy by declaration**;
+`max`/`min` (number), `append` (list) and `sum` (counterMap) are conflict-free. There is no default — you
+must state which you are taking.
+
+**`key` splits documents.** Without one a var lands in the shared document; with one it gets its own, with its
+own version guard and byte budget — so posting a note stops rewriting the rest of the world's state. Up to 6
+destinations. Bare `saveRoom` persists every destination whose snapshot changed; `saveRoom` with a `key`
+names one.
+
+## 4. The client — `src/main.ts` (delta from `hangout`)
+
+Room vars are ordinary synced state, so a persisted board renders with **no extra read** — `persistent` only
+changes whether it OUTLIVES the room:
+
+```ts
+const room = mp.room!;
+type Note = { author: string; text: string };
+
+// Persistent ROOM state — replicated like any other roomVar, no fetch.
+const notes = room.vars.list<Note>('notes');
+const record = room.vars.num('bestRun');
+boardEl.innerHTML = notes.map((n) => `<li><b>${n.author}</b> — ${n.text}</li>`).join('');
+recordEl.textContent = record >= 999999 ? '—' : `${record.toFixed(1)}s`;
+
+// Post a note (the room owns the write; the client only sends intent)
+room.sendAction('postNote', { text, author: myDisplayName });
+
+// The player's OWN blob — client-written KV, one JSON document per player
+await Helix.dataStore.set({ favouriteColour: 'teal', tutorialDone: true });
+const mine = await Helix.dataStore.get();
+
+// Rankings + the community total (both read through the data store, not synced state)
+const top = await Helix.leaderboard.top('main', { limit: 10 });
+const donated = await Helix.dataStore.get('world:counter:donations');
+```
+
+## 5. Footguns — every one of these fails SILENTLY
+
+- **A `min` var must default to something WORSE than any real value** (999999 for a time, not 0), or the
+  default wins every merge forever and the record can never be set. Mirrored for `max`.
+- **A room reads its OWN view.** A `sum` or `append` var shows what this room hydrated plus its own changes;
+  other instances land in the stored document, not in this room's replicated state. The true cross-instance
+  value is `Helix.dataStore.get('mp:world')`. Same deal counters already make — it is why the policies must be
+  commutative: rooms never have to agree live.
+- **Durability window.** Room state lives in memory until the flush (about 5 s, 60 s ceiling), so a hard crash
+  loses the tail. Fine for boards and tallies; **wrong for anything a player paid for** — that belongs on
+  `save` or `submitScore`, which are per-event.
+- **`save` is event-driven, never a `tick` heartbeat.** Fire it on the beat that changed something worth
+  keeping. Every write spends a slice of the world's shared budget.
+- **Renaming a persistent var resets it.** Stored documents are re-validated against the CURRENT build: wrong
+  types are discarded, numbers clamp, an enum miss falls back to the default, and vars you deleted are
+  dropped. Treat persistent names as a schema.
+- **Publish fails on a `save` with no persistent playerVar, or a `saveRoom` with no persistent roomVar.** That
+  error means a forgotten `"persistent": true`, not a stray verb.
+- **A `ref` never persists** — not as a var, not as a list element. A ref names a live player or entity in
+  THIS session and means nothing after a restart.
+- **Bulk world data has no home here.** Ten thousand placed objects cannot be replicated state, so they cannot
+  be roomVars and the rule language cannot reach them. Splitting destinations does not help.
+
+## 6. Build, validate, publish
+
+`npm install` → **`install_world_packages`** (MCP tool) → `npm run build` → `validate_world` on `dist/`
+(watch the persistence caps: 16 persistent playerVars, 16 persistent roomVars, 6 destinations, and the
+per-document byte 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`.
+
+To see it work, leave and rejoin: your level and title come back, and the guestbook survives the room itself
+shutting down.