@genex-ai/multiplayer 0.8.0 → 0.8.1

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
@@ -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

@@ -508,6 +508,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 +582,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 +673,7 @@ async function matchmake(opts) {
     session = null;
     await search();
   };
-  await search();
+  void search();
   const liveRoom = () => session ? roomOf(session) : null;
   return {
     get session() {
@@ -675,6 +692,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 +740,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.1",
   "description": "The multiplayer client wrapper + shared room schema for genex.",
   "type": "module",
   "main": "./dist/index.js",