@genex-ai/cli-demo 0.4.0 → 0.6.0

package/dist/index.js

@@ -816,6 +816,9 @@ async function deployGame(sshUrl, opts, log) {
     });
     if (push.code === 0) {
       log.success("Pushed.");
+      if (opts.playUrl) {
+        await waitUntilLive(opts.playUrl, await buildFingerprint(siteDir), opts.liveTimeoutMs ?? 12e4, log);
+      }
       return true;
     }
     log.warn("git push failed \u2014 your live game was NOT updated.");
@@ -850,6 +853,41 @@ async function fileExists(p) {
     return false;
   }
 }
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function buildFingerprint(siteDir) {
+  let html;
+  try {
+    html = await fs6.readFile(path7.join(siteDir, "index.html"), "utf8");
+  } catch {
+    return null;
+  }
+  const m = html.match(/[A-Za-z0-9_]+-[A-Za-z0-9_-]{8}\.(?:js|css)/);
+  return m ? m[0] : null;
+}
+async function waitUntilLive(playUrl, fingerprint, timeoutMs, log) {
+  if (!fingerprint) {
+    log.dim(`  ${playUrl}`);
+    log.dim("  (GitHub Pages rebuilds ~30\u201390s after a push.)");
+    return;
+  }
+  log.step("Waiting for GitHub Pages to serve the new build\u2026");
+  const deadline = Date.now() + timeoutMs;
+  let n = 0;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${playUrl}?_genexlive=${n++}`, { cache: "no-store" });
+      if (res.ok && (await res.text()).includes(fingerprint)) {
+        log.success(`Live. \u{1F310}  ${playUrl}`);
+        return;
+      }
+    } catch {
+    }
+    await sleep(4e3);
+  }
+  log.warn("Still publishing \u2014 GitHub Pages can take a bit longer.");
+  log.dim(`  ${playUrl}`);
+  log.dim("  (Open it in ~30\u201360s; the new build is on its way.)");
+}
 async function warnIfAbsolutePaths(siteDir, log) {
   let html;
   try {
@@ -884,7 +922,7 @@ async function runPublish(opts) {
   if (opts.noPush) {
     log.info("Skipping build + git push (--no-push).");
   } else {
-    pushed = await deployGame(meta.sshUrl, { noBuild: opts.noBuild }, log);
+    pushed = await deployGame(meta.sshUrl, { noBuild: opts.noBuild, playUrl: meta.playUrl }, log);
   }
   log.step("Listing it in the gallery\u2026");
   let res;
@@ -918,7 +956,6 @@ async function runPublish(opts) {
   }
   if (meta.playUrl) {
     log.dim(`  play: ${meta.playUrl}`);
-    if (pushed === true) log.dim("  (GitHub Pages rebuilds ~30\u201390s after a push.)");
   }
 }
 
@@ -933,18 +970,18 @@ async function runPreview(opts) {
     process.exitCode = 1;
     return;
   }
-  const pushed = await deployGame(meta.sshUrl, { noBuild: opts.noBuild }, log);
+  const pushed = await deployGame(
+    meta.sshUrl,
+    { noBuild: opts.noBuild, playUrl: meta.playUrl },
+    log
+  );
   log.plain("");
   if (!pushed) {
     log.warn("Preview not updated \u2014 see the error above.");
     process.exitCode = 1;
     return;
   }
-  log.success("Preview deployed. \u{1F310}");
-  if (meta.playUrl) {
-    log.dim(`  ${meta.playUrl}`);
-    log.dim("  (GitHub Pages rebuilds ~30\u201390s after a push; it stays an unlisted draft until you publish.)");
-  }
+  log.success("Preview deployed \u2014 unlisted draft (run `genex publish` to list it).");
 }
 
 // src/commands/generate.ts
@@ -967,17 +1004,21 @@ async function downloadToFile(url, dest, headers) {
 }
 
 // src/commands/generate.ts
+var PUBLIC_PREFIX = "public/";
 var KIND_DIR = {
-  model: "assets/models",
-  skybox: "assets/skybox",
-  sfx: "assets/sfx",
-  texture: "assets/textures"
+  model: "public/assets/models",
+  skybox: "public/assets/skybox",
+  sfx: "public/assets/sfx",
+  texture: "public/assets/textures"
 };
-var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function runtimePath(rel) {
+  return `./${rel.replace(PUBLIC_PREFIX, "")}`;
+}
+var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
 function fileDest(kind, slug, f) {
   if (kind === "texture") {
     const name = f.role.replace(/^texture-/, "");
-    return `assets/textures/${slug}/${name}.${f.ext}`;
+    return `public/assets/textures/${slug}/${name}.${f.ext}`;
   }
   return `${KIND_DIR[kind]}/${slug}.${f.ext}`;
 }
@@ -1082,19 +1123,21 @@ async function poll(apiUrl, token, id, onProgress) {
       }
     } catch {
     }
-    await sleep(3e3);
+    await sleep2(3e3);
   }
   return null;
 }
 function printHint(kind, written, log) {
-  const primary = written[0] ?? "";
+  const load = runtimePath(written[0] ?? "");
   const hint = {
-    model: `Load with GLTFLoader and add to the scene \u2014 see the genex-ai-model skill. Use the relative path "./${primary}".`,
-    skybox: `Load as an equirectangular texture \u2192 scene.background + scene.environment \u2014 see genex-ai-skybox. Path "./${primary}".`,
-    sfx: `Load with AudioLoader into a THREE.PositionalAudio (camera needs an AudioListener) \u2014 see genex-ai-sfx. Path "./${primary}".`,
-    texture: `Load with TextureLoader, set RepeatWrapping, build a MeshStandardMaterial \u2014 see genex-ai-texture. Path "./${primary}".`
+    model: `Load with GLTFLoader and add to the scene \u2014 see the genex-ai-model skill. Use the relative path "${load}".`,
+    skybox: `Load as an equirectangular texture \u2192 scene.background + scene.environment \u2014 see genex-ai-skybox. Path "${load}".`,
+    sfx: `Load with AudioLoader into a THREE.PositionalAudio (camera needs an AudioListener) \u2014 see genex-ai-sfx. Path "${load}".`,
+    texture: `Load with TextureLoader, set RepeatWrapping, build a MeshStandardMaterial \u2014 see genex-ai-texture. Path "${load}".`
   };
-  log.success("Done. Asset saved into ./assets (commit it \u2014 `genex publish` ships it with the game).");
+  log.success(
+    "Done. Asset saved into public/assets (so Vite ships it; load it as ./assets/\u2026 \u2014 `genex publish` commits and ships it with the game)."
+  );
   log.dim(`  ${hint[kind]}`);
 }
 
@@ -1117,10 +1160,10 @@ ${c.bold("Usage")}
   genex init [<name>] [options]      Scaffold + authorize + create the draft project.
   genex preview [options]            Build + push to the hosted draft URL (unlisted).
   genex publish [options]            Build + push, then list the game in the gallery.
-  genex model "<prompt>" [options]   Generate a 3D model (GLB) into ./assets/models.
-  genex skybox "<prompt>" [options]  Generate a skybox (equirect) into ./assets/skybox.
-  genex sfx "<prompt>" [options]     Generate a sound effect (mp3) into ./assets/sfx.
-  genex texture "<prompt>" [options] Generate a PBR texture into ./assets/textures.
+  genex model "<prompt>" [options]   Generate a 3D model (GLB) into public/assets/models.
+  genex skybox "<prompt>" [options]  Generate a skybox (equirect) into public/assets/skybox.
+  genex sfx "<prompt>" [options]     Generate a sound effect (mp3) into public/assets/sfx.
+  genex texture "<prompt>" [options] Generate a PBR texture into public/assets/textures.
 
 ${c.bold("Options for the generators (`model` `skybox` `sfx` `texture`)")}
   --terrain            (texture) seamless tiling surface for terrain/ground.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/skills/genex-ai-model/SKILL.md

@@ -24,11 +24,33 @@ Write a specific prompt — "weathered wooden barrel with rusted iron bands" bea
 "barrel". The command blocks until the mesh is ready (up to ~a minute), then saves:
 
 ```
-assets/models/<slug>.glb
+public/assets/models/<slug>.glb
 ```
 
 `<slug>` is derived from the prompt (e.g. `weathered-wooden-barrel.glb`). The file
-is **committed by `npx genex publish`**, so it ships inside your published game.
+lives under `public/` so Vite ships it in the build (load it as `./assets/models/...` —
+the `public/` prefix is stripped when served). It is **committed by `npx genex publish`**,
+so it ships inside your published game.
+
+## Hero models must face forward
+
+For the model the player controls (a ship, car, character — the "hero"), the mesh should
+**face forward**: its front pointing down the direction of travel (conventionally `+Z`,
+i.e. "looking forward"). A hero whose nose points sideways reads as broken at a glance.
+
+- **In the prompt:** when it's the player's craft, ask for it facing forward — e.g.
+  `"...game-ready, facing forward, front toward +Z"`.
+- **On load (fallback):** if the imported GLB still isn't forward, rotate it once so its
+  nose aligns with travel. Wrap the model in a parent `Object3D` and apply the correction
+  to the child, so your movement code can rotate the parent cleanly:
+  ```ts
+  const hero = new THREE.Object3D();
+  gltf.scene.rotation.y = Math.PI / 2; // one-time facing correction — tune per model
+  hero.add(gltf.scene);
+  scene.add(hero); // move/rotate `hero`, not gltf.scene
+  ```
+- Orientation **is** visible in a still — confirm the hero faces forward in your
+  self-check screenshot before moving on.
 
 ## Load it into the scene
 
@@ -55,7 +77,8 @@ To place many copies, `model.clone()` per instance. For animated GLBs, drive
   (`/assets/...`) — GitHub Pages serves the game at a subpath.
 - Set `base: "./"` in `vite.config.ts` before `npm run build` (see the scaffold
   prompt's publish step).
-- Commit the `assets/` folder — `npx genex publish` pushes it with the game.
+- Keep generated assets under `public/assets/` — Vite only ships files under `public/`
+  (or files you `import`); `npx genex publish` commits and pushes that folder with the game.
 
 ## Options
 

package/templates/skills/genex-ai-sfx/SKILL.md

@@ -18,7 +18,7 @@ npx genex sfx "punchy laser zap, short and dry" --duration 2
 Blocks until ready, then saves:
 
 ```
-assets/sfx/<slug>.mp3
+public/assets/sfx/<slug>.mp3
 ```
 
 Committed by `npx genex publish`, so it ships with your game.
@@ -55,7 +55,8 @@ Reuse one loaded `buffer` across many plays; create a fresh `Audio`/`PositionalA
 
 ## Publish checklist
 
-- Relative path `./assets/sfx/...`; `base: "./"` in `vite.config.ts`; commit `assets/`.
+- Relative path `./assets/sfx/...`; `base: "./"` in `vite.config.ts`; files live under
+  `public/assets/` so Vite ships them; `npx genex publish` commits and pushes them.
 
 ## Troubleshooting
 

package/templates/skills/genex-ai-skybox/SKILL.md

@@ -26,7 +26,7 @@ npx genex skybox "<prompt>"
 Blocks until ready, then saves:
 
 ```
-assets/skybox/<slug>.jpg
+public/assets/skybox/<slug>.jpg
 ```
 
 The JPG is **committed by `npx genex publish`**, so it ships with your game.
@@ -63,7 +63,8 @@ texture.dispose; // (dispose the PMREM source later if you stop using it)
 
 - Use the **relative** path `./assets/skybox/...` (GitHub Pages serves at a subpath).
 - `base: "./"` in `vite.config.ts` before `npm run build`.
-- Commit `assets/` — `npx genex publish` pushes it with the game.
+- Generated files live under `public/assets/` so Vite ships them; `npx genex publish`
+  commits and pushes that folder with the game.
 
 ## Troubleshooting
 

package/templates/skills/genex-ai-texture/SKILL.md

@@ -27,7 +27,7 @@ npx genex texture "lush green grass" --terrain    # seamless tiling for ground/t
 Blocks until ready, then saves:
 
 ```
-assets/textures/<slug>/basecolor.<ext>
+public/assets/textures/<slug>/basecolor.<ext>
 ```
 
 Committed by `npx genex publish`, so it ships with your game.
@@ -67,7 +67,8 @@ scene.add(ground);
 
 ## Publish checklist
 
-- Relative path `./assets/textures/...`; `base: "./"` in `vite.config.ts`; commit `assets/`.
+- Relative path `./assets/textures/...`; `base: "./"` in `vite.config.ts`; files live under
+  `public/assets/` so Vite ships them; `npx genex publish` commits and pushes them.
 
 ## Troubleshooting
 

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

@@ -0,0 +1,167 @@
+---
+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.
+---
+
+# 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.
+
+**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.
+
+Read [references/realtime-patterns.md](references/realtime-patterns.md) for the
+copy-paste `RemoteInterpolator` + local-prediction helpers and the persistence/config code.
+
+## Install
+
+```bash
+npm i @genex-ai/multiplayer
+```
+
+## 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.
+
+```ts
+import { connect } from "@genex-ai/multiplayer";
+
+type State = { x: number; z: number; yaw: number };  // YOUR per-player state
+
+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
+});
+```
+
+## 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.
+
+## 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.
+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.
+
+## Smoothness is human-tested — you cannot see it
+
+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.
+
+Your job is bounded:
+
+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.
+
+**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.
+
+### When the human reports a problem, match the symptom (don't guess)
+
+- **"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.
+
+## Config wiring (required — the browser can't read `.genex/project.json`)
+
+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`:
+
+```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;
+```
+
+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.)
+
+## 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:
+
+```ts
+// load on boot
+const { data } = await fetch(`${GENEX.apiUrl}/api/projects/${GENEX.slug}/state`).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`, {
+  method: "PUT",
+  headers: { "Content-Type": "application/json" },
+  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.
+
+## Checklist
+
+- [ ] `npm i @genex-ai/multiplayer`, and config values wired into the client build.
+- [ ] `room` is the **project slug**.
+- [ ] `me.set` on a fixed **10–20 Hz** tick (not per frame); 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).

package/templates/skills/genex-threejs-multiplayer/references/realtime-patterns.md

@@ -0,0 +1,202 @@
+# Realtime patterns: interpolation, prediction, persistence
+
+The `@genex-ai/multiplayer` relay gives you the **latest** state of each player and
+nothing else — no timestamps, no smoothing. These are the pieces you add on top so the
+game feels good. All code is plain TypeScript; nothing here is provided by the package.
+
+## Why you need this
+
+- You publish `me.set` at ~15 Hz but render at 60 fps. If you snap each remote player to
+  their last received position, they move in visible 15 Hz steps and jump on packet
+  jitter. **Fix: interpolation** — render each remote player slightly in the past and
+  lerp between their two surrounding snapshots.
+- Your *own* avatar would feel laggy if you waited for the server to echo your position
+  back. **Fix: prediction** — apply input locally and render yourself from that
+  immediately; the tick still publishes it for everyone else.
+
+## RemoteInterpolator (render-delay interpolation)
+
+Buffers timestamped snapshots per remote player and samples a smoothed value ~100 ms in
+the past. Stamp snapshots with the local clock on arrival (we don't get server time).
+
+```ts
+// interpolation.ts
+const RENDER_DELAY_MS = 100; // render remotes this far in the past; raise if jittery
+const BUFFER_MS = 1000;      // keep ~1s of history
+
+type Vec = { x: number; y: number; z: number; yaw: number };
+type Snap = { t: number; v: Vec };
+
+function lerp(a: number, b: number, k: number) {
+  return a + (b - a) * k;
+}
+// shortest-arc angle lerp (radians) — avoids spinning the wrong way across ±π
+function lerpAngle(a: number, b: number, k: number) {
+  let d = (b - a) % (Math.PI * 2);
+  if (d > Math.PI) d -= Math.PI * 2;
+  if (d < -Math.PI) d += Math.PI * 2;
+  return a + d * k;
+}
+
+export class RemoteInterpolator {
+  private buffers = new Map<string, Snap[]>();
+
+  /** Call whenever you read a remote player's latest state (e.g. each frame, or on 'change'). */
+  push(id: string, v: Vec, now = performance.now()) {
+    let buf = this.buffers.get(id);
+    if (!buf) this.buffers.set(id, (buf = []));
+    const last = buf[buf.length - 1];
+    // de-dupe identical repeats (players is re-read every frame)
+    if (last && last.v.x === v.x && last.v.z === v.z && last.v.yaw === v.yaw && last.v.y === v.y) return;
+    buf.push({ t: now, v });
+    const cutoff = now - BUFFER_MS;
+    while (buf.length > 2 && buf[0].t < cutoff) buf.shift();
+  }
+
+  /** Smoothed value to render this frame, or null if we have nothing yet. */
+  sample(id: string, now = performance.now()): Vec | null {
+    const buf = this.buffers.get(id);
+    if (!buf || buf.length === 0) return null;
+    const target = now - RENDER_DELAY_MS;
+    if (buf.length === 1 || target <= buf[0].t) return buf[0].v;
+    if (target >= buf[buf.length - 1].t) return buf[buf.length - 1].v; // clamp (no extrapolation)
+    for (let i = 0; i < buf.length - 1; i++) {
+      const a = buf[i], b = buf[i + 1];
+      if (target >= a.t && target <= b.t) {
+        const k = (target - a.t) / (b.t - a.t || 1);
+        return {
+          x: lerp(a.v.x, b.v.x, k),
+          y: lerp(a.v.y, b.v.y, k),
+          z: lerp(a.v.z, b.v.z, k),
+          yaw: lerpAngle(a.v.yaw, b.v.yaw, k),
+        };
+      }
+    }
+    return buf[buf.length - 1].v;
+  }
+
+  remove(id: string) {
+    this.buffers.delete(id);
+  }
+}
+```
+
+**Tuning:** `RENDER_DELAY_MS` ≈ one tick interval + jitter (100 ms is safe for a 15 Hz
+tick). Lower = more responsive but more stutter on jitter. For sudden teleports (respawn,
+warp) clear that player's buffer and snap, so you don't lerp across the whole map.
+
+## Complete movement example
+
+```ts
+import * as THREE from "three";
+import { connect } from "@genex-ai/multiplayer";
+import { GENEX } from "./genex.config";
+import { RemoteInterpolator } from "./interpolation";
+
+type S = { x: number; z: number; yaw: number };
+
+const room = await connect<S>({ url: GENEX.colyseusUrl, room: GENEX.slug });
+const interp = new RemoteInterpolator();
+
+// --- local player: prediction. Input mutates this; we render yourself from it. ---
+const me = { x: 0, z: 0, yaw: 0 };
+addEventListener("keydown", (e) => {
+  if (e.key === "ArrowLeft") me.yaw += 0.1;
+  if (e.key === "ArrowRight") me.yaw -= 0.1;
+  if (e.key === "ArrowUp") { me.x += Math.sin(me.yaw); me.z += Math.cos(me.yaw); }
+});
+
+// --- publish at ~15 Hz (NOT per frame) ---
+const tick = setInterval(() => room.me.set(me), 66);
+
+// --- meshes, one per id ---
+const meshes = new Map<string, THREE.Object3D>();
+function meshFor(id: string) {
+  let m = meshes.get(id);
+  if (!m) { m = new THREE.Mesh(boxGeo, boxMat); scene.add(m); meshes.set(id, m); }
+  return m;
+}
+room.on("leave", (id) => {
+  const m = meshes.get(id);
+  if (m) { scene.remove(m); meshes.delete(id); }
+  interp.remove(id);
+});
+
+function frame() {
+  // yourself: render from local predicted state (zero latency)
+  meshFor(room.id).position.set(me.x, 0, me.z);
+  meshFor(room.id).rotation.y = me.yaw;
+
+  // everyone else: feed the interpolator, render the smoothed sample
+  for (const [id, p] of room.players) {
+    if (id === room.id) continue;
+    interp.push(id, { x: p.state.x ?? 0, y: 0, z: p.state.z ?? 0, yaw: p.state.yaw ?? 0 });
+    const v = interp.sample(id);
+    if (!v) continue;
+    const m = meshFor(id);
+    m.position.set(v.x, v.y, v.z);
+    m.rotation.y = v.yaw;
+  }
+
+  renderer.render(scene, camera);
+  requestAnimationFrame(frame);
+}
+frame();
+
+// cleanup if you ever tear down: clearInterval(tick); room.leave();
+```
+
+## Custom events (shots, emotes, chat)
+
+For one-off actions that aren't part of continuous state, use `send` — it doesn't belong
+in `me.set` (which is your *current* state, not events):
+
+```ts
+// shooter:
+room.send("shot", { from: room.id, x: me.x, z: me.z, yaw: me.yaw });
+
+// everyone else:
+room.on("shot", (msg: any) => spawnTracer(msg.x, msg.z, msg.yaw));
+```
+
+## Shared room state (scores, round, world)
+
+`shared` is for state everyone agrees on, not per-player position:
+
+```ts
+room.shared.set("round", (Number(room.shared.get("round")) || 0) + 1);
+room.on("shared", (key, value) => { if (key === "score") updateScoreboard(value); });
+```
+
+Any client can write any key (demo relay has no auth). For authority (who may change the
+score / advance the round), pick one client — e.g. the first/lowest session id present —
+and let only it write.
+
+## Persistence helper
+
+```ts
+// persistence.ts
+export async function loadWorld<T>(fallback: T): Promise<T> {
+  try {
+    const { data } = await fetch(`${GENEX.apiUrl}/api/projects/${GENEX.slug}/state`).then(r => r.json());
+    return (data as T) ?? fallback;
+  } catch { return fallback; }
+}
+
+let saveTimer: ReturnType<typeof setTimeout> | null = null;
+export function saveWorld(world: unknown) {
+  // debounce: at most one PUT per second, from ONE authority client
+  if (saveTimer) return;
+  saveTimer = setTimeout(() => {
+    saveTimer = null;
+    fetch(`${GENEX.apiUrl}/api/projects/${GENEX.slug}/state`, {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(world),
+    }).catch(() => {});
+  }, 1000);
+}
+```
+
+State is one JSON blob per project, max 1 MB, last-write-wins. Save from a single
+authority (host) so concurrent writers don't clobber each other.

package/templates/skills/genex-threejs-skill-router/SKILL.md

@@ -36,6 +36,11 @@ map, execution order, and acceptance gate.
 | exposure, tone mapping, color grading, LUTs | `$genex-threejs-exposure-color-grading` |
 | render-target ownership, pass ordering, depth/normal/history signals | `$genex-threejs-image-pipeline` |
 | fixed-view captures, seed sweeps, browser and GPU evidence | `$genex-threejs-visual-validation` |
+| realtime multiplayer: movement sync, shared state, presence, shots/emotes, persistence | `$genex-threejs-multiplayer` |
+
+**Multiplayer is mandatory routing:** if the game has 2+ players sharing a world, loading
+`$genex-threejs-multiplayer` is **required** before any networking code — the relay does no
+interpolation/prediction, and that skill is how you add them.
 
 ## Real (AI-generated) assets — `npx genex` commands
 
@@ -58,6 +63,20 @@ Prefer the **procedural** skills above for abstract/parametric/animated systems
 **`npx genex` generators** for concrete, describable, photoreal assets. They complement
 each other.
 
+**Generate a core asset set by default — don't wait to be asked.** For any game that
+needs concrete objects or surfaces, decide a small core set from the concept and start
+generating it **up front, in parallel** (each `npx genex` is an independent ~1-minute
+job — launch them concurrently in the background, then scaffold the scene while they run
+and wire each asset in as it lands, with a procedural placeholder as fallback until then):
+
+- the **hero model** the player controls or chases (`npx genex model`),
+- one key **texture** for the ground/main surface (`npx genex texture --terrain` for ground),
+- a **skybox** when the scene is outdoors (`npx genex skybox`),
+- a **sfx** or two for the core action/feedback (`npx genex sfx`).
+
+Skip generation only for purely abstract/geometric games. Keep the set small and
+concept-driven — a richer first build beats a grey-box one.
+
 ## Routing rules
 
 - Start from the playable game target: player verb, scene scale, camera distance,

package/templates/skills/genex-threejs-skill-router/references/routing-map.md

@@ -51,3 +51,11 @@ publishing or multiplayer, inspect the project first. Prefer clean boundaries:
 - serializable player/session state;
 - explicit asset loading paths;
 - one clear start function for local preview and hosted launch.
+
+**Multiplayer is mandatory routing.** If the game has 2+ players sharing a world,
+load `$genex-threejs-multiplayer` **before writing any networking code** — it is not
+optional. The `@genex-ai/multiplayer` relay syncs `me`/`shared` but does **no**
+physics, prediction, or interpolation; that skill is how you add interpolation for
+remote players, prediction for the local player, config wiring, and (for save-state
+games) the persistent-world API. Use only the APIs that skill documents — do not
+invent transport methods.