@energy8platform/game-engine 0.17.0 → 0.19.0

package/src/slot/anim/CascadeController.ts

@@ -0,0 +1,102 @@
+// packages/game-engine/src/slot/anim/CascadeController.ts
+import { Tween } from '../../animation';
+import { EASING_BY_NAME } from './easing-map';
+import type { ReelGrid } from '../grid/ReelGrid';
+import type { CellData } from '../grid/SymbolCell';
+
+export interface CascadeStepData {
+  winningCells: { col: number; row: number }[];
+  removedCells: { col: number; row: number }[];
+  newCells: { col: number; row: number; symbol: string }[];
+  settledGrid: CellData[][];
+}
+export interface CascadeTimings { reveal: number; highlight: number; remove: number; drop: number; refill: number; wait: number; }
+export interface CascadeAnim {
+  col: number; row: number;
+  phase: 'reveal' | 'highlight' | 'remove' | 'drop' | 'refill';
+  from?: { x: number; y: number };
+  to?: { x: number; y: number };
+  scale?: number;
+  alpha?: number;
+  duration: number;
+  easing?: string;
+  delay?: number;
+}
+
+const DEFAULT_TIMINGS: CascadeTimings = { reveal: 300, highlight: 400, remove: 250, drop: 200, refill: 220, wait: 150 };
+
+export class CascadeController {
+  private _grid: ReelGrid;
+  private _t: CascadeTimings;
+  private _killed = false;
+
+  constructor(grid: ReelGrid, timings?: Partial<CascadeTimings>) {
+    this._grid = grid;
+    this._t = { ...DEFAULT_TIMINGS, ...(timings ?? {}) };
+  }
+
+  /** PURE: ordered animation descriptors for a cascade step. */
+  plan(step: CascadeStepData, opts?: { turbo?: boolean }): CascadeAnim[] {
+    const f = opts?.turbo ? 0.5 : 1;
+    const out: CascadeAnim[] = [];
+
+    for (const w of step.winningCells) {
+      out.push({ col: w.col, row: w.row, phase: 'highlight', scale: 1.08, duration: this._t.highlight * f, easing: 'easeOutQuad' });
+    }
+    for (const w of step.winningCells) {
+      out.push({ col: w.col, row: w.row, phase: 'remove', scale: 0, alpha: 0, duration: this._t.remove * f, easing: 'easeInBack' });
+    }
+    // new cells drop from two row-heights above their target, staggered per column.
+    // Row height is derived purely from public geometry (no private grid access).
+    const rowStep = this._grid.cellPosition(0, 1).y - this._grid.cellPosition(0, 0).y;
+    const perCol: Record<number, number> = {};
+    for (const n of step.newCells) {
+      const to = this._grid.cellPosition(n.col, n.row);
+      const from = { x: to.x, y: to.y - rowStep * 2 };
+      const idx = (perCol[n.col] = (perCol[n.col] ?? 0) + 1);
+      out.push({ col: n.col, row: n.row, phase: 'drop', from, to, duration: this._t.drop * f, easing: 'easeOutBounce', delay: idx * 30 * f });
+    }
+    return out;
+  }
+
+  /** Execute the plan via Tween. Not unit-tested (Ticker doesn't tick in node). */
+  async run(step: CascadeStepData, opts?: { turbo?: boolean }): Promise<void> {
+    this._killed = false;
+    const plan = this.plan(step, opts);
+    // highlight + remove first
+    for (const a of plan.filter((p) => p.phase === 'highlight')) {
+      if (this._killed) return;
+      const cell = this._grid.getCell(a.col, a.row);
+      cell.setState({ winning: true });
+      await Tween.to(cell, { 'scale.x': a.scale!, 'scale.y': a.scale! }, a.duration, EASING_BY_NAME[a.easing ?? 'easeOutQuad']);
+    }
+    for (const a of plan.filter((p) => p.phase === 'remove')) {
+      if (this._killed) return;
+      const cell = this._grid.getCell(a.col, a.row);
+      await Tween.to(cell, { 'scale.x': 0, 'scale.y': 0, alpha: 0 }, a.duration, EASING_BY_NAME[a.easing ?? 'easeInBack']);
+    }
+    // settle data, then drop new cells in
+    this._grid.setGrid(step.settledGrid);
+    await Promise.all(
+      plan.filter((p) => p.phase === 'drop').map(async (a) => {
+        if (this._killed) return;
+        const cell = this._grid.getCell(a.col, a.row);
+        cell.alpha = 1; cell.scale.set(1);
+        cell.position.set(a.from!.x, a.from!.y);
+        if (a.delay) await Tween.delay(a.delay);
+        await Tween.to(cell, { 'position.y': a.to!.y }, a.duration, EASING_BY_NAME[a.easing ?? 'easeOutBounce']);
+      }),
+    );
+  }
+
+  private _killOwnTweens(): void {
+    for (let c = 0; c < this._grid.cols; c++) {
+      for (let r = 0; r < this._grid.rows; r++) {
+        Tween.killTweensOf(this._grid.getCell(c, r));
+      }
+    }
+  }
+
+  skip(): void { this._killOwnTweens(); }
+  kill(): void { this._killed = true; this._killOwnTweens(); }
+}

package/src/slot/anim/ReelSpinController.ts

@@ -0,0 +1,81 @@
+// packages/game-engine/src/slot/anim/ReelSpinController.ts
+import { Tween, Easing } from '../../animation';
+import type { ReelGrid } from '../grid/ReelGrid';
+import type { CellData } from '../grid/SymbolCell';
+
+export interface ReelSpinData { targetGrid: CellData[][]; strip?: (reel: number) => string[]; }
+export interface ReelSpinTimings { spinUp: number; hold: number; stopStagger: number; settle: number; }
+export interface ReelStopPlan {
+  reel: number;
+  stopTime: number;
+  landing: CellData[];
+  settle: { amp: number; ms: number };
+}
+
+const DEFAULT_TIMINGS: ReelSpinTimings = { spinUp: 500, hold: 200, stopStagger: 120, settle: 240 };
+
+export class ReelSpinController {
+  private _grid: ReelGrid;
+  private _t: ReelSpinTimings;
+  private _killed = false;
+
+  constructor(grid: ReelGrid, timings?: Partial<ReelSpinTimings>) {
+    this._grid = grid;
+    this._t = { ...DEFAULT_TIMINGS, ...(timings ?? {}) };
+  }
+
+  /** PURE: per-reel stop timing + landing window. No Pixi mutation. */
+  plan(data: ReelSpinData, opts?: { turbo?: boolean }): ReelStopPlan[] {
+    const f = opts?.turbo ? 0.5 : 1;
+    const out: ReelStopPlan[] = [];
+    for (let reel = 0; reel < this._grid.cols; reel++) {
+      out.push({
+        reel,
+        stopTime: this._t.spinUp * f + reel * this._t.stopStagger * f,
+        landing: data.targetGrid[reel] ?? [],
+        settle: { amp: 7, ms: this._t.settle * f },
+      });
+    }
+    return out;
+  }
+
+  /** Execute the spin: scroll each reel, decelerate, land on target, settle-bounce. Not unit-tested. */
+  async run(data: ReelSpinData, opts?: { turbo?: boolean }): Promise<void> {
+    this._killed = false;
+    const plan = this.plan(data, opts);
+    await Promise.all(
+      plan.map(async (p) => {
+        if (this._killed) return;
+        const strip = data.strip?.(p.reel) ?? p.landing.map((c) => c.symbol ?? '');
+        // texture-swap spin: cycle symbols quickly while decelerating, then land
+        const cells = Array.from({ length: this._grid.rows }, (_, r) => this._grid.getCell(p.reel, r));
+        const ticks = Math.max(6, Math.floor(p.stopTime / 60));
+        for (let i = 0; i < ticks; i++) {
+          if (this._killed) break;
+          for (let r = 0; r < cells.length; r++) {
+            const sym = strip[(i + r) % strip.length] || null;
+            cells[r].setData({ symbol: sym });
+          }
+          await Tween.delay(Math.min(60, p.stopTime / ticks));
+        }
+        // land on the real target
+        for (let r = 0; r < cells.length; r++) cells[r].setData(p.landing[r] ?? { symbol: null });
+        // settle bounce on the column parent
+        if (!this._killed && cells[0]?.parent) {
+          const colY = cells[0].parent.y;
+          await Tween.fromTo(cells[0].parent, { y: colY - p.settle.amp }, { y: colY }, p.settle.ms, Easing.easeOutBack);
+        }
+      }),
+    );
+  }
+
+  private _killOwnTweens(): void {
+    for (let c = 0; c < this._grid.cols; c++) {
+      for (let r = 0; r < this._grid.rows; r++) {
+        Tween.killTweensOf(this._grid.getCell(c, r));
+      }
+    }
+  }
+
+  skip(): void { this._killed = true; this._killOwnTweens(); }
+}

package/src/slot/anim/easing-map.ts

@@ -0,0 +1,14 @@
+// packages/game-engine/src/slot/anim/easing-map.ts
+import { Easing } from '../../animation';
+import type { EasingFunction } from '../../types';
+
+/** Resolve a descriptor's string easing name to the engine's easing function. */
+export const EASING_BY_NAME: Record<string, EasingFunction> = {
+  linear: Easing.linear,
+  easeOutQuad: Easing.easeOutQuad,
+  easeOutCubic: Easing.easeOutCubic,
+  easeOutBack: Easing.easeOutBack,
+  easeOutBounce: Easing.easeOutBounce,
+  easeInBack: Easing.easeInBack,
+  easeInOutCubic: Easing.easeInOutCubic,
+};

package/src/slot/freeSpins/FreeSpinsSession.ts

@@ -0,0 +1,40 @@
+import type { SlotSpinResultBase } from '@energy8platform/platform-core/slot-result';
+
+export interface FreeSpinsSessionConfig {
+  initialSpins: number;
+  /** Optional: extra spins to award from a result (retrigger). Default: none. */
+  retrigger?: (result: SlotSpinResultBase) => number;
+  /** Optional hard exit (e.g. max-win reached). */
+  isMaxWin?: () => boolean;
+}
+
+/** Headless free-spins state machine. The scene drives it; rendering/HUD reflect it. */
+export class FreeSpinsSession {
+  remaining: number;
+  total: number;
+  totalWin = 0;
+  private readonly cfg: FreeSpinsSessionConfig;
+
+  constructor(cfg: FreeSpinsSessionConfig) {
+    this.cfg = cfg;
+    this.remaining = cfg.initialSpins;
+    this.total = cfg.initialSpins;
+  }
+
+  award(extra: number): void {
+    if (extra > 0) { this.remaining += extra; this.total += extra; }
+  }
+
+  /** Convenience: award using the configured retrigger rule. */
+  applyRetrigger(result: SlotSpinResultBase): void {
+    this.award(this.cfg.retrigger?.(result) ?? 0);
+  }
+
+  addWin(amount: number): void { this.totalWin += amount; }
+
+  consume(): void { if (this.remaining > 0) this.remaining -= 1; }
+
+  get isComplete(): boolean {
+    return this.remaining <= 0 || (this.cfg.isMaxWin?.() ?? false);
+  }
+}

package/src/slot/grid/AnimatedSymbol.ts

@@ -0,0 +1,68 @@
+import { Container, Sprite, AnimatedSprite, type Texture } from 'pixi.js';
+import { SpriteAnimation } from '../../animation';
+import type { SymbolView } from './SymbolView';
+
+export interface SymbolTextures { base: Texture; idle?: Texture[]; win?: Texture[]; }
+export interface AnimatedSymbolConfig { textures: SymbolTextures; size: number; fps?: number; }
+
+/** Built-in SymbolView: a static base sprite with optional idle/win spritesheet frames. */
+export class AnimatedSymbol extends Container implements SymbolView {
+  private _base: Sprite;
+  private _anim: AnimatedSprite | null = null;
+  private _textures: SymbolTextures;
+  private _size: number;
+  private _fps: number;
+
+  constructor(config: AnimatedSymbolConfig) {
+    super();
+    this._textures = config.textures;
+    this._size = config.size;
+    this._fps = config.fps ?? 24;
+    this._base = new Sprite(config.textures.base);
+    this._base.anchor.set(0.5);
+    this.addChild(this._base);
+    this.resize(this._size);
+  }
+
+  setTextures(t: SymbolTextures): void {
+    this._textures = t;
+    this._base.texture = t.base;
+    this.showStatic();
+  }
+
+  resize(size: number): void {
+    this._size = size;
+    this._base.width = size;
+    this._base.height = size;
+    if (this._anim) { this._anim.width = size; this._anim.height = size; }
+  }
+
+  showStatic(): void {
+    if (this._anim) { this._anim.destroy(); this._anim = null; }
+    this._base.visible = true;
+  }
+
+  playIdle(): void {
+    if (!this._textures.idle?.length) return;
+    this._swap(this._textures.idle, true);
+  }
+
+  playWin(): Promise<void> {
+    if (!this._textures.win?.length) return Promise.resolve();
+    return new Promise<void>((resolve) => {
+      this._swap(this._textures.win!, false, () => { this.showStatic(); resolve(); });
+    });
+  }
+
+  private _swap(frames: Texture[], loop: boolean, onComplete?: () => void): void {
+    if (this._anim) { this._anim.destroy(); this._anim = null; }
+    this._base.visible = false;
+    const a = SpriteAnimation.create(frames, { loop, autoPlay: true, onComplete });
+    a.anchor.set(0.5);
+    a.width = this._size;
+    a.height = this._size;
+    a.animationSpeed = this._fps / 60;
+    this.addChild(a);
+    this._anim = a;
+  }
+}

package/src/slot/grid/ReelGrid.ts

@@ -0,0 +1,92 @@
+import { Container, Graphics, Sprite, type Texture } from 'pixi.js';
+import { SymbolCell, type CellData, type CellFrameStyle } from './SymbolCell';
+import type { SymbolResolver } from './SymbolView';
+
+export interface DecorationConfig { texture?: Texture; padding?: number; }
+export interface ReelGridConfig {
+  cols: number; rows: number; cellSize: number; gap?: number;
+  resolve: SymbolResolver; frameStyle?: CellFrameStyle;
+  decoration?: DecorationConfig;
+  mask?: boolean;
+}
+
+export class ReelGrid extends Container {
+  readonly __uiComponent = true as const;
+
+  private _cols: number;
+  private _rows: number;
+  private _cellSize: number;
+  private _gap: number;
+  private _cells: SymbolCell[][] = [];
+  private _cellLayer = new Container();
+
+  constructor(config: ReelGridConfig) {
+    super();
+    this._cols = config.cols;
+    this._rows = config.rows;
+    this._cellSize = config.cellSize;
+    this._gap = config.gap ?? 0;
+
+    if (config.decoration) {
+      const pad = config.decoration.padding ?? 0;
+      const w = this._cols * (this._cellSize + this._gap) - this._gap + pad * 2;
+      const h = this._rows * (this._cellSize + this._gap) - this._gap + pad * 2;
+      if (config.decoration.texture) {
+        const deco = new Sprite(config.decoration.texture);
+        deco.width = w; deco.height = h; deco.position.set(-pad - this._cellSize / 2, -pad - this._cellSize / 2);
+        this.addChild(deco);
+      }
+    }
+
+    this.addChild(this._cellLayer);
+
+    for (let c = 0; c < this._cols; c++) {
+      this._cells[c] = [];
+      for (let r = 0; r < this._rows; r++) {
+        const cell = new SymbolCell({ size: this._cellSize, resolve: config.resolve, frameStyle: config.frameStyle });
+        const { x, y } = this.cellPosition(c, r);
+        cell.position.set(x, y);
+        this._cellLayer.addChild(cell);
+        this._cells[c][r] = cell;
+      }
+    }
+
+    if (config.mask) {
+      const w = this._cols * (this._cellSize + this._gap) - this._gap;
+      const h = this._rows * (this._cellSize + this._gap) - this._gap;
+      const m = new Graphics()
+        .rect(-this._cellSize / 2, -this._cellSize / 2, w, h)
+        .fill(0xffffff);
+      this._cellLayer.mask = m;
+      this.addChild(m);
+    }
+  }
+
+  get cols(): number { return this._cols; }
+  get rows(): number { return this._rows; }
+
+  cellPosition(col: number, row: number): { x: number; y: number } {
+    const step = this._cellSize + this._gap;
+    return { x: col * step, y: row * step };
+  }
+
+  getCell(col: number, row: number): SymbolCell { return this._cells[col][row]; }
+
+  setGrid(cells: CellData[][]): void {
+    for (let c = 0; c < this._cols; c++) {
+      for (let r = 0; r < this._rows; r++) {
+        this._cells[c]?.[r]?.setData(cells[c]?.[r] ?? { symbol: null });
+      }
+    }
+  }
+
+  resize(cellSize: number): void {
+    this._cellSize = cellSize;
+    for (let c = 0; c < this._cols; c++) {
+      for (let r = 0; r < this._rows; r++) {
+        const { x, y } = this.cellPosition(c, r);
+        this._cells[c][r].position.set(x, y);
+      }
+    }
+  }
+}

package/src/slot/grid/SymbolCell.ts

@@ -0,0 +1,127 @@
+import { Container, Graphics, Text } from 'pixi.js';
+import { Tween, Easing } from '../../animation';
+import type { SymbolResolver, SymbolView } from './SymbolView';
+
+export interface CellFrameStyle {
+  radius?: number;
+  idle?: { color: number; alpha: number };
+  winning?: { color: number; alpha: number };
+  removed?: { color: number; alpha: number };
+  fresh?: { color: number; alpha: number };
+}
+export interface CellData {
+  symbol: string | null;
+  multiplier?: number;
+  bonus?: number;
+  sticky?: { remaining: number };
+}
+export interface CellState { winning?: boolean; removed?: boolean; fresh?: boolean; }
+export interface SymbolCellConfig { size: number; resolve: SymbolResolver; frameStyle?: CellFrameStyle; }
+
+const DEFAULT_STYLE: Required<CellFrameStyle> = {
+  radius: 8,
+  idle: { color: 0x223047, alpha: 0.34 },
+  winning: { color: 0x00d4ff, alpha: 0.95 },
+  removed: { color: 0x223047, alpha: 0.12 },
+  fresh: { color: 0xffffff, alpha: 0.6 },
+};
+
+export class SymbolCell extends Container {
+  readonly __uiComponent = true as const;
+
+  private _size: number;
+  private _resolve: SymbolResolver;
+  private _style: Required<CellFrameStyle>;
+  private _frame: Graphics;
+  private _view: SymbolView | null = null;
+  private _badges = new Container();
+  private _multBadge: Container | null = null;
+  private _bonusBadge: Container | null = null;
+  /** Last applied state key — exposed for tests/inspection. */
+  frameStyleKey: 'idle' | 'winning' | 'removed' | 'fresh' = 'idle';
+
+  constructor(config: SymbolCellConfig) {
+    super();
+    this._size = config.size;
+    this._resolve = config.resolve;
+    this._style = { ...DEFAULT_STYLE, ...(config.frameStyle ?? {}) } as Required<CellFrameStyle>;
+    this._frame = new Graphics();
+    this.addChild(this._frame);
+    this.addChild(this._badges);
+    this._drawFrame('idle');
+  }
+
+  get view(): SymbolView | null { return this._view; }
+
+  setData(data: CellData): void {
+    // symbol view
+    if (data.symbol == null) {
+      if (this._view) { this._view.destroy(); this._view = null; }
+    } else {
+      if (this._view) { this._view.destroy(); this._view = null; }
+      const v = this._resolve(data.symbol);
+      if (v) {
+        v.resize?.(this._size);
+        this.addChildAt(v, 1); // above frame, below badges
+        this._view = v;
+      }
+    }
+    // badges
+    this._setMultiplier(data.multiplier);
+    this._setBonus(data.bonus);
+  }
+
+  setState(state: CellState): void {
+    const key = state.winning ? 'winning' : state.removed ? 'removed' : state.fresh ? 'fresh' : 'idle';
+    this.frameStyleKey = key;
+    this._drawFrame(key);
+  }
+
+  playWin(): Promise<void> {
+    if (this._view?.playWin) return this._view.playWin();
+    // default: scale pop
+    const target = this._view ?? this;
+    return Tween.to(target, { 'scale.x': 1.15, 'scale.y': 1.15 }, 160, Easing.easeOutBack)
+      .then(() => Tween.to(target, { 'scale.x': 1, 'scale.y': 1 }, 140, Easing.easeOutQuad));
+  }
+
+  playIdle(): void { this._view?.playIdle?.(); }
+
+  hasBadge(kind: 'multiplier' | 'bonus'): boolean {
+    return kind === 'multiplier' ? this._multBadge != null : this._bonusBadge != null;
+  }
+
+  private _drawFrame(key: 'idle' | 'winning' | 'removed' | 'fresh'): void {
+    const s = this._style[key];
+    this._frame.clear();
+    this._frame
+      .roundRect(-this._size / 2, -this._size / 2, this._size, this._size, this._style.radius)
+      .fill({ color: s.color, alpha: s.alpha });
+    // store the colour as tint for cheap inspection/testing
+    this._frame.tint = s.color;
+  }
+
+  private _setMultiplier(value?: number): void {
+    if (this._multBadge) { this._multBadge.destroy(); this._multBadge = null; }
+    if (!value || value <= 1) return;
+    this._multBadge = this._badge(`×${value}`, 0xffd24a);
+    this._multBadge.position.set(this._size / 2 - 12, -this._size / 2 + 12);
+    this._badges.addChild(this._multBadge);
+  }
+
+  private _setBonus(value?: number): void {
+    if (this._bonusBadge) { this._bonusBadge.destroy(); this._bonusBadge = null; }
+    if (!value || value <= 0) return;
+    this._bonusBadge = this._badge(`+${value}`, 0x7ad7ff);
+    this._bonusBadge.position.set(-this._size / 2 + 12, -this._size / 2 + 12);
+    this._badges.addChild(this._bonusBadge);
+  }
+
+  private _badge(label: string, color: number): Container {
+    const c = new Container();
+    const t = new Text({ text: label, style: { fontSize: 18, fill: color, fontWeight: '700' } });
+    t.anchor.set(0.5);
+    c.addChild(t);
+    return c;
+  }
+}

package/src/slot/grid/SymbolView.ts

@@ -0,0 +1,13 @@
+import type { Container } from 'pixi.js';
+
+/** A symbol's visual. Any Container; optionally implements the lifecycle the cell drives. */
+export interface SymbolView extends Container {
+  playIdle?(): void;
+  playWin?(): Promise<void>;
+  showStatic?(): void;
+  /** Resize the symbol to the given cell size in pixels. */
+  resize?(size: number): void;
+}
+
+/** Game-supplied factory: build the view for a symbol id (sprite / layered sprites / Spine / composite). */
+export type SymbolResolver = (symbolId: string) => SymbolView | null;

package/src/slot/index.ts

@@ -0,0 +1,21 @@
+export type { SymbolView, SymbolResolver } from './grid/SymbolView';
+export { AnimatedSymbol } from './grid/AnimatedSymbol';
+export type { SymbolTextures, AnimatedSymbolConfig } from './grid/AnimatedSymbol';
+export { SymbolCell } from './grid/SymbolCell';
+export type { CellFrameStyle, CellData, CellState, SymbolCellConfig } from './grid/SymbolCell';
+export { ReelGrid } from './grid/ReelGrid';
+export type { DecorationConfig, ReelGridConfig } from './grid/ReelGrid';
+export { CascadeController } from './anim/CascadeController';
+export type { CascadeStepData, CascadeTimings, CascadeAnim } from './anim/CascadeController';
+export { ReelSpinController } from './anim/ReelSpinController';
+export type { ReelSpinData, ReelSpinTimings, ReelStopPlan } from './anim/ReelSpinController';
+export { pickTier, tierIndexAtValue } from './overlay/tiers';
+export type { WinTier } from './overlay/tiers';
+export { valueAt, CountUpDisplay } from './overlay/CountUpDisplay';
+export type { CountUpConfig } from './overlay/CountUpDisplay';
+export { BigWinOverlay } from './overlay/BigWinOverlay';
+export type { BigWinOverlayConfig } from './overlay/BigWinOverlay';
+export { FreeSpinsSession } from './freeSpins/FreeSpinsSession';
+export type { FreeSpinsSessionConfig } from './freeSpins/FreeSpinsSession';
+export { MultiplierAccumulator } from './multiplier/MultiplierAccumulator';
+export type { CarryPolicy } from './multiplier/MultiplierAccumulator';

package/src/slot/multiplier/MultiplierAccumulator.ts

@@ -0,0 +1,29 @@
+/** The boundary at which a collected multiplier resets. */
+export type CarryPolicy = 'spin' | 'cascade' | 'session';
+
+// How long each policy survives: cascade (shortest) < spin < session (longest).
+const RANK: Record<CarryPolicy, number> = { cascade: 0, spin: 1, session: 2 };
+
+/**
+ * Headless sticky/collector multiplier — the unified abstraction behind
+ * kitsunebi / recipe / orb / stage multipliers. reset(boundary) clears the
+ * value only when the boundary is at or above the configured policy scope.
+ */
+export class MultiplierAccumulator {
+  value: number;
+  private readonly base: number;
+  private readonly policy: CarryPolicy;
+
+  constructor(cfg: { policy: CarryPolicy; base?: number }) {
+    this.policy = cfg.policy;
+    this.base = cfg.base ?? 1;
+    this.value = this.base;
+  }
+
+  add(delta: number): void { this.value += delta; }
+  set(value: number): void { this.value = value; }
+
+  reset(boundary: CarryPolicy): void {
+    if (RANK[boundary] >= RANK[this.policy]) this.value = this.base;
+  }
+}

package/src/slot/overlay/BigWinOverlay.ts

@@ -0,0 +1,89 @@
+import { Container, Graphics, Sprite, Text } from 'pixi.js';
+import { Tween, Easing } from '../../animation';
+import { pickTier, tierIndexAtValue, type WinTier } from './tiers';
+import { CountUpDisplay } from './CountUpDisplay';
+
+export interface BigWinOverlayConfig {
+  tiers: WinTier[];
+  formatMoney: (v: number) => string;
+  countUpDuration?: (win: number) => number;
+  particleCount?: number;
+  width: number;
+  height: number;
+}
+
+const DEFAULT_DURATION = (win: number) => Math.min(2500, Math.max(800, win * 20));
+
+export class BigWinOverlay extends Container {
+  readonly __uiComponent = true as const;
+
+  private _cfg: BigWinOverlayConfig;
+  private _dim: Graphics;
+  private _banner: Sprite | null = null;
+  private _title: Text;
+  private _count: CountUpDisplay;
+
+  constructor(config: BigWinOverlayConfig) {
+    super();
+    this._cfg = config;
+    this.visible = false;
+
+    this._dim = new Graphics();
+    this.addChild(this._dim);
+
+    this._title = new Text({ text: '', style: { fontFamily: 'sans-serif', fontSize: 72, fill: 0xffffff, fontWeight: '900' } });
+    this._title.anchor.set(0.5);
+    this.addChild(this._title);
+
+    this._count = new CountUpDisplay({ format: config.formatMoney });
+    this.addChild(this._count);
+
+    this.resize(config.width, config.height);
+  }
+
+  /** Pure helper (testable): the tier title for a given win/bet, or null below the lowest tier. */
+  tierTitleFor(win: number, bet: number): string | null {
+    return pickTier(this._cfg.tiers, win, bet)?.title ?? null;
+  }
+
+  resize(width: number, height: number): void {
+    this._cfg.width = width; this._cfg.height = height;
+    this._dim.clear();
+    this._dim.rect(0, 0, width, height).fill({ color: 0x000000, alpha: 0.72 });
+    this._title.position.set(width / 2, height * 0.4);
+    this._count.position.set(width / 2, height * 0.56);
+  }
+
+  async show(win: number, bet: number, format?: (v: number) => string): Promise<void> {
+    const tier = pickTier(this._cfg.tiers, win, bet);
+    if (!tier) return;
+    if (format) this._count.setFormat(format);
+    this.visible = true;
+    this.alpha = 0;
+    this._title.text = tier.title;
+    this._title.style.fill = tier.accentColor;
+
+    if (this._banner) { this._banner.destroy(); this._banner = null; }
+    if (tier.bannerTexture) {
+      this._banner = new Sprite(tier.bannerTexture);
+      this._banner.anchor.set(0.5);
+      this._banner.position.set(this._cfg.width / 2, this._cfg.height * 0.4);
+      this.addChildAt(this._banner, 1);
+    }
+
+    await Tween.to(this, { alpha: 1 }, 200, Easing.easeOutQuad);
+    const dur = (this._cfg.countUpDuration ?? DEFAULT_DURATION)(win);
+    let lastIdx = tierIndexAtValue(this._cfg.tiers, 0, bet);
+    await this._count.countTo(win, dur, undefined);
+    // tier-promotion title updates as the value climbs (sampled at the end for simplicity)
+    const finalIdx = tierIndexAtValue(this._cfg.tiers, win, bet);
+    if (finalIdx > lastIdx && this._cfg.tiers[finalIdx]) {
+      this._title.text = this._cfg.tiers[finalIdx].title;
+    }
+    void lastIdx;
+  }
+
+  skip(): void { Tween.killTweensOf(this); this._count.skip(); }
+
+  hide(): void { this.visible = false; Tween.killTweensOf(this); }
+}