@genex-ai/multiplayer 0.8.0 → 0.8.2

package/README.md

@@ -13,15 +13,24 @@ import { connect } from '@genex-ai/multiplayer';
 ## Connect
 
 ```ts
+import { waitForPlayer, getColyseusAuth } 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
   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` 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.
+
 Different `room` ids are **fully isolated** — players in game A never see game B.
 
 ---
@@ -82,8 +91,10 @@ player. `state` is smoothed; `stateRaw` is the raw latest (hit-tests). `objects.
 
 ## `isHost` / `host` — the elected room authority
 
-One client is the **host** (the first joiner still present, re-elected automatically when they
-leave). Use it to pick a single writer for scores/rounds or a single simulator for NPCs.
+One client is the **host** — the earliest **signed-in** player still present (guests host only
+while no account is in the room), re-elected automatically. The host can change on **join** as
+well as leave: the first account entering a guest-hosted room takes over. Use it to pick a single
+writer for scores/rounds or a single simulator for NPCs.
 
 ```ts
 if (room.isHost) room.shared.set('round', nextRound);   // only the host advances the round
@@ -167,13 +178,13 @@ room.leave();
 
 ## Smoothing remote players
 
-Remote players are **smoothed automatically** — nothing to configure. `room.players` gives each remote player's `state` rendered slightly in the past and interpolated between snapshots, so motion glides between network updates (you send ~10–20Hz but render at 60). Interpolation runs on the **sender's clock** (each update is timestamped and mapped to your local clock), the way Valve/Unity/Mirror do it — so jitter doesn't distort the motion. The delay **self-tunes to the live snapshot rate**, so it works whether you send at 5Hz or 30Hz.
+Remote players are **smoothed automatically** — nothing to configure. `room.players` gives each remote player's `state` rendered slightly in the past and interpolated between snapshots, so motion glides between network updates (you send ~10–20Hz but render at 60). Interpolation runs on the **sender's clock** (each update is timestamped and mapped to your local clock), the way Valve/Unity/Mirror do it — so jitter doesn't distort the motion. The delay **self-tunes to both the live snapshot rate and the link's measured jitter**, so it stays smooth whether you send at 5Hz or 30Hz and whether the connection is a clean LAN or a jittery mobile link — a deeper buffer is used only where the jitter demands it.
 
 - `player.state` is the **smoothed** value (what you draw); `player.stateRaw` is the **latest raw** snapshot — use it for hit-tests / discrete logic.
 - **Your own player is never delayed** — you always render yourself live.
 - **Numbers** are interpolated; a 4-element `[x, y, z, w]` **quaternion** is **slerped** (shortest-arc); anything else snaps.
 - **Send rotation as a quaternion:** `state.q = mesh.quaternion.toArray()`, then on the remote `mesh.quaternion.fromArray(p.state.q)`. The package slerps it and **output-smooths** it so it glides through turns.
-- **Late/dropped packets keep moving:** **position** dead-reckons forward from its last velocity (capped ~0.25s, Source-style) until fresh snapshots arrive; **rotation** holds its last orientation rather than extrapolating (extrapolating a turn overshoots and snaps — Mirror/Unity interpolate rotation only). Both are output-smoothed, so the catch-up glides. This is what holds up on high-latency links.
+- **Late/dropped packets keep moving:** **position** dead-reckons forward from its last velocity (capped ~0.25s, Source-style) until fresh snapshots arrive; **rotation** also continues the turn but on a **tighter cap** (~0.15s), so a remote's heading keeps moving through a brief gap instead of freezing and then snapping when the next packet lands — the short cap plus output-smoothing bound any overshoot. This is what holds up on high-latency links.
 
 > No client-side prediction/reconciliation: in this relay you're authoritative over **yourself** (you render instantly, the server never corrects you), so there's nothing to predict — smoothing *remote* players is the piece that matters.
 
@@ -183,9 +194,15 @@ Remote players are **smoothed automatically** — nothing to configure. `room.pl
 
 ```ts
 import { connect } from '@genex-ai/multiplayer';
+import { waitForPlayer, getColyseusAuth } from '@genex-ai/embed-sdk';
 type S = { x: number; z: number };
 
-const room = await connect<S>({ url: 'wss://demo-colyseus.glotech.world', room: GAME_ID });
+await waitForPlayer();   // identity gate (guest OR signed-in) — see Connect above
+const room = await connect<S>({
+  url: 'wss://demo-colyseus.glotech.world',
+  room: GAME_ID,
+  auth: getColyseusAuth()!,   // REQUIRED — tokenless joins are rejected
+});
 
 const me = { x: 0, z: 0 };
 
@@ -231,18 +248,26 @@ 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 */});
+mm.on("error", (e) => {/* queue join failed even after the SDK's automatic retries — persistent
+                          (broken auth / server unreachable); fix the cause, then mm.retry() */});
 
 // 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.retry();        // re-enter the queue after a terminal 'error' (no-op in any other state)
 mm.cancel();       // stop searching / leave the match
 ```
 
+A failed queue join is **retried automatically** with backoff (~10s total), so transient failures
+(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` | `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):
+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):
 
 ```jsonc
 "genex": {

package/dist/index.d.ts

@@ -13,10 +13,11 @@ type ConnectOptions = {
     /**
      * Verified-identity credential — REQUIRED to actually join: the relay
      * rejects tokenless joins (there is no anonymous play). Pass
-     * `genexEmbed.getColyseusAuth()` AFTER `await genexEmbed.waitForAuth()`
-     * (from `@genex-ai/embed-sdk`), and read it fresh at every connect() call —
-     * never cache the object across reconnects (tokens rotate every ~10 min).
-     * NEVER log this value.
+     * `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.
      */
     auth?: {
         embedToken: string;
@@ -65,7 +66,8 @@ type Session<TState extends Record<string, unknown>> = {
     readonly shared: {
         /** Read a shared value (any JSON), or `undefined`. */
         get(key: string): unknown;
-        /** Set a shared value (any JSON). Any client may set any key (no auth — demo). */
+        /** Set a shared value (any JSON). Any client may write game keys — by convention only
+         * the host writes agreed facts (see `isHost`); `__*` keys are reserved and rejected. */
         set(key: string, value: unknown): void;
         /** All shared keys currently set. */
         keys(): string[];
@@ -90,8 +92,10 @@ type Session<TState extends Record<string, unknown>> = {
         /** Ids of every object seen so far. */
         ids(): string[];
     };
-    /** True if you are the elected room host (first joiner still present). Settles within the
-     * first state patch after connect — read it in your loop or react to `on('host')`, not once. */
+    /** True if you are the elected room host — the earliest signed-in player still present
+     * (guests host only while no account is in the room); can migrate on join as well as leave.
+     * Settles within the first state patch after connect — read it in your loop or react to
+     * `on('host')`, not once. */
     readonly isHost: boolean;
     /** Session id of the current room host, or `undefined` until the first host patch lands. */
     readonly host: string | undefined;
@@ -154,8 +158,12 @@ type Session<TState extends Record<string, unknown>> = {
  * Connect to a genex multiplayer room. You must supply your player-state type:
  *
  * ```ts
+ * import { waitForPlayer, getColyseusAuth } from '@genex-ai/embed-sdk';
+ *
+ * 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
  * });
  * room.me.set({ x, y, z });          // typed + validated by the compiler
  * room.players.get(id)?.state.x;     // number — auto-smoothed for remote players
@@ -205,6 +213,8 @@ type Matchmaking<TState extends Record<string, unknown>> = {
      * 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.
+     * error: joining the queue failed even after the SDK's automatic retries (persistent —
+     * e.g. auth is broken or the server is unreachable); fix the cause, then call `retry()`.
      */
     on(event: 'searching' | 'queue' | 'matched' | 'matchStart' | 'matchEnded' | 'spectate' | 'error', cb: (payload?: unknown) => void): () => void;
     /** Report your OWN elimination (the `lastStanding` win condition). */
@@ -213,6 +223,9 @@ type Matchmaking<TState extends Record<string, unknown>> = {
     score(delta?: number): void;
     /** Report that you finished (the `firstToFinish` win condition — a race). */
     finish(): void;
+    /** Re-enter the queue after a terminal `error`. No-op while searching/matched, after
+     * `cancel()`, and for private lobbies (create/join a new lobby instead). */
+    retry(): void;
     /** Stop searching / leave the current match. */
     cancel(): void;
 };
@@ -238,6 +251,10 @@ type MatchmakeOptions = {
  * 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).
+ *
+ * A failed queue join is retried automatically with backoff (~10s total) — transient failures
+ * (token rotation, identity settling) never surface. A persistent failure emits 'error' and the
+ * handle idles until `retry()` is called.
  */
 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`. */

package/dist/index.js

@@ -4,10 +4,12 @@ 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_MIN_MS = 90;
 var INTERP_MAX_MS = 300;
+var JITTER_SAFETY = 1.2;
 var INTERP_EASE = 0.1;
 var MAX_EXTRAP_MS = 250;
+var ROT_EXTRAP_MS = 150;
 var CLOCK_WIN = 80;
 var SMOOTH_TAU_POS = 30;
 var SMOOTH_TAU_ROT = 70;
@@ -43,6 +45,14 @@ function parseValue(s) {
     return void 0;
   }
 }
+var finiteReplacer = (_k, v) => {
+  if (typeof v === "number") return Number.isFinite(v) ? v : 0;
+  if (typeof v === "bigint") return Number(v);
+  return v;
+};
+function sanitizeFinite(obj) {
+  return JSON.parse(JSON.stringify(obj, finiteReplacer));
+}
 var nowMs = () => typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
 function slerp(a, b, t) {
   let [bx, by, bz, bw] = b;
@@ -71,6 +81,7 @@ function isQuat(v) {
 }
 function blend(a, b, tNum, tQuat) {
   const out = {};
+  const interpolating = tNum < 1;
   for (const k in b) {
     const av = a[k];
     const bv = b[k];
@@ -79,7 +90,7 @@ function blend(a, b, tNum, tQuat) {
     } else if (isQuat(av) && isQuat(bv)) {
       out[k] = slerp(av, bv, tQuat);
     } else {
-      out[k] = bv;
+      out[k] = interpolating && k in a ? av : bv;
     }
   }
   return out;
@@ -111,9 +122,9 @@ function sampleBuffer(buf, renderTime) {
     const b2 = buf[n - 1];
     const span2 = b2.t - a2.t;
     if (span2 <= 0) return b2.state;
-    const capped = Math.min(renderTime, b2.t + MAX_EXTRAP_MS);
-    const t2 = (capped - a2.t) / span2;
-    return blend(a2.state, b2.state, t2, 1);
+    const tPos = (Math.min(renderTime, b2.t + MAX_EXTRAP_MS) - a2.t) / span2;
+    const tRot = (Math.min(renderTime, b2.t + ROT_EXTRAP_MS) - a2.t) / span2;
+    return blend(a2.state, b2.state, tPos, tRot);
   }
   const a = buf[j - 1];
   const b = buf[j];
@@ -126,6 +137,12 @@ function median(xs) {
   const s = [...xs].sort((a, b) => a - b);
   return s[s.length >> 1];
 }
+function quantile(xs, q) {
+  if (xs.length === 0) return 0;
+  const s = [...xs].sort((a, b) => a - b);
+  const i = Math.min(s.length - 1, Math.max(0, Math.round(q * (s.length - 1))));
+  return s[i];
+}
 async function connect(opts) {
   const client = new Client(opts.url);
   const room = await client.joinOrCreate(RELAY_ROOM_TYPE, {
@@ -138,7 +155,21 @@ async function connect(opts) {
   });
   return attachSession(client, room);
 }
-var RESERVED_SEND_TYPES = /* @__PURE__ */ new Set(["state", "shared", "claim", "obj", "release", "destroy"]);
+var RESERVED_SEND_TYPES = /* @__PURE__ */ new Set([
+  "state",
+  "shared",
+  "claim",
+  "obj",
+  "release",
+  "destroy",
+  // Server→client control verbs a game must never ORIGINATE — they'd broadcast to peers via the
+  // relay's `*` handler: 'server:restart' would trip every peer's save-flush, 'rate:drop' a bogus
+  // over-budget warning, 'queue'/'seat' spurious matchmaking control.
+  "server:restart",
+  "rate:drop",
+  "queue",
+  "seat"
+]);
 var isReservedSendType = (type) => RESERVED_SEND_TYPES.has(type) || type.startsWith("match:") || type.startsWith(RESERVED_PREFIX);
 var RECONNECT_DELAYS_MS = [500, 1e3, 2e3, 4e3, 8e3];
 var ROOM_REF = /* @__PURE__ */ Symbol("genex.roomRef");
@@ -172,12 +203,17 @@ function attachSession(client, initialRoom) {
     lastStamp.set(id, t);
     if (prev != null) {
       const gap = t - prev;
-      if (gap > 5 && gap < 1e3) {
+      if (gap > 5 && gap < 2e3) {
         let iv = intervalsById.get(id);
         if (!iv) intervalsById.set(id, iv = []);
         iv.push(gap);
         if (iv.length > 30) iv.shift();
-        const target = Math.min(INTERP_MAX_MS, Math.max(INTERP_MIN_MS, INTERP_RATIO * median(iv)));
+        const ow = offsetWin.get(id);
+        const jitter = ow && ow.length >= 8 ? quantile(ow, 0.9) - Math.min(...ow) : 0;
+        const target = Math.min(
+          INTERP_MAX_MS,
+          Math.max(INTERP_MIN_MS, INTERP_RATIO * median(iv), JITTER_SAFETY * jitter)
+        );
         const cur = autoDelayById.get(id) ?? 100;
         autoDelayById.set(id, cur + (target - cur) * INTERP_EASE);
       }
@@ -228,8 +264,10 @@ function attachSession(client, initialRoom) {
     "reconnecting",
     "reconnected",
     "disconnect",
-    INPUT_MSG
+    INPUT_MSG,
     // inputs.on() has its own channel — never bridged as a custom event
+    "rate:drop"
+    // relay → us only (over-budget warning); handled internally, never bridged
   ]);
   const emit = (event, ...args) => emitters.get(event)?.forEach((cb) => cb(...args));
   const lastShared = /* @__PURE__ */ new Map();
@@ -254,7 +292,10 @@ function attachSession(client, initialRoom) {
       if (ownerChanged) {
         if (owner) objOwners.set(id, owner);
         else objOwners.delete(id);
-        if (owner !== room.sessionId) localObjState.delete(id);
+        if (owner !== room.sessionId) {
+          localObjState.delete(id);
+          clearStream(key);
+        }
       }
       if (blob.d && typeof blob.d === "object" && Object.keys(blob.d).length > 0) {
         objRaw.set(id, blob.d);
@@ -276,6 +317,17 @@ function attachSession(client, initialRoom) {
   };
   let intentionalLeave = false;
   let dead = false;
+  let droppedWhileOffline = 0;
+  const send0 = (type, payload, countIfDropped = false) => {
+    if (room.connection?.isOpen) {
+      try {
+        room.send(type, payload);
+        return;
+      } catch {
+      }
+    }
+    if (countIfDropped) droppedWhileOffline++;
+  };
   const wireRoom = (r) => {
     const $ = getStateCallbacks(r);
     $(r.state).players.onAdd((player, id) => {
@@ -316,6 +368,11 @@ function attachSession(client, initialRoom) {
     r.onMessage(INPUT_MSG, (msg) => {
       if (msg && typeof msg.from === "string") emit(INPUT_MSG, msg.from, msg.d);
     });
+    r.onMessage("rate:drop", (msg) => {
+      console.warn(
+        `[multiplayer] the relay dropped ${msg?.dropped ?? "some"} of your messages in the last second \u2014 you are publishing over budget. Publish idle/unchanged objects at \u22642Hz keepalive, not every tick (see the multiplayer skill's "message budget" section).`
+      );
+    });
     for (const event of bridged) r.onMessage(event, (msg) => emit(event, msg));
     r.onLeave((code) => handleLeave(r, code ?? 1006));
     r.onError(() => {
@@ -332,18 +389,27 @@ function attachSession(client, initialRoom) {
     void attemptReconnect(left.reconnectionToken, code);
   };
   const attemptReconnect = async (token, code) => {
-    for (let attempt = 1; attempt <= RECONNECT_DELAYS_MS.length; attempt++) {
+    for (let attempt = 1; attempt <= RECONNECT_DELAYS_MS.length + 1; attempt++) {
       emit("reconnecting", { attempt, code });
-      await new Promise((r) => setTimeout(r, RECONNECT_DELAYS_MS[attempt - 1]));
       if (intentionalLeave || dead) return;
       try {
         const next = await client.reconnect(token);
         room = next;
         wireRoom(next);
         emit("reconnected");
+        if (droppedWhileOffline > 0) {
+          console.warn(
+            `[multiplayer] ${droppedWhileOffline} fire-and-forget event(s)/input(s) were dropped while reconnecting \u2014 they are not buffered; player/object state re-synced automatically.`
+          );
+          droppedWhileOffline = 0;
+        }
         return;
       } catch {
       }
+      if (attempt <= RECONNECT_DELAYS_MS.length) {
+        await new Promise((r) => setTimeout(r, RECONNECT_DELAYS_MS[attempt - 1]));
+        if (intentionalLeave || dead) return;
+      }
     }
     dead = true;
     emit("disconnect", code);
@@ -384,8 +450,12 @@ function attachSession(client, initialRoom) {
     },
     me: {
       set(state) {
-        localState = { ...state };
-        room.send("state", JSON.stringify({ ...state, [SEND_TIME_KEY]: nowMs() }));
+        if (SEND_TIME_KEY in state) {
+          console.warn(`[multiplayer] '${SEND_TIME_KEY}' is a reserved field name and will be overwritten by the send timestamp \u2014 rename it.`);
+        }
+        const clean = sanitizeFinite(state);
+        localState = clean;
+        send0("state", JSON.stringify({ ...clean, [SEND_TIME_KEY]: nowMs() }));
       }
     },
     shared: {
@@ -395,7 +465,7 @@ function attachSession(client, initialRoom) {
       },
       set(key, value) {
         if (key.startsWith(RESERVED_PREFIX)) return;
-        room.send("shared", { key, value: JSON.stringify(value) });
+        send0("shared", { key, value: JSON.stringify(sanitizeFinite(value)) });
       },
       keys() {
         return room.state?.shared ? Array.from(room.state.shared.keys()).filter((k) => !k.startsWith(RESERVED_PREFIX)) : [];
@@ -405,13 +475,13 @@ function attachSession(client, initialRoom) {
       claim(id) {
         const key = String(id);
         objOwners.set(key, room.sessionId);
-        room.send("claim", { id: key });
+        send0("claim", { id: key });
       },
       release(id) {
         const key = String(id);
         localObjState.delete(key);
         if (objOwners.get(key) === room.sessionId) objOwners.delete(key);
-        room.send("release", { id: key });
+        send0("release", { id: key });
       },
       remove(id) {
         const key = String(id);
@@ -421,12 +491,13 @@ function attachSession(client, initialRoom) {
           objOwners.delete(key);
           clearStream(OBJ_PREFIX + key);
         }
-        room.send("destroy", { id: key });
+        send0("destroy", { id: key });
       },
       set(id, state) {
         const key = String(id);
-        if (objOwners.get(key) === room.sessionId) localObjState.set(key, { ...state });
-        room.send("obj", { id: key, d: { ...state } });
+        const clean = sanitizeFinite(state);
+        if (objOwners.get(key) === room.sessionId) localObjState.set(key, clean);
+        send0("obj", { id: key, d: clean, t: nowMs() });
       },
       get(id) {
         const key = String(id);
@@ -457,7 +528,7 @@ function attachSession(client, initialRoom) {
     },
     inputs: {
       send(payload) {
-        room.send(INPUT_MSG, payload);
+        send0(INPUT_MSG, sanitizeFinite(payload), true);
       },
       on(cb) {
         let set = emitters.get(INPUT_MSG);
@@ -476,7 +547,7 @@ function attachSession(client, initialRoom) {
           last = nowMs();
           timer = setInterval(() => {
             const t = nowMs();
-            cb(t - last);
+            cb(Math.min(t - last, 250));
             last = t;
           }, Math.max(10, Math.round(1e3 / hz)));
         } else if (!shouldRun && timer) {
@@ -498,7 +569,7 @@ function attachSession(client, initialRoom) {
         console.warn(`[multiplayer] send('${type}') collides with a relay-internal channel \u2014 use a different event name`);
         return;
       }
-      room.send(type, payload);
+      send0(type, payload, true);
     },
     leave() {
       intentionalLeave = true;
@@ -508,6 +579,7 @@ function attachSession(client, initialRoom) {
   Object.defineProperty(session, ROOM_REF, { value: () => room, enumerable: false });
   return session;
 }
+var SEARCH_BACKOFF_MS = [1e3, 2e3, 4e3];
 var resolveAuth = (auth) => typeof auth === "function" ? auth() : auth;
 var matchJoinOptions = (opts) => ({
   gameId: opts.room,
@@ -581,48 +653,64 @@ async function matchmake(opts) {
   let queueRoom = null;
   let queueInfo = { position: 0, size: 0 };
   let cancelled = false;
+  let searching = 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;
+    if (cancelled || searching) return;
+    searching = true;
     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)
-    );
-    q.onLeave(() => {
-      if (cancelled || queueRoom !== q) return;
-      queueRoom = null;
-      void (async () => {
-        for (const delayMs of RECONNECT_DELAYS_MS) {
-          await new Promise((r) => setTimeout(r, delayMs));
-          if (cancelled || queueRoom || session) return;
-          await search();
-          if (queueRoom || session) return;
+      session = null;
+      matchRoom = null;
+      for (let attempt = 0; ; attempt++) {
+        if (queueRoom) {
+          void queueRoom.leave();
+          queueRoom = null;
         }
-      })();
-    });
-    emit("searching");
+        queueInfo = { position: 0, size: 0 };
+        let q;
+        try {
+          q = await client.joinOrCreate(QUEUE_ROOM_TYPE, matchJoinOptions(opts));
+        } catch (err) {
+          if (cancelled) return;
+          const delay = SEARCH_BACKOFF_MS[attempt];
+          if (delay == null) {
+            emit("error", err);
+            return;
+          }
+          await new Promise((r) => setTimeout(r, delay));
+          if (cancelled) return;
+          continue;
+        }
+        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)
+        );
+        q.onLeave(() => {
+          if (cancelled || queueRoom !== q) return;
+          queueRoom = null;
+          void (async () => {
+            for (const delayMs of RECONNECT_DELAYS_MS) {
+              await new Promise((r) => setTimeout(r, delayMs));
+              if (cancelled || queueRoom || session) return;
+              await search();
+              if (queueRoom || session) return;
+            }
+          })();
+        });
+        emit("searching");
+        return;
+      }
+    } finally {
+      searching = false;
+    }
   };
   const consumeSeat = async (reservation, role) => {
     try {
@@ -656,7 +744,7 @@ async function matchmake(opts) {
     session = null;
     await search();
   };
-  await search();
+  void search();
   const liveRoom = () => session ? roomOf(session) : null;
   return {
     get session() {
@@ -675,6 +763,10 @@ async function matchmake(opts) {
     finish() {
       liveRoom()?.send("match:finish", {});
     },
+    retry() {
+      if (cancelled || searching || queueRoom || matchRoom) return;
+      void search();
+    },
     cancel() {
       cancelled = true;
       session?.leave();
@@ -719,6 +811,8 @@ function wirePrivate(client, room) {
     finish() {
       liveRoom()?.send("match:finish", {});
     },
+    retry() {
+    },
     cancel() {
       session.leave();
       live = false;

package/package.json

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