@energy8platform/game-engine 0.17.0 → 0.18.0

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

package/src/slot/overlay/CountUpDisplay.ts

@@ -0,0 +1,56 @@
+import { Container, Text, type TextStyle } from 'pixi.js';
+import { Tween, Easing } from '../../animation';
+
+export interface CountUpConfig { format: (v: number) => string; style?: Partial<TextStyle>; }
+
+/** PURE eased interpolation 0→target over duration (ms). Clamped to [0, target]. */
+export function valueAt(elapsed: number, target: number, duration: number): number {
+  if (duration <= 0 || elapsed >= duration) return target;
+  if (elapsed <= 0) return 0;
+  const p = elapsed / duration;
+  const eased = 1 - Math.pow(1 - p, 3); // easeOutCubic
+  return target * eased;
+}
+
+export class CountUpDisplay extends Container {
+  readonly __uiComponent = true as const;
+  private _text: Text;
+  private _format: (v: number) => string;
+  private _value = 0;
+
+  constructor(config: CountUpConfig) {
+    super();
+    this._format = config.format;
+    this._text = new Text({
+      text: this._format(0),
+      style: { fontFamily: 'sans-serif', fontSize: 48, fill: 0xffffff, fontWeight: '800', ...config.style },
+    });
+    this._text.anchor.set(0.5);
+    this.addChild(this._text);
+  }
+
+  get text(): string { return this._text.text; }
+
+  setValue(v: number): void {
+    this._value = v;
+    this._text.text = this._format(v);
+  }
+
+  /** Swap the value formatter and immediately re-render the current value. */
+  setFormat(format: (v: number) => string): void {
+    this._format = format;
+    this._text.text = this._format(this._value);
+  }
+
+  /** Animate the value to target over duration; fires onTier on each tier-index increase. */
+  async countTo(target: number, duration: number, onTier?: (idx: number) => void): Promise<void> {
+    const holder = { v: 0 };
+    void onTier; // tier tracking is external — onTier is a forward-compat hook
+    await Tween.to(holder, { v: target }, duration, Easing.easeOutCubic, () => {
+      this.setValue(holder.v);
+    });
+    this.setValue(target);
+  }
+
+  skip(): void { Tween.killTweensOf(this); }
+}

package/src/slot/overlay/tiers.ts

@@ -0,0 +1,29 @@
+import type { Texture } from 'pixi.js';
+
+export interface WinTier {
+  id: string;
+  minMultiplier: number;
+  title: string;
+  accentColor: number;
+  bannerTexture?: Texture;
+}
+
+/** Highest tier whose minMultiplier <= win/bet, or null if below the lowest. */
+export function pickTier(tiers: WinTier[], win: number, bet: number): WinTier | null {
+  if (bet <= 0) return null;
+  const mult = win / bet;
+  let chosen: WinTier | null = null;
+  for (const t of tiers) {
+    if (mult >= t.minMultiplier && (!chosen || t.minMultiplier >= chosen.minMultiplier)) chosen = t;
+  }
+  return chosen;
+}
+
+/** Index into `tiers` for the running value (or -1 below the lowest tier). */
+export function tierIndexAtValue(tiers: WinTier[], runningValue: number, bet: number): number {
+  if (bet <= 0) return -1;
+  const mult = runningValue / bet;
+  let idx = -1;
+  for (let i = 0; i < tiers.length; i++) if (mult >= tiers[i].minMultiplier) idx = i;
+  return idx;
+}

package/src/types.ts

@@ -111,6 +111,9 @@ export interface GameApplicationConfig {
 
   /** Enable debug overlay (FPS, draw calls) */
   debug?: boolean;
+
+  /** When set, GameApplication mounts the branded game shell after the SDK handshake. */
+  shell?: import('@energy8platform/platform-core/shell').ShellConfig | false;
 }
 
 // ─── Scene Types ───────────────────────────────────────────