@unboxy/phaser-sdk 0.2.12 → 0.2.13

package/SDK-GUIDE.md

@@ -369,7 +369,7 @@ 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.
+Use this for ephemeral actions: fires, hits, emotes, explosions. Not persisted. (For **chat**, prefer the dedicated `room.chat` helper below — it adds local echo, length capping, and a stamped sender name on top of this same primitive.)
 
 ```ts
 // Sender
@@ -381,6 +381,68 @@ const offFire = room.on('fire', (msg: { from: string; x: number; y: number; angl
 });
 ```
 
+#### Chat — `room.chat.send` and `room.chat.onMessage`
+
+A thin wrapper over the transient relay tuned for in-game chat. Use this instead of raw `room.send('chat', text)` — you get four things you'd otherwise re-implement in every game:
+
+1. **Local echo** — the sender's own message hits the same `onMessage` handler stream the moment it's sent, so your UI has one render path for both your messages and remote ones.
+2. **Stamped sender info** — every `ChatMessage` carries `kind`, `from` (sessionId), `displayName` (sender's human-readable name at send time), `text`, and `ts`. No need to look up the sender in `room.state.players`.
+3. **Trim + length cap** — text is `.trim()`ed, dropped if empty, and silently truncated to `MAX_CHAT_TEXT_LEN` (500) so a stray paste can't flood the relay.
+4. **Auto-emitted system messages** — when a remote player joins or leaves, the SDK dispatches a `kind: 'system.joined'` / `'system.left'` message into the same stream. No wire traffic; computed locally on each client from `room.state.players`. Skipped for the local player's own join.
+
+```ts
+import { MAX_CHAT_TEXT_LEN } from '@unboxy/phaser-sdk';
+import type { ChatMessage } from '@unboxy/phaser-sdk';
+
+const log: ChatMessage[] = [];
+
+const offChat = room.chat.onMessage((msg) => {
+  log.push(msg);
+  if (msg.kind === 'user') {
+    const who = msg.from === room.sessionId ? 'You' : (msg.displayName || 'Player');
+    appendChatLine(`${formatTime(msg.ts)} ${who}: ${msg.text}`);
+  } else {
+    // 'system.joined' or 'system.left' — render however you like.
+    // msg.text is already a sensible English fallback ("Alice joined").
+    appendSystemLine(`${formatTime(msg.ts)} — ${msg.text}`);
+  }
+});
+
+inputEl.maxLength = MAX_CHAT_TEXT_LEN;       // mirror the cap on the input box
+inputEl.addEventListener('keydown', async (e) => {
+  if (e.key !== 'Enter') return;
+  try {
+    await room.chat.send(inputEl.value);     // trim + cap + local echo + wire send
+    inputEl.value = '';                      // safe: echo already dispatched synchronously
+  } catch (err) {
+    // Local-side dispatch failed (e.g. connection dropped). Show a UI hint.
+    showChatError(err);
+  }
+});
+
+scene.events.once('shutdown', offChat);
+```
+
+`ChatMessage` discriminates by `kind`:
+
+```ts
+type ChatMessageKind = 'user' | 'system.joined' | 'system.left';
+interface ChatMessage {
+  kind: ChatMessageKind;
+  from: string;          // sessionId of the sender (or join/leave subject)
+  displayName: string;   // their displayName at the time
+  text: string;          // user-typed text, or English system fallback
+  ts: number;            // Date.now() when emitted
+}
+```
+
+Notes:
+- **No history.** A player who joins mid-room sees no prior `'user'` messages. If you need scrollback, write to `room.data.set('chatLog', [...])` yourself — the relay is fire-and-forget.
+- **System messages are local-only.** Each client computes them from `room.state.players` add/remove events. They are NOT broadcast over the wire, and never echo from the wire even if a different client tries to send one.
+- **`send` returns `Promise<void>`.** Resolves once dispatch is complete (echo + wire queued); rejects if the underlying connection blew up. It is **not** an ack — the relay itself is fire-and-forget; the Promise only catches local-side errors.
+- **Order by arrival.** `ts` is `Date.now()`, advisory only. Skew between clients is small in practice but don't sort by `ts` across senders.
+- **Trust model.** `text` and `displayName` come from the sender — no server-side validation. Same as every other transient relay payload.
+
 #### Server-tracked membership
 
 `room.state.players` is server-owned. Each entry exposes:
@@ -411,7 +473,7 @@ await room.leave();
 | 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. |
+| Chat message | `room.chat.send(text)` + `room.chat.onMessage(...)` | Helper over the relay: local echo, stamped sender, length cap. |
 | Current turn in a turn-based game | `room.data.set('turn', sid)` | Authoritative shared state. |
 
 Rules of thumb:
@@ -482,6 +544,7 @@ Don't blindly apply interpolation to everything. It's wrong for a chess piece an
 
 ## Changelog
 
+- **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.
 - **0.2.10** — docs: added a `createUnboxyGame` options table (including the new `plugins` field) and a third-party Phaser plugin registration example. No code changes; version bumped so existing workspaces pick up the new guidance via `npm update @unboxy/phaser-sdk`.

package/dist/index.d.ts

@@ -9,7 +9,8 @@ export { SavesModule } from './saves/SavesModule.js';
 export { GameDataModule } from './gamedata/GameDataModule.js';
 export { RealtimeModule } from './realtime/RealtimeModule.js';
 export type { JoinOptions, RoomListEntry, RoomListOptions } from './realtime/RealtimeModule.js';
-export { UnboxyRoom, PlayerDataFacade, RoomDataFacade } from './realtime/UnboxyRoom.js';
+export { UnboxyRoom, PlayerDataFacade, RoomDataFacade, ChatFacade, MAX_CHAT_TEXT_LEN, } from './realtime/UnboxyRoom.js';
+export type { ChatMessage, ChatMessageKind } 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, PlayerDataFacade, RoomDataFacade } from './realtime/UnboxyRoom.js';
+export { UnboxyRoom, PlayerDataFacade, RoomDataFacade, ChatFacade, MAX_CHAT_TEXT_LEN, } from './realtime/UnboxyRoom.js';
 export { RpcError } from './core/Transport.js';
 export { PROTOCOL_VERSION, } from './protocol.js';

package/dist/realtime/UnboxyRoom.d.ts

@@ -29,6 +29,94 @@ export declare class RoomDataFacade {
     /** Read a shared room value. Returns null if the key is absent. */
     get<T = unknown>(key: string): T | null;
 }
+/** Maximum text length accepted by `ChatFacade.send`. Longer input is silently
+ *  truncated. Games should mirror this on their input box's `maxLength`. */
+export declare const MAX_CHAT_TEXT_LEN = 500;
+/**
+ * Discriminator for `ChatMessage`:
+ *  - `'user'` — a real player message sent via `ChatFacade.send`.
+ *  - `'system.joined'` — auto-emitted locally when a remote player enters the room.
+ *  - `'system.left'` — auto-emitted locally when a player leaves the room.
+ *
+ * System messages are computed locally on each client from `room.state.players`
+ * add/remove events; they never go over the wire. The first joiner does not
+ * see "X joined" for players already in the room when they themselves arrived
+ * (initial hydration is suppressed).
+ */
+export type ChatMessageKind = 'user' | 'system.joined' | 'system.left';
+/** Canonical chat-message shape delivered to `ChatFacade.onMessage` handlers.
+ *  See unboxy-design/features/multiplayer-chat.md §3 for the rationale on
+ *  each field. */
+export interface ChatMessage {
+    /** What kind of message this is — see `ChatMessageKind`. Default `'user'`. */
+    kind: ChatMessageKind;
+    /** For user messages: sender's session id (equals `room.sessionId` on the
+     *  sender's local-echoed copy). For system messages: the joined/left player's
+     *  session id. */
+    from: string;
+    /** Sender's (or subject's) display name at the time of the message. Empty if
+     *  the Player entry carried no displayName. */
+    displayName: string;
+    /** For user messages: the trimmed, length-capped text. For system messages:
+     *  a sensible English fallback (e.g. `"Alice joined"`). Games doing their own
+     *  i18n should switch on `kind` and ignore this. */
+    text: string;
+    /** Sender-side `Date.now()` for user messages, local `Date.now()` for system
+     *  messages. Advisory: order chat by arrival, not by ts. */
+    ts: number;
+}
+/**
+ * Convenience layer over the transient relay for in-game chat. Wraps
+ * `room.send('chat', ...)` / `room.on('chat', ...)` with three things every
+ * game would otherwise re-implement inconsistently:
+ *  - Local echo so the sender's own message hits the same handler stream
+ *    immediately (synchronous, before the network call).
+ *  - A canonical `ChatMessage` payload shape every chat in every game shares.
+ *  - Outbound `text.trim()` + length-cap to MAX_CHAT_TEXT_LEN, so a stray
+ *    paste cannot flood the relay.
+ *
+ * `displayName` is read from the sender's Player entry at send time and
+ * stamped onto the payload so receivers don't have to chase room.state to
+ * resolve a sessionId. See unboxy-design/features/multiplayer-chat.md §3.4.
+ */
+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;
+    constructor(room: Room<unknown>);
+    /**
+     * Send a chat line. Empty-after-trim input is dropped silently. Text longer
+     * than MAX_CHAT_TEXT_LEN is silently truncated. Local echo fires
+     * synchronously before the wire send, so the input box can be cleared on
+     * the same tick.
+     *
+     * Returns a Promise that resolves once dispatch is complete (local echo +
+     * wire send queued). Rejects if the underlying `room.send` throws (e.g.
+     * the connection has dropped). Note: resolution does NOT confirm remote
+     * delivery — the underlying transient relay is fire-and-forget. Use this
+     * for catching local-side errors; do not treat it as an ack.
+     */
+    send(text: string): Promise<void>;
+    /**
+     * Subscribe to chat messages — both remote and local-echoed (your own), plus
+     * auto-emitted `'system.joined'` / `'system.left'` events. Returns an
+     * unsubscribe function. Call it on scene shutdown.
+     */
+    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.
+     */
+    private subscribeToPlayers;
+    private dispatch;
+}
 /**
  * Unboxy-flavored wrapper around a Colyseus Room. Exposes only the surface
  * documented in SDK-GUIDE.md so games are portable to a different realtime
@@ -38,6 +126,7 @@ export declare class UnboxyRoom<State = unknown> {
     private readonly room;
     readonly player: PlayerDataFacade;
     readonly data: RoomDataFacade;
+    readonly chat: ChatFacade;
     constructor(room: Room<State>);
     get id(): string;
     get name(): string;

package/dist/realtime/UnboxyRoom.js

@@ -54,6 +54,176 @@ export class RoomDataFacade {
         return parseOrNull(state?.data?.get?.(key));
     }
 }
+/** Maximum text length accepted by `ChatFacade.send`. Longer input is silently
+ *  truncated. Games should mirror this on their input box's `maxLength`. */
+export const MAX_CHAT_TEXT_LEN = 500;
+/**
+ * Convenience layer over the transient relay for in-game chat. Wraps
+ * `room.send('chat', ...)` / `room.on('chat', ...)` with three things every
+ * game would otherwise re-implement inconsistently:
+ *  - Local echo so the sender's own message hits the same handler stream
+ *    immediately (synchronous, before the network call).
+ *  - A canonical `ChatMessage` payload shape every chat in every game shares.
+ *  - Outbound `text.trim()` + length-cap to MAX_CHAT_TEXT_LEN, so a stray
+ *    paste cannot flood the relay.
+ *
+ * `displayName` is read from the sender's Player entry at send time and
+ * stamped onto the payload so receivers don't have to chase room.state to
+ * resolve a sessionId. See unboxy-design/features/multiplayer-chat.md §3.4.
+ */
+export class ChatFacade {
+    constructor(room) {
+        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();
+        this.subscribeToPlayers();
+    }
+    /**
+     * Send a chat line. Empty-after-trim input is dropped silently. Text longer
+     * than MAX_CHAT_TEXT_LEN is silently truncated. Local echo fires
+     * synchronously before the wire send, so the input box can be cleared on
+     * the same tick.
+     *
+     * Returns a Promise that resolves once dispatch is complete (local echo +
+     * wire send queued). Rejects if the underlying `room.send` throws (e.g.
+     * the connection has dropped). Note: resolution does NOT confirm remote
+     * delivery — the underlying transient relay is fire-and-forget. Use this
+     * for catching local-side errors; do not treat it as an ack.
+     */
+    send(text) {
+        if (typeof text !== 'string')
+            return Promise.resolve();
+        const trimmed = text.trim();
+        if (trimmed.length === 0)
+            return Promise.resolve();
+        const capped = trimmed.length > MAX_CHAT_TEXT_LEN ? trimmed.slice(0, MAX_CHAT_TEXT_LEN) : trimmed;
+        const state = this.room.state;
+        const me = state?.players?.get?.(this.room.sessionId);
+        const displayName = typeof me?.displayName === 'string' ? me.displayName : '';
+        const msg = {
+            kind: 'user',
+            from: this.room.sessionId,
+            displayName,
+            text: capped,
+            ts: Date.now(),
+        };
+        // Local echo first, synchronously, so callers can clear input on the same
+        // tick the message lands in their chat log.
+        this.dispatch(msg);
+        // Wire send. The server's wildcard relay rebroadcasts to every other
+        // client (`except: senderClient`) with `from: client.sessionId` stamped.
+        try {
+            this.room.send('chat', { kind: 'user', text: capped, ts: msg.ts, displayName });
+        }
+        catch (err) {
+            return Promise.reject(err);
+        }
+        return Promise.resolve();
+    }
+    /**
+     * Subscribe to chat messages — both remote and local-echoed (your own), plus
+     * auto-emitted `'system.joined'` / `'system.left'` events. Returns an
+     * unsubscribe function. Call it on scene shutdown.
+     */
+    onMessage(handler) {
+        this.handlers.add(handler);
+        if (!this.remoteOff) {
+            const cb = (raw) => {
+                const p = (raw && typeof raw === 'object' ? raw : {});
+                if (typeof p.text !== 'string')
+                    return; // defensive: drop legacy raw-string sends
+                // System messages are always computed locally — clamp wire kind to 'user'.
+                const msg = {
+                    kind: 'user',
+                    from: typeof p.from === 'string' ? p.from : '',
+                    displayName: typeof p.displayName === 'string' ? p.displayName : '',
+                    text: p.text,
+                    ts: typeof p.ts === 'number' ? p.ts : Date.now(),
+                };
+                // Server uses `except: senderClient`, so a remote 'chat' is never the
+                // sender's own — no de-dupe with local echo needed.
+                this.dispatch(msg);
+            };
+            this.remoteOff = this.room.onMessage('chat', cb);
+        }
+        return () => {
+            this.handlers.delete(handler);
+        };
+    }
+    /**
+     * 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.
+     */
+    subscribeToPlayers() {
+        const players = this.room.state?.players;
+        if (!players)
+            return;
+        if (typeof players.forEach === 'function') {
+            try {
+                players.forEach((_p, sid) => { this.seen.add(sid); });
+            }
+            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');
+            }
+        }
+        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(),
+                });
+            });
+        }
+        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(),
+                });
+            });
+        }
+    }
+    dispatch(msg) {
+        for (const h of this.handlers) {
+            try {
+                h(msg);
+            }
+            catch (err) {
+                console.error('[unboxy.chat] handler threw', err);
+            }
+        }
+    }
+}
 /**
  * Unboxy-flavored wrapper around a Colyseus Room. Exposes only the surface
  * documented in SDK-GUIDE.md so games are portable to a different realtime
@@ -64,6 +234,7 @@ export class UnboxyRoom {
         this.room = room;
         this.player = new PlayerDataFacade(room);
         this.data = new RoomDataFacade(room);
+        this.chat = new ChatFacade(room);
     }
     get id() { return this.room.roomId; }
     get name() { return this.room.name; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboxy/phaser-sdk",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "description": "Unboxy Phaser 3 SDK — game infrastructure for the Unboxy platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,6 +10,7 @@
   ],
   "scripts": {
     "build": "tsc",
+    "test": "npm run build && node --test scripts/test-chat-facade.mjs",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {