@genex-ai/multiplayer 0.10.0 → 0.10.1

package/README.md

@@ -22,14 +22,15 @@ const room = await connect<State>({
   urls: getColyseusUrls(),          // regional relays for this session — SDK joins the fastest
   room: '<game-id>',                          // everyone with the same id shares a room (use the project slug)
   name: 'ada',                                // optional display name
-  auth: getColyseusAuth()!,                   // REQUIRED — the relay rejects tokenless joins
+  auth: () => getColyseusAuth(),              // REQUIRED — resolved fresh for this connect
 });
 ```
 
 `auth` is **required** — the relay rejects tokenless joins. Get it from `@genex-ai/embed-sdk`:
 `await waitForPlayer()` first (never `waitForAuth()` — that resolves only for signed-in accounts
-and keeps guests out forever), then read `getColyseusAuth()` **fresh at every `connect()`** —
-tokens rotate every ~10 min, so never cache the object across reconnects. Never log it.
+and keeps guests out forever), then pass `() => getColyseusAuth()` so each explicit
+`connect()` reads it fresh — tokens rotate every ~10 min, so never cache the object
+across reconnects. Never log it.
 
 Different `room` ids are **fully isolated** — players in game A never see game B.
 
@@ -46,7 +47,7 @@ room.me.snap({ x: spawnX, y: spawnY, z: spawnZ }); // respawn/teleport: hard-res
 
 ## `players` — everyone in the room
 
-A fresh `Map` each read; **includes you** (skip with `id === room.id`). For remote players `p.state` is **auto-smoothed** (interpolated); for yourself it's live. `p.stateRaw` is always the latest raw snapshot (use it for hit-tests / logic).
+A fresh `Map` each read; **includes you** (skip with `id === room.id`). For remote players `p.state` is **auto-smoothed** (interpolated); for yourself it's live. `p.stateRaw` is always the latest raw snapshot (use it for hit-tests / logic). A reserved reconnecting seat stays in `players` with `p.connected === false`; use `room.activePlayers` when gameplay needs the live transport quorum.
 
 ```ts
 for (const [id, p] of room.players) {
@@ -253,7 +254,7 @@ await waitForPlayer();   // identity gate (guest OR signed-in) — see Connect a
 const room = await connect<S>({
   urls: getColyseusUrls(),
   room: GAME_ID,
-  auth: getColyseusAuth()!,   // REQUIRED — tokenless joins are rejected
+  auth: () => getColyseusAuth(), // REQUIRED — resolved fresh for this connect
 });
 
 const me = { x: 0, z: 0 };
@@ -317,7 +318,7 @@ A failed queue join is **retried automatically** with backoff (~10s total), so t
 (a token mid-rotation, identity still settling on page load) never surface. Only a persistent
 failure emits `error`; the handle then idles until you call `mm.retry()`.
 
-**`mm.matchmaking`** (read every frame for your HUD): `status` (`searching` | `waiting` | `countdown` | `playing` | `ended`; the legacy `spectating` is never emitted — server-side spectators were removed), `queue` (`{ position, size }`), `players`, `opponents`, `teams`, `myTeam`, `scores`, `winCondition`, `config` (numeric knobs), `roundId`, `winnerId`, `message`. `championId`/`challengerId` are 1v1 aliases.
+**`mm.matchmaking`** (read every frame for your HUD): `status` (`searching` | `waiting` | `countdown` | `playing` | `ended`; the legacy `spectating` is never emitted — server-side spectators were removed), `queue` (`{ position, size }`), `players` (reserved seats), `connectedPlayers` (live transports), `opponents`, `teams`, `myTeam`, `scores`, `winCondition`, `config` (numeric knobs), `roundId`, `winnerId`, `message`. `championId`/`challengerId` are 1v1 aliases. During an automatic reconnect, the SDK retains the last coherent roster and match view until the replacement room hydrates, so status does not transiently regress to `waiting`.
 
 Configure once in the game's `package.json` (reported at `genex preview` AND `genex publish`;
 removing it clears the stored config on the next preview/publish — never sent from the client):

package/dist/index.d.ts

@@ -1,6 +1,10 @@
 export { PlayerState, RoomState } from './schema.js';
 import '@colyseus/schema';
 
+type ColyseusAuth = {
+    embedToken: string;
+};
+type AuthSource = ColyseusAuth | (() => ColyseusAuth | undefined);
 type ConnectOptions = {
     /** Regional relay urls (pass `getColyseusUrls()`) — the SDK pings each and connects to the
      *  lowest-latency one; a single entry just connects. */
@@ -17,18 +21,19 @@ type ConnectOptions = {
      * `genexEmbed.getColyseusAuth()` AFTER `await genexEmbed.waitForPlayer()`
      * (from `@genex-ai/embed-sdk`). NOT `waitForAuth()` — that resolves only for
      * signed-in accounts and would keep guests out of multiplayer forever.
-     * Read it fresh at every connect() call — never cache the object across
-     * reconnects (tokens rotate every ~10 min). NEVER log this value.
+     * Prefer a supplier `() => getColyseusAuth()` so every explicit connect()
+     * call reads the current token (tokens rotate every ~10 min). A current
+     * value remains supported for backward compatibility. NEVER log it.
      */
-    auth?: {
-        embedToken: string;
-    };
+    auth?: AuthSource;
     /** Extra join options passed to the room. */
     options?: Record<string, unknown>;
 };
 type PlayerView<TState> = {
     id: string;
     name: string;
+    /** Transport is live now. False while this reserved seat is inside reconnect grace. */
+    connected: boolean;
     /** State to render — for remote players this is **auto-smoothed** (interpolated);
      * for yourself it's live. Numeric fields are lerped; everything else snaps. */
     state: TState;
@@ -81,6 +86,8 @@ type Session<TState extends Record<string, unknown>> = {
      * `state` is auto-smoothed; read `stateRaw` for the raw latest value.
      */
     readonly players: Map<string, PlayerView<TState>>;
+    /** Connected subset of `players`; excludes seats currently held only by reconnect grace. */
+    readonly activePlayers: Map<string, PlayerView<TState>>;
     readonly me: {
         /**
          * Publish your synced state (replaces it wholesale). Call on a **fixed tick**
@@ -198,7 +205,7 @@ type Session<TState extends Record<string, unknown>> = {
  * await waitForPlayer();             // identity gate (guest OR signed-in)
  * const room = await connect<{ x: number; y: number; z: number }>({
  *   url: 'ws://localhost:2567', room: gameId, name: 'ada',
- *   auth: getColyseusAuth()!,        // REQUIRED — the relay rejects tokenless joins
+ *   auth: () => getColyseusAuth(),   // REQUIRED — fresh on every explicit connect call
  * });
  * room.me.set({ x, y, z });          // typed + validated by the compiler
  * room.players.get(id)?.state.x;     // number — auto-smoothed for remote players
@@ -220,6 +227,8 @@ type MatchmakingView = {
     };
     /** Every active participant id (N-player: 1v1, FFA, teams). */
     players: string[];
+    /** Participants whose transport is live now; graced seats remain only in `players`. */
+    connectedPlayers: string[];
     /** The other active player id(s) — everyone in `players` except you. */
     opponents: string[];
     /** teamId -> member ids for team presets; empty for FFA + 1v1. */
@@ -276,11 +285,7 @@ type MatchmakeOptions = {
      * 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);
+    auth?: AuthSource;
 };
 /**
  * Join a game's matchmaking. Returns immediately in the SEARCHING state (`session` is null); the
@@ -311,4 +316,4 @@ declare function createPrivate<TState extends Record<string, unknown> = never>(o
  */
 declare function joinPrivate<TState extends Record<string, unknown> = never>(code: string, opts: MatchmakeOptions): Promise<Matchmaking<TState>>;
 
-export { type ConnectOptions, type MatchStatus, type MatchmakeOptions, type Matchmaking, type MatchmakingView, type ObjectControlOperation, type ObjectControlOptions, type ObjectControlReason, type ObjectControlResult, type ObjectView, type PlayerView, type PrivateMatch, type Session, connect, createPrivate, joinPrivate, matchmake };
+export { type AuthSource, type ColyseusAuth, type ConnectOptions, type MatchStatus, type MatchmakeOptions, type Matchmaking, type MatchmakingView, type ObjectControlOperation, type ObjectControlOptions, type ObjectControlReason, type ObjectControlResult, type ObjectView, type PlayerView, type PrivateMatch, type Session, connect, createPrivate, joinPrivate, matchmake };

package/dist/index.js

@@ -33,6 +33,7 @@ async function relayClient(opts) {
   if (!url) throw new Error("genex multiplayer: `urls` must contain at least one relay URL");
   return new Client(url);
 }
+var resolveAuth = (auth) => typeof auth === "function" ? auth() : auth;
 function parseData(s) {
   if (!s) return { state: {} };
   try {
@@ -161,7 +162,7 @@ async function connect(opts) {
   const room = await client.joinOrCreate(RELAY_ROOM_TYPE, {
     gameId: opts.room,
     name: opts.name,
-    embedToken: opts.auth?.embedToken,
+    embedToken: resolveAuth(opts.auth)?.embedToken,
     ...opts.options,
     __v: MP_PROTOCOL
     // tells the relay this client hides reserved `__` keys (see MP_PROTOCOL)
@@ -368,6 +369,7 @@ function attachSession(client, initialRoom) {
   };
   const parseCache = /* @__PURE__ */ new Map();
   const playerEpochs = /* @__PURE__ */ new Map();
+  let lastPlayersView = /* @__PURE__ */ new Map();
   const cachedParse = (id, raw) => {
     if (!raw) return {};
     const hit = parseCache.get(id);
@@ -658,7 +660,6 @@ function attachSession(client, initialRoom) {
       try {
         const next = await client.reconnect(token);
         room = next;
-        connected = true;
         const reconnectGap = reconnectStartedAt ? nowMs() - reconnectStartedAt : 0;
         reconnectStartedAt = 0;
         if (reconnectGap > 1e3) {
@@ -667,6 +668,7 @@ function attachSession(client, initialRoom) {
         const hydrated = wireRoom(next);
         await Promise.race([hydrated, new Promise((r) => setTimeout(r, 2e3))]);
         if (room !== next || dead || intentionalLeave) return;
+        connected = true;
         syncHostTicks();
         for (const pending of pendingControls.values()) sendPendingControl(pending);
         emit("reconnected");
@@ -718,10 +720,22 @@ function attachSession(client, initialRoom) {
         } else {
           state = sampleSmoothed(id, localNow) ?? latest;
         }
-        out.set(id, { id, name: p.name, state, stateRaw: raw });
+        out.set(id, {
+          id,
+          name: p.name,
+          connected: p.connected !== false,
+          // old relay schemas did not carry the field
+          state,
+          stateRaw: raw
+        });
       });
+      if (!connected && out.size === 0 && lastPlayersView.size > 0) return new Map(lastPlayersView);
+      lastPlayersView = out;
       return out;
     },
+    get activePlayers() {
+      return new Map([...session.players].filter(([, player]) => player.connected));
+    },
     me: {
       set(state) {
         if (SEND_TIME_KEY in state) {
@@ -894,7 +908,6 @@ function attachSession(client, initialRoom) {
   return session;
 }
 var SEARCH_BACKOFF_MS = [1e3, 2e3, 4e3];
-var resolveAuth = (auth) => typeof auth === "function" ? auth() : auth;
 var matchJoinOptions = (opts) => ({
   gameId: opts.room,
   name: opts.name,
@@ -911,6 +924,7 @@ function buildView(matchRoom, queueInfo) {
       role: "player",
       queue: queueInfo,
       players: [],
+      connectedPlayers: [],
       opponents: [],
       teams: {},
       myTeam: null,
@@ -929,6 +943,7 @@ function buildView(matchRoom, queueInfo) {
   const challengerId = m.challengerId ?? null;
   const teams = m.teams ?? {};
   const players = m.players ?? [championId, challengerId].filter((x) => !!x);
+  const connectedPlayers = m.connectedPlayers ?? players;
   const isPlayer = myId != null && players.includes(myId);
   const status = isPlayer ? m.phase : "spectating";
   const opponents = players.filter((id) => id !== myId);
@@ -939,6 +954,7 @@ function buildView(matchRoom, queueInfo) {
     role: isPlayer ? "player" : "spectator",
     queue: { position: 0, size: 0 },
     players,
+    connectedPlayers,
     opponents,
     teams,
     myTeam,
@@ -968,9 +984,13 @@ async function matchmake(opts) {
   let queueInfo = { position: 0, size: 0 };
   let cancelled = false;
   let searching = false;
+  let lifecycleEpoch = 0;
+  let seating = false;
+  let requeueing = false;
   const search = async () => {
     if (cancelled || searching) return;
     searching = true;
+    const epoch = ++lifecycleEpoch;
     try {
       session = null;
       matchRoom = null;
@@ -994,7 +1014,7 @@ async function matchmake(opts) {
           if (cancelled) return;
           continue;
         }
-        if (cancelled) {
+        if (cancelled || epoch !== lifecycleEpoch) {
           void q.leave();
           return;
         }
@@ -1003,10 +1023,13 @@ async function matchmake(opts) {
           queueInfo = { position: msg.position, size: msg.size };
           emit("queue", msg);
         });
-        q.onMessage(
-          "seat",
-          (msg) => void consumeSeat(msg.reservation, msg.role)
-        );
+        q.onMessage("seat", (msg) => {
+          if (cancelled || epoch !== lifecycleEpoch || queueRoom !== q || seating) return;
+          seating = true;
+          queueRoom = null;
+          void q.leave();
+          void consumeSeat(msg.reservation, msg.role, epoch);
+        });
         q.onLeave(() => {
           if (cancelled || queueRoom !== q) return;
           queueRoom = null;
@@ -1026,10 +1049,10 @@ async function matchmake(opts) {
       searching = false;
     }
   };
-  const consumeSeat = async (reservation, role) => {
+  const consumeSeat = async (reservation, role, epoch) => {
     try {
       const mr = await client.consumeSeatReservation(reservation);
-      if (cancelled) {
+      if (cancelled || epoch !== lifecycleEpoch) {
         void mr.leave();
         return;
       }
@@ -1038,7 +1061,9 @@ async function matchmake(opts) {
       session = s;
       s.on("match:start", (m) => emit("matchStart", m));
       s.on("match:ended", (m) => emit("matchEnded", m));
-      s.on("match:requeue", () => void requeue());
+      s.on("match:requeue", () => {
+        if (session === s) void requeue();
+      });
       s.on("disconnect", () => {
         if (!cancelled && session === s) void requeue();
       });
@@ -1049,23 +1074,50 @@ async function matchmake(opts) {
       emit("matched");
       if (role === "spectator") emit("spectate");
     } catch {
-      void search();
+      if (!cancelled && epoch === lifecycleEpoch) {
+        seating = false;
+        void search();
+      }
+    } finally {
+      if (epoch === lifecycleEpoch) seating = false;
     }
   };
   const requeue = async () => {
-    session?.leave();
-    matchRoom = null;
-    session = null;
-    await search();
+    if (cancelled || requeueing) return;
+    requeueing = true;
+    try {
+      lifecycleEpoch++;
+      seating = false;
+      session?.leave();
+      matchRoom = null;
+      session = null;
+      await search();
+    } finally {
+      requeueing = false;
+    }
   };
   void search();
   const liveRoom = () => session ? roomOf(session) : null;
+  let viewSession = null;
+  let lastHydratedView = null;
+  const stableView = () => {
+    if (session !== viewSession) {
+      viewSession = session;
+      lastHydratedView = null;
+    }
+    const live = liveRoom();
+    const hydrated = live?.state?.shared?.get(MATCH_KEY) != null;
+    if (!hydrated && session && lastHydratedView) return lastHydratedView;
+    const next = buildView(live, queueInfo);
+    if (hydrated) lastHydratedView = next;
+    return next;
+  };
   return {
     get session() {
       return session;
     },
     get matchmaking() {
-      return buildView(liveRoom(), queueInfo);
+      return stableView();
     },
     on,
     eliminated() {
@@ -1083,6 +1135,8 @@ async function matchmake(opts) {
     },
     cancel() {
       cancelled = true;
+      lifecycleEpoch++;
+      seating = false;
       session?.leave();
       if (!session && matchRoom) void matchRoom.leave();
       if (queueRoom) void queueRoom.leave();

package/dist/schema.d.ts

@@ -5,10 +5,12 @@ declare const PlayerState: _colyseus_schema.SchemaWithExtendsConstructor<{
     name: "string";
     data: "string";
     epoch: "number";
+    connected: "boolean";
 }, _colyseus_schema.AssignableProps<_colyseus_schema.InferSchemaInstanceType<{
     name: "string";
     data: "string";
     epoch: "number";
+    connected: "boolean";
 }>>, typeof _colyseus_schema.Schema>;
 type PlayerState = SchemaType<typeof PlayerState>;
 declare const RoomState: _colyseus_schema.SchemaWithExtendsConstructor<{
@@ -17,15 +19,18 @@ declare const RoomState: _colyseus_schema.SchemaWithExtendsConstructor<{
             name: "string";
             data: "string";
             epoch: "number";
+            connected: "boolean";
         }, _colyseus_schema.AssignableProps<_colyseus_schema.InferSchemaInstanceType<{
             name: "string";
             data: "string";
             epoch: "number";
+            connected: "boolean";
         }>>, typeof _colyseus_schema.Schema>;
         default: MapSchema<_colyseus_schema.InferSchemaInstanceType<{
             name: "string";
             data: "string";
             epoch: "number";
+            connected: "boolean";
         }>, string>;
     };
     shared: {
@@ -38,15 +43,18 @@ declare const RoomState: _colyseus_schema.SchemaWithExtendsConstructor<{
             name: "string";
             data: "string";
             epoch: "number";
+            connected: "boolean";
         }, _colyseus_schema.AssignableProps<_colyseus_schema.InferSchemaInstanceType<{
             name: "string";
             data: "string";
             epoch: "number";
+            connected: "boolean";
         }>>, typeof _colyseus_schema.Schema>;
         default: MapSchema<_colyseus_schema.InferSchemaInstanceType<{
             name: "string";
             data: "string";
             epoch: "number";
+            connected: "boolean";
         }>, string>;
     };
     shared: {

package/dist/schema.js

@@ -6,7 +6,10 @@ var PlayerState = schema(
     data: "string",
     // Relay-owned discontinuity epoch. Ordinary state updates keep it stable;
     // state:snap increments it so new SDKs discard interpolation history.
-    epoch: "number"
+    epoch: "number",
+    // Seat presence is distinct from connectivity: a dropped player keeps the
+    // seat during reconnection grace but flips connected=false immediately.
+    connected: "boolean"
   },
   "PlayerState"
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/multiplayer",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "The multiplayer client wrapper + shared room schema for genex.",
   "type": "module",
   "main": "./dist/index.js",