@unboxy/phaser-sdk 0.2.13 → 0.2.15

package/SDK-GUIDE.md

@@ -544,6 +544,8 @@ 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.
 - **0.2.11** — added `roomCode` + `maxClients` to `JoinOptions`. SDK-GUIDE's Multiplayer chapter now documents matchmaking: room type is always `'lobby'`; use `roomCode` to bucket independent rooms per gameId (create-with-fresh-code, join-with-shared-code, quick-match with empty code). Fixes a real bug where agents were passing a gameId-derived string as the room type (e.g. `joinOrCreate('blokus-<code>', ...)`) and failing with "no handler" server-side.

package/dist/realtime/UnboxyRoom.d.ts

@@ -83,10 +83,19 @@ export declare class ChatFacade {
     private readonly room;
     private readonly handlers;
     private remoteOff;
-    /** Sids that were already in `state.players` when this facade was constructed
-     *  — we suppress "joined" system messages for them so the joiner doesn't see
-     *  a flood of "X joined" for everyone already in the room. */
-    private readonly seen;
+    /** Sids known to this facade, mapped to the displayName they had at the
+     *  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
@@ -108,13 +117,44 @@ export declare class ChatFacade {
      */
     onMessage(handler: (msg: ChatMessage) => void): Unsubscribe;
     /**
-     * Snapshot the current player list and subscribe to add/remove for system
-     * messages. By the time `client.joinOrCreate` resolves (and UnboxyRoom is
-     * constructed), Colyseus has delivered the initial state — so the snapshot
-     * here covers everyone already in the room, and we skip emission for them.
-     * Adds and removes after this point are real events.
+     * 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).
      */
     private subscribeToPlayers;
+    /** 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

@@ -76,10 +76,19 @@ export class ChatFacade {
         this.room = room;
         this.handlers = new Set();
         this.remoteOff = null;
-        /** Sids that were already in `state.players` when this facade was constructed
-         *  — we suppress "joined" system messages for them so the joiner doesn't see
-         *  a flood of "X joined" for everyone already in the room. */
-        this.seen = new Set();
+        /** Sids known to this facade, mapped to the displayName they had at the
+         *  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();
     }
     /**
@@ -155,37 +164,97 @@ export class ChatFacade {
         };
     }
     /**
-     * Snapshot the current player list and subscribe to add/remove for system
-     * messages. By the time `client.joinOrCreate` resolves (and UnboxyRoom is
-     * constructed), Colyseus has delivered the initial state — so the snapshot
-     * here covers everyone already in the room, and we skip emission for them.
-     * Adds and removes after this point are real events.
+     * 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).
      */
     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;
+        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.
+        }
+    }
+    /** 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 || typeof players.forEach !== 'function')
             return;
-        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) => { this.seen.add(sid); });
+                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; the seen set 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');
+                return;
             }
+            this.hydrated = true;
+            return;
         }
-        if (typeof players.onAdd === 'function') {
-            players.onAdd((player, sid) => {
-                if (this.seen.has(sid))
+        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.seen.add(sid);
-                // Don't announce yourself joining your own room.
+                }
+                this.knownNames.set(sid, name);
                 if (sid === this.room.sessionId)
-                    return;
-                const name = typeof player?.displayName === 'string' ? player.displayName : '';
+                    return; // don't announce self-join
                 const who = name || 'A player';
                 this.dispatch({
                     kind: 'system.joined',
@@ -196,20 +265,22 @@ export class ChatFacade {
                 });
             });
         }
-        if (typeof players.onRemove === 'function') {
-            players.onRemove((player, sid) => {
-                if (!this.seen.has(sid))
-                    return;
-                this.seen.delete(sid);
-                const name = typeof player?.displayName === 'string' ? player.displayName : '';
-                const who = name || 'A player';
-                this.dispatch({
-                    kind: 'system.left',
-                    from: sid,
-                    displayName: name,
-                    text: `${who} left`,
-                    ts: Date.now(),
-                });
+        catch {
+            return;
+        }
+        // Anyone in knownNames but not in nowSids has left.
+        for (const sid of [...this.knownNames.keys()]) {
+            if (nowSids.has(sid))
+                continue;
+            const name = this.knownNames.get(sid) ?? '';
+            this.knownNames.delete(sid);
+            const who = name || 'A player';
+            this.dispatch({
+                kind: 'system.left',
+                from: sid,
+                displayName: name,
+                text: `${who} left`,
+                ts: Date.now(),
             });
         }
     }

package/package.json

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