@energy8platform/game-engine 0.34.2 → 0.35.0

package/src/host/types.ts

@@ -34,6 +34,58 @@ export interface StakeIntegration {
   adapter: BookAdapter | AdapterModule;
 }
 
+/** The live Artube bridge, structurally. Kept minimal so game-engine never has to import
+ *  `@energy8platform/artube-bridge` — see `ArtubeIntegration.load`. */
+export interface ArtubeBridgeLike {
+  /** Resolves once the backend has sent its init. */
+  ready(): Promise<void>;
+  destroy(): void;
+}
+
+/** What `ArtubeIntegration.load()` must resolve to. `@energy8platform/artube-bridge`'s own entry
+ *  satisfies this structurally, so `load: () => import('@energy8platform/artube-bridge')` typechecks
+ *  with no adapter. The launch CLASSIFIER comes from the same module as the bridge: one import, and
+ *  no chicken-and-egg where the host would have to load something to decide whether to load. */
+export interface ArtubeModule {
+  classifyArtubeLaunch: (url: string) => 'artube' | 'blocked' | 'offline';
+  ArtubeBridge: new (options: {
+    devMode?: boolean;
+    gameId?: string;
+    url?: string;
+    apiBase?: string;
+    demoBalance?: number;
+  }) => ArtubeBridgeLike;
+}
+
+/** Artube host integration. There is no per-game artifact to pass: the game's own BACKEND
+ *  (`@energy8platform/artube-server`) owns the round shape, so the bridge is a pure protocol
+ *  translator — `load` is the only required field. `gameId` comes from the model, the launch params
+ *  from the URL. */
+export interface ArtubeIntegration {
+  /** REQUIRED. How the host reaches the bridge:
+   *  `load: () => import('@energy8platform/artube-bridge')`.
+   *
+   *  Why the GAME supplies this instead of the host importing the package itself: a bare
+   *  `import('@energy8platform/artube-bridge')` inside this always-shipped `/host` entry is resolved
+   *  STATICALLY by every bundler, so it would have to resolve in games that never opted into Artube
+   *  and therefore never installed the package — esbuild/webpack fail the build outright, and Vite
+   *  silently substitutes an empty module (it stubs uninstalled optional peers), which is worse:
+   *  the game builds and then dies at runtime. With the loader, the specifier only ever appears in
+   *  the bundle of a game that took the dependency.
+   *
+   *  The loaded chunk is fetched on every launch of such a game (the classifier lives in it), which
+   *  is the point of the split: only Artube-targeted builds pay for it. */
+  load: () => Promise<ArtubeModule>;
+  /** Starting virtual balance for a DEMO session (the platform doesn't keep one — the bridge does,
+   *  client-side). Default: the backend's own configured demo balance. Ignored for real sessions. */
+  demoBalance?: number;
+  /** Origin of the game's backend. Default (and the only supported PRODUCTION value) is the launch
+   *  URL's own origin: Artube serves frontend and backend on one domain, split by path (`/api/**`).
+   *  Override only for local dev against a backend on another port — prefer proxying `/api` from the
+   *  dev server (what the `BUILD_TARGET=artube` target does) so dev matches production. */
+  apiBase?: string;
+}
+
 /** One scene registered with the host: a key + its constructor. The list order matters — the
  *  first scene that is eligible for the current launch mode is the start scene (unless an explicit
  *  `startScene` overrides it). */
@@ -77,6 +129,10 @@ export interface CreateSlotGameOptions<T extends SlotSpinResultBase = SlotSpinRe
   textureDefaults?: boolean;
   dev?: boolean;
   stake?: StakeIntegration;
+  /** Run on Artube when the launch URL says so (`?sessionId=…`):
+   *  `artube: { load: () => import('@energy8platform/artube-bridge') }`. See `ArtubeIntegration`
+   *  for why the game supplies the loader. Build with `BUILD_TARGET=artube`. */
+  artube?: ArtubeIntegration;
   shell?: SlotShellOptions;
   /** Customise the bonus bar readout for games whose bonus isn't plain free spins (adventure,
    *  hold-and-spin, respins). Omit for the free-spins default. See `BonusReadoutConfig`. */
@@ -101,5 +157,7 @@ export type ShellFactory = (config: PixiShellConfig) => Shell;
 export interface SlotGameHandle {
   game: GameApplication;
   stakeBridge: StakeBridge | null;
+  /** The live Artube bridge — non-null only on a real Artube launch (`opts.artube` + `?sessionId=…`). */
+  artubeBridge: ArtubeBridgeLike | null;
   shell: Shell | null;
 }

package/src/loading/LoadingScene.ts

@@ -1,9 +1,13 @@
 import { Scene } from '../core/Scene';
 import type { LoadingScreenConfig } from '../types';
 import {
+  createCSSPreloader,
   setCSSPreloaderProgress,
   waitCSSPreloaderTap,
   removeCSSPreloader,
+  hasExternalOverlay,
+  externalOverlayHold,
+  releaseExternalOverlay,
 } from '@energy8platform/platform-core/loading';
 
 interface LoadingSceneData {
@@ -21,6 +25,14 @@ interface LoadingSceneData {
  * 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.
  */
 export class LoadingScene extends Scene {
   private _engine!: any;
@@ -40,6 +52,12 @@ export 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
@@ -104,8 +122,10 @@ export class LoadingScene extends Scene {
     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();
   }
@@ -131,6 +151,60 @@ export class LoadingScene extends Scene {
     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.
+   */
+  private async takeOverFromExternalOverlay(): Promise<void> {
+    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). */
+  private nextPaint(): Promise<void> {
+    if (typeof requestAnimationFrame !== 'function') return Promise.resolve();
+    return new Promise<void>((resolve) => {
+      requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+    });
+  }
+
   // ─── Progress ──────────────────────────────────────────
 
   private updateLoaderBar(progress: number): void {

package/src/loading/index.ts

@@ -7,6 +7,12 @@ export {
   setCSSPreloaderProgress,
   waitCSSPreloaderTap,
   removeCSSPreloader,
+  adoptExternalOverlay,
+  advanceExternalOverlay,
+  externalOverlayHold,
+  releaseExternalOverlay,
+  hasExternalOverlay,
+  DEFAULT_EXTERNAL_MIN_DISPLAY_MS,
   buildLogoSVG,
   LOADER_BAR_MAX_WIDTH,
 } from '@energy8platform/platform-core/loading';

package/src/types.ts

@@ -37,6 +37,7 @@ export enum Orientation {
 // existing game-engine consumers keep their imports.
 import type {
   LoadingScreenConfig,
+  ExternalLoadingOverlay,
   AssetManifest,
   AssetBundle,
   AssetEntry,
@@ -44,6 +45,7 @@ import type {
 
 export type {
   LoadingScreenConfig,
+  ExternalLoadingOverlay,
   AssetManifest,
   AssetBundle,
   AssetEntry,