@energy8platform/game-engine 0.17.0 → 0.19.0

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import * as _energy8platform_platform_core_shell from '@energy8platform/platform-core/shell';
 import { Container, ApplicationOptions, Application, Texture, AnimatedSprite, Spritesheet, TextStyle, ColorSource } from 'pixi.js';
 import { CasinoGameSDK, InitData, GameConfigData, SessionData } from '@energy8platform/game-sdk';
 export { AnywhereWinData, BalanceData, BridgeDestroyedError, BridgeNotReadyError, GameConfigData, InitData, PaylineData, PlayParams, PlayResultData, SDKError, SessionData, SymbolData, TimeoutError, WinLineData } from '@energy8platform/game-sdk';
@@ -60,6 +61,8 @@ interface GameApplicationConfig {
     pixi?: Partial<ApplicationOptions>;
     /** Enable debug overlay (FPS, draw calls) */
     debug?: boolean;
+    /** When set, GameApplication mounts the branded game shell after the SDK handshake. */
+    shell?: _energy8platform_platform_core_shell.ShellConfig | false;
 }
 interface SceneConstructor {
     new (): IScene;
@@ -339,6 +342,7 @@ declare class AudioManager {
     private _persist;
     private _storageKey;
     private _categories;
+    private _masterGain;
     private _currentMusic;
     private _unlocked;
     private _unlockHandler;
@@ -379,6 +383,10 @@ declare class AudioManager {
      * Stop all sounds.
      */
     stopAll(): void;
+    /** Global gain (0..1) folded into every category's effective volume. Driven by the shell's
+     *  'master' settingChange. Does not affect the persisted per-category volumes. */
+    setMasterVolume(volume: number): void;
+    getMasterVolume(): number;
     /**
      * Set volume for a category.
      */
@@ -581,6 +589,7 @@ declare class ViewportManager extends EventEmitter<ViewportEvents> {
     private _app;
     private _container;
     private _config;
+    private _target;
     private _resizeObserver;
     private _currentOrientation;
     private _currentWidth;
@@ -588,7 +597,7 @@ declare class ViewportManager extends EventEmitter<ViewportEvents> {
     private _currentScale;
     private _destroyed;
     private _resizeTimeout;
-    constructor(app: Application, container: HTMLElement, config: ViewportConfig);
+    constructor(app: Application, container: HTMLElement, config: ViewportConfig, target?: Container);
     /** Current canvas width in game units */
     get width(): number;
     /** Current canvas height in game units */
@@ -689,6 +698,12 @@ declare class GameApplication extends EventEmitter<GameEngineEvents> {
     input: InputManager;
     /** Viewport manager */
     viewport: ViewportManager;
+    /** Scaled world root (holds scenes). Transformed by the ViewportManager to fit the design
+     *  resolution; lives below the UI layer on app.stage. */
+    worldRoot: Container;
+    /** Unscaled, screen-space UI layer. Sits above {@link worldRoot} and is NOT touched by the
+     *  viewport transform — children fill the real screen (e.g. the host's shell + overlay). */
+    uiLayer: Container;
     /** SDK instance (null in offline mode) */
     sdk: CasinoGameSDK | null;
     /** FPS overlay instance (only when debug: true) */
@@ -697,6 +712,8 @@ declare class GameApplication extends EventEmitter<GameEngineEvents> {
     initData: InitData | null;
     /** Platform session (SDK + optional DevBridge). null until start() runs. */
     platformSession: PlatformSession | null;
+    /** Branded game shell (only when config.shell is set). */
+    shell?: _energy8platform_platform_core_shell.GameShell;
     /** Configuration */
     readonly config: GameApplicationConfig;
     private _running;
@@ -723,7 +740,7 @@ declare class GameApplication extends EventEmitter<GameEngineEvents> {
     /**
      * Destroy the engine and free all resources.
      */
-    destroy(): void;
+    destroy(): Promise<void>;
     private resolveContainer;
     private initPixi;
     private initSDK;

package/dist/index.esm.js

@@ -734,6 +734,7 @@ class AudioManager {
     _persist;
     _storageKey;
     _categories;
+    _masterGain = 1.0;
     _currentMusic = null;
     _unlocked = false;
     _unlockHandler = null;
@@ -793,7 +794,7 @@ class AudioManager {
         if (this._globalMuted || this._categories[category].muted)
             return;
         const { sound } = this._soundModule;
-        const vol = (options?.volume ?? 1) * this._categories[category].volume;
+        const vol = (options?.volume ?? 1) * this._categories[category].volume * this._masterGain;
         try {
             sound.play(alias, {
                 volume: vol,
@@ -822,7 +823,7 @@ class AudioManager {
             if (this._globalMuted || this._categories.music.muted)
                 return;
             // Fade out the previous track
-            this.fadeVolume(prevAlias, this._categories.music.volume, 0, fadeDuration, () => {
+            this.fadeVolume(prevAlias, this._categories.music.volume * this._masterGain, 0, fadeDuration, () => {
                 try {
                     sound.stop(prevAlias);
                 }
@@ -834,7 +835,7 @@ class AudioManager {
                     volume: 0,
                     loop: true,
                 });
-                this.fadeVolume(alias, 0, this._categories.music.volume, fadeDuration);
+                this.fadeVolume(alias, 0, this._categories.music.volume * this._masterGain, fadeDuration);
             }
             catch (e) {
                 console.warn(`[AudioManager] Failed to play music "${alias}":`, e);
@@ -853,7 +854,7 @@ class AudioManager {
                 return;
             try {
                 sound.play(alias, {
-                    volume: this._categories.music.volume,
+                    volume: this._categories.music.volume * this._masterGain,
                     loop: true,
                 });
             }
@@ -887,6 +888,15 @@ class AudioManager {
         sound.stopAll();
         this._currentMusic = null;
     }
+    /** Global gain (0..1) folded into every category's effective volume. Driven by the shell's
+     *  'master' settingChange. Does not affect the persisted per-category volumes. */
+    setMasterVolume(volume) {
+        this._masterGain = Math.max(0, Math.min(1, volume));
+        this.applyVolumes();
+    }
+    getMasterVolume() {
+        return this._masterGain;
+    }
     /**
      * Set volume for a category.
      */
@@ -1032,7 +1042,7 @@ class AudioManager {
         const { sound } = this._soundModule;
         // Global mute is owned by sound.muteAll()/unmuteAll() (context.muted),
         // not by volumeAll — mixing both leaves mute un-undoable after reload.
-        sound.volumeAll = 1;
+        sound.volumeAll = this._masterGain; // master multiplies the global bus
     }
     setupMobileUnlock() {
         if (this._unlocked)
@@ -1300,6 +1310,7 @@ class ViewportManager extends EventEmitter {
     _app;
     _container;
     _config;
+    _target;
     _resizeObserver = null;
     _currentOrientation = Orientation.LANDSCAPE;
     _currentWidth = 0;
@@ -1307,11 +1318,15 @@ class ViewportManager extends EventEmitter {
     _currentScale = 1;
     _destroyed = false;
     _resizeTimeout = null;
-    constructor(app, container, config) {
+    constructor(app, container, config, target) {
         super();
         this._app = app;
         this._container = container;
         this._config = config;
+        // The container this manager scales/offsets. Defaults to app.stage for backward
+        // compatibility; the engine passes a dedicated scaled world root so app.stage stays
+        // identity (screen space) for unscaled UI layers.
+        this._target = target ?? app.stage;
         this.setupObserver();
     }
     /** Current canvas width in game units */
@@ -1400,19 +1415,19 @@ class ViewportManager extends EventEmitter {
         const stageScale = scaleMode === ScaleMode.STRETCH
             ? Math.min(containerWidth / designWidth, containerHeight / designHeight)
             : scale;
-        this._app.stage.scale.set(stageScale);
+        this._target.scale.set(stageScale);
         // Center the stage for FIT mode
         if (scaleMode === ScaleMode.FIT) {
-            this._app.stage.x = Math.round((containerWidth - designWidth * stageScale) / 2);
-            this._app.stage.y = Math.round((containerHeight - designHeight * stageScale) / 2);
+            this._target.x = Math.round((containerWidth - designWidth * stageScale) / 2);
+            this._target.y = Math.round((containerHeight - designHeight * stageScale) / 2);
         }
         else if (scaleMode === ScaleMode.FILL) {
-            this._app.stage.x = Math.round((containerWidth - gameWidth * stageScale) / 2);
-            this._app.stage.y = Math.round((containerHeight - gameHeight * stageScale) / 2);
+            this._target.x = Math.round((containerWidth - gameWidth * stageScale) / 2);
+            this._target.y = Math.round((containerHeight - gameHeight * stageScale) / 2);
         }
         else {
-            this._app.stage.x = 0;
-            this._app.stage.y = 0;
+            this._target.x = 0;
+            this._target.y = 0;
         }
         this._currentWidth = gameWidth;
         this._currentHeight = gameHeight;
@@ -1903,6 +1918,12 @@ class GameApplication extends EventEmitter {
     input;
     /** Viewport manager */
     viewport;
+    /** Scaled world root (holds scenes). Transformed by the ViewportManager to fit the design
+     *  resolution; lives below the UI layer on app.stage. */
+    worldRoot;
+    /** Unscaled, screen-space UI layer. Sits above {@link worldRoot} and is NOT touched by the
+     *  viewport transform — children fill the real screen (e.g. the host's shell + overlay). */
+    uiLayer;
     /** SDK instance (null in offline mode) */
     sdk = null;
     /** FPS overlay instance (only when debug: true) */
@@ -1911,6 +1932,8 @@ class GameApplication extends EventEmitter {
     initData = null;
     /** Platform session (SDK + optional DevBridge). null until start() runs. */
     platformSession = null;
+    /** Branded game shell (only when config.shell is set). */
+    shell;
     /** Configuration */
     config;
     // ─── Private state ──────────────────────────────────────
@@ -1972,6 +1995,11 @@ class GameApplication extends EventEmitter {
             await this.initPixi();
             // 4. Initialize SDK (if enabled)
             await this.initSDK();
+            // 4b. Mount the branded game shell after the SDK handshake (optional)
+            if (this.config.shell) {
+                const { createGameShell } = await import('@energy8platform/platform-core/shell');
+                this.shell = createGameShell(this.config.shell);
+            }
             // 5. Merge design dimensions from SDK config
             this.applySDKConfig();
             // 6. Initialize sub-systems
@@ -1995,11 +2023,16 @@ class GameApplication extends EventEmitter {
     /**
      * Destroy the engine and free all resources.
      */
-    destroy() {
+    async destroy() {
         if (this._destroyed)
             return;
         this._destroyed = true;
         this._running = false;
+        if (this.shell) {
+            const { removeGameShell } = await import('@energy8platform/platform-core/shell');
+            await removeGameShell();
+            this.shell = undefined;
+        }
         this.scenes?.destroy();
         this.input?.destroy();
         this.audio?.destroy();
@@ -2070,20 +2103,27 @@ class GameApplication extends EventEmitter {
         this.audio = new AudioManager(this.config.audio);
         // Input Manager
         this.input = new InputManager(this.app.canvas);
-        // Viewport Manager
+        // Stage layers: a scaled world root (scenes, transformed to design resolution by the
+        // viewport) below an unscaled UI layer (screen space). app.stage itself stays identity.
+        this.worldRoot = new Container();
+        this.worldRoot.label = 'world';
+        this.uiLayer = new Container();
+        this.uiLayer.label = 'ui';
+        this.app.stage.addChild(this.worldRoot, this.uiLayer);
+        // Viewport Manager — scales worldRoot (NOT app.stage), so the UI layer is unscaled.
         this.viewport = new ViewportManager(this.app, this._container, {
             designWidth: this.config.designWidth,
             designHeight: this.config.designHeight,
             scaleMode: this.config.scaleMode,
             orientation: this.config.orientation,
-        });
-        // Wire SceneManager to the PixiJS stage
-        this.scenes.setRoot(this.app.stage);
+        }, this.worldRoot);
+        // Wire SceneManager to the scaled world root
+        this.scenes.setRoot(this.worldRoot);
         this.scenes.setApp(this);
         // Wire viewport resize → scene manager + input manager
         this.viewport.on('resize', ({ width, height, scale }) => {
             this.scenes.resize(width, height);
-            this.input.setViewportTransform(scale, this.app.stage.x, this.app.stage.y);
+            this.input.setViewportTransform(scale, this.worldRoot.x, this.worldRoot.y);
             this.emit('resize', { width, height });
         });
         this.viewport.on('orientationChange', (orientation) => {