@genex-ai/multiplayer 0.10.0 → 0.10.2

package/README.md

@@ -22,17 +22,25 @@ 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.
 
+`connect()` joins immediately. Use it for one ongoing drop-in world. If the game has a
+Play/Online/Local/Bots menu, call it only after the online click and call `room.leave()` when the
+player returns to the offline menu. Immediate connect + spawn is valid only when loading the game
+already means joining the always-online world; do not put a fake Play screen in front of a player
+who is already present. Use `matchmake()` below for fresh bounded sessions with queue/quorum/fair
+start/backfill behavior.
+
 ---
 
 ## `me` — publish your own state
@@ -46,7 +54,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) {
@@ -100,7 +108,11 @@ room.objects.snap('ball', { x: 0, y: 1, z: 0, q: [0, 0, 0, 1] });
 ```
 
 Keep object state **flat** (top-level numbers + a 4-number quaternion) so it smooths, same as a
-player. `state` is smoothed; `stateRaw` is the raw latest (hit-tests). `objects.ids()` lists them.
+player. `state` is render-only and smoothed; `stateRaw` is the raw latest for every gameplay read
+(hit-tests, reach, pickups, physics adoption, discrete values). `objects.ids()` lists them.
+`objects.set()` and `objects.snap()` are owner-only: SDK 0.10.2+ ignores an unowned call and warns
+once per object/operation. Await `claimConfirmed()` and check `accepted` before an irreversible
+write; legacy `claim(); set()` remains valid because `claim()` is optimistic locally.
 
 The relay enforces a short minimum ownership hold to prevent contact thrash. A current-owner
 reassert is a true no-op: it does not extend that hold. Legacy `claim()` remains optimistic for
@@ -253,7 +265,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 +329,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,20 +21,22 @@ 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;
-    /** State to render — for remote players this is **auto-smoothed** (interpolated);
-     * for yourself it's live. Numeric fields are lerped; everything else snaps. */
+    /** Transport is live now. False while this reserved seat is inside reconnect grace. */
+    connected: boolean;
+    /** RENDER ONLY — for remote players this is **auto-smoothed** (interpolated) and delayed;
+     * for yourself it's live. Numeric fields are lerped; everything else snaps. Use `stateRaw`
+     * for every gameplay read (hits, reach, pickups, flags, physics adoption). */
     state: TState;
     /** The latest raw snapshot (never smoothed/delayed) — use for hit-tests / logic. */
     stateRaw: TState;
@@ -44,8 +50,8 @@ type ObjectView<TState> = {
     owner: string | undefined;
     /** True if you own it (so you should simulate + `objects.set` it). */
     isMine: boolean;
-    /** State to render — **auto-smoothed** like a remote player when someone else owns it;
-     * live (your last `set`) when it's yours. */
+    /** RENDER ONLY — **auto-smoothed** and delayed like a remote player when someone else owns it;
+     * live (your last `set`) when it's yours. Use `stateRaw` for every gameplay read. */
     state: TState;
     /** The latest raw snapshot (never smoothed/delayed) — for hit-tests / logic. */
     stateRaw: TState;
@@ -81,6 +87,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 +206,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 +228,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 +286,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 +317,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)
@@ -207,6 +208,7 @@ function attachSession(client, initialRoom) {
   const objEpochs = /* @__PURE__ */ new Map();
   const objRaw = /* @__PURE__ */ new Map();
   const localObjState = /* @__PURE__ */ new Map();
+  const warnedUnownedWrites = /* @__PURE__ */ new Set();
   const pendingBridge = /* @__PURE__ */ new Map();
   let hostId;
   let objectControlVersion = 0;
@@ -214,6 +216,17 @@ function attachSession(client, initialRoom) {
   const pendingControls = /* @__PURE__ */ new Map();
   const testSkew = typeof globalThis !== "undefined" && globalThis.__GENEX_MP_TEST_SKEW__ || 0;
   const now = testSkew ? () => nowMs() + testSkew : nowMs;
+  const rejectUnownedWrite = (operation, id) => {
+    if (objOwners.get(id) === room.sessionId) return false;
+    const warningKey = `${operation}:${id}`;
+    if (!warnedUnownedWrites.has(warningKey)) {
+      warnedUnownedWrites.add(warningKey);
+      console.warn(
+        `[multiplayer] objects.${operation}('${id}') ignored because this session does not own the object \u2014 await objects.claimConfirmed('${id}') and check accepted before publishing`
+      );
+    }
+    return true;
+  };
   const pushSnap = (id, state, sendTime) => {
     const arrival = now();
     const t = sendTime ?? arrival;
@@ -368,6 +381,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 +672,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 +680,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 +732,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) {
@@ -787,12 +813,14 @@ function attachSession(client, initialRoom) {
       },
       set(id, state) {
         const key = String(id);
+        if (rejectUnownedWrite("set", key)) return;
         const clean = sanitizeFinite(state);
         if (objOwners.get(key) === room.sessionId) localObjState.set(key, clean);
         send0("obj", { id: key, d: clean, t: now() });
       },
       snap(id, state) {
         const key = String(id);
+        if (rejectUnownedWrite("snap", key)) return;
         const clean = sanitizeFinite(state);
         if (objOwners.get(key) === room.sessionId) localObjState.set(key, clean);
         send0(OBJECT_SNAP_MSG, { id: key, d: clean, t: now() });
@@ -894,7 +922,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 +938,7 @@ function buildView(matchRoom, queueInfo) {
       role: "player",
       queue: queueInfo,
       players: [],
+      connectedPlayers: [],
       opponents: [],
       teams: {},
       myTeam: null,
@@ -929,6 +957,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 +968,7 @@ function buildView(matchRoom, queueInfo) {
     role: isPlayer ? "player" : "spectator",
     queue: { position: 0, size: 0 },
     players,
+    connectedPlayers,
     opponents,
     teams,
     myTeam,
@@ -968,9 +998,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 +1028,7 @@ async function matchmake(opts) {
           if (cancelled) return;
           continue;
         }
-        if (cancelled) {
+        if (cancelled || epoch !== lifecycleEpoch) {
           void q.leave();
           return;
         }
@@ -1003,10 +1037,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 +1063,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 +1075,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 +1088,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 +1149,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.2",
   "description": "The multiplayer client wrapper + shared room schema for genex.",
   "type": "module",
   "main": "./dist/index.js",