@hypersoniclabs/helix-mcp 0.2.5 → 0.2.12

package/docs/multiplayer-templates/physics-bumper.md

@@ -35,7 +35,7 @@ a physics body** (bumper cars, derby, sumo). Lifted from the verified `multiplay
   "slug": "bumper-cars",
   "entry": "index.html",
   "maxPlayers": 8,
-  "permissions": ["auth.profile", "multiplayer"],
+  "permissions": ["auth.profile", "multiplayer", "voice.room"],
   "multiplayer": {
     "authoritative": true,
     "uploadHz": 20,
@@ -90,12 +90,22 @@ a physics body** (bumper cars, derby, sumo). Lifted from the verified `multiplay
   },
   "supportsMobile": true,
   "contentRating": "everyone",
-  "systems": { "humanoid-character": "^0.2" }
+  "systems": { "humanoid-character": "^0.3" }
 }
 ```
 
+> Voice here is **`voice.room`** (flat room-wide), not `voice.proximity`: this facade-free world has no
+> `CharacterVoice` proximity driver, so after the room join just call `Helix.voice.join()` (fail-soft) and
+> everyone hears everyone — which is what an arena wants anyway. There is no `attachVoice` without the facade.
+
 ## 3. The client — `src/main.ts` (delta from `physics-football`)
 
+> **This is the facade-free template — when NOT to use `CharacterMultiplayer`.** The facade's whole substrate is
+> humanoid presence: a local `Character` + humanoid replicas + avatars + nameplates. Here the player IS a physics
+> body (a car) — there are no humanoids at all — so the facade has nothing to contribute. Worlds like this wire
+> `Helix.init()` → guarded `joinRoom()` by hand (four lines — see the hangout appendix §a/§b) and build everything
+> from the primitives. The decision rule: **no humanoid players ⇒ no facade.**
+
 Same `SharedPhysicsWorld` + `EntityScene` physics build (a `DynamicBody` per car/puck). New for dual-sim: a
 **`DualSimController`** bound to *your* car — each frame it flips the dual-sim flag on peer cars you're touching so
 they're locally predicted + reconciled. You **drive** your car directly with a mass-aware impulse (the player IS the
@@ -121,19 +131,26 @@ const entities = new EntityScene({
   },
 });
 
+// No humanoid character here (the car IS the avatar), so the world owns AND PUMPS the router itself,
+// driving everything off the standard `move` id — WASD + left stick for free (character-world §8c):
+const input = new InputService();
+input.attach(window as never);
+input.attachPointer(renderer.domElement as never, undefined, { dragLook: true });
+registerStandardActions(input, { only: ['move'] });
+help.innerHTML = input.format('<b>{move}</b> drive · ram the other cars');  // re-run on activeDevice() change
+
 let dualSim: DualSimController | null = null, dualSimId: string | null = null;
 // frame loop:
+input.update(dt);           // NO character to pump the router — the world calls update(dt) itself, queries come AFTER
 let myId: string | null = null; const others: DynamicBody[] = [];
 for (const { id, state } of entities.entries()) {
   if (state.kind !== 'car') continue;
   if (state.controller === room.sessionId) myId = id; else { const b = carBodies.get(id); if (b) others.push(b); }
 }
 const mine = myId ? carBodies.get(myId) : undefined;
-if (mine) {                                              // WASD → mass-aware impulse (consistent accel regardless of mass)
-  // `keys` is your own Set<string> filled from keydown/keyup; screen-relative (the camera looks down −Z)
-  const dx = (keys.has('d') ? 1 : 0) - (keys.has('a') ? 1 : 0);
-  const dz = (keys.has('s') ? 1 : 0) - (keys.has('w') ? 1 : 0);
-  if (dx || dz) mine.applyImpulse({ x: dx * ACCEL * CAR_MASS * dt, y: 0, z: dz * ACCEL * CAR_MASS * dt });
+if (mine) {                                              // move vec2 → mass-aware impulse (consistent accel regardless of mass)
+  const move = input.vec2('move');                       // +y forward; screen-relative (the camera looks down −Z)
+  if (move.x || move.y) mine.applyImpulse({ x: move.x * ACCEL * CAR_MASS * dt, y: 0, z: -move.y * ACCEL * CAR_MASS * dt });
 }
 if (myId && dualSimId !== myId) { dualSim = new DualSimController(shared, myId, entities); dualSimId = myId; }
 shared.step(dt);            // ORDER MATTERS: step → dualSim.update (reads fresh contacts) → entities.update (renders the flag)
@@ -145,9 +162,10 @@ room.sendState(carPose(mine));   // the player IS the car: carPose() = a Replica
 **Footguns:** the car body **must** declare `proximityMargin` (the dual-sim engagement sensor) — omit it and dual-sim
 silently never fires; mirror `maxSpeed`/`mass`/`shape`; keep `maxPlayers ≤ 12` (uploadHz 20); the step →
 `dualSim.update` → `entities.update` order is load-bearing; one `DualSimController` bound to *your* car (rebind if
-your car id changes); `carPose(mine)`, `wasdDir`/`keys`, and `makeCarMesh` are your own helpers, not SDK APIs.
+your car id changes); character-less worlds must call `input.update(dt)` themselves every frame (with a character,
+`character.update(dt)` pumps it); `carPose(mine)` and `makeCarMesh` are your own helpers, not SDK APIs.
 
 ## 4. Build, validate, publish
 
 `npm install` → **`install_world_packages`** (MCP tool) → `npm run build` → `validate_world` on `dist/` (enforces `dualSimOnContact`
-requires `transferPolicy:'fixed'`, and `uploadHz:20` ⇒ `maxPlayers ≤ 12`) → `whoami` → `publish_world`.
+requires `transferPolicy:'fixed'`, and `uploadHz:20` ⇒ `maxPlayers ≤ 12`) → **`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/physics-football.md

@@ -4,8 +4,10 @@
 **Capability: networked physics — the AUTHORITY-TRANSFER model.** One **shared dynamic body** (the ball) sits
 server-held between touches; the instant a player contacts it the server **auto-hands control to them**
 (`claimOnContact`), that client simulates the collision locally, and when the ball comes to rest it **reverts to
-the server** (`revertOnRest`). Use this for **one contested object** (soccer, hockey, pool, air-hockey). Lifted from
-the verified `multiplayer-football` world (contract v16).
+the server** (`revertOnRest`). Use this for **one contested object** (soccer, hockey, air-hockey). A MULTI-body set
+— a pool rack, a bowling pin deck — is exactly what per-contact claiming cannot do atomically: declare a `group` on
+the kind and a `claimGroup` action instead (multiplayer-logic §9a). Lifted from the verified `multiplayer-football`
+world (contract v16).
 
 > Networked physics is the newest, churniest part of the platform — lift this verbatim. The *other* physics model
 > (each player owns their own body) is `physics-bumper`. Grammar: `read_doc({ name: "multiplayer-logic" })` §9 +
@@ -34,7 +36,7 @@ the verified `multiplayer-football` world (contract v16).
   "slug": "networked-football",
   "entry": "index.html",
   "maxPlayers": 8,
-  "permissions": ["auth.profile", "multiplayer"],
+  "permissions": ["auth.profile", "multiplayer", "voice.proximity"],
   "multiplayer": {
     "authoritative": true,
     "state": {
@@ -82,7 +84,7 @@ the verified `multiplayer-football` world (contract v16).
   },
   "supportsMobile": true,
   "contentRating": "everyone",
-  "systems": { "humanoid-character": "^0.2" }
+  "systems": { "humanoid-character": "^0.3" }
 }
 ```
 
@@ -93,14 +95,26 @@ geometry is mirrored in so the ball rests on the same floor) and an **`EntitySce
 hands back a **`DynamicBody`**. `EntityScene` flips the body hosted (I touched it → I simulate) vs remote (a proxy
 at the owner's stream) and owns the interp / gated upload.
 
+> **Why `new EntityScene(...)` here instead of `mp.entities()`:** the shared-world step MUST run between the
+> facade's upload and the entity update (drive proxies → `shared.step` → `entities.update`). `mp.entities()`
+> updates inside `mp.update()`, which would step entities before the physics world — so a physics world creates
+> the `EntityScene` directly (with `room: mp.room`) and owns its frame ordering. Presence still rides the facade.
+
 ```ts
 import { SharedPhysicsWorld, DynamicBody, EntityScene, type EntityHandle } from '@helix/humanoid-character';
+import type { PlayerState } from '@hypersoniclabs/helix-sdk';
 const BALL_MAX_SPEED = 18, BALL_RADIUS = 0.6;          // mirror the DSL maxSpeed + shape
+const room = mp.room!;
 
 const shared = await SharedPhysicsWorld.create();      // ONE shared world for the ball
 // body.addStaticCuboid(...) on your character body mirrors the arena floor/walls into `shared` too.
 const proxies = new PlayerProxies(shared);             // a kinematic capsule per player (so the ball hits players)
 
+// Live remote refs for the proxy drive (the facade renders replicas; physics needs the raw positions too).
+const others = new Map<string, PlayerState>();
+room.onAdd('players', (p, id) => { if (id !== room.sessionId) others.set(id, p); });
+room.onRemove('players', (_p, id) => others.delete(id));
+
 const entities = new EntityScene({
   room,
   maxSpeed: { ball: BALL_MAX_SPEED },
@@ -111,13 +125,13 @@ const entities = new EntityScene({
       { id, shape: { type: 'sphere', radius: BALL_RADIUS }, restitution: 0.6, friction: 0.6, mass: 1, linearDamping: 0.2, angularDamping: 0.4, ccd: true },
       { mode: 'remote', maxSpeed: BALL_MAX_SPEED },     // EntityScene flips this to 'hosted' when I own it
     );
-    return { object3d: mesh, physics: dyn, onUpdate: (e) => tintByOwner(mesh, e.controller, room!.sessionId), dispose: () => { dyn.dispose(); scene.remove(mesh); } };
+    return { object3d: mesh, physics: dyn, onUpdate: (e) => tintByOwner(mesh, e.controller, room.sessionId), dispose: () => { dyn.dispose(); scene.remove(mesh); } };
   },
 });
 
-// frame loop (inside `if (room && entities)`), AFTER replicas.update + sendState:
+// frame loop, AFTER mp.update(dt) (which already ran replicas + sendState):
 proxies.drive(room.sessionId, body.position);          // drive every player's capsule to their feet…
-for (const [id, p] of remote) proxies.drive(id, p.position);
+for (const [id, p] of others) proxies.drive(id, p.position);
 shared.step(dt);                                       // …then ONE shared-world step resolves ball ↔ floor/walls/players
 entities.update(dt);                                   // hosted ball: read post-step state → render + upload; remote: proxy at the stream
 ```
@@ -130,4 +144,4 @@ before `entities.update`; `tintByOwner`/`makeBallMesh`/`PlayerProxies` are your
 ## 4. Build, validate, publish
 
 `npm install` → **`install_world_packages`** (MCP tool) → `npm run build` → `validate_world` on `dist/` (it enforces the physics
-cross-field rules + `physicsKinds` cap) → `whoami` → `publish_world`.
+cross-field rules + `physicsKinds` cap) → **`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/relic-bearers.md

@@ -36,7 +36,7 @@ world.
   "slug": "relic-bearers",
   "entry": "index.html",
   "maxPlayers": 8,
-  "permissions": ["auth.profile", "multiplayer"],
+  "permissions": ["auth.profile", "multiplayer", "voice.proximity"],
   "multiplayer": {
     "authoritative": true,
     "state": {
@@ -84,24 +84,21 @@ world.
   },
   "supportsMobile": true,
   "contentRating": "everyone",
-  "systems": { "humanoid-character": "^0.2" }
+  "systems": { "humanoid-character": "^0.3" }
 }
 ```
 
 ## 3. The client — `src/main.ts` (delta from `hangout`)
 
-The new API is **`EntityScene`** (from `@helix/humanoid-character`) — the generic owner-entity transport. You give
-it a `build(kind)` (a mesh + `onUpdate`) and a `motion(kind)` fn; it runs your motion + predicts/reconciles/uploads
-for entities **you control** and interpolates the rest. **`maxSpeed` MUST mirror the DSL** (it drives the reconcile
-clamp).
+The new part is the **owner-entity transport** — the same `mp.entities()` call as the render-only templates,
+plus a `motion(kind)` fn: EntityScene runs your motion + predicts/reconciles/uploads for entities **you
+control** and interpolates the rest. **`maxSpeed` MUST mirror the DSL** (it drives the reconcile clamp).
 
 ```ts
-import { EntityScene } from '@helix/humanoid-character';
-
 const RELIC_MAX_SPEED = 50, PET_MAX_SPEED = 12;   // MUST equal the DSL maxSpeed
+const room = mp.room!;
 
-const entities = new EntityScene({
-  room,
+const entities = mp.entities({
   maxSpeed: { relic: RELIC_MAX_SPEED, pet: PET_MAX_SPEED },
   motion: {                                        // only invoked for entities I control
     relic: (e, dt, ctx) => stepToward(ctx.position, { x: body.position.x + Math.cos(angleFor(e.id)), y: 1.45, z: body.position.z + Math.sin(angleFor(e.id)) }, RELIC_MAX_SPEED * 0.83 * dt),
@@ -112,22 +109,22 @@ const entities = new EntityScene({
     const mat = mesh.material as THREE.MeshStandardMaterial;
     return {
       object3d: mesh,
-      onUpdate: (e) => { mat.color.setHex(e.controller === room!.sessionId ? COLOR_MINE : e.controller === '' ? COLOR_FREE : hueFor(e.controller)); },  // recolor by owner
+      onUpdate: (e) => { mat.color.setHex(e.controller === room.sessionId ? COLOR_MINE : e.controller === '' ? COLOR_FREE : hueFor(e.controller)); },  // recolor by owner
       dispose: () => { scene.remove(mesh); mesh.geometry.dispose(); mat.dispose(); },
     };
   },
 });
-// frame loop (inside `if (room)`): entities.update(dt);
+// mp.update(dt) drives the sim/interpolation — nothing to add in your frame loop.
 
 // Claim the nearest relic that isn't already mine — the client only picks the id; the SERVER runs the takeover:
 function claimNearest() {
   let best = '', bestD = CLAIM_RADIUS ** 2;
   for (const { id, object3d, state } of entities.entries()) {
-    if (state.kind !== 'relic' || state.controller === room!.sessionId) continue;
+    if (state.kind !== 'relic' || state.controller === room.sessionId) continue;
     const d2 = (object3d.position.x - body.position.x) ** 2 + (object3d.position.z - body.position.z) ** 2;
     if (d2 < bestD) { bestD = d2; best = id; }
   }
-  if (best) room!.sendAction('claim', { target: best });
+  if (best) room.sendAction('claim', { target: best });
 }
 // bind `pass` to a key: room.sendAction('pass');
 ```
@@ -137,4 +134,4 @@ function claimNearest() {
 
 ## 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/server-motion.md

@@ -34,7 +34,7 @@ prefer server motion + a retargeting rule over hosting an entity on a client.
   "slug": "vacuum-collector",
   "entry": "index.html",
   "maxPlayers": 8,
-  "permissions": ["auth.profile", "multiplayer"],
+  "permissions": ["auth.profile", "multiplayer", "voice.proximity"],
   "multiplayer": {
     "authoritative": true,
     "state": {
@@ -91,7 +91,7 @@ prefer server motion + a retargeting rule over hosting an entity on a client.
   },
   "supportsMobile": true,
   "contentRating": "everyone",
-  "systems": { "humanoid-character": "^0.2" }
+  "systems": { "humanoid-character": "^0.3" }
 }
 ```
 
@@ -101,28 +101,25 @@ tick. The retarget rule writes that var through `{ ref: room.bot, var: "target"
 
 ## 3. The client — `src/main.ts` (delta from `collect-a-thon`)
 
-Identical *server-only render-proxy* — the client never drives entity motion; the **server** owns the position and
-the client just **interpolates** toward each entity's live `position`. The only new bit is switching the mesh on
-`entity.kind`:
+Identical render-only `mp.entities()` — the client never drives entity motion; the **server** owns the position
+and EntityScene interpolates each entity off source-time. The only new bit is switching the mesh on `kind`
+(the `build` callback receives it):
 
 ```ts
-room.onAdd('entities', (entity, id) => {
-  if (entity.kind === 'vacuum') { const g = makeVacuum(); scene.add(g); bots.set(id, { g, state: entity }); }
-  else                          { const m = makeCoin();   scene.add(m); coins.set(id, { m, state: entity }); }
-});
-room.onRemove('entities', (_e, id) => {
-  const b = bots.get(id);  if (b) { scene.remove(b.g); bots.delete(id); return; }
-  const c = coins.get(id); if (c) { scene.remove(c.m); coins.delete(id); }
+const entities = mp.entities({
+  build: (kind) => {
+    const group = new THREE.Group();
+    const visual = kind === 'vacuum' ? makeVacuum() : makeCoin();
+    visual.position.y = kind === 'vacuum' ? 1 : 0.8;    // visual float — a child of the positioned group
+    group.add(visual); scene.add(group);
+    return { object3d: group, dispose: () => scene.remove(group) };
+  },
 });
-
-// frame loop (inside `if (room)`): lerp each proxy toward its synced position — the bot glides because the
-// SERVER moves it; the client only smooths the sparse updates.
-for (const [, b] of bots)  if (b.state.position) b.g.position.lerp(tmp.copy(b.state.position).setY(b.state.position.y + 1), 0.3);
-for (const [, c] of coins) if (c.state.position) c.m.position.lerp(tmp.copy(c.state.position).setY(c.state.position.y + 0.8), 0.25);
+// mp.update(dt) interpolates every entity — the bot glides because the SERVER moves it. No upload, no motion fn.
 ```
 
-No `EntityScene`, no upload — server-authoritative motion needs neither. (That's the whole appeal.)
+No `motion` fn = server-authoritative — nothing to simulate, nothing to upload. (That's the whole appeal.)
 
 ## 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/shooter-range.md

@@ -0,0 +1,275 @@
+# Multiplayer template — `shooter-range`
+
+**What it is.** An arena shooter: players carry guns, fire hitscan shots with real spread, land server-
+validated damage on each other and on destructible targets, go down into a physics ragdoll, and respawn —
+plus gun-declared damage via published weapon definitions. **Capability: the combat loop** — `playerVars.
+health` + claim actions + cooldown gates + kill credit + respawn, destructible slot-respawning entities, and
+the `weaponItems`/`weaponDamage` lane (a gun's damage comes from its PUBLISHED definition, resolved
+server-side — a client never names a number). Use this for deathmatch, team shooters, PvE ranges, horde
+survival with guns. Lifted from the verified `multiplayer-shooter-range` world.
+
+> The client half (installing `gun-control`, weapon profiles, FX/hit systems, the crosshair, ragdoll) is its
+> own recipe: **`read_doc({ name: "shooter-worlds" })` — read it FIRST.** This page is the ROOM half plus a
+> trimmed client starter. Grammar refs: `multiplayer-logic` §14 (actions), §8 (respawn), §6–7 (entities),
+> §5 (timers).
+
+## 1. DSL used
+
+- **Declared state** (§2) — `playerVars`: `health` (the room OWNS the number — rules mutate, clients read),
+  `kills`, `lastHitBy` (a player ref for kill credit).
+- **Actions** (§14) — `claimHit` (target: a player) and `claimTargetHit` (target: an entity). The client's
+  hit chain sends EXACTLY ONE claim per trigger pull (the one-claim rule — over-rate senders are struck).
+- **Timers** (§5) — a per-player `cooldown` (server-side fire-rate ceiling: claims inside 0.08 s are
+  ignored) and a per-player `respawnDelay`.
+- **`weaponItems` + the `weaponDamage` op** — the world declares WHICH published gun definitions it hosts
+  (`"<vaultAssetId>@<version>"`, ≤16); the room fetches each pinned definition itself (server-trusted,
+  checksummed) and `{"op":"weaponDamage","of":<player>,"target":<player>,"default":n}` reads the damage of
+  the gun that player is HOLDING (base × pellets, distance falloff applied when `target` is given). The
+  world still owns consequences — clamp it, scale it, or ignore it in your own rule. `default` covers a
+  player holding no declared gun. Using the op without `weaponItems` fails validation.
+- **Entities** (§6) — destructible `target` blocks with an `hp` var and a `slot` tag; a per-slot tick rule
+  respawns any missing slot (destroy → ~1 s later it is back).
+- **Broadcast** (§13) — `down { who, by }`: the server-confirmed kill feed (drive kill markers off THIS,
+  never off the client's predicted hit).
+- **`respawn`** (§8) — the death rule starts `respawnDelay`; its elapse respawns and restores health.
+
+## 2. The manifest — `public/helix.json` (the `multiplayer` block)
+
+```json
+"multiplayer": {
+  "authoritative": true,
+  "weaponItems": ["11111111-2222-4333-8444-555555555555@1"],
+  "state": {
+    "playerVars": {
+      "health": { "type": "number", "default": 100 },
+      "kills": { "type": "number", "default": 0 },
+      "lastHitBy": { "type": "ref", "of": "player" }
+    }
+  },
+  "entities": {
+    "target": { "vars": { "hp": { "type": "number", "default": 5 }, "slot": { "type": "number", "default": 0 } } }
+  },
+  "actions": {
+    "claimHit": { "args": { "target": { "type": "ref", "of": "player" } } },
+    "claimTargetHit": { "args": { "target": { "type": "ref", "of": "entity:target" } } }
+  },
+  "timers": { "cooldown": { "keyed": "player" }, "respawnDelay": { "keyed": "player" } },
+  "events": { "down": { "payload": { "who": { "type": "ref", "of": "player" }, "by": { "type": "ref", "of": "player" } } } },
+  "rules": [
+    {
+      "when": { "on": "action", "name": "claimHit" },
+      "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": "setRef", "target": { "ref": { "var": "action.args.target" }, "var": "lastHitBy" }, "to": "self" },
+        { "do": "add", "target": { "ref": { "var": "action.args.target" }, "var": "health" },
+          "by": { "op": "*", "a": -1, "b": { "op": "weaponDamage", "of": "self", "target": { "var": "action.args.target" }, "default": 20 } } },
+        { "do": "startTimer", "timer": "cooldown", "seconds": 0.08, "key": "self" }
+      ]
+    },
+    {
+      "when": { "on": "action", "name": "claimTargetHit" },
+      "if": { "op": "==", "a": { "op": "timerRemaining", "timer": "cooldown", "key": "self" }, "b": 0 },
+      "then": [
+        { "do": "add", "target": { "ref": { "var": "action.args.target" }, "var": "hp" }, "by": -1 },
+        { "do": "startTimer", "timer": "cooldown", "seconds": 0.08, "key": "self" }
+      ]
+    },
+    {
+      "when": { "on": "varReached", "scope": "self", "var": "health", "cmp": "<=", "value": 0 },
+      "then": [
+        { "do": "add", "target": { "ref": { "var": "self.lastHitBy" }, "var": "kills" }, "by": 1 },
+        { "do": "broadcast", "event": "down", "to": "all", "payload": { "who": "self", "by": { "var": "self.lastHitBy" } } },
+        { "do": "startTimer", "timer": "respawnDelay", "seconds": 2.5, "key": "self" }
+      ]
+    },
+    {
+      "when": { "on": "timerElapsed", "timer": "respawnDelay" },
+      "then": [
+        { "do": "respawn", "player": "self", "to": { "vec3": [0, 0, -2] } },
+        { "do": "set", "target": "self.health", "to": 100 }
+      ]
+    },
+    {
+      "when": { "on": "tick", "everyN": 20 },
+      "if": { "op": "==", "a": { "op": "aggregate", "scope": "entities:target", "agg": "count", "as": "t", "where": { "op": "==", "a": { "ref": "t", "var": "slot" }, "b": 1 } }, "b": 0 },
+      "then": [{ "do": "spawnEntity", "kind": "target", "at": { "vec3": [-6, 0, 10] }, "vars": { "slot": 1 } }]
+    },
+    {
+      "when": { "on": "tick", "everyN": 1 },
+      "then": [{ "do": "forEachEntity", "kind": "target", "as": "t", "where": { "op": "<=", "a": { "ref": "t", "var": "hp" }, "b": 0 }, "then": [{ "do": "destroyEntity", "entity": "t" }] }]
+    }
+  ]
+}
+```
+
+Duplicate the slot-1 spawn rule per target position (slot 2, 3, … each with its own `at`). The pattern
+"count of my slot == 0 → spawn me" IS the respawn — destroyed targets come back on the next check. Replace
+the `weaponItems` example id with a supported, existing package-backed weapon definition pin (`assetId@version`); a world using ONLY hand-registered profiles drops `weaponItems` and hardcodes `"by": -20`.
+
+**Why the claims carry no damage:** a client-named number is a client-named damage multiplier. The gun's
+damage lives in its PUBLISHED, immutable definition; the room resolves it itself (`weaponItems`) off the
+attachment the shooter is actually holding. The distance gate (60 m) and the cooldown timer are the
+anti-cheat floor — keep both.
+
+## 3. The client — `src/main.ts` (delta from `hangout`)
+
+The full recipe with every option explained is `read_doc({ name: "shooter-worlds" })`; this is the minimal
+assembly. Prereqs: `gun-control` pinned + installed (bundle at the WORLD ROOT — see the recipe's §1),
+a gun GLB in `public/props/`, its shot sounds in `public/fx/sounds/`.
+
+```ts
+import { Helix } from '{{SDK_DEP_SPEC}}';
+import {
+  CharacterMultiplayer, GunAudio, GunFxSystem, GunHitSystem, MuzzleFlashPool, RapierBody, ShellEjector, TracerPool,
+  applyWeaponProfile, createSpreadCrosshair, loadInstalledAbilities, registerWeaponProfile, resolveWeaponProfile,
+} from '@helix/humanoid-character';
+
+const SPAWN = { x: 0, y: 0, z: -2 };
+const GUN_URL = new URL('props/blaster.glb', location.href).href; // ABSOLUTE — the ref replicates verbatim
+
+// One world-supplied gun: cadence/ammo/spread by category, sounds by relative path. Published definitions
+// replace this block with installWeaponItem(...) — see shooter-worlds §8.
+registerWeaponProfile({
+  weapon: 'blaster', category: 'Rifle',
+  fire: { rpm: 480, mode: 'auto' }, ammo: { clip: 30, reserve: 90 },
+  damage: { base: 11, falloffM: [], sweepRadiusM: 0.02, maxRangeM: 100, pellets: 1, tags: [] },
+  spread: resolveWeaponProfile('KAL')?.spread ?? /* copy a category spread block */ undefined as never,
+  fx: { shell: 'rifle', muzzlePointM: [0, 0.05, 0.4] },
+  sounds: { shots: ['blaster/shot_01.ogg', 'blaster/shot_02.ogg'] },
+});
+
+const body = await RapierBody.create({ position: SPAWN });
+// …your floor/walls/static colliders here…
+
+const soundsBaseUrl = new URL('fx/sounds/', location.href).href;
+const modulesBaseUrl = new URL('helix_modules/', document.baseURI).href;
+
+// ONE audio, flash pool and shell ejector for the WHOLE world. Every GunFxSystem (local + each replica)
+// writes into these three; only the LOCAL system gets the real objects and advances them — replicas get
+// non-advancing shims (their update is dt-driven, per-character ticking decays FX N× too fast, and a
+// per-replica GunAudio would open an AudioContext each — browsers cap those around six).
+const audio = new GunAudio({ listenerTarget: camera });
+const flashPool = new MuzzleFlashPool({ scene });
+const shells = new ShellEjector({ scene, baseUrl: new URL('fx/shells/', location.href).href });
+const sharedAudio = { preload: (u) => audio.preload(u), play: (u, o) => audio.play(u, o), setMasterVolume: (v) => audio.setMasterVolume(v), update: () => {}, dispose: () => {} };
+const sharedFlash = { flash: (a, o) => flashPool.flash(a, o), update: () => {}, dispose: () => {} };
+const sharedShells = { preload: (c) => shells.preload(c), eject: (c, o, r, u) => shells.eject(c, o, r, u), update: () => {}, dispose: () => {} };
+const replicaFx = new Map(); // id → { character, player, fx, url, prop } — the per-frame weapon poll reads it
+
+const mp = await CharacterMultiplayer.create({
+  helix: Helix, renderer, scene, camera, body, assetBase: SYSTEM_ASSET_BASE, spawn: SPAWN,
+  character: {
+    character: { health: { enabled: true } },                      // the room's health drives the chassis
+    bindings: { 'gun-control.equip': 'KeyH' },                     // off Digit1 (equip-slot collision)
+  },
+  replica: {
+    decorate: (character, player, id) => {                         // replicas run the SAME bundle, remote-driven
+      character.setEnabled(false);
+      const fx = new GunFxSystem({ scene, camera, soundsBaseUrl, audio: sharedAudio, flashPool: sharedFlash, shells: sharedShells });
+      fx.attachTo(character);
+      const entry = { character, player, fx, url: null, prop: null };
+      replicaFx.set(id, entry);
+      void loadInstalledAbilities(modulesBaseUrl, character)
+        .then(() => character.services.config.set('gun-control.remoteDriven', true))
+        .finally(() => character.setEnabled(true));
+      // Identity-guarded: the facade can build a seat twice back-to-back — a losing build's dispose
+      // must not evict the winner's live entry.
+      return { dispose: () => { fx.dispose(); if (replicaFx.get(id) === entry) replicaFx.delete(id); } };
+    },
+  },
+});
+
+await loadInstalledAbilities(modulesBaseUrl, mp.local);            // BEFORE the first mp.update()
+
+// Bundle blackboard keys exist only while the bundle is installed — the has() guard keeps a per-frame
+// read from ever throwing inside the render loop (an uncaught throw there freezes the world for good).
+const bb = (key) => (mp.local.blackboard.has(key) ? mp.local.blackboard.get(key) : undefined);
+// The weapon a player replicated onto the grip socket, or null (attachments is an Iterable, not an array).
+const gripAsset = (player) => {
+  for (const a of player?.attachments ?? []) if (a.socket === 'hand_r.grip') return a.asset;
+  return null;
+};
+
+const gunFx = new GunFxSystem({ scene, camera, soundsBaseUrl, audio, flashPool, shells });
+gunFx.attachTo(mp.local);
+const tracers = new TracerPool({ scene });
+const gunHit = new GunHitSystem({
+  camera, body,
+  walkSpeedMps: mp.local.services.config.get('locomotion.walkSpeed'),
+  maxSpeedMps: mp.local.services.config.get('locomotion.runSpeed'),
+  muzzle: (out) => gunFx.muzzleWorld(out),
+  players: function* () { for (const [id, r] of replicaFx) yield { id, position: r.character.model.position }; },
+  onPlayerHit: ({ id, point, claim }) => {
+    tracers.spawn(tracerFrom(point), point);
+    if (claim) { mp.room?.sendAction('claimHit', { target: id }); crosshair.hit('hit'); }
+  },
+  onWorldHit: ({ point }) => tracers.spawn(tracerFrom(point), point),
+  onMiss: ({ end }) => tracers.spawn(tracerFrom(end), end),
+});
+gunHit.attachTo(mp.local);
+const crosshair = createSpreadCrosshair({
+  spreadDeg: () => gunHit.spreadDeg, fovYDeg: () => camera.fov,
+  visible: () => bb('gunDrawn') === true,
+});
+
+// Equip drawn: attach (replicates) → profile → FX/hit wiring → the draw tap (no `drawn` config exists).
+const held = await mp.attach(GUN_URL, 'hand_r.grip', { preset: 'rifle' });
+const profile = resolveWeaponProfile(GUN_URL);
+if (profile) applyWeaponProfile(mp.local, profile);
+gunFx.setWeapon(GUN_URL, held.object);
+gunHit.setWeapon(GUN_URL);
+mp.local.services.input.setVirtualButton('gun-control.equip', true);
+mp.local.services.input.setVirtualButton('gun-control.equip', null);
+mp.local.events.on('revived', () => { /* same two-line tap — death holsters */ });
+
+// The server-confirmed kill feed — the authoritative marker (the predicted one can over-report).
+mp.room?.onMessage('down', ({ who, by }) => { if (by === mp.room?.sessionId && who !== by) crosshair.hit('lethal'); });
+
+renderer.setAnimationLoop(() => {
+  const dt = Math.min(clock.getDelta(), 0.1);
+  mp.update(dt);          // shots latch during the character tick…
+  gunFx.update(dt);       // …and resolve after it — keep this order
+  gunHit.update(dt);
+  tracers.update(dt);
+  crosshair.update(dt);
+  // REQUIRED — replica weapons resolve by poll, or other players' guns are silent, flashless and held
+  // two-handed. The wire url lands with the attachment set but the prop GLB loads async: wait for the
+  // PAIR, re-resolve on either edge, and tick each replica's FX system after its character updated.
+  for (const r of replicaFx.values()) {
+    const url = gripAsset(r.player);          // helper below — attachments is an Iterable, not an array
+    const prop = r.character.services.sockets?.anchorOf('hand_r.grip')?.children[0] ?? null;
+    if (url !== r.url || prop !== r.prop) {
+      r.url = url; r.prop = prop;
+      const ready = url !== null && prop !== null;
+      const profile = url !== null ? resolveWeaponProfile(url) : null;
+      r.fx.setWeapon(ready ? url : null, ready ? prop : null);        // muzzle point, shot sounds, shells
+      if (profile !== null) {
+        try { applyWeaponProfile(r.character, profile); }             // stance family (one-handed!), placement
+        catch (err) { console.warn('replica profile failed:', err); } // untrusted item data — config.set throws
+      }
+    }
+    r.fx.update(dt);
+  }
+  renderer.render(scene, camera);
+});
+```
+
+**Footguns:** the frame order is a contract (shots resolve AFTER `mp.update`); the replica weapon poll
+above is NOT optional — `GunFxSystem` without `setWeapon` is silently inert, and `shotSeq` still driving
+the recoil animation hides the omission; one claim per trigger — the room strikes over-rate action
+senders; read `walkSpeedMps`/`maxSpeedMps` from live locomotion config, never literals; the health HUD
+reads `mp.room.me.num('health', 100)` fresh each frame; ragdoll needs nothing — death hands the body to
+physics automatically (tune via `character.ragdoll`, recipe §6), and NEVER wrap it in an input-context
+push (that releases pointer lock — the shooter guide §6/§7 has both rules in full); destructible
+targets are `mp.entities()` + `mp.damageables({ action: 'claimTargetHit' })` — the recipe's §4 shows the
+registration.
+
+## 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) → `whoami` → `publish_world`. Verify with TWO clients —
+every combat bug worth finding is invisible solo.