@umicat/phaser-sdk 1.0.0

package/dist/realtime/UmicatRoom.js

@@ -0,0 +1,353 @@
+function parseOrNull(raw) {
+    if (raw == null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Facade for per-player state — one entry per player, only the owner can write
+ * to their own entry. Delta-synced via Colyseus schema.
+ */
+export class PlayerDataFacade {
+    constructor(room) {
+        this.room = room;
+    }
+    /** Write a JSON-serializable value to the caller's own player data. */
+    set(key, value) {
+        this.room.send('player.set', { key, value });
+    }
+    /** Remove a key from the caller's own player data. */
+    delete(key) {
+        this.room.send('player.delete', { key });
+    }
+    /** Read a player's data value. Returns null if the player or key is absent. */
+    get(sessionId, key) {
+        const state = this.room.state;
+        const player = state?.players?.get?.(sessionId);
+        return parseOrNull(player?.data?.get?.(key));
+    }
+}
+/**
+ * Facade for room-scope shared state — one map per room, any client may write.
+ * Delta-synced via Colyseus schema. Use for shared game state like current
+ * turn, scoreboard, shared level-of-the-day, etc.
+ */
+export class RoomDataFacade {
+    constructor(room) {
+        this.room = room;
+    }
+    /** Write a JSON-serializable value into the room's shared data map. */
+    set(key, value) {
+        this.room.send('room.set', { key, value });
+    }
+    /** Remove a key from the room's shared data map. */
+    delete(key) {
+        this.room.send('room.delete', { key });
+    }
+    /** Read a shared room value. Returns null if the key is absent. */
+    get(key) {
+        const state = this.room.state;
+        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 umicat-design/features/multiplayer-chat.md §3.4.
+ */
+export class ChatFacade {
+    constructor(room) {
+        this.room = room;
+        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 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();
+    }
+    /**
+     * 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);
+        };
+    }
+    /**
+     * 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 UmicatRoom
+     * 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 || 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 (!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) => {
+                    const name = typeof p?.displayName === 'string' ? p.displayName : '';
+                    this.knownNames.set(sid, name);
+                });
+            }
+            catch {
+                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()]) {
+            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(),
+            });
+        }
+    }
+    dispatch(msg) {
+        for (const h of this.handlers) {
+            try {
+                h(msg);
+            }
+            catch (err) {
+                console.error('[umicat.chat] handler threw', err);
+            }
+        }
+    }
+}
+/**
+ * Umicat-flavored wrapper around a Colyseus Room. Exposes only the surface
+ * documented in SDK-GUIDE.md so games are portable to a different realtime
+ * backend should we migrate away from Colyseus.
+ */
+export class UmicatRoom {
+    constructor(room) {
+        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; }
+    get sessionId() { return this.room.sessionId; }
+    /**
+     * Current server-authoritative state. Proxied from Colyseus Schema — read
+     * values directly. Mutations do not propagate; only server-side handlers
+     * may change state.
+     */
+    get state() { return this.room.state; }
+    /** Send a transient message. Relayed to every other client in the room
+     *  with `from: sessionId` stamped onto the payload. Not persisted in state. */
+    send(type, payload) {
+        this.room.send(type, payload);
+    }
+    /** Register a handler for a server-sent message type. Returns unsubscribe. */
+    on(type, handler) {
+        return this.room.onMessage(type, handler);
+    }
+    /** Fires whenever the server-authoritative state changes. */
+    onStateChange(handler) {
+        const cb = () => handler(this.room.state);
+        this.room.onStateChange(cb);
+        return () => this.room.onStateChange.remove(cb);
+    }
+    /**
+     * Fires when the connection closes (kick, server shutdown, network drop).
+     * `code` follows WebSocket close codes plus Colyseus-specific ones.
+     */
+    onLeave(handler) {
+        const cb = (code) => handler(code);
+        this.room.onLeave(cb);
+        return () => this.room.onLeave.remove(cb);
+    }
+    /** Fires when the server reports an error for this room. */
+    onError(handler) {
+        const cb = (code, message) => handler(code, message);
+        this.room.onError(cb);
+        return () => this.room.onError.remove(cb);
+    }
+    /** Disconnect from the room. Resolves with the close code. */
+    async leave(consented = true) {
+        return this.room.leave(consented);
+    }
+}

package/dist/recording/RecordingManager.d.ts

@@ -0,0 +1,11 @@
+import Phaser from 'phaser';
+/**
+ * Sets up postMessage listeners for video recording of the game canvas.
+ *
+ * Parent sends: 'startRecording'
+ * Game responds: { type: 'recordingStarted' }
+ *
+ * Parent sends: 'stopRecording'
+ * Game responds: { type: 'recordingComplete', data: string (base64 data URL), mimeType: string }
+ */
+export declare function setupRecordingListener(game: Phaser.Game): void;

package/dist/recording/RecordingManager.js

@@ -0,0 +1,59 @@
+let mediaRecorder = null;
+let recordedChunks = [];
+/**
+ * Sets up postMessage listeners for video recording of the game canvas.
+ *
+ * Parent sends: 'startRecording'
+ * Game responds: { type: 'recordingStarted' }
+ *
+ * Parent sends: 'stopRecording'
+ * Game responds: { type: 'recordingComplete', data: string (base64 data URL), mimeType: string }
+ */
+export function setupRecordingListener(game) {
+    window.addEventListener('message', (event) => {
+        if (event.data === 'startRecording') {
+            try {
+                const canvas = game.canvas;
+                if (!canvas)
+                    return;
+                recordedChunks = [];
+                const stream = canvas.captureStream(30);
+                // Pick best available codec
+                const mimeType = MediaRecorder.isTypeSupported('video/webm;codecs=vp9')
+                    ? 'video/webm;codecs=vp9'
+                    : 'video/webm';
+                mediaRecorder = new MediaRecorder(stream, {
+                    mimeType,
+                    videoBitsPerSecond: 1500000, // 1.5 Mbps
+                });
+                mediaRecorder.ondataavailable = (e) => {
+                    if (e.data.size > 0)
+                        recordedChunks.push(e.data);
+                };
+                mediaRecorder.onstop = () => {
+                    const blob = new Blob(recordedChunks, { type: 'video/webm' });
+                    const reader = new FileReader();
+                    reader.onloadend = () => {
+                        window.parent.postMessage({
+                            type: 'recordingComplete',
+                            data: reader.result,
+                            mimeType: 'video/webm',
+                        }, '*');
+                    };
+                    reader.readAsDataURL(blob);
+                };
+                mediaRecorder.start(1000); // collect data every 1 second
+                window.parent.postMessage({ type: 'recordingStarted' }, '*');
+            }
+            catch (e) {
+                console.error('[UmicatSDK] Recording failed to start:', e);
+                window.parent.postMessage({ type: 'recordingError', error: String(e) }, '*');
+            }
+        }
+        if (event.data === 'stopRecording') {
+            if (mediaRecorder && mediaRecorder.state !== 'inactive') {
+                mediaRecorder.stop();
+            }
+        }
+    });
+}

package/dist/saves/SavesModule.d.ts

@@ -0,0 +1,23 @@
+import type { Transport } from '../core/Transport.js';
+/**
+ * Per-user key-value save data scoped to the current (game, user).
+ *
+ * When the viewer is authenticated, reads/writes go through the host to the
+ * Umicat backend. When anonymous or standalone, the same API is backed by
+ * localStorage — games do not branch on auth state.
+ *
+ * Size quotas (enforced at the backend):
+ *   - 100 KB per value
+ *   - 1 MB total per (game, user)
+ *   - 64 keys per (game, user)
+ */
+export declare class SavesModule {
+    private transport;
+    constructor(transport: Transport);
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown, options?: {
+        ifVersion?: number;
+    }): Promise<number>;
+    delete(key: string): Promise<boolean>;
+    list(): Promise<string[]>;
+}

package/dist/saves/SavesModule.js

@@ -0,0 +1,37 @@
+/**
+ * Per-user key-value save data scoped to the current (game, user).
+ *
+ * When the viewer is authenticated, reads/writes go through the host to the
+ * Umicat backend. When anonymous or standalone, the same API is backed by
+ * localStorage — games do not branch on auth state.
+ *
+ * Size quotas (enforced at the backend):
+ *   - 100 KB per value
+ *   - 1 MB total per (game, user)
+ *   - 64 keys per (game, user)
+ */
+export class SavesModule {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async get(key) {
+        const res = await this.transport.call('saves.get', { key });
+        return (res?.value ?? null);
+    }
+    async set(key, value, options) {
+        const res = await this.transport.call('saves.set', {
+            key,
+            value,
+            ifVersion: options?.ifVersion,
+        });
+        return res.version;
+    }
+    async delete(key) {
+        const res = await this.transport.call('saves.delete', { key });
+        return res.deleted;
+    }
+    async list() {
+        const res = await this.transport.call('saves.list');
+        return res.keys;
+    }
+}

package/dist/scene/EditorMode.d.ts

@@ -0,0 +1,17 @@
+import Phaser from 'phaser';
+/**
+ * Slice-1 entry point that became a thin wrapper over the slice-2 editor
+ * bridge. The bridge owns the full edit-mode lifecycle (pause world scenes,
+ * launch overlay, handle pointer events, route postMessage commands).
+ *
+ * Wire shape (host → SDK):
+ *   { type: 'umicat:editor:enter' }   - enter edit mode
+ *   { type: 'umicat:editor:exit'  }   - exit edit mode
+ *   ...plus the rest of the editor protocol — see protocol.ts
+ *
+ * The slice-1 `umicat:setEditMode` message is no longer accepted; home-ui
+ * has been updated to send the editor:enter / editor:exit pair as part of
+ * the slice-2 work.
+ */
+export declare function setupEditorModeListener(game: Phaser.Game): void;
+export declare function isEditMode(game: Phaser.Game): boolean;

package/dist/scene/EditorMode.js

@@ -0,0 +1,22 @@
+import { setupEditorBridge } from '../editor/EditorBridge.js';
+import { getEditorState } from '../editor/EditorState.js';
+/**
+ * Slice-1 entry point that became a thin wrapper over the slice-2 editor
+ * bridge. The bridge owns the full edit-mode lifecycle (pause world scenes,
+ * launch overlay, handle pointer events, route postMessage commands).
+ *
+ * Wire shape (host → SDK):
+ *   { type: 'umicat:editor:enter' }   - enter edit mode
+ *   { type: 'umicat:editor:exit'  }   - exit edit mode
+ *   ...plus the rest of the editor protocol — see protocol.ts
+ *
+ * The slice-1 `umicat:setEditMode` message is no longer accepted; home-ui
+ * has been updated to send the editor:enter / editor:exit pair as part of
+ * the slice-2 work.
+ */
+export function setupEditorModeListener(game) {
+    setupEditorBridge(game);
+}
+export function isEditMode(game) {
+    return getEditorState(game).active;
+}

package/dist/scene/EntityRegistry.d.ts

@@ -0,0 +1,39 @@
+import Phaser from 'phaser';
+/**
+ * Per-scene lookup of spawned entities. Behavior code uses this to find
+ * the player, enemies, doors, etc. by id or role without coupling to
+ * scene-file structure.
+ *
+ * Created by `loadWorldScene` and stashed on `scene.data` under the key
+ * `'unboxyEntityRegistry'`. Access via `getEntityRegistry(scene)`.
+ */
+export declare class EntityRegistry {
+    private byIdMap;
+    private byRoleMap;
+    /**
+     * Slice 11 (Phase B.1): track every spawned instance of each prefab so
+     * the editor's `umicat:editor:editPrefab` flow can re-apply visual /
+     * physics edits to live instances. Populated by `spawnPrefab`; ignored
+     * for non-prefab entities authored in scene JSON.
+     */
+    private byPrefabIdMap;
+    /** Per-prefab monotonic counter for runtime-generated entity ids. */
+    private prefabCounters;
+    register(id: string, role: string | undefined, go: Phaser.GameObjects.GameObject, prefabId?: string): void;
+    byId(id: string): Phaser.GameObjects.GameObject | undefined;
+    byRole(role: string): Phaser.GameObjects.GameObject[];
+    /** All live instances of a given prefab. Slice 11. */
+    byPrefabId(prefabId: string): Phaser.GameObjects.GameObject[];
+    all(): Phaser.GameObjects.GameObject[];
+    /**
+     * Reserve the next runtime id for instances of `prefabId`. Format
+     * is `<prefabId>#<counter>` starting at 1. Used by `spawnPrefab`.
+     */
+    nextInstanceId(prefabId: string): string;
+    /** Remove an entity from the registry. Does NOT destroy the GameObject —
+     *  callers (editor delete path) destroy first, then unregister. */
+    unregister(id: string): void;
+    clear(): void;
+}
+export declare function attachEntityRegistry(scene: Phaser.Scene): EntityRegistry;
+export declare function getEntityRegistry(scene: Phaser.Scene): EntityRegistry | undefined;

package/dist/scene/EntityRegistry.js

@@ -0,0 +1,103 @@
+/**
+ * Per-scene lookup of spawned entities. Behavior code uses this to find
+ * the player, enemies, doors, etc. by id or role without coupling to
+ * scene-file structure.
+ *
+ * Created by `loadWorldScene` and stashed on `scene.data` under the key
+ * `'unboxyEntityRegistry'`. Access via `getEntityRegistry(scene)`.
+ */
+export class EntityRegistry {
+    constructor() {
+        this.byIdMap = new Map();
+        this.byRoleMap = new Map();
+        /**
+         * Slice 11 (Phase B.1): track every spawned instance of each prefab so
+         * the editor's `umicat:editor:editPrefab` flow can re-apply visual /
+         * physics edits to live instances. Populated by `spawnPrefab`; ignored
+         * for non-prefab entities authored in scene JSON.
+         */
+        this.byPrefabIdMap = new Map();
+        /** Per-prefab monotonic counter for runtime-generated entity ids. */
+        this.prefabCounters = new Map();
+    }
+    register(id, role, go, prefabId) {
+        this.byIdMap.set(id, go);
+        if (role) {
+            const list = this.byRoleMap.get(role) ?? [];
+            list.push(go);
+            this.byRoleMap.set(role, list);
+        }
+        if (prefabId) {
+            const list = this.byPrefabIdMap.get(prefabId) ?? [];
+            list.push(go);
+            this.byPrefabIdMap.set(prefabId, list);
+        }
+    }
+    byId(id) {
+        return this.byIdMap.get(id);
+    }
+    byRole(role) {
+        return this.byRoleMap.get(role) ?? [];
+    }
+    /** All live instances of a given prefab. Slice 11. */
+    byPrefabId(prefabId) {
+        return this.byPrefabIdMap.get(prefabId) ?? [];
+    }
+    all() {
+        return Array.from(this.byIdMap.values());
+    }
+    /**
+     * Reserve the next runtime id for instances of `prefabId`. Format
+     * is `<prefabId>#<counter>` starting at 1. Used by `spawnPrefab`.
+     */
+    nextInstanceId(prefabId) {
+        const next = (this.prefabCounters.get(prefabId) ?? 0) + 1;
+        this.prefabCounters.set(prefabId, next);
+        return `${prefabId}#${next}`;
+    }
+    /** Remove an entity from the registry. Does NOT destroy the GameObject —
+     *  callers (editor delete path) destroy first, then unregister. */
+    unregister(id) {
+        const go = this.byIdMap.get(id);
+        if (!go)
+            return;
+        this.byIdMap.delete(id);
+        for (const [role, list] of this.byRoleMap) {
+            const idx = list.indexOf(go);
+            if (idx >= 0) {
+                list.splice(idx, 1);
+                if (list.length === 0)
+                    this.byRoleMap.delete(role);
+            }
+        }
+        for (const [prefabId, list] of this.byPrefabIdMap) {
+            const idx = list.indexOf(go);
+            if (idx >= 0) {
+                list.splice(idx, 1);
+                if (list.length === 0)
+                    this.byPrefabIdMap.delete(prefabId);
+            }
+        }
+    }
+    clear() {
+        this.byIdMap.clear();
+        this.byRoleMap.clear();
+        this.byPrefabIdMap.clear();
+        this.prefabCounters.clear();
+    }
+}
+const REGISTRY_KEY = 'unboxyEntityRegistry';
+export function attachEntityRegistry(scene) {
+    const existing = scene.data?.get(REGISTRY_KEY);
+    if (existing) {
+        existing.clear();
+        return existing;
+    }
+    const registry = new EntityRegistry();
+    // Phaser auto-creates DataManager on first .data access if absent.
+    scene.data.set(REGISTRY_KEY, registry);
+    return registry;
+}
+export function getEntityRegistry(scene) {
+    return scene.data?.get(REGISTRY_KEY);
+}