@unboxy/phaser-sdk 0.2.3 → 0.2.5

package/SDK-GUIDE.md

@@ -6,8 +6,10 @@ Reference for AI agents building games on the Unboxy platform. Tracks the **inst
 
 - `createUnboxyGame(options)` — Phaser.Game factory with platform defaults (screenshot + recording wired up)
 - `UnboxyScene` — optional base scene with `createButton`, `shakeCamera`, `flashCamera` helpers
-- `Unboxy.init()` — platform services: identity, save data
-- (future: leaderboards, multiplayer lobbies)
+- `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)
+- `unboxy.rooms` — **multiplayer rooms** (server-authoritative state sync, requires sign-in and host support)
 
 ## Platform services
 
@@ -124,6 +126,113 @@ const saved = await unboxy.saves.get<number>('highScore').catch(() => null);
 this.highScore = typeof saved === 'number' ? saved : 0;
 ```
 
+### Game data — `unboxy.gameData`
+
+Same API shape as `saves`, but **game-scope**: one value per key, shared by all players of the game. Use it for things the whole playerbase sees — scoreboards, shared inventories, tournament state, level-of-the-day.
+
+```ts
+// Read — public. Works for anonymous visitors.
+type Entry = { name: string; score: number; at: number };
+const board = await unboxy.gameData.get<Entry[]>('leaderboard') ?? [];
+
+// Write — requires an authenticated user. Throws RpcError('UNAUTHENTICATED') otherwise.
+// Safe append: read + modify + write with ifVersion to avoid clobbering
+// concurrent writers (two players finishing at the same time).
+const { value: current, version } = await unboxy.gameData
+  .get<Entry[]>('leaderboard')
+  .then((v) => ({ value: v ?? [], version: null as number | null }))  // null means "not yet written"
+
+async function submitScore(name: string, score: number) {
+  if (!unboxy.isAuthenticated) return;             // skip for anonymous
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const raw = await unboxy.gameData.get<Entry[]>('leaderboard');
+    const list = Array.isArray(raw) ? raw : [];
+    const next = [...list, { name, score, at: Date.now() }]
+      .sort((a, b) => b.score - a.score)
+      .slice(0, 100);                              // cap to top 100 so we don't blow the 100 KB limit
+    try {
+      await unboxy.gameData.set('leaderboard', next);
+      return;                                      // success
+    } catch (err: any) {
+      if (err?.code !== 'VERSION_MISMATCH') throw err;
+      // another writer landed first — re-read and retry
+    }
+  }
+}
+```
+
+### Saves vs. gameData — which one?
+
+| Need | Use | Why |
+|---|---|---|
+| My personal high score | `saves` | Only I write it, only I read it. Anonymous-friendly (localStorage fallback). |
+| Progress through levels | `saves` | Per-user private state. |
+| Character / loadout choice | `saves` | Per-user. |
+| Scoreboard visible to everyone | `gameData` | Multiple users write; anyone reads. |
+| Today's puzzle / daily challenge | `gameData` | Single global value read by all players. |
+| Shared tournament bracket | `gameData` | Shared mutable state across players. |
+| Player name in a chat log | `gameData` | But consider size caps — chat is noisy. |
+| Current frame's enemy positions | *neither* — transient, don't persist | Wastes quota and confuses state after refresh. |
+
+Rule of thumb: if two different players would write to the same key, it's `gameData`. If a write from player A should never be visible to player B, it's `saves`.
+
+### Concurrency + size (gameData specifics)
+
+- **List writes race.** If two players append to `leaderboard` simultaneously, one overwrites the other's work. Use `ifVersion` for read-modify-write. On `VERSION_MISMATCH`, re-read and retry.
+- **Truncate.** A single key caps at 100 KB — roughly 500-1000 compact JSON entries. Keep lists bounded (top N, drop older), or shard across keys.
+- **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.
@@ -131,9 +240,13 @@ this.highScore = typeof saved === 'number' ? saved : 0;
 - Do **not** save on every frame / every score tick. Debounce or only save on meaningful events (game over, level clear).
 - Do **not** store large binary blobs (images, audio) as save values — use a dedicated blob API when it ships.
 - Do **not** use `localStorage` directly for persistent data when `unboxy.saves` is available — you'll lose cross-device sync when we ship provisional accounts.
+- Do **not** put secrets, private messages, or per-user data in `gameData` — it's public. That's `saves`.
+- Do **not** write to `gameData` on every score tick either — submit once at game-over or level-clear.
 
 ## 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`
 - **0.2.1** — added `Unboxy.init`, `unboxy.user`, `unboxy.saves`, Transport abstraction (PostMessage + LocalStorage backends)

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,5 +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. */
@@ -20,6 +22,8 @@ export interface UnboxyInitOptions {
 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

@@ -1,8 +1,10 @@
 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.3';
+const SDK_VERSION = '0.2.5';
 /**
  * Unboxy platform services bound to the current (game, user).
  *
@@ -13,14 +15,23 @@ const SDK_VERSION = '0.2.3';
 export class Unboxy {
     constructor(transport) {
         this.transport = transport;
-        // Saves are per-user. When the viewer is anonymous (no logged-in user),
-        // route save calls to localStorage even if a host is attached — the host
-        // backend requires auth, so forwarding would 401. Other module surfaces
-        // (future leaderboards, etc.) can still use the primary transport.
+        // Saves are per-user. When the viewer is anonymous, route save calls to
+        // localStorage even if a host is attached — the backend requires auth,
+        // so forwarding would 401. Games see the same `unboxy.saves` API either
+        // way and don't have to branch on auth state.
         const savesTransport = transport.user === null
             ? new LocalStorageTransport(transport.gameId || 'anonymous')
             : transport;
         this.saves = new SavesModule(savesTransport);
+        // gameData is game-scope: reads are public (anonymous OK), only writes
+        // need auth. The primary transport handles both; if it's a LocalStorage
+        // 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/LocalStorageTransport.d.ts

@@ -11,11 +11,12 @@ export declare class LocalStorageTransport implements Transport {
     readonly user: UnboxyUser | null;
     constructor(gameId: string);
     call<T = unknown>(method: string, params?: unknown): Promise<T>;
-    private prefix;
+    private savesPrefix;
+    private gameDataPrefix;
     private read;
     private write;
-    private savesGet;
-    private savesSet;
-    private savesDelete;
-    private savesList;
+    private kvGet;
+    private kvSet;
+    private kvDelete;
+    private kvList;
 }

package/dist/core/transports/LocalStorageTransport.js

@@ -12,18 +12,23 @@ export class LocalStorageTransport {
     }
     async call(method, params) {
         switch (method) {
-            case 'saves.get': return this.savesGet(params);
-            case 'saves.set': return this.savesSet(params);
-            case 'saves.delete': return this.savesDelete(params);
-            case 'saves.list': return this.savesList();
+            case 'saves.get': return this.kvGet(this.savesPrefix(), params);
+            case 'saves.set': return this.kvSet(this.savesPrefix(), params);
+            case 'saves.delete': return this.kvDelete(this.savesPrefix(), params);
+            case 'saves.list': return this.kvList(this.savesPrefix());
+            case 'gameData.get': return this.kvGet(this.gameDataPrefix(), params);
+            case 'gameData.set': return this.kvSet(this.gameDataPrefix(), params);
+            case 'gameData.delete': return this.kvDelete(this.gameDataPrefix(), params);
+            case 'gameData.list': return this.kvList(this.gameDataPrefix());
             default: throw new RpcError('UNKNOWN_METHOD', `Unknown method: ${method}`);
         }
     }
-    prefix() { return `unboxy:saves:${this.gameId}:`; }
-    read(key) {
+    savesPrefix() { return `unboxy:saves:${this.gameId}:`; }
+    gameDataPrefix() { return `unboxy:gameData:${this.gameId}:`; }
+    read(prefix, key) {
         if (typeof localStorage === 'undefined')
             return null;
-        const raw = localStorage.getItem(this.prefix() + key);
+        const raw = localStorage.getItem(prefix + key);
         if (!raw)
             return null;
         try {
@@ -33,41 +38,40 @@ export class LocalStorageTransport {
             return null;
         }
     }
-    write(key, rec) {
+    write(prefix, key, rec) {
         if (typeof localStorage === 'undefined')
             throw new RpcError('UNAVAILABLE', 'localStorage unavailable');
-        localStorage.setItem(this.prefix() + key, JSON.stringify(rec));
+        localStorage.setItem(prefix + key, JSON.stringify(rec));
     }
-    savesGet({ key }) {
-        const rec = this.read(key);
+    kvGet(prefix, { key }) {
+        const rec = this.read(prefix, key);
         return rec ? { value: rec.value, version: rec.version } : { value: null, version: null };
     }
-    savesSet({ key, value, ifVersion }) {
-        const existing = this.read(key);
+    kvSet(prefix, { key, value, ifVersion }) {
+        const existing = this.read(prefix, key);
         if (ifVersion !== undefined && existing && existing.version !== ifVersion) {
             throw new RpcError('VERSION_MISMATCH', `Expected version ${ifVersion} but stored is ${existing.version}`);
         }
         const next = { value, version: (existing?.version ?? 0) + 1 };
-        this.write(key, next);
+        this.write(prefix, key, next);
         return { version: next.version };
     }
-    savesDelete({ key }) {
+    kvDelete(prefix, { key }) {
         if (typeof localStorage === 'undefined')
             return { deleted: false };
-        const full = this.prefix() + key;
+        const full = prefix + key;
         const existed = localStorage.getItem(full) !== null;
         localStorage.removeItem(full);
         return { deleted: existed };
     }
-    savesList() {
+    kvList(prefix) {
         if (typeof localStorage === 'undefined')
             return { keys: [] };
         const keys = [];
-        const p = this.prefix();
         for (let i = 0; i < localStorage.length; i++) {
             const k = localStorage.key(i);
-            if (k && k.startsWith(p))
-                keys.push(k.slice(p.length));
+            if (k && k.startsWith(prefix))
+                keys.push(k.slice(prefix.length));
         }
         return { keys };
     }

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/gamedata/GameDataModule.d.ts

@@ -0,0 +1,45 @@
+import type { Transport } from '../core/Transport.js';
+/**
+ * Game-scope key-value store shared by all players of a game.
+ *
+ * Unlike `unboxy.saves` (per-user), `gameData` lives at the game level — one
+ * value per key, visible to everyone. Reads are public (anonymous players
+ * see the same data). Writes require an authenticated user; calling
+ * `set()` or `delete()` when `unboxy.user === null` throws an `RpcError`
+ * with code `UNAUTHENTICATED`.
+ *
+ * Typical uses: scoreboards, shared inventories, tournament state, level
+ * of the day. Values are opaque JSON — primitive, object, or collection.
+ *
+ * Trust model (see SDK-GUIDE.md for details):
+ *   - The backend does not enforce invariants INSIDE a value. If you store
+ *     a list and append your entry, you own the read-modify-write loop —
+ *     including not mutating other players' entries, truncating to cap
+ *     the list size, and retrying on 409 conflicts.
+ *   - Use `ifVersion` to avoid lost updates when concurrent writes race.
+ *
+ * Quotas (enforced at the backend):
+ *   - 100 KB per value
+ *   - 1 MB total per game
+ *   - 64 keys per game
+ */
+export declare class GameDataModule {
+    private transport;
+    constructor(transport: Transport);
+    /** Read the value under `key`. Returns `null` if unset. Public — works for anonymous viewers. */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Write `value` under `key`. Requires an authenticated user.
+     * @param options.ifVersion — only succeed if the stored version matches; otherwise throws
+     *   an RpcError with code `VERSION_MISMATCH`. Use this to implement safe read-modify-write
+     *   loops for list values (scoreboards, shared lists).
+     * @returns the new version number.
+     */
+    set(key: string, value: unknown, options?: {
+        ifVersion?: number;
+    }): Promise<number>;
+    /** Delete the value at `key`. Requires an authenticated user. */
+    delete(key: string): Promise<boolean>;
+    /** List all keys that have a value set for this game. Public. */
+    list(): Promise<string[]>;
+}

package/dist/gamedata/GameDataModule.js

@@ -0,0 +1,59 @@
+/**
+ * Game-scope key-value store shared by all players of a game.
+ *
+ * Unlike `unboxy.saves` (per-user), `gameData` lives at the game level — one
+ * value per key, visible to everyone. Reads are public (anonymous players
+ * see the same data). Writes require an authenticated user; calling
+ * `set()` or `delete()` when `unboxy.user === null` throws an `RpcError`
+ * with code `UNAUTHENTICATED`.
+ *
+ * Typical uses: scoreboards, shared inventories, tournament state, level
+ * of the day. Values are opaque JSON — primitive, object, or collection.
+ *
+ * Trust model (see SDK-GUIDE.md for details):
+ *   - The backend does not enforce invariants INSIDE a value. If you store
+ *     a list and append your entry, you own the read-modify-write loop —
+ *     including not mutating other players' entries, truncating to cap
+ *     the list size, and retrying on 409 conflicts.
+ *   - Use `ifVersion` to avoid lost updates when concurrent writes race.
+ *
+ * Quotas (enforced at the backend):
+ *   - 100 KB per value
+ *   - 1 MB total per game
+ *   - 64 keys per game
+ */
+export class GameDataModule {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** Read the value under `key`. Returns `null` if unset. Public — works for anonymous viewers. */
+    async get(key) {
+        const res = await this.transport.call('gameData.get', { key });
+        return (res?.value ?? null);
+    }
+    /**
+     * Write `value` under `key`. Requires an authenticated user.
+     * @param options.ifVersion — only succeed if the stored version matches; otherwise throws
+     *   an RpcError with code `VERSION_MISMATCH`. Use this to implement safe read-modify-write
+     *   loops for list values (scoreboards, shared lists).
+     * @returns the new version number.
+     */
+    async set(key, value, options) {
+        const res = await this.transport.call('gameData.set', {
+            key,
+            value,
+            ifVersion: options?.ifVersion,
+        });
+        return res.version;
+    }
+    /** Delete the value at `key`. Requires an authenticated user. */
+    async delete(key) {
+        const res = await this.transport.call('gameData.delete', { key });
+        return res.deleted;
+    }
+    /** List all keys that have a value set for this game. Public. */
+    async list() {
+        const res = await this.transport.call('gameData.list');
+        return res.keys;
+    }
+}

package/dist/index.d.ts

@@ -6,7 +6,11 @@ export { setupRecordingListener } from './recording/RecordingManager.js';
 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, } 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

@@ -8,5 +8,8 @@ export { setupRecordingListener } from './recording/RecordingManager.js';
 // Platform services (v0.2.1+)
 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';
+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;
 }
@@ -65,3 +71,36 @@ export type SavesDeleteResult = {
 export interface SavesListResult {
     keys: string[];
 }
+export interface GameDataGetParams {
+    key: string;
+}
+export interface GameDataGetResult {
+    value: unknown | null;
+    version: number | null;
+}
+export interface GameDataSetParams {
+    key: string;
+    value: unknown;
+    ifVersion?: number;
+}
+export interface GameDataSetResult {
+    version: number;
+}
+export interface GameDataDeleteParams {
+    key: string;
+}
+export type GameDataDeleteResult = {
+    deleted: boolean;
+};
+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.3",
+  "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"
   },