@energy8platform/game-engine 0.1.0

package/src/state/StateMachine.ts

@@ -0,0 +1,228 @@
+import { EventEmitter } from '../core/EventEmitter';
+
+interface StateConfig<TContext> {
+  enter?: (ctx: TContext, data?: unknown) => void | Promise<void>;
+  exit?: (ctx: TContext) => void | Promise<void>;
+  update?: (ctx: TContext, dt: number) => void;
+}
+
+interface StateMachineEvents {
+  transition: { from: string | null; to: string };
+  error: Error;
+}
+
+/**
+ * Generic finite state machine for game flow management.
+ *
+ * Supports:
+ * - Typed context object shared across all states
+ * - Async enter/exit hooks
+ * - Per-frame update per state
+ * - Transition guards
+ * - Event emission on state change
+ *
+ * @example
+ * ```ts
+ * interface GameContext {
+ *   balance: number;
+ *   bet: number;
+ *   lastWin: number;
+ * }
+ *
+ * const fsm = new StateMachine<GameContext>({ balance: 1000, bet: 10, lastWin: 0 });
+ *
+ * fsm.addState('idle', {
+ *   enter: (ctx) => console.log('Waiting for spin...'),
+ *   update: (ctx, dt) => { // optional per-frame },
+ * });
+ *
+ * fsm.addState('spinning', {
+ *   enter: async (ctx) => {
+ *     const result = await sdk.play({ action: 'spin', bet: ctx.bet });
+ *     ctx.lastWin = result.totalWin;
+ *     await fsm.transition('presenting');
+ *   },
+ * });
+ *
+ * fsm.addState('presenting', {
+ *   enter: async (ctx) => {
+ *     await showWinPresentation(ctx.lastWin);
+ *     await fsm.transition('idle');
+ *   },
+ * });
+ *
+ * // Optional guard
+ * fsm.addGuard('idle', 'spinning', (ctx) => ctx.balance >= ctx.bet);
+ *
+ * await fsm.start('idle');
+ * ```
+ */
+export class StateMachine<TContext = Record<string, unknown>> extends EventEmitter<StateMachineEvents> {
+  private _states = new Map<string, StateConfig<TContext>>();
+  private _guards = new Map<string, (ctx: TContext) => boolean>();
+  private _current: string | null = null;
+  private _transitioning = false;
+  private _context: TContext;
+
+  constructor(context: TContext) {
+    super();
+    this._context = context;
+  }
+
+  /** Current state name */
+  get current(): string | null {
+    return this._current;
+  }
+
+  /** Whether a transition is in progress */
+  get isTransitioning(): boolean {
+    return this._transitioning;
+  }
+
+  /** State machine context (shared data) */
+  get context(): TContext {
+    return this._context;
+  }
+
+  /**
+   * Register a state with optional enter/exit/update hooks.
+   */
+  addState(name: string, config: StateConfig<TContext>): this {
+    this._states.set(name, config);
+    return this;
+  }
+
+  /**
+   * Add a transition guard.
+   * The guard function must return true to allow the transition.
+   *
+   * @param from - Source state
+   * @param to - Target state
+   * @param guard - Guard function
+   */
+  addGuard(from: string, to: string, guard: (ctx: TContext) => boolean): this {
+    this._guards.set(`${from}->${to}`, guard);
+    return this;
+  }
+
+  /**
+   * Start the state machine in the given initial state.
+   */
+  async start(initialState: string, data?: unknown): Promise<void> {
+    if (this._current !== null) {
+      throw new Error('[StateMachine] Already started. Use transition() to change states.');
+    }
+
+    const state = this._states.get(initialState);
+    if (!state) {
+      throw new Error(`[StateMachine] State "${initialState}" not registered.`);
+    }
+
+    this._current = initialState;
+    await state.enter?.(this._context, data);
+    this.emit('transition', { from: null, to: initialState });
+  }
+
+  /**
+   * Transition to a new state.
+   *
+   * @param to - Target state name
+   * @param data - Optional data passed to the new state's enter hook
+   * @returns true if the transition succeeded, false if blocked by a guard
+   */
+  async transition(to: string, data?: unknown): Promise<boolean> {
+    if (this._transitioning) {
+      console.warn('[StateMachine] Transition already in progress');
+      return false;
+    }
+
+    const from = this._current;
+
+    // Check guard
+    if (from !== null) {
+      const guardKey = `${from}->${to}`;
+      const guard = this._guards.get(guardKey);
+      if (guard && !guard(this._context)) {
+        return false;
+      }
+    }
+
+    const toState = this._states.get(to);
+    if (!toState) {
+      throw new Error(`[StateMachine] State "${to}" not registered.`);
+    }
+
+    this._transitioning = true;
+
+    try {
+      // Exit current state
+      if (from !== null) {
+        const fromState = this._states.get(from);
+        await fromState?.exit?.(this._context);
+      }
+
+      // Enter new state
+      this._current = to;
+      await toState.enter?.(this._context, data);
+
+      this.emit('transition', { from, to });
+    } catch (err) {
+      this.emit('error', err instanceof Error ? err : new Error(String(err)));
+      throw err;
+    } finally {
+      this._transitioning = false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Call the current state's update function.
+   * Should be called from the game loop.
+   */
+  update(dt: number): void {
+    if (this._current === null) return;
+    const state = this._states.get(this._current);
+    state?.update?.(this._context, dt);
+  }
+
+  /**
+   * Check if a state is registered.
+   */
+  hasState(name: string): boolean {
+    return this._states.has(name);
+  }
+
+  /**
+   * Check if a transition is allowed (guard passes).
+   */
+  canTransition(to: string): boolean {
+    if (this._current === null) return false;
+    const guardKey = `${this._current}->${to}`;
+    const guard = this._guards.get(guardKey);
+    if (!guard) return true;
+    return guard(this._context);
+  }
+
+  /**
+   * Reset the state machine (exit current state, clear current).
+   */
+  async reset(): Promise<void> {
+    if (this._current !== null) {
+      const state = this._states.get(this._current);
+      await state?.exit?.(this._context);
+    }
+    this._current = null;
+    this._transitioning = false;
+  }
+
+  /**
+   * Destroy the state machine.
+   */
+  async destroy(): Promise<void> {
+    await this.reset();
+    this._states.clear();
+    this._guards.clear();
+    this.removeAllListeners();
+  }
+}

package/src/state/index.ts

@@ -0,0 +1 @@
+export { StateMachine } from './StateMachine';

package/src/types.ts

@@ -0,0 +1,218 @@
+import type { ApplicationOptions, Container } from 'pixi.js';
+import type {
+  InitData,
+  GameConfigData,
+  SessionData,
+  PlayParams,
+  PlayResultData,
+} from '@energy8platform/game-sdk';
+
+// ─── Scale Modes ───────────────────────────────────────────
+
+export enum ScaleMode {
+  /** Fit inside container, maintain aspect ratio (letterbox/pillarbox) */
+  FIT = 'FIT',
+  /** Fill container, maintain aspect ratio (crop edges) */
+  FILL = 'FILL',
+  /** Stretch to fill (distorts) */
+  STRETCH = 'STRETCH',
+}
+
+// ─── Orientation ───────────────────────────────────────────
+
+export enum Orientation {
+  LANDSCAPE = 'landscape',
+  PORTRAIT = 'portrait',
+  ANY = 'any',
+}
+
+// ─── Loading Screen Config ─────────────────────────────────
+
+export interface LoadingScreenConfig {
+  /** Background color (hex number or CSS string) */
+  backgroundColor?: number | string;
+  /** Background gradient (CSS string applied to the CSS preloader) */
+  backgroundGradient?: string;
+  /** Logo texture alias (must be in 'preload' bundle) */
+  logoAsset?: string;
+  /** Logo scale (default: 1) */
+  logoScale?: number;
+  /** Show percentage text below the loader bar */
+  showPercentage?: boolean;
+  /** Custom progress text formatter */
+  progressTextFormatter?: (progress: number) => string;
+  /** Show "Tap to start" after loading (needed for mobile audio unlock) */
+  tapToStart?: boolean;
+  /** "Tap to start" label text */
+  tapToStartText?: string;
+  /** Minimum display time in ms (so the user sees the brand, even if loading is fast) */
+  minDisplayTime?: number;
+  /** CSS preloader custom HTML (shown before PixiJS is ready) */
+  cssPreloaderHTML?: string;
+}
+
+// ─── Asset Manifest ────────────────────────────────────────
+
+export interface AssetEntry {
+  alias: string;
+  src: string | string[];
+  /** Optional data to pass to the loader */
+  data?: Record<string, unknown>;
+}
+
+export interface AssetBundle {
+  name: string;
+  assets: AssetEntry[];
+}
+
+export interface AssetManifest {
+  bundles: AssetBundle[];
+}
+
+// ─── Audio Config ──────────────────────────────────────────
+
+export interface AudioCategory {
+  volume: number;
+  muted: boolean;
+}
+
+export interface AudioConfig {
+  /** Default volumes per category (0..1) */
+  music?: number;
+  sfx?: number;
+  ui?: number;
+  ambient?: number;
+  /** Persist mute state in localStorage */
+  persist?: boolean;
+  /** LocalStorage key prefix */
+  storageKey?: string;
+}
+
+// ─── Game Application Config ───────────────────────────────
+
+export interface GameApplicationConfig {
+  /** Container element or CSS selector to mount canvas into */
+  container?: HTMLElement | string;
+
+  /** Reference design width (fallback: GameConfigData.viewport.width or 1920) */
+  designWidth?: number;
+
+  /** Reference design height (fallback: GameConfigData.viewport.height or 1080) */
+  designHeight?: number;
+
+  /** How to scale the game to fit the container */
+  scaleMode?: ScaleMode;
+
+  /** Preferred orientation */
+  orientation?: Orientation;
+
+  /** Loading screen configuration */
+  loading?: LoadingScreenConfig;
+
+  /** Asset manifest — what to load */
+  manifest?: AssetManifest;
+
+  /** Audio configuration */
+  audio?: AudioConfig;
+
+  /** SDK options. Set to false to disable SDK (offline/development mode) */
+  sdk?:
+    | {
+        parentOrigin?: string;
+        timeout?: number;
+        debug?: boolean;
+      }
+    | false;
+
+  /** PixiJS Application options (pass-through) */
+  pixi?: Partial<ApplicationOptions>;
+
+  /** Enable debug overlay (FPS, draw calls) */
+  debug?: boolean;
+}
+
+// ─── Scene Types ───────────────────────────────────────────
+
+export interface SceneConstructor {
+  new (): IScene;
+}
+
+export interface IScene {
+  /** Root display container for this scene */
+  readonly container: Container;
+
+  /** Called when the scene is entered */
+  onEnter?(data?: unknown): Promise<void> | void;
+
+  /** Called when the scene is exited */
+  onExit?(): Promise<void> | void;
+
+  /** Called every frame */
+  onUpdate?(dt: number): void;
+
+  /** Called when viewport resizes */
+  onResize?(width: number, height: number): void;
+
+  /** Called when the scene is destroyed */
+  onDestroy?(): void;
+}
+
+// ─── Transition Types ──────────────────────────────────────
+
+export enum TransitionType {
+  NONE = 'none',
+  FADE = 'fade',
+  SLIDE_LEFT = 'slide-left',
+  SLIDE_RIGHT = 'slide-right',
+}
+
+export interface TransitionConfig {
+  type: TransitionType;
+  duration?: number;
+  easing?: (t: number) => number;
+}
+
+// ─── Event Types ───────────────────────────────────────────
+
+export interface GameEngineEvents {
+  /** Fired when engine initialization is complete */
+  initialized: void;
+  /** Fired when all assets are loaded */
+  loaded: void;
+  /** Fired when the engine starts running */
+  started: void;
+  /** Fired on viewport resize */
+  resize: { width: number; height: number };
+  /** Fired on orientation change */
+  orientationChange: Orientation;
+  /** Fired on scene change */
+  sceneChange: { from: string | null; to: string };
+  /** Fired on error */
+  error: Error;
+  /** Fired when engine is destroyed */
+  destroyed: void;
+}
+
+// ─── Tween Types ───────────────────────────────────────────
+
+export type EasingFunction = (t: number) => number;
+
+export interface TweenOptions {
+  duration: number;
+  easing?: EasingFunction;
+  delay?: number;
+  repeat?: number;
+  yoyo?: boolean;
+  onUpdate?: (progress: number) => void;
+  onComplete?: () => void;
+}
+
+// ─── Re-exports from SDK for convenience ───────────────────
+
+export type {
+  InitData,
+  GameConfigData,
+  SessionData,
+  PlayParams,
+  PlayResultData,
+};

package/src/ui/BalanceDisplay.ts

@@ -0,0 +1,155 @@
+import { Container } from 'pixi.js';
+import { Label } from './Label';
+import { Tween } from '../animation/Tween';
+import { Easing } from '../animation/Easing';
+
+export interface BalanceDisplayConfig {
+  /** Label prefix (e.g., "BALANCE") */
+  prefix?: string;
+  /** Text style overrides */
+  style?: Record<string, unknown>;
+  /** Currency code */
+  currency?: string;
+  /** Locale for number formatting */
+  locale?: string;
+  /** Max width */
+  maxWidth?: number;
+  /** Animate value changes */
+  animated?: boolean;
+  /** Animation duration in ms */
+  animationDuration?: number;
+}
+
+/**
+ * Reactive balance display component.
+ *
+ * Automatically formats currency and can animate value changes
+ * with a smooth countup/countdown effect.
+ *
+ * @example
+ * ```ts
+ * const balance = new BalanceDisplay({ currency: 'USD', animated: true });
+ * balance.setValue(1000);
+ *
+ * // Wire to SDK
+ * sdk.on('balanceUpdate', ({ balance: val }) => balance.setValue(val));
+ * ```
+ */
+export class BalanceDisplay extends Container {
+  private _prefixLabel: Label | null = null;
+  private _valueLabel: Label;
+  private _config: Required<Pick<BalanceDisplayConfig, 'currency' | 'locale' | 'animated' | 'animationDuration'>>;
+  private _currentValue = 0;
+  private _displayedValue = 0;
+  private _animating = false;
+
+  constructor(config: BalanceDisplayConfig = {}) {
+    super();
+
+    this._config = {
+      currency: config.currency ?? 'USD',
+      locale: config.locale ?? 'en-US',
+      animated: config.animated ?? true,
+      animationDuration: config.animationDuration ?? 500,
+    };
+
+    // Prefix label
+    if (config.prefix) {
+      this._prefixLabel = new Label({
+        text: config.prefix,
+        style: {
+          fontSize: 16,
+          fill: 0xaaaaaa,
+          ...(config.style as any),
+        },
+      });
+      this.addChild(this._prefixLabel);
+    }
+
+    // Value label
+    this._valueLabel = new Label({
+      text: '0.00',
+      style: {
+        fontSize: 28,
+        fontWeight: 'bold',
+        fill: 0xffffff,
+        ...(config.style as any),
+      },
+      maxWidth: config.maxWidth,
+      autoFit: !!config.maxWidth,
+    });
+    this.addChild(this._valueLabel);
+
+    this.layoutLabels();
+  }
+
+  /** Current displayed value */
+  get value(): number {
+    return this._currentValue;
+  }
+
+  /**
+   * Set the balance value. If animated, smoothly counts to the new value.
+   */
+  setValue(value: number): void {
+    const oldValue = this._currentValue;
+    this._currentValue = value;
+
+    if (this._config.animated && oldValue !== value) {
+      this.animateValue(oldValue, value);
+    } else {
+      this._displayedValue = value;
+      this.updateDisplay();
+    }
+  }
+
+  /**
+   * Set the currency code.
+   */
+  setCurrency(currency: string): void {
+    this._config.currency = currency;
+    this.updateDisplay();
+  }
+
+  private async animateValue(from: number, to: number): Promise<void> {
+    this._animating = true;
+    const duration = this._config.animationDuration;
+    const startTime = Date.now();
+
+    return new Promise<void>((resolve) => {
+      const tick = () => {
+        const elapsed = Date.now() - startTime;
+        const t = Math.min(elapsed / duration, 1);
+        const eased = Easing.easeOutCubic(t);
+
+        this._displayedValue = from + (to - from) * eased;
+        this.updateDisplay();
+
+        if (t < 1) {
+          requestAnimationFrame(tick);
+        } else {
+          this._displayedValue = to;
+          this.updateDisplay();
+          this._animating = false;
+          resolve();
+        }
+      };
+      requestAnimationFrame(tick);
+    });
+  }
+
+  private updateDisplay(): void {
+    this._valueLabel.setCurrency(
+      this._displayedValue,
+      this._config.currency,
+      this._config.locale,
+    );
+  }
+
+  private layoutLabels(): void {
+    if (this._prefixLabel) {
+      this._prefixLabel.y = -14;
+      this._valueLabel.y = 14;
+    }
+  }
+}