@energy8platform/game-engine 0.34.2 → 0.35.0

package/dist/index.esm.js

@@ -1,6 +1,6 @@
 import { Ticker, Assets, Container, Text, Application, AnimatedSprite, Texture } from 'pixi.js';
 import { createPlatformSession } from '@energy8platform/platform-core';
-import { waitCSSPreloaderTap, removeCSSPreloader, setCSSPreloaderProgress, createCSSPreloader } from '@energy8platform/platform-core/loading';
+import { waitCSSPreloaderTap, removeCSSPreloader, hasExternalOverlay, externalOverlayHold, createCSSPreloader, releaseExternalOverlay, setCSSPreloaderProgress, adoptExternalOverlay, advanceExternalOverlay } from '@energy8platform/platform-core/loading';
 export { BridgeDestroyedError, BridgeNotReadyError, SDKError, TimeoutError } from '@energy8platform/game-sdk';
 export { DevBridge } from '@energy8platform/platform-core/dev-bridge';
 
@@ -751,6 +751,12 @@ class AudioManager {
     _categories;
     _masterGain = 1.0;
     _currentMusic = null;
+    /** Duck factor (0..1) from duckMusic/unduckMusic. A presentation state, not a player setting. */
+    _musicDuck = 1;
+    /** Crossfade ramp (0..1) for the track that is fading IN. 1 whenever no fade is running. */
+    _musicFade = 1;
+    /** Generation counter so a superseded crossfade ramp stops writing over the new track's. */
+    _musicFadeToken = 0;
     _unlocked = false;
     _unlockHandler = null;
     constructor(config) {
@@ -809,7 +815,10 @@ class AudioManager {
         if (this._globalMuted || this._categories[category].muted)
             return;
         const { sound } = this._soundModule;
-        const vol = (options?.volume ?? 1) * this._categories[category].volume * this._masterGain;
+        // The master gain lives on the GLOBAL bus (`sound.volumeAll`, see applyVolumes) and @pixi/sound
+        // already multiplies it in — folding it in here as well squared it, so a master of 0.5 played
+        // sfx at 0.25.
+        const vol = (options?.volume ?? 1) * this._categories[category].volume;
         try {
             sound.play(alias, {
                 volume: vol,
@@ -831,52 +840,50 @@ class AudioManager {
         if (!this._initialized || !this._soundModule)
             return;
         const { sound } = this._soundModule;
-        // Stop current music with fade-out, start new music with fade-in
-        if (this._currentMusic && fadeDuration > 0) {
-            const prevAlias = this._currentMusic;
-            this._currentMusic = alias;
-            if (this._globalMuted || this._categories.music.muted)
-                return;
-            // Fade out the previous track
-            this.fadeVolume(prevAlias, this._categories.music.volume * this._masterGain, 0, fadeDuration, () => {
-                try {
-                    sound.stop(prevAlias);
-                }
-                catch { /* ignore */ }
-            });
-            // Start new track at zero volume, fade in
-            try {
-                sound.play(alias, {
-                    volume: 0,
-                    loop: true,
+        const prevAlias = this._currentMusic;
+        const crossfade = !!prevAlias && prevAlias !== alias && fadeDuration > 0;
+        // Retire the outgoing track. Its own SOUND-level volume is the only thing still pointing at it,
+        // so fading that to 0 is safe — nothing else writes it once `_currentMusic` has moved on.
+        if (prevAlias) {
+            if (crossfade) {
+                const from = this.soundVolumeOf(prevAlias);
+                this.fadeVolume(prevAlias, from, 0, fadeDuration, () => {
+                    try {
+                        sound.stop(prevAlias);
+                    }
+                    catch { /* ignore */ }
                 });
-                this.fadeVolume(alias, 0, this._categories.music.volume * this._masterGain, fadeDuration);
-            }
-            catch (e) {
-                console.warn(`[AudioManager] Failed to play music "${alias}":`, e);
             }
-        }
-        else {
-            // No crossfade — instant switch
-            if (this._currentMusic) {
+            else {
                 try {
-                    sound.stop(this._currentMusic);
+                    sound.stop(prevAlias);
                 }
                 catch { /* ignore */ }
             }
-            this._currentMusic = alias;
-            if (this._globalMuted || this._categories.music.muted)
-                return;
-            try {
-                sound.play(alias, {
-                    volume: this._categories.music.volume * this._masterGain,
-                    loop: true,
-                });
-            }
-            catch (e) {
-                console.warn(`[AudioManager] Failed to play music "${alias}":`, e);
-            }
         }
+        this._currentMusic = alias;
+        this._musicFadeToken++; // any ramp still running belongs to a track we just replaced
+        // Deliberately started even while muted. Global mute is the @pixi/sound CONTEXT mute and a
+        // muted music category is a 0 term in `musicGain()` — both already make this inaudible, and
+        // both undo themselves the moment the player flips them back. Returning early here instead
+        // meant a track begun while muted never existed, so unmuting restored silence until some
+        // later mode change happened to switch tracks.
+        // The incoming track plays at INSTANCE volume 1 and carries its whole gain on the SOUND layer
+        // (`musicGain()`), which is the layer the slider, the duck and this fade all write. Splitting
+        // them across layers is what silenced every crossfade: the track was started at instance volume
+        // 0 and the ramp then moved the sound layer, whose product with 0 is 0 for the track's life.
+        // The gain is written BEFORE play() so the first frame is never at full volume.
+        this._musicFade = crossfade ? 0 : 1;
+        this.applyMusicGain();
+        try {
+            sound.play(alias, { volume: 1, loop: true });
+        }
+        catch (e) {
+            console.warn(`[AudioManager] Failed to play music "${alias}":`, e);
+            return;
+        }
+        if (crossfade)
+            this.rampMusicFade(fadeDuration);
     }
     /**
      * Stop current music.
@@ -892,6 +899,10 @@ class AudioManager {
             // ignore
         }
         this._currentMusic = null;
+        // Retire any running ramp and clear the fade term, so the next track does not inherit a
+        // half-finished crossfade and start silent.
+        this._musicFadeToken++;
+        this._musicFade = 1;
     }
     /**
      * Stop all sounds.
@@ -917,6 +928,9 @@ class AudioManager {
      */
     setVolume(category, volume) {
         this._categories[category].volume = Math.max(0, Math.min(1, volume));
+        // applyVolumes() re-pushes the music gain, so moving the Music slider is heard on the track
+        // that is ALREADY playing — it used to take effect only at the next playMusic (a mode change).
+        // SFX need no push: play() reads the category volume fresh on every call.
         this.applyVolumes();
         this.saveState();
     }
@@ -989,30 +1003,19 @@ class AudioManager {
      * @param factor - Volume multiplier (0..1), e.g. 0.3 = 30% of normal
      */
     duckMusic(factor) {
-        if (!this._initialized || !this._soundModule || !this._currentMusic)
-            return;
-        const { sound } = this._soundModule;
-        const vol = this._categories.music.volume * factor;
-        try {
-            sound.volume(this._currentMusic, vol);
-        }
-        catch {
-            // ignore
-        }
+        // Held as a FACTOR rather than written as a finished volume: the duck used to write
+        // `category × factor` onto a track whose instance already carried the category volume, so it
+        // ducked to category², and unducking restored category² instead of category. Keeping it as one
+        // term of `musicGain()` also keeps the slider live while ducked.
+        this._musicDuck = Math.max(0, Math.min(1, factor));
+        this.applyMusicGain();
     }
     /**
      * Restore music to normal volume after ducking.
      */
     unduckMusic() {
-        if (!this._initialized || !this._soundModule || !this._currentMusic)
-            return;
-        const { sound } = this._soundModule;
-        try {
-            sound.volume(this._currentMusic, this._categories.music.volume);
-        }
-        catch {
-            // ignore
-        }
+        this._musicDuck = 1;
+        this.applyMusicGain();
     }
     /**
      * Destroy the audio manager and free resources.
@@ -1051,6 +1054,57 @@ class AudioManager {
         };
         requestAnimationFrame(tick);
     }
+    /**
+     * The SOUND-layer gain for the running music track.
+     *
+     * @pixi/sound resolves a playing instance as `instance × sound × global` (WebAudioInstance.
+     * refresh). Each of those three has exactly ONE owner here, which is what keeps the mixer honest:
+     *   global   — the master gain (`applyVolumes`)
+     *   sound    — music: this function. sfx: untouched, left at 1.
+     *   instance — sfx: the per-call volume × the sfx category. music: always 1.
+     * Everything that can move music volume — the player's slider, the category mute, a big-win duck,
+     * a crossfade — is a term below, so they compose instead of overwriting each other.
+     */
+    musicGain() {
+        const c = this._categories.music;
+        return (c.muted ? 0 : 1) * c.volume * this._musicDuck * this._musicFade;
+    }
+    /** Push `musicGain()` at the current track. Safe before it starts playing and with none playing. */
+    applyMusicGain() {
+        if (!this._soundModule || !this._currentMusic)
+            return;
+        try {
+            this._soundModule.sound.volume(this._currentMusic, this.musicGain());
+        }
+        catch {
+            // ignore — alias not registered yet
+        }
+    }
+    /** Current SOUND-layer volume of `alias`, or 0 when it cannot be read. */
+    soundVolumeOf(alias) {
+        try {
+            return Number(this._soundModule.sound.volume(alias)) || 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /** Ramp the crossfade term 0 → 1 over `durationMs`, recomposing the gain each frame so a slider
+     *  drag or a duck landing mid-fade is honoured rather than overwritten when the fade ends. */
+    rampMusicFade(durationMs) {
+        const token = this._musicFadeToken;
+        const start = Date.now();
+        const tick = () => {
+            if (token !== this._musicFadeToken)
+                return; // a newer track owns the music now
+            const t = Math.min((Date.now() - start) / durationMs, 1);
+            this._musicFade = t;
+            this.applyMusicGain();
+            if (t < 1)
+                requestAnimationFrame(tick);
+        };
+        requestAnimationFrame(tick);
+    }
     applyVolumes() {
         if (!this._soundModule)
             return;
@@ -1058,6 +1112,7 @@ class AudioManager {
         // Global mute is owned by sound.muteAll()/unmuteAll() (context.muted),
         // not by volumeAll — mixing both leaves mute un-undoable after reload.
         sound.volumeAll = this._masterGain; // master multiplies the global bus
+        this.applyMusicGain(); // category volume/mute reach the RUNNING track
     }
     setupMobileUnlock() {
         if (this._unlocked)
@@ -1539,6 +1594,14 @@ class Scene {
  * 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.
+ *
+ * When the game supplied its own overlay (`loading.externalOverlay`, e.g.
+ * Artube's `LoaderViewController`), this scene is also the HAND-OVER point: that
+ * overlay covered the gap this scene's existence ends — the bundle download,
+ * Pixi init and the SDK handshake, none of which the engine can paint over. The
+ * first thing `onEnter` does is mount the preloader, wait for it to be painted,
+ * and dismiss the game's overlay. Everything after that line is identical on
+ * every platform.
  */
 class LoadingScene extends Scene {
     _engine;
@@ -1556,6 +1619,10 @@ class LoadingScene extends Scene {
         this._targetScene = targetScene;
         this._targetData = targetData;
         this._config = engine.config.loading ?? {};
+        // Take the screen from a game-supplied loading overlay, if there is one. Before any awaited
+        // work: from here on the player is looking at OUR loading screen, and `_startTime` (which
+        // `minDisplayTime` is measured from) must start when that becomes true.
+        await this.takeOverFromExternalOverlay();
         this._startTime = Date.now();
         // Initialize asset manager
         await this._engine.assets.init();
@@ -1602,8 +1669,10 @@ class LoadingScene extends Scene {
         // Final snap to 100%
         this._displayedProgress = 1;
         this.updateLoaderBar(1);
-        // Wait for the player's tap — resolves immediately when tapToStart is
-        // false (the preloader honours that flag) — then enter the game.
+        // Wait for the player's tap — resolves immediately when tapToStart is false — then enter the
+        // game. This is the preloader's gate and it reads the preloader's config, so it means the same
+        // thing on every target: a game-supplied overlay has no say in it, and by now no part in the
+        // screen either. It was dismissed at the hand-over above; the player is looking at ours.
         await waitCSSPreloaderTap();
         await this.transitionToGame();
     }
@@ -1622,6 +1691,59 @@ class LoadingScene extends Scene {
         // (e.g. the scene was popped externally). Idempotent.
         void removeCSSPreloader(this.hostElement());
     }
+    // ─── Hand-over from a game-supplied overlay ────────────
+    /**
+     * Swap a game-supplied loading overlay for the engine's own loading screen.
+     *
+     * The overlay (Artube's) has been on screen since before this bundle was fetched, covering a gap
+     * nothing of ours could. Its job ends here, at the first frame the engine paints; the player then
+     * gets the game's own brand, progress bar and tap-to-start, exactly as on every other target.
+     *
+     * The order of the four steps is the whole design, and each is wrong on its own:
+     *
+     *  0. Wait out whatever the overlay is still owed on screen (`externalOverlayMinDisplayTime`,
+     *     default 1.5s, plus room for a phase crossfade already in flight). The gap this overlay
+     *     covers can be under half a second, which is not long enough for a partner's brand to
+     *     register. Waiting here — BEFORE mounting ours — rather than after is what keeps the two
+     *     screens' timelines from overlapping: our splash and brand floor start when the player can
+     *     actually see them, not behind someone else's overlay. On any boot slower than the floor
+     *     this step costs nothing, and on a non-Artube target it is not reached at all.
+     *  1. Mount the preloader, opaque and full-bleed, while theirs is still up. Both are on screen
+     *     together for a few frames, so there is never a moment with neither, whatever happens next.
+     *  2. Wait for that frame to actually be PAINTED — mounting only queues it. Dismissing theirs
+     *     before the paint is precisely the flash of bare background this ordering exists to avoid.
+     *     Two `requestAnimationFrame`s: the first callback runs before the frame it belongs to is
+     *     composited, the second after. Two frames is also enough for Pixi's own rAF-driven ticker
+     *     to have rendered this scene at least once, so "the loading scene has painted" is literally
+     *     true by the time step 3 runs.
+     *  3. Only then dismiss theirs. Their `hideLoader()` plays a 0.3s fade and removes the element.
+     *     Not waiting for that fade is deliberate — it is an animation on someone else's element,
+     *     and blocking a boot on it would be a hang waiting to happen.
+     *
+     * Which of the two is visually on top is the host page's business, not ours, and it does NOT
+     * change the guarantee. On a typical game page (`#game { position: fixed; inset: 0 }`) the fixed
+     * container establishes a stacking context, so the preloader's z-index is scoped inside it and
+     * Artube's `position: fixed; z-index: 9999` sits above — their fade then crossfades onto our
+     * loading screen, which is what was observed live and looks right. On a page where ours wins
+     * instead, their fade simply plays underneath, unseen. Either way the seam is covered, because
+     * what step 2 buys is that OUR screen is already painted before theirs starts going away.
+     */
+    async takeOverFromExternalOverlay() {
+        if (!hasExternalOverlay())
+            return;
+        await externalOverlayHold();
+        createCSSPreloader(this.hostElement(), this._config);
+        await this.nextPaint();
+        releaseExternalOverlay();
+    }
+    /** Resolves after the browser has composited at least one frame (see step 2 above). */
+    nextPaint() {
+        if (typeof requestAnimationFrame !== 'function')
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+        });
+    }
     // ─── Progress ──────────────────────────────────────────
     updateLoaderBar(progress) {
         setCSSPreloaderProgress(Math.max(0, Math.min(1, progress)));
@@ -1876,14 +1998,37 @@ class GameApplication extends EventEmitter {
             return;
         }
         try {
+            // 0. Adopt a game-supplied loading overlay (`loading.externalOverlay`) BEFORE anything that
+            //    can throw. Such an overlay is already on screen — Artube's is injected into index.html,
+            //    so it paints before this bundle is even fetched — and until the engine has adopted it,
+            //    the catch below has no way to take it down. A bad `container` selector (step 1) would
+            //    otherwise strand it on screen forever. It needs no container of ours.
+            //    Adoption is also where its minimum display time starts counting, which is why the
+            //    config value is handed over here rather than read at the hand-over: this is the
+            //    earliest moment the engine runs, and the overlay has been on screen since before it.
+            const external = this.config.loading?.externalOverlay;
+            if (external)
+                adoptExternalOverlay(external, this.config.loading?.externalOverlayMinDisplayTime);
             // 1. Resolve container element
             this._container = this.resolveContainer();
-            // 2. Show CSS preloader immediately (before PixiJS)
-            createCSSPreloader(this._container, this.config.loading);
+            // 2. Show the CSS preloader immediately (before PixiJS) — UNLESS a game-supplied overlay is
+            //    already covering the screen. In that case the preloader is mounted later, by LoadingScene
+            //    at its first frame, which is where the hand-over happens. Mounting it here instead would
+            //    put our brand over theirs for the whole of Pixi init and the SDK handshake, i.e. hand
+            //    over long before the gap the external overlay exists to cover has closed.
+            if (!hasExternalOverlay())
+                createCSSPreloader(this._container, this.config.loading);
             // 3. Initialize PixiJS
             await this.initPixi();
+            // Milestones through the pre-first-frame gap, for a game-supplied overlay only (no-ops
+            // otherwise, so the built-in preloader's behaviour is untouched). They are also what makes
+            // Artube's loader crossfade from its dark partner phase to its branded one: that transition
+            // fires on the first progress above zero, and without it the player would never see the
+            // brand the loader exists to show. Values are honest weights of what remains, not a timer.
+            advanceExternalOverlay(0.35);
             // 4. Initialize SDK (if enabled)
             await this.initSDK();
+            advanceExternalOverlay(0.7);
             // 4b. Mount the branded game shell after the SDK handshake (optional)
             if (this.config.shell) {
                 const { createGameShell } = await import('@energy8platform/shell/html');
@@ -1893,10 +2038,17 @@ class GameApplication extends EventEmitter {
             this.applySDKConfig();
             // 6. Initialize sub-systems
             this.initSubSystems();
+            advanceExternalOverlay(0.85);
             this.emit('initialized');
             // 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).
+            //
+            //    With a game-supplied overlay the sequence has one extra step at the
+            //    front: LoadingScene MOUNTS the preloader, waits for its first painted
+            //    frame, and only then dismisses the external overlay. From that frame
+            //    on this path and every other are identical — same brand, same bar,
+            //    same tap-to-start.
             await this.loadAssets(firstScene, sceneData);
             this.emit('loaded');
             // 8. Start the game loop
@@ -1905,9 +2057,13 @@ class GameApplication extends EventEmitter {
         }
         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)
-                removeCSSPreloader(this._container);
+            // Tear down both possible overlays so a failure strands neither brand frame. BOTH calls run:
+            // a throw during the hand-over window can leave the preloader mounted AND the external
+            // overlay still adopted, and each call is a no-op when there is nothing to remove. The
+            // container may never have resolved (step 1 is inside this try), hence the `document.body`
+            // fallback — the external overlay ignores the element entirely.
+            releaseExternalOverlay();
+            void removeCSSPreloader(this._container ?? document.body);
             this.emit('error', err instanceof Error ? err : new Error(String(err)));
             throw err;
         }