@energy8platform/shell 0.4.1 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@energy8platform/shell",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Energy8 branded game shell — one logic core, pluggable html/pixi renderers behind a stable contract.",
   "type": "module",
   "main": "./dist/index.cjs.js",

package/src/core/ShellController.ts

@@ -6,14 +6,32 @@ import { createI18n, type I18n } from './i18n';
 import { KeyboardController, type KeyboardHost } from './keyboard';
 import { PACKAGE_VERSION } from './version';
 import type {
-  ShellConfig, ResolvedShellConfig, ShellState, ShellEvents, ShellMode,
-  AutoplayOptions, FreeSpinsState, BonusOption, ThemeConfig, ModalOptions, ReplayModalOptions,
+  ShellConfig,
+  ResolvedShellConfig,
+  ShellState,
+  ShellEvents,
+  ShellMode,
+  AutoplayOptions,
+  FreeSpinsState,
+  BonusReadout,
+  BonusOption,
+  ThemeConfig,
+  ModalOptions,
+  ReplayModalOptions,
+  VolumeKey,
 } from './types';
 import type {
-  ShellRenderer, ShellHost, ShellActions, OverlayHandle, OverlayRequest, ShellLayoutMode,
+  ShellRenderer,
+  ShellHost,
+  ShellActions,
+  OverlayHandle,
+  OverlayRequest,
+  ShellLayoutMode,
 } from './renderer';
 
-export interface CreateShellOptions extends ShellConfig { renderer: ShellRenderer; }
+export interface CreateShellOptions extends ShellConfig {
+  renderer: ShellRenderer;
+}
 
 /** Apply defaults to the raw config (the mount target lives on the renderer, not here). */
 export function resolveConfig(config: ShellConfig): ResolvedShellConfig {
@@ -30,6 +48,7 @@ export function resolveConfig(config: ShellConfig): ResolvedShellConfig {
     features: config.features,
     theme: config.theme,
     onBonusBuy: config.onBonusBuy,
+    volumes: config.volumes,
     version: config.version ?? '1.0.0',
     isSocial: config.isSocial ?? false,
     replay: config.replay ?? config.mode === 'replay',
@@ -53,6 +72,7 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
   private kbd?: KeyboardController;
   private overlay: OverlayHandle | null = null;
   private soundRefresh: ((on: boolean) => void) | null = null;
+  private volumeRefresh: ((key: VolumeKey, value: number) => void) | null = null;
   private prevBalance: number;
   private prevWin: number;
   private destroyed = false;
@@ -79,12 +99,21 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
   }
 
   // ── ShellHost ──────────────────────────────────────────────────────────────
-  t(text: string): string { return this.i18n.t(text); }
-  formatCurrency(n: number, win = false): string { return formatCurrency(n, this.config.currency, win); }
-  formatWin(value: number): string { return this.formatCurrency(value, true); }
+  t(text: string): string {
+    return this.i18n.t(text);
+  }
+  formatCurrency(n: number, win = false): string {
+    return formatCurrency(n, this.config.currency, win);
+  }
+  formatWin(value: number): string {
+    return this.formatCurrency(value, true);
+  }
   notifyResize(w: number, h: number): void {
     const layout: ShellLayoutMode = w !== 0 && h > w ? 'mobile' : 'wide';
-    if (layout !== this.layout) { this.layout = layout; this.renderer.setLayout(layout); }
+    if (layout !== this.layout) {
+      this.layout = layout;
+      this.renderer.setLayout(layout);
+    }
     this.renderer.renderBar();
   }
 
@@ -94,7 +123,9 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
       stepBet: (dir) => {
         const next = stepBet(this.state, dir);
         if (next === this.state.bet) return;
-        this.state.bet = next; this.emit('betChange', next); this.renderer.renderBar();
+        this.state.bet = next;
+        this.emit('betChange', next);
+        this.renderer.renderBar();
       },
       setBet: (n) => {
         if (n !== this.state.bet) {
@@ -105,7 +136,9 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
       },
       cycleTurbo: () => {
         const next = nextTurbo(this.state.turbo, this.config.features.turbo);
-        this.state.turbo = next; this.emit('turboChange', next); this.renderer.renderBar();
+        this.state.turbo = next;
+        this.emit('turboChange', next);
+        this.renderer.renderBar();
       },
       toggleAutoplay: () => {
         if (this.state.autoplay.active) a.stopAutoplay();
@@ -113,11 +146,13 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
       },
       startAutoplay: (remaining) => {
         this.state.autoplay = { active: true, remaining };
-        this.emit('autoplayStart', { active: true, remaining }); this.renderer.renderBar();
+        this.emit('autoplayStart', { active: true, remaining });
+        this.renderer.renderBar();
       },
       stopAutoplay: () => {
         this.state.autoplay = { active: false, remaining: 0 };
-        this.emit('autoplayStop'); this.renderer.renderBar();
+        this.emit('autoplayStop');
+        this.renderer.renderBar();
       },
       openMenu: () => this.openMenu(),
       openSettings: () => this.openSettings(),
@@ -138,12 +173,24 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
     // eslint-disable-next-line @typescript-eslint/no-this-alias
     const self = this;
     const host: KeyboardHost = {
-      get state() { return self.state; },
-      get hotkeysEnabled() { return self.config.features.hotkeys !== false; },
-      get spacebarEnabled() { return self.config.features.spacebar !== false; },
-      get turboLevels() { return self.config.features.turbo; },
-      get autoplayEnabled() { return self.config.features.autoplay != null; },
-      get buyBonusEnabled() { return self.config.features.buyBonus !== false; },
+      get state() {
+        return self.state;
+      },
+      get hotkeysEnabled() {
+        return self.config.features.hotkeys !== false;
+      },
+      get spacebarEnabled() {
+        return self.config.features.spacebar !== false;
+      },
+      get turboLevels() {
+        return self.config.features.turbo;
+      },
+      get autoplayEnabled() {
+        return self.config.features.autoplay != null;
+      },
+      get buyBonusEnabled() {
+        return self.config.features.buyBonus !== false;
+      },
       hasOpenLayer: () => self.overlay !== null,
       routeToLayer: (e) => self.overlay?.onKey?.(e) ?? false,
       spin: () => self.actions.spin(),
@@ -160,26 +207,57 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
     this.kbd.attach();
   }
 
-  private pullFocus = (): void => { try { (globalThis as { focus?: () => void }).focus?.(); } catch { /* cross-origin */ } };
+  private pullFocus = (): void => {
+    try {
+      (globalThis as { focus?: () => void }).focus?.();
+    } catch {
+      /* cross-origin */
+    }
+  };
 
   // ── overlay flow ─────────────────────────────────────────────────────────────
   private show(req: OverlayRequest): void {
     this.closeModal();
     this.overlay = this.renderer.openOverlay(req) ?? null;
   }
-  openMenu(): void { this.emit('menuOpen'); this.openSettings(); }
-  openSettings(): void { this.emit('settingsOpen'); this.show({ kind: 'settings' }); }
-  openInfo(): void { this.emit('infoOpen'); this.show({ kind: 'gameInfo' }); }
-  openBuyBonus(): void { if (this.config.onBonusBuy) { this.config.onBonusBuy(); return; } this.show({ kind: 'buyBonus' }); }
-  openBetPicker(): void { this.show({ kind: 'betPicker' }); }
-  openAutoplayPicker(): void { this.show({ kind: 'autoplayPicker' }); }
-  openReplay(opts: ReplayModalOptions): void { if (this.destroyed) return; this.show({ kind: 'replay', opts }); }
-  openModal(opts: ModalOptions): void { this.show({ kind: 'modal', opts }); }
+  openMenu(): void {
+    this.emit('menuOpen');
+    this.openSettings();
+  }
+  openSettings(): void {
+    this.emit('settingsOpen');
+    this.show({ kind: 'settings' });
+  }
+  openInfo(): void {
+    this.emit('infoOpen');
+    this.show({ kind: 'gameInfo' });
+  }
+  openBuyBonus(): void {
+    if (this.config.onBonusBuy) {
+      this.config.onBonusBuy();
+      return;
+    }
+    this.show({ kind: 'buyBonus' });
+  }
+  openBetPicker(): void {
+    this.show({ kind: 'betPicker' });
+  }
+  openAutoplayPicker(): void {
+    this.show({ kind: 'autoplayPicker' });
+  }
+  openReplay(opts: ReplayModalOptions): void {
+    if (this.destroyed) return;
+    this.show({ kind: 'replay', opts });
+  }
+  openModal(opts: ModalOptions): void {
+    this.show({ kind: 'modal', opts });
+  }
   /** Programmatically dismiss whatever overlay/modal is open. No-op when nothing is shown. */
   closeModal(): void {
     if (!this.overlay) return;
     this.overlay = null;
     this.soundRefresh = null;
+    this.volumeRefresh = null;
     this.renderer.closeOverlay();
   }
 
@@ -190,16 +268,39 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
     this.soundRefresh?.(on);
     this.renderer.refreshSoundIcon?.(on);
   }
-  setSoundRefresh(fn: ((on: boolean) => void) | null): void { this.soundRefresh = fn; }
+  setSoundRefresh(fn: ((on: boolean) => void) | null): void {
+    this.soundRefresh = fn;
+  }
+
+  // ── volume ─────────────────────────────────────────────────────────────────
+  getVolume(key: VolumeKey): number {
+    return this.state.volumes[key];
+  }
+  /** 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 {
+    const v = Math.max(0, Math.min(1, value));
+    this.state.volumes[key] = v;
+    this.emit('settingChange', { key, value: v });
+    this.volumeRefresh?.(key, v);
+  }
+  setVolumeRefresh(fn: ((key: VolumeKey, value: number) => void) | null): void {
+    this.volumeRefresh = fn;
+  }
 
   // ── features ─────────────────────────────────────────────────────────────────
   activateFeature(bonus: BonusOption): void {
-    this.state.activeFeature = bonus; this.emit('featureActivate', { id: bonus.id }); this.renderer.renderBar();
+    this.state.activeFeature = bonus;
+    this.emit('featureActivate', { id: bonus.id });
+    this.renderer.renderBar();
   }
   deactivateFeature(): void {
     const prev = this.state.activeFeature;
     if (!prev) return;
-    this.state.activeFeature = null; this.emit('featureDeactivate', { id: prev.id }); this.renderer.renderBar();
+    this.state.activeFeature = null;
+    this.emit('featureDeactivate', { id: prev.id });
+    this.renderer.renderBar();
   }
 
   // ── game-facing public API (mirrors GameShell/PixiGameShell) ───────────────────
@@ -207,19 +308,79 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
     this.renderer.renderBar();
     if (to !== from) this.renderer.animateMoney(field, from, to);
   }
-  setBalance(n: number): void { const from = this.prevBalance; this.state.balance = n; this.prevBalance = n; this.money('balance', from, n); }
-  setWin(n: number): void { const from = this.prevWin; this.state.win = n; this.prevWin = n; this.money('win', from, n); }
-  setBet(n: number): void { this.state.bet = n; this.renderer.renderBar(); }
-  setMode(mode: ShellMode): void { if (mode === 'replay') this.state.replay = true; this.state.mode = mode; this.renderer.renderBar(); }
-  setBusy(busy: boolean): void { this.state.busy = busy; this.renderer.renderBar(); this.kbd?.notifyBusyChanged(busy); }
-  setAutoplay(a: AutoplayOptions): void { this.state.autoplay = a; this.renderer.renderBar(); }
-  setTurbo(level: number): void { this.state.turbo = level; this.renderer.renderBar(); }
-  setBuyBonusEnabled(enabled: boolean): void { this.state.buyBonusEnabled = enabled; this.renderer.renderBar(); }
-  setFreeSpins(fs: FreeSpinsState): void { this.state.freeSpins = fs; this.renderer.renderBar(); }
-  setTheme(theme: ThemeConfig): void { this.config.theme = theme; this.tokens = resolveTheme(theme); this.renderer.applyTheme(this.tokens); this.renderer.renderBar(); }
-  setLanguage(lang: string): void { this.config.language = lang; this.i18n = createI18n({ language: lang, isSocial: this.config.isSocial }); this.renderer.renderBar(); }
-  setSocial(isSocial: boolean): void { this.config.isSocial = isSocial; this.i18n = createI18n({ language: this.config.language, isSocial }); this.renderer.renderBar(); }
-  setLayout(layout: ShellLayoutMode): void { if (layout === this.layout) return; this.layout = layout; this.renderer.setLayout(layout); this.renderer.renderBar(); }
+  setBalance(n: number): void {
+    const from = this.prevBalance;
+    this.state.balance = n;
+    this.prevBalance = n;
+    this.money('balance', from, n);
+  }
+  setWin(n: number): void {
+    const from = this.prevWin;
+    this.state.win = n;
+    this.prevWin = n;
+    this.money('win', from, n);
+  }
+  setBet(n: number): void {
+    this.state.bet = n;
+    this.renderer.renderBar();
+  }
+  setMode(mode: ShellMode): void {
+    if (mode === 'replay') this.state.replay = true;
+    this.state.mode = mode;
+    this.renderer.renderBar();
+  }
+  setBusy(busy: boolean): void {
+    this.state.busy = busy;
+    this.renderer.renderBar();
+    this.kbd?.notifyBusyChanged(busy);
+  }
+  setAutoplay(a: AutoplayOptions): void {
+    this.state.autoplay = a;
+    this.renderer.renderBar();
+  }
+  setTurbo(level: number): void {
+    this.state.turbo = level;
+    this.renderer.renderBar();
+  }
+  setBuyBonusEnabled(enabled: boolean): void {
+    this.state.buyBonusEnabled = enabled;
+    this.renderer.renderBar();
+  }
+  setFreeSpins(fs: FreeSpinsState): void {
+    this.state.freeSpins = fs;
+    this.state.bonus = null;
+    this.renderer.renderBar();
+  }
+  /** 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 {
+    this.state.bonus = { label: b.label, value: b.value };
+    this.state.freeSpins = { ...this.state.freeSpins, totalWin: b.totalWin };
+    this.renderer.renderBar();
+  }
+  setTheme(theme: ThemeConfig): void {
+    this.config.theme = theme;
+    this.tokens = resolveTheme(theme);
+    this.renderer.applyTheme(this.tokens);
+    this.renderer.renderBar();
+  }
+  setLanguage(lang: string): void {
+    this.config.language = lang;
+    this.i18n = createI18n({ language: lang, isSocial: this.config.isSocial });
+    this.renderer.renderBar();
+  }
+  setSocial(isSocial: boolean): void {
+    this.config.isSocial = isSocial;
+    this.i18n = createI18n({ language: this.config.language, isSocial });
+    this.renderer.renderBar();
+  }
+  setLayout(layout: ShellLayoutMode): void {
+    if (layout === this.layout) return;
+    this.layout = layout;
+    this.renderer.setLayout(layout);
+    this.renderer.renderBar();
+  }
 
   destroy(): Promise<void> {
     if (this.destroyed) return Promise.resolve();

package/src/core/renderer.ts

@@ -2,7 +2,7 @@ import type { EventEmitter } from './EventEmitter';
 import type { ShellTokens } from './theme';
 import type {
   ResolvedShellConfig, ShellState, ShellEvents, BonusOption,
-  ModalOptions, ReplayModalOptions,
+  ModalOptions, ReplayModalOptions, VolumeKey,
 } from './types';
 
 export type ShellLayoutMode = 'wide' | 'mobile';
@@ -77,6 +77,13 @@ export 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;
 }

package/src/core/state.ts

@@ -13,10 +13,21 @@ export function createInitialState(config: ShellConfig): ShellState {
     turbo: 0,
     buyBonusEnabled: true,
     freeSpins: { current: 0, total: 0, totalWin: 0 },
+    bonus: null,
     activeFeature: null,
+    volumes: {
+      master: clampVolume(config.volumes?.master),
+      music: clampVolume(config.volumes?.music),
+      sfx: clampVolume(config.volumes?.sfx),
+    },
   };
 }
 
+/** Clamp a configured volume to 0..1, defaulting to full (1) when unset/invalid. */
+export function clampVolume(v: number | undefined): number {
+  return typeof v === 'number' && Number.isFinite(v) ? Math.max(0, Math.min(1, v)) : 1;
+}
+
 /** Step bet up/down within availableBets, clamped at the ends. */
 export function stepBet(state: ShellState, direction: 1 | -1): number {
   const idx = state.availableBets.indexOf(state.bet);

package/src/core/types.ts

@@ -1,4 +1,12 @@
-export 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). */
+export type ShellMode = 'base' | 'bonus' | 'freeSpins' | 'replay';
+
+/** The three independent volume sliders shown in the Settings overlay. */
+export type VolumeKey = 'master' | 'music' | 'sfx';
+export type VolumeLevels = Record<VolumeKey, number>;
 
 export interface CurrencyConfig {
   symbol: string;
@@ -162,6 +170,20 @@ export interface FreeSpinsState {
   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. */
+export 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. */
 export interface ModalAction {
   title: string;
@@ -226,12 +248,31 @@ export 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. */
-export type ResolvedShellConfig = Required<Pick<ShellConfig,
-  'language' | 'currency' | 'availableBets' | 'defaultBet' | 'balance' | 'win' | 'mode' | 'features' | 'gameInfo' | 'version' | 'isSocial' | 'replay'>>
-  & Pick<ShellConfig, 'currentBet' | 'theme' | 'onBonusBuy'>;
+export type ResolvedShellConfig = Required<
+  Pick<
+    ShellConfig,
+    | 'language'
+    | 'currency'
+    | 'availableBets'
+    | 'defaultBet'
+    | 'balance'
+    | 'win'
+    | 'mode'
+    | 'features'
+    | 'gameInfo'
+    | 'version'
+    | 'isSocial'
+    | 'replay'
+  >
+> &
+  Pick<ShellConfig, 'currentBet' | 'theme' | 'onBonusBuy' | 'volumes'>;
 
 export interface ShellState {
   mode: ShellMode;
@@ -248,9 +289,15 @@ export 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 | 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;
 }
 
 export interface ShellEvents {

package/src/core/version.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED by scripts/gen-version.mjs — do not edit. Mirrors package.json "version".
 /** The @energy8platform/shell package version, stamped into the game-info footer. */
-export const PACKAGE_VERSION = '0.4.1';
+export const PACKAGE_VERSION = '0.6.0';