@energy8platform/game-engine 0.17.0 → 0.18.0

package/src/host/types.ts

@@ -0,0 +1,71 @@
+// packages/game-engine/src/host/types.ts
+import type { ApplicationOptions } from 'pixi.js';
+import type { GameModel } from '@energy8platform/platform-core/game-spec';
+import type { AssetManifest, LoadingScreenConfig } from '@energy8platform/platform-core';
+import type { GameShell } from '@energy8platform/platform-core/shell';
+import type { AudioConfig, ScaleMode, Orientation, SceneConstructor } from '../types';
+import type { BookAdapter, AdapterModule, StakeBridge } from '@energy8platform/stake-bridge';
+import type { GameApplication } from '../core';
+import type { SlotShellOptions } from './shellConfig';
+import type { SlotSpinResultBase, SlotResultNormalizer } from '@energy8platform/platform-core/slot-result';
+
+export interface StakeIntegration {
+  /** The game's BookAdapter (or its module). modeMap + gameId come from the model. */
+  adapter: BookAdapter | AdapterModule;
+}
+
+/** One scene registered with the host: a key + its constructor. The list order matters — the
+ *  first scene that is eligible for the current launch mode is the start scene (unless an explicit
+ *  `startScene` overrides it). */
+export interface SceneRegistration {
+  key: string;
+  scene: SceneConstructor;
+  /** Skip this scene as a START scene on a replay launch (e.g. an intro). It is still registered
+   *  (other scenes can `goto` it), it just isn't auto-started — the first non-skipped scene is. */
+  skipOnReplay?: boolean;
+}
+
+/** @deprecated alias kept for one release — use {@link SceneRegistration}. */
+export type SceneEntry = SceneRegistration;
+
+/** Navigation injected into the start data of EVERY scene the host registers.
+ *  Any scene (intro, game, …) reads it from its `onEnter(data)` to navigate. */
+export interface SceneNavData {
+  /** Switch to another registered scene by key. */
+  goto: (key: string, data?: unknown) => void;
+}
+
+export interface CreateSlotGameOptions<T extends SlotSpinResultBase = SlotSpinResultBase> {
+  model: GameModel;
+  /** REQUIRED: maps the raw play result into the game's typed result. The host calls it on every play. */
+  normalize: SlotResultNormalizer<T>;
+  /** ALL scenes the game uses, registered up front, in order. The first scene eligible for the
+   *  launch mode is the start scene — so a replay launch skips any leading `skipOnReplay` scene
+   *  (e.g. the intro) and starts directly on the game scene. */
+  scenes: SceneRegistration[];
+  /** Optional explicit start scene key. Defaults to the first scene eligible for the launch mode
+   *  (honoured only when that scene is itself eligible; otherwise the first eligible one wins). */
+  startScene?: string;
+  /** Start data passed to the start scene's `onEnter` (merged with the injected `goto`). */
+  startData?: unknown;
+  manifest: AssetManifest;
+  container?: HTMLElement | string;
+  design?: { width: number; height: number };
+  scaleMode?: ScaleMode;
+  orientation?: Orientation;
+  loading?: LoadingScreenConfig;
+  audio?: AudioConfig;
+  pixi?: Partial<ApplicationOptions>;
+  fonts?: string[];
+  textureDefaults?: boolean;
+  dev?: boolean;
+  stake?: StakeIntegration;
+  shell?: SlotShellOptions;
+  onFatalError?: (message: string) => void;
+}
+
+export interface SlotGameHandle {
+  game: GameApplication;
+  stakeBridge: StakeBridge | null;
+  shell: GameShell | null;
+}

package/src/scenes/IntroScene.ts

@@ -0,0 +1,66 @@
+// packages/game-engine/src/scenes/IntroScene.ts
+import { Container, Graphics, Text } from 'pixi.js';
+import { Scene } from '../core/Scene';
+
+export interface IntroSceneConfig {
+  title?: string;
+  logo?: string;          // texture alias (optional; title text is the default)
+  tapToStart?: boolean;   // default true
+  /** Where to navigate on tap. Defaults to the conventional 'game' key. */
+  next?: string;
+  /** Optional explicit start callback. Takes precedence over `goto(next)`. */
+  onStart?: () => void;
+}
+
+/**
+ * Reusable splash scene: shows a title (or logo) + "tap to start", then advances.
+ *
+ * The host no longer special-cases the intro. Navigation works like every other
+ * scene: the host injects `goto(key)` into this scene's start data. On tap this
+ * scene calls `onStart` if the game supplied one, otherwise `goto(next ?? 'game')`.
+ * (The built-in can't know the game's scene key generically, so it falls back to
+ * the conventional 'game' key — override via `next`. Scaffold-generated intros
+ * skip this primitive and call `goto('game')` directly.)
+ */
+export class IntroScene extends Scene {
+  private layer?: Container;
+
+  async onEnter(data?: unknown): Promise<void> {
+    const cfg = (data ?? {}) as IntroSceneConfig & { goto?: (key: string, data?: unknown) => void };
+    const start = () =>
+      cfg.onStart ? cfg.onStart() : cfg.goto?.(cfg.next ?? 'game');
+    const layer = new Container();
+    this.layer = layer;
+    this.container.addChild(layer);
+
+    const title = new Text({
+      text: cfg.title ?? 'PLAY',
+      style: { fill: 0xffffff, fontSize: 96, fontFamily: 'Inter', align: 'center' },
+    });
+    title.anchor.set(0.5);
+    title.position.set(960, 460);
+    layer.addChild(title);
+
+    if (cfg.tapToStart !== false) {
+      const hint = new Text({
+        text: 'Tap to start',
+        style: { fill: 0xffd24a, fontSize: 36, fontFamily: 'Inter' },
+      });
+      hint.anchor.set(0.5);
+      hint.position.set(960, 600);
+      layer.addChild(hint);
+    }
+
+    // full-screen tap target
+    const hit = new Graphics().rect(0, 0, 1920, 1080).fill({ color: 0x000000, alpha: 0.001 });
+    hit.eventMode = 'static';
+    hit.cursor = 'pointer';
+    hit.once('pointerdown', () => start());
+    layer.addChild(hit);
+  }
+
+  onExit(): void {
+    this.layer?.destroy({ children: true });
+    this.layer = undefined;
+  }
+}

package/src/shell/index.ts

@@ -0,0 +1,20 @@
+// Re-export the renderer-agnostic branded game shell from platform-core so
+// game-engine consumers can import it via @energy8platform/game-engine/shell.
+export {
+  createGameShell,
+  removeGameShell,
+  GameShell,
+} from '@energy8platform/platform-core/shell';
+export type {
+  ShellConfig,
+  ShellMode,
+  ShellFeatures,
+  ShellState,
+  ShellEvents,
+  BonusOption,
+  CurrencyConfig,
+  ThemeConfig,
+  GameInfoContent,
+  AutoplayOptions,
+  FreeSpinsState,
+} from '@energy8platform/platform-core/shell';

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;
+  }
+}