@genex-ai/cli-demo 0.8.0 → 0.11.0

package/templates/skills/genex-threejs-multiplayer/SKILL.md

@@ -1,22 +1,35 @@
 ---
 name: genex-threejs-multiplayer
-description: Implement realtime multiplayer for Genex Three.js games with `@genex-ai/multiplayer`. Use whenever 2+ players share a world — movement sync, shared scores/rounds, shots/emotes, presence, and persistent worlds. MANDATORY whenever a game has multiplayer: load this before writing any networking code.
+description: Realtime multiplayer for Genex Three.js games with `@genex-ai/multiplayer` — a relay whose SDK auto-smooths remote players AND shared objects (you do NOT write interpolation). Use whenever 2+ players share a world: movement sync, a shared ball/NPC via objects + ownership, host-authoritative scores/waves, shots/emotes, presence. MANDATORY for any multiplayer game — load before writing networking code.
 ---
 
 # Genex Three.js Multiplayer
 
-`@genex-ai/multiplayer` is a **relay**: whatever you write to `me` or `shared` is
-synced to everyone; everything else stays local. The server runs **no physics, no
-prediction, and no interpolation** — you run your own game logic and add your own
-smoothing. This skill covers the API, the smoothing you must add yourself
-(interpolation + prediction), config wiring, and persistent worlds.
+`@genex-ai/multiplayer` is a **relay with a smart client**: whatever you write to `me`,
+`shared`, or an `object` is synced to everyone; everything else stays local. The **server**
+runs no physics and no game logic — but it *does* enforce two generic invariants so the naive
+path is the correct one: **exactly one smoother** (the SDK interpolates remote players and
+objects for you) and **exactly one owner/host** (server-arbitrated). You read a remote player
+or a shared object and it is already smooth; you never fight over who simulates the ball.
 
-**This skill is mandatory for any multiplayer game.** Load it before you write a
-single line of networking code. Naïvely snapping every remote player to their last
-raw network position looks terrible — interpolation/prediction are not optional polish.
+**This skill is mandatory for any multiplayer game. Load it before you write a single line of
+networking code.** The mistakes below are what make a multiplayer game stutter — they are the
+whole reason this skill exists.
 
-Read [references/realtime-patterns.md](references/realtime-patterns.md) for the
-copy-paste `RemoteInterpolator` + local-prediction helpers and the persistence/config code.
+## Two rules that decide whether it feels good
+
+1. **Do NOT write your own interpolation/smoothing.** The SDK already smooths remote players
+   *and* objects. Read `players.get(id).state` / `objects.get(id).state` and draw them directly.
+   Buffering `state` and lerping it yourself stacks a second smoother and adds ~100 ms of lag —
+   the #1 cause of a "laggy/stuttery" game here. Drawing `state` **is** the smooth path.
+2. **Render YOURSELF (and objects you own) from your own local object, live.** Your input
+   mutates a local object; you draw yourself from it every frame (zero latency). Never draw
+   yourself from `players.get(room.id).state` — that's the network echo, round-trip-delayed.
+
+Read [references/realtime-patterns.md](references/realtime-patterns.md) for the complete movement
+example, the shared-object/ball code, rotation, and host usage. Read
+[references/genre-recipes.md](references/genre-recipes.md) for ready-made per-genre setups
+(sports/ball, shooter, co-op with host-simulated enemies) — pick the one matching the game.
 
 ## Install
 
@@ -24,144 +37,224 @@ copy-paste `RemoteInterpolator` + local-prediction helpers and the persistence/c
 npm i @genex-ai/multiplayer
 ```
 
+`objects` and `host` need `@genex-ai/multiplayer` **≥ 0.4.0**.
+
 ## Connect
 
 Pick your own per-player state shape (any JSON). `room` is the **project slug**
 (printed by `genex init`) — same id = same room, different ids are fully isolated.
 
+**Joining requires a signed-in identity — the relay rejects joins without one.**
+Load the `genex-threejs-embed-auth` skill first (it sets up `initEmbed(...)`),
+then gate `connect()` on `waitForAuth()`:
+
 ```ts
 import { connect } from "@genex-ai/multiplayer";
+import { waitForAuth, getColyseusAuth } from "@genex-ai/embed-sdk";
 
-type State = { x: number; z: number; yaw: number };  // YOUR per-player state
+type State = { x: number; z: number; q: number[] };  // YOUR per-player state (rotation as quaternion)
 
+const { user } = await waitForAuth();  // identity gate — rejects if the session is blocked
 const room = await connect<State>({
-  url: GENEX.colyseusUrl, // e.g. "wss://demo-colyseus.glotech.world" — see config wiring below
-  room: GENEX.slug,       // the project slug — everyone with this id shares a room
-  name: "ada",            // optional display name
+  url: GENEX.colyseusUrl,     // e.g. "wss://demo-colyseus.glotech.world" — see config wiring below
+  room: GENEX.slug,           // the project slug — everyone with this id shares a room
+  name: user.name,            // display name — the server prefers the verified identity's name
+  auth: getColyseusAuth()!,   // REQUIRED — tokenless joins are rejected. Read fresh each connect; NEVER log it.
 });
 ```
 
+## Which channel for which data
+
+**This table is the most important thing in this skill.** Every piece of networked state is one
+of five kinds — put each on its channel and the game just works:
+
+| What you're syncing | Channel | Who writes it |
+| --- | --- | --- |
+| Your own avatar (position, rotation, anim) | `me.set` → others read `players` | you (each player their own) |
+| A moving thing nobody owns (**ball**, puck, NPC) | `objects` (claim + set) | the one current **owner** |
+| Slow agreed facts (score, round, wave, seed) | `shared` | the **host** (`isHost`) |
+| One-off actions (shot, emote, hit, chat) | `send` + `on` | whoever did it |
+| Discrete per-player values (hp, ammo, flags) | in `me.set`, read via `stateRaw` | you |
+
+Getting the channel right is the whole game. A ball on `shared` stutters (not smoothed) and
+fights (many writers). A ball on `objects` glides and has one owner. That's the difference.
+
 ## API surface (exact — do not invent methods)
 
 - `room.id` — your own session id.
-- `room.me.set(state)` — publish your state. **Replaces it wholesale** (send the full
-  object, not a partial). Call on a **fixed 10–20 Hz tick**, never per render frame —
-  one `set` = one network message.
-- `room.players` — a **fresh `Map` each read**, and it **includes you**. Skip yourself
-  with `if (id === room.id) continue;`. Each value is `{ id, name, state }`.
-- `room.shared.get(key)` / `room.shared.set(key, value)` / `room.shared.keys()` —
-  a key/value store (any JSON) synced to everyone. Use for world state, scores, round.
-- `room.on(event, cb)` → returns an **unsubscribe** function. Events: `'join'` /
-  `'change'` `(id, state)` (both also fire for **you** on connect — filter `id === room.id`),
-  `'leave'` `(id)`, `'shared'` `(key, value)`, and any custom event name from `send`.
-- `room.send(type, payload)` — fire-and-forget to all **other** clients, not stored in
-  state. Use for shots, emotes, chat, pings.
-- `room.leave()` — leave the room.
+- `room.me.set(state)` — publish your state, **replaces it wholesale**. Fixed **10–20 Hz tick**,
+  never per frame.
+- `room.players` — fresh `Map` each read, **includes you** (skip `id === room.id`). Each value is
+  `{ id, name, state, stateRaw }`: `state` is auto-smoothed (remotes) / live (you); `stateRaw` is
+  the raw latest (hit-tests, discrete values).
+- `room.objects` — shared objects nobody owns until claimed (a ball, an NPC):
+  - `claim(id)` — take ownership (last claim wins; call on kick/contact).
+  - `set(id, state)` — publish it (only lands while you own it; full flat object each call).
+  - `get(id)` → `{ id, owner, isMine, state, stateRaw }` or `undefined`. `state` is auto-smoothed
+    (or live if `isMine`); `stateRaw` is the raw latest.
+  - `release(id)` — give up ownership. `remove(id)` — destroy it (for transient bullets/pickups).
+  - `ids()` — all object ids seen.
+- `room.isHost` / `room.host` — you are (or who is) the elected authority. Use to pick the single
+  writer of `shared` scores/rounds and the single simulator of host-owned objects. Settles within
+  the first patch after connect — read in your loop / react to `on('host')`, not once.
+- `room.shared.get/set/keys` — key/value store (any JSON) for **slow agreed facts only**.
+- `room.on(event, cb)` → unsubscribe fn. Events: `'join'`/`'change'` `(id, state)` (also fire for
+  you), `'leave'` `(id)`, `'shared'` `(key, value)`, `'object'` `(id)` (ownership handoff),
+  `'host'` `(id)`, and any custom `send` name.
+- `room.send(type, payload)` — fire-and-forget to all **other** clients. **It never echoes to
+  you**, so apply your own action's local effect directly (draw your own tracer at fire time),
+  not inside `on(...)`. `room.leave()`.
 
 ## The loop you must build (input → local → tick → render)
 
 1. **Input mutates a local object only** (`me.x += …`). Never network on keypress.
-2. **A fixed tick publishes it:** `setInterval(() => room.me.set(me), 66)` (~15 Hz).
-3. **Render at your own framerate**, drawing:
-   - **yourself** from your *local predicted* state (zero latency — never from the
-     echoed server copy of you), and
-   - **every other player** through an **interpolator** (render ~100 ms in the past and
-     lerp between their last two snapshots) — never snap to raw network state.
+2. **A fixed tick publishes it:** `setInterval(() => room.me.set(me), 66)` (~15 Hz). If you own an
+   object, `objects.set` it in the same tick.
+3. **Render at your own framerate:** yourself from your *local* object; every other player from
+   `players.get(id).state` directly (already smoothed); every object from `objects.get(id).state`.
 4. **Create-or-reuse one mesh per id**; remove a player's mesh on `'leave'`.
 
-See [references/realtime-patterns.md](references/realtime-patterns.md) for the ready-made
-`RemoteInterpolator` helper and a complete movement example.
+## Rotation: sync a quaternion, not an angle
 
-## Smoothness is human-tested — you cannot see it
+Send rotation as a 4-number quaternion `q: mesh.quaternion.toArray()`; on the remote do
+`mesh.quaternion.fromArray(p.state.q)`. A scalar `yaw` is lerped linearly, so a heading crossing
+±π spins the long way. This applies to `objects` state too — keep object fields **flat**
+(top-level numbers + a 4-number quaternion smooth; nested objects snap).
 
-Lag, stutter, and jitter are *motion over time*. A screenshot is one frozen instant, so
-**you cannot tell from a screenshot (or any still capture) whether remote movement feels
-smooth.** Don't try. Trying to "verify smoothness" from captures leads to blind parameter
-tuning, regressions, and reverts.
+## Smoothed vs raw — `state` vs `stateRaw`
 
-Your job is bounded:
+`state` is smoothed and rendered slightly in the past (that's what makes motion glide). `stateRaw`
+is the newest value with no smoothing. **Draw** from `state`; **test** against `stateRaw` — hit
+detection, "am I close enough to kick", pickups, and any discrete number (hp, ammo, animation id,
+a 0/1 flag) that must not arrive fractional. This holds for both players and objects.
 
-1. **Use the reference `RemoteInterpolator` as written.** Render-delay + lerp between the
-   last two snapshots, with a clamp (no extrapolation). Don't hand-roll your own smoother.
-2. **Verify it *runs*, not that it *feels good*:** two clients, two distinct meshes, both
-   move, no console errors, each player sees the other. That's all a capture can prove.
-3. **Then hand the feel off to the human.** Say plainly: *"Multiplayer smoothness depends on
-   your network and can only be felt by a person — open it in two tabs or with a friend and
-   tell me how it feels."* Stop there; don't keep tuning on speculation.
+## Shared objects (the ball, the NPC) — use `objects`, never `shared`
 
-**Do NOT add velocity extrapolation, "keep gliding," dead-reckoning, or prediction for
-*remote* players** until a human reports a specific symptom. The reference deliberately
-clamps instead of extrapolating — extrapolation overshoots on turns and looks worse, which
-is exactly the trap to avoid.
+A ball belongs to no player. Put it on `objects`: exactly one client owns it at a time (the SDK +
+relay enforce it), the owner simulates it, and everyone else reads it auto-smoothed — on the same
+interpolation as a player. Ownership survives the owner leaving (reassigned to the host).
 
-### When the human reports a problem, match the symptom (don't guess)
+```ts
+if (iKickedIt) room.objects.claim("ball");          // become the owner on contact
+
+if (room.objects.get("ball")?.isMine) {
+  room.objects.set("ball", stepBallPhysics());       // only the owner's writes land
+}
+const ball = room.objects.get("ball");
+if (ball) drawBall(ball.state);                       // smoothed for everyone, live for the owner
+```
 
-- **"My own plane feels laggy."** You're rendering yourself from the echoed server copy.
-  Render *yourself* from your local predicted object instead (zero latency).
-- **"Other players teleport / stutter / move in steps."** Snapping to raw state, or
-  `RENDER_DELAY_MS` too low for the jitter. Confirm remotes go through the interpolator,
-  then raise `RENDER_DELAY_MS` (e.g. 100 → 150).
-- **"Other players rubber-band / float past corners / overshoot."** That's extrapolation or
-  raw network round-trip latency — *more smoothing won't fix it.* Remove any extrapolation
-  and accept the small honest delay; true RTT is not a client-side bug.
-- **"Everyone lags equally, including stationary objects."** Likely `me.set` per frame
-  flooding the relay — move publishing to the fixed 10–20 Hz tick.
+**Only claim on interaction, not every frame.** Keep object state flat. Full code and the handoff
+details are in [references/realtime-patterns.md](references/realtime-patterns.md).
 
-## Config wiring (required — the browser can't read `.genex/project.json`)
+## Host authority (scores, rounds, enemies)
 
-The game runs in the browser; `.genex/project.json` (which holds `slug`, `colyseusUrl`,
-`apiUrl`) is gitignored and not bundled. Surface those values to the client explicitly —
-e.g. a tiny committed `src/genex.config.ts`:
+One client is the `host`. Let *only* the host write agreed state and simulate shared enemies, so
+there's a single source of truth:
 
 ```ts
-// src/genex.config.ts — values from `.genex/project.json` (printed by `genex init`)
-export const GENEX = {
-  slug: "my-game-slug",
-  colyseusUrl: "wss://demo-colyseus.glotech.world",
-  apiUrl: "https://demo-api.glotech.world",
-} as const;
+if (room.isHost) room.shared.set("round", nextRound);   // only the host advances the round
+room.on("host", (id) => {});                             // host migrated (someone left)
 ```
 
-Read `.genex/project.json` once and fill these in. (A Vite `define` / `.env` with
-`VITE_` vars works too — the point is the values must end up in the built JS.)
+For host-simulated NPCs, the host claims and drives each enemy as an `object`; when the host
+leaves, its enemies are reassigned to the new host, which reads their `stateRaw` and keeps
+simulating. See the co-op recipe in [references/genre-recipes.md](references/genre-recipes.md).
+
+## Smoothness is felt, not seen — hand the feel to a human
+
+Lag and stutter are *motion over time*. A screenshot is one frozen instant, so **you cannot tell
+from any still capture whether movement feels smooth.** Don't try — it leads to blind tuning.
+
+1. **Trust the SDK's smoothing.** Draw `state` directly; don't add your own.
+2. **Verify it *runs*:** two clients, distinct meshes, both move, no console errors, each sees the
+   other (and the ball, if any). That's all a capture can prove.
+3. **Then say plainly:** *"Multiplayer smoothness depends on your network and can only be felt by a
+   person — open it in two tabs or with a friend and tell me how it feels."* Stop there.
+
+### When the human reports a problem, match the symptom (don't guess)
+
+- **"Everyone (including me) feels laggy / stuttery."** You're re-smoothing: you buffered `state`
+  and lerped it yourself. **Delete that** — draw `state` directly. Most common mistake.
+- **"My own avatar feels laggy."** You're rendering yourself from the network echo. Render yourself
+  from your local object instead.
+- **"Other players spin the wrong way when turning."** You synced a scalar `yaw`. Use a quaternion.
+- **"The ball stutters / jumps / two of it / fights."** It's on `shared`, or you re-smoothed it.
+  Put it on `objects` (claim on contact, owner simulates, everyone draws `state`).
+- **"The ball freezes when someone else takes it."** You're re-smoothing an object, or reading the
+  wrong owner — just draw `objects.get(id).state`; handoff continuity is handled for you.
+- **"The score/enemies desync or double up."** More than one writer. Gate writes on `room.isHost`.
+- **"Everything lags equally, even idle objects."** You're calling `me.set`/`objects.set` per
+  frame — move publishing to the fixed 10–20 Hz tick.
+
+## Config wiring (already done — do NOT hand-write URLs)
+
+`genex init` already wrote `src/genex.config.ts` — a static env-reader with
+production URL defaults (local-stack overrides live in `.env.development.local`,
+which applies in dev mode only and is never committed or shipped). Just import
+it; never hardcode a URL or edit the file:
+
+```ts
+import { GENEX } from "./genex.config";
+// GENEX.slug / GENEX.colyseusUrl / GENEX.apiUrl / GENEX.dashboardOrigins
+```
+
+See the `genex-threejs-embed-auth` skill's "Config wiring" section for the full
+file layout.
 
 ## Persistent worlds (optional — survives restarts)
 
-The relay is in-memory: room state is gone when everyone leaves or the server restarts.
-For a world that persists, save/load one JSON blob keyed by the project slug:
+The relay is in-memory: room state is gone when everyone leaves or the server restarts. For a world
+that persists, save/load one JSON blob keyed by the project slug, from **one authority** (the host):
+
+Both calls **require the embed identity** (`Authorization: Bearer` with the token from
+`getEmbedToken()`) — there is no anonymous read or save. Call them only after
+`await waitForAuth()` (see the `genex-threejs-embed-auth` skill):
 
 ```ts
-// load on boot
-const { data } = await fetch(`${GENEX.apiUrl}/api/projects/${GENEX.slug}/state`).then(r => r.json());
+import { getEmbedToken } from "@genex-ai/embed-sdk";
+
+// load on boot (after waitForAuth() has resolved)
+const { data } = await fetch(`${GENEX.apiUrl}/api/projects/${GENEX.slug}/state`, {
+  headers: { Authorization: `Bearer ${getEmbedToken()}` },
+}).then(r => r.json());
 initWorld(data ?? defaultWorld());
 
-// save from ONE authority (e.g. the host client) to avoid races; max 1 MB, last-write-wins
-fetch(`${GENEX.apiUrl}/api/projects/${GENEX.slug}/state`, {
+// save from ONE authority — the elected host — to avoid races; max 1 MB, last-write-wins
+if (room.isHost) fetch(`${GENEX.apiUrl}/api/projects/${GENEX.slug}/state`, {
   method: "PUT",
-  headers: { "Content-Type": "application/json" },
+  headers: {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${getEmbedToken()}`,
+  },
   body: JSON.stringify(world),
 });
 ```
 
-`GET` returns `{ data }` (or `{ data: null }` if never saved). It's public (no auth) and
-size-capped at 1 MB. Don't save every frame — debounce, and elect a single writer.
+`GET` returns `{ data }` (or `{ data: null }` if never saved). It requires a valid embed
+token for this exact game (401 without one, 403 with another game's token) and is
+size-capped at 1 MB. Don't save every frame — debounce, and let `room.isHost` pick the
+single writer.
 
 ## Checklist
 
-- [ ] `npm i @genex-ai/multiplayer`, and config values wired into the client build.
+- [ ] `npm i @genex-ai/multiplayer` (≥ 0.4.0 for objects/host); config wired into the build.
+- [ ] `connect()` runs AFTER `await waitForAuth()` and passes `auth: getColyseusAuth()!`
+      (the relay rejects tokenless joins — see `genex-threejs-embed-auth`).
 - [ ] `room` is the **project slug**.
-- [ ] `me.set` on a fixed **10–20 Hz** tick (not per frame); full object each time.
+- [ ] `me.set` on a fixed **10–20 Hz** tick; full object each time.
 - [ ] Skip yourself in `room.players` (`id === room.id`).
-- [ ] Remote players go through interpolation; **you** render from local predicted state.
-- [ ] Create-or-reuse a mesh per id; remove it on `'leave'`.
-- [ ] If the world should persist, save from one authority via the state API.
-
-## Troubleshooting
-
-- **Other players stutter / teleport** — you're snapping to raw network state. Use the
-  `RemoteInterpolator` (render-delay + lerp).
-- **My own movement feels laggy** — you're rendering yourself from the echoed server
-  state. Render yourself from your local predicted object instead.
-- **Too much traffic / desync** — you're calling `me.set` per frame. Move it to the tick.
-- **Players never appear** — `room.players` is empty until the first state patch lands;
-  read it in the render loop, and remember it includes you (filter your own id).
+- [ ] Remote players & objects drawn from `state` **directly** — no hand-rolled interpolation.
+- [ ] **You** (and objects you own) render from your local object, not the network echo.
+- [ ] Rotation synced as a quaternion `q`, not a scalar angle.
+- [ ] Hit-tests and discrete values read from `stateRaw`, not `state`.
+- [ ] A ball / shared NPC is on `objects` (claim on contact), never on `shared`.
+- [ ] `shared` scores/rounds and host-simulated enemies are written only by `room.isHost`.
+- [ ] Picked the matching recipe from [references/genre-recipes.md](references/genre-recipes.md).
+
+## Troubleshooting auth
+
+- **`connect()` rejects with 401/403** — 401 "auth required"/"invalid token": you joined
+  without `auth` or before `waitForAuth()` resolved (or the token expired mid-reconnect —
+  read `getColyseusAuth()` fresh at every connect). 403 "wrong game": the `room` value
+  doesn't match this game's own slug.

package/templates/skills/genex-threejs-multiplayer/references/genre-recipes.md

@@ -0,0 +1,115 @@
+# Genre recipes
+
+Pick the recipe matching the game and follow its **decisions** — which channel carries what, who
+is the authority. The mechanisms are just the SDK calls from
+[realtime-patterns.md](realtime-patterns.md); these recipes only tell you *how to wire them per
+genre*. Don't invent your own netcode — every genre reduces to the five-channel table in SKILL.md.
+
+Set the human's expectation up front: this is **casual, favor-the-player** multiplayer (Haxball,
+not Rocket League). There's no server-side simulation or anti-cheat — great for friends over a
+link, not for ranked play. Say that plainly rather than chasing perfect contested physics.
+
+---
+
+## Recipe 1 — Sports / ball (football, hockey, dodgeball)
+
+The genre where a single contested object is the whole game.
+
+| Thing | Channel | Authority |
+| --- | --- | --- |
+| Each player's avatar | `me.set` / `players` | each player |
+| The ball / puck | `objects` (`"ball"`) | current owner (last kicker) |
+| Score, timer, kickoff | `shared` | `room.isHost` |
+| Goal celebration / whistle | `send` | whoever scored / the host |
+
+**Decisions:**
+- **Claim the ball on contact**, not every frame: when your player's collider touches the ball,
+  `room.objects.claim("ball")` and apply the kick impulse to your local ball sim.
+- **Only the owner simulates** the ball (`if (objects.get("ball")?.isMine) objects.set("ball", …)`
+  in the tick). Everyone draws `objects.get("ball").state`. Non-owner writes are dropped by the
+  relay, so two players kicking at once resolve to one owner — no fighting.
+- **Ball state stays flat** (`{x,y,z}` plus a quaternion if it spins). Nested objects don't smooth.
+- **Goals are host-only:** the host detects the ball crossing the line (it reads the ball like
+  everyone else) and writes the score to `shared`; everyone reads `shared.get("score_a")` in the HUD.
+- **A player quitting mid-match doesn't kill the ball** — if the owner leaves, the ball is
+  reassigned to the host automatically and play continues.
+
+**Acceptance feel:** the kicker sees the ball respond the same frame; everyone else sees it glide;
+a contested kick settles on one owner within a snapshot; the owner leaving doesn't freeze the ball.
+
+---
+
+## Recipe 2 — Shooter / arena (top-down or FPS .io)
+
+Fast players, instant hits, a live scoreboard. No shared physics object needed for hitscan.
+
+| Thing | Channel | Authority |
+| --- | --- | --- |
+| Player pos + rotation + hp | `me.set` / `players` (hp read via `stateRaw`) | each player |
+| A shot being fired | `send("shot", …)` | the shooter |
+| Damage applied | victim's own `me.set` (hp) | the victim |
+| Score / round | `shared` | `room.isHost` |
+| Slow physical projectiles (grenades, rockets) | `objects` (one per projectile, `remove` on expiry) | the thrower |
+
+**Decisions:**
+- **The shooter judges the hit locally** ("favor the shooter"): raycast against what *you* see,
+  then `send("shot", { hit: targetId })` — and draw your own muzzle flash / tracer **right there**,
+  because `send` never echoes back to you. This is how casual browser shooters feel responsive; a
+  high-ping victim occasionally "dies behind a wall", which is inherent to server-less shooters —
+  set that expectation, don't try to fix it with more smoothing.
+- **The victim applies its own damage** on receiving the shot (`if (m.hit === room.id) me.hp -= …`)
+  — each player owns their own hp, so there's no write conflict.
+- **Hit-tests read `stateRaw`, not `state`** — you want the raw latest position, not the
+  render-delayed smoothed one. Same for reading remote hp (a discrete value; `state` would lerp it
+  to fractions).
+- **Hitscan uses `send`, not objects** — a shot is an event, not continuous state. Reserve
+  `objects` for a *slow, visible* projectile the players can dodge (a rocket): claim on spawn,
+  `objects.set` its arc, `objects.remove` on impact.
+- **Scoreboard is host-only:** the host tallies kills into `shared`; everyone renders it.
+
+**Acceptance feel:** movement is smooth for 4–8 players; hits register on what you aimed at; the
+scoreboard updates for everyone; one player on a throttled/backgrounded tab doesn't drag others.
+
+---
+
+## Recipe 3 — Co-op vs enemies (horde, tower defense, dungeon)
+
+Players cooperate against AI the game itself controls. The trick: **one client runs the enemy AI**,
+and it's the host, so it survives players joining and leaving.
+
+| Thing | Channel | Authority |
+| --- | --- | --- |
+| Each player's avatar | `me.set` / `players` | each player |
+| Each enemy / NPC | `objects` (`"enemy:<n>"`), one per enemy | the **host** |
+| Wave number, shared score, boss hp | `shared` | `room.isHost` |
+| Spawn flashes, hit sparks | `send` | the host / whoever hit |
+
+**Decisions:**
+- **The host owns and simulates the enemies.** On spawn, the host `claim`s each enemy object and,
+  in its tick, runs the AI and `objects.set`s each one. Non-host clients never simulate enemies —
+  they just draw `objects.get("enemy:n").state` (smoothed) and read `stateRaw` for hit-tests.
+- **One object per enemy** (flat `{x,y,z,hp}`) so each smooths independently. For a big horde keep
+  the count modest (≈8–16 active); it's casual, not a bullet-hell server.
+- **Host migration keeps the game alive:** if the host leaves, its enemies are reassigned to the
+  new host automatically. The new host reads each enemy's `stateRaw` and continues the AI from
+  there — no wave restart. React to `on("host")` if the new host needs to (re)seed spawns.
+- **Players still deal damage favor-the-player**: a **non-host** player `send`s "I hit enemy:3" and
+  the host (owner of enemy:3) applies the damage to its enemy sim and publishes the new hp. But
+  `send` never echoes to the sender — so when the **host itself** shoots an enemy it owns, it must
+  apply that damage to its local enemy sim **directly**, not via `send` (which wouldn't come back).
+  Rule of thumb: if `objects.get("enemy:3")?.isMine`, apply the hit locally; otherwise `send` it.
+  Enemy death: the host `objects.remove("enemy:3")`.
+- **Waves/score are host-only** in `shared`; late joiners read the current wave on connect.
+
+**Acceptance feel:** enemies move smoothly for everyone; killing the host's tab mid-wave promotes a
+new host and the enemies keep going within a second or two (no freeze, no duplicates); a late joiner
+sees the correct wave and enemy positions.
+
+---
+
+## Not sure which? Start from the table
+
+Whatever the genre, ask per thing: *is it one player's own state* (`me.set`) *· a moving thing
+nobody owns* (`objects`) *· a slow agreed fact* (`shared`, host-written) *· or a one-off event*
+(`send`)? Answer that for each moving/shared piece and the netcode is done. If you're inventing a
+sixth mechanism, you've taken a wrong turn — re-read the channel table in SKILL.md.