@energy8platform/shell 0.4.1 → 0.6.0

package/dist/pixi.d.ts

@@ -18,7 +18,14 @@ declare class EventEmitter<TEvents extends {}> {
     removeAllListeners(event?: keyof TEvents): this;
 }
 
-type ShellMode = 'base' | 'freeSpins' | 'replay';
+/** `freeSpins` and `bonus` are the SAME bar layout (host-driven hero + Total Win); `freeSpins` is
+ *  kept as a back-compat alias for the common case (its readout is derived current/total), while
+ *  `bonus` pairs with `setBonus()` to show a game-supplied label + value (adventure, hold-and-spin,
+ *  respins — anything that isn't a plain free-spins counter). */
+type ShellMode = 'base' | 'bonus' | 'freeSpins' | 'replay';
+/** The three independent volume sliders shown in the Settings overlay. */
+type VolumeKey = 'master' | 'music' | 'sfx';
+type VolumeLevels = Record<VolumeKey, number>;
 interface CurrencyConfig {
     symbol: string;
     position: 'left' | 'right';
@@ -207,6 +214,19 @@ interface FreeSpinsState {
     total: number;
     totalWin: number;
 }
+/** A game-supplied bonus readout for the bar hero, set via `setBonus()`. Generalizes the
+ *  free-spins counter: the shell renders `label` (localized via the shell translator, so a game
+ *  i18n entry for it is honoured) + `value` (a pre-formatted string, shown verbatim — "2 / 10",
+ *  "3", "×5", "7 coins") + the Total Win accumulator. The shell stays free of any per-game bonus
+ *  concept — the label/value semantics live in the game/host. */
+interface BonusReadout {
+    /** Bar label, e.g. 'Free spins' | 'Adventure' | 'Hold & Spin'. Run through the shell translator. */
+    label: string;
+    /** Pre-formatted counter value shown verbatim (NOT translated). */
+    value: string;
+    /** Cumulative bonus win for the Total Win readout. */
+    totalWin: number;
+}
 /** One footer button of a generic modal. Clicking it runs `on` (if any), then closes the modal. */
 interface ModalAction {
     title: string;
@@ -267,9 +287,13 @@ interface ShellConfig {
      *  opening the built-in buy-bonus overlay (e.g. the game shows its own bonus UI). The button
      *  is shown whenever this OR `features.buyBonus` is set. */
     onBonusBuy?: () => void;
+    /** Initial Settings-overlay volume slider positions (each 0..1, defaults to 1 = 100%). The shell
+     *  keeps them stateful across opens; read/update at runtime via `shell.getVolume()` /
+     *  `shell.setVolume()`, and listen to `settingChange` ({ key: 'master'|'music'|'sfx' }) to apply. */
+    volumes?: Partial<VolumeLevels>;
 }
 /** ShellConfig after the controller applies defaults (version, isSocial, replay, theme). No mount. */
-type ResolvedShellConfig = Required<Pick<ShellConfig, 'language' | 'currency' | 'availableBets' | 'defaultBet' | 'balance' | 'win' | 'mode' | 'features' | 'gameInfo' | 'version' | 'isSocial' | 'replay'>> & Pick<ShellConfig, 'currentBet' | 'theme' | 'onBonusBuy'>;
+type ResolvedShellConfig = Required<Pick<ShellConfig, 'language' | 'currency' | 'availableBets' | 'defaultBet' | 'balance' | 'win' | 'mode' | 'features' | 'gameInfo' | 'version' | 'isSocial' | 'replay'>> & Pick<ShellConfig, 'currentBet' | 'theme' | 'onBonusBuy' | 'volumes'>;
 interface ShellState {
     mode: ShellMode;
     /** Sticky replay marker — true for a historical-round replay, regardless of the current
@@ -285,9 +309,18 @@ interface ShellState {
     turbo: number;
     buyBonusEnabled: boolean;
     freeSpins: FreeSpinsState;
+    /** Game-supplied bonus label + value override (from `setBonus()`). When null the bar derives the
+     *  readout from `freeSpins` (label 'Free spins', value current/total) — the back-compat default. */
+    bonus: {
+        label: string;
+        value: string;
+    } | null;
     /** The currently activated `feature` option (e.g. Ante), or null. Drives the
      *  effective-bet readout tint and the BUY BONUS → DISABLE toggle on the bar. */
     activeFeature: BonusOption$1 | null;
+    /** Volume slider positions (0..1) surfaced in the Settings overlay. Stateful across opens so a
+     *  reopened overlay reflects the last-set positions instead of resetting to 100%. */
+    volumes: VolumeLevels;
 }
 interface ShellEvents {
     spin: void;
@@ -410,6 +443,13 @@ interface ShellHost {
     setSound(on: boolean): void;
     /** An open Settings overlay registers an icon updater here (null clears it on close). */
     setSoundRefresh(fn: ((on: boolean) => void) | null): void;
+    /** Current volume slider position (0..1) for master/music/sfx. */
+    getVolume(key: VolumeKey): number;
+    /** Set a volume slider (0..1): clamps, stores, emits `settingChange`, and live-updates an open
+     *  Settings overlay. Called by the slider control on drag AND by game code as the public API. */
+    setVolume(key: VolumeKey, value: number): void;
+    /** An open Settings overlay registers a slider updater here (null clears it on close). */
+    setVolumeRefresh(fn: ((key: VolumeKey, value: number) => void) | null): void;
     /** Logic-bearing actions invoked by renderer controls. */
     readonly actions: ShellActions;
 }
@@ -473,13 +513,14 @@ declare class ShellController extends EventEmitter<ShellEvents> implements Shell
     tokens: ShellTokens;
     layout: ShellLayoutMode;
     soundOn: boolean;
-    readonly engineVersion = "0.4.1";
+    readonly engineVersion = "0.6.0";
     readonly actions: ShellActions;
     private renderer;
     private i18n;
     private kbd?;
     private overlay;
     private soundRefresh;
+    private volumeRefresh;
     private prevBalance;
     private prevWin;
     private destroyed;
@@ -504,6 +545,12 @@ declare class ShellController extends EventEmitter<ShellEvents> implements Shell
     closeModal(): void;
     setSound(on: boolean): void;
     setSoundRefresh(fn: ((on: boolean) => void) | null): void;
+    getVolume(key: VolumeKey): number;
+    /** Set a volume slider (0..1). Shared by the slider control (drag) and game code (public API):
+     *  clamps, stores so a reopened Settings overlay reflects it, emits `settingChange`, and
+     *  live-updates the slider if the overlay is currently open. */
+    setVolume(key: VolumeKey, value: number): void;
+    setVolumeRefresh(fn: ((key: VolumeKey, value: number) => void) | null): void;
     activateFeature(bonus: BonusOption$1): void;
     deactivateFeature(): void;
     private money;
@@ -516,6 +563,10 @@ declare class ShellController extends EventEmitter<ShellEvents> implements Shell
     setTurbo(level: number): void;
     setBuyBonusEnabled(enabled: boolean): void;
     setFreeSpins(fs: FreeSpinsState): void;
+    /** Generic bonus readout (adventure / hold-and-spin / respins). Sets a game-supplied label+value
+     *  override for the bar hero and folds `totalWin` into the shared accumulator. Pairs with
+     *  `setMode('bonus')`. `setFreeSpins()` clears the override back to the derived current/total. */
+    setBonus(b: BonusReadout): void;
     setTheme(theme: ThemeConfig): void;
     setLanguage(lang: string): void;
     setSocial(isSocial: boolean): void;
@@ -539,7 +590,7 @@ interface I18n {
 declare function createI18n(opts: I18nOptions): I18n;
 
 /** The @energy8platform/shell package version, stamped into the game-info footer. */
-declare const PACKAGE_VERSION = "0.4.1";
+declare const PACKAGE_VERSION = "0.6.0";
 
 /** A shell: the renderer-agnostic controller plus the surface facade (safeArea/barHeight/setVisible)
  *  an embedding host reads. `createShell`, `createGameShell` and `createPixiShell` all return this. */
@@ -679,4 +730,4 @@ declare function createPixiShell(config: PixiShellConfig): PixiGameShell;
 declare function removePixiShell(): Promise<void>;
 
 export { DEFAULT_ACCENT, PACKAGE_VERSION, PixiRenderer, SCHEMES, ShellController, createI18n, createPixiShell, createShell, normalizeLang, removePixiShell, resolveConfig, resolveTheme, socialize };
-export type { AutoplayConfig, AutoplayOptions, BonusCardContext, BonusOption, CellRef, CreateShellOptions, CurrencyConfig, FreeSpinsState, GameInfoContent, GameInfoSection, GameMode, I18n, I18nOptions, Lang, ModalAction, ModalOptions, OverlayHandle, OverlayRequest, PaylineDef, PaytableRow, PixiGameShell, PixiShellConfig, PixiShellSurface, ReplayModalOptions, ResolvedShellConfig, SafeArea, ShapeDef, Shell, ShellActions, ShellConfig, ShellEvents, ShellFeatures, ShellHost, ShellLayoutMode, ShellMode, ShellRenderer, ShellState, ShellSurface, ShellTokens, ThemeConfig, WinSection };
+export type { AutoplayConfig, AutoplayOptions, BonusCardContext, BonusOption, BonusReadout, CellRef, CreateShellOptions, CurrencyConfig, FreeSpinsState, GameInfoContent, GameInfoSection, GameMode, I18n, I18nOptions, Lang, ModalAction, ModalOptions, OverlayHandle, OverlayRequest, PaylineDef, PaytableRow, PixiGameShell, PixiShellConfig, PixiShellSurface, ReplayModalOptions, ResolvedShellConfig, SafeArea, ShapeDef, Shell, ShellActions, ShellConfig, ShellEvents, ShellFeatures, ShellHost, ShellLayoutMode, ShellMode, ShellRenderer, ShellState, ShellSurface, ShellTokens, ThemeConfig, VolumeKey, VolumeLevels, WinSection };