@unboxy/phaser-sdk 0.2.4 → 0.2.6

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,125 @@ 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 platform is **game-agnostic** — the server tracks who's in the room and relays data, but does not know what kind of game you're building. Two opaque primitives are your building blocks:
+
+1. **Delta-synced KV state** (`room.player.*`, `room.data.*`) — server-maintained maps. Values are JSON-serializable. Every client sees changes via `onStateChange`. State is preserved while the room exists; new joiners see the current snapshot.
+2. **Transient message relay** (`room.send` + `room.on`) — fire-and-forget. Payloads are stamped with `from: senderSessionId` and broadcast to every other client in the room. Not persisted.
+
+#### Join a room
+
+```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',
+});
+
+room.id;         // room identifier
+room.sessionId;  // this connection's session id within the room
+room.state;      // proxy of the server-authoritative schema
+```
+
+#### 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.
+
+```ts
+// Per-player (only you can write your own entry)
+room.player.set('pos', { x: 120, y: 340 });
+room.player.set('hp', 80);
+room.player.delete('pos');
+
+// Read another player's data at any time
+const otherPos = room.player.get<{x:number; y:number}>(otherSessionId, 'pos');
+
+// Per-room (any client can write)
+room.data.set('currentTurn', playerSessionId);
+room.data.set('scoreboard', [{ sid: 's1', score: 12 }, ...]);
+const board = room.data.get<Entry[]>('scoreboard') ?? [];
+
+// React to any state change
+const offState = room.onStateChange(() => {
+  room.state.players.forEach((p, sid) => {
+    const pos = room.player.get<{x:number;y:number}>(sid, 'pos');
+    // ... re-render
+  });
+});
+```
+
+Values are JSON-stringified under the hood. Use for anything JSON-serializable.
+
+#### Transient events — `room.send` and `room.on`
+
+Use this for ephemeral actions: fires, hits, emotes, explosions, chat. Not persisted.
+
+```ts
+// Sender
+room.send('fire', { x: 100, y: 200, angle: 1.5 });
+
+// Every other client (sender does NOT receive their own)
+const offFire = room.on('fire', (msg: { from: string; x: number; y: number; angle: number }) => {
+  spawnProjectile(msg.x, msg.y, msg.angle);
+});
+```
+
+#### Server-tracked membership
+
+`room.state.players` is server-owned. Each entry exposes:
+- `userId` — Unboxy identity (from the JWT)
+- `displayName` — set by the joining client
+- `joinedAt` — ms timestamp
+- `data` — the MapSchema<string> the player writes to via `room.player.set`
+
+Games never mutate these directly; read them from `room.state.players`.
+
+#### Connection lifecycle
+
+```ts
+room.onLeave((code) => console.log('disconnected', code));
+room.onError((code, message) => console.warn('room error', code, message));
+
+// Clean up on scene shutdown
+offState();
+offFire();
+await room.leave();
+```
+
+#### Picking the right primitive
+
+| Need | Use | Why |
+|---|---|---|
+| Smooth position sync of a player | `room.player.set('pos', {x,y})` at ~10-20 Hz + `onStateChange` | Delta-compressed, survives reconnect, server is source of truth. |
+| Per-frame local movement feel | client-side prediction + interpolate remotes from state | State arrives at ~20 Hz; lerp toward it. |
+| Scoreboard shared by all | `room.data.set('scoreboard', [...])` | One writer wins on conflict; use optimistic patterns or turn-based writes. |
+| Projectile spawn / hit effect | `room.send('fire', {...})` + `room.on('fire', ...)` | Ephemeral, not needed on reconnect. |
+| Chat message | `room.send('chat', text)` + `room.on('chat', ...)` | Same — ephemeral relay. |
+| Current turn in a turn-based game | `room.data.set('turn', sid)` | Authoritative shared state. |
+
+Rules of thumb:
+- **If someone joining mid-game should see it, it's state** (`room.player.*` or `room.data.*`).
+- **If it's a one-shot action, it's a message** (`room.send` / `room.on`).
+- **Do not implement position sync via messages.** You will reinvent delta compression badly and spend more bandwidth. Use `room.player.set('pos', {x,y})`.
+- **Server is authoritative but permissive** — it doesn't validate what you put in `data`. Treat inbound values from other players as untrusted (don't eval, validate shape before reading).
+
+#### 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
+
+- `lobby` — the generic room described above. Use for any multiplayer gameplay.
+
+**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 +314,8 @@ Rule of thumb: if two different players would write to the same key, it's `gameD
 
 ## Changelog
 
+- **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`.
+- **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.6';
 /**
  * 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, PlayerDataFacade, RoomDataFacade } 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, PlayerDataFacade, RoomDataFacade } 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,68 @@
+import type { Room } from 'colyseus.js';
+type Unsubscribe = () => void;
+/**
+ * Facade for per-player state — one entry per player, only the owner can write
+ * to their own entry. Delta-synced via Colyseus schema.
+ */
+export declare class PlayerDataFacade {
+    private readonly room;
+    constructor(room: Room<unknown>);
+    /** Write a JSON-serializable value to the caller's own player data. */
+    set(key: string, value: unknown): void;
+    /** Remove a key from the caller's own player data. */
+    delete(key: string): void;
+    /** Read a player's data value. Returns null if the player or key is absent. */
+    get<T = unknown>(sessionId: string, key: string): T | null;
+}
+/**
+ * Facade for room-scope shared state — one map per room, any client may write.
+ * Delta-synced via Colyseus schema. Use for shared game state like current
+ * turn, scoreboard, shared level-of-the-day, etc.
+ */
+export declare class RoomDataFacade {
+    private readonly room;
+    constructor(room: Room<unknown>);
+    /** Write a JSON-serializable value into the room's shared data map. */
+    set(key: string, value: unknown): void;
+    /** Remove a key from the room's shared data map. */
+    delete(key: string): void;
+    /** Read a shared room value. Returns null if the key is absent. */
+    get<T = unknown>(key: string): T | null;
+}
+/**
+ * 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;
+    readonly player: PlayerDataFacade;
+    readonly data: RoomDataFacade;
+    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 transient message. Relayed to every other client in the room
+     *  with `from: sessionId` stamped onto the payload. Not persisted in state. */
+    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,111 @@
+function parseOrNull(raw) {
+    if (raw == null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Facade for per-player state — one entry per player, only the owner can write
+ * to their own entry. Delta-synced via Colyseus schema.
+ */
+export class PlayerDataFacade {
+    constructor(room) {
+        this.room = room;
+    }
+    /** Write a JSON-serializable value to the caller's own player data. */
+    set(key, value) {
+        this.room.send('player.set', { key, value });
+    }
+    /** Remove a key from the caller's own player data. */
+    delete(key) {
+        this.room.send('player.delete', { key });
+    }
+    /** Read a player's data value. Returns null if the player or key is absent. */
+    get(sessionId, key) {
+        const state = this.room.state;
+        const player = state?.players?.get?.(sessionId);
+        return parseOrNull(player?.data?.get?.(key));
+    }
+}
+/**
+ * Facade for room-scope shared state — one map per room, any client may write.
+ * Delta-synced via Colyseus schema. Use for shared game state like current
+ * turn, scoreboard, shared level-of-the-day, etc.
+ */
+export class RoomDataFacade {
+    constructor(room) {
+        this.room = room;
+    }
+    /** Write a JSON-serializable value into the room's shared data map. */
+    set(key, value) {
+        this.room.send('room.set', { key, value });
+    }
+    /** Remove a key from the room's shared data map. */
+    delete(key) {
+        this.room.send('room.delete', { key });
+    }
+    /** Read a shared room value. Returns null if the key is absent. */
+    get(key) {
+        const state = this.room.state;
+        return parseOrNull(state?.data?.get?.(key));
+    }
+}
+/**
+ * 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;
+        this.player = new PlayerDataFacade(room);
+        this.data = new RoomDataFacade(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 transient message. Relayed to every other client in the room
+     *  with `from: sessionId` stamped onto the payload. Not persisted in state. */
+    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.6",
   "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"
   },