@energy8platform/game-engine 0.18.0 → 0.20.0

package/dist/host.d.ts

@@ -1,8 +1,9 @@
 import { Container, ApplicationOptions, Application, Texture } from 'pixi.js';
 import { GameModel } from '@energy8platform/platform-core/game-spec';
 import { LoadingScreenConfig, AssetManifest, PlatformSession } from '@energy8platform/platform-core';
+import { CurrencyConfig, GameInfoContent, BonusOption, ShellFeatures, ShellMode, PixiShellConfig, PixiGameShell } from '@energy8platform/pixi-shell';
 import * as _energy8platform_platform_core_shell from '@energy8platform/platform-core/shell';
-import { CurrencyConfig, GameInfoContent, BonusOption, ShellFeatures, ShellMode, ShellConfig, GameShell } from '@energy8platform/platform-core/shell';
+import { Lang } from '@energy8platform/platform-core/shell';
 export { socialize } from '@energy8platform/platform-core/shell';
 import { BookAdapter, AdapterModule, StakeBridge } from '@energy8platform/stake-bridge';
 import { CasinoGameSDK, InitData, GameConfigData, SessionData } from '@energy8platform/game-sdk';
@@ -333,6 +334,7 @@ declare class AudioManager {
     private _persist;
     private _storageKey;
     private _categories;
+    private _masterGain;
     private _currentMusic;
     private _unlocked;
     private _unlockHandler;
@@ -373,6 +375,10 @@ declare class AudioManager {
      * Stop all sounds.
      */
     stopAll(): void;
+    /** Global gain (0..1) folded into every category's effective volume. Driven by the shell's
+     *  'master' settingChange. Does not affect the persisted per-category volumes. */
+    setMasterVolume(volume: number): void;
+    getMasterVolume(): number;
     /**
      * Set volume for a category.
      */
@@ -575,6 +581,7 @@ declare class ViewportManager extends EventEmitter<ViewportEvents> {
     private _app;
     private _container;
     private _config;
+    private _target;
     private _resizeObserver;
     private _currentOrientation;
     private _currentWidth;
@@ -582,7 +589,7 @@ declare class ViewportManager extends EventEmitter<ViewportEvents> {
     private _currentScale;
     private _destroyed;
     private _resizeTimeout;
-    constructor(app: Application, container: HTMLElement, config: ViewportConfig);
+    constructor(app: Application, container: HTMLElement, config: ViewportConfig, target?: Container);
     /** Current canvas width in game units */
     get width(): number;
     /** Current canvas height in game units */
@@ -683,6 +690,12 @@ declare class GameApplication extends EventEmitter<GameEngineEvents> {
     input: InputManager;
     /** Viewport manager */
     viewport: ViewportManager;
+    /** Scaled world root (holds scenes). Transformed by the ViewportManager to fit the design
+     *  resolution; lives below the UI layer on app.stage. */
+    worldRoot: Container;
+    /** Unscaled, screen-space UI layer. Sits above {@link worldRoot} and is NOT touched by the
+     *  viewport transform — children fill the real screen (e.g. the host's shell + overlay). */
+    uiLayer: Container;
     /** SDK instance (null in offline mode) */
     sdk: CasinoGameSDK | null;
     /** FPS overlay instance (only when debug: true) */
@@ -737,7 +750,6 @@ interface WinTier {
 }
 
 interface SlotShellOptions {
-    mount?: HTMLElement;
     /** Override the derived currency (normally taken from initData). */
     currency?: CurrencyConfig;
     /** Author-supplied info sections, MERGED over the host-derived set by section identity (an author
@@ -754,6 +766,11 @@ interface SlotShellOptions {
     buyBonus?: BonusOption[];
     tiers?: WinTier[];
     features?: Partial<ShellFeatures>;
+    /** Per-game translation map. Keys are the English source strings (from the spec or copy);
+     *  values are the translated strings for each language. Merged with the shell's built-in
+     *  `LOCALES` catalog — game strings take precedence over the built-in entries for the same key.
+     *  When not supplied, English source strings pass through verbatim (socialised in social mode). */
+    i18n?: Partial<Record<Lang, Record<string, string>>>;
 }
 /** Runtime context from the SDK handshake (initData) + the resolved mode. */
 interface ShellRuntime {
@@ -795,8 +812,9 @@ interface JurisdictionRestrictions {
 /** Total stake for an action = bet × the action's cost multiplier (1 for a base spin; e.g. 100 for
  *  a buy bonus). The host uses this to block a play the balance can't cover. */
 declare function stakeForAction(model: GameModel, action: string, bet: number): number;
-/** Pure: assemble a ShellConfig from the model + runtime context (currency/balance/language/mode). */
-declare function buildShellConfig(opts: SlotShellOptions, model: GameModel, runtime: ShellRuntime): ShellConfig;
+/** Pure: assemble the shell config (sans mount target) from the model + runtime context
+ *  (currency/balance/language/mode). The host adds `app` at the call site. */
+declare function buildShellConfig(opts: SlotShellOptions, model: GameModel, runtime: ShellRuntime): Omit<PixiShellConfig, 'app' | 'parent'>;
 
 interface StakeIntegration {
     /** The game's BookAdapter (or its module). modeMap + gameId come from the model. */
@@ -849,12 +867,15 @@ interface CreateSlotGameOptions<T extends SlotSpinResultBase = SlotSpinResultBas
     dev?: boolean;
     stake?: StakeIntegration;
     shell?: SlotShellOptions;
+    /** Double-tap on the play area to skip the current spin animation. Default `true`. Set `false`
+     *  to disable the gesture (e.g. games where a tap means something else). */
+    skipGesture?: boolean;
     onFatalError?: (message: string) => void;
 }
 interface SlotGameHandle {
     game: GameApplication;
     stakeBridge: StakeBridge | null;
-    shell: GameShell | null;
+    shell: PixiGameShell | null;
 }
 
 /**
@@ -882,34 +903,104 @@ declare function resolveReplayBonusId(model: GameModel, stakeMode: string): stri
  */
 declare function resolveStartScene(scenes: SceneRegistration[], isReplay: boolean, explicitStart?: string): string;
 
-/** Everything a scene needs to render one result. The host builds it once per round. */
+/** Everything a scene needs to render one segment. The host builds it per segment. */
 interface RenderContext {
-    /** Bet for this round (major units). Stable for the whole round (a bonus is one round). */
+    /** Bet for this round (major units). Stable for the whole round. */
     bet: number;
-    /** Trigger action in the game's own vocabulary (gameSpec.actions keys): 'spin' | 'ante' |
-     *  'buy_bonus' | … Stable for the whole round. */
+    /** Trigger action in the game's own vocabulary ('spin' | 'ante' | 'buy_bonus' | …). */
     action: string;
-    /** Stake bet-mode of the round (model.spec.modeMap[action]): 'BASE' | 'ANTE' | 'BONUS' | …
-     *  Canonical per-round identifier of WHICH bonus/feature this is. Stable for the whole round. */
+    /** Stake bet-mode of the round ('BASE' | 'ANTE' | 'BONUS' | …). */
     mode: string;
-    /** Currency-aware money formatter. win/totalWin get variable decimals (0.0041 stays 0.0041). */
+    /** Currency-aware money formatter. */
     formatAmount(value: number): string;
-    /** LIVE turbo level (0 = off, 1..3 = escalating speed), matching the shell's state.turbo. Read at
-     *  the moment of access (getter) so a mid-round toggle is reflected. */
+    /** LIVE turbo level (0 = off, 1..3 = escalating speed). Read at access. */
     readonly turbo: number;
+    /** Aborted when the player skips this segment (double-tap). The scene's async pacing can race or
+     *  cancel on it; on abort the scene must collapse to the segment's final visual state. */
+    signal: AbortSignal;
 }
-/** The contract a slot scene implements. The HOST owns the play→present→ack→drain loop and calls
- *  these; the scene only renders. The game never sees play/ack/roundId. */
+/** Playback-only audio handle. Volume/mute are shell settings → host, never the scene. */
+interface SceneAudio {
+    play(alias: string, opts?: {
+        volume?: number;
+        loop?: boolean;
+        speed?: number;
+    }): void;
+    playMusic(alias: string, fadeMs?: number): void;
+    stopMusic(): void;
+    duck(factor: number): void;
+    unduck(): void;
+}
+interface OverlayShowOptions {
+    /** Draw the overlay content into `container` (sized to the canvas). */
+    build(container: Container, size: {
+        width: number;
+        height: number;
+    }): void;
+    /** Auto-close after N ms (combine with closeOn — whichever fires first). */
+    autoCloseMs?: number;
+    /** Dismiss on a single tap. Default 'tap'. Set false to require an explicit close(). */
+    closeOn?: 'tap' | false;
+    /** Optional host-drawn backdrop alpha (0..1). Default: none (game draws its own). */
+    dim?: number;
+}
+/** Single host-owned layer above scene + shell. Eats pointer events so shell controls are
+ *  unreachable while open. */
+interface SceneOverlay {
+    /** Resolves when the overlay closes. Rejects if one is already open. */
+    show(opts: OverlayShowOptions): Promise<void>;
+    close(): void;
+}
+interface SceneShell {
+    /** Live insets (px). `bottom` = the shell bar height; read inside onResize. */
+    readonly safeArea: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+}
+interface AutoplaySceneState {
+    running: boolean;
+    remaining: number;
+}
+/** Stable capabilities injected once via onCreate. */
+interface SceneApi {
+    audio: SceneAudio;
+    overlay: SceneOverlay;
+    shell: SceneShell;
+    formatAmount(value: number): string;
+    readonly bet: number;
+    readonly mode: string;
+    readonly turbo: number;
+}
+/** The contract a slot scene implements. The HOST owns the play→present→ack→drain loop and the
+ *  shell; the scene only renders + reacts. The core spin-lifecycle hooks are REQUIRED (implement
+ *  them — empty bodies are fine where a game has nothing to do); the incidental reactions below
+ *  stay optional. */
 interface SlotSceneController<T extends SlotSpinResultBase = SlotSpinResultBase> {
-    /** Render ONE segment (a spin, or one free spin). All pacing/pauses/overlays live here
-     *  (await your own animations). The host calls this once per segment. */
-    present(result: T, ctx: RenderContext): Promise<void>;
-    /** Optional. Fires EXACTLY before the first free spin of a bonus (intro; spin counts in
-     *  trigger.freeSpins). */
-    onBonusEnter?(trigger: T, ctx: RenderContext): Promise<void>;
-    /** Optional. Fires after the last free spin of a bonus (summary; last.totalWin = bonus total). */
-    onBonusExit?(last: T, ctx: RenderContext): Promise<void>;
+    /** Injected ONCE before the first round — capabilities, subscriptions, one-time setup. */
+    onCreate(api: SceneApi): void;
+    /** Fires once per round when the player presses spin (before the network result). */
+    onSpinStart(): void;
+    /** Render ONE segment (a spin or one free spin). Await your own pacing. */
+    onSpin(result: T, ctx: RenderContext): Promise<void>;
+    /** Fires when ctx.mode changes between segments (entering a non-BASE mode/bonus). */
+    onEnterMode(result: T, ctx: RenderContext): Promise<void>;
+    /** Fires when leaving a mode (back toward BASE). */
+    onExitMode(result: T, ctx: RenderContext): Promise<void>;
+    /** Fires once per round after the full drain (controls unlocked). */
+    onSpinEnd(result: T, ctx: RenderContext): void;
+    /** Shell events (may fire while idle) — optional. */
+    onBetChanged?(bet: number): void;
+    onTurboChanged?(level: number): void;
+    onAutoplayChanged?(state: AutoplaySceneState): void;
+    /** Double-tap skip during an active onSpin (gated by the skipGesture setting). */
+    onSkip?(): void;
+    /** Tab focus lost / regained. */
+    onPause?(): void;
+    onResume?(): void;
 }
 
 export { buildShellConfig, createSlotGame, resolveReplayBonusId, resolveStartScene, stakeForAction };
-export type { CreateSlotGameOptions, RenderContext, SceneEntry, SceneNavData, SceneRegistration, SlotGameHandle, SlotSceneController, SlotShellOptions, StakeIntegration };
+export type { AutoplaySceneState, CreateSlotGameOptions, OverlayShowOptions, RenderContext, SceneApi, SceneAudio, SceneEntry, SceneNavData, SceneOverlay, SceneRegistration, SceneShell, SlotGameHandle, SlotSceneController, SlotShellOptions, StakeIntegration };