@energy8platform/game-engine 0.18.0 → 0.20.0

package/dist/index.cjs.js

@@ -736,6 +736,7 @@ class AudioManager {
     _persist;
     _storageKey;
     _categories;
+    _masterGain = 1.0;
     _currentMusic = null;
     _unlocked = false;
     _unlockHandler = null;
@@ -795,7 +796,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,
@@ -824,7 +825,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);
                 }
@@ -836,7 +837,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);
@@ -855,7 +856,7 @@ class AudioManager {
                 return;
             try {
                 sound.play(alias, {
-                    volume: this._categories.music.volume,
+                    volume: this._categories.music.volume * this._masterGain,
                     loop: true,
                 });
             }
@@ -889,6 +890,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.
      */
@@ -1034,7 +1044,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)
@@ -1302,6 +1312,7 @@ class ViewportManager extends EventEmitter {
     _app;
     _container;
     _config;
+    _target;
     _resizeObserver = null;
     _currentOrientation = exports.Orientation.LANDSCAPE;
     _currentWidth = 0;
@@ -1309,11 +1320,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 */
@@ -1402,19 +1417,19 @@ class ViewportManager extends EventEmitter {
         const stageScale = scaleMode === exports.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 === exports.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 === exports.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;
@@ -1503,34 +1518,20 @@ class Scene {
 }
 
 /**
- * Build the loading scene variant of the logo SVG.
- * Uses unique IDs (prefixed with 'ls') to avoid collisions with CSSPreloader.
- */
-function buildLoadingLogoSVG() {
-    return loading.buildLogoSVG({
-        idPrefix: 'ls',
-        svgStyle: 'width:100%;height:auto;',
-        clipRectId: 'ge-loader-rect',
-        textId: 'ge-loader-pct',
-        textContent: '0%',
-    });
-}
-/**
- * Built-in loading screen using the Energy8 SVG logo with animated loader bar.
+ * Built-in loading screen.
  *
- * Renders as an HTML overlay on top of the canvas for crisp SVG quality.
- * The loader bar fill width is driven by asset loading progress.
+ * It does NOT render its own overlay — the CSS preloader created at boot
+ * (`createPlatformSession`/`GameApplication.start`) stays on screen, and this
+ * scene merely drives it: asset-load progress → `setCSSPreloaderProgress`,
+ * tap-to-start → `waitCSSPreloaderTap`, then fades it out via
+ * `removeCSSPreloader` before entering the game. One continuous overlay from
+ * boot to gameplay — no second logo, no mid-load flash.
  */
 class LoadingScene extends Scene {
     _engine;
     _targetScene;
     _targetData;
     _config;
-    // HTML overlay
-    _overlay = null;
-    _loaderRect = null;
-    _percentEl = null;
-    _tapToStartEl = null;
     // State
     _displayedProgress = 0;
     _targetProgress = 0;
@@ -1543,8 +1544,6 @@ class LoadingScene extends Scene {
         this._targetData = targetData;
         this._config = engine.config.loading ?? {};
         this._startTime = Date.now();
-        // Create the HTML overlay with the SVG logo
-        this.createOverlay();
         // Initialize asset manager
         await this._engine.assets.init();
         // Initialize audio manager
@@ -1590,110 +1589,29 @@ class LoadingScene extends Scene {
         // Final snap to 100%
         this._displayedProgress = 1;
         this.updateLoaderBar(1);
-        // Show "Tap to Start" or transition directly
-        if (this._config.tapToStart !== false) {
-            await this.showTapToStart();
-        }
-        else {
-            await this.transitionToGame();
-        }
+        // Wait for the player's tap — resolves immediately when tapToStart is
+        // false (the preloader honours that flag) — then enter the game.
+        await loading.waitCSSPreloaderTap();
+        await this.transitionToGame();
     }
     onUpdate(dt) {
-        // Smooth progress bar fill via HTML (during active loading)
+        // Smooth progress bar fill (during active loading)
         if (!this._loadingComplete && this._displayedProgress < this._targetProgress) {
             this._displayedProgress = Math.min(this._displayedProgress + dt * 1.5, this._targetProgress);
             this.updateLoaderBar(this._displayedProgress);
         }
     }
     onResize(_width, _height) {
-        // Overlay is CSS-based, auto-resizes
+        // The preloader overlay is CSS-based and auto-resizes.
     }
     onDestroy() {
-        this.removeOverlay();
-    }
-    // ─── HTML Overlay ──────────────────────────────────────
-    createOverlay() {
-        const bgColor = typeof this._config.backgroundColor === 'string'
-            ? this._config.backgroundColor
-            : typeof this._config.backgroundColor === 'number'
-                ? `#${this._config.backgroundColor.toString(16).padStart(6, '0')}`
-                : '#0a0a1a';
-        const bgGradient = this._config.backgroundGradient ??
-            `linear-gradient(135deg, ${bgColor} 0%, #1a1a3e 100%)`;
-        this._overlay = document.createElement('div');
-        this._overlay.id = '__ge-loading-overlay__';
-        this._overlay.innerHTML = `
-      <div class="ge-loading-content">
-        ${buildLoadingLogoSVG()}
-      </div>
-    `;
-        const style = document.createElement('style');
-        style.id = '__ge-loading-style__';
-        style.textContent = `
-      #__ge-loading-overlay__ {
-        position: absolute;
-        top: 0; left: 0;
-        width: 100%; height: 100%;
-        background: ${bgGradient};
-        display: flex;
-        align-items: center;
-        justify-content: center;
-        z-index: 9999;
-        transition: opacity 0.5s ease-out;
-        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-      }
-      #__ge-loading-overlay__.ge-fade-out {
-        opacity: 0;
-        pointer-events: none;
-      }
-      .ge-loading-content {
-        display: flex;
-        flex-direction: column;
-        align-items: center;
-        width: 75%;
-        max-width: 650px;
-      }
-      .ge-loading-content svg {
-        filter: drop-shadow(0 0 40px rgba(121, 57, 194, 0.5));
-        cursor: default;
-      }
-
-      .ge-svg-pulse {
-        animation: ge-tap-pulse 1.2s ease-in-out infinite;
-      }
-      @keyframes ge-tap-pulse {
-        0%, 100% { opacity: 0.5; }
-        50% { opacity: 1; }
-      }
-    `;
-        // Get the container that holds the canvas
-        const container = this._engine.app?.canvas?.parentElement;
-        if (container) {
-            container.style.position = container.style.position || 'relative';
-            container.appendChild(style);
-            container.appendChild(this._overlay);
-        }
-        // Cache the SVG loader rect for progress updates
-        this._loaderRect = this._overlay.querySelector('#ge-loader-rect');
-        this._percentEl = this._overlay.querySelector('#ge-loader-pct');
-    }
-    removeOverlay() {
-        this._overlay?.remove();
-        document.getElementById('__ge-loading-style__')?.remove();
-        this._overlay = null;
-        this._loaderRect = null;
-        this._percentEl = null;
-        this._tapToStartEl = null;
+        // Defensive: ensure the preloader is gone even if we never transitioned
+        // (e.g. the scene was popped externally). Idempotent.
+        void loading.removeCSSPreloader(this.hostElement());
     }
     // ─── Progress ──────────────────────────────────────────
     updateLoaderBar(progress) {
-        if (this._loaderRect) {
-            this._loaderRect.setAttribute('width', String(loading.LOADER_BAR_MAX_WIDTH * progress));
-        }
-        if (this._percentEl) {
-            const pct = Math.round(progress * 100);
-            this._percentEl.textContent = `${pct}%`;
-        }
+        loading.setCSSPreloaderProgress(Math.max(0, Math.min(1, progress)));
     }
     /**
      * Smoothly animate the displayed progress from its current value to `target`
@@ -1723,49 +1641,20 @@ class LoadingScene extends Scene {
             requestAnimationFrame(tick);
         });
     }
-    // ─── Tap to Start ─────────────────────────────────────
-    async showTapToStart() {
-        const tapText = this._config.tapToStartText ?? 'TAP TO START';
-        // Reuse the same SVG text element — replace percentage with tap text
-        if (this._percentEl) {
-            const el = this._percentEl;
-            el.textContent = tapText;
-            el.setAttribute('fill', '#ffffff');
-            el.classList.add('ge-svg-pulse');
-            this._tapToStartEl = el;
-        }
-        // Make overlay clickable
-        if (this._overlay) {
-            this._overlay.style.cursor = 'pointer';
-        }
-        // Wait for tap
-        return new Promise((resolve) => {
-            const handler = async () => {
-                this._overlay?.removeEventListener('click', handler);
-                await this.transitionToGame();
-                resolve();
-            };
-            // Listen on the full overlay for easier mobile tap
-            this._overlay?.addEventListener('click', handler);
-        });
-    }
     // ─── Transition ────────────────────────────────────────
+    /** The DOM element hosting the canvas + preloader overlay. */
+    hostElement() {
+        return this._engine?.app?.canvas?.parentElement ?? document.body;
+    }
     async transitionToGame() {
-        // Fade out the HTML overlay
-        if (this._overlay) {
-            this._overlay.classList.add('ge-fade-out');
-            await new Promise((resolve) => {
-                this._overlay.addEventListener('transitionend', () => resolve(), { once: true });
-                // Safety timeout
-                setTimeout(resolve, 600);
-            });
-        }
-        // Remove overlay
-        this.removeOverlay();
+        // Fade out and remove the shared CSS preloader (resolves after the fade).
+        await loading.removeCSSPreloader(this.hostElement());
         // Navigate to the target scene, always passing the engine reference
         await this._engine.scenes.goto(this._targetScene, {
             engine: this._engine,
-            ...(this._targetData && typeof this._targetData === 'object' ? this._targetData : { data: this._targetData }),
+            ...(this._targetData && typeof this._targetData === 'object'
+                ? this._targetData
+                : { data: this._targetData }),
         });
     }
 }
@@ -1905,6 +1794,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) */
@@ -1986,17 +1881,20 @@ class GameApplication extends EventEmitter {
             // 6. Initialize sub-systems
             this.initSubSystems();
             this.emit('initialized');
-            // 7. Remove CSS preloader, show Canvas loading screen
-            loading.removeCSSPreloader(this._container);
-            // 8. Load assets with loading screen
+            // 7. Load assets. The CSS preloader stays on screen — LoadingScene drives
+            //    its progress/tap and removes it before entering the game, so there's
+            //    a single continuous overlay from boot to gameplay (no logo flash).
             await this.loadAssets(firstScene, sceneData);
             this.emit('loaded');
-            // 9. Start the game loop
+            // 8. Start the game loop
             this._running = true;
             this.emit('started');
         }
         catch (err) {
             console.error('[GameEngine] Failed to start:', err);
+            // Tear down the preloader so a failure doesn't strand the brand frame.
+            if (this._container)
+                loading.removeCSSPreloader(this._container);
             this.emit('error', err instanceof Error ? err : new Error(String(err)));
             throw err;
         }
@@ -2084,20 +1982,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 pixi_js.Container();
+        this.worldRoot.label = 'world';
+        this.uiLayer = new pixi_js.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) => {