@energy8platform/game-engine 0.34.3 → 0.35.0

package/dist/host.esm.js

@@ -1,6 +1,6 @@
 import { Ticker, Assets, Container, Text, Application, Graphics, TextureSource } 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 { PixiRenderer, createPixiShell, createShell } from '@energy8platform/shell/pixi';
 import { socialize, createI18n } from '@energy8platform/shell';
 export { socialize } from '@energy8platform/shell';
@@ -1595,6 +1595,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;
@@ -1612,6 +1620,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();
@@ -1658,8 +1670,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();
     }
@@ -1678,6 +1692,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)));
@@ -1932,14 +1999,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');
@@ -1949,10 +2039,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
@@ -1961,9 +2058,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;
         }
@@ -2158,21 +2259,33 @@ class IntroScene extends Scene {
 
 /**
  * Pure: map host options to a GameApplicationConfig with sane defaults.
- * `isStakeNow` is computed by the orchestrator (kept out of here so this
- * stays a pure, renderer-free function).
+ * `isStakeNow` / `isArtubeNow` are computed by the orchestrator (kept out of
+ * here so this stays a pure, renderer-free function).
+ *
+ * Both host bridges run IN-PROCESS with the game, so either one means the SDK
+ * must be in `devMode` — that is what makes it talk over the in-memory channel
+ * the bridge listens on instead of postMessage-ing an outer host that isn't
+ * there. (`dev` is the third, unrelated reason for the same flag: DevBridge.)
  */
-function buildAppConfig(opts, isStakeNow) {
+function buildAppConfig(opts, isStakeNow, isArtubeNow = false) {
     return {
         container: opts.container ?? '#game',
         designWidth: opts.design?.width ?? 1920,
         designHeight: opts.design?.height ?? 1080,
         scaleMode: opts.scaleMode ?? ScaleMode.FILL,
         orientation: opts.orientation ?? Orientation.ANY,
-        loading: opts.loading ?? { tapToStart: false, minDisplayTime: 600 },
+        // MERGED, not replaced. `opts.loading ?? {…}` looked equivalent and was not: a game that
+        // passes ANY loading option loses every default it did not restate, so `{ minDisplayTime: 900 }`
+        // silently re-armed tap-to-start (the engine's own default for that flag is `true`, for
+        // backwards compatibility with direct GameApplication users). The Artube target made it
+        // visible — a game supplying only `externalOverlay` waited for a tap there and nowhere else,
+        // i.e. the same source line behaved differently per platform. Spreading `opts.loading` last
+        // keeps every explicit value winning while unset keys stay on the host's defaults.
+        loading: { tapToStart: false, minDisplayTime: 600, ...opts.loading },
         manifest: opts.manifest,
         audio: opts.audio,
         pixi: opts.pixi,
-        sdk: { devMode: isStakeNow || (opts.dev ?? false) },
+        sdk: { devMode: isStakeNow || isArtubeNow || (opts.dev ?? false) },
         debug: opts.dev ?? false,
     };
 }
@@ -2301,7 +2414,7 @@ function installGlobalErrorHandlers(container, fatal = (m) => showFatalError(con
 
 // packages/game-engine/src/host/createSlotGame.ts
 /**
- * One-call slot bootstrap: preboot → (optional Stake bridge) → GameApplication
+ * One-call slot bootstrap: preboot → (optional Stake / Artube bridge) → GameApplication
  * → register scene → start. Collapses the per-game main.ts boilerplate.
  *
  * Not unit-tested: GameApplication.init() drives Pixi, which hangs in headless
@@ -2316,6 +2429,25 @@ async function createSlotGame(opts) {
     // Declared up front so `fatal` can route errors through the shell's own modal once it exists.
     let shell = null;
     const fatal = (message) => {
+        // Take down a game-supplied loading overlay (`loading.externalOverlay`) first. Several fatal
+        // paths below — a refused Artube launch, a bridge that cannot connect — happen BEFORE
+        // `GameApplication.start()`, so its own error path never runs and nothing else would ever
+        // dismiss the overlay. Artube's is already on screen from index.html at z-index 9999: leaving
+        // it up means the player stares at a frozen loading screen, and a custom `onFatalError`
+        // renderer would be hidden underneath it entirely.
+        //
+        // `releaseExternalOverlay` handles the case where the engine already adopted it (and keeps the
+        // dismissal idempotent, which matters now that the normal hand-over also dismisses it). Its
+        // `false` means the engine never got that far — those are exactly the pre-boot refusals, where
+        // hiding the game's overlay directly is the only thing that can work.
+        if (!releaseExternalOverlay()) {
+            try {
+                opts.loading?.externalOverlay?.hideLoader();
+            }
+            catch {
+                /* the overlay is the game's; a throw here must not swallow the error we came to report */
+            }
+        }
         if (opts.onFatalError)
             return opts.onFatalError(message);
         // Once the shell is up, use ITS branded modal (consistent chrome, social vocabulary, fit
@@ -2385,7 +2517,65 @@ async function createSlotGame(opts) {
             }
         }
     }
-    const game = new GameApplication(buildAppConfig(opts, isStakeNow));
+    let artubeBridge = null;
+    let isArtubeNow = false;
+    // `!isStakeNow`: both bridges install themselves in-process on the SAME SDK memory channel, so
+    // whichever launch already claimed the game wins. (The two launch shapes are disjoint in practice
+    // — Stake's marker is `sessionID`/`replay`, Artube's is `sessionId` — so this never fires; it just
+    // makes the precedence explicit rather than leaving two bridges racing.)
+    if (opts.artube && !isStakeNow) {
+        // The GAME supplies the loader (see `ArtubeIntegration.load`): a bare
+        // `import('@energy8platform/artube-bridge')` here would be resolved statically by every bundler
+        // and would break — loudly or, under Vite, silently — every game that never installed the
+        // package. Classifier and bridge come from the same module, so this is one load.
+        let artube;
+        try {
+            artube = await opts.artube.load();
+        }
+        catch (err) {
+            fatal('Could not start the game.');
+            throw err;
+        }
+        // Security gate, the Artube counterpart of the Stake one above. Artube's only launch marker is
+        // `sessionId`, and unlike Stake there is no attacker-suppliable server address to validate
+        // (`apiBase` is the launch URL's own origin). What IS reachable is stripping the session: a URL
+        // that carries `sessionId` with an empty/blank value claims a session it doesn't have, fails the
+        // "is this Artube?" check, and would silently fall through to the offline/dev bridge — the
+        // free-play hole. 'artube' = a real launch (load the bridge); 'offline' = no marker at all, a
+        // genuine dev launch.
+        //
+        // What URL classification cannot catch: a marker removed ENTIRELY is indistinguishable from a
+        // dev launch. In a production BUILD there is nothing to fall through to anyway — the DevBridge
+        // bootstrapper is injected by a Vite plugin with `apply: 'serve'`, so no build carries one,
+        // whatever BUILD_TARGET says. Under a plain `npm run dev` the bootstrapper HAS already started a
+        // DevBridge before this code runs (it wraps the entry module), so there the protection is this
+        // gate refusing to start the game — not the absence of a bridge.
+        const launch = artube.classifyArtubeLaunch(location.href);
+        if (launch === 'blocked') {
+            fatal('Invalid game session. Please relaunch the game from the lobby.');
+            throw new Error('createSlotGame: refusing to run — Artube launch with a missing or blank sessionId');
+        }
+        isArtubeNow = launch === 'artube';
+        if (isArtubeNow) {
+            try {
+                artubeBridge = new artube.ArtubeBridge({
+                    // In-process over the SDK's MemoryChannel (see buildAppConfig's devMode).
+                    devMode: true,
+                    gameId: opts.model.spec.id,
+                    url: location.href,
+                    // Same-origin in production; both fields are dev/demo escape hatches (see ArtubeIntegration).
+                    ...(opts.artube.apiBase ? { apiBase: opts.artube.apiBase } : {}),
+                    ...(opts.artube.demoBalance != null ? { demoBalance: opts.artube.demoBalance } : {}),
+                });
+                await artubeBridge.ready();
+            }
+            catch (err) {
+                fatal('Could not connect to the game server. Please reload.');
+                throw err;
+            }
+        }
+    }
+    const game = new GameApplication(buildAppConfig(opts, isStakeNow, isArtubeNow));
     // Register EVERY scene up front so any of them can navigate to any other.
     for (const { key, scene } of opts.scenes)
         game.scenes.register(key, scene);
@@ -2450,6 +2640,8 @@ async function createSlotGame(opts) {
         const { resolveReplayBonusId } = await Promise.resolve().then(function () { return replay; });
         const ps = game.platformSession;
         const balance = game.initData?.balance ?? 0;
+        // Replay is a STAKE concept (a shared link that re-plays one recorded round). Artube has no
+        // equivalent, so an Artube launch is always 'base' — nothing to mirror here.
         const isReplay = !!stakeBridge?.isReplay;
         const mode = isReplay ? 'replay' : 'base';
         // initData.config carries the Stake bridge's currency/social/disclaimer surface (GameConfigData);
@@ -2464,17 +2656,26 @@ async function createSlotGame(opts) {
         // carrier for the same value (INIT only ever has a session on a resume). Both are ignored when
         // absent or 0 so an ordinary launch still starts on the default.
         const resumedBet = config?.activeRound?.bet || initData?.session?.betAmount || undefined;
+        // Artube states its per-session default bet as an INDEX into the platform's ladder; resolve it
+        // against that SAME ladder so `runtime.defaultBet` is an amount on both platforms.
+        const artubeDefaultBet = isArtubeNow
+            ? config?.betLevels?.[config?.artube?.defaultBetIndex ?? -1]
+            : undefined;
         const { resolveCurrency } = await Promise.resolve().then(function () { return shellConfig; });
         // SINGLE source of truth for the symbol: the Stake bridge already puts a full CurrencyMetaData
         // (symbol + placement) on initData.config.currency. In the non-stake/devBridge path that meta
         // is absent and we only have the spec's currency CODE — resolve it through the SAME table
         // (stake-bridge's lookupCurrency) so e.g. 'EUR' renders as '€', not the literal text "EUR".
         // stake-bridge ships with every scaffold; if it's somehow absent we degrade to the code.
+        // On Artube the session currency is the PLATFORM's (per player, and 'FUN' for demo sessions) and
+        // arrives as a bare code on initData — there is no meta object. It outranks the spec's static
+        // code, which would otherwise show every Artube player the spec's currency symbol.
+        const currencyCode = (isArtubeNow ? initData?.currency : undefined) || opts.model.spec.currency;
         let currencyMeta = config?.currency;
-        if (!currencyMeta?.symbol && opts.model.spec.currency) {
+        if (!currencyMeta?.symbol && currencyCode) {
             try {
                 const { lookupCurrency } = await import('@energy8platform/stake-bridge');
-                currencyMeta = lookupCurrency(opts.model.spec.currency);
+                currencyMeta = lookupCurrency(currencyCode);
             }
             catch {
                 /* stake-bridge not installed — resolveCurrency falls back to the code */
@@ -2482,16 +2683,17 @@ async function createSlotGame(opts) {
         }
         const runtime = {
             balance,
-            currency: resolveCurrency(currencyMeta, opts.model.spec.currency),
+            currency: resolveCurrency(currencyMeta, currencyCode),
             language: initData?.lang,
             mode,
             social: config?.socialMode,
             disclaimerLines: config?.disclaimerLines,
             jurisdiction: config?.jurisdiction,
-            // Currency-specific ladder + per-currency default from /wallet/authenticate (Stake);
-            // absent on dev/devBridge → buildShellConfig falls back to the spec.
+            // Currency-specific ladder + per-currency default from /wallet/authenticate (Stake) or the
+            // backend's `allowed_bets` (Artube); absent on dev/devBridge → buildShellConfig falls back to
+            // the spec.
             betLevels: config?.betLevels,
-            defaultBet: resumedBet ?? config?.stake?.defaultBetLevel ?? config?.defaultBet,
+            defaultBet: resumedBet ?? config?.stake?.defaultBetLevel ?? artubeDefaultBet ?? config?.defaultBet,
             // Hard stake window; the bridge rejects anything outside it before /bet/play.
             minBet: config?.stake?.minBet,
             maxBet: config?.stake?.maxBet,
@@ -2500,9 +2702,13 @@ async function createSlotGame(opts) {
         // spec's (EUR-shaped) ladder here would put the game on bets the wallet can't honour — every
         // spin rejected on a high-denomination currency (ARS minBet 50), or silently mispriced. Fail
         // where the cause is visible instead of at the first spin.
-        if (isStakeNow && !runtime.betLevels?.length) {
+        // Artube is the same requirement by a different route: the wire carries a bet INDEX, not an
+        // amount, and the bridge maps the amount the game plays to the NEAREST rung of the platform's
+        // ladder — so a spec-shaped ladder wouldn't be rejected, it would silently charge a different
+        // price than the bar shows. Refuse there too.
+        if ((isStakeNow || isArtubeNow) && !runtime.betLevels?.length) {
             fatal('Could not load the bet levels for your currency. Please relaunch the game.');
-            throw new Error('createSlotGame: Stake launch returned no config.betLevels — refusing to fall back to the spec ladder');
+            throw new Error(`createSlotGame: ${isStakeNow ? 'Stake' : 'Artube'} launch returned no config.betLevels — refusing to fall back to the spec ladder`);
         }
         if (opts.dev) {
             // Dev-only diagnostic. Logged as PLAIN STRINGS (not collapsed objects) so the values are
@@ -3045,7 +3251,7 @@ async function createSlotGame(opts) {
             });
         }
     }
-    return { game, stakeBridge, shell };
+    return { game, stakeBridge, artubeBridge, shell };
 }
 
 // packages/game-engine/src/host/shellConfig.ts