@unboxy/phaser-sdk 0.2.10 → 0.2.12

package/SDK-GUIDE.md

@@ -237,6 +237,107 @@ room.sessionId;  // this connection's session id within the room
 room.state;      // proxy of the server-authoritative schema
 ```
 
+**Room type is always `'lobby'`.** This is the only room type the realtime server registers — there is no `'blokus'` / `'chess'` / `'mygame'` type. Passing any other name results in "no handler" and throws. To distinguish rooms (private matches, per-code lobbies, etc.) use the `roomCode` option, documented below.
+
+#### Matchmaking — one game can have many rooms
+
+By default (no `roomCode`), every player of the same game lands in **one shared room**. Fine for a single hangout or a "public lobby" — but not for games where users need to open *private* rooms (e.g. "play this match with my friend" / "create a room with code ABC123 and share it").
+
+Use the `roomCode` option to bucket players. Two clients with the same `(gameId, roomCode)` join the same room; different codes create independent rooms.
+
+```ts
+// --- Create a private room with a fresh code ---
+const code = Math.random().toString(36).slice(2, 8).toUpperCase();  // e.g. 'AB3X7Y'
+const hostRoom = await unboxy.rooms.joinOrCreate('lobby', {
+  roomCode: code,
+  maxClients: 4,                       // cap to 4 players (server clamps to [1, 16])
+  displayName: unboxy.user?.name ?? 'host',
+});
+
+// Show `code` in the UI; the host shares it with friends manually.
+
+// --- Friend joins the same room with the shared code ---
+const guestRoom = await unboxy.rooms.joinOrCreate('lobby', {
+  roomCode: 'AB3X7Y',                  // whatever the host shared
+  displayName: unboxy.user?.name ?? 'guest',
+});
+```
+
+**`roomCode` caveats:**
+- Not a password. Anyone who knows the code can join. Use it for unguessable rather than *secret*.
+- Defaults to empty string when omitted. Two clients that both omit `roomCode` share the same "default" room — useful for a single global lobby per game.
+- Changing `roomCode` between joins does NOT transfer state; it's a different room. Leave the old room (`room.leave()`) before joining a new one.
+
+**`maxClients` caveats:**
+- Only honored by the client who CREATES the room (the first one in). Later joiners see the creator's choice.
+- Server clamps to `[1, 16]`. Passing `maxClients: 1000` silently becomes 16.
+- When full, `joinOrCreate` throws. Handle that in your UI (e.g. "Room is full. Ask your friend to create a smaller room or try a different code.").
+
+**Quick match / public room pattern.** If you want a "click Play, get matched with someone" flow, omit `roomCode` — everyone lands in the same default room. Players are differentiated by their `sessionId`. Add your own ready / waiting logic in `room.data`.
+
+```ts
+// Public quick match — no roomCode, everyone shares one room per game
+const room = await unboxy.rooms.joinOrCreate('lobby', {
+  maxClients: 2,
+  displayName: unboxy.user?.name ?? 'guest',
+});
+```
+
+#### Browsing open rooms — `unboxy.rooms.list()`
+
+A room code is enough for "my friend and I agreed on code ABC123 out of band", but not for "show me a list of open games and let me click one to join." For that, ask the server what rooms are currently open for your game:
+
+```ts
+interface RoomListEntry {
+  roomId: string;          // opaque — pass to joinById
+  roomCode: string;        // the code the host passed (empty for default rooms)
+  clients: number;         // current occupants
+  maxClients: number;      // cap the host set (server-clamped to [1, 16])
+  metadata?: unknown;      // whatever the host set via room.setMetadata (optional)
+  createdAt?: number;      // ms since epoch
+}
+
+const rooms = await unboxy.rooms.list();
+rooms
+  .filter(r => r.clients < r.maxClients)  // hide full rooms
+  .forEach(renderLobbyCard);
+
+// On click:
+async function joinRoom(entry: RoomListEntry) {
+  const room = await unboxy.rooms.joinById(entry.roomId, {
+    displayName: unboxy.user?.name ?? 'guest',
+  });
+  // room state is populated after the first onStateChange — see
+  // "Connection lifecycle" below for the state-timing rule.
+}
+```
+
+**Scope.** `list()` only returns rooms for the caller's game. A player can't see rooms from other games (the server cross-checks the gameId claim on the token).
+
+**Filter.** Pass `{ roomCode: 'ABC' }` to narrow to one code without paging through the whole list — useful for "is the room with code ABC up yet?" polling.
+
+**Polling, not subscription.** There is no push-on-change API today. Poll on a timer (e.g. every 3-5 s) while the lobby is open, and refresh on the user's explicit click. Cancel the timer when the player leaves the lobby.
+
+```ts
+// Simple lobby browser refresh loop
+let stop = false;
+async function refreshLoop() {
+  while (!stop) {
+    try {
+      const rooms = await unboxy.rooms.list();
+      renderLobby(rooms);
+    } catch (e) {
+      // Network hiccup or REALTIME_UNAVAILABLE — surface in UI, keep looping.
+    }
+    await new Promise(r => setTimeout(r, 3000));
+  }
+}
+refreshLoop();
+scene.events.once('shutdown', () => { stop = true; });
+```
+
+**Unlisted rooms.** Every room created via `joinOrCreate` / `create` is currently listable by players of the same game. There is no "private room" flag yet — if you need that, tell your users to share the code out of band and don't render a lobby browser.
+
 #### Delta-synced state — `room.player` and `room.data`
 
 Use this for anything that represents the *current world*: positions, hp, score, turn state, scoreboard, etc. The server delta-syncs diffs to every client.
@@ -381,6 +482,8 @@ Don't blindly apply interpolation to everything. It's wrong for a chess piece an
 
 ## Changelog
 
+- **0.2.12** — added `unboxy.rooms.list(options?)` — returns the open rooms for the caller's game right now, scoped server-side to the caller's gameId. Use this to build a lobby browser ("show me open rooms, click to join") without needing an out-of-band room code. SDK-GUIDE adds a "Browsing open rooms" section under Multiplayer covering the `RoomListEntry` shape, the poll-on-timer pattern, and the `{ roomCode }` filter for "is room X up yet?" probes.
+- **0.2.11** — added `roomCode` + `maxClients` to `JoinOptions`. SDK-GUIDE's Multiplayer chapter now documents matchmaking: room type is always `'lobby'`; use `roomCode` to bucket independent rooms per gameId (create-with-fresh-code, join-with-shared-code, quick-match with empty code). Fixes a real bug where agents were passing a gameId-derived string as the room type (e.g. `joinOrCreate('blokus-<code>', ...)`) and failing with "no handler" server-side.
 - **0.2.10** — docs: added a `createUnboxyGame` options table (including the new `plugins` field) and a third-party Phaser plugin registration example. No code changes; version bumped so existing workspaces pick up the new guidance via `npm update @unboxy/phaser-sdk`.
 - **0.2.9** — `createUnboxyGame` now forwards the optional `plugins` field to Phaser's `GameConfig`. Previously the option was accepted at the call site but silently dropped — any `phaser3-rex-plugins` (or similar) registration never took effect, and `this.plugins.get(key)` returned undefined at runtime. Purely additive; no effect on games that don't pass `plugins`. Lets the `phaser-rex-touch` agent skill work end-to-end.
 - **0.2.8** — docs: added "Making remote motion feel smooth" section to the multiplayer chapter with concrete examples for interpolation (continuous motion), extrapolation (projectiles), and snap (discrete/turn-based/infrequent). No code changes — version bumped so existing workspaces pick up the new guidance via `npm update @unboxy/phaser-sdk`.

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export type { UnboxyInitOptions } from './core/Unboxy.js';
 export { SavesModule } from './saves/SavesModule.js';
 export { GameDataModule } from './gamedata/GameDataModule.js';
 export { RealtimeModule } from './realtime/RealtimeModule.js';
-export type { JoinOptions } from './realtime/RealtimeModule.js';
+export type { JoinOptions, RoomListEntry, RoomListOptions } from './realtime/RealtimeModule.js';
 export { UnboxyRoom, PlayerDataFacade, RoomDataFacade } from './realtime/UnboxyRoom.js';
 export { RpcError } from './core/Transport.js';
 export type { Transport, TransportKind } from './core/Transport.js';

package/dist/realtime/RealtimeModule.d.ts

@@ -1,8 +1,51 @@
 import type { Transport } from '../core/Transport.js';
 import { UnboxyRoom } from './UnboxyRoom.js';
+export interface RoomListEntry {
+    /** Opaque Colyseus room id — pass to `joinById` to connect. */
+    roomId: string;
+    /** Short code the host passed on create (empty string for default rooms). */
+    roomCode: string;
+    /** Current number of connected clients. */
+    clients: number;
+    /** Max clients the host set (server-clamped to [1, 16]). */
+    maxClients: number;
+    /** Whatever the host attached via `room.setMetadata(...)`. Unvalidated. */
+    metadata?: unknown;
+    /** Server-side creation time (ms since epoch). */
+    createdAt?: number;
+}
+export interface RoomListOptions {
+    /**
+     * Filter to rooms with this exact roomCode. Useful for "is a room with code
+     * X up yet?" polling without enumerating the whole list.
+     */
+    roomCode?: string;
+    /** Max entries to return. Server caps to 100 regardless. */
+    limit?: number;
+}
 export interface JoinOptions extends Record<string, unknown> {
     /** Optional display name passed to the server-side room on join. */
     displayName?: string;
+    /**
+     * Short code that distinguishes independent rooms for the same game.
+     * Empty / omitted means "the one shared room per game."
+     *
+     * Pass a non-empty value on `joinOrCreate` / `create` / `join` to bucket
+     * players into a private room. Two clients with the same `(gameId, roomCode)`
+     * land in the same room; different `roomCode` values create separate rooms.
+     * This is how you implement "Create Room" / "Join with code" UX — the
+     * server's `filterBy(["gameId", "roomCode"])` enforces the separation.
+     *
+     * Not a password: anyone who knows the code can join. Treat as an
+     * unguessability measure, not an access control.
+     */
+    roomCode?: string;
+    /**
+     * Cap on concurrent clients in the room the creator makes. Server clamps
+     * to [1, 16]. Defaults to 8 server-side. Only honored by the FIRST client
+     * (the creator) — later joiners see whatever the creator set.
+     */
+    maxClients?: number;
 }
 /**
  * Multiplayer rooms backed by unboxy-realtime-service (Colyseus under the hood).
@@ -26,5 +69,25 @@ export declare class RealtimeModule {
     create<State = unknown>(roomType: string, options?: JoinOptions): Promise<UnboxyRoom<State>>;
     join<State = unknown>(roomType: string, options?: JoinOptions): Promise<UnboxyRoom<State>>;
     joinById<State = unknown>(roomId: string, options?: JoinOptions): Promise<UnboxyRoom<State>>;
+    /**
+     * List the open rooms for the caller's game, as seen by the realtime
+     * service right now. Results are scoped server-side to the caller's
+     * gameId — you can't enumerate rooms from a different game.
+     *
+     * Use this to build a lobby browser ("show me open rooms, click to join").
+     * Poll on a timer or on a user's "Refresh" click; the API is request/
+     * response, not a live subscription.
+     *
+     * Example:
+     * ```ts
+     * const rooms = await unboxy.rooms.list();
+     * rooms
+     *   .filter(r => r.clients < r.maxClients)
+     *   .forEach(r => {
+     *     // render a button; on click: unboxy.rooms.joinById(r.roomId)
+     *   });
+     * ```
+     */
+    list(options?: RoomListOptions): Promise<RoomListEntry[]>;
     private connect;
 }

package/dist/realtime/RealtimeModule.js

@@ -33,6 +33,56 @@ export class RealtimeModule {
     async joinById(roomId, options = {}) {
         return this.connect(roomId, options, 'joinById');
     }
+    /**
+     * List the open rooms for the caller's game, as seen by the realtime
+     * service right now. Results are scoped server-side to the caller's
+     * gameId — you can't enumerate rooms from a different game.
+     *
+     * Use this to build a lobby browser ("show me open rooms, click to join").
+     * Poll on a timer or on a user's "Refresh" click; the API is request/
+     * response, not a live subscription.
+     *
+     * Example:
+     * ```ts
+     * const rooms = await unboxy.rooms.list();
+     * rooms
+     *   .filter(r => r.clients < r.maxClients)
+     *   .forEach(r => {
+     *     // render a button; on click: unboxy.rooms.joinById(r.roomId)
+     *   });
+     * ```
+     */
+    async list(options = {}) {
+        if (!this.available) {
+            throw new RpcError('REALTIME_UNAVAILABLE', 'Multiplayer is not available for this host. Unboxy.rooms.list requires running inside unboxy-home-ui with realtime enabled.');
+        }
+        const { token } = await this.transport.call('realtime.getToken', {});
+        const url = new URL(toHttpBase(this.realtimeUrl) + '/rooms');
+        url.searchParams.set('gameId', this.transport.gameId);
+        if (typeof options.roomCode === 'string')
+            url.searchParams.set('roomCode', options.roomCode);
+        if (typeof options.limit === 'number' && Number.isFinite(options.limit)) {
+            url.searchParams.set('limit', String(Math.floor(options.limit)));
+        }
+        const res = await fetch(url.toString(), {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!res.ok) {
+            let detail = '';
+            try {
+                const body = await res.json();
+                if (body && typeof body.error === 'string')
+                    detail = `: ${body.error}`;
+            }
+            catch { }
+            throw new RpcError('ROOMS_LIST_FAILED', `/rooms returned ${res.status}${detail}`);
+        }
+        const body = await res.json();
+        if (!body || !Array.isArray(body.rooms)) {
+            throw new RpcError('ROOMS_LIST_FAILED', '/rooms response missing rooms[]');
+        }
+        return body.rooms;
+    }
     async connect(nameOrId, options, method) {
         if (!this.available) {
             throw new RpcError('REALTIME_UNAVAILABLE', 'Multiplayer is not available for this host. Unboxy.rooms requires running inside unboxy-home-ui with realtime enabled.');
@@ -52,3 +102,14 @@ export class RealtimeModule {
         return new UnboxyRoom(room);
     }
 }
+// Convert the realtime WebSocket base (wss://ws.unboxy.com/rt or ws://…) to
+// the matching HTTP base used for the /rooms REST endpoint. Colyseus's HTTP
+// routes (/matchmake, /rooms, /health) ride the same nginx vhost + path
+// prefix as the WebSocket, so this is just a scheme swap.
+function toHttpBase(wsUrl) {
+    if (wsUrl.startsWith('wss://'))
+        return 'https://' + wsUrl.slice('wss://'.length);
+    if (wsUrl.startsWith('ws://'))
+        return 'http://' + wsUrl.slice('ws://'.length);
+    return wsUrl;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboxy/phaser-sdk",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "Unboxy Phaser 3 SDK — game infrastructure for the Unboxy platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",