@sadhaka/loom-engine 0.12.0 → 0.13.0

package/dist/network/peer-pool.js

@@ -0,0 +1,185 @@
+// PeerPool - tracks all known remote peers and their interpolated
+// world position.
+//
+// Each peer keeps the last two known positions (prev, current) with
+// timestamps. At frame time the system asks the pool for the
+// interpolated (x, y) per peer, which is computed as
+//   factor = clamp01((nowMs - prevTsMs) / (currentTsMs - prevTsMs))
+//   x      = lerp(prevX, currentX, factor)
+//   y      = lerp(prevY, currentY, factor)
+//
+// When a new presence.update arrives, prev <- current, current <- new.
+// The factor saturates at 1 once nowMs passes currentTsMs, so a peer
+// who stops sending updates simply freezes at their last known
+// position rather than extrapolating off into the distance.
+//
+// "Acceptable lag" per the phase 15.1 spec is ~150ms (one update
+// interval at the 10Hz wire rate), which is imperceptible at
+// walk-speed. No CRDT, no client-side prediction beyond the
+// straight-line lerp - those are deferred until shared state extends
+// past raw position.
+//
+// Self-filter: the local character's own character_id should NOT
+// appear among the rendered peers (we don't render ourselves as a
+// ghost). The PeerPresenceSystem owns this filter via
+// setLocalCharacterId(); peers with that id are silently skipped on
+// upsert and removed if already present.
+function lerp(a, b, t) {
+    return a + (b - a) * t;
+}
+function clamp01(t) {
+    if (t < 0)
+        return 0;
+    if (t > 1)
+        return 1;
+    return t;
+}
+export class PeerPool {
+    peers = new Map();
+    localCharacterId = null;
+    // Reused on every getRenderedPosition / forEachRendered call so the
+    // hot per-frame path is allocation-free.
+    scratchView = {
+        characterId: '',
+        x: 0,
+        y: 0,
+        zone: '',
+        name: null,
+    };
+    setLocalCharacterId(id) {
+        this.localCharacterId = id;
+        if (id !== null && this.peers.has(id)) {
+            this.peers.delete(id);
+        }
+    }
+    getLocalCharacterId() {
+        return this.localCharacterId;
+    }
+    // Apply a new presence update for a peer. If the peer is the local
+    // character, the update is ignored (self-filter). If this is the
+    // first update for the peer, prev = current = the new position so
+    // the lerp factor immediately saturates and the peer renders at the
+    // sent position.
+    upsert(characterId, x, y, zone, tsMs, name) {
+        if (this.localCharacterId !== null && characterId === this.localCharacterId) {
+            return;
+        }
+        const existing = this.peers.get(characterId);
+        if (!existing) {
+            this.peers.set(characterId, {
+                characterId,
+                zone,
+                name: name ?? null,
+                prevX: x,
+                prevY: y,
+                prevTsMs: tsMs,
+                currentX: x,
+                currentY: y,
+                currentTsMs: tsMs,
+                lastRenderedFrame: -1,
+            });
+            return;
+        }
+        // Out-of-order: drop messages older than current. Wire protocol
+        // is monotonic per character_id, but reorder buffers + reconnect
+        // replays can deliver an older ts after a newer one.
+        if (tsMs < existing.currentTsMs) {
+            return;
+        }
+        existing.prevX = existing.currentX;
+        existing.prevY = existing.currentY;
+        existing.prevTsMs = existing.currentTsMs;
+        existing.currentX = x;
+        existing.currentY = y;
+        existing.currentTsMs = tsMs;
+        existing.zone = zone;
+        if (name !== undefined) {
+            existing.name = name;
+        }
+    }
+    // Replace the entire roster with a snapshot. Peers not present in
+    // the snapshot are dropped; peers in the snapshot but not yet
+    // tracked are inserted (with prev = current so they render at the
+    // sent position immediately).
+    applySnapshot(peers) {
+        const seen = new Set();
+        for (let i = 0; i < peers.length; i++) {
+            const p = peers[i];
+            if (!p)
+                continue;
+            if (this.localCharacterId !== null && p.characterId === this.localCharacterId) {
+                continue;
+            }
+            seen.add(p.characterId);
+            this.upsert(p.characterId, p.x, p.y, p.zone, p.tsMs, p.name);
+        }
+        // Drop anyone not in the snapshot. Iterate keys snapshot first
+        // because Map.delete during iteration is fine but copying makes
+        // intent obvious.
+        const toRemove = [];
+        this.peers.forEach((_v, k) => {
+            if (!seen.has(k))
+                toRemove.push(k);
+        });
+        for (let i = 0; i < toRemove.length; i++) {
+            const k = toRemove[i];
+            if (k)
+                this.peers.delete(k);
+        }
+    }
+    remove(characterId) {
+        return this.peers.delete(characterId);
+    }
+    has(characterId) {
+        return this.peers.has(characterId);
+    }
+    size() {
+        return this.peers.size;
+    }
+    get(characterId) {
+        return this.peers.get(characterId);
+    }
+    // Iterate every tracked peer with their interpolated world
+    // position at nowMs. The view object is reused; consumers must
+    // copy any field they want to retain past the callback.
+    forEachRendered(nowMs, frame, fn) {
+        this.peers.forEach((entry) => {
+            const v = this.scratchView;
+            v.characterId = entry.characterId;
+            v.zone = entry.zone;
+            v.name = entry.name;
+            const dt = entry.currentTsMs - entry.prevTsMs;
+            if (dt <= 0) {
+                v.x = entry.currentX;
+                v.y = entry.currentY;
+            }
+            else {
+                const t = clamp01((nowMs - entry.prevTsMs) / dt);
+                v.x = lerp(entry.prevX, entry.currentX, t);
+                v.y = lerp(entry.prevY, entry.currentY, t);
+            }
+            entry.lastRenderedFrame = frame;
+            fn(v);
+        });
+    }
+    // Single-peer query for tests + the rare ad-hoc lookup. Hot paths
+    // use forEachRendered to avoid map lookups.
+    getRenderedPosition(characterId, nowMs) {
+        const entry = this.peers.get(characterId);
+        if (!entry)
+            return null;
+        const dt = entry.currentTsMs - entry.prevTsMs;
+        if (dt <= 0) {
+            return { x: entry.currentX, y: entry.currentY };
+        }
+        const t = clamp01((nowMs - entry.prevTsMs) / dt);
+        return {
+            x: lerp(entry.prevX, entry.currentX, t),
+            y: lerp(entry.prevY, entry.currentY, t),
+        };
+    }
+    clear() {
+        this.peers.clear();
+    }
+}
+//# sourceMappingURL=peer-pool.js.map

package/dist/network/peer-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-pool.js","sourceRoot":"","sources":["../../src/network/peer-pool.ts"],"names":[],"mappings":"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"}

package/dist/network/sse-multiplayer-bridge.d.ts

@@ -0,0 +1,36 @@
+import { type IMultiplayerBridge, type MultiplayerBridgeStatus, type MultiplayerBridgeStats, type PresenceMessage } from './multiplayer-bridge.js';
+export interface SSEMultiplayerBridgeOptions {
+    baseUrl: string;
+    broadcastUrl?: string;
+    characterId: string;
+    zone: string;
+    eventSourceFactory?: (url: string) => EventSource;
+    fetchFn?: typeof fetch;
+}
+export declare class SSEMultiplayerBridge implements IMultiplayerBridge {
+    private readonly baseUrl;
+    private readonly broadcastUrl;
+    private readonly characterId;
+    private readonly zone;
+    private readonly eventSourceFactory;
+    private readonly fetchFn;
+    private es;
+    private queue;
+    private statusValue;
+    private statsValue;
+    private lastBroadcastMs;
+    constructor(opts: SSEMultiplayerBridgeOptions);
+    connect(): void;
+    disconnect(): void;
+    status(): MultiplayerBridgeStatus;
+    pollMessages(): PresenceMessage[];
+    broadcastPosition(x: number, y: number, zone: string, tsMs: number): void;
+    stats(): Readonly<MultiplayerBridgeStats>;
+    private buildUrl;
+    private openConnection;
+    private closeConnection;
+    private handleUpdate;
+    private handleDepart;
+    private handleSnapshot;
+}
+//# sourceMappingURL=sse-multiplayer-bridge.d.ts.map

package/dist/network/sse-multiplayer-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-multiplayer-bridge.d.ts","sourceRoot":"","sources":["../../src/network/sse-multiplayer-bridge.ts"],"names":[],"mappings":"AA4BA,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EAErB,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,2BAA2B;IAI1C,OAAO,EAAE,MAAM,CAAC;IAKhB,YAAY,CAAC,EAAE,MAAM,CAAC;IAItB,WAAW,EAAE,MAAM,CAAC;IAEpB,IAAI,EAAE,MAAM,CAAC;IAGb,kBAAkB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,WAAW,CAAC;IAClD,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB;AAED,qBAAa,oBAAqB,YAAW,kBAAkB;IAC7D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA+B;IAClE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IAEvC,OAAO,CAAC,EAAE,CAA4B;IACtC,OAAO,CAAC,KAAK,CAAyB;IACtC,OAAO,CAAC,WAAW,CAAmC;IACtD,OAAO,CAAC,UAAU,CAKhB;IAEF,OAAO,CAAC,eAAe,CAAqB;gBAEhC,IAAI,EAAE,2BAA2B;IAwB7C,OAAO,IAAI,IAAI;IAMf,UAAU,IAAI,IAAI;IAKlB,MAAM,IAAI,uBAAuB;IAIjC,YAAY,IAAI,eAAe,EAAE;IAOjC,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IA0BzE,KAAK,IAAI,QAAQ,CAAC,sBAAsB,CAAC;IAMzC,OAAO,CAAC,QAAQ;IAUhB,OAAO,CAAC,cAAc;IAmCtB,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,YAAY;IAyBpB,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,cAAc;CAsCvB"}

package/dist/network/sse-multiplayer-bridge.js

@@ -0,0 +1,264 @@
+// SSEMultiplayerBridge - real EventSource subscription to the
+// backend's presence endpoint, paired with a fetch POST for outbound
+// position broadcasts.
+//
+// Wire protocol (paired with Track B server-side):
+//   GET <baseUrl>?character_id=...&zone=... opens an SSE stream that
+//   emits three event types:
+//     - 'presence.snapshot' { peers: [{ character_id, x, y, zone, ts_ms, name? }] }
+//         emitted once on connect with the full current peer roster.
+//     - 'presence.update'   { character_id, x, y, zone, ts_ms, name? }
+//         emitted as peers move.
+//     - 'presence.depart'   { character_id }
+//         emitted when a peer disconnects.
+//
+//   POST <broadcastUrl> { character_id, x, y, zone, ts_ms }
+//     called by broadcastPosition at most BROADCAST_HZ per second.
+//     Engine-side rate limit; the bridge silently drops excess calls
+//     and increments rateLimitedDrops.
+//
+// Reconnect strategy: EventSource handles transport-layer reconnect
+// internally. We observe via onerror/onopen and surface 'reconnecting'
+// to the consumer. On reconnect the server is expected to re-emit a
+// fresh 'presence.snapshot', which the PeerPool consumes and treats
+// as authoritative (any peer not in the snapshot is dropped).
+//
+// Browser-only. Constructor throws if EventSource is undefined (Node
+// test environment). Tests use MockMultiplayerBridge instead.
+import { BROADCAST_MIN_INTERVAL_MS, } from './multiplayer-bridge.js';
+export class SSEMultiplayerBridge {
+    baseUrl;
+    broadcastUrl;
+    characterId;
+    zone;
+    eventSourceFactory;
+    fetchFn;
+    es = null;
+    queue = [];
+    statusValue = 'idle';
+    statsValue = {
+        messagesReceived: 0,
+        messagesSent: 0,
+        rateLimitedDrops: 0,
+        reconnects: 0,
+    };
+    lastBroadcastMs = -Infinity;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl;
+        this.broadcastUrl = opts.broadcastUrl ?? defaultBroadcastUrl(opts.baseUrl);
+        this.characterId = opts.characterId;
+        this.zone = opts.zone;
+        if (opts.eventSourceFactory) {
+            this.eventSourceFactory = opts.eventSourceFactory;
+        }
+        else {
+            if (typeof EventSource === 'undefined') {
+                throw new Error('SSEMultiplayerBridge: EventSource is not available in this environment. Use MockMultiplayerBridge for tests.');
+            }
+            const ESCtor = EventSource;
+            this.eventSourceFactory = (u) => new ESCtor(u, { withCredentials: true });
+        }
+        if (opts.fetchFn) {
+            this.fetchFn = opts.fetchFn;
+        }
+        else {
+            if (typeof fetch === 'undefined') {
+                throw new Error('SSEMultiplayerBridge: fetch is not available in this environment.');
+            }
+            this.fetchFn = fetch.bind(globalThis);
+        }
+    }
+    connect() {
+        if (this.es)
+            return;
+        this.statusValue = 'connecting';
+        this.openConnection();
+    }
+    disconnect() {
+        this.statusValue = 'closed';
+        this.closeConnection();
+    }
+    status() {
+        return this.statusValue;
+    }
+    pollMessages() {
+        if (this.queue.length === 0)
+            return [];
+        const out = this.queue;
+        this.queue = [];
+        return out;
+    }
+    broadcastPosition(x, y, zone, tsMs) {
+        const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
+        if (now - this.lastBroadcastMs < BROADCAST_MIN_INTERVAL_MS) {
+            this.statsValue.rateLimitedDrops++;
+            return;
+        }
+        this.lastBroadcastMs = now;
+        this.statsValue.messagesSent++;
+        // Fire-and-forget POST. Errors are surfaced via stats only - the
+        // engine doesn't block on the network round trip. The body
+        // matches the server contract from the phase 15.1 spec.
+        const body = JSON.stringify({
+            character_id: this.characterId,
+            x,
+            y,
+            zone,
+            ts_ms: tsMs,
+        });
+        void this.fetchFn(this.broadcastUrl, {
+            method: 'POST',
+            credentials: 'include',
+            headers: { 'Content-Type': 'application/json' },
+            body,
+        }).catch(() => { });
+    }
+    stats() {
+        return this.statsValue;
+    }
+    // ----- Internal -----
+    buildUrl() {
+        const sep = this.baseUrl.includes('?') ? '&' : '?';
+        return (this.baseUrl +
+            sep +
+            'character_id=' + encodeURIComponent(this.characterId) +
+            '&zone=' + encodeURIComponent(this.zone));
+    }
+    openConnection() {
+        const url = this.buildUrl();
+        let es;
+        try {
+            es = this.eventSourceFactory(url);
+        }
+        catch (err) {
+            this.statusValue = 'closed';
+            throw err;
+        }
+        this.es = es;
+        es.onopen = () => {
+            this.statusValue = 'connected';
+        };
+        es.onerror = () => {
+            const closed = es.readyState === 2; // EventSource.CLOSED
+            if (closed) {
+                this.statusValue = 'closed';
+                this.closeConnection();
+                return;
+            }
+            this.statusValue = 'reconnecting';
+            this.statsValue.reconnects++;
+        };
+        es.addEventListener('presence.update', (e) => {
+            this.handleUpdate(e);
+        });
+        es.addEventListener('presence.depart', (e) => {
+            this.handleDepart(e);
+        });
+        es.addEventListener('presence.snapshot', (e) => {
+            this.handleSnapshot(e);
+        });
+    }
+    closeConnection() {
+        if (!this.es)
+            return;
+        try {
+            this.es.close();
+        }
+        catch { /* ignore */ }
+        this.es = null;
+    }
+    handleUpdate(e) {
+        const data = parseJson(e.data);
+        if (!data || typeof data !== 'object')
+            return;
+        const characterId = data.character_id;
+        const x = data.x;
+        const y = data.y;
+        const zone = data.zone;
+        const tsMs = data.ts_ms;
+        if (typeof characterId !== 'string')
+            return;
+        if (typeof x !== 'number' || typeof y !== 'number')
+            return;
+        if (typeof zone !== 'string')
+            return;
+        if (typeof tsMs !== 'number')
+            return;
+        const name = data.name;
+        this.statsValue.messagesReceived++;
+        this.queue.push({
+            kind: 'update',
+            characterId,
+            x,
+            y,
+            zone,
+            tsMs,
+            ...(typeof name === 'string' ? { name } : {}),
+        });
+    }
+    handleDepart(e) {
+        const data = parseJson(e.data);
+        if (!data || typeof data !== 'object')
+            return;
+        const characterId = data.character_id;
+        if (typeof characterId !== 'string')
+            return;
+        this.statsValue.messagesReceived++;
+        this.queue.push({ kind: 'depart', characterId });
+    }
+    handleSnapshot(e) {
+        const data = parseJson(e.data);
+        if (!data || typeof data !== 'object')
+            return;
+        const peersRaw = data.peers;
+        if (!Array.isArray(peersRaw))
+            return;
+        const peers = [];
+        for (let i = 0; i < peersRaw.length; i++) {
+            const p = peersRaw[i];
+            if (!p || typeof p !== 'object')
+                continue;
+            const characterId = p.character_id;
+            const x = p.x;
+            const y = p.y;
+            const zone = p.zone;
+            const tsMs = p.ts_ms;
+            if (typeof characterId !== 'string')
+                continue;
+            if (typeof x !== 'number' || typeof y !== 'number')
+                continue;
+            if (typeof zone !== 'string')
+                continue;
+            if (typeof tsMs !== 'number')
+                continue;
+            const name = p.name;
+            peers.push({
+                characterId,
+                x,
+                y,
+                zone,
+                tsMs,
+                ...(typeof name === 'string' ? { name } : {}),
+            });
+        }
+        this.statsValue.messagesReceived++;
+        this.queue.push({ kind: 'snapshot', peers });
+    }
+}
+function parseJson(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function defaultBroadcastUrl(baseUrl) {
+    if (baseUrl.endsWith('/events')) {
+        return baseUrl.slice(0, -'/events'.length) + '/move';
+    }
+    return baseUrl + '/move';
+}
+//# sourceMappingURL=sse-multiplayer-bridge.js.map

package/dist/network/sse-multiplayer-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-multiplayer-bridge.js","sourceRoot":"","sources":["../../src/network/sse-multiplayer-bridge.ts"],"names":[],"mappings":"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"}

package/dist/systems/peer-presence-system.d.ts

@@ -0,0 +1,19 @@
+import type { System } from '../system.js';
+import type { World } from '../world.js';
+export declare class PeerPresenceSystem implements System {
+    readonly name: string;
+    update(world: World, _dt: number): void;
+}
+export declare class PeerRenderSystem implements System {
+    readonly name: string;
+    private scratchTextStyle;
+    private scratchTint;
+    private readonly labelYOffset;
+    private readonly showNames;
+    constructor(opts?: {
+        labelYOffset?: number;
+        showNames?: boolean;
+    });
+    update(world: World, _dt: number): void;
+}
+//# sourceMappingURL=peer-presence-system.d.ts.map

package/dist/systems/peer-presence-system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-presence-system.d.ts","sourceRoot":"","sources":["../../src/systems/peer-presence-system.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAiBzC,qBAAa,kBAAmB,YAAW,MAAM;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAmB;IAExC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;CAwBxC;AAKD,qBAAa,gBAAiB,YAAW,MAAM;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAiB;IAGtC,OAAO,CAAC,gBAAgB,CAKtB;IACF,OAAO,CAAC,WAAW,CAEjB;IAMF,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;gBAExB,IAAI,GAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAO;IAKrE,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;CAgCxC"}

package/dist/systems/peer-presence-system.js

@@ -0,0 +1,118 @@
+// PeerPresenceSystem - drains the IMultiplayerBridge each tick, applies
+// presence messages to the PeerPool, and (optionally) broadcasts the
+// local character's position via PeerBroadcastBridge.
+//
+// PeerRenderSystem - iterates PeerPool at frame time, computes each
+// peer's interpolated position from prev/current samples, looks up
+// their sprite via PeerSpritePool, and submits drawSprite + drawText
+// (name label) calls to the device.
+//
+// Phasing rationale (matches DirectorSystem):
+//   PHASE_INPUT  - PeerPresenceSystem drains the bridge so peers are
+//                  fresh before any logic system reads them. Mirrors
+//                  the DirectorSystem ordering.
+//   PHASE_RENDER - PeerRenderSystem submits draw calls. Per-peer
+//                  interp factor is computed from the current
+//                  TimeResource clock, so peers move smoothly even on
+//                  frames with no inbound update.
+//
+// PeerPresenceSystem also routes the snapshot, update, and depart
+// message kinds to the right PeerPool method:
+//   snapshot -> applySnapshot (drops anyone not in the snapshot)
+//   update   -> upsert
+//   depart   -> remove
+//
+// Self-filter: callers register the local character_id via
+// peerPool.setLocalCharacterId(...) at startup. The pool refuses to
+// store an entry with that id; if a snapshot or update mentions it,
+// it's silently skipped (we don't render ourselves as a ghost).
+import { RESOURCE_MULTIPLAYER_BRIDGE, RESOURCE_PEER_POOL, } from '../network/multiplayer-bridge.js';
+import { POOL_PEER_SPRITE } from '../components/peer-sprite.js';
+import { RESOURCE_DEVICE, RESOURCE_CAMERA, RESOURCE_TIME, } from '../resources.js';
+export class PeerPresenceSystem {
+    name = 'peer-presence';
+    update(world, _dt) {
+        const bridge = world.resources.get(RESOURCE_MULTIPLAYER_BRIDGE);
+        const pool = world.resources.get(RESOURCE_PEER_POOL);
+        if (!bridge || !pool)
+            return;
+        const messages = bridge.pollMessages();
+        if (messages.length === 0)
+            return;
+        for (let i = 0; i < messages.length; i++) {
+            const m = messages[i];
+            if (!m)
+                continue;
+            switch (m.kind) {
+                case 'update':
+                    pool.upsert(m.characterId, m.x, m.y, m.zone, m.tsMs, m.name);
+                    break;
+                case 'depart':
+                    pool.remove(m.characterId);
+                    break;
+                case 'snapshot':
+                    pool.applySnapshot(m.peers);
+                    break;
+            }
+        }
+    }
+}
+// Render-phase counterpart. Optional - consumers who only want to
+// surface peer state (e.g. on a minimap) can read PeerPool directly
+// and skip this system.
+export class PeerRenderSystem {
+    name = 'peer-render';
+    // Reused per-frame to avoid allocation in the per-peer hot path.
+    scratchTextStyle = {
+        font: '12px sans-serif',
+        fill: { r: 1, g: 1, b: 1, a: 1 },
+        align: 'center',
+        baseline: 'bottom',
+    };
+    scratchTint = {
+        r: 1, g: 1, b: 1, a: 1,
+    };
+    // Vertical offset (world units) applied to the name label so it
+    // sits just above the sprite. Tuned for the engine's standard
+    // 64-px sprite cell; consumers with custom art can override via
+    // the PeerRenderSystem constructor.
+    labelYOffset;
+    showNames;
+    constructor(opts = {}) {
+        this.labelYOffset = opts.labelYOffset ?? -32;
+        this.showNames = opts.showNames ?? true;
+    }
+    update(world, _dt) {
+        const pool = world.resources.get(RESOURCE_PEER_POOL);
+        const sprites = world.getPool(POOL_PEER_SPRITE);
+        const device = world.resources.get(RESOURCE_DEVICE);
+        const camera = world.resources.get(RESOURCE_CAMERA);
+        const time = world.resources.get(RESOURCE_TIME);
+        if (!pool || !sprites || !device || !camera)
+            return;
+        device.setCamera(camera);
+        const nowMs = (time ? time.elapsed * 1000 : 0) + (typeof performance !== 'undefined' ? performance.now() : 0);
+        const frame = time ? time.frame : -1;
+        // Capture the values we need from each peer before drawing.
+        // forEachRendered's view is reused; we have to read fields out
+        // before the next iteration mutates the scratch.
+        pool.forEachRendered(nowMs, frame, (view) => {
+            const entry = sprites.resolve(view.characterId);
+            if (entry.tint) {
+                const t = this.scratchTint;
+                t.r = entry.tint.r;
+                t.g = entry.tint.g;
+                t.b = entry.tint.b;
+                t.a = entry.tint.a;
+                device.drawSprite(view.x, view.y, 0, entry.atlas, entry.frame, t);
+            }
+            else {
+                device.drawSprite(view.x, view.y, 0, entry.atlas, entry.frame);
+            }
+            if (this.showNames && view.name) {
+                device.drawText(view.x, view.y + this.labelYOffset, view.name, this.scratchTextStyle);
+            }
+        });
+    }
+}
+//# sourceMappingURL=peer-presence-system.js.map

package/dist/systems/peer-presence-system.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-presence-system.js","sourceRoot":"","sources":["../../src/systems/peer-presence-system.ts"],"names":[],"mappings":"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"}