@genex-ai/cli-demo 0.8.0 → 0.10.0

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

@@ -1,113 +1,56 @@
-# Realtime patterns: interpolation, prediction, persistence
+# Realtime patterns: rendering, objects, host, events, 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.
+The `@genex-ai/multiplayer` SDK smooths remote players **and shared objects** for you (client-side
+entity interpolation on a shared clock). These are the patterns you build on top — none of them
+re-implement smoothing, because doing so is the mistake that makes games lag.
 
-## Why you need this
+## The golden rule
 
-- 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.
+- **Remote players & objects:** draw `players.get(id).state` / `objects.get(id).state` directly.
+  Already smoothed.
+- **Yourself & objects you own:** draw from your own local object. Never from the network echo.
 
-## RemoteInterpolator (render-delay interpolation)
+If you ever buffer `state` and lerp between snapshots, stop — you're rebuilding smoothing the SDK
+already did, and stacking two smoothers adds visible lag.
 
-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
+## Complete movement example (players)
 
 ```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 };
+// Your published state — EVERY synced field, including discrete ones like hp. `me.set`
+// replaces your state wholesale, so the tick must send all of these every time (below).
+type S = { x: number; z: number; q: number[]; hp: 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 };
+// --- local player: input mutates this; we render yourself from it (zero latency) ---
+// This ONE object holds everything you sync. Keep hp/ammo/etc. here too — see the warning below.
+const me = { x: 0, z: 0, yaw: 0, hp: 100 };
 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);
+// rotation helper — turn our yaw into the quaternion we publish (and send with shots, below)
+const _q = new THREE.Quaternion();
+const myQuat = (): number[] => _q.setFromAxisAngle(new THREE.Vector3(0, 1, 0), me.yaw).toArray();
+
+// --- publish at ~15 Hz (NOT per frame). Send the WHOLE state — a field you omit is deleted. ---
+const tick = setInterval(() => {
+  room.me.set({ x: me.x, z: me.z, q: myQuat(), hp: me.hp });
+}, 66);
+```
+
+> **`me.set` replaces your state wholesale.** Every tick must include EVERY field — position,
+> rotation, AND discrete values like `hp`/`ammo`. A field you leave out is gone on the wire, so
+> keep one local `me` object with all of them and publish it whole each tick. (Same for
+> `objects.set`.)
+
+```ts
 
 // --- meshes, one per id ---
 const meshes = new Map<string, THREE.Object3D>();
@@ -119,84 +62,156 @@ function meshFor(id: string) {
 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;
+  // yourself: render from the local object (zero latency)
+  const self = meshFor(room.id);
+  self.position.set(me.x, 0, me.z);
+  self.rotation.y = me.yaw;
 
-  // everyone else: feed the interpolator, render the smoothed sample
+  // everyone else: draw state DIRECTLY — it is already smoothed
   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;
+    m.position.set(p.state.x ?? 0, 0, p.state.z ?? 0);
+    if (p.state.q) m.quaternion.fromArray(p.state.q);   // slerped for you by the SDK
   }
 
   renderer.render(scene, camera);
   requestAnimationFrame(frame);
 }
 frame();
-
-// cleanup if you ever tear down: clearInterval(tick); room.leave();
 ```
 
-## Custom events (shots, emotes, chat)
+No interpolation buffer, no render-delay constant, no lerp of remote state — the SDK owns all of it.
+
+## A shared object (the ball) — `objects`, not `shared`
 
-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):
+A ball belongs to no player. On `objects`, exactly one client **owns** it at a time (server-
+enforced), the owner simulates it, and everyone else reads it auto-smoothed — on the same
+interpolation as a player. The stream is keyed by the object id, so it stays continuous when
+ownership changes (no snap), and the object survives its owner leaving (reassigned to the host).
 
 ```ts
-// shooter:
-room.send("shot", { from: room.id, x: me.x, z: me.z, yaw: me.yaw });
+// ball.ts
+const ball = { x: 0, y: 0.5, z: 0, vx: 0, vy: 0, vz: 0 }; // the owner's local sim
 
-// everyone else:
-room.on("shot", (msg: any) => spawnTracer(msg.x, msg.z, msg.yaw));
+// claim on contact (you kicked it) — NOT every frame
+function kick(dir: THREE.Vector3, power: number) {
+  room.objects.claim("ball");
+  ball.vx += dir.x * power; ball.vz += dir.z * power;
+}
+
+// in your fixed tick: if you own it, simulate + publish it (flat fields so it smooths)
+function publishBall() {
+  const view = room.objects.get("ball");
+  if (view?.isMine) {
+    stepBallPhysics(ball);                     // your own integrator or Rapier
+    room.objects.set("ball", { x: ball.x, y: ball.y, z: ball.z });
+  }
+}
+
+// render: owner draws its local sim (zero latency); everyone else draws the smoothed state
+function drawBall() {
+  const view = room.objects.get<{ x: number; y: number; z: number }>("ball");
+  if (!view) return;
+  ballMesh.position.set(view.state.x ?? 0, view.state.y ?? 0, view.state.z ?? 0);
+}
+```
+
+Rules that keep it correct:
+
+- **Claim on interaction, not continuously.** Whoever last kicked owns and simulates it.
+- **Keep object fields flat** (`x/y/z`, a 4-number quaternion). Nested objects snap instead of glide.
+- **Only the owner's `set` lands** — the relay drops writes from non-owners, so you never get two
+  clients fighting over the ball. You don't need to check "am I owner" before drawing, only before
+  simulating.
+- **Transient objects** (bullets, pickups): `room.objects.remove(id)` when they expire, so they
+  don't pile up.
+
+## Host authority (scores, rounds, world)
+
+One client is `room.host` (the first joiner, re-elected on leave). Let only the host write agreed
+state, so there's a single source of truth — no "who increments the score" races:
+
+```ts
+function updateHud() {
+  scoreEl.textContent = String(room.shared.get("score") ?? 0);   // everyone reads
+}
+function goal(team: "a" | "b") {
+  if (!room.isHost) return;                                       // only the host writes
+  const key = `score_${team}`;
+  room.shared.set(key, (Number(room.shared.get(key)) || 0) + 1);
+}
+room.on("host", () => {/* host migrated — the new host takes over writing */});
 ```
 
-## Shared room state (scores, round, world)
+`room.on('shared', …)` fires when a key is **first set**, not on every change — for a live value,
+read `room.shared.get(...)` in your loop (as `updateHud` does) rather than relying on the event.
+
+## Custom events (shots, emotes, chat)
+
+For one-off actions that aren't continuous state, use `send`. The shooter judges the hit **locally**
+against what it sees (favor-the-shooter) and announces it; the victim applies its own damage.
 
-`shared` is for state everyone agrees on, not per-player position:
+**`send` reaches only OTHER clients — it never echoes back to you.** So apply your own action's
+visible effect *directly* at fire time; use `on(...)` only to render everyone else's:
 
 ```ts
-room.shared.set("round", (Number(room.shared.get("round")) || 0) + 1);
-room.on("shared", (key, value) => { if (key === "score") updateScoreboard(value); });
+function fire() {
+  const hit = raycastAgainstWhatISee();       // favor-the-shooter: judge locally
+  spawnTracer(me.x, me.z, myQuat());          // MY tracer — right here, not via on("shot")
+  room.send("shot", { from: room.id, x: me.x, z: me.z, q: myQuat(), hit: hit ?? null });
+}
+
+room.on("shot", (m: any) => {
+  spawnTracer(m.x, m.z, m.q);                 // OTHER players' tracers
+  if (m.hit === room.id) me.hp -= 10;         // I was hit → my next me.set publishes the new hp
+});
 ```
 
-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.
+Read remote positions for hit-testing from `stateRaw` (raw latest), not `state` (rendered in the
+past). Guard the lookup — a player may have just left:
+
+```ts
+const t = room.players.get(id);
+if (!t) return;
+const px = t.stateRaw.x, pz = t.stateRaw.z;   // test against the raw latest
+```
 
 ## Persistence helper
 
 ```ts
-// persistence.ts
+// persistence.ts — /state requires the embed identity: call only after
+// `await waitForAuth()` has resolved (see the genex-threejs-embed-auth skill).
+import { getEmbedToken } from "@genex-ai/embed-sdk";
+
 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());
+    const { data } = await fetch(`${GENEX.apiUrl}/api/projects/${GENEX.slug}/state`, {
+      headers: { Authorization: `Bearer ${getEmbedToken()}` },
+    }).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;
+  if (saveTimer) return;                     // debounce: at most one PUT/sec, from the host only
   saveTimer = setTimeout(() => {
     saveTimer = null;
     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),
     }).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.
+State is one JSON blob per project, max 1 MB, last-write-wins. Save from a single authority
+(`room.isHost`) so concurrent writers don't clobber each other.

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

@@ -37,11 +37,13 @@ map, execution order, and acceptance gate.
 | eye adaptation, tone mapping, LUT grading, output color | `$genex-threejs-exposure-color-grading` |
 | shared depth/normal/velocity ownership and multi-pass ordering | `$genex-threejs-image-pipeline` |
 | fixed-view diagnostics, seed sweeps, temporal and budget evidence | `$genex-threejs-visual-validation` |
-| realtime multiplayer: movement sync, shared state, presence, shots/emotes, persistence | `$genex-threejs-multiplayer` |
+| realtime multiplayer: movement sync, a shared ball/NPC, host-run scores/enemies, 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.
+`$genex-threejs-multiplayer` is **required** before any networking code — the SDK auto-smooths
+remote players **and shared objects**, and gives you server-enforced object ownership (a ball) and
+a room `host` (scores, enemies). That skill covers the rules that keep it smooth and its per-genre
+recipes (sports/ball, shooter, co-op).
 
 ## Real (AI-generated) assets — `npx genex` commands
 

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

@@ -54,8 +54,11 @@ publishing or multiplayer, inspect the project first. Prefer clean boundaries:
 
 **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.
+optional. The `@genex-ai/multiplayer` relay syncs `me`/`shared`/`objects`; the **SDK
+auto-smooths remote players AND shared objects** for you (do not write your own
+interpolation). It gives you server-enforced primitives — `objects` (one owner per ball/
+NPC, claimed on contact) and a room `host` (single writer of scores, single simulator of
+enemies). That skill covers the rules that keep it smooth (draw `state` directly, render
+yourself and objects you own from a local object, quaternion rotation, `stateRaw` for
+hit-tests), the per-genre recipes (sports/ball, shooter, co-op), config wiring, and the
+persistent-world API. Use only the APIs that skill documents — do not invent transport methods.