@energy8platform/game-engine 0.34.2 → 0.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@energy8platform/game-engine",
-  "version": "0.34.2",
+  "version": "0.35.0",
   "description": "Universal casino game engine built on PixiJS v8 and @energy8platform/game-sdk",
   "type": "module",
   "main": "./dist/index.cjs.js",
@@ -93,7 +93,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@energy8platform/platform-core": ">=0.30.8",
+    "@energy8platform/platform-core": ">=0.31.0",
     "@energy8platform/shell": ">=0.7.0"
   },
   "peerDependencies": {

package/src/audio/AudioManager.ts

@@ -37,6 +37,12 @@ export class AudioManager {
   private _categories: Record<AudioCategoryName, CategoryState>;
   private _masterGain = 1.0;
   private _currentMusic: string | null = null;
+  /** Duck factor (0..1) from duckMusic/unduckMusic. A presentation state, not a player setting. */
+  private _musicDuck = 1;
+  /** Crossfade ramp (0..1) for the track that is fading IN. 1 whenever no fade is running. */
+  private _musicFade = 1;
+  /** Generation counter so a superseded crossfade ramp stops writing over the new track's. */
+  private _musicFadeToken = 0;
   private _unlocked = false;
   private _unlockHandler: (() => void) | null = null;
 
@@ -106,7 +112,10 @@ export 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, {
@@ -129,47 +138,45 @@ export 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) {
-        try { sound.stop(this._currentMusic); } catch { /* ignore */ }
+      } else {
+        try { 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);
   }
 
   /**
@@ -184,6 +191,10 @@ export 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;
   }
 
   /**
@@ -212,6 +223,9 @@ export class AudioManager {
    */
   setVolume(category: AudioCategoryName, volume: number): void {
     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();
   }
@@ -291,27 +305,20 @@ export class AudioManager {
    * @param factor - Volume multiplier (0..1), e.g. 0.3 = 30% of normal
    */
   duckMusic(factor: number): void {
-    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(): void {
-    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();
   }
 
   /**
@@ -357,12 +364,63 @@ export 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.
+   */
+  private musicGain(): number {
+    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. */
+  private applyMusicGain(): void {
+    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. */
+  private soundVolumeOf(alias: string): number {
+    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. */
+  private rampMusicFade(durationMs: number): void {
+    const token = this._musicFadeToken;
+    const start = Date.now();
+    const tick = (): void => {
+      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);
+  }
+
   private applyVolumes(): void {
     if (!this._soundModule) return;
     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 = this._masterGain; // master multiplies the global bus
+    this.applyMusicGain(); // category volume/mute reach the RUNNING track
   }
 
   private setupMobileUnlock(): void {

package/src/core/GameApplication.ts

@@ -11,7 +11,14 @@ import { AudioManager } from '../audio/AudioManager';
 import { InputManager } from '../input/InputManager';
 import { ViewportManager } from '../viewport/ViewportManager';
 import { LoadingScene } from '../loading/LoadingScene';
-import { createCSSPreloader, removeCSSPreloader } from '@energy8platform/platform-core/loading';
+import {
+  createCSSPreloader,
+  removeCSSPreloader,
+  adoptExternalOverlay,
+  advanceExternalOverlay,
+  releaseExternalOverlay,
+  hasExternalOverlay,
+} from '@energy8platform/platform-core/loading';
 import { FPSOverlay } from '../debug/FPSOverlay';
 
 /**
@@ -155,17 +162,40 @@ export class GameApplication extends EventEmitter<GameEngineEvents> {
     }
 
     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) {
@@ -178,12 +208,19 @@ export class GameApplication extends EventEmitter<GameEngineEvents> {
 
       // 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');
@@ -193,8 +230,13 @@ export class GameApplication extends EventEmitter<GameEngineEvents> {
       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) 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;
     }

package/src/host/buildConfig.ts

@@ -6,12 +6,18 @@ import type { SlotSpinResultBase } from '@energy8platform/platform-core/slot-res
 
 /**
  * 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.)
  */
 export function buildAppConfig<T extends SlotSpinResultBase = SlotSpinResultBase>(
   opts: CreateSlotGameOptions<T>,
   isStakeNow: boolean,
+  isArtubeNow = false,
 ): GameApplicationConfig {
   return {
     container: opts.container ?? '#game',
@@ -19,11 +25,18 @@ export function buildAppConfig<T extends SlotSpinResultBase = SlotSpinResultBase
     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,
   };
 }

package/src/host/createSlotGame.ts

@@ -5,13 +5,14 @@ import { buildAppConfig } from './buildConfig';
 import { loadFonts, applyTextureDefaults, bootGuard } from './preboot';
 import { showFatalError, installGlobalErrorHandlers } from './fatalError';
 import type { CreateSlotGameOptions, SlotGameHandle } from './types';
+import { releaseExternalOverlay } from '@energy8platform/platform-core/loading';
 import type { SlotSpinResultBase } from '@energy8platform/platform-core/slot-result';
 import type { ShellMode } from '@energy8platform/shell/pixi';
 import type { SceneApi, SlotSceneController, RenderContext } from './sceneController';
 import type { FreeSpinsView } from './freeSpinsCounter';
 
 /**
- * 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
@@ -29,6 +30,24 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
   let shell: SlotGameHandle['shell'] = null;
 
   const fatal = (message: string) => {
+    // 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
     // scaling) rather than the bare DOM fallback. Errors thrown before the shell boots (asset
@@ -100,7 +119,66 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
     }
   }
 
-  const game = new GameApplication(buildAppConfig(opts, isStakeNow));
+  let artubeBridge: SlotGameHandle['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: import('./types').ArtubeModule;
+    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);
@@ -174,6 +252,8 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
 
     const ps = game.platformSession;
     const balance = (game.initData?.balance as number | undefined) ?? 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: ShellMode = isReplay ? 'replay' : 'base';
     // initData.config carries the Stake bridge's currency/social/disclaimer surface (GameConfigData);
@@ -189,9 +269,16 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
         stake?: { defaultBetLevel?: number; minBet?: number; maxBet?: number };
         /** Set by the Stake bridge when `/wallet/authenticate` returned a still-open round. */
         activeRound?: { bet?: number; roundId?: string; mode?: string };
+        /** Artube's platform block. The default bet arrives as an INDEX into `config.betLevels`
+         *  (the platform's `allowed_bets`), where Stake states an amount. */
+        artube?: { defaultBetIndex?: number };
       };
-      /** Present only on a resume — the bridge synthesises it from the open round. */
+      /** Present only on a resume — the bridge synthesises it from the open round. Both the Stake
+       *  and the Artube bridge fill it the same way, so the resumed-bet path below is shared. */
       session?: { betAmount?: number };
+      /** Session currency CODE. The Artube bridge's only currency surface (the platform picks it
+       *  per session; demo sessions are 'FUN'); Stake sends full meta on `config.currency` instead. */
+      currency?: string;
       lang?: string;
     } | null;
     const config = initData?.config;
@@ -203,33 +290,44 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
     // 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 import('./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 */
       }
     }
     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,
@@ -238,10 +336,14 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
     // 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',
+        `createSlotGame: ${isStakeNow ? 'Stake' : 'Artube'} launch returned no config.betLevels — refusing to fall back to the spec ladder`,
       );
     }
     if (opts.dev) {
@@ -811,5 +913,5 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
     }
   }
 
-  return { game, stakeBridge, shell };
+  return { game, stakeBridge, artubeBridge, shell };
 }

package/src/host/index.ts

@@ -4,6 +4,9 @@ export type {
   CreateSlotGameOptions,
   SlotGameHandle,
   StakeIntegration,
+  ArtubeIntegration,
+  ArtubeModule,
+  ArtubeBridgeLike,
   SceneRegistration,
   SceneNavData,
   ShellFactory,