@unboxy/phaser-sdk 0.2.9 → 0.2.11

package/SDK-GUIDE.md

@@ -11,6 +11,39 @@ Reference for AI agents building games on the Unboxy platform. Tracks the **inst
 - `unboxy.gameData` — **per-game** key-value store (read by anyone; write requires auth)
 - `unboxy.rooms` — **multiplayer rooms** (server-authoritative state sync, requires sign-in and host support)
 
+## `createUnboxyGame` options
+
+| field | type | note |
+|-------|------|------|
+| `width` | `number` | required |
+| `height` | `number` | required |
+| `scenes` | `Phaser.Scene class[]` | required |
+| `backgroundColor` | `string` | defaults to `'#1a1a2e'` |
+| `pixelArt` | `boolean` | defaults to `false` |
+| `physics` | `Phaser.Types.Core.PhysicsConfig` | defaults to arcade physics, no gravity |
+| `plugins` | `Phaser.Types.Core.PluginObject` | forwarded as-is into the Phaser `GameConfig`. **Since 0.2.9.** Earlier versions silently dropped this field. |
+
+Any field not listed is ignored. If you need something else (e.g. `callbacks`, custom `render` options), use plain `new Phaser.Game(config)` instead of `createUnboxyGame`.
+
+### Registering third-party Phaser plugins (e.g. rexUI)
+
+Pass them via the `plugins` option — do NOT try to register them inside a scene's `preload`:
+
+```ts
+import VirtualJoystickPlugin from 'phaser3-rex-plugins/plugins/virtualjoystick-plugin.js';
+
+createUnboxyGame({
+  // ...
+  plugins: {
+    global: [
+      { key: 'rexVirtualJoystick', plugin: VirtualJoystickPlugin, start: true },
+    ],
+  },
+});
+```
+
+Then in a scene: `this.plugins.get('rexVirtualJoystick').add(this, { ... })`.
+
 ## Platform services
 
 Initialize once at module load — resolves the host (home-ui, standalone, etc.) and returns a bound instance. Scenes read from the resulting promise.
@@ -204,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.
@@ -348,6 +427,8 @@ Don't blindly apply interpolation to everything. It's wrong for a chess piece an
 
 ## Changelog
 
+- **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`.
 - **0.2.7** — fixed handshake race on slow-mounting hosts. `PostMessageTransport.connect` now retries `unboxy:hello` every 200 ms until `unboxy:init` arrives (previously one-shot → lost on Android/mobile where React mounted after the iframe first fired hello). Default handshake timeout bumped from 2 s → 5 s.
 - **0.2.6** — redesigned `unboxy.rooms` around two generic primitives: delta-synced KV state (`room.player.set/get/delete`, `room.data.set/get/delete`) + transient relay (`room.send` / `room.on`). Server no longer bakes in game-specific fields like x/y/color/ready or a `move` handler — games define their own shapes via opaque JSON values, same contract as `gameData` / `saves`.

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.9",
+  "version": "0.2.11",
   "description": "Unboxy Phaser 3 SDK — game infrastructure for the Unboxy platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",