@unboxy/phaser-sdk 0.2.14 → 0.2.15

package/SDK-GUIDE.md

@@ -544,6 +544,7 @@ Don't blindly apply interpolation to everything. It's wrong for a chess piece an
 
 ## Changelog
 
+- **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/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.15",
   "description": "Unboxy Phaser 3 SDK — game infrastructure for the Unboxy platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",