@unboxy/phaser-sdk 0.2.14 → 0.2.16

package/SDK-GUIDE.md

@@ -15,16 +15,28 @@ Reference for AI agents building games on the Unboxy platform. Tracks the **inst
 
 | field | type | note |
 |-------|------|------|
-| `width` | `number` | required |
-| `height` | `number` | required |
+| `orientation` | `'portrait' \| 'landscape'` | mutually exclusive with `width`/`height`. Resolves to preset dims from `ORIENTATION_DIMENSIONS`. **Since 0.2.16.** |
+| `width` | `number` | required if `orientation` is omitted |
+| `height` | `number` | required if `orientation` is omitted |
 | `scenes` | `Phaser.Scene class[]` | required |
 | `backgroundColor` | `string` | defaults to `'#1a1a2e'` |
 | `pixelArt` | `boolean` | defaults to `false` |
 | `physics` | `Phaser.Types.Core.PhysicsConfig` | defaults to arcade physics, no gravity |
 | `plugins` | `Phaser.Types.Core.PluginObject` | forwarded as-is into the Phaser `GameConfig`. **Since 0.2.9.** Earlier versions silently dropped this field. |
 
+`orientation` and explicit `width`/`height` are a TypeScript union — pass one or the other, not both. The compiler rejects mixed usage.
+
 Any field not listed is ignored. If you need something else (e.g. `callbacks`, custom `render` options), use plain `new Phaser.Game(config)` instead of `createUnboxyGame`.
 
+### Orientation presets
+
+```ts
+import { ORIENTATION_DIMENSIONS } from '@unboxy/phaser-sdk';
+// { landscape: { width: 1280, height: 720 }, portrait: { width: 720, height: 1280 } }
+```
+
+The orientation a game uses is decided **once at game creation** and baked into the template's `src/config.ts`. There is no runtime API to flip orientation — switching mid-development would invalidate every screen layout.
+
 ### Registering third-party Phaser plugins (e.g. rexUI)
 
 Pass them via the `plugins` option — do NOT try to register them inside a scene's `preload`:
@@ -544,6 +556,8 @@ Don't blindly apply interpolation to everything. It's wrong for a chess piece an
 
 ## Changelog
 
+- **0.2.16** — added orientation presets. `createUnboxyGame` now accepts an `orientation: 'portrait' | 'landscape'` option as an alternative to explicit `width`/`height` (TS union — pass one or the other). New exports: `Orientation` type and `ORIENTATION_DIMENSIONS` map (`landscape: 1280×720`, `portrait: 720×1280`). Lets games declare orientation once and have a single source of truth for canvas dimensions.
+- **0.2.15** — fix: `ChatFacade.subscribeToPlayers` early-returned when `state.players` was `undefined` at construction time, which it always is on a fresh `joinOrCreate` (Colyseus delivers initial state as a separate message a few ms later). The early return meant `onStateChange` never subscribed and `system.joined` / `system.left` stayed silent in production despite the 0.2.14 callback-API fix. Now: always subscribe; treat the first state change as initial hydration (silent), subsequent changes do real diff. Three regression tests cover the deferred-hydration flow.
 - **0.2.14** — fix: `ChatFacade` `system.joined` / `system.left` events were silently no-op'ing in production. The lifecycle subscription used `state.players.onAdd` / `.onRemove` instance methods that Colyseus 0.16 removed in favour of `getStateCallbacks(room)`; the runtime check `typeof players.onAdd === 'function'` evaluated false, so neither system message fired. Now uses `room.onStateChange` + a known-names diff — robust to future Colyseus API changes. Tests updated to match. Patch-only; no API change for game code.
 - **0.2.13** — added `room.chat` helper for in-game chat. New API: `room.chat.send(text)` (returns `Promise<void>`) + `room.chat.onMessage(handler)`, plus exports `ChatMessage`, `ChatMessageKind`, and `MAX_CHAT_TEXT_LEN`. Wraps the existing `'chat'` wildcard relay with local echo (sender sees own message synchronously), stamped `displayName` on every payload, trim + 500-char silent truncate, and auto-emitted `kind: 'system.joined'` / `'system.left'` messages computed locally from `room.state.players` add/remove events (no wire traffic). Replaces the raw `room.send('chat', text)` pattern in the Multiplayer chapter — raw still works but loses local echo, length cap, and join/leave events.
 - **0.2.12** — added `unboxy.rooms.list(options?)` — returns the open rooms for the caller's game right now, scoped server-side to the caller's gameId. Use this to build a lobby browser ("show me open rooms, click to join") without needing an out-of-band room code. SDK-GUIDE adds a "Browsing open rooms" section under Multiplayer covering the `RoomListEntry` shape, the poll-on-timer pattern, and the `{ roomCode }` filter for "is room X up yet?" probes.

package/dist/core/UnboxyGame.d.ts

@@ -1,9 +1,6 @@
 import Phaser from 'phaser';
-export interface UnboxyGameOptions {
-    /** Game width in pixels */
-    width: number;
-    /** Game height in pixels */
-    height: number;
+import { type Orientation } from '../orientation.js';
+interface UnboxyGameBaseOptions {
     /** Phaser scene classes to register */
     scenes: (new (...args: any[]) => Phaser.Scene)[];
     /** Background color (default: '#1a1a2e') */
@@ -15,8 +12,24 @@ export interface UnboxyGameOptions {
     /** Phaser plugin registrations (e.g. `phaser3-rex-plugins` virtual joystick) */
     plugins?: Phaser.Types.Core.PluginObject;
 }
+/**
+ * Either pass `orientation` (preset dims from ORIENTATION_DIMENSIONS) OR
+ * explicit `width`/`height` — not both. The TS union enforces this at
+ * compile time so games can't drift out of the orientation presets by
+ * accident.
+ */
+export type UnboxyGameOptions = (UnboxyGameBaseOptions & {
+    orientation: Orientation;
+    width?: never;
+    height?: never;
+}) | (UnboxyGameBaseOptions & {
+    width: number;
+    height: number;
+    orientation?: never;
+});
 /**
  * Create an Unboxy-enhanced Phaser game instance.
  * Includes built-in integrations: screenshot capture, preserveDrawingBuffer, etc.
  */
 export declare function createUnboxyGame(options: UnboxyGameOptions): Phaser.Game;
+export {};

package/dist/core/UnboxyGame.js

@@ -1,19 +1,23 @@
 import Phaser from 'phaser';
 import { setupScreenshotListener } from '../screenshot/ScreenshotManager.js';
 import { setupRecordingListener } from '../recording/RecordingManager.js';
+import { ORIENTATION_DIMENSIONS } from '../orientation.js';
 /**
  * Create an Unboxy-enhanced Phaser game instance.
  * Includes built-in integrations: screenshot capture, preserveDrawingBuffer, etc.
  */
 export function createUnboxyGame(options) {
+    const { width, height } = 'orientation' in options && options.orientation
+        ? ORIENTATION_DIMENSIONS[options.orientation]
+        : { width: options.width, height: options.height };
     const config = {
         type: Phaser.AUTO,
         backgroundColor: options.backgroundColor ?? '#1a1a2e',
         scale: {
             mode: Phaser.Scale.FIT,
             autoCenter: Phaser.Scale.CENTER_BOTH,
-            width: options.width,
-            height: options.height,
+            width,
+            height,
         },
         render: {
             preserveDrawingBuffer: true,

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { createUnboxyGame } from './core/UnboxyGame.js';
 export type { UnboxyGameOptions } from './core/UnboxyGame.js';
 export { UnboxyScene } from './core/UnboxyScene.js';
+export { ORIENTATION_DIMENSIONS } from './orientation.js';
+export type { Orientation } from './orientation.js';
 export { setupScreenshotListener, takeScreenshot } from './screenshot/ScreenshotManager.js';
 export { setupRecordingListener } from './recording/RecordingManager.js';
 export { Unboxy } from './core/Unboxy.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 // Core
 export { createUnboxyGame } from './core/UnboxyGame.js';
 export { UnboxyScene } from './core/UnboxyScene.js';
+export { ORIENTATION_DIMENSIONS } from './orientation.js';
 // Screenshot
 export { setupScreenshotListener, takeScreenshot } from './screenshot/ScreenshotManager.js';
 // Recording

package/dist/orientation.d.ts

@@ -0,0 +1,5 @@
+export type Orientation = 'portrait' | 'landscape';
+export declare const ORIENTATION_DIMENSIONS: Record<Orientation, {
+    width: number;
+    height: number;
+}>;

package/dist/orientation.js

@@ -0,0 +1,4 @@
+export const ORIENTATION_DIMENSIONS = {
+    landscape: { width: 1280, height: 720 },
+    portrait: { width: 720, height: 1280 },
+};

package/dist/realtime/UnboxyRoom.d.ts

@@ -84,12 +84,18 @@ export declare class ChatFacade {
     private readonly handlers;
     private remoteOff;
     /** Sids known to this facade, mapped to the displayName they had at the
-     *  time we last observed them. Populated at construction-time snapshot
-     *  (so we don't emit "X joined" for everyone already present when the local
-     *  user joins) and on every subsequent diff. We track the displayName here
-     *  because by the time a player is detected as "left" they're already gone
-     *  from `state.players` and we can't read it from there. */
+     *  time we last observed them. Populated either at construction (if state
+     *  was already synced) or on the first `onStateChange` (initial hydration
+     *  — silent, no system messages). Subsequent state changes diff against
+     *  this map to emit `system.joined` / `system.left`. We track displayName
+     *  here because by the time a player is detected as "left" they're already
+     *  gone from `state.players` and we can't read it from there. */
     private readonly knownNames;
+    /** Becomes true the first time we observe a usable `state.players` map.
+     *  The very first observation is treated as "initial state arrived" and
+     *  must NOT fire `system.joined` for the players already in the room when
+     *  the local user joined — only subsequent diffs are real lifecycle events. */
+    private hydrated;
     constructor(room: Room<unknown>);
     /**
      * Send a chat line. Empty-after-trim input is dropped silently. Text longer
@@ -111,26 +117,43 @@ export declare class ChatFacade {
      */
     onMessage(handler: (msg: ChatMessage) => void): Unsubscribe;
     /**
-     * Snapshot the current player list and hook `onStateChange` to detect
-     * subsequent joins / leaves. By the time `client.joinOrCreate` resolves
-     * (and UnboxyRoom is constructed), Colyseus has delivered the initial
-     * state — so the snapshot covers everyone already in the room and we skip
-     * emission for them.
+     * Hook `onStateChange` to detect joins / leaves and try an eager snapshot
+     * if `state.players` is already populated.
+     *
+     * **The onStateChange subscription must always be set up, even when
+     * `state.players` is `undefined` at construction.** Colyseus 0.16 (and
+     * earlier) deliver the initial state as a *separate* message that arrives
+     * a few ms after `client.joinOrCreate` resolves — so right when UnboxyRoom
+     * is constructed, `room.state.players` is typically `undefined`. An earlier
+     * 0.2.14 implementation early-returned in that case and never subscribed,
+     * which meant the diff machinery never armed and BOTH `system.joined` /
+     * `system.left` silently dead-stopped in production (Blokus chat game,
+     * 2026-04-27).
+     *
+     * Eager snapshot if `state.players` is already there sets `hydrated=true`
+     * so the first state change does a real diff. Otherwise the first state
+     * change is treated as initial hydration: populate `knownNames` silently,
+     * skip system messages, set `hydrated=true`. Subsequent state changes do
+     * the real lifecycle diff.
      *
      * Why `onStateChange` and not `MapSchema.onAdd` / `.onRemove`: Colyseus
      * 0.16 dropped those instance methods in favour of a separate
      * `getStateCallbacks(room)` proxy API. Hooking `onStateChange` and diffing
      * `players` keys ourselves works the same in any Colyseus version, keeps
      * us decoupled from the realtime backend's callback shape, and adds < 1ms
-     * of work per state change for typical room sizes (max 16 players). The
-     * earlier 0.2.13 implementation tried `players.onAdd` directly — the
-     * conditional silently no-op'd in 0.16 and BOTH `system.joined` /
-     * `system.left` events stopped firing in production. Surfaced via a Blokus
-     * chat game on 2026-04-27.
+     * of work per state change for typical room sizes (max 16 players).
      */
     private subscribeToPlayers;
-    /** Compare current `players` membership against `knownNames`, emit
-     *  `system.joined` for new sids and `system.left` for vanished sids. */
+    /** Populate `knownNames` from `state.players` if it's already available
+     *  and mark hydrated. Silent — never emits system messages. A successful
+     *  `forEach` (even iterating zero items) means the schema is synced and
+     *  this is "what the room looked like when we joined" — safe to hydrate. */
+    private tryEagerSnapshot;
+    /** Compare current `players` membership against `knownNames`. On the very
+     *  first invocation (post-construction) when `hydrated=false`, this is
+     *  the initial-hydration call: populate `knownNames` silently and bail.
+     *  Subsequent invocations diff against `knownNames` and emit
+     *  `system.joined` for new sids, `system.left` for vanished sids. */
     private diffPlayers;
     private dispatch;
 }

package/dist/realtime/UnboxyRoom.js

@@ -77,12 +77,18 @@ export class ChatFacade {
         this.handlers = new Set();
         this.remoteOff = null;
         /** Sids known to this facade, mapped to the displayName they had at the
-         *  time we last observed them. Populated at construction-time snapshot
-         *  (so we don't emit "X joined" for everyone already present when the local
-         *  user joins) and on every subsequent diff. We track the displayName here
-         *  because by the time a player is detected as "left" they're already gone
-         *  from `state.players` and we can't read it from there. */
+         *  time we last observed them. Populated either at construction (if state
+         *  was already synced) or on the first `onStateChange` (initial hydration
+         *  — silent, no system messages). Subsequent state changes diff against
+         *  this map to emit `system.joined` / `system.left`. We track displayName
+         *  here because by the time a player is detected as "left" they're already
+         *  gone from `state.players` and we can't read it from there. */
         this.knownNames = new Map();
+        /** Becomes true the first time we observe a usable `state.players` map.
+         *  The very first observation is treated as "initial state arrived" and
+         *  must NOT fire `system.joined` for the players already in the room when
+         *  the local user joined — only subsequent diffs are real lifecycle events. */
+        this.hydrated = false;
         this.subscribeToPlayers();
     }
     /**
@@ -158,83 +164,109 @@ export class ChatFacade {
         };
     }
     /**
-     * Snapshot the current player list and hook `onStateChange` to detect
-     * subsequent joins / leaves. By the time `client.joinOrCreate` resolves
-     * (and UnboxyRoom is constructed), Colyseus has delivered the initial
-     * state — so the snapshot covers everyone already in the room and we skip
-     * emission for them.
+     * Hook `onStateChange` to detect joins / leaves and try an eager snapshot
+     * if `state.players` is already populated.
+     *
+     * **The onStateChange subscription must always be set up, even when
+     * `state.players` is `undefined` at construction.** Colyseus 0.16 (and
+     * earlier) deliver the initial state as a *separate* message that arrives
+     * a few ms after `client.joinOrCreate` resolves — so right when UnboxyRoom
+     * is constructed, `room.state.players` is typically `undefined`. An earlier
+     * 0.2.14 implementation early-returned in that case and never subscribed,
+     * which meant the diff machinery never armed and BOTH `system.joined` /
+     * `system.left` silently dead-stopped in production (Blokus chat game,
+     * 2026-04-27).
+     *
+     * Eager snapshot if `state.players` is already there sets `hydrated=true`
+     * so the first state change does a real diff. Otherwise the first state
+     * change is treated as initial hydration: populate `knownNames` silently,
+     * skip system messages, set `hydrated=true`. Subsequent state changes do
+     * the real lifecycle diff.
      *
      * Why `onStateChange` and not `MapSchema.onAdd` / `.onRemove`: Colyseus
      * 0.16 dropped those instance methods in favour of a separate
      * `getStateCallbacks(room)` proxy API. Hooking `onStateChange` and diffing
      * `players` keys ourselves works the same in any Colyseus version, keeps
      * us decoupled from the realtime backend's callback shape, and adds < 1ms
-     * of work per state change for typical room sizes (max 16 players). The
-     * earlier 0.2.13 implementation tried `players.onAdd` directly — the
-     * conditional silently no-op'd in 0.16 and BOTH `system.joined` /
-     * `system.left` events stopped firing in production. Surfaced via a Blokus
-     * chat game on 2026-04-27.
+     * of work per state change for typical room sizes (max 16 players).
      */
     subscribeToPlayers() {
+        // Always subscribe — regardless of whether `state.players` is populated yet.
+        this.room.onStateChange(() => this.diffPlayers());
+        // Best-effort eager snapshot. If state is already synced (rare — usually
+        // only in tests or on a reconnect to a hot room), this lets us mark
+        // hydrated immediately and treat the first state change as a real diff.
+        this.tryEagerSnapshot();
+    }
+    /** Populate `knownNames` from `state.players` if it's already available
+     *  and mark hydrated. Silent — never emits system messages. A successful
+     *  `forEach` (even iterating zero items) means the schema is synced and
+     *  this is "what the room looked like when we joined" — safe to hydrate. */
+    tryEagerSnapshot() {
         const players = this.room.state?.players;
-        if (!players)
+        if (!players || typeof players.forEach !== 'function')
             return;
-        if (typeof players.forEach === 'function') {
-            try {
-                players.forEach((p, sid) => {
-                    const name = typeof p?.displayName === 'string' ? p.displayName : '';
-                    this.knownNames.set(sid, name);
-                });
-            }
-            catch {
-                // forEach can throw on an unsynced state; knownNames stays empty,
-                // which means we'll emit "joined" for the initial hydration. That's
-                // a degraded but non-broken behavior — the chat log gets an extra
-                // line per existing player. Log once for visibility.
-                console.warn('[unboxy.chat] could not snapshot players on subscribe');
-            }
+        try {
+            players.forEach((p, sid) => {
+                const name = typeof p?.displayName === 'string' ? p.displayName : '';
+                this.knownNames.set(sid, name);
+            });
+            this.hydrated = true;
+        }
+        catch {
+            // State not iterable yet — leave it for the first onStateChange.
         }
-        // Diff on every state change. Cheap for any reasonable room size
-        // (Colyseus caps maxClients at 16 server-side).
-        this.room.onStateChange(() => this.diffPlayers());
     }
-    /** Compare current `players` membership against `knownNames`, emit
-     *  `system.joined` for new sids and `system.left` for vanished sids. */
+    /** Compare current `players` membership against `knownNames`. On the very
+     *  first invocation (post-construction) when `hydrated=false`, this is
+     *  the initial-hydration call: populate `knownNames` silently and bail.
+     *  Subsequent invocations diff against `knownNames` and emit
+     *  `system.joined` for new sids, `system.left` for vanished sids. */
     diffPlayers() {
         const state = this.room.state;
         const players = state?.players;
-        if (!players)
+        if (!players || typeof players.forEach !== 'function')
             return;
-        const nowSids = new Set();
-        if (typeof players.forEach === 'function') {
+        if (!this.hydrated) {
+            // Initial hydration — silently absorb whoever's in the room when we
+            // joined. Don't say "X joined" for everyone already there.
             try {
                 players.forEach((p, sid) => {
-                    nowSids.add(sid);
                     const name = typeof p?.displayName === 'string' ? p.displayName : '';
-                    if (this.knownNames.has(sid)) {
-                        // Refresh the cached name in case Colyseus updated it post-join
-                        // (e.g. delayed state sync); but don't re-emit for an existing sid.
-                        this.knownNames.set(sid, name);
-                        return;
-                    }
                     this.knownNames.set(sid, name);
-                    if (sid === this.room.sessionId)
-                        return; // don't announce self-join
-                    const who = name || 'A player';
-                    this.dispatch({
-                        kind: 'system.joined',
-                        from: sid,
-                        displayName: name,
-                        text: `${who} joined`,
-                        ts: Date.now(),
-                    });
                 });
             }
             catch {
-                // Iteration shouldn't throw post-snapshot, but if it does we just
-                // skip this diff cycle rather than break the chat stream.
                 return;
             }
+            this.hydrated = true;
+            return;
+        }
+        const nowSids = new Set();
+        try {
+            players.forEach((p, sid) => {
+                nowSids.add(sid);
+                const name = typeof p?.displayName === 'string' ? p.displayName : '';
+                if (this.knownNames.has(sid)) {
+                    // Refresh cached name in case Colyseus updated it post-join.
+                    this.knownNames.set(sid, name);
+                    return;
+                }
+                this.knownNames.set(sid, name);
+                if (sid === this.room.sessionId)
+                    return; // don't announce self-join
+                const who = name || 'A player';
+                this.dispatch({
+                    kind: 'system.joined',
+                    from: sid,
+                    displayName: name,
+                    text: `${who} joined`,
+                    ts: Date.now(),
+                });
+            });
+        }
+        catch {
+            return;
         }
         // Anyone in knownNames but not in nowSids has left.
         for (const sid of [...this.knownNames.keys()]) {

package/package.json

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