@energy8platform/game-engine 0.34.2 → 0.35.0

package/dist/host.d.ts

@@ -337,6 +337,12 @@ declare class AudioManager {
     private _categories;
     private _masterGain;
     private _currentMusic;
+    /** Duck factor (0..1) from duckMusic/unduckMusic. A presentation state, not a player setting. */
+    private _musicDuck;
+    /** Crossfade ramp (0..1) for the track that is fading IN. 1 whenever no fade is running. */
+    private _musicFade;
+    /** Generation counter so a superseded crossfade ramp stops writing over the new track's. */
+    private _musicFadeToken;
     private _unlocked;
     private _unlockHandler;
     constructor(config?: AudioConfig);
@@ -430,6 +436,25 @@ declare class AudioManager {
      * Smoothly fade a sound's volume from `fromVol` to `toVol` over `durationMs`.
      */
     private fadeVolume;
+    /**
+     * 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;
+    /** Push `musicGain()` at the current track. Safe before it starts playing and with none playing. */
+    private applyMusicGain;
+    /** Current SOUND-layer volume of `alias`, or 0 when it cannot be read. */
+    private soundVolumeOf;
+    /** 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;
     private applyVolumes;
     private setupMobileUnlock;
     private removeMobileUnlock;
@@ -871,6 +896,55 @@ interface StakeIntegration {
     /** The game's BookAdapter (or its module). modeMap + gameId come from the model. */
     adapter: BookAdapter | AdapterModule;
 }
+/** The live Artube bridge, structurally. Kept minimal so game-engine never has to import
+ *  `@energy8platform/artube-bridge` — see `ArtubeIntegration.load`. */
+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. */
+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. */
+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). */
@@ -915,6 +989,10 @@ interface CreateSlotGameOptions<T extends SlotSpinResultBase = SlotSpinResultBas
     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`. */
@@ -937,11 +1015,13 @@ type ShellFactory = (config: PixiShellConfig) => Shell;
 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;
 }
 
 /**
- * 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
@@ -1136,4 +1216,4 @@ interface SlotSceneController<T extends SlotSpinResultBase = SlotSpinResultBase>
 }
 
 export { buildShellConfig, createSlotGame, createWinReporter, resolveReplayBonusId, resolveStartScene, stakeForAction };
-export type { AutoplaySceneState, CreateSlotGameOptions, OverlayShowOptions, RenderContext, SceneApi, SceneAudio, SceneNavData, SceneOverlay, SceneRegistration, SceneShell, ShellFactory, SlotGameHandle, SlotSceneController, SlotShellOptions, StakeIntegration, WinReportOptions, WinReporter };
+export type { ArtubeBridgeLike, ArtubeIntegration, ArtubeModule, AutoplaySceneState, CreateSlotGameOptions, OverlayShowOptions, RenderContext, SceneApi, SceneAudio, SceneNavData, SceneOverlay, SceneRegistration, SceneShell, ShellFactory, SlotGameHandle, SlotSceneController, SlotShellOptions, StakeIntegration, WinReportOptions, WinReporter };