@mpgd/game-runtime 0.1.0

package/dist/phaser/index.js

@@ -0,0 +1,286 @@
+export function bindPhaserGameScene(input) {
+    const { scene, controller, resetInput, audio, uiScope, onUnsupportedState, onError } = input;
+    if (input.renderingPolicy !== 'visibility' || typeof onUnsupportedState !== 'function') {
+        throw new TypeError('Choose visibility rendering and provide an unsupported-state observer.');
+    }
+    if (typeof resetInput !== 'function') {
+        throw new TypeError('Provide a gameplay input reset callback.');
+    }
+    if (controller.getSnapshot().status === 'destroyed') {
+        throw new Error('Cannot bind a destroyed game execution controller.');
+    }
+    const events = scene.sys.events;
+    let disposed = false;
+    let sceneEnded = false;
+    let reportedSimulation = false;
+    let reportedAudio = false;
+    let applying = false;
+    let dirty = false;
+    let ownedPause = false;
+    let ownedVisibility = false;
+    let ownedAudio = false;
+    let inputBlocked = false;
+    const ownedInput = new Set();
+    let unsubscribe = () => { };
+    function report(error) {
+        try {
+            const result = onError?.(error);
+            if (result !== undefined) {
+                void Promise.resolve(result).catch(() => { });
+            }
+        }
+        catch {
+            // Diagnostics cannot interrupt teardown.
+        }
+    }
+    function attempt(callback) {
+        try {
+            const result = callback();
+            if (result !== undefined) {
+                void Promise.resolve(result).catch(report);
+            }
+        }
+        catch (error) {
+            report(error);
+        }
+    }
+    let disposing = false;
+    function restoreAudio() {
+        if (ownedAudio && audio !== undefined) {
+            // A throwing setter leaves cleanup ownership pending for an explicit retry.
+            audio.setMuted(false);
+            ownedAudio = false;
+        }
+    }
+    function restore(resumeScene) {
+        const shouldResume = resumeScene && ownedPause;
+        ownedPause = false;
+        for (const plugin of ownedInput) {
+            attempt(() => {
+                plugin.enabled = true;
+            });
+        }
+        ownedInput.clear();
+        if (resumeScene && !sceneEnded && ownedVisibility && (scene.sys.isActive() || scene.sys.isPaused())) {
+            attempt(() => {
+                scene.sys.setVisible(true);
+            });
+        }
+        ownedVisibility = false;
+        attempt(restoreAudio);
+        // Resume last: its listeners may synchronously restart the scene and install a new binding.
+        if (shouldResume && !sceneEnded) {
+            attempt(() => {
+                if (controller.getSnapshot().status === 'active' && scene.sys.isPaused()) {
+                    scene.sys.resume();
+                }
+            });
+        }
+    }
+    function dispose(mode = 'restore') {
+        if (disposing) {
+            return;
+        }
+        disposing = true;
+        try {
+            if (disposed) {
+                // Retry only unresolved sink cleanup, never scene controls or terminal teardown.
+                if (mode === 'restore' && ownedAudio) {
+                    attempt(() => {
+                        if (controller.getSnapshot().status === 'active') {
+                            restoreAudio();
+                        }
+                    });
+                }
+                return;
+            }
+            disposed = true;
+            attempt(unsubscribe);
+            // Keep shutdown observation installed while restoration calls into consumer/engine code.
+            if (mode !== 'terminal') {
+                attempt(() => {
+                    if (controller.getSnapshot().status === 'active') {
+                        restore(mode === 'restore');
+                    }
+                });
+            }
+            for (const event of ['shutdown', 'destroy']) {
+                attempt(() => {
+                    events.off(event, onShutdown);
+                });
+            }
+            attempt(() => {
+                events.off('sleep', onSleep);
+            });
+            attempt(() => {
+                events.off('wake', onWake);
+            });
+            attempt(() => {
+                events.off('pause', onPause);
+            });
+            attempt(() => {
+                events.off('resume', onResume);
+            });
+            attempt(() => {
+                events.off('create', apply);
+            });
+            attempt(() => uiScope?.dispose());
+            ownedInput.clear();
+        }
+        finally {
+            disposing = false;
+        }
+    }
+    function onShutdown() {
+        sceneEnded = true;
+        dispose('shutdown');
+    }
+    function onPause() {
+        if (!disposed && !applying) {
+            ownedPause = false;
+        }
+    }
+    function onResume() {
+        if (!disposed && !applying) {
+            ownedPause = false;
+            apply();
+        }
+    }
+    function onSleep() {
+        // External sleep owns activity/visibility until an external wake. Never wake it ourselves.
+        ownedPause = false;
+        ownedVisibility = false;
+    }
+    function onWake() {
+        if (controller.getSnapshot().blocked['gameplay-input']) {
+            inputBlocked = false;
+        }
+        apply();
+    }
+    function apply() {
+        dirty = true;
+        if (disposed || applying) {
+            return;
+        }
+        applying = true;
+        try {
+            while (dirty && !disposed) {
+                dirty = false;
+                const snapshot = controller.getSnapshot();
+                if (snapshot.status === 'destroyed') {
+                    // Terminal runtime teardown must not request gameplay resume or unmute.
+                    dispose('terminal');
+                    break;
+                }
+                const blocked = snapshot.blocked;
+                const simulationUnsupported = blocked.simulation && !blocked['gameplay-input'];
+                const audioUnsupported = blocked.audio && audio === undefined;
+                const notifySimulation = simulationUnsupported && !reportedSimulation;
+                const notifyAudio = audioUnsupported && !reportedAudio;
+                reportedSimulation = simulationUnsupported;
+                reportedAudio = audioUnsupported;
+                if (notifySimulation) {
+                    attempt(() => onUnsupportedState(snapshot, 'simulation-requires-input-block'));
+                }
+                if (notifyAudio) {
+                    attempt(() => onUnsupportedState(snapshot, 'audio-sink-missing'));
+                }
+                if (simulationUnsupported) {
+                    continue;
+                }
+                if (audio !== undefined) {
+                    attempt(() => {
+                        if (blocked.audio && !audio.getMuted()) {
+                            ownedAudio = true;
+                            audio.setMuted(true);
+                        }
+                        else if (!blocked.audio && ownedAudio) {
+                            restoreAudio();
+                        }
+                    });
+                }
+                if (disposed) {
+                    break;
+                }
+                if (controller.getSnapshot().version !== snapshot.version) {
+                    dirty = true;
+                    continue;
+                }
+                // Stopped, destroyed, and sleeping scenes belong to their external lifecycle owner.
+                if (!scene.sys.isActive() && !scene.sys.isPaused()) {
+                    continue;
+                }
+                if (blocked['gameplay-input'] && !inputBlocked) {
+                    inputBlocked = true;
+                    for (const plugin of [scene.input, scene.input.keyboard, scene.input.gamepad]) {
+                        if (plugin !== null && plugin !== undefined && plugin.enabled) {
+                            ownedInput.add(plugin);
+                            attempt(() => {
+                                plugin.enabled = false;
+                            });
+                        }
+                    }
+                    attempt(resetInput);
+                    if (disposed) {
+                        break;
+                    }
+                    if (controller.getSnapshot().version !== snapshot.version) {
+                        dirty = true;
+                        continue;
+                    }
+                }
+                else if (!blocked['gameplay-input'] && inputBlocked) {
+                    inputBlocked = false;
+                    for (const plugin of ownedInput) {
+                        attempt(() => {
+                            plugin.enabled = true;
+                        });
+                    }
+                    ownedInput.clear();
+                }
+                if (blocked.rendering && scene.sys.isVisible()) {
+                    ownedVisibility = true;
+                    scene.sys.setVisible(false);
+                }
+                else if (!blocked.rendering && ownedVisibility) {
+                    ownedVisibility = false;
+                    scene.sys.setVisible(true);
+                }
+                if (blocked.simulation && scene.sys.isActive()) {
+                    ownedPause = true;
+                    scene.sys.pause();
+                }
+                else if (!blocked.simulation && ownedPause) {
+                    ownedPause = false;
+                    if (scene.sys.isPaused()) {
+                        scene.sys.resume();
+                    }
+                }
+            }
+        }
+        catch (error) {
+            report(error);
+        }
+        finally {
+            applying = false;
+        }
+    }
+    try {
+        for (const event of ['shutdown', 'destroy']) {
+            events.on(event, onShutdown);
+        }
+        events.on('sleep', onSleep);
+        events.on('wake', onWake);
+        events.on('pause', onPause);
+        events.on('resume', onResume);
+        // SceneManager sets RUNNING after scene.create() returns; apply before its first update.
+        events.on('create', apply);
+        unsubscribe = controller.subscribe(apply);
+        apply();
+    }
+    catch (error) {
+        dispose('shutdown');
+        throw error;
+    }
+    return Object.freeze({ dispose: () => dispose() });
+}

package/dist/platform/index.d.ts

@@ -0,0 +1,25 @@
+import type { ExecutionChannel, GameExecutionController } from '../index.js';
+import { type ObserverErrorHandler } from '../observers.js';
+/** Compatible with PlatformGateway.lifecycle without importing a platform SDK. */
+export interface GameLifecycleSource {
+  onPause(callback: () => void): () => void;
+  onResume(callback: () => void): () => void;
+}
+export type GameLifecycleState = 'active' | 'inactive' | 'unknown';
+export type LifecycleInitialization = {
+  readonly initialState: GameLifecycleState;
+  readonly readState?: never;
+} | {
+  readonly readState: () => GameLifecycleState;
+  readonly initialState?: never;
+};
+export interface GameLifecycleBinding {
+  dispose(): void;
+}
+export declare function bindGameLifecycle(input: LifecycleInitialization & {
+  readonly controller: GameExecutionController;
+  readonly source: GameLifecycleSource;
+  readonly reason?: string;
+  readonly channels?: readonly ExecutionChannel[];
+  readonly onError?: ObserverErrorHandler;
+}): GameLifecycleBinding;

package/dist/platform/index.js

@@ -0,0 +1,120 @@
+import { executionChannels } from '../channels.js';
+import { observe } from '../observers.js';
+export function bindGameLifecycle(input) {
+    const { controller, source, onError } = input;
+    const reason = input.reason ?? 'lifecycle';
+    const channels = [...(input.channels ?? executionChannels)];
+    if (typeof reason !== 'string' || reason.trim().length === 0 || channels.length === 0) {
+        throw new TypeError('Lifecycle reason and channels must be non-empty.');
+    }
+    if (channels.some((channel) => !executionChannels.includes(channel))) {
+        throw new TypeError('Unknown lifecycle execution channel.');
+    }
+    const readState = input.readState;
+    let state = 'unknown';
+    if (readState === undefined) {
+        state = validateState(input.initialState);
+    }
+    else if (typeof readState !== 'function') {
+        throw new TypeError('Lifecycle readState must be a function.');
+    }
+    let disposed = false;
+    let initializing = true;
+    let applying = false;
+    let dirty = false;
+    let eventsSeen = 0;
+    let block;
+    const unsubscribes = [];
+    function dispose() {
+        if (disposed) {
+            return;
+        }
+        disposed = true;
+        for (const unsubscribe of unsubscribes.splice(0)) {
+            observe(unsubscribe, onError);
+        }
+        const owned = block;
+        block = undefined;
+        owned?.release();
+    }
+    function reconcile() {
+        dirty = true;
+        if (disposed || initializing || applying) {
+            return;
+        }
+        applying = true;
+        try {
+            while (dirty && !disposed) {
+                dirty = false;
+                if (controller.getSnapshot().status === 'destroyed') {
+                    dispose();
+                    break;
+                }
+                if (state !== 'active' && block === undefined) {
+                    const acquired = controller.acquireBlock({ reason, channels });
+                    if (disposed) {
+                        acquired.release();
+                    }
+                    else {
+                        block = acquired;
+                    }
+                }
+                else if (state === 'active' && block !== undefined) {
+                    const owned = block;
+                    block = undefined;
+                    owned.release();
+                }
+            }
+        }
+        finally {
+            applying = false;
+        }
+    }
+    function receive(next) {
+        if (!disposed) {
+            eventsSeen += 1;
+            state = next;
+            reconcile();
+        }
+    }
+    function own(unsubscribe) {
+        if (disposed) {
+            observe(unsubscribe, onError);
+        }
+        else {
+            unsubscribes.push(unsubscribe);
+        }
+    }
+    try {
+        own(controller.subscribe((snapshot) => {
+            if (snapshot.status === 'destroyed') {
+                dispose();
+            }
+        }));
+        own(source.onPause(() => receive('inactive')));
+        if (!disposed) {
+            own(source.onResume(() => receive('active')));
+        }
+        if (!disposed && readState !== undefined) {
+            const beforeRead = eventsSeen;
+            const initial = validateState(readState());
+            // A synchronously observed event during the read is newer than its return value.
+            if (eventsSeen === beforeRead) {
+                state = initial;
+            }
+        }
+        initializing = false;
+        reconcile();
+    }
+    catch (error) {
+        dispose();
+        throw error;
+    }
+    return Object.freeze({ dispose });
+}
+function validateState(state) {
+    if (state !== 'active' && state !== 'inactive' && state !== 'unknown') {
+        throw new TypeError('Provide an explicit active, inactive, or unknown lifecycle state.');
+    }
+    return state;
+}

package/dist/ui/index.d.ts

@@ -0,0 +1,33 @@
+import { type ObserverErrorHandler } from '../observers.js';
+export type UiListener<T> = (value: T) => void | Promise<void>;
+export type UiCleanup = () => void | Promise<void>;
+export interface GameUiScope<TSnapshot, TCommand, TEvent> {
+  isDisposed(): boolean;
+  /** Register owned cleanup; the returned function releases it once, early if needed. */
+  own(cleanup: UiCleanup): () => void;
+  subscribeSnapshot(listener: UiListener<TSnapshot>): () => void;
+  subscribeSelector<TSelected>(selector: (snapshot: TSnapshot) => TSelected, listener: UiListener<TSelected>, equality?: (left: TSelected, right: TSelected) => boolean): () => void;
+  onCommand(listener: UiListener<TCommand>): () => void;
+  onEvent(listener: UiListener<TEvent>): () => void;
+  /** False after scope disposal, including disposal through bridge destruction. */
+  setSnapshot(snapshot: TSnapshot): boolean;
+  emit(event: TEvent): boolean;
+  dispatch(command: TCommand): boolean;
+  dispose(): void;
+}
+export interface GameUiBridge<TSnapshot, TCommand, TEvent> {
+  getSnapshot(): TSnapshot;
+  setSnapshot(snapshot: TSnapshot): void;
+  subscribeSnapshot(listener: UiListener<TSnapshot>): () => void;
+  subscribeSelector<TSelected>(selector: (snapshot: TSnapshot) => TSelected, listener: UiListener<TSelected>, equality?: (left: TSelected, right: TSelected) => boolean): () => void;
+  dispatch(command: TCommand): void;
+  onCommand(listener: UiListener<TCommand>): () => void;
+  emit(event: TEvent): void;
+  onEvent(listener: UiListener<TEvent>): () => void;
+  createScope(): GameUiScope<TSnapshot, TCommand, TEvent>;
+  destroy(): void;
+}
+export declare function createGameUiBridge<TSnapshot, TCommand, TEvent = never>(input: {
+  readonly initialSnapshot: TSnapshot;
+  readonly onListenerError?: ObserverErrorHandler;
+}): GameUiBridge<TSnapshot, TCommand, TEvent>;

package/dist/ui/index.js

@@ -0,0 +1,197 @@
+import { observe } from '../observers.js';
+export function createGameUiBridge(input) {
+    let snapshot = input.initialSnapshot;
+    const onError = input.onListenerError;
+    const snapshots = new Set();
+    const commands = new Set();
+    const events = new Set();
+    const scopes = new Set();
+    const queue = [];
+    let destroyed = false;
+    let delivering = false;
+    function assertActive() {
+        if (destroyed) {
+            throw new Error('Game UI bridge is destroyed.');
+        }
+    }
+    function subscribe(subscriptions, listener) {
+        assertActive();
+        if (typeof listener !== 'function') {
+            throw new TypeError('UI listener must be a function.');
+        }
+        const subscription = { listener, active: true };
+        subscriptions.add(subscription);
+        return () => {
+            subscription.active = false;
+            subscriptions.delete(subscription);
+        };
+    }
+    function publish(subscriptions, value) {
+        const recipients = [...subscriptions];
+        queue.push(() => {
+            for (const subscription of recipients) {
+                if (!destroyed && subscription.active) {
+                    observe(() => subscription.listener(value), onError);
+                }
+            }
+        });
+        if (delivering) {
+            return;
+        }
+        delivering = true;
+        try {
+            for (let cursor = 0; !destroyed && cursor < queue.length; cursor += 1) {
+                queue[cursor]?.();
+            }
+        }
+        finally {
+            queue.length = 0;
+            delivering = false;
+        }
+    }
+    const bridge = {
+        getSnapshot: () => snapshot,
+        setSnapshot(next) {
+            assertActive();
+            if (!Object.is(snapshot, next)) {
+                snapshot = next;
+                publish(snapshots, next);
+            }
+        },
+        subscribeSnapshot: (listener) => subscribe(snapshots, listener),
+        subscribeSelector(selector, listener, equality = Object.is) {
+            assertActive();
+            if (typeof selector !== 'function'
+                || typeof listener !== 'function'
+                || typeof equality !== 'function') {
+                throw new TypeError('Selector, listener and equality must be functions.');
+            }
+            // Selectors and equality functions must be pure. An initial failure registers nothing.
+            let selected = selector(snapshot);
+            return subscribe(snapshots, (next) => {
+                const nextSelected = selector(next);
+                if (!equality(selected, nextSelected)) {
+                    selected = nextSelected;
+                    return listener(nextSelected);
+                }
+            });
+        },
+        dispatch(command) {
+            assertActive();
+            publish(commands, command);
+        },
+        onCommand: (listener) => subscribe(commands, listener),
+        emit(event) {
+            assertActive();
+            publish(events, event);
+        },
+        onEvent: (listener) => subscribe(events, listener),
+        createScope() {
+            assertActive();
+            const cleanups = new Set();
+            let disposed = false;
+            function assertScopeActive() {
+                assertActive();
+                if (disposed) {
+                    throw new Error('Game UI scope is disposed.');
+                }
+            }
+            function register(registerListener) {
+                assertScopeActive();
+                const unsubscribe = registerListener();
+                // Selector callbacks can dispose the scope during registration.
+                if (disposed || destroyed) {
+                    unsubscribe();
+                    return () => { };
+                }
+                return scope.own(unsubscribe);
+            }
+            function guarded(listener) {
+                if (typeof listener !== 'function') {
+                    throw new TypeError('UI listener must be a function.');
+                }
+                return (value) => {
+                    if (!disposed && !destroyed) {
+                        return listener(value);
+                    }
+                };
+            }
+            const scope = {
+                isDisposed: () => disposed,
+                own(cleanup) {
+                    if (typeof cleanup !== 'function') {
+                        throw new TypeError('Scope cleanup must be a function.');
+                    }
+                    let active = true;
+                    const release = () => {
+                        if (active) {
+                            active = false;
+                            cleanups.delete(release);
+                            observe(cleanup, onError);
+                        }
+                    };
+                    if (disposed || destroyed) {
+                        release();
+                    }
+                    else {
+                        cleanups.add(release);
+                    }
+                    return release;
+                },
+                subscribeSnapshot: (listener) => register(() => bridge.subscribeSnapshot(guarded(listener))),
+                subscribeSelector: (selector, listener, equality) => register(() => bridge.subscribeSelector(selector, guarded(listener), equality)),
+                onCommand: (listener) => register(() => bridge.onCommand(guarded(listener))),
+                onEvent: (listener) => register(() => bridge.onEvent(guarded(listener))),
+                setSnapshot(next) {
+                    if (disposed || destroyed) {
+                        return false;
+                    }
+                    bridge.setSnapshot(next);
+                    return true;
+                },
+                emit(event) {
+                    if (disposed || destroyed) {
+                        return false;
+                    }
+                    bridge.emit(event);
+                    return true;
+                },
+                dispatch(command) {
+                    if (disposed || destroyed) {
+                        return false;
+                    }
+                    bridge.dispatch(command);
+                    return true;
+                },
+                dispose() {
+                    if (disposed) {
+                        return;
+                    }
+                    disposed = true;
+                    scopes.delete(scope);
+                    // Revoke all scope callbacks before cleanup can reenter the bridge.
+                    const owned = [...cleanups];
+                    for (const cleanup of owned) {
+                        cleanup();
+                    }
+                },
+            };
+            scopes.add(scope);
+            return Object.freeze(scope);
+        },
+        destroy() {
+            if (destroyed) {
+                return;
+            }
+            destroyed = true;
+            for (const scope of [...scopes]) {
+                scope.dispose();
+            }
+            snapshots.clear();
+            commands.clear();
+            events.clear();
+            queue.length = 0;
+        },
+    };
+    return Object.freeze(bridge);
+}