@genex-ai/multiplayer 0.4.0 → 0.7.0

package/README.md

@@ -169,6 +169,68 @@ onKey('right', () => { me.x += 1; });
 
 ---
 
+## `matchmake` — competitive matches (server-owned)
+
+When players should be **matched into separate capped rooms** instead of sharing one big room (1v1, FFA, teams, invite lobby), use `matchmake()` instead of `connect()`. The queue, roles, winner-stays, forfeit, timeout, and win condition are all **server-owned** — the client declares nothing and runs no matchmaking logic.
+
+```ts
+import { matchmake } from "@genex-ai/multiplayer";
+
+// Pass `auth` as a FUNCTION — a handle re-joins many times (re-search/requeue) and tokens rotate
+// (~10 min); a function is read fresh each join, a static object goes stale mid-session.
+const mm = await matchmake<State>({ url, room: slug, auth: () => getColyseusAuth() });
+
+// `session` is null WHILE SEARCHING — render your own "finding a match…" HUD until it goes live.
+// each frame:
+if (mm.session) renderGame(mm.session);        // a live Session (same API as connect())
+else renderSearchingHud(mm.matchmaking);
+
+mm.on("matched", () => {/* session is live */});
+mm.on("matchStart", ({ roundId }) => {/* round began */});
+mm.on("matchEnded", ({ winnerId, scores, draw }) => {/* result screen */});
+mm.on("spectate", () => {/* seated as a spectator (overflow) — read-only */});
+
+// Report ONLY your own outcome — the server adjudicates. Pick the call that matches the win condition:
+mm.eliminated();   // I'm out              (lastStanding)
+mm.score(1);       // I scored             (firstToScore / highScoreInTime)
+mm.finish();       // I finished the race  (firstToFinish)
+
+mm.cancel();       // stop searching / leave the match
+```
+
+**`mm.matchmaking`** (read every frame for your HUD): `status` (`searching` | `waiting` | `countdown` | `playing` | `ended` | `spectating`), `queue` (`{ position, size }`), `players`, `opponents`, `teams`, `myTeam`, `scores`, `winCondition`, `config` (numeric knobs), `roundId`, `winnerId`, `message`. `championId`/`challengerId` are 1v1 aliases.
+
+Configure once in the game's `package.json` (reported at publish; never sent from the client):
+
+```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**, **firstToScore**, **highScoreInTime**, **firstToFinish**; a round that hits the time cap undecided is a draw.
+
+### Private lobbies — `createPrivate` / `joinPrivate`
+
+For `preset: 'private'` games, skip the queue: a host mints an invite **code**, friends join it, and everyone lands in the SAME persistent lobby (rounds replay, nobody is evicted). Both handles have the same shape as `matchmake()`, but `session` is live on return (no searching phase).
+
+```ts
+import { createPrivate, joinPrivate } from "@genex-ai/multiplayer";
+
+// host
+const lobby = await createPrivate<State>({ url, room: slug, auth: () => getColyseusAuth() });
+share(lobby.code);                 // e.g. show it in the UI
+
+// friend (elsewhere)
+const joined = await joinPrivate<State>(code, { url, room: slug, auth: () => getColyseusAuth() });
+
+// then identical to matchmake(): .session, .matchmaking, eliminated()/score()/finish(), cancel()
+```
+
 ## Rules of thumb
 
 - **`me` / `shared` are synced; everything else is local.** Movement input → mutate a local object → `me.set` it on the tick.
@@ -181,13 +243,18 @@ onKey('right', () => { me.x += 1; });
 
 ## Persistent worlds (optional)
 
-The relay is in-memory — room state is gone when everyone leaves or the server restarts. To persist world state across restarts, save/load a JSON blob via the API (keyed by the project slug):
+The relay is in-memory — room state is gone when everyone leaves or the server restarts. To persist world state across restarts, use `@genex-ai/embed-sdk`'s state helpers (they own auth tokens, guest handling, and write-conflict decoding):
 
 ```ts
+import { loadWorldState, saveWorldState } from '@genex-ai/embed-sdk';
+
 // load on boot
-const { data } = await fetch(`${API}/api/projects/${slug}/state`).then(r => r.json());
+const { data, version } = await loadWorldState();
 initWorld(data ?? defaultWorld());
 
-// save whenever (from ONE authority — e.g. a host client — to avoid races)
-fetch(`${API}/api/projects/${slug}/state`, { method: 'PUT', body: JSON.stringify(world) });
+// save (from ONE authority — the elected host — debounced, with ifVersion so
+// races surface as { conflict: true } instead of silently clobbering)
+if (room.isHost) await saveWorldState(world, { ifVersion: version });
 ```
+
+The relay prefers signed-in players when electing the host (guests cannot write saves), so host-driven persistence works whenever any account is in the room. Per-player progression belongs in `savePlayerState()` (each player's own slot), never in the shared world blob.

package/dist/index.d.ts

@@ -128,5 +128,97 @@ type Session<TState extends Record<string, unknown>> = {
  * automatically (entity interpolation) — `state` is smooth, `stateRaw` is raw.
  */
 declare function connect<TState extends Record<string, unknown> = never>(opts: ConnectOptions): Promise<Session<TState>>;
+type MatchStatus = 'searching' | 'waiting' | 'countdown' | 'playing' | 'ended' | 'spectating';
+type MatchmakingView = {
+    status: MatchStatus;
+    role: 'player' | 'spectator';
+    /** Your place in the search line while `status === 'searching'`. */
+    queue: {
+        position: number;
+        size: number;
+    };
+    /** Every active participant id (N-player: 1v1, FFA, teams). */
+    players: string[];
+    /** The other active player id(s) — everyone in `players` except you. */
+    opponents: string[];
+    /** teamId -> member ids for team presets; empty for FFA + 1v1. */
+    teams: Record<string, string[]>;
+    /** Your team id, if the preset uses teams and you're an active player; else null. */
+    myTeam: string | null;
+    scores: Record<string, number>;
+    /** The server-owned numeric preset knobs in effect (e.g. { countdownMs, maxRoundMs, scoreTarget }). */
+    config: Record<string, number>;
+    /** The win condition this game runs: 'lastStanding' | 'firstToScore' | 'highScoreInTime' | 'firstToFinish'. */
+    winCondition: string;
+    /** 1v1 (duel) convenience aliases; null for presets without a champion/challenger role. */
+    championId: string | null;
+    challengerId: string | null;
+    roundId: number;
+    /** Winner of the round shown while `status === 'ended'` (competitor id; null on a draw). */
+    winnerId: string | null;
+    message: string;
+};
+type Matchmaking<TState extends Record<string, unknown>> = {
+    /** The live game session, or null while searching for a match. */
+    readonly session: Session<TState> | null;
+    /** Read every frame to render your matchmaking HUD. */
+    readonly matchmaking: MatchmakingView;
+    /**
+     * searching: (re)entered the queue. queue: your position changed ({position,size}).
+     * matched: `session` is now live. matchStart: a round began ({roundId}).
+     * matchEnded: {winnerId,loserId,draw,scores}. spectate: you're watching, not playing.
+     */
+    on(event: 'searching' | 'queue' | 'matched' | 'matchStart' | 'matchEnded' | 'spectate' | 'error', cb: (payload?: unknown) => void): () => void;
+    /** Report your OWN elimination (the `lastStanding` win condition). */
+    eliminated(): void;
+    /** Report a score delta for yourself (the `firstToScore` / `highScoreInTime` conditions). */
+    score(delta?: number): void;
+    /** Report that you finished (the `firstToFinish` win condition — a race). */
+    finish(): void;
+    /** Stop searching / leave the current match. */
+    cancel(): void;
+};
+type MatchmakeOptions = {
+    /** Colyseus server url. */
+    url: string;
+    /** Game id (your project slug/id) — isolates this game's matchmaking. */
+    room: string;
+    name?: string;
+    /**
+     * Verified-identity credential (see ConnectOptions.auth). Required to join. Tokens rotate (~10 min),
+     * and a single matchmake() handle re-joins the queue/match many times over its life (re-search,
+     * requeue). Pass a FUNCTION — `() => genexEmbed.getColyseusAuth()` — so each (re)join reads a FRESH
+     * token; a static object is read only once and will be rejected once it expires.
+     */
+    auth?: {
+        embedToken: string;
+    } | (() => {
+        embedToken: string;
+    } | undefined);
+};
+/**
+ * Join a game's matchmaking. Returns immediately in the SEARCHING state (`session` is null); the
+ * matchmaker seats you into a match room, at which point `session` becomes a live Session and a
+ * `matched` event fires. The preset + config are owned by the project (server-side).
+ */
+declare function matchmake<TState extends Record<string, unknown> = never>(opts: MatchmakeOptions): Promise<Matchmaking<TState>>;
+/** A private lobby handle — a Matchmaking whose `session` is live immediately, plus the invite `code`. */
+type PrivateMatch<TState extends Record<string, unknown>> = Matchmaking<TState> & {
+    /** Share this with friends; they pass it to `joinPrivate()` to land in the SAME lobby. */
+    readonly code: string;
+};
+/**
+ * Create a PRIVATE lobby for a game and return a shareable invite `code`. Unlike matchmake() there's
+ * no queue: you're the host, `session` is live immediately, and friends join the SAME lobby with
+ * `joinPrivate(code, …)`. The preset + rules are still server-owned (the game's config) — a game that
+ * wants invite lobbies publishes `preset: 'private'`, a persistent lobby that replays rounds without
+ * evicting anyone.
+ */
+declare function createPrivate<TState extends Record<string, unknown> = never>(opts: MatchmakeOptions): Promise<PrivateMatch<TState>>;
+/**
+ * Join an existing private lobby by its invite `code` (from createPrivate()). `session` is live on
+ * return — render the game immediately (there is no searching phase for a private lobby).
+ */
+declare function joinPrivate<TState extends Record<string, unknown> = never>(code: string, opts: MatchmakeOptions): Promise<Matchmaking<TState>>;
 
-export { type ConnectOptions, type ObjectView, type PlayerView, type Session, connect };
+export { type ConnectOptions, type MatchStatus, type MatchmakeOptions, type Matchmaking, type MatchmakingView, type ObjectView, type PlayerView, type PrivateMatch, type Session, connect, createPrivate, joinPrivate, matchmake };

package/dist/index.js

@@ -1,6 +1,8 @@
 // src/index.ts
 import { Client, getStateCallbacks } from "colyseus.js";
 var RELAY_ROOM_TYPE = "play";
+var QUEUE_ROOM_TYPE = "queue";
+var MATCH_ROOM_TYPE = "match";
 var INTERP_RATIO = 1.5;
 var INTERP_MIN_MS = 50;
 var INTERP_MAX_MS = 300;
@@ -13,6 +15,7 @@ var SEND_TIME_KEY = "__t";
 var RESERVED_PREFIX = "__";
 var OBJ_PREFIX = "__obj:";
 var HOST_KEY = "__host";
+var MATCH_KEY = "__match";
 var MP_PROTOCOL = 1;
 function parseData(s) {
   if (!s) return { state: {} };
@@ -132,6 +135,9 @@ async function connect(opts) {
     __v: MP_PROTOCOL
     // tells the relay this client hides reserved `__` keys (see MP_PROTOCOL)
   });
+  return attachSession(room);
+}
+function attachSession(room) {
   const buffers = /* @__PURE__ */ new Map();
   const lastStamp = /* @__PURE__ */ new Map();
   const clockOffsets = /* @__PURE__ */ new Map();
@@ -226,6 +232,7 @@ async function connect(opts) {
   const handleShared = (value, key) => {
     if (lastShared.get(key) === value) return;
     lastShared.set(key, value);
+    if (key === MATCH_KEY) return;
     if (key === HOST_KEY) {
       const next = parseValue(value) || void 0;
       if (next !== hostId) {
@@ -389,6 +396,222 @@ async function connect(opts) {
     }
   };
 }
+var resolveAuth = (auth) => typeof auth === "function" ? auth() : auth;
+var matchJoinOptions = (opts) => ({
+  gameId: opts.room,
+  name: opts.name,
+  embedToken: resolveAuth(opts.auth)?.embedToken,
+  __v: MP_PROTOCOL
+});
+function buildView(matchRoom, queueInfo) {
+  const raw = matchRoom?.state?.shared?.get(MATCH_KEY);
+  const parsed = raw != null ? parseValue(raw) : null;
+  const m = parsed && typeof parsed === "object" ? parsed : null;
+  if (!m) {
+    return {
+      status: matchRoom ? "waiting" : "searching",
+      role: "player",
+      queue: queueInfo,
+      players: [],
+      opponents: [],
+      teams: {},
+      myTeam: null,
+      scores: {},
+      config: {},
+      winCondition: "lastStanding",
+      championId: null,
+      challengerId: null,
+      roundId: 0,
+      winnerId: null,
+      message: matchRoom ? "Waiting for players\u2026" : "Finding a match\u2026"
+    };
+  }
+  const myId = matchRoom?.sessionId;
+  const championId = m.championId ?? null;
+  const challengerId = m.challengerId ?? null;
+  const teams = m.teams ?? {};
+  const players = m.players ?? [championId, challengerId].filter((x) => !!x);
+  const isPlayer = myId != null && players.includes(myId);
+  const status = isPlayer ? m.phase : "spectating";
+  const opponents = players.filter((id) => id !== myId);
+  const myTeam = myId ? Object.keys(teams).find((t) => teams[t]?.includes(myId)) ?? null : null;
+  const { winCondition: wc, ...numericCfg } = m.cfg ?? {};
+  return {
+    status,
+    role: isPlayer ? "player" : "spectator",
+    queue: { position: 0, size: 0 },
+    players,
+    opponents,
+    teams,
+    myTeam,
+    scores: m.scores ?? {},
+    config: numericCfg,
+    winCondition: wc?.type ?? "lastStanding",
+    championId,
+    challengerId,
+    roundId: m.roundId ?? 0,
+    winnerId: m.winnerId ?? null,
+    message: m.message ?? ""
+  };
+}
+async function matchmake(opts) {
+  const client = new Client(opts.url);
+  const emitters = /* @__PURE__ */ new Map();
+  const emit = (event, ...args) => emitters.get(event)?.forEach((cb) => cb(...args));
+  const on = ((event, cb) => {
+    let set = emitters.get(event);
+    if (!set) emitters.set(event, set = /* @__PURE__ */ new Set());
+    set.add(cb);
+    return () => void set?.delete(cb);
+  });
+  let session = null;
+  let matchRoom = null;
+  let queueRoom = null;
+  let queueInfo = { position: 0, size: 0 };
+  let cancelled = false;
+  const search = async () => {
+    if (cancelled) return;
+    session = null;
+    matchRoom = null;
+    if (queueRoom) {
+      void queueRoom.leave();
+      queueRoom = null;
+    }
+    queueInfo = { position: 0, size: 0 };
+    let q;
+    try {
+      q = await client.joinOrCreate(QUEUE_ROOM_TYPE, matchJoinOptions(opts));
+    } catch (err) {
+      if (!cancelled) emit("error", err);
+      return;
+    }
+    if (cancelled) {
+      void q.leave();
+      return;
+    }
+    queueRoom = q;
+    q.onMessage("queue", (msg) => {
+      queueInfo = { position: msg.position, size: msg.size };
+      emit("queue", msg);
+    });
+    q.onMessage(
+      "seat",
+      (msg) => void consumeSeat(msg.reservation, msg.role)
+    );
+    emit("searching");
+  };
+  const consumeSeat = async (reservation, role) => {
+    try {
+      const mr = await client.consumeSeatReservation(reservation);
+      if (cancelled) {
+        void mr.leave();
+        return;
+      }
+      matchRoom = mr;
+      session = attachSession(mr);
+      mr.onMessage("match:start", (m) => emit("matchStart", m));
+      mr.onMessage("match:ended", (m) => emit("matchEnded", m));
+      mr.onMessage("match:requeue", () => void requeue());
+      if (queueRoom) {
+        void queueRoom.leave();
+        queueRoom = null;
+      }
+      emit("matched");
+      if (role === "spectator") emit("spectate");
+    } catch {
+      void search();
+    }
+  };
+  const requeue = async () => {
+    if (matchRoom) {
+      void matchRoom.leave();
+      matchRoom = null;
+    }
+    session = null;
+    await search();
+  };
+  await search();
+  return {
+    get session() {
+      return session;
+    },
+    get matchmaking() {
+      return buildView(matchRoom, queueInfo);
+    },
+    on,
+    eliminated() {
+      matchRoom?.send("match:eliminated", {});
+    },
+    score(delta = 1) {
+      matchRoom?.send("match:score", { delta });
+    },
+    finish() {
+      matchRoom?.send("match:finish", {});
+    },
+    cancel() {
+      cancelled = true;
+      if (matchRoom) void matchRoom.leave();
+      if (queueRoom) void queueRoom.leave();
+      matchRoom = null;
+      queueRoom = null;
+      session = null;
+    }
+  };
+}
+function wirePrivate(client, room) {
+  const emitters = /* @__PURE__ */ new Map();
+  const emit = (event, ...args) => emitters.get(event)?.forEach((cb) => cb(...args));
+  const on = ((event, cb) => {
+    let set = emitters.get(event);
+    if (!set) emitters.set(event, set = /* @__PURE__ */ new Set());
+    set.add(cb);
+    return () => void set?.delete(cb);
+  });
+  let matchRoom = room;
+  const session = attachSession(room);
+  room.onMessage("match:start", (m) => emit("matchStart", m));
+  room.onMessage("match:ended", (m) => emit("matchEnded", m));
+  room.onMessage("match:requeue", () => void (matchRoom = null));
+  room.onLeave(() => void (matchRoom = null));
+  return {
+    get session() {
+      return matchRoom ? session : null;
+    },
+    get matchmaking() {
+      return buildView(matchRoom, { position: 0, size: 0 });
+    },
+    on,
+    eliminated() {
+      matchRoom?.send("match:eliminated", {});
+    },
+    score(delta = 1) {
+      matchRoom?.send("match:score", { delta });
+    },
+    finish() {
+      matchRoom?.send("match:finish", {});
+    },
+    cancel() {
+      if (matchRoom) void matchRoom.leave();
+      matchRoom = null;
+      void client;
+    }
+  };
+}
+async function createPrivate(opts) {
+  const client = new Client(opts.url);
+  const room = await client.create(MATCH_ROOM_TYPE, matchJoinOptions(opts));
+  const handle = wirePrivate(client, room);
+  Object.defineProperty(handle, "code", { value: room.roomId, enumerable: true });
+  return handle;
+}
+async function joinPrivate(code, opts) {
+  const client = new Client(opts.url);
+  const room = await client.joinById(code, matchJoinOptions(opts));
+  return wirePrivate(client, room);
+}
 export {
-  connect
+  connect,
+  createPrivate,
+  joinPrivate,
+  matchmake
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/multiplayer",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "description": "The multiplayer client wrapper + shared room schema for genex.",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,6 +20,12 @@
   "files": [
     "dist"
   ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "check": "pnpm build && publint && attw --pack . --profile esm-only",
+    "prepack": "pnpm build && publint"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -45,10 +51,5 @@
     "url": "git+https://github.com/me-ai-org/genex-demo.git",
     "directory": "packages/multiplayer"
   },
-  "license": "MIT",
-  "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc --noEmit",
-    "check": "pnpm build && publint && attw --pack . --profile esm-only"
-  }
-}
+  "license": "MIT"
+}