@helix3/helix-mcp 0.2.2-helix3.14

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

@@ -0,0 +1,153 @@
+# Multiplayer template — `physics-bumper`
+
+**What it is.** Each player drives a physics **car** and bashes into everyone else's. **Capability: networked
+physics — the DUAL-SIM model.** Each player **permanently owns their own body** (`transferPolicy:'fixed'` — you
+never lose your car); on contact both clients **simulate both cars and reconcile favor-local** (`dualSimOnContact`)
+so ramming feels instant on both screens. Runs on the **`uploadHz: 20`** fast tier. Use this when **every player is
+a physics body** (bumper cars, derby, sumo). Lifted from the verified `multiplayer-bumper-cars-20hz` world.
+
+> Two things differ from the other templates: (1) the **player IS the car** — a physics entity, **no humanoid
+> avatar** (you still pin `humanoid-character` for the physics + networking primitives). (2) `uploadHz: 20`
+> **caps `maxPlayers` at 12** (publish enforces it). Read `physics-football` first (shared `SharedPhysicsWorld` +
+> `EntityScene` physics). Grammar: `read_doc({ name: "multiplayer-logic" })` §9 + physics.
+
+## 1. DSL used
+
+- **`uploadHz: 20`** (§1) — the fast client→server tier for twitchy physics. **Hard rule: `maxPlayers ≤ 12`** (the
+  validator rejects more). Default is 10; opt to 20 only when motion is fast *and* the room is small.
+- **A dual-sim `physics` entity** (§9) — `car` is `authority:'owner'` + `maxSpeed` + a `physics` block with
+  **`dualSimOnContact: true`**. **Cross-field rule:** `dualSimOnContact` **requires `transferPolicy:'fixed'`**
+  (the default — a controlled body never transfers). `ownerLifecycle:'despawnWithOwner'` removes a player's car
+  when they leave.
+- **(Reused) an authority-transfer `physics` entity** — `puck` is the `physics-football` pattern
+  (`claimOnContact` + `revertOnRest` + `transferPolicy:'takeover'`): one shared object anyone can grab. A world can
+  mix both physics models.
+- **Declared state** (§2) — `playerVars.car` (a ref to my car) + `bumps`; `roomVars.puckRef`.
+- **Rules** (§3) — `playerJoin` spawns a `car` and stores it in `self.car`; `tick` keeps one `puck` alive; the
+  `claim` action takes over the puck.
+
+## 2. The manifest — `public/helix.json`
+
+```json
+{
+  "helixVersion": "0.3",
+  "title": "Bumper Cars",
+  "slug": "bumper-cars",
+  "entry": "index.html",
+  "maxPlayers": 8,
+  "permissions": ["auth.profile", "multiplayer"],
+  "multiplayer": {
+    "authoritative": true,
+    "uploadHz": 20,
+    "state": {
+      "roomVars": { "puckRef": { "type": "ref", "of": "entity:puck" } },
+      "playerVars": { "car": { "type": "ref", "of": "entity:car" }, "bumps": { "type": "number", "default": 0 } }
+    },
+    "entities": {
+      "car": {
+        "authority": "owner",
+        "maxSpeed": 20,
+        "ownerLifecycle": "despawnWithOwner",
+        "physics": {
+          "bodyType": "dynamic",
+          "shape": { "type": "box", "halfExtents": [0.9, 0.5, 1.6] },
+          "mass": 4, "restitution": 0.8, "friction": 0.7,
+          "dualSimOnContact": true
+        }
+      },
+      "puck": {
+        "authority": "owner",
+        "maxSpeed": 20,
+        "transferPolicy": "takeover",
+        "physics": {
+          "bodyType": "dynamic",
+          "shape": { "type": "box", "halfExtents": [0.9, 0.5, 1.6] },
+          "mass": 4, "restitution": 0.8, "friction": 0.7,
+          "claimOnContact": true, "revertOnRest": true
+        }
+      }
+    },
+    "states": { "initial": "play", "phases": ["play"], "joinPolicy": { "play": { "joinable": true } } },
+    "actions": { "claim": { "args": { "target": { "type": "ref", "of": "entity:puck" } } } },
+    "rules": [
+      {
+        "when": { "on": "playerJoin" },
+        "then": [
+          { "do": "spawnEntity", "kind": "car", "at": { "op": "randomPoint", "min": [-6, 0.5, -6], "max": [6, 0.5, 6] }, "bind": "spawned" },
+          { "do": "setRef", "target": "self.car", "to": "spawned" }
+        ]
+      },
+      { "when": { "on": "action", "name": "claim" }, "then": [{ "do": "takeover", "entity": { "var": "action.args.target" }, "to": "self" }] },
+      {
+        "when": { "on": "tick" },
+        "if": { "op": "<", "a": { "op": "aggregate", "scope": "entities:puck", "agg": "count" }, "b": 1 },
+        "then": [
+          { "do": "spawnEntity", "kind": "puck", "at": { "vec3": [0, 0.5, 0] }, "bind": "spawned" },
+          { "do": "setRef", "target": "room.puckRef", "to": "spawned" }
+        ]
+      }
+    ]
+  },
+  "supportsMobile": true,
+  "contentRating": "everyone",
+  "systems": { "humanoid-character": "^0.2" }
+}
+```
+
+## 3. The client — `src/main.ts` (delta from `physics-football`)
+
+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
+car — no humanoid `Character`/`ReplicaScene`):
+
+```ts
+import { EntityScene, SharedPhysicsWorld, DynamicBody, DualSimController, type EntityHandle } from '@helix/humanoid-character';
+const CAR_MAX_SPEED = 20, CAR_MASS = 4, ACCEL = 26;     // mirror the DSL maxSpeed + mass
+
+const shared = await SharedPhysicsWorld.create();
+const carBodies = new Map<string, DynamicBody>();        // entity id → its DynamicBody
+const entities = new EntityScene({
+  room, maxSpeed: { car: CAR_MAX_SPEED, puck: CAR_MAX_SPEED },
+  build: (kind, id): EntityHandle => {
+    const dyn = new DynamicBody(shared,
+      { id, shape: { type: 'box', halfExtents: [0.9, 0.5, 1.6] }, mass: CAR_MASS, restitution: 0.8, friction: 0.7,
+        linearDamping: 0.6, angularDamping: 0.8, ccd: true,
+        enabledRotations: [false, true, false],   // yaw-only: the car stays flat, only spins about Y
+        proximityMargin: 0.6 },                    // REQUIRED for dual-sim — the engagement sensor; OMIT IT AND DUAL-SIM NEVER FIRES
+      { mode: 'remote', maxSpeed: CAR_MAX_SPEED, maxAngularSpeed: 8 });
+    carBodies.set(id, dyn);
+    return { object3d: makeCarMesh(kind), physics: dyn, onUpdate: () => {}, dispose: () => { dyn.dispose(); carBodies.delete(id); } };
+  },
+});
+
+let dualSim: DualSimController | null = null, dualSimId: string | null = null;
+// frame loop:
+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 (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)
+dualSim?.update(others);
+entities.update(dt);
+room.sendState(carPose(mine));   // the player IS the car: carPose() = a ReplicaInput from the car body's transform (no humanoid)
+```
+
+**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.
+
+## 4. Build, validate, publish
+
+`npm install` → `helix install` → `npm run build` → `validate_world` on `dist/` (enforces `dualSimOnContact`
+requires `transferPolicy:'fixed'`, and `uploadHz:20` ⇒ `maxPlayers ≤ 12`) → `whoami` → `publish_world`.

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

@@ -0,0 +1,133 @@
+# Multiplayer template — `physics-football`
+
+**What it is.** A shared ball with real physics: players bump it around an arena and into goals to score.
+**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).
+
+> 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 +
+> the physics section.
+
+## 1. DSL used
+
+- **A `physics` entity** (§9) — `ball` is `authority:'owner'` + `maxSpeed` + `transferPolicy:'takeover'` + a
+  **`physics` block**: `bodyType:'dynamic'`, a `shape` (sphere/box/capsule), and material (`mass`, `restitution`,
+  `friction`, optional `linearDamping`/`angularDamping`). The two arbitration flags: **`claimOnContact: true`**
+  (server auto-takes-over the body to whoever touches it — **requires `transferPolicy:'takeover'`**) and
+  **`revertOnRest: true`** (release to the server when at rest). Validator rules: a `physics` block **requires**
+  `authority:'owner'`; `claimOnContact` **requires** `transferPolicy:'takeover'`. Cap: ≤ `physicsKinds` (8) per world.
+- **Zones** (§10) — two goal volumes that `tracks:'entity:ball'` (the ball entering a goal fires `zoneEnter`).
+- **Declared state** (§2) — `ballRef` (a ball ref) + two scores.
+- **Actions/rules** (§3/§14) — spawn the ball when none exists; goal `zoneEnter` → score + `destroyEntity`; an
+  optional `claim` action lets a client *optimistically* request the takeover for instant response (the server's
+  `claimOnContact` is the authority).
+
+## 2. The manifest — `public/helix.json`
+
+```json
+{
+  "helixVersion": "0.3",
+  "title": "Networked Football",
+  "slug": "networked-football",
+  "entry": "index.html",
+  "maxPlayers": 8,
+  "permissions": ["auth.profile", "multiplayer"],
+  "multiplayer": {
+    "authoritative": true,
+    "state": {
+      "roomVars": {
+        "ballRef": { "type": "ref", "of": "entity:ball" },
+        "westScore": { "type": "number", "default": 0 },
+        "eastScore": { "type": "number", "default": 0 }
+      }
+    },
+    "entities": {
+      "ball": {
+        "authority": "owner",
+        "maxSpeed": 18,
+        "transferPolicy": "takeover",
+        "physics": {
+          "bodyType": "dynamic",
+          "shape": { "type": "sphere", "radius": 0.6 },
+          "mass": 1,
+          "restitution": 0.6,
+          "friction": 0.6,
+          "claimOnContact": true,
+          "revertOnRest": true
+        }
+      }
+    },
+    "states": { "initial": "play", "phases": ["play"], "joinPolicy": { "play": { "joinable": true } } },
+    "zones": [
+      { "id": "westGoal", "shape": "box", "center": [-17.5, 1.75, 0], "size": [1.6, 3.5, 6], "tracks": "entity:ball" },
+      { "id": "eastGoal", "shape": "box", "center": [17.5, 1.75, 0], "size": [1.6, 3.5, 6], "tracks": "entity:ball" }
+    ],
+    "actions": { "claim": { "args": { "target": { "type": "ref", "of": "entity:ball" } } } },
+    "rules": [
+      { "when": { "on": "action", "name": "claim" }, "then": [{ "do": "takeover", "entity": { "var": "action.args.target" }, "to": "self" }] },
+      {
+        "when": { "on": "tick" },
+        "if": { "op": "<", "a": { "op": "aggregate", "scope": "entities:ball", "agg": "count" }, "b": 1 },
+        "then": [
+          { "do": "spawnEntity", "kind": "ball", "at": { "vec3": [0, 0.6, 0] }, "bind": "spawned" },
+          { "do": "setRef", "target": "room.ballRef", "to": "spawned" }
+        ]
+      },
+      { "when": { "on": "zoneEnter", "zone": "westGoal" }, "then": [{ "do": "add", "target": "room.eastScore", "by": 1 }, { "do": "destroyEntity", "entity": "self" }] },
+      { "when": { "on": "zoneEnter", "zone": "eastGoal" }, "then": [{ "do": "add", "target": "room.westScore", "by": 1 }, { "do": "destroyEntity", "entity": "self" }] }
+    ]
+  },
+  "supportsMobile": true,
+  "contentRating": "everyone",
+  "systems": { "humanoid-character": "^0.2" }
+}
+```
+
+## 3. The client — `src/main.ts` (delta from `relic-bearers`)
+
+Physics adds **one `SharedPhysicsWorld`** (the ball + a kinematic capsule proxy per player; the character's static
+geometry is mirrored in so the ball rests on the same floor) and an **`EntityScene` `physics` kind** whose `build`
+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.
+
+```ts
+import { SharedPhysicsWorld, DynamicBody, EntityScene, type EntityHandle } from '@helix/humanoid-character';
+const BALL_MAX_SPEED = 18, BALL_RADIUS = 0.6;          // mirror the DSL maxSpeed + shape
+
+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)
+
+const entities = new EntityScene({
+  room,
+  maxSpeed: { ball: BALL_MAX_SPEED },
+  build: (_kind, id): EntityHandle => {
+    const mesh = makeBallMesh(); scene.add(mesh);
+    const dyn = new DynamicBody(
+      shared,
+      { 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); } };
+  },
+});
+
+// frame loop (inside `if (room && entities)`), AFTER replicas.update + 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);
+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
+```
+
+`claimOnContact` is **server-automatic** — you don't have to call anything to get the handoff. (For zero-latency
+feel you may optimistically host on contact + `room.sendAction('claim', { target: id })`; the server's claim is
+authoritative.) **Footguns:** mirror `maxSpeed` + the `shape`; one `SharedPhysicsWorld`; step it once per frame
+before `entities.update`; `tintByOwner`/`makeBallMesh`/`PlayerProxies` are your own helpers, not SDK APIs.
+
+## 4. Build, validate, publish
+
+`npm install` → `helix install` → `npm run build` → `validate_world` on `dist/` (it enforces the physics
+cross-field rules + `physicsKinds` cap) → `whoami` → `publish_world`.

package/docs/multiplayer-templates/relic-bearers.md

@@ -0,0 +1,140 @@
+# Multiplayer template — `relic-bearers`
+
+**What it is.** Relics lie scattered; walk up and **claim** one and it floats around you; **pass** your relics to
+the least-busy player; and each player gets a **pet** that trails behind them and survives brief disconnects.
+**Capability: CLIENT-hosted single-owner entities** (`authority: "owner"`) — the **escape hatch** for motion the
+server can't compute — driven through **`EntityScene`**, plus **ownership** reads/transfer (`controlledBy`,
+`leastLoadedPlayer`, `takeover`) and owner-leave **migration**. Lifted from the verified `multiplayer-relic-bearers`
+world.
+
+> Prefer **server motion** (`server-motion` template) first; reach for `authority:'owner'` only when a client must
+> simulate the entity. Hosting is **reachable only through `EntityScene`** — never call `room.uploadEntity`.
+> Grammar: `read_doc({ name: "multiplayer-logic" })` §7–§9.
+
+## 1. DSL used
+
+- **Entities** (§9) — `relic` (`authority:'owner'`, `maxSpeed:50`, `transferPolicy:'takeover'` so it can be
+  stolen) and `pet` (`authority:'owner'`, `maxSpeed:12`, `ownerLifecycle:'migrateToServer'` — it freezes during a
+  brief owner absence and the **same** owner resumes on reconnect). `maxSpeed` is **required** for owner kinds.
+- **Declared state** (§2) — `relicsSpawned`, `heir` (a `ref` player), `handoffs`.
+- **Actions** (§14) — `claim` (arg `target`: a relic ref) and `pass`. Actions are the **cheat-resistant** path;
+  the client picks a target id, the **server** decides the transfer.
+- **Ownership ops** (§7/§8) — `takeover` (move authority), `controlledBy` (filter), `leastLoadedPlayer` (the
+  least-busy host — load balancing).
+- **Rules** (§3) — spawn 5 relics; spawn a `pet` per `playerJoin`; `claim` → `takeover` to `self`; `pass` /
+  `playerLeave` → re-home this player's relics to `leastLoadedPlayer` via `forEachEntity … where controlledBy`.
+
+> **Firewall (§17):** owner-entity logic can't write to other players. Cross-player effects (claiming, stealing)
+> go through a server-validated **action**, never from the entity's own client.
+
+## 2. The manifest — `public/helix.json`
+
+```json
+{
+  "helixVersion": "0.3",
+  "title": "Relic Bearers",
+  "slug": "relic-bearers",
+  "entry": "index.html",
+  "maxPlayers": 8,
+  "permissions": ["auth.profile", "multiplayer"],
+  "multiplayer": {
+    "authoritative": true,
+    "state": {
+      "roomVars": {
+        "relicsSpawned": { "type": "number", "default": 0 },
+        "heir": { "type": "ref", "of": "player" },
+        "handoffs": { "type": "number", "default": 0 }
+      }
+    },
+    "entities": {
+      "relic": { "authority": "owner", "maxSpeed": 50, "transferPolicy": "takeover" },
+      "pet": { "authority": "owner", "maxSpeed": 12, "ownerLifecycle": "migrateToServer" }
+    },
+    "states": { "initial": "play", "phases": ["play"], "joinPolicy": { "play": { "joinable": true } } },
+    "actions": {
+      "claim": { "args": { "target": { "type": "ref", "of": "entity:relic" } } },
+      "pass": {}
+    },
+    "rules": [
+      {
+        "when": { "on": "tick", "everyN": 1 },
+        "if": { "op": "<", "a": { "var": "room.relicsSpawned" }, "b": 5 },
+        "then": [
+          { "do": "spawnEntity", "kind": "relic", "at": { "op": "randomPoint", "min": [-14, 0, -14], "max": [14, 0, 14] } },
+          { "do": "add", "target": "room.relicsSpawned", "by": 1 }
+        ]
+      },
+      { "when": { "on": "playerJoin" }, "then": [{ "do": "spawnEntity", "kind": "pet", "at": { "var": "self.position" } }] },
+      { "when": { "on": "action", "name": "claim" }, "then": [{ "do": "takeover", "entity": { "var": "action.args.target" }, "to": "self" }] },
+      {
+        "when": { "on": "action", "name": "pass" },
+        "then": [
+          { "do": "setRef", "target": "room.heir", "to": { "op": "leastLoadedPlayer" } },
+          { "do": "forEachEntity", "kind": "relic", "as": "r", "where": { "op": "controlledBy", "entity": "r", "by": "self" }, "then": [{ "do": "takeover", "entity": "r", "to": { "var": "room.heir" } }] }
+        ]
+      },
+      {
+        "when": { "on": "playerLeave" },
+        "then": [
+          { "do": "setRef", "target": "room.heir", "to": { "op": "leastLoadedPlayer" } },
+          { "do": "forEachEntity", "kind": "relic", "as": "r", "where": { "op": "controlledBy", "entity": "r", "by": "self" }, "then": [{ "do": "takeover", "entity": "r", "to": { "var": "room.heir" } }, { "do": "add", "target": "room.handoffs", "by": 1 }] }
+        ]
+      }
+    ]
+  },
+  "supportsMobile": true,
+  "contentRating": "everyone",
+  "systems": { "humanoid-character": "^0.2" }
+}
+```
+
+## 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).
+
+```ts
+import { EntityScene } from '@helix/humanoid-character';
+
+const RELIC_MAX_SPEED = 50, PET_MAX_SPEED = 12;   // MUST equal the DSL maxSpeed
+
+const entities = new EntityScene({
+  room,
+  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),
+    pet:   (_e, dt, ctx) => stepToward(ctx.position, { x: body.position.x - 1.4, y: 0.35, z: body.position.z - 1.4 }, PET_MAX_SPEED * 0.83 * dt),
+  },
+  build: (kind) => {
+    const mesh = kind === 'pet' ? makePet() : makeRelic(); scene.add(mesh);
+    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
+      dispose: () => { scene.remove(mesh); mesh.geometry.dispose(); mat.dispose(); },
+    };
+  },
+});
+// frame loop (inside `if (room)`): entities.update(dt);
+
+// 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;
+    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 });
+}
+// bind `pass` to a key: room.sendAction('pass');
+```
+
+**Footguns:** mirror `maxSpeed` (DSL ↔ `EntityScene`); never call `room.uploadEntity` — register through
+`EntityScene`; recolor by `e.controller` (`''` = unowned/server) so claims + hand-offs are visible.
+
+## 4. Build, validate, publish
+
+`npm install` → `helix install` → `npm run build` → `validate_world` on `dist/` → `whoami` → `publish_world`.

package/docs/multiplayer-templates/server-motion.md

@@ -0,0 +1,128 @@
+# Multiplayer template — `server-motion`
+
+**What it is.** A roaming **bot vacuum** glides around the arena chasing the nearest player and hoovering up coins
+it passes over — all computed **on the server**. **Capability: server-authoritative entity motion** (`seek` /
+`waypoints` / `orbit` / `linear`). This is the **preferred entity default**: declare `motion` and the server moves
+the entity deterministically — cheat-proof, never freezes, no client hosting. Reach for client hosting
+(`relic-bearers`) only when the server genuinely can't compute the behavior. Lifted from the verified
+`multiplayer-vacuum-collector` world.
+
+> Read the **hub** + `collect-a-thon` first (this reuses its server-entity render-proxy). Grammar:
+> `read_doc({ name: "multiplayer-logic" })` §9 (entities/motion).
+
+## 1. DSL used
+
+- **Entities** (§9) — `coin` (a `value`) + `vacuum`, which has `motion: { type: "seek", target: "target", speed }`
+  (homes toward whatever player its `target` ref var holds) and an **attached zone** that `tracks: "entity:coin"`
+  (entity-vs-entity overlap — the vacuum's field absorbs coins, with `requireDwell`/`debounce`). Both default to
+  `authority: "server"` — **no client code drives them.**
+- **Declared state** (§2) — `roomVars.collected` + `roomVars.bot` (a `ref` to the vacuum entity).
+- **State machine** (§12) — a single `playing` phase, used as a `stateEnter` setup hook.
+- **Rules** (§3) — spawn the bot + coins on `stateEnter`; **the "AI": every 10 ticks, re-point the bot's `target`
+  to `{op:"nearestPlayer"}`** (so `seek` chases the closest player); refill coins when the count hits 0
+  (`aggregate count`); on the vacuum-zone `zoneEnter` (binds `self` = the coin) add its value + `destroyEntity`.
+
+The whole "chase" behavior is **two rules + a `seek` motion** — no pathfinding, no client sim. That's the lesson:
+prefer server motion + a retargeting rule over hosting an entity on a client.
+
+## 2. The manifest — `public/helix.json`
+
+```json
+{
+  "helixVersion": "0.3",
+  "title": "Vacuum Collector",
+  "slug": "vacuum-collector",
+  "entry": "index.html",
+  "maxPlayers": 8,
+  "permissions": ["auth.profile", "multiplayer"],
+  "multiplayer": {
+    "authoritative": true,
+    "state": {
+      "roomVars": {
+        "collected": { "type": "number", "default": 0 },
+        "bot": { "type": "ref", "of": "entity:vacuum" }
+      }
+    },
+    "entities": {
+      "coin": { "vars": { "value": { "type": "number", "default": 1 } } },
+      "vacuum": {
+        "vars": { "target": { "type": "ref", "of": "player" } },
+        "motion": { "type": "seek", "target": "target", "speed": 2.5 },
+        "zone": { "shape": "sphere", "radius": 2.5, "tracks": "entity:coin", "requireDwell": 0.8, "debounce": 0.3 }
+      }
+    },
+    "states": { "initial": "playing", "phases": ["playing"] },
+    "rules": [
+      {
+        "when": { "on": "stateEnter", "phase": "playing" },
+        "then": [
+          { "do": "spawnEntity", "kind": "vacuum", "at": { "vec3": [0, 0, 0] } },
+          { "do": "setRef", "target": "room.bot", "to": { "op": "nearestEntity", "from": { "vec3": [0, 0, 0] }, "kind": "vacuum" } },
+          { "do": "spawnEntity", "kind": "coin", "at": { "vec3": [8, 0, 0] } },
+          { "do": "spawnEntity", "kind": "coin", "at": { "vec3": [-8, 0, 0] } },
+          { "do": "spawnEntity", "kind": "coin", "at": { "vec3": [0, 0, 8] } },
+          { "do": "spawnEntity", "kind": "coin", "at": { "vec3": [0, 0, -8] } }
+        ]
+      },
+      {
+        "when": { "on": "tick", "everyN": 40 },
+        "if": { "op": "==", "a": { "op": "aggregate", "scope": "entities:coin", "agg": "count" }, "b": 0 },
+        "then": [
+          { "do": "spawnEntity", "kind": "coin", "at": { "vec3": [8, 0, 8] } },
+          { "do": "spawnEntity", "kind": "coin", "at": { "vec3": [-8, 0, -8] } },
+          { "do": "spawnEntity", "kind": "coin", "at": { "vec3": [8, 0, -8] } },
+          { "do": "spawnEntity", "kind": "coin", "at": { "vec3": [-8, 0, 8] } }
+        ]
+      },
+      {
+        "when": { "on": "tick", "everyN": 10 },
+        "then": [
+          { "do": "setRef", "target": { "ref": { "var": "room.bot" }, "var": "target" }, "to": { "op": "nearestPlayer", "from": { "ref": { "var": "room.bot" }, "var": "position" } } }
+        ]
+      },
+      {
+        "when": { "on": "zoneEnter", "zone": "vacuum" },
+        "then": [
+          { "do": "add", "target": "room.collected", "by": { "ref": "self", "var": "value" } },
+          { "do": "destroyEntity", "entity": "self" }
+        ]
+      }
+    ]
+  },
+  "supportsMobile": true,
+  "contentRating": "everyone",
+  "systems": { "humanoid-character": "^0.2" }
+}
+```
+
+`motion.target` names a `ref`-typed var **on the entity**; the server integrates `seek` toward that member each
+tick. The retarget rule writes that var through `{ ref: room.bot, var: "target" }`. The vacuum's attached zone
+`tracks: "entity:coin"`, so its `zoneEnter` binds `self` = the **coin** (entity-vs-entity).
+
+## 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`:
+
+```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); }
+});
+
+// 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);
+```
+
+No `EntityScene`, no upload — server-authoritative motion needs neither. (That's the whole appeal.)
+
+## 4. Build, validate, publish
+
+`npm install` → `helix install` → `npm run build` → `validate_world` on `dist/` → `whoami` → `publish_world`.