@mpgd/game-runtime 0.3.0 → 0.5.0

package/dist/ads/index.d.ts

@@ -1,4 +1,4 @@
-import type { PlatformEvidenceEnvelope, PlatformGateway, PurchaseResult } from '@mpgd/platform';
+import type { PlatformEvidenceEnvelope, PlatformGateway, PlatformPurchasePresentationEvent, PurchaseResult } from '@mpgd/platform';
 import type { GameServicesRewardedAdResult } from '@mpgd/game-services/operations';
 import { type AdPlacementInput, type AdProvider, type AdShowInput, type AdShowResult } from '@mpgd/platform/ads';
 import { type ObserverErrorHandler } from '../observers.js';
@@ -44,11 +44,7 @@ export declare function createCoordinatedAdProvider(input: {
     readonly result: AdShowResult;
   }) => void | Promise<void>;
 }): CoordinatedAdProvider;
-export interface PurchasePresentationEvent {
-  readonly idempotencyKey: string;
-  readonly sequence: number;
-  readonly state: 'open' | 'closed' | 'not-started' | 'unknown';
-}
+export type PurchasePresentationEvent = PlatformPurchasePresentationEvent;
 export interface CoordinatedPlatformGateway extends PlatformGateway {
   dispose(): void;
 }

package/dist/ads/index.js

@@ -34,6 +34,7 @@ export function createCoordinatedAdProvider(input) {
     const protocol = provider.protocol;
     const protocolVersion = provider.protocolVersion;
     const rewardSignal = provider.rewardSignal;
+    const presentationAudio = provider.presentationAudio;
     const capacity = input.maxRememberedInvocations ?? 1024;
     if (!Number.isSafeInteger(capacity) || capacity < 1 || capacity > 10000) {
         throw new RangeError('maxRememberedInvocations must be from 1 to 10000.');
@@ -372,7 +373,7 @@ export function createCoordinatedAdProvider(input) {
                     throw new PresentationExecutionError('disposed');
                 }
                 try {
-                    flight.lease = input.presentation.acquire({ kind: request.format, invocationId: request.invocationId });
+                    flight.lease = input.presentation.acquire({ kind: request.format, invocationId: request.invocationId, audioStart: presentationAudio ?? 'requested' });
                 }
                 catch (error) {
                     if (error instanceof PresentationExecutionError && error.code === 'busy') {
@@ -419,6 +420,7 @@ export function createCoordinatedAdProvider(input) {
     }
     return Object.freeze({
         id: id, protocol: protocol, protocolVersion: protocolVersion, rewardSignal: rewardSignal,
+        ...(presentationAudio === undefined ? {} : { presentationAudio }),
         getAvailability,
         async preload(supplied) {
             const request = placement(supplied);
@@ -473,7 +475,8 @@ export function createCoordinatedPlatformGateway(input) {
         }
         maybeDetach();
     }
-    const unsubscribe = input.purchasePresentation?.subscribe((event) => {
+    const purchasePresentation = input.purchasePresentation ?? input.gateway.commerce.presentation;
+    const unsubscribe = purchasePresentation?.subscribe((event) => {
         observe(() => {
             const flight = purchases.get(event.idempotencyKey);
             if (flight === undefined || !flight.called || flight.closed) {

package/dist/game/index.d.ts

@@ -15,12 +15,21 @@ export interface GameServicePorts {
     reconcile(): Promise<unknown>;
   };
 }
+/** One scene's logical play state; execution blocks remain owned by the game runtime. */
+export interface GameGameplayScope {
+  setActive(active: boolean): void;
+  dispose(): void;
+}
 export interface GamePlatformRuntime<T extends PlatformGateway = PlatformGateway, S extends GameServicePorts = GameServicePorts> {
   readonly gateway: T;
   readonly execution: GameExecutionController;
   readonly presentation: FullScreenPresentationScope;
   readonly services: S;
   readonly actions?: GameActionCoordinator;
+  createGameplayScope(): GameGameplayScope;
+  setLoadingProgress(progress: number): void;
+  /** Complete host loading before opening a play scene. Rejected starts remain blocked. */
+  completeLoading(): Promise<void>;
   /** Reconcile existing journal entries only; this method never opens platform UI. */
   reconcile(): Promise<void>;
   /** Game teardown; native observers and application-owned late recovery may continue. */
@@ -38,4 +47,6 @@ export declare function createGamePlatformRuntime<T extends PlatformGateway, S e
     subscribe(listener: (event: PurchasePresentationEvent) => void): () => void;
   };
   readonly onObserverError?: ObserverErrorHandler;
+  /** Must complete synchronously; asynchronous uploads belong at earlier checkpoints. */
+  readonly onExit?: () => void;
 }): GamePlatformRuntime<T, S>;

package/dist/game/index.js

@@ -1,4 +1,4 @@
-import { createGameExecutionController } from '../index.js';
+import { createGameExecutionController, } from '../index.js';
 import { bindGameLifecycle } from '../platform/index.js';
 import { createFullScreenPresentationScope, } from '../presentation/index.js';
 import { createAdClaimEvidenceRecoveryObserver, createCoordinatedPlatformGateway, } from '../ads/index.js';
@@ -39,12 +39,123 @@ export function createGamePlatformRuntime(input) {
     let actions;
     let unsubscribeResume;
     let disposed = false;
+    let unsubscribeExit;
+    let startupBlock = input.gateway.gameLoading === undefined
+        ? undefined
+        : execution.acquireBlock({
+            reason: 'game-runtime:loading',
+            channels: ['simulation', 'gameplay-input', 'audio'],
+        });
+    let loadingCompletion;
+    const setLoadingProgress = (progress) => {
+        if (!disposed && loadingCompletion === undefined) {
+            observe(() => gateway.gameLoading?.setProgress(Math.max(0, Math.min(100, Number(progress) || 0))), input.onObserverError);
+        }
+    };
+    const completeLoading = () => {
+        if (disposed) {
+            return Promise.reject(new Error('Game runtime is disposed.'));
+        }
+        if (loadingCompletion !== undefined) {
+            return loadingCompletion;
+        }
+        const attempt = Promise.resolve().then(async () => {
+            if (disposed) {
+                throw new Error('Game runtime is disposed.');
+            }
+            gateway.gameLoading?.setProgress(100);
+            await gateway.gameLoading?.complete();
+            if (disposed) {
+                throw new Error('Game runtime was disposed during loading.');
+            }
+            const owned = startupBlock;
+            startupBlock = undefined;
+            owned?.release();
+        });
+        loadingCompletion = attempt;
+        void attempt.catch(() => {
+            if (loadingCompletion === attempt) {
+                loadingCompletion = undefined;
+            }
+        });
+        return attempt;
+    };
+    let hostAudio;
+    let unsubscribeHostAudio;
+    const gameplayScopes = new Map();
+    const lifecycleReason = 'game-runtime:lifecycle';
+    let gameplayActive = false;
+    let hasPlayed = false;
+    let loading = true;
+    let unsubscribeActivity;
+    const updateActivity = () => {
+        const snapshot = execution.getSnapshot();
+        const activity = gateway.gameActivity;
+        const playable = [...gameplayScopes.values()].some(Boolean);
+        const blocked = snapshot.blocks.some((block) => block.channels.includes('simulation')
+            && !(activity?.handlesFocusChanges === true && hasPlayed && block.reason === lifecycleReason));
+        const next = !disposed && snapshot.status === 'active' && playable && !blocked;
+        if (next && loading) {
+            observe(() => {
+                activity?.setLoading(false);
+                loading = false;
+            }, input.onObserverError);
+            if (loading) {
+                return;
+            }
+        }
+        if (next !== gameplayActive) {
+            observe(() => {
+                activity?.setGameplayActive(next);
+                gameplayActive = next;
+                if (next) {
+                    hasPlayed = true;
+                }
+            }, input.onObserverError);
+        }
+    };
+    const createGameplayScope = () => {
+        const owner = {};
+        let ended = disposed;
+        if (!ended) {
+            gameplayScopes.set(owner, false);
+        }
+        return Object.freeze({
+            setActive(active) {
+                if (!ended && !disposed) {
+                    gameplayScopes.set(owner, active);
+                    updateActivity();
+                }
+            },
+            dispose() {
+                if (!ended) {
+                    ended = true;
+                    gameplayScopes.delete(owner);
+                    updateActivity();
+                }
+            },
+        });
+    };
     const dispose = () => {
         if (disposed) {
             return;
         }
         disposed = true;
+        updateActivity();
+        if (loading) {
+            observe(() => {
+                gateway.gameActivity?.setLoading(false);
+                loading = false;
+            }, input.onObserverError);
+        }
+        unsubscribeActivity?.();
+        unsubscribeExit?.();
+        gameplayScopes.clear();
         execution.destroy();
+        if (unsubscribeHostAudio !== undefined) {
+            observe(unsubscribeHostAudio, input.onObserverError);
+        }
+        hostAudio?.release();
         actions?.dispose();
         coordinated?.dispose();
         presentation.dispose();
@@ -83,14 +194,46 @@ export function createGamePlatformRuntime(input) {
             });
         }
         lifecycle = bindGameLifecycle({ controller: execution, source: gateway.lifecycle, initialState: input.initialLifecycleState,
+            reason: lifecycleReason,
             ...(input.onObserverError === undefined ? {} : { onError: input.onObserverError }),
         });
         unsubscribeResume = gateway.lifecycle.onResume(() => { observe(reconcile, input.onObserverError); });
+        unsubscribeExit = gateway.lifecycle.onExit?.(() => {
+            observe(() => input.onExit?.(), input.onObserverError);
+            dispose();
+        });
+        if (disposed) {
+            unsubscribeExit?.();
+            throw new Error('Game exited during runtime initialization.');
+        }
+        const settings = gateway.gameSettings;
+        if (settings !== undefined) {
+            const updateMute = (muted) => {
+                if (disposed) {
+                    return;
+                }
+                if (muted && hostAudio === undefined) {
+                    hostAudio = execution.acquireBlock({ reason: 'game-runtime:host-audio', channels: ['audio'] });
+                }
+                else if (!muted && hostAudio !== undefined) {
+                    const owned = hostAudio;
+                    hostAudio = undefined;
+                    owned.release();
+                }
+            };
+            unsubscribeHostAudio = settings.onAudioMuteChange(updateMute);
+            updateMute(settings.getAudioMuted());
+        }
+        observe(() => gateway.gameActivity?.setLoading(true), input.onObserverError);
+        unsubscribeActivity = execution.subscribe(updateActivity);
         return Object.freeze({
             gateway,
             execution,
             presentation,
             services,
+            createGameplayScope,
+            setLoadingProgress,
+            completeLoading,
             ...(actions === undefined ? {} : { actions }),
             reconcile,
             dispose,

package/dist/phaser/index.d.ts

@@ -1,4 +1,5 @@
 import type Phaser from 'phaser';
+import type { GameGameplayScope } from '../game/index.js';
 import type { GameExecutionController, GameExecutionSnapshot } from '../index.js';
 export interface GameplayAudioSink {
   getMuted(): boolean;
@@ -21,6 +22,7 @@ export interface BindPhaserGameSceneInput {
   readonly uiScope?: {
     dispose(): void;
   };
+  readonly gameplayScope?: GameGameplayScope;
   /** Phaser pause also suspends input: simulation-only blocking cannot preserve active input. */
   readonly onUnsupportedState: (snapshot: GameExecutionSnapshot, reason: UnsupportedPhaserExecutionState) => void | Promise<void>;
   readonly onError?: (error: unknown) => void | Promise<void>;

package/dist/phaser/index.js

@@ -23,6 +23,7 @@ export function bindPhaserGameScene(input) {
     let ownedVisibility = false;
     let ownedAudio = false;
     let inputBlocked = false;
+    let externallyInactive = scene.sys.isPaused();
     const ownedInput = new Set();
     let unsubscribe = () => { };
     function report(error) {
@@ -99,6 +100,7 @@ export function bindPhaserGameScene(input) {
             }
             disposed = true;
             attempt(unsubscribe);
+            attempt(() => input.gameplayScope?.dispose());
             // Keep shutdown observation installed while restoration calls into consumer/engine code.
             if (mode !== 'terminal') {
                 attempt(() => {
@@ -141,11 +143,14 @@ export function bindPhaserGameScene(input) {
     function onPause() {
         if (!disposed && !applying) {
             ownedPause = false;
+            externallyInactive = true;
+            attempt(() => input.gameplayScope?.setActive(false));
         }
     }
     function onResume() {
         if (!disposed && !applying) {
             ownedPause = false;
+            externallyInactive = false;
             apply();
         }
     }
@@ -153,8 +158,11 @@ export function bindPhaserGameScene(input) {
         // External sleep owns activity/visibility until an external wake. Never wake it ourselves.
         ownedPause = false;
         ownedVisibility = false;
+        externallyInactive = true;
+        attempt(() => input.gameplayScope?.setActive(false));
     }
     function onWake() {
+        externallyInactive = false;
         if (controller.getSnapshot().blocked['gameplay-input']) {
             inputBlocked = false;
         }
@@ -175,6 +183,7 @@ export function bindPhaserGameScene(input) {
                     dispose('terminal');
                     break;
                 }
+                attempt(() => input.gameplayScope?.setActive(!externallyInactive && (scene.sys.isActive() || scene.sys.isPaused())));
                 const blocked = snapshot.blocked;
                 const simulationUnsupported = blocked.simulation && !blocked['gameplay-input'];
                 const audioUnsupported = blocked.audio && audio === undefined && input.audioOwner !== 'game';

package/dist/presentation/index.d.ts

@@ -23,6 +23,7 @@ export interface FullScreenPresentationScope {
   acquire(input: {
     readonly kind: FullScreenPresentationKind;
     readonly invocationId: string;
+    readonly audioStart?: 'requested' | 'started';
   }): FullScreenPresentationLease;
   getSnapshot(): FullScreenPresentationSnapshot;
   subscribe(listener: UiListener<FullScreenPresentationSnapshot>): () => void;

package/dist/presentation/index.js

@@ -49,8 +49,10 @@ export function createFullScreenPresentationScope(input) {
             }
             const kind = request.kind;
             const invocationId = request.invocationId;
+            const audioStart = request.audioStart ?? 'requested';
             if (!['purchase', 'rewarded', 'interstitial'].includes(kind)
-                || typeof invocationId !== 'string' || invocationId.trim() === '' || invocationId.length > 512) {
+                || typeof invocationId !== 'string' || invocationId.trim() === '' || invocationId.length > 512
+                || (audioStart !== 'requested' && audioStart !== 'started')) {
                 throw new TypeError('Invalid presentation identity.');
             }
             if (isDisposed()) {
@@ -66,7 +68,7 @@ export function createFullScreenPresentationScope(input) {
             owner = owned;
             try {
                 owned.block = input.execution.acquireBlock({
-                    reason: `presentation:${kind}`, channels: ['simulation', 'gameplay-input', 'audio'],
+                    reason: `presentation:${kind}`, channels: audioStart === 'started' ? ['simulation', 'gameplay-input'] : ['simulation', 'gameplay-input', 'audio'],
                 });
             }
             catch (error) {
@@ -75,16 +77,46 @@ export function createFullScreenPresentationScope(input) {
                 }
                 throw error;
             }
+            let acquiringAudio = false;
+            const ensureAudio = () => {
+                if (audioStart !== 'started' || acquiringAudio || owned.audioBlock !== undefined || input.execution.getSnapshot().status === 'destroyed') {
+                    return;
+                }
+                acquiringAudio = true;
+                try {
+                    const block = input.execution.acquireBlock({ reason: `presentation:${kind}:audio`, channels: ['audio'] });
+                    if (owner === owned) {
+                        owned.audioBlock = block;
+                    }
+                    else {
+                        block.release();
+                    }
+                }
+                finally {
+                    acquiringAudio = false;
+                }
+            };
             publish();
             return Object.freeze({
                 markStarted() {
                     if (owner === owned && owned.info.state !== 'open') {
+                        const previousInfo = owned.info;
+                        ensureAudio();
+                        if (owner !== owned || owned.info !== previousInfo) {
+                            return;
+                        }
                         owned.info = Object.freeze({ ...owned.info, state: 'open' });
                         publish();
                     }
                 },
                 markUnknown() {
                     if (owner === owned && owned.info.state !== 'unknown') {
+                        const previousInfo = owned.info;
+                        // Lost native observations quarantine audio as well as execution.
+                        ensureAudio();
+                        if (owner !== owned || owned.info !== previousInfo) {
+                            return;
+                        }
                         owned.info = Object.freeze({ ...owned.info, state: 'unknown' });
                         publish();
                     }
@@ -95,6 +127,7 @@ export function createFullScreenPresentationScope(input) {
                     }
                     owner = undefined;
                     publish();
+                    owned.audioBlock?.release();
                     owned.block?.release();
                 },
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/game-runtime",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Gameplay execution, scoped UI and action coordination with optional Phaser scene bindings.",
   "license": "MIT",
   "keywords": [
@@ -64,8 +64,8 @@
     "@types/node": "^24.0.0"
   },
   "dependencies": {
-    "@mpgd/game-services": "0.18.0",
-    "@mpgd/platform": "0.15.0"
+    "@mpgd/game-services": "0.19.0",
+    "@mpgd/platform": "0.17.0"
   },
   "repository": {
     "type": "git",