@helix3/helix-mcp 0.2.2-helix3.14

package/docs/multiplayer-logic.md

@@ -0,0 +1,394 @@
+# HELIX Instant — Multiplayer Logic (the declarative DSL) reference
+
+This is the **reference** for HELIX's server-authoritative multiplayer game logic. You declare game logic as **data** in
+your world's `helix.json` under the `multiplayer` block; a platform-owned room interprets it every tick. **You write no
+server code.** Pair this with a **template** from `multiplayer-world.md` (the hub) — the template shows a complete working
+world; this doc is the grammar each template links into. New to multiplayer? Read `multiplayer-world.md` first.
+
+> This reference is lookup-shaped — skim to the section you need. Every construct here is what the platform actually
+> interprets (validated at publish). If you write a verb/op/event not listed here, publish rejects it with a did-you-mean.
+
+## Mental model — read once
+
+1. **The server is authoritative and platform-owned.** A generic room holds the shared state and runs your rules. Clients
+   send only their own input (position, ability casts, declared actions); the server makes every authoritative write.
+2. **You declare state + rules; the room runs them at a fixed 20 Hz tick.** Each tick: ingest client input → fire lifecycle
+   + timer events → integrate entity motion → recompute zones → **evaluate your rules in declared order** → drain the
+   cascade (effects that fired secondary events) → broadcast the diffed state to clients.
+3. **Rules are `when` (an event) → optional `if` (a condition) → `then` (effects).** Effects mutate declared state, which
+   syncs to every client automatically.
+4. **Clients render off the synced state.** Players are replicated for you (see the hangout template); your declared
+   `roomVars` / per-player `vars` / `entities` are read from `room.state`.
+5. **It must work single-player.** Guests/solo still run the world; gate any "needs 2 players" logic explicitly.
+
+---
+
+## 1. The `multiplayer` block
+
+Lives in `public/helix.json` (manifest `helixVersion: "0.3"`, with `maxPlayers > 1` and the `multiplayer` permission — see
+`multiplayer-world.md`). Every sub-key is optional; declare only what your world uses.
+
+```jsonc
+"multiplayer": {
+  "authoritative": true,          // keep true (the only model)
+  "minPlayers": 1,                // default 1; the world MUST work solo
+  "interestRadius": 30,           // advisory meters (reserved); optional
+  "uploadHz": 10,                 // client→server rate: 10 (default) | 20 (fast physics; then maxPlayers ≤ 12)
+  "state":   { "roomVars": {…}, "playerVars": {…} },   // §2 declared state
+  "entities": { "<kind>": {…} },  // §9 server- or client-hosted objects
+  "zones":   [ {…} ],             // §10 spatial volumes
+  "timers":  { "<name>": {…} },   // §11 countdowns
+  "states":  { "initial": "…", "phases": […] },        // §12 state machine
+  "events":  { "<name>": {…} },   // §13 server→client broadcasts
+  "actions": { "<name>": {…} },   // §14 client→server intents
+  "rules":   [ { "when": …, "if": …, "then": […] } ]   // §3 behavior
+}
+```
+
+---
+
+## 2. Declared state (`state.roomVars`, `state.playerVars`)
+
+`roomVars` exist once per room; `playerVars` are realized per connected player. Each entry is a typed var. Entities have
+their own `vars` (§9). A var declaration is a discriminated union on `type`:
+
+| `type` | Fields | Notes |
+|---|---|---|
+| `number` | `default` (req), `min?`, `max?`, `integer?` | `add`/`set` clamp to `[min,max]` if declared |
+| `string` | `default` (req), `maxLen?` (≤1024), `enum?` (≤64 values) | client-written strings are length-clamped + enum-checked |
+| `boolean` | `default` (req) | |
+| `vec3` | `default` (req): `[x,y,z]` | positions/points |
+| `ref` | `of: "player" \| "entity:<kind>"`, `default?: null` | holds a member id; unset reads as `""` |
+| `list` | `of: <elem>`, `maxLen` (req, ≤256) | bounded array; starts empty (§5) |
+| `counterMap` | `keys: string[]` (≤64) | string→number map; all keys start `0` (§5) |
+
+**List element (`of`)** is `"number" | "string" | "boolean"`, or `{ type:"ref", of:… }`, or a flat **record**:
+`{ type:"record", fields: { <name>: <recordField> } }` (≤8 fields). Record fields are scalar only — `number`/`string`/
+`boolean`/`vec3` (each with optional `default`) or `ref` (no nesting; no list-of-list).
+
+```jsonc
+"state": {
+  "roomVars":   { "score": {"type":"number","default":0}, "winner": {"type":"ref","of":"player"} },
+  "playerVars": { "team": {"type":"string","default":"none","enum":["red","blue","none"]},
+                  "hand": {"type":"list","maxLen":8,"of":{"type":"record","fields":{"card":{"type":"string"},"power":{"type":"number","default":0}}}} }
+}
+```
+
+**Reserved built-ins (read-only — don't redeclare):** players expose `position` (vec3), `connected` (bool), `active`
+(bool); the room exposes `phase` (string). Read them like any var (`self.position`, `room.phase`).
+
+---
+
+## 3. Rules — `when` / `if` / `then`
+
+```jsonc
+{ "when": { "on": "<event>", … }, "if": <expr>, "then": [ <effect>, … ] }
+```
+- `when` selects the trigger (§4). `if` is an optional boolean condition (§6); omitted = always. `then` is an ordered,
+  non-empty effect list (§8).
+- **Order matters:** rules evaluate in declared order; effects within a `then` apply in order; later rules see earlier
+  rules' writes (within the same tick).
+- **Cascade:** effects that fire secondary events (`transitionTo`→`stateEnter`/`stateExit`, `spawnEntity`→`entitySpawn`,
+  `destroyEntity`→`entityDestroy`, `takeover`/`requestOwnership`→`ownershipChanged`) queue and drain **breadth-first
+  after** the primary rules, bounded by `maxCascadeDepth` (16). Publish rejects cascades that could cycle. (`varReached`
+  is separate — it is edge-checked once at the **end** of the rule phase, not part of the cascade drain.)
+- Caps: `rules` ≤128, effects per `then` ≤16, `if` depth ≤8 / ≤64 nodes.
+
+---
+
+## 4. Events (`when.on`)
+
+| `on` | Params | Binds | Fires |
+|---|---|---|---|
+| `tick` | `everyN?` | — (room) | every N ticks (default 1) |
+| `playerJoin` / `playerLeave` | — | `self` = the player | once on join / on leave (after grace) |
+| `playerDisconnect` / `playerReconnect` | — | `self` | enters / resumes reconnection grace |
+| `zoneEnter` / `zoneExit` | `zone` | `self` = member; `source` = carrier (attached zones) | edge: once on cross in/out |
+| `zoneInside` | `zone` | `self`; `source` = carrier (attached zones) | every tick while inside |
+| `playerContact` | `radius` | `self`, `other` | once per pair entering `radius` (the tag primitive) |
+| `action` | `name` | `self` = actor | a client sent a declared action (args pre-validated); read `action.args.<x>` |
+| `stateEnter` / `stateExit` | `phase` | — (room) | on `transitionTo` in/out of a phase (cascade) |
+| `timerElapsed` | `timer` | `self` = the timer's key (if keyed) | a timer deadline passed |
+| `entitySpawn` / `entityDestroy` | `kind` | `self` = the entity | once on spawn / destroy |
+| `ownershipChanged` | `kind` | `self` = new owner, `source` = entity | on a successful ownership transfer |
+| `varReached` | `scope`("room"\|"self"\|"entity"), `kind?`, `var`, `cmp`, `value` | `self` = the member | edge: a watched var crosses a threshold (false→true) |
+
+`value` for `varReached` is a literal, or `{var:"…"}`, or `{ref:<ref>,var:"…"}` (a dynamic threshold).
+
+---
+
+## 5–8 are the value/effect language. §5 collections appear inline in §6/§8.
+
+## 6. Expressions (`if` conditions and value operands)
+
+A `HelixExpr` is one of:
+
+**Literals & reads**
+- `42`, `"red"`, `true` — literals · `{"vec3":[x,y,z]}` — vec3 literal
+- `{"var":"room.score"}` / `{"var":"self.team"}` / `{"var":"action.args.amount"}` — scalar read
+- `{"ref":<ref>,"var":"score"}` — read another member's var (or a record field), via a ref (§7)
+
+**Arithmetic** `{"op":"+"|"-"|"*"|"/","a":<expr>,"b":<expr>}` → number
+**Comparison** `{"op":"=="|"!="|"<"|"<="|">"|">=","a":…,"b":…}` → boolean. `==`/`!=` take same-typed scalars (no vec3); the ordering ops `<`/`<=`/`>`/`>=` require **numbers**.
+**Logical** `{"op":"and"|"or","of":[…]}` · `{"op":"not","of":<expr>}` → boolean
+**Distance** `{"op":"distance","a":<vec3>,"b":<vec3>}` → number
+
+**Leaf generators** `{"op":"playerCount"}` (active = connected, not eliminated) · `{"op":"random"}` (0..1) · `{"op":"now"}` (epoch seconds) ·
+`{"op":"timeInState"}` (s in phase) · `{"op":"randomPoint","min":[…],"max":[…]}` → vec3
+
+**Aggregate** over a population → number:
+```jsonc
+{ "op":"aggregate", "scope":"players"|"zone:<id>"|"entities:<kind>",
+  "agg":"count"|"sum"|"min"|"max"|"avg", "field":"<numberVar>", "where":<expr>, "as":"p" }
+```
+`count` needs no `field`; `where`/`as` are an optional filter (bind each candidate to `as`).
+
+**Timers** `{"op":"timerRemaining","timer":"round","key":<ref>?}` → seconds left (0 if inactive).
+
+**Collections** (operate on a `list`/`counterMap` var):
+- `{"op":"listLength","list":<lvalue>}` → number
+- `{"op":"listAt","list":<lvalue>,"index":<expr>,"field":"<f>"?}` → element (or record field); out-of-range → typed zero
+- `{"op":"count","map":<lvalue>,"key":"<k>"}` → counterMap value
+- `{"op":"listCount","list":<lvalue>,"as":"e","where":<expr>}` → number matching (O(maxLen))
+- `{"op":"listIndexOf","list":<lvalue>,"as":"e","where":<expr>}` → index or -1
+
+**Ownership / load**
+- `{"op":"controlledBy","entity":<ref>,"by":<ref>}` → boolean
+- `{"op":"hostLoad","of":<ref>}` → number of entities that player controls
+- `{"op":"sameRef","a":<ref>,"b":<ref>}` → boolean (identity; false if either unset)
+
+---
+
+## 7. Refs (`HelixRef`)
+
+A ref resolves to a live member (player or entity). Reading through a dangling/unset ref yields the typed zero (`0`/`""`/
+`false`); effects on a dangling ref are counted no-ops (not errors).
+
+- `"self"` / `"other"` / `"source"` — bound by the event (§4)
+- `{"var":"room.winner"}` — deref a `ref`-typed var
+- `{"op":"nearestPlayer","from":<vec3>}` / `{"op":"nearestEntity","from":<vec3>,"kind":"<k>"?}` → nearest member
+- `{"op":"controllerOf","entity":<ref>}` → the player controlling it (`""` = server/unowned)
+- `{"op":"leastLoadedPlayer","where":<expr>?,"as":"p"?}` → connected player controlling the fewest entities
+- `{"op":"listAt","list":<lvalue>,"index":<expr>}` → a ref from a list-of-ref
+- `{"op":"aggregate","scope":…,"agg":"argmax"|"argmin","field":"<f>","where":?,"as":?}` → the member with the max/min field
+
+**Lvalues (effect targets):** `"room.<var>"`, `"self.<var>"`, or `{"ref":<ref>,"var":"<var>"}` (write through a ref — the
+pattern for cross-player writes, subject to the firewall in §17).
+
+---
+
+## 8. Effects (`then`)
+
+**State** `{"do":"add","target":<lv>,"by":<expr>}` · `{"do":"set","target":<lv>,"to":<expr>}` ·
+`{"do":"setRef","target":<lv>,"to":<ref>|null}`
+**Movement** `{"do":"teleport"|"respawn","player":<ref>,"to":<vec3>}` (server-authoritative; re-anchors the move gate)
+**Loops**
+- `{"do":"forEachPlayer","as":"p","where":<expr>?,"includeEliminated":false?,"then":[…]}`
+- `{"do":"forEachEntity","kind":"<k>","as":"e","where":?,"then":[…]}`
+- `{"do":"forEachInList","list":<lv>,"as":"e","where":?,"then":[…]}` (no nesting; don't structurally mutate the list you iterate)
+
+**Broadcast** `{"do":"broadcast","event":"<name>","to":"all"|<ref>|{"team":"<playerVar>=<value>"},"payload":{…}}` (§13)
+**State machine** `{"do":"transitionTo","phase":"<p>"}` · `{"do":"startTimer","timer":"<t>","seconds":<expr>,"key":<ref>?}` ·
+`{"do":"cancelTimer","timer":"<t>","key":<ref>?}`
+**Entities** `{"do":"spawnEntity","kind":"<k>","at":<vec3>,"vars":{…}?,"bind":"spawned"?}` ·
+`{"do":"destroyEntity","entity":<ref>}`
+**Ownership** `{"do":"requestOwnership"|"takeover","entity":<ref>,"to":<ref>|null}` (§9: `requestOwnership` needs `transferPolicy` ∈ {`request`,`takeover`}; `takeover` needs `transferPolicy:"takeover"`)
+**Collections**
+- `{"do":"append","target":<lv>,"value":<expr|ref|record>}` · `{"do":"clear","target":<lv>}`
+- `{"do":"addCount","target":<lv>,"key":"<k>","by":<expr>}`
+- `{"do":"removeAt","target":<lv>,"index":<expr>}` · `{"do":"removeWhere","target":<lv>,"as":"e","where":<expr>}`
+- `{"do":"setField","target":<lv>?,"index":<expr>?,"as":"e"?,"field":"<f>","to":<expr|ref>}` (by index, or on a `forEachInList` element)
+
+**Turns & elimination** `{"do":"advanceTurn","order":<lv list-of-ref>,"index":<lv number>}` (skips inactive, wraps) ·
+`{"do":"eliminate","player":<ref>}` / `{"do":"revive","player":<ref>}` (eliminated = `active:false`, still connected/spectating)
+
+---
+
+## 9. Entities
+
+Server- or client-hosted objects beyond players. Declare per kind under `entities`. Spawn with the `spawnEntity` effect.
+
+```jsonc
+"entities": {
+  "coin": { "vars": { "value": {"type":"number","default":1} } },           // server-authoritative (default)
+  "pet":  { "authority":"owner", "maxSpeed":12, "ownerLifecycle":"migrateToServer",
+            "motion": {"type":"seek","target":"owner","speed":6} }
+}
+```
+
+| Field | Values | Meaning |
+|---|---|---|
+| `vars` | var decls (§2) | per-entity state |
+| `authority` | `"server"` (default) \| `"owner"` | who simulates it (see below) |
+| `maxSpeed` | number | **required for `owner`**; m/s plausibility gate on uploads |
+| `motion` | `static`\|`linear`\|`orbit`\|`seek`\|`waypoints` | server-deterministic kinematics |
+| `transferPolicy` | `"fixed"` (default) \| `"request"` \| `"takeover"` | gates `requestOwnership`/`takeover` |
+| `ownerLifecycle` | `despawnWithOwner` (default) \| `persist` \| `migrateToServer` \| `hostMigrate` | what happens when the host leaves |
+| `shared` | boolean | game-owned, host-migrated (needs `authority:"owner"` + `ownerLifecycle:"hostMigrate"`) |
+| `idleTimeout` | seconds | a hostless shared entity despawns after this |
+| `zone` | attached zone | an entity-attached spatial volume (§10) |
+| `physics` | physics block | opt-in client-simulated **dynamic rigid body** (colliding) — needs `authority:"owner"`; see "Networked physics" below |
+| `rejoinOnRelease` | `nearestPoint` (default) \| `timeIndex` \| `seekBack` | for a HYBRID (physics + non-static `motion`): how it re-bases its server path when released |
+
+**Motion** types: `{"type":"linear","velocity":[…]}`, `{"type":"orbit","center":[…],"radius":r,"speed":rad/s}` (circle in the XZ plane),
+`{"type":"seek","target":"<refVarName>","speed":s}` (homes toward the member held in that ref var),
+`{"type":"waypoints","points":[[…],…],"speed":s,"loop":true?}`.
+
+### Authority — **declare `motion` first**
+- **`authority:"server"` (default):** deterministic, cheat-proof, never freezes. Use server `motion` (straight-line `seek`,
+  `waypoints`, `orbit`) for anything the server can compute. **This is the default; reach for it first.**
+- **`authority:"owner"`:** a client simulates the entity and uploads its transform; the server sanity-validates + relays.
+  This is the **escape hatch** for behavior the server can't express (real pathfinding, client physics, complex AI) — it is
+  spoofable by design. Requires `maxSpeed`. Single-owner (`ownerLifecycle`) or `shared:true` (re-elects a host on leave).
+
+### Client side — render + host entities with `EntityScene`
+Entities reach the client through `EntityScene` (from `@helix/humanoid-character`). You give it a `build(kind,id)` per kind;
+it interpolates server/remote entities and, for entities you own (`controller === sessionId`), runs your `motion` fn and
+uploads. **Never call `room.uploadEntity` directly** — register through `EntityScene`.
+
+```ts
+const scene = new EntityScene({
+  room,
+  build: (kind, id) => ({ object3d: makeMesh(kind), onUpdate: (e, dt) => {/* render off e.vars */} }),
+  maxSpeed: { pet: 12 },                 // MUST mirror the DSL maxSpeed (reconcile clamp reads this)
+  motion: { pet: (e, dt, ctx) => ctx.seekNearest(6, 1) },  // only for entities YOU host
+});
+// each frame: scene.update(dt)
+```
+
+### Networked physics — colliding dynamic bodies
+Add a `physics` block to an `authority:"owner"` kind to make it a **client-simulated dynamic rigid body** (a ball, a
+puck, a car) that collides with world geometry, players, and other physics bodies. Absent ⇒ today's kinematic
+position-only path. The owner runs the Rapier sim locally + uploads pos/velocity/orientation; remotes reproduce it.
+
+```jsonc
+"ball": { "authority":"owner", "maxSpeed":18, "transferPolicy":"takeover",
+  "physics": {
+    "bodyType":"dynamic",
+    "shape": {"type":"sphere","radius":0.6},     // or {"type":"box","halfExtents":[x,y,z]} / {"type":"capsule","halfHeight":h,"radius":r}
+    "mass":1, "restitution":0.6, "friction":0.6, // optional too: linearDamping, angularDamping, maxAngularSpeed, collidesWith:["<kind>"]
+    "claimOnContact":true, "revertOnRest":true } }
+```
+
+Field defaults: `mass` 1, `restitution` 0.2, `friction` 0.5, `linearDamping` 0, `angularDamping` 0.05,
+`maxAngularSpeed` derived from `maxSpeed`. `revertOnRest` defaults **off** for a `fixed` body, **on** for a `shared` one.
+
+**The arbitration matrix — each flag is opt-in and composes per kind:**
+- **Base (no flags)** — `physics` + `authority:"owner"` + `transferPolicy:"fixed"` (the default): ONE client hosts +
+  simulates the body for its whole life and it **never transfers**; remotes see a kinematic proxy at the owner's stream
+  (collision response is favor-owner). Pair with `shared:true` + `ownerLifecycle:"hostMigrate"` for a **game-owned**
+  body the server re-elects a host for on leave (a host-migrated physics object, still no per-contact handoff).
+- **+ `claimOnContact:true`** — authority-transfer: the server hands control to whoever touches the body (usually with
+  `revertOnRest:true` to release it to the server at rest). **Requires `transferPolicy:"takeover"`.** For ONE contested,
+  un-owned object (ball/puck) — the `physics-football` template.
+- **+ `dualSimOnContact:true`** — dual-sim: each player keeps their OWN body; on contact both clients simulate both and
+  reconcile favor-local. **Requires `transferPolicy:"fixed"`.** For player-driven bodies (bumper cars/derby) — the
+  `physics-bumper` template.
+
+Cross-field rules (publish enforces): a `physics` block **requires `authority:"owner"`**; `claimOnContact` ⇒
+`transferPolicy:"takeover"`; `dualSimOnContact` ⇒ `transferPolicy:"fixed"`; `collidesWith` names declared kinds. A
+**hybrid** (physics + a non-static `motion`) re-bases its server path on release via `rejoinOnRelease`.
+
+**Client:** physics kinds run through `EntityScene` too — its `build` returns a `DynamicBody` (set as `physics` on the
+handle) created against one shared `SharedPhysicsWorld` you `step(dt)` each frame; for dual-sim you also bind a
+`DualSimController`. Mirror `maxSpeed` (and the shape) between the DSL and the client. The templates show the full
+wiring. Fast/twitchy physics may opt the room up to `uploadHz:20` (§1) — which caps `maxPlayers` at 12. Cap:
+**`physicsKinds` ≤ 8** per world.
+
+---
+
+## 10. Zones
+
+Static volumes (`zones: []`) or entity-attached (`entities.<k>.zone`). Drive `zoneEnter`/`zoneExit`/`zoneInside`.
+
+```jsonc
+"zones": [ { "id":"base", "shape":"box", "center":[0,0,0], "size":[10,4,10],
+             "tracks":"players", "requireDwell":0, "debounce":0 } ]
+```
+`shape`: `"box"` (`center` + full `size` `[x,y,z]` — full dimensions, **not** half-extents; note this differs from a `physics.shape` box, which uses `halfExtents`) or `"sphere"` (`center`+`radius`). `tracks`: `"players"` (default) or
+`"entity:<kind>"`. `requireDwell` (s before a fresh enter fires) / `debounce` (s an exit suppresses re-enter) optional.
+Attached zones add `offset` and omit `id`. Caps: `zones` ≤64, extent ≤10000.
+
+## 11. Timers
+
+```jsonc
+"timers": { "round": {}, "cooldown": { "keyed":"player" } }
+```
+Room-scoped by default; `keyed:"player"` / `keyed:"entity:<kind>"` makes per-member instances (`startTimer`/`timerElapsed`
+then need/bind a `key`). Arm with `startTimer` (`seconds` floors at 0.05). Read `timerRemaining`. Caps: ≤32.
+
+## 12. State machine
+
+```jsonc
+"states": { "initial":"lobby", "phases":["lobby","play","results"],
+            "joinPolicy": { "play": { "joinable":false, "onLateJoin":[ /* spectate setup */ ] } } }
+```
+`room.phase` is the current phase; change it with `transitionTo` (fires `stateExit`→`stateEnter`). `joinPolicy.<phase>`
+controls late-join: `joinable:false` runs `onLateJoin` instead of the normal `playerJoin` rules (spectate-until-next-round).
+Caps: phases ≤32, cascade depth ≤16.
+
+## 13. Broadcast events (server → client)
+
+```jsonc
+"events": { "scored": { "payload": { "by": {"type":"ref","of":"player"}, "points": {"type":"number"} } } }
+```
+Fire with the `broadcast` effect; clients receive via `room.onMessage("scored", cb)`. Payload field types: scalars, `ref`,
+or a **collection snapshot** (`{type:"list",of:…}` / `{type:"counterMap",keys:…}` mirroring a declared var — e.g. a
+leaderboard). `to`: `"all"`, a ref, or `{team:"<playerVar>=<value>"}` (matched stringified — `<value>` is compared as a string). Caps: events ≤64, fields ≤16.
+
+## 14. Actions (client → server)
+
+```jsonc
+"actions": { "claimHit": { "args": { "target": {"type":"ref","of":"player"} } } }
+```
+Clients call `room.sendAction("claimHit", { target: id })`; the server validates args (types/bounds/liveness) then fires
+`{when:{on:"action",name:"claimHit"}}` with `self` = the actor and `action.args.<name>` readable. Arg types: scalars or
+`ref`. Caps: actions ≤64, args ≤16. **Actions are the cheat-resistant input path** (validated server-side) — prefer them
+over owner-entity tricks for anything that affects other players.
+
+---
+
+## 15. Consuming declared state on the client
+
+The SDK gives you a `HelixRoom` (`Helix.multiplayer.joinRoom()`; see `multiplayer-world.md`). Read declared state off
+`room.state`; you never write it directly — you `sendState` (your own avatar), `sendAction`, `sendAbility`, or host entities
+via `EntityScene`.
+
+- `room.state.roomVars["score"]`, `room.state.players[id].vars["team"]`, `room.state.entities[id]` (`.vars`/`.position`/`.controller`).
+- `room.onStateChange(cb)` · `room.onAdd("entities", cb)` / `onRemove` · `room.onMessage("<event>", cb)` (broadcasts).
+- `room.sendAction(name, args)` · `room.sendAbility(id, active)` · `room.sendState(input)` (your avatar, ~10 Hz, throttled for you).
+
+**Footguns (every template handles these — copy them):** `room.state.players`/`entities` are live Colyseus maps mutated in
+place → **copy values you cache** (don't alias). **Skip your own `sessionId`** when spawning remotes. **Guard
+`roomVars`/`vars` until the first patch** (empty on frame 0). **Mirror an entity's `maxSpeed`** between the DSL and the
+`EntityScene` options. Let `EntityScene`/the SDK handle source-time (`posT`) interpolation.
+
+---
+
+## 16. Limits — stay inside the caps (publish enforces them)
+
+The validator rejects an over-cap config with a precise message. Key caps: `roomVars`/`playerVars` 64 · `rules` 128 ·
+effects/rule 16 · `if` depth 8 / nodes 64 · `entityKinds` 32 · `entitiesPerKind` 256 · `entityVars` 64 · `zones` 64 ·
+`timers` 32 · `phases` 32 · `events`/`actions` 64 · `listMaxLen` 256 · `counterKeys` 64 · `recordFields` 8 ·
+`stringMaxLen` 1024 · `physicsKinds` 8 (§9) · `enum` values 64 · `joinPolicy` effects 16. Var **names** are identifiers
+≤32 chars. Also: `uploadHz:20` requires `maxPlayers ≤ 12`, and the platform caps **concurrent players per room** at 24
+(extras spill into a fresh instance) regardless of `maxPlayers`. There is also a **per-tick evaluation budget**
+(`tickNodeBudget` 100000) computed statically from your rules × loop fan-out × cascade depth — a too-large `forEach`
+or deeply-nested expensive ops (`aggregate`/`nearest*`) fails publish. Simplify or spread work across ticks.
+
+## 17. Security — the cross-player write firewall
+
+Clients are not trusted. `owner`-authority entity uploads are sanity-validated, not cheat-proof. Publish **statically blocks**
+owner-entity logic from any cross-player **write OR read** — no `set`/`add`/`teleport`/`respawn`/`destroyEntity`/collection
+mutation/ownership verb/keyed timer/`broadcast` aimed at another member, and no dereferencing a client-supplied ref to
+*read* another member's var — that's a publish error, not a runtime no-op. For anything that affects *other*
+players, use a declared **`action`** (server-validated) — e.g. the `claimHit` pattern: validate distance + cooldown in the
+rule, then write to the target via `{ref: action.args.target, var: "health"}`.
+
+## 18. Where Tier-2 stops (use the escape hatch or a different layer)
+
+Out of scope for the declarative DSL: **cheat-proof collision/raycast/hitscan** and **navmesh pathfinding / autonomous AI**
+(straight-line `seek` is in; *navigating around obstacles* and *deciding* are not — run them on an `owner` entity
+client-side). **Cross-session persistence** (saved currency/progression/inventory across sessions) is a separate storage
+layer, not here — worlds reset per room. **Networked physics** (colliding rigid bodies) IS supported — see §9 "Networked
+physics — colliding dynamic bodies." Nested collections / free-form JSON are intentionally unsupported (flat records only).

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

@@ -0,0 +1,123 @@
+# Multiplayer template — `chrono-orchard`
+
+**What it is.** Plant crops; they **ripen over real time**; harvest a mature one for points (worth more in good
+weather); water to hurry them along. A `season` timer flips the weather on a random cadence. **Capability: the TIME
+axis** — the `{op:now}` wall-clock, **dynamic timer durations**, growth-over-time, and cooldowns. Use this for
+farming, idle/incremental, day-cycle, anything where elapsed real time matters. Lifted from the verified
+`multiplayer-chrono-orchard` world.
+
+> A character world (presence) **plus** time logic. Grammar: `read_doc({ name: "multiplayer-logic" })` §6
+> (`{op:now}`), §11 (timers), §9 (entities).
+
+## 1. DSL used
+
+- **`{op:now}`** (§6) — epoch **seconds**. Stamp `plantedAt: {op:now}` when a crop spawns; compute age as
+  `now - plantedAt`; gate the harvest on `age >= 15`; implement a cooldown as `now - lastWaterAt >= 3`.
+- **Dynamic timers** (§11) — `startTimer`'s `seconds` is an **expression** (`8 + random*8`), and the `season`
+  timer **re-arms itself** on `timerElapsed` for a recurring, jittered cadence.
+- **Entities** (§9) — `crop` (`plantedAt`, `growth`) with an attached harvest zone; a `tick everyN:5` rule ages
+  every crop (`set growth = now - plantedAt`).
+- **Broadcast events** (§13) — `weatherChanged` / `watered`.
+- **Actions** (§14) — `plant` (spawns a crop stamped with `now`); `water` (cooldown-gated; backdates `plantedAt`
+  to accelerate growth).
+
+## 2. The manifest — `public/helix.json`
+
+```json
+{
+  "helixVersion": "0.3",
+  "title": "Chrono-Orchard",
+  "slug": "chrono-orchard",
+  "entry": "index.html",
+  "maxPlayers": 8,
+  "permissions": ["auth.profile", "multiplayer"],
+  "multiplayer": {
+    "authoritative": true,
+    "state": {
+      "roomVars": { "reward": { "type": "number", "default": 1 } },
+      "playerVars": { "score": { "type": "number", "default": 0 }, "lastWaterAt": { "type": "number", "default": 0 } }
+    },
+    "entities": {
+      "crop": {
+        "vars": { "plantedAt": { "type": "number", "default": 0 }, "growth": { "type": "number", "default": 0 } },
+        "zone": { "shape": "sphere", "radius": 1.2 }
+      }
+    },
+    "states": { "initial": "day", "phases": ["day"], "joinPolicy": { "day": { "joinable": true } } },
+    "timers": { "season": {} },
+    "actions": { "plant": {}, "water": {} },
+    "events": {
+      "weatherChanged": { "payload": { "reward": { "type": "number" } } },
+      "watered": { "payload": {} }
+    },
+    "rules": [
+      { "when": { "on": "action", "name": "plant" }, "then": [{ "do": "spawnEntity", "kind": "crop", "at": { "var": "self.position" }, "vars": { "plantedAt": { "op": "now" } } }] },
+      { "when": { "on": "tick", "everyN": 5 }, "then": [{ "do": "forEachEntity", "kind": "crop", "as": "c", "then": [{ "do": "set", "target": { "ref": "c", "var": "growth" }, "to": { "op": "-", "a": { "op": "now" }, "b": { "ref": "c", "var": "plantedAt" } } }] }] },
+      {
+        "when": { "on": "zoneEnter", "zone": "crop" },
+        "if": { "op": ">=", "a": { "op": "-", "a": { "op": "now" }, "b": { "ref": "source", "var": "plantedAt" } }, "b": 15 },
+        "then": [{ "do": "add", "target": "self.score", "by": { "var": "room.reward" } }, { "do": "destroyEntity", "entity": "source" }]
+      },
+      {
+        "when": { "on": "action", "name": "water" },
+        "if": { "op": ">=", "a": { "op": "-", "a": { "op": "now" }, "b": { "var": "self.lastWaterAt" } }, "b": 3 },
+        "then": [
+          { "do": "set", "target": "self.lastWaterAt", "to": { "op": "now" } },
+          { "do": "forEachEntity", "kind": "crop", "as": "c", "then": [{ "do": "set", "target": { "ref": "c", "var": "plantedAt" }, "to": { "op": "-", "a": { "ref": "c", "var": "plantedAt" }, "b": 5 } }] },
+          { "do": "broadcast", "event": "watered", "to": "all", "payload": {} }
+        ]
+      },
+      { "when": { "on": "stateEnter", "phase": "day" }, "then": [{ "do": "startTimer", "timer": "season", "seconds": { "op": "+", "a": 8, "b": { "op": "*", "a": { "op": "random" }, "b": 8 } } }] },
+      {
+        "when": { "on": "timerElapsed", "timer": "season" },
+        "then": [
+          { "do": "set", "target": "room.reward", "to": { "op": "-", "a": 3, "b": { "var": "room.reward" } } },
+          { "do": "startTimer", "timer": "season", "seconds": { "op": "+", "a": 8, "b": { "op": "*", "a": { "op": "random" }, "b": 8 } } },
+          { "do": "broadcast", "event": "weatherChanged", "to": "all", "payload": { "reward": { "var": "room.reward" } } }
+        ]
+      }
+    ]
+  },
+  "supportsMobile": true,
+  "contentRating": "everyone",
+  "systems": { "humanoid-character": "^0.2" }
+}
+```
+
+`{op:now}` is the same clock on every rule, so `now - plantedAt` is a true elapsed-seconds age. `water` backdates
+`plantedAt` (subtracts 5 s) to *fast-forward* growth — a neat trick. `startTimer.seconds` and the cooldown
+thresholds are all plain expressions. `season` re-arms itself, so the weather toggles forever on a jittered timer.
+
+## 3. The client — `src/main.ts` (delta from `hangout`)
+
+Presence + a crop render-proxy (server entities, like `collect-a-thon`) **scaled by `growth`**, plus the two
+actions and the weather banner:
+
+```ts
+const crops = new Map<string, { mesh: THREE.Object3D; state: EntityState }>();
+if (room) {
+  room.onAdd('entities', (e, id) => { const m = makeSprout(); scene.add(m); crops.set(id, { mesh: m, state: e }); });
+  room.onRemove('entities', (_e, id) => { const c = crops.get(id); if (c) { scene.remove(c.mesh); crops.delete(id); } });
+}
+
+// frame loop (inside `if (room)`): grow each crop visually from its synced `growth` (clamped to a ripe size at ~15s)
+for (const [, c] of crops) {
+  if (c.state.position) c.mesh.position.set(c.state.position.x, c.state.position.y, c.state.position.z);
+  const g = Math.min(1, Number((c.state.vars as Record<string, unknown>)?.growth ?? 0) / 15);
+  c.mesh.scale.setScalar(0.2 + 0.8 * g);                 // sprout → ripe
+}
+
+addEventListener('keydown', (e) => {
+  if (e.key === 'e') room.sendAction('plant');
+  else if (e.key === 'q') room.sendAction('water');       // server enforces the 3s cooldown
+});
+room.onMessage('weatherChanged', (m) => showBanner(Number(m.reward) > 1 ? '☀ Bumper crop! (reward up)' : '☁ Lean season'));
+room.onMessage('watered', () => showBanner('💧 Watered — crops sped up'));
+```
+
+**Footguns:** time is **server** time (`{op:now}`) — never compute elapsed from a client clock; read each crop's
+live `growth` per frame; the `water` cooldown is server-enforced (the client just sends the intent).
+
+## 4. Build, validate, publish
+
+`npm install` → `helix install` → `npm run build` → `validate_world` on `dist/` → `whoami` → `publish_world`.