@unboxy/phaser-sdk 0.2.5 → 0.2.7

package/SDK-GUIDE.md

@@ -185,7 +185,12 @@ Rule of thumb: if two different players would write to the same key, it's `gameD
 
 ### 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`.
+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
@@ -194,37 +199,101 @@ 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
+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 });
 
-// React to server updates
-const offState = room.onStateChange((state) => {
-  // re-render player list, scores, etc.
+// 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`
 
-// Messages (server ↔ client, typed by name)
-const offHit = room.on('hit', (payload) => { /* apply a hit effect */ });
-room.send('move', { x: 120, y: 340 });
+Games never mutate these directly; read them from `room.state.players`.
 
-// Connection lifecycle
+#### Connection lifecycle
+
+```ts
 room.onLeave((code) => console.log('disconnected', code));
 room.onError((code, message) => console.warn('room error', code, message));
 
-// Clean up when the scene is destroyed
+// Clean up on scene shutdown
 offState();
-offHit();
+offFire();
 await room.leave();
 ```
 
-**Availability**
+#### 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 (server-owned)**
-- `lobby` — simple player list with `ready` flag and chat broadcast. Use for pre-match staging.
-- (more coming: `TurnBasedRoom`, `RealtimeSyncRoom`)
+#### 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.
@@ -245,6 +314,8 @@ await room.leave();
 
 ## Changelog
 
+- **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`.
 - **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)

package/dist/core/Unboxy.d.ts

@@ -4,7 +4,7 @@ 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. */
+    /** Handshake timeout in ms when running inside a host. Default 5000. */
     handshakeTimeoutMs?: number;
     /**
      * Game ID used for the localStorage fallback. Ignored when connected to a

package/dist/core/Unboxy.js

@@ -4,7 +4,7 @@ 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.5';
+const SDK_VERSION = '0.2.7';
 /**
  * Unboxy platform services bound to the current (game, user).
  *
@@ -50,7 +50,7 @@ export class Unboxy {
      * Discord Activity support is designed for but not shipped in this version.
      */
     static async init(options = {}) {
-        const handshakeTimeoutMs = options.handshakeTimeoutMs ?? 2000;
+        const handshakeTimeoutMs = options.handshakeTimeoutMs ?? 5000;
         const standaloneGameId = options.standaloneGameId ?? 'standalone';
         const pm = await PostMessageTransport.connect(handshakeTimeoutMs, SDK_VERSION);
         if (pm)

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

@@ -15,9 +15,14 @@ export declare class PostMessageTransport implements Transport {
     private constructor();
     /**
      * Perform the handshake. Resolves once parent has replied with `unboxy:init`.
-     * Rejects if no response within `timeoutMs`.
+     * Resolves to null if no response within `timeoutMs`.
+     *
+     * The hello is retried at `helloRetryMs` intervals because the parent's
+     * RPC-host message listener may not be mounted yet when the iframe first
+     * fires hello — especially on slower mobile devices where React takes
+     * longer to boot. One-shot hello was losing the handshake on Android.
      */
-    static connect(timeoutMs?: number, sdkVersion?: string): Promise<PostMessageTransport | null>;
+    static connect(timeoutMs?: number, sdkVersion?: string, helloRetryMs?: number): Promise<PostMessageTransport | null>;
     private installResultListener;
     call<T = unknown>(method: string, params?: unknown): Promise<T>;
 }

package/dist/core/transports/PostMessageTransport.js

@@ -15,35 +15,51 @@ export class PostMessageTransport {
     }
     /**
      * Perform the handshake. Resolves once parent has replied with `unboxy:init`.
-     * Rejects if no response within `timeoutMs`.
+     * Resolves to null if no response within `timeoutMs`.
+     *
+     * The hello is retried at `helloRetryMs` intervals because the parent's
+     * RPC-host message listener may not be mounted yet when the iframe first
+     * fires hello — especially on slower mobile devices where React takes
+     * longer to boot. One-shot hello was losing the handshake on Android.
      */
-    static async connect(timeoutMs = 2000, sdkVersion = '0.0.0') {
+    static async connect(timeoutMs = 5000, sdkVersion = '0.0.0', helloRetryMs = 200) {
         if (typeof window === 'undefined' || window.parent === window)
             return null;
         const transport = new PostMessageTransport(window.parent);
-        const initPromise = new Promise((resolve) => {
+        const hello = {
+            type: 'unboxy:hello',
+            protocolVersion: PROTOCOL_VERSION,
+            sdkVersion,
+        };
+        const init = await new Promise((resolve) => {
+            let settled = false;
+            const finish = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                window.removeEventListener('message', onMessage);
+                clearInterval(helloInterval);
+                clearTimeout(timeoutHandle);
+                resolve(value);
+            };
             const onMessage = (event) => {
                 if (event.source !== window.parent)
                     return;
                 const data = event.data;
                 if (!data || data.type !== 'unboxy:init')
                     return;
-                window.removeEventListener('message', onMessage);
-                resolve(data);
+                finish(data);
             };
             window.addEventListener('message', onMessage);
-            setTimeout(() => {
-                window.removeEventListener('message', onMessage);
-                resolve(null);
-            }, timeoutMs);
+            // Fire the first hello immediately, then keep retrying until init
+            // arrives or timeout fires. Retries are cheap (a postMessage with a
+            // small payload); the parent's RPC host replies on first valid hello.
+            transport.parent.postMessage(hello, '*');
+            const helloInterval = setInterval(() => {
+                transport.parent.postMessage(hello, '*');
+            }, helloRetryMs);
+            const timeoutHandle = setTimeout(() => finish(null), timeoutMs);
         });
-        const hello = {
-            type: 'unboxy:hello',
-            protocolVersion: PROTOCOL_VERSION,
-            sdkVersion,
-        };
-        transport.parent.postMessage(hello, '*');
-        const init = await initPromise;
         if (!init)
             return null;
         if (init.protocolVersion !== PROTOCOL_VERSION) {

package/dist/index.d.ts

@@ -9,7 +9,7 @@ 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 { 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';

package/dist/index.js

@@ -10,6 +10,6 @@ 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 { UnboxyRoom, PlayerDataFacade, RoomDataFacade } from './realtime/UnboxyRoom.js';
 export { RpcError } from './core/Transport.js';
 export { PROTOCOL_VERSION, } from './protocol.js';

package/dist/realtime/UnboxyRoom.d.ts

@@ -1,5 +1,34 @@
 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
@@ -7,6 +36,8 @@ type Unsubscribe = () => void;
  */
 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;
@@ -17,7 +48,8 @@ export declare class UnboxyRoom<State = unknown> {
      * may change state.
      */
     get state(): State;
-    /** Send a typed message to the server. */
+    /** 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;

package/dist/realtime/UnboxyRoom.js

@@ -1,3 +1,59 @@
+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
@@ -6,6 +62,8 @@
 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; }
@@ -16,7 +74,8 @@ export class UnboxyRoom {
      * may change state.
      */
     get state() { return this.room.state; }
-    /** Send a typed message to the server. */
+    /** 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);
     }

package/package.json

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