@genex-ai/cli-demo 0.14.2 → 0.16.0

package/dist/index.js

@@ -1110,6 +1110,24 @@ async function detectMultiplayer(cwd = process.cwd()) {
     return false;
   }
 }
+async function detectMatchmaking(log, cwd = process.cwd()) {
+  let pkg;
+  try {
+    pkg = JSON.parse(await fs8.readFile(path9.join(cwd, "package.json"), "utf8"));
+  } catch (err) {
+    log.dim(`  (skipping matchmaking \u2014 couldn't read package.json: ${String(err)})`);
+    return null;
+  }
+  const mm = pkg.genex?.matchmaking;
+  if (mm && typeof mm.preset === "string" && mm.preset) {
+    return {
+      preset: mm.preset,
+      ...mm.winCondition ? { winCondition: mm.winCondition } : {},
+      ...mm.config ? { config: mm.config } : {}
+    };
+  }
+  return null;
+}
 async function runPublish(opts) {
   const log = createLogger({ quiet: opts.quiet });
   log.plain(c.bold("genex publish"));
@@ -1151,6 +1169,8 @@ async function runPublish(opts) {
     const embedSdkVersion = await detectEmbedSdkVersion();
     if (embedSdkVersion) body.embedSdkVersion = embedSdkVersion;
     body.multiplayer = await detectMultiplayer();
+    const matchmaking = await detectMatchmaking(log);
+    if (matchmaking) body.matchmaking = matchmaking;
     res = await fetch(`${apiUrl}/api/projects/${meta.id}/publish`, {
       method: "POST",
       headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.14.2",
+  "version": "0.16.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-threejs-embed-auth/SKILL.md

@@ -1,15 +1,16 @@
 ---
 name: genex-threejs-embed-auth
-description: Wire up player identity for a Genex game via @genex-ai/embed-sdk. Load this UNCONDITIONALLY for every game, multiplayer or not, BEFORE writing any boot code — every player gets an identity (signed-in account or guest); saving progress requires sign-in, and multiplayer requires the SDK's token either way.
+description: Wire up player identity AND durable game state for a Genex game via @genex-ai/embed-sdk. Load this UNCONDITIONALLY for every game, multiplayer or not, BEFORE writing any boot code — every player gets an identity (signed-in account or guest); per-player saves, shared world state, and leaderboards are one-line SDK calls; multiplayer requires the SDK's token either way.
 ---
 
 # Genex Three.js Embed Auth
 
-`@genex-ai/embed-sdk` is how a Genex game learns **who is playing it**. Every
-game needs it. Published games are playable by **guests** (no account — the
-SDK mints a temporary identity like `Guest-1234` automatically), while
-**signing in** unlocks saving/loading progress; multiplayer works for both,
-using the SDK's token. The SDK handles every context with one
+`@genex-ai/embed-sdk` is how a Genex game learns **who is playing it** — and
+how it **saves**. Every game needs it. Published games are playable by
+**guests** (no account — the SDK mints a temporary identity like `Guest-1234`
+automatically), while **signing in** unlocks saving/loading progress (each
+player gets their own save slot) and leaderboard entries; multiplayer works
+for both, using the SDK's token. The SDK handles every context with one
 `initEmbed(...)` call:
 
 - **Embedded in the Genex dashboard (an iframe):** a silent handshake signs
@@ -102,10 +103,10 @@ boot-path gate; `waitForAuth()` guards saves only.
   synchronous.
 - `getUser()` → `{ id, name, image? } | null` — non-null once authenticated OR
   guest. Guest ids are prefixed `guest:`.
-- `getEmbedToken()` → `string | undefined` — for `Authorization: Bearer` on
-  `GET`/`PUT ${GENEX.apiUrl}/api/projects/${GENEX.slug}/state`. Defined for
-  guests too, but `/state` answers guests with `403 { "error": "guest_no_save" }`
-  — that's why saves gate on `waitForAuth()`, not on the token existing.
+- `getEmbedToken()` → `string | undefined` — the raw token, for the RARE
+  advanced case of calling the Genex API by hand. The state/leaderboard
+  helpers below attach it automatically — prefer them; never hand-roll fetch
+  calls to `/state` endpoints.
 - `getColyseusAuth()` → `{ embedToken } | undefined` — pass as `connect()`'s
   `auth` option (REQUIRED — the relay rejects tokenless joins; guest tokens
   are accepted). Read it fresh at every `connect()` call; tokens rotate
@@ -114,6 +115,31 @@ boot-path gate; `waitForAuth()` guards saves only.
   `"blocked"`, `"error"`. A mid-game sign-in fires `"authenticated"` after
   `"guest"` — progress saving can start right then, no reload.
 
+Durable state + leaderboards (all six are safe to call from boot — they wait
+for identity internally, never throw for guests, and reject only when the
+session is blocked):
+
+- `loadPlayerState()` → `Promise<{ data, version, guest? }>` — THIS player's
+  own save (per-player, per-game; other players can never read or overwrite
+  it). `{ data: null, version: 0 }` when they never saved.
+- `savePlayerState(data, { ifVersion? }?)` → `Promise<{ saved, version?,
+  conflict?, guest?, queued? }>` — save any JSON ≤ 256KB to their slot. For
+  guests the value is QUEUED in memory and auto-flushed if they sign in
+  mid-game — no extra code. Small saves survive tab close automatically.
+- `loadWorldState()` / `saveWorldState(data, { ifVersion? }?)` — the game's
+  ONE shared world slot (≤ 1MB, every player reads/writes the same blob) —
+  level layouts, persistent-world object positions. Multiplayer games: only
+  the host writes it (see the multiplayer skill). Always pass `ifVersion`
+  here (shared slot = real races); a losing write resolves
+  `{ conflict: true, version }` — reload, merge, retry.
+- `submitScore(score, { board?, mode? }?)` → `Promise<{ submitted, best?,
+  improved?, guest?, queued? }>` — keep-best leaderboard submit (`mode:
+  "min"` for lap-time boards). Guests: best value queues, flushes on sign-in.
+- `getLeaderboard({ board?, limit?, order? }?)` → `Promise<{ items, me }>` —
+  top entries (verified display names — never trust client-side name input
+  for this) + the signed-in player's own `{ rank, score }`. Works for guests
+  too (`me: null`).
+
 From `@genex-ai/embed-sdk/sentry` (crash reporting; exactly these two):
 
 - `initGameSentry({ slug, dsn?, environment? })` — call once, BEFORE
@@ -134,30 +160,53 @@ function animate() {
 }
 ```
 
-## Saving progress with guests around
+## Saving progress (per-player — every player has their own slot)
 
-Guests play but cannot save — design the save path accordingly:
+Use the SDK helpers; never hand-roll fetch calls to the state API. Progression,
+inventory, unlocks — anything about ONE player — goes in their player slot:
 
 ```ts
-// Fire-and-forget save that is simply OFF for guests:
-async function saveProgress(data: unknown) {
-  const token = getEmbedToken();
-  if (getAuthState() !== "authenticated" || !token) return; // guest: skip silently
-  await fetch(`${GENEX.apiUrl}/api/projects/${GENEX.slug}/state`, {
-    method: "PUT",
-    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
-    body: JSON.stringify(data),
-  });
-}
+import { loadPlayerState, savePlayerState } from "@genex-ai/embed-sdk";
+
+// boot: load whatever this player saved last time (fine for guests — resolves
+// { data: null, guest: true } instead of failing)
+const { data } = await loadPlayerState();
+applyProgress(data ?? defaultProgress());
+
+// checkpoints / level-ups: fire-and-forget, DEBOUNCED (not per frame)
+void savePlayerState(progress);
+```
+
+Guests need zero special handling: their saves queue in memory and auto-flush
+the moment they sign in mid-game (so a guest's progress follows them into
+their new account), and `waitForAuth()` resolving is the signal that a real
+account now exists. The SDK already tells guests to sign in (its popover / the
+dashboard's card) — don't add another prompt.
+
+**Per-player vs world:** `savePlayerState` is each player's own progress;
+`saveWorldState` is the game's ONE shared world (persistent-world layouts —
+see the multiplayer skill's persistence section for the host-writes pattern).
+Never store per-player progression in the world slot: every player of the
+game shares that single blob.
+
+## Leaderboards
+
+```ts
+import { submitScore, getLeaderboard } from "@genex-ai/embed-sdk";
+
+// on game over / lap complete — keep-best, so just submit every run
+void submitScore(finalScore);                            // higher is better
+void submitScore(lapMs, { board: "laps", mode: "min" }); // lower is better
 
-// And start loading/saving the moment a guest upgrades mid-game:
-waitForAuth().then(({ user }) => {
-  // signed in (possibly after starting as a guest) — load their save now
-}).catch(() => { /* blocked — SDK overlay owns the UX */ });
+// render a top-10 + the player's own rank
+const { items, me } = await getLeaderboard({ limit: 10 });
 ```
 
-The SDK already tells guests to sign in (its popover / the dashboard's card) —
-don't add another prompt.
+Scores are per-account (one row per player per board, real display names from
+their Genex account) and keep-best — submitting a worse score changes nothing
+(`improved: false`). Guests can READ leaderboards; their submits queue and
+post when they sign in. Send a consistent `mode` per board. Scores are
+client-reported (arcade-style trust) — don't present them as anti-cheat.
 
 ## Crash reporting rules
 
@@ -216,9 +265,13 @@ concerns.
 - [ ] `genex.config.ts` includes `dashboardOrigins` (from `.genex/project.json`).
 - [ ] Multiplayer `connect()` and player-name UI await `waitForPlayer()` —
       NEVER `waitForAuth()` (guests would hang forever).
-- [ ] `/state` load/save gates on `waitForAuth()` / `getAuthState() ===
-      "authenticated"` and sends `Authorization: Bearer ${getEmbedToken()}`;
-      guests skip saves silently (the server answers them `403 guest_no_save`).
+- [ ] Saves/loads use the SDK helpers (`savePlayerState`/`loadPlayerState` for
+      per-player progress, `saveWorldState`/`loadWorldState` for the shared
+      world, `submitScore`/`getLeaderboard` for scores) — no hand-rolled fetch
+      to `/state` endpoints, no manual guest gating (the helpers own it).
+- [ ] Per-player progression lives in the PLAYER slot, never in the shared
+      world slot.
+- [ ] Saves are debounced (checkpoints/level-ups), not per-frame.
 - [ ] No token value is ever logged or sent to analytics.
 - [ ] No custom sign-in prompt, guest badge, or auth overlay — the SDK popover/
       overlay and the dashboard own all of that UX.
@@ -241,6 +294,12 @@ concerns.
 - **Multiplayer join rejected with 403 "guest capacity"** — the room is at its
   guest limit; only signing in gets the player a seat right now. Surface the
   relay's message as-is.
-- **`/state` returns 401/403** — missing `Authorization` header (401), a guest
-  token (403 `guest_no_save` — expected, skip saves for guests), or the token
-  belongs to a different game (403): `GENEX.slug` doesn't match this project.
+- **`/state` returns 401/403 (hand-rolled fetch)** — missing `Authorization`
+  header (401), a guest token (403 `guest_no_save`), or the token belongs to a
+  different game (403). All three mean the code bypassed the SDK helpers —
+  switch to `savePlayerState`/`saveWorldState`, which handle every case.
+- **`saveWorldState` resolves `{ conflict: true }`** — another player wrote the
+  shared slot since your last read. Expected under concurrency: reload with
+  `loadWorldState()`, merge, retry with the fresh `version`. If it happens
+  constantly, more than one client is acting as the writer — in multiplayer,
+  only the host should save the world.

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

@@ -37,7 +37,62 @@ example, the shared-object/ball code, rotation, and host usage. Read
 npm i @genex-ai/multiplayer
 ```
 
-`objects` and `host` need `@genex-ai/multiplayer` **≥ 0.4.0**.
+This skill targets `@genex-ai/multiplayer` **≥ 0.7.0** (`objects`/`host` since 0.4; `matchmake()` since 0.5; presets + `score()`/`finish()` since 0.6; `createPrivate()`/`joinPrivate()` since 0.7).
+
+## Matchmaking (competitive presets — server-owned)
+
+When players should be **matched into separate capped rooms** rather than share one big room (a 1v1
+duel, an FFA arena, N-v-N teams, an invite lobby), use `matchmake()` instead of `connect()`. It
+returns a handle whose **`session` is `null` while searching** — render your OWN "finding a match…"
+HUD from `mm.matchmaking` (its `status`, `queue.position`, `players`/`opponents`, `teams`, `scores`,
+`winCondition`), and switch to the game once `session` goes live:
+
+```ts
+// Pass auth as a FUNCTION — one matchmake() handle re-joins the queue/match many times (re-search,
+// requeue) over a session, and embed tokens rotate (~10 min). A function is read fresh each (re)join;
+// a static object goes stale and gets rejected mid-session.
+const mm = await matchmake<MyState>({ url, room: slug, auth: () => getColyseusAuth() });
+mm.on('matched', () => {/* session is live — start the game */});
+// each frame: if (mm.session) renderGame(mm.session); else renderSearchingHud(mm.matchmaking);
+mm.on('matchEnded', ({ winnerId, scores, draw }) => {/* result screen */});
+mm.on('error', (e) => {/* a (re)join failed, e.g. auth — usually transient; the handle keeps searching */});
+
+// Report ONLY your own outcome — the server adjudicates. Which call fits depends on the win condition:
+mm.eliminated();   // I'm out              (lastStanding)
+mm.score(1);       // I scored             (firstToScore / highScoreInTime)
+mm.finish();       // I finished the race  (firstToFinish)
+```
+
+Everything is **server-owned** — set once in `package.json` under `genex.matchmaking`, reported at
+publish; the client declares nothing. You never run matchmaking logic: the server owns the queue,
+roles, winner-stays, forfeit, timeout, and the win condition.
+
+```jsonc
+"genex": {
+  "matchmaking": {
+    "preset": "arena",                 // duel | arena | teams | private
+    "winCondition": "firstToScore",    // lastStanding | firstToScore | highScoreInTime | firstToFinish
+    "config": { "scoreTarget": 20, "maxPlayers": 8 }   // numeric knobs, optional
+  }
+}
+```
+
+Presets: **duel** (1v1 winner-stays), **arena** (N-player FFA, join-anytime), **teams** (balanced
+N-v-N), **private** (invite-code lobby). Win conditions: **lastStanding** (last one alive),
+**firstToScore** (first to the score target), **highScoreInTime** (top score at the time cap),
+**firstToFinish** (first to finish). A round that hits the time cap undecided is a draw.
+
+**Private lobbies** (for `preset: 'private'`) don't use `matchmake()` — a host makes an invite code
+and friends join it; the lobby is persistent (rounds replay, nobody is evicted):
+
+```ts
+import { createPrivate, joinPrivate } from "@genex-ai/multiplayer";
+const lobby = await createPrivate<MyState>({ url, room: slug, auth: () => getColyseusAuth() });  // live NOW
+showCode(lobby.code);                                                   // share this
+// a friend, elsewhere:
+const lobby = await joinPrivate<MyState>(code, { url, room: slug, auth: () => getColyseusAuth() });
+// same handle API as matchmake(): lobby.session, lobby.matchmaking, eliminated()/score()/finish(), cancel()
+```
 
 ## Connect
 
@@ -207,38 +262,42 @@ 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, from **one authority** (the host):
-
-Both calls **require a signed-in identity** (`Authorization: Bearer` with the token
-from `getEmbedToken()`) — guests play multiplayer but cannot read or write saves
-(the server answers their token `403 guest_no_save`). Gate them on
-`await waitForAuth()` — the ACCOUNT gate, deliberately stricter than the
-`waitForPlayer()` gate `connect()` uses (see the `genex-threejs-embed-auth` skill):
+that persists (a driven car stays where it was parked, built structures survive), save/load the
+game's shared world slot via the embed SDK, from **one authority** (the host):
 
 ```ts
-import { getEmbedToken } from "@genex-ai/embed-sdk";
+import { loadWorldState, saveWorldState } 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());
+// load on boot (safe to call immediately — waits for identity internally;
+// guests resolve { data: null, guest: true } and receive the live world
+// through the room instead)
+const { data, version } = await loadWorldState();
 initWorld(data ?? defaultWorld());
-
-// 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",
-    Authorization: `Bearer ${getEmbedToken()}`,
-  },
-  body: JSON.stringify(world),
-});
+let worldVersion = version;
+
+// save from ONE authority — the elected host — debounced, WITH ifVersion so a
+// stale host handoff loses loudly instead of silently clobbering:
+async function persistWorld(world: unknown) {
+  if (!room.isHost) return;
+  const res = await saveWorldState(world, { ifVersion: worldVersion });
+  if (res.saved) worldVersion = res.version!;
+  else if (res.conflict) {
+    // someone else wrote since our read (host migration race) — resync
+    const fresh = await loadWorldState();
+    worldVersion = fresh.version;
+    mergeWorld(fresh.data);
+  }
+  // res.guest: this host is a guest (guest-only room) — saving is off until a
+  // signed-in player joins; the relay prefers signed-in hosts automatically.
+}
 ```
 
-`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.
+The slot is one JSON blob per game (≤ 1 MB) shared by every player — world layout only,
+NEVER per-player progression (that belongs in each player's own `savePlayerState()` slot —
+see the embed-auth skill). Don't save every frame: debounce (~1/sec), and also flush on
+`document.visibilitychange === "hidden"` so the last edits survive the host closing the tab.
+Guests can't write it, but the relay elects a signed-in host whenever one is present, so
+host-driven saving works as long as ANY account is in the room.
 
 ## Checklist
 

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

@@ -183,35 +183,50 @@ const px = t.stateRaw.x, pz = t.stateRaw.z;   // test against the raw latest
 ## Persistence helper
 
 ```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";
+// persistence.ts — the embed SDK owns tokens, guest handling, and conflict
+// decoding (see the genex-threejs-embed-auth skill). World slot = shared
+// layout only; per-player progression goes in savePlayerState() instead.
+import { loadWorldState, saveWorldState } from "@genex-ai/embed-sdk";
+
+let worldVersion = 0;
 
 export async function loadWorld<T>(fallback: T): Promise<T> {
   try {
-    const { data } = await fetch(`${GENEX.apiUrl}/api/projects/${GENEX.slug}/state`, {
-      headers: { Authorization: `Bearer ${getEmbedToken()}` },
-    }).then(r => r.json());
+    const { data, version } = await loadWorldState(); // waits for identity itself
+    worldVersion = version;
     return (data as T) ?? fallback;
   } catch { return fallback; }
 }
 
 let saveTimer: ReturnType<typeof setTimeout> | null = null;
+let latest: unknown;
 export function saveWorld(world: unknown) {
-  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",
-        Authorization: `Bearer ${getEmbedToken()}`,
-      },
-      body: JSON.stringify(world),
-    }).catch(() => {});
-  }, 1000);
+  latest = world;                            // debounce: at most one write/sec, host only
+  if (saveTimer) return;
+  saveTimer = setTimeout(() => { saveTimer = null; void flushWorld(); }, 1000);
+}
+
+async function flushWorld() {
+  const res = await saveWorldState(latest, { ifVersion: worldVersion }).catch(() => null);
+  if (!res) return;
+  if (res.saved) worldVersion = res.version!;
+  else if (res.conflict) worldVersion = res.version!; // stale after a host race — next save wins
 }
+
+// The host closing their tab must not lose the last edits: flush immediately
+// when the page goes hidden (savePlayerState/saveWorldState small writes ride
+// fetch keepalive, so this completes even mid-unload).
+document.addEventListener("visibilitychange", () => {
+  if (document.visibilityState === "hidden" && saveTimer) {
+    clearTimeout(saveTimer);
+    saveTimer = null;
+    void flushWorld();
+  }
+});
 ```
 
-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.
+State is one JSON blob per project, max 1 MB, shared by every player. Save from a single
+authority (`room.isHost`) so concurrent writers don't clobber each other; `ifVersion` turns
+any remaining race into a visible `conflict` instead of silent data loss. Guests can't
+write it — the relay prefers signed-in players as host, so saving works whenever any
+account is in the room (guest-only rooms simply don't persist until one joins).