@unboxy/phaser-sdk 0.2.4 → 0.2.5

package/SDK-GUIDE.md

@@ -9,7 +9,7 @@ Reference for AI agents building games on the Unboxy platform. Tracks the **inst
 - `Unboxy.init()` — platform services entry point
 - `unboxy.saves` — **per-user** key-value store (only the owner sees/writes their data)
 - `unboxy.gameData` — **per-game** key-value store (read by anyone; write requires auth)
-- (future: multiplayer lobbies)
+- `unboxy.rooms` — **multiplayer rooms** (server-authoritative state sync, requires sign-in and host support)
 
 ## Platform services
 
@@ -183,6 +183,56 @@ Rule of thumb: if two different players would write to the same key, it's `gameD
 - **Reads are cheap and public.** No auth needed — even logged-out players see `gameData`. Don't put anything secret here.
 - **Trust is thin.** The backend stores what you write, verbatim. A player with devtools could submit any JSON. For casual games this is fine; for competitive stakes, a future typed leaderboards API with server-side validation is the right fix.
 
+### Multiplayer rooms — `unboxy.rooms`
+
+Realtime rooms backed by unboxy-realtime-service. The server is authoritative — clients send intents; the server updates state; every client receives the delta. This layer is for *live* shared play; persistent leaderboards/scores still belong in `gameData` or `saves`.
+
+```ts
+// Join or create a room scoped to this game. The SDK fetches a short-lived
+// token from the host and forwards it; the iframe never handles credentials.
+const room = await unboxy.rooms.joinOrCreate('lobby', {
+  displayName: unboxy.user?.name ?? 'guest',
+});
+
+// Read server state (Colyseus Schema proxy — access fields directly)
+room.state;           // e.g. { players: Map, gameId, ... } depending on room type
+room.id;              // room identifier
+room.sessionId;       // this connection's session id within the room
+
+// React to server updates
+const offState = room.onStateChange((state) => {
+  // re-render player list, scores, etc.
+});
+
+// Messages (server ↔ client, typed by name)
+const offHit = room.on('hit', (payload) => { /* apply a hit effect */ });
+room.send('move', { x: 120, y: 340 });
+
+// Connection lifecycle
+room.onLeave((code) => console.log('disconnected', code));
+room.onError((code, message) => console.warn('room error', code, message));
+
+// Clean up when the scene is destroyed
+offState();
+offHit();
+await room.leave();
+```
+
+**Availability**
+- Requires sign-in. Anonymous players get `RpcError('UNAUTHENTICATED')`.
+- Requires a host with multiplayer enabled. Standalone games (no host) get `RpcError('REALTIME_UNAVAILABLE')` — guard with `if (unboxy.host === 'unboxy-home-ui')` if your game can run both hosted and standalone.
+
+**Available room types (server-owned)**
+- `lobby` — simple player list with `ready` flag and chat broadcast. Use for pre-match staging.
+- (more coming: `TurnBasedRoom`, `RealtimeSyncRoom`)
+
+**Rules of the road**
+- The server is the source of truth. Never trust `send()` payloads coming from other clients — the server validates.
+- Room state is *ephemeral*. When the last player leaves, it disposes. Persist anything you want to keep via `saves` or `gameData`.
+- Keep messages small. State syncs are delta-compressed; raw `send()` payloads are not.
+- Unsubscribe on scene shutdown. `onStateChange`, `on`, `onLeave`, `onError` all return an unsubscribe function — call them from `scene.events.once('shutdown', ...)`.
+- One Colyseus client is kept internally; repeated `joinOrCreate` calls reuse it and mint fresh tokens each connection.
+
 ## Anti-patterns (don't do these)
 
 - Do **not** call `Unboxy.init()` inside a scene. Initialize at module load in `main.ts` and export the promise.
@@ -195,6 +245,7 @@ Rule of thumb: if two different players would write to the same key, it's `gameD
 
 ## Changelog
 
+- **0.2.5** — added `unboxy.rooms` module (server-authoritative multiplayer rooms backed by Colyseus on unboxy-realtime-service). Requires sign-in. Host must advertise `realtime` capability. Colyseus client loaded lazily — single-player games do not pay for the dependency.
 - **0.2.4** — added `unboxy.gameData` module (game-scope key-value store for scoreboards, shared state)
 - **0.2.3** — anonymous users now use localStorage even inside a host (was throwing UNAUTHENTICATED when calling `saves` in home-ui without login)
 - **0.2.2** — added `SDK-GUIDE.md`

package/dist/core/Transport.d.ts

@@ -13,6 +13,12 @@ export interface Transport {
     readonly kind: TransportKind;
     readonly user: UnboxyUser | null;
     readonly gameId: string;
+    /**
+     * Endpoint for unboxy-realtime-service (WebSocket URL). Set by the host
+     * during handshake when multiplayer is enabled. Absent in standalone mode —
+     * `unboxy.rooms.*` is unavailable in that case.
+     */
+    readonly realtimeUrl?: string;
     call<T = unknown>(method: string, params?: unknown): Promise<T>;
 }
 export type TransportKind = 'unboxy-home-ui' | 'standalone' | 'discord';

package/dist/core/Unboxy.d.ts

@@ -1,6 +1,7 @@
 import type { TransportKind } from './Transport.js';
 import { SavesModule } from '../saves/SavesModule.js';
 import { GameDataModule } from '../gamedata/GameDataModule.js';
+import { RealtimeModule } from '../realtime/RealtimeModule.js';
 import type { UnboxyUser } from '../protocol.js';
 export interface UnboxyInitOptions {
     /** Handshake timeout in ms when running inside a host. Default 2000. */
@@ -22,6 +23,7 @@ export declare class Unboxy {
     private transport;
     readonly saves: SavesModule;
     readonly gameData: GameDataModule;
+    readonly rooms: RealtimeModule;
     private constructor();
     /** The current authenticated user, or `null` if anonymous / standalone. */
     get user(): UnboxyUser | null;

package/dist/core/Unboxy.js

@@ -2,8 +2,9 @@ import { PostMessageTransport } from './transports/PostMessageTransport.js';
 import { LocalStorageTransport } from './transports/LocalStorageTransport.js';
 import { SavesModule } from '../saves/SavesModule.js';
 import { GameDataModule } from '../gamedata/GameDataModule.js';
+import { RealtimeModule } from '../realtime/RealtimeModule.js';
 // Kept in sync with package.json on each publish.
-const SDK_VERSION = '0.2.4';
+const SDK_VERSION = '0.2.5';
 /**
  * Unboxy platform services bound to the current (game, user).
  *
@@ -27,6 +28,10 @@ export class Unboxy {
         // fallback (standalone mode) that also works — the module speaks the
         // same RPC interface.
         this.gameData = new GameDataModule(transport);
+        // Multiplayer requires a realtime endpoint from the host. When absent
+        // (standalone or a host without multiplayer), methods throw a clear
+        // REALTIME_UNAVAILABLE error rather than silently misbehaving.
+        this.rooms = new RealtimeModule(transport, transport.realtimeUrl);
     }
     /** The current authenticated user, or `null` if anonymous / standalone. */
     get user() { return this.transport.user; }

package/dist/core/transports/PostMessageTransport.d.ts

@@ -9,6 +9,7 @@ export declare class PostMessageTransport implements Transport {
     readonly kind: "unboxy-home-ui";
     user: UnboxyUser | null;
     gameId: string;
+    realtimeUrl?: string;
     private pending;
     private seq;
     private constructor();

package/dist/core/transports/PostMessageTransport.js

@@ -51,6 +51,7 @@ export class PostMessageTransport {
         }
         transport.user = init.user;
         transport.gameId = init.gameId;
+        transport.realtimeUrl = init.realtimeUrl;
         transport.installResultListener();
         return transport;
     }

package/dist/index.d.ts

@@ -7,7 +7,10 @@ export { Unboxy } from './core/Unboxy.js';
 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 { UnboxyRoom } from './realtime/UnboxyRoom.js';
 export { RpcError } from './core/Transport.js';
 export type { Transport, TransportKind } from './core/Transport.js';
 export type { UnboxyUser } from './protocol.js';
-export { PROTOCOL_VERSION, type HelloMessage, type InitMessage, type RpcRequestMessage, type RpcResultOk, type RpcResultError, type HostToSdkMessage, type SdkToHostMessage, type RpcErrorPayload, type RpcMethod, type SavesGetParams, type SavesGetResult, type SavesSetParams, type SavesSetResult, type SavesDeleteParams, type SavesDeleteResult, type SavesListResult, type GameDataGetParams, type GameDataGetResult, type GameDataSetParams, type GameDataSetResult, type GameDataDeleteParams, type GameDataDeleteResult, type GameDataListResult, } from './protocol.js';
+export { PROTOCOL_VERSION, type HelloMessage, type InitMessage, type RpcRequestMessage, type RpcResultOk, type RpcResultError, type HostToSdkMessage, type SdkToHostMessage, type RpcErrorPayload, type RpcMethod, type SavesGetParams, type SavesGetResult, type SavesSetParams, type SavesSetResult, type SavesDeleteParams, type SavesDeleteResult, type SavesListResult, type GameDataGetParams, type GameDataGetResult, type GameDataSetParams, type GameDataSetResult, type GameDataDeleteParams, type GameDataDeleteResult, type GameDataListResult, type RealtimeGetTokenParams, type RealtimeGetTokenResult, } from './protocol.js';

package/dist/index.js

@@ -9,5 +9,7 @@ export { setupRecordingListener } from './recording/RecordingManager.js';
 export { Unboxy } from './core/Unboxy.js';
 export { SavesModule } from './saves/SavesModule.js';
 export { GameDataModule } from './gamedata/GameDataModule.js';
+export { RealtimeModule } from './realtime/RealtimeModule.js';
+export { UnboxyRoom } from './realtime/UnboxyRoom.js';
 export { RpcError } from './core/Transport.js';
 export { PROTOCOL_VERSION, } from './protocol.js';

package/dist/protocol.d.ts

@@ -22,6 +22,12 @@ export interface InitMessage {
     gameId: string;
     user: UnboxyUser | null;
     capabilities: string[];
+    /**
+     * WebSocket endpoint for unboxy-realtime-service. Present only when the host
+     * has multiplayer configured (capabilities includes 'realtime'). SDK connects
+     * here after fetching a JWT via the 'realtime.getToken' RPC.
+     */
+    realtimeUrl?: string;
 }
 export interface RpcResultOk {
     type: 'unboxy:rpc.result';
@@ -40,7 +46,7 @@ export interface RpcResultError {
     error: RpcErrorPayload;
 }
 export type HostToSdkMessage = InitMessage | RpcResultOk | RpcResultError;
-export type RpcMethod = 'saves.get' | 'saves.set' | 'saves.delete' | 'saves.list' | 'gameData.get' | 'gameData.set' | 'gameData.delete' | 'gameData.list';
+export type RpcMethod = 'saves.get' | 'saves.set' | 'saves.delete' | 'saves.list' | 'gameData.get' | 'gameData.set' | 'gameData.delete' | 'gameData.list' | 'realtime.getToken';
 export interface SavesGetParams {
     key: string;
 }
@@ -89,3 +95,12 @@ export type GameDataDeleteResult = {
 export interface GameDataListResult {
     keys: string[];
 }
+export interface RealtimeGetTokenParams {
+    /** Opaque, forwarded to server-side auth (future use). */
+    purpose?: string;
+}
+export interface RealtimeGetTokenResult {
+    token: string;
+    /** Epoch millis when the token expires. */
+    expiresAt: number;
+}

package/dist/realtime/RealtimeModule.d.ts

@@ -0,0 +1,30 @@
+import type { Transport } from '../core/Transport.js';
+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;
+}
+/**
+ * Multiplayer rooms backed by unboxy-realtime-service (Colyseus under the hood).
+ *
+ * Availability: only when the host provided a `realtimeUrl` during the
+ * handshake (i.e. connected to unboxy-home-ui with multiplayer enabled).
+ * Unavailable in standalone/anonymous mode — methods throw RpcError
+ * 'REALTIME_UNAVAILABLE'.
+ *
+ * Tokens are fetched per connection attempt via the `realtime.getToken`
+ * RPC — the iframe never holds a long-lived credential.
+ */
+export declare class RealtimeModule {
+    private readonly transport;
+    private readonly realtimeUrl;
+    private client;
+    constructor(transport: Transport, realtimeUrl: string | undefined);
+    /** `true` when a realtime endpoint was provided by the host. */
+    get available(): boolean;
+    joinOrCreate<State = unknown>(roomType: string, options?: JoinOptions): Promise<UnboxyRoom<State>>;
+    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>>;
+    private connect;
+}

package/dist/realtime/RealtimeModule.js

@@ -0,0 +1,54 @@
+import { RpcError } from '../core/Transport.js';
+import { UnboxyRoom } from './UnboxyRoom.js';
+/**
+ * Multiplayer rooms backed by unboxy-realtime-service (Colyseus under the hood).
+ *
+ * Availability: only when the host provided a `realtimeUrl` during the
+ * handshake (i.e. connected to unboxy-home-ui with multiplayer enabled).
+ * Unavailable in standalone/anonymous mode — methods throw RpcError
+ * 'REALTIME_UNAVAILABLE'.
+ *
+ * Tokens are fetched per connection attempt via the `realtime.getToken`
+ * RPC — the iframe never holds a long-lived credential.
+ */
+export class RealtimeModule {
+    constructor(transport, realtimeUrl) {
+        this.transport = transport;
+        this.realtimeUrl = realtimeUrl;
+        this.client = null;
+    }
+    /** `true` when a realtime endpoint was provided by the host. */
+    get available() {
+        return typeof this.realtimeUrl === 'string' && this.realtimeUrl.length > 0;
+    }
+    async joinOrCreate(roomType, options = {}) {
+        return this.connect(roomType, options, 'joinOrCreate');
+    }
+    async create(roomType, options = {}) {
+        return this.connect(roomType, options, 'create');
+    }
+    async join(roomType, options = {}) {
+        return this.connect(roomType, options, 'join');
+    }
+    async joinById(roomId, options = {}) {
+        return this.connect(roomId, options, 'joinById');
+    }
+    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.');
+        }
+        if (!this.client) {
+            // Dynamic import so single-player games do not pull Colyseus into their
+            // bundle. Vite tree-shakes this path when `rooms` is never referenced.
+            const { Client } = await import('colyseus.js');
+            this.client = new Client(this.realtimeUrl);
+        }
+        const { token } = await this.transport.call('realtime.getToken', {});
+        // Inject gameId from the transport so the server-side gameId check sees
+        // a value consistent with the JWT — games never pass this directly.
+        const merged = { ...options, gameId: this.transport.gameId };
+        this.client.auth.token = token;
+        const room = await this.client[method](nameOrId, merged);
+        return new UnboxyRoom(room);
+    }
+}

package/dist/realtime/UnboxyRoom.d.ts

@@ -0,0 +1,36 @@
+import type { Room } from 'colyseus.js';
+type Unsubscribe = () => void;
+/**
+ * Unboxy-flavored wrapper around a Colyseus Room. Exposes only the surface
+ * documented in SDK-GUIDE.md so games are portable to a different realtime
+ * backend should we migrate away from Colyseus.
+ */
+export declare class UnboxyRoom<State = unknown> {
+    private readonly room;
+    constructor(room: Room<State>);
+    get id(): string;
+    get name(): string;
+    get sessionId(): string;
+    /**
+     * Current server-authoritative state. Proxied from Colyseus Schema — read
+     * values directly. Mutations do not propagate; only server-side handlers
+     * may change state.
+     */
+    get state(): State;
+    /** Send a typed message to the server. */
+    send(type: string, payload?: unknown): void;
+    /** Register a handler for a server-sent message type. Returns unsubscribe. */
+    on(type: string, handler: (payload: unknown) => void): Unsubscribe;
+    /** Fires whenever the server-authoritative state changes. */
+    onStateChange(handler: (state: State) => void): Unsubscribe;
+    /**
+     * Fires when the connection closes (kick, server shutdown, network drop).
+     * `code` follows WebSocket close codes plus Colyseus-specific ones.
+     */
+    onLeave(handler: (code: number) => void): Unsubscribe;
+    /** Fires when the server reports an error for this room. */
+    onError(handler: (code: number, message?: string) => void): Unsubscribe;
+    /** Disconnect from the room. Resolves with the close code. */
+    leave(consented?: boolean): Promise<number>;
+}
+export {};

package/dist/realtime/UnboxyRoom.js

@@ -0,0 +1,52 @@
+/**
+ * Unboxy-flavored wrapper around a Colyseus Room. Exposes only the surface
+ * documented in SDK-GUIDE.md so games are portable to a different realtime
+ * backend should we migrate away from Colyseus.
+ */
+export class UnboxyRoom {
+    constructor(room) {
+        this.room = room;
+    }
+    get id() { return this.room.roomId; }
+    get name() { return this.room.name; }
+    get sessionId() { return this.room.sessionId; }
+    /**
+     * Current server-authoritative state. Proxied from Colyseus Schema — read
+     * values directly. Mutations do not propagate; only server-side handlers
+     * may change state.
+     */
+    get state() { return this.room.state; }
+    /** Send a typed message to the server. */
+    send(type, payload) {
+        this.room.send(type, payload);
+    }
+    /** Register a handler for a server-sent message type. Returns unsubscribe. */
+    on(type, handler) {
+        return this.room.onMessage(type, handler);
+    }
+    /** Fires whenever the server-authoritative state changes. */
+    onStateChange(handler) {
+        const cb = () => handler(this.room.state);
+        this.room.onStateChange(cb);
+        return () => this.room.onStateChange.remove(cb);
+    }
+    /**
+     * Fires when the connection closes (kick, server shutdown, network drop).
+     * `code` follows WebSocket close codes plus Colyseus-specific ones.
+     */
+    onLeave(handler) {
+        const cb = (code) => handler(code);
+        this.room.onLeave(cb);
+        return () => this.room.onLeave.remove(cb);
+    }
+    /** Fires when the server reports an error for this room. */
+    onError(handler) {
+        const cb = (code, message) => handler(code, message);
+        this.room.onError(cb);
+        return () => this.room.onError.remove(cb);
+    }
+    /** Disconnect from the room. Resolves with the close code. */
+    async leave(consented = true) {
+        return this.room.leave(consented);
+    }
+}

package/package.json

@@ -1,18 +1,25 @@
 {
   "name": "@unboxy/phaser-sdk",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Unboxy Phaser 3 SDK — game infrastructure for the Unboxy platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["dist", "SDK-GUIDE.md"],
+  "files": [
+    "dist",
+    "SDK-GUIDE.md"
+  ],
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "npm run build"
   },
+  "dependencies": {
+    "colyseus.js": "^0.16.0"
+  },
   "peerDependencies": {
     "phaser": "^3.60.0"
   },
   "devDependencies": {
+    "jose": "^6.2.2",
     "phaser": "^3.80.0",
     "typescript": "^5.5.0"
   },