@unboxy/phaser-sdk 0.2.10 → 0.2.11

package/SDK-GUIDE.md

@@ -237,6 +237,52 @@ 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',
+});
+```
+
 #### 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.

package/dist/realtime/RealtimeModule.d.ts

@@ -3,6 +3,26 @@ import { UnboxyRoom } from './UnboxyRoom.js';
 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).

package/package.json

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