@unboxy/phaser-sdk 0.2.13 → 0.2.14

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.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,13 @@ 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 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. */
+    private readonly knownNames;
     constructor(room: Room<unknown>);
     /**
      * Send a chat line. Empty-after-trim input is dropped silently. Text longer
@@ -108,13 +111,27 @@ 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.
+     * 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.
+     *
+     * 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.
      */
     private subscribeToPlayers;
+    /** Compare current `players` membership against `knownNames`, emit
+     *  `system.joined` for new sids and `system.left` for vanished sids. */
+    private diffPlayers;
     private dispatch;
 }
 /**

package/dist/realtime/UnboxyRoom.js

@@ -76,10 +76,13 @@ 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 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. */
+        this.knownNames = new Map();
         this.subscribeToPlayers();
     }
     /**
@@ -155,11 +158,22 @@ 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.
+     * 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.
+     *
+     * 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.
      */
     subscribeToPlayers() {
         const players = this.room.state?.players;
@@ -167,49 +181,74 @@ export class ChatFacade {
             return;
         if (typeof players.forEach === 'function') {
             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,
+                // 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');
             }
         }
-        if (typeof players.onAdd === 'function') {
-            players.onAdd((player, sid) => {
-                if (this.seen.has(sid))
-                    return;
-                this.seen.add(sid);
-                // Don't announce yourself joining your own room.
-                if (sid === this.room.sessionId)
-                    return;
-                const name = typeof player?.displayName === 'string' ? player.displayName : '';
-                const who = name || 'A player';
-                this.dispatch({
-                    kind: 'system.joined',
-                    from: sid,
-                    displayName: name,
-                    text: `${who} joined`,
-                    ts: Date.now(),
+        // 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. */
+    diffPlayers() {
+        const state = this.room.state;
+        const players = state?.players;
+        if (!players)
+            return;
+        const nowSids = new Set();
+        if (typeof players.forEach === 'function') {
+            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;
+            }
         }
-        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(),
-                });
+        // 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.14",
   "description": "Unboxy Phaser 3 SDK — game infrastructure for the Unboxy platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",