@energy8platform/shell 0.5.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@energy8platform/shell",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "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

@@ -18,6 +18,7 @@ import type {
   ThemeConfig,
   ModalOptions,
   ReplayModalOptions,
+  VolumeKey,
 } from './types';
 import type {
   ShellRenderer,
@@ -47,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',
@@ -70,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;
@@ -254,6 +257,7 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
     if (!this.overlay) return;
     this.overlay = null;
     this.soundRefresh = null;
+    this.volumeRefresh = null;
     this.renderer.closeOverlay();
   }
 
@@ -268,6 +272,23 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
     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;
@@ -293,10 +314,17 @@ export class ShellController extends EventEmitter<ShellEvents> implements ShellH
     this.prevBalance = n;
     this.money('balance', from, n);
   }
-  setWin(n: number): void {
+  /** Set the WIN readout. Counts up/down from the previous value by default. Pass
+   *  `{ animate: false }` to SNAP instantly (renderBar cancels any in-flight count-up) — used by the
+   *  host to clear WIN to 0 at spin start, where an animated count-DOWN would look wrong. */
+  setWin(n: number, opts?: { animate?: boolean }): void {
     const from = this.prevWin;
     this.state.win = n;
     this.prevWin = n;
+    if (opts?.animate === false) {
+      this.renderer.renderBar(); // instant repaint from state; cancels running money anims
+      return;
+    }
     this.money('win', from, n);
   }
   setBet(n: number): void {

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

@@ -15,9 +15,19 @@ export function createInitialState(config: ShellConfig): ShellState {
     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

@@ -4,6 +4,10 @@
  *  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;
   position: 'left' | 'right';
@@ -244,6 +248,10 @@ 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. */
@@ -264,7 +272,7 @@ export type ResolvedShellConfig = Required<
     | 'replay'
   >
 > &
-  Pick<ShellConfig, 'currentBet' | 'theme' | 'onBonusBuy'>;
+  Pick<ShellConfig, 'currentBet' | 'theme' | 'onBonusBuy' | 'volumes'>;
 
 export interface ShellState {
   mode: ShellMode;
@@ -287,6 +295,9 @@ export interface ShellState {
   /** 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.5.0';
+export const PACKAGE_VERSION = '0.6.1';

package/src/ui/html/components/Settings.ts

@@ -1,4 +1,5 @@
 import type { ShellHost } from '@/core/renderer';
+import type { VolumeKey } from '@/core/types';
 import { createOverlay } from '../primitives';
 import { icon } from '../icons';
 
@@ -27,25 +28,33 @@ export function openSettingsModal(host: ShellHost): HTMLElement {
   })();
   body.appendChild(sound);
 
-  // Volume sliders — full-width column rows with a live value readout
-  const slider = (key: string, label: string) => {
+  // Volume sliders — full-width column rows with a live value readout. Positions are read from the
+  // shell's stored volumes (not hardcoded to 100%), so reopening the overlay reflects the last set
+  // value, and `host.setVolume()` from game code updates them live via the registered refreshers.
+  const updaters: Partial<Record<VolumeKey, (v: number) => void>> = {};
+  const slider = (key: VolumeKey, label: string) => {
     const row = document.createElement('div'); row.className = 'ge-ov-row ge-col';
     const head = document.createElement('div'); head.className = 'ge-row-head';
-    const val = document.createElement('span'); val.className = 'ge-val'; val.textContent = '100%';
+    const val = document.createElement('span'); val.className = 'ge-val';
     head.innerHTML = `<span>${label}</span>`; head.appendChild(val);
     const input = document.createElement('input');
-    input.type = 'range'; input.min = '0'; input.max = '1'; input.step = '0.05'; input.value = '1';
+    input.type = 'range'; input.min = '0'; input.max = '1'; input.step = '0.05';
     input.className = 'ge-slider'; input.dataset.ge = `setting-${key}`;
+    const paint = (v: number) => { input.value = String(v); val.textContent = `${Math.round(v * 100)}%`; };
+    paint(host.getVolume(key));
     input.addEventListener('input', () => {
       val.textContent = `${Math.round(Number(input.value) * 100)}%`;
-      host.emit('settingChange', { key, value: Number(input.value) });
+      host.setVolume(key, Number(input.value));
     });
+    updaters[key] = paint;
     row.append(head, input);
     return row;
   };
   body.appendChild(slider('master', host.t('Master volume')));
   body.appendChild(slider('music', host.t('Music')));
   body.appendChild(slider('sfx', host.t('SFX')));
+  // Live-update sliders when volume changes via host.setVolume (shell clears on close).
+  host.setVolumeRefresh((key, v) => updaters[key]?.(v));
 
   // Game info — full-width row button that opens its own overlay
   const gameInfo = document.createElement('button');

package/src/ui/pixi/PixiRenderer.ts

@@ -75,6 +75,12 @@ export class PixiRenderer implements ShellRenderer {
     this.app.stage.eventMode = 'static';
 
     this.app.renderer.on('resize', this.onResize);
+    // Seed the layout from the CURRENT screen size. The renderer was resized to the container during
+    // boot (ViewportManager.refresh) BEFORE this shell mounted and subscribed above, so that initial
+    // 'resize' event is already gone and won't fire again on a stationary device. Without this seed
+    // the controller's layout stays at its 'wide' DEFAULT — a portrait mobile would show the DESKTOP
+    // bar. (The HTML renderer gets this for free: its ResizeObserver fires immediately on observe.)
+    if (this.screenW > 0) this.host.notifyResize(this.screenW, this.screenH);
     whenFontReady(() => {
       if (!this.destroyed) this.renderBar();
     });
@@ -333,6 +339,9 @@ export class PixiRenderer implements ShellRenderer {
       notifyResize: (w, h) => host.notifyResize(w, h),
       setSound: (on) => host.setSound(on),
       setSoundRefresh: (fn) => host.setSoundRefresh(fn),
+      getVolume: (key) => host.getVolume(key),
+      setVolume: (key, v) => host.setVolume(key, v),
+      setVolumeRefresh: (fn) => host.setVolumeRefresh(fn),
       // — Pixi-specific surface —
       get ticker() { return self.app.ticker; },
       get canvas() { return self.app.canvas as HTMLCanvasElement | undefined; },

package/src/ui/pixi/components/Settings.ts

@@ -1,4 +1,5 @@
 import { Container, Text } from 'pixi.js';
+import type { VolumeKey } from '@/core/types';
 import type { PixiComponentContext, ShellLayer } from '../context';
 import { Overlay } from '../primitives/overlay';
 import { makeText } from '../text';
@@ -40,10 +41,13 @@ function buildBody(host: PixiComponentContext, width: number): Container {
   });
   col.add(glassRow(host, [textNode(host, host.t('Sound')), new Spacer(), speaker]));
 
-  // Volume sliders
-  col.add(sliderRow(host, width, 'master', host.t('Master volume')));
-  col.add(sliderRow(host, width, 'music', host.t('Music')));
-  col.add(sliderRow(host, width, 'sfx', host.t('SFX')));
+  // Volume sliders — positions read from the shell's stored volumes (stateful across opens); the
+  // registered refreshers let `host.setVolume()` from game code move the thumbs live.
+  const updaters: Partial<Record<VolumeKey, (v: number) => void>> = {};
+  col.add(sliderRow(host, width, 'master', host.t('Master volume'), updaters));
+  col.add(sliderRow(host, width, 'music', host.t('Music'), updaters));
+  col.add(sliderRow(host, width, 'sfx', host.t('SFX'), updaters));
+  host.setVolumeRefresh?.((key, v) => updaters[key]?.(v));
 
   // Game info link
   const infoIcon = makeIcon('info', 22, '#ffffff');
@@ -94,7 +98,13 @@ function glassRow(host: PixiComponentContext, children: Container[], opts: { but
 }
 
 /** A column row: head (label + live % value) over a draggable slider. */
-function sliderRow(host: PixiComponentContext, bodyWidth: number, key: string, label: string): FlexBox {
+function sliderRow(
+  host: PixiComponentContext,
+  bodyWidth: number,
+  key: VolumeKey,
+  label: string,
+  updaters: Partial<Record<VolumeKey, (v: number) => void>>,
+): FlexBox {
   const row = new FlexBox({
     direction: 'column',
     align: 'stretch',
@@ -103,14 +113,19 @@ function sliderRow(host: PixiComponentContext, bodyWidth: number, key: string, l
     background: { fill: host.tokens.plaqueGlass, radius: 16 },
   });
   const head = new FlexBox({ direction: 'row', align: 'center', justify: 'space-between' });
-  const valueText = makeText('100%', { size: 13, weight: '700', color: host.tokens.plaqueLabel });
+  const initial = host.getVolume(key);
+  const valueText = makeText(`${Math.round(initial * 100)}%`, { size: 13, weight: '700', color: host.tokens.plaqueLabel });
   head.add(makeText(label, { size: 14, weight: '600', color: '#ffffff' }));
   head.add(new Spacer(), { grow: 1 });
   head.add(valueText);
-  const slider = new Slider(host, 1, (v) => {
+  const slider = new Slider(host, initial, (v) => {
     valueText.text = `${Math.round(v * 100)}%`;
-    host.emit('settingChange', { key, value: v });
+    host.setVolume(key, v);
   });
+  updaters[key] = (v) => {
+    valueText.text = `${Math.round(v * 100)}%`;
+    slider.setValue(v);
+  };
   row.add(head);
   row.add(slider);
   return row;

package/src/ui/pixi/primitives/controls.ts

@@ -182,6 +182,13 @@ export class Slider extends Container implements Sizable {
     this.hitArea = new Rectangle(0, 0, this.w, h);
   }
 
+  /** Programmatically move the thumb (0..1) without firing onInput — for live updates driven by
+   *  `host.setVolume()` while the overlay is open. */
+  setValue(v: number): void {
+    this._value = Math.max(0, Math.min(1, v));
+    this.draw();
+  }
+
   setLayoutSize(w: number | undefined): void {
     if (w != null) this.w = w;
     this.draw();