@unboxy/phaser-sdk 0.2.11 → 0.2.12

package/SDK-GUIDE.md

@@ -283,6 +283,61 @@ const room = await unboxy.rooms.joinOrCreate('lobby', {
 });
 ```
 
+#### 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.
@@ -427,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,5 +1,28 @@
 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;
@@ -46,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.11",
+  "version": "0.2.12",
   "description": "Unboxy Phaser 3 SDK — game infrastructure for the Unboxy platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",