@genex-ai/multiplayer 0.9.0 → 0.10.1

package/README.md

@@ -13,23 +13,24 @@ import { connect } from '@genex-ai/multiplayer';
 ## Connect
 
 ```ts
-import { waitForPlayer, getColyseusAuth } from '@genex-ai/embed-sdk';
+import { waitForPlayer, getColyseusAuth, getColyseusUrls } from '@genex-ai/embed-sdk';
 
 type State = { x: number; y: number; z: number };   // YOUR per-player state — any JSON shape
 
 await waitForPlayer();                        // identity gate — resolves for guests AND accounts
 const room = await connect<State>({
-  url:  'wss://demo-colyseus.glotech.world',  // the genex multiplayer server
+  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) {
@@ -246,14 +247,14 @@ bounded extrapolation.
 
 ```ts
 import { connect } from '@genex-ai/multiplayer';
-import { waitForPlayer, getColyseusAuth } from '@genex-ai/embed-sdk';
+import { waitForPlayer, getColyseusAuth, getColyseusUrls } from '@genex-ai/embed-sdk';
 type S = { x: number; z: number };
 
 await waitForPlayer();   // identity gate (guest OR signed-in) — see Connect above
 const room = await connect<S>({
-  url: 'wss://demo-colyseus.glotech.world',
+  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 };
@@ -289,7 +290,7 @@ 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() });
+const mm = await matchmake<State>({ urls, room: slug, auth: () => getColyseusAuth() });
 
 // `session` is null WHILE SEARCHING — render your own "finding a match…" HUD until it goes live.
 // each frame:
@@ -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):
@@ -344,11 +345,11 @@ For `preset: 'private'` games, skip the queue: a host mints an invite **code**,
 import { createPrivate, joinPrivate } from "@genex-ai/multiplayer";
 
 // host
-const lobby = await createPrivate<State>({ url, room: slug, auth: () => getColyseusAuth() });
+const lobby = await createPrivate<State>({ urls, 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() });
+const joined = await joinPrivate<State>(code, { urls, room: slug, auth: () => getColyseusAuth() });
 
 // then identical to matchmake(): .session, .matchmaking, eliminated()/score()/finish(), cancel()
 ```

package/dist/index.d.ts

@@ -1,9 +1,14 @@
 export { PlayerState, RoomState } from './schema.js';
 import '@colyseus/schema';
 
+type ColyseusAuth = {
+    embedToken: string;
+};
+type AuthSource = ColyseusAuth | (() => ColyseusAuth | undefined);
 type ConnectOptions = {
-    /** Colyseus server url, e.g. "ws://localhost:2567". */
-    url: string;
+    /** Regional relay urls (pass `getColyseusUrls()`) — the SDK pings each and connects to the
+     *  lowest-latency one; a single entry just connects. */
+    urls: string[];
     /** Game id — everyone who passes the same id shares a room; different ids are
      * fully isolated. Use your project slug (or any stable per-game string). */
     room: string;
@@ -16,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;
@@ -80,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**
@@ -197,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
@@ -219,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. */
@@ -264,8 +274,8 @@ type Matchmaking<TState extends Record<string, unknown>> = {
     cancel(): void;
 };
 type MatchmakeOptions = {
-    /** Colyseus server url. */
-    url: string;
+    /** Regional relay urls (pass `getColyseusUrls()`) — pings each, connects to the lowest-latency one. */
+    urls: string[];
     /** Game id (your project slug/id) — isolates this game's matchmaking. */
     room: string;
     name?: string;
@@ -275,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
@@ -310,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

@@ -1,5 +1,5 @@
 // src/index.ts
-import { Client, getStateCallbacks } from "colyseus.js";
+import { Client, getStateCallbacks } from "@colyseus/sdk";
 var RELAY_ROOM_TYPE = "play";
 var QUEUE_ROOM_TYPE = "queue";
 var MATCH_ROOM_TYPE = "match";
@@ -27,6 +27,13 @@ var OBJECT_CONTROL_VERSION = 2;
 var STATE_SNAP_MSG = "__state:snap";
 var OBJECT_SNAP_MSG = "__object:snap";
 var MP_PROTOCOL = 2;
+async function relayClient(opts) {
+  if (opts.urls.length > 1) return Client.selectByLatency(opts.urls);
+  const url = opts.urls[0];
+  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 {
@@ -151,11 +158,11 @@ function quantile(xs, q) {
   return s[i];
 }
 async function connect(opts) {
-  const client = new Client(opts.url);
+  const client = await relayClient(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)
@@ -362,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);
@@ -652,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) {
@@ -661,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");
@@ -712,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) {
@@ -888,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,
@@ -905,6 +924,7 @@ function buildView(matchRoom, queueInfo) {
       role: "player",
       queue: queueInfo,
       players: [],
+      connectedPlayers: [],
       opponents: [],
       teams: {},
       myTeam: null,
@@ -923,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);
@@ -933,6 +954,7 @@ function buildView(matchRoom, queueInfo) {
     role: isPlayer ? "player" : "spectator",
     queue: { position: 0, size: 0 },
     players,
+    connectedPlayers,
     opponents,
     teams,
     myTeam,
@@ -947,7 +969,7 @@ function buildView(matchRoom, queueInfo) {
   };
 }
 async function matchmake(opts) {
-  const client = new Client(opts.url);
+  const client = await relayClient(opts);
   const emitters = /* @__PURE__ */ new Map();
   const emit = (event, ...args) => emitters.get(event)?.forEach((cb) => cb(...args));
   const on = ((event, cb) => {
@@ -962,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;
@@ -988,7 +1014,7 @@ async function matchmake(opts) {
           if (cancelled) return;
           continue;
         }
-        if (cancelled) {
+        if (cancelled || epoch !== lifecycleEpoch) {
           void q.leave();
           return;
         }
@@ -997,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;
@@ -1020,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;
       }
@@ -1032,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();
       });
@@ -1043,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() {
@@ -1077,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();
@@ -1128,14 +1188,14 @@ function wirePrivate(client, room) {
   };
 }
 async function createPrivate(opts) {
-  const client = new Client(opts.url);
+  const client = await relayClient(opts);
   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 client = await relayClient(opts);
   const room = await client.joinById(code, matchJoinOptions(opts));
   return wirePrivate(client, room);
 }

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.9.0",
+  "version": "0.10.1",
   "description": "The multiplayer client wrapper + shared room schema for genex.",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,8 +30,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@colyseus/schema": "^3.0.76",
-    "colyseus.js": "^0.16.22"
+    "@colyseus/schema": "^4.0.27",
+    "@colyseus/sdk": "^0.17.43"
   },
   "peerDependencies": {
     "three": ">=0.160.0"