@energy8platform/game-engine 0.1.0

package/src/ui/Toast.ts

@@ -0,0 +1,124 @@
+import { Container, Graphics, Text } from 'pixi.js';
+import { Tween } from '../animation/Tween';
+import { Easing } from '../animation/Easing';
+
+export type ToastType = 'info' | 'success' | 'warning' | 'error';
+
+export interface ToastConfig {
+  /** Auto-dismiss after this many ms (0 = manual dismiss only) */
+  duration?: number;
+  /** Toast position from bottom */
+  bottomOffset?: number;
+}
+
+const TOAST_COLORS: Record<ToastType, number> = {
+  info: 0x3498db,
+  success: 0x27ae60,
+  warning: 0xf39c12,
+  error: 0xe74c3c,
+};
+
+/**
+ * Toast notification component for displaying transient messages.
+ *
+ * @example
+ * ```ts
+ * const toast = new Toast();
+ * scene.container.addChild(toast);
+ * await toast.show('Connection lost', 'error', 1920, 1080);
+ * ```
+ */
+export class Toast extends Container {
+  private _bg: Graphics;
+  private _text: Text;
+  private _config: Required<ToastConfig>;
+  private _dismissTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(config: ToastConfig = {}) {
+    super();
+
+    this._config = {
+      duration: 3000,
+      bottomOffset: 60,
+      ...config,
+    };
+
+    this._bg = new Graphics();
+    this.addChild(this._bg);
+
+    this._text = new Text({
+      text: '',
+      style: {
+        fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+        fontSize: 16,
+        fill: 0xffffff,
+      },
+    });
+    this._text.anchor.set(0.5);
+    this.addChild(this._text);
+
+    this.visible = false;
+  }
+
+  /**
+   * Show a toast message.
+   */
+  async show(
+    message: string,
+    type: ToastType = 'info',
+    viewWidth?: number,
+    viewHeight?: number,
+  ): Promise<void> {
+    // Clear previous dismiss
+    if (this._dismissTimeout) {
+      clearTimeout(this._dismissTimeout);
+    }
+
+    this._text.text = message;
+
+    const padding = 20;
+    const width = Math.max(200, this._text.width + padding * 2);
+    const height = 44;
+    const radius = 8;
+
+    this._bg.clear();
+    this._bg.roundRect(-width / 2, -height / 2, width, height, radius).fill(TOAST_COLORS[type]);
+    this._bg.roundRect(-width / 2, -height / 2, width, height, radius)
+      .fill({ color: 0x000000, alpha: 0.2 });
+
+    // Position
+    if (viewWidth && viewHeight) {
+      this.x = viewWidth / 2;
+      this.y = viewHeight - this._config.bottomOffset;
+    }
+
+    this.visible = true;
+    this.alpha = 0;
+    this.y += 20;
+
+    // Animate in
+    await Tween.to(this, { alpha: 1, y: this.y - 20 }, 300, Easing.easeOutCubic);
+
+    // Auto-dismiss
+    if (this._config.duration > 0) {
+      this._dismissTimeout = setTimeout(() => {
+        this.dismiss();
+      }, this._config.duration);
+    }
+  }
+
+  /**
+   * Dismiss the toast.
+   */
+  async dismiss(): Promise<void> {
+    if (!this.visible) return;
+
+    if (this._dismissTimeout) {
+      clearTimeout(this._dismissTimeout);
+      this._dismissTimeout = null;
+    }
+
+    await Tween.to(this, { alpha: 0, y: this.y + 20 }, 200, Easing.easeInCubic);
+    this.visible = false;
+  }
+}

package/src/ui/WinDisplay.ts

@@ -0,0 +1,133 @@
+import { Container } from 'pixi.js';
+import { Label } from './Label';
+import { Easing } from '../animation/Easing';
+
+export interface WinDisplayConfig {
+  /** Text style overrides */
+  style?: Record<string, unknown>;
+  /** Currency code */
+  currency?: string;
+  /** Locale for number formatting */
+  locale?: string;
+  /** Countup duration in ms */
+  countupDuration?: number;
+  /** Scale pop animation on win */
+  popScale?: number;
+}
+
+/**
+ * Win amount display with countup animation.
+ *
+ * Shows a dramatic countup from 0 to the win amount, with optional
+ * scale pop effect — typical of slot games.
+ *
+ * @example
+ * ```ts
+ * const winDisplay = new WinDisplay({ currency: 'USD' });
+ * scene.container.addChild(winDisplay);
+ * await winDisplay.showWin(150.50); // countup animation
+ * winDisplay.hide();
+ * ```
+ */
+export class WinDisplay extends Container {
+  private _label: Label;
+  private _config: Required<Pick<WinDisplayConfig, 'currency' | 'locale' | 'countupDuration' | 'popScale'>>;
+  private _cancelCountup = false;
+
+  constructor(config: WinDisplayConfig = {}) {
+    super();
+
+    this._config = {
+      currency: config.currency ?? 'USD',
+      locale: config.locale ?? 'en-US',
+      countupDuration: config.countupDuration ?? 1500,
+      popScale: config.popScale ?? 1.2,
+    };
+
+    this._label = new Label({
+      text: '',
+      style: {
+        fontSize: 48,
+        fontWeight: 'bold',
+        fill: 0xffd700,
+        stroke: { color: 0x000000, width: 3 },
+        ...(config.style as any),
+      },
+    });
+    this.addChild(this._label);
+
+    this.visible = false;
+  }
+
+  /**
+   * Show a win with countup animation.
+   *
+   * @param amount - Win amount
+   * @returns Promise that resolves when the animation completes
+   */
+  async showWin(amount: number): Promise<void> {
+    this.visible = true;
+    this._cancelCountup = false;
+    this.alpha = 1;
+
+    const duration = this._config.countupDuration;
+    const startTime = Date.now();
+
+    // Scale pop
+    this.scale.set(0.5);
+
+    return new Promise<void>((resolve) => {
+      const tick = () => {
+        if (this._cancelCountup) {
+          this.displayAmount(amount);
+          resolve();
+          return;
+        }
+
+        const elapsed = Date.now() - startTime;
+        const t = Math.min(elapsed / duration, 1);
+        const eased = Easing.easeOutCubic(t);
+
+        // Countup
+        const current = amount * eased;
+        this.displayAmount(current);
+
+        // Scale animation
+        const scaleT = Math.min(elapsed / 300, 1);
+        const scaleEased = Easing.easeOutBack(scaleT);
+        const targetScale = 1;
+        this.scale.set(0.5 + (targetScale - 0.5) * scaleEased);
+
+        if (t < 1) {
+          requestAnimationFrame(tick);
+        } else {
+          this.displayAmount(amount);
+          this.scale.set(1);
+          resolve();
+        }
+      };
+      requestAnimationFrame(tick);
+    });
+  }
+
+  /**
+   * Skip the countup animation and show the final amount immediately.
+   */
+  skipCountup(amount: number): void {
+    this._cancelCountup = true;
+    this.displayAmount(amount);
+    this.scale.set(1);
+  }
+
+  /**
+   * Hide the win display.
+   */
+  hide(): void {
+    this.visible = false;
+    this._label.text = '';
+  }
+
+  private displayAmount(amount: number): void {
+    this._label.setCurrency(amount, this._config.currency, this._config.locale);
+  }
+}

package/src/ui/index.ts

@@ -0,0 +1,16 @@
+export { Button } from './Button';
+export type { ButtonConfig, ButtonState } from './Button';
+export { ProgressBar } from './ProgressBar';
+export type { ProgressBarConfig } from './ProgressBar';
+export { Label } from './Label';
+export type { LabelConfig } from './Label';
+export { Panel } from './Panel';
+export type { PanelConfig } from './Panel';
+export { BalanceDisplay } from './BalanceDisplay';
+export type { BalanceDisplayConfig } from './BalanceDisplay';
+export { WinDisplay } from './WinDisplay';
+export type { WinDisplayConfig } from './WinDisplay';
+export { Modal } from './Modal';
+export type { ModalConfig } from './Modal';
+export { Toast } from './Toast';
+export type { ToastConfig, ToastType } from './Toast';

package/src/viewport/ViewportManager.ts

@@ -0,0 +1,241 @@
+import type { Application } from 'pixi.js';
+import { EventEmitter } from '../core/EventEmitter';
+import { ScaleMode, Orientation } from '../types';
+
+interface ViewportConfig {
+  designWidth: number;
+  designHeight: number;
+  scaleMode: ScaleMode;
+  orientation: Orientation;
+}
+
+interface ViewportEvents {
+  resize: { width: number; height: number; scale: number };
+  orientationChange: Orientation;
+}
+
+/**
+ * Manages responsive scaling of the game canvas to fit its container.
+ *
+ * Supports three scale modes:
+ * - **FIT** — letterbox/pillarbox to maintain aspect ratio (industry standard)
+ * - **FILL** — fill container, crop edges
+ * - **STRETCH** — stretch to fill (distorts)
+ *
+ * Also handles:
+ * - Orientation detection (landscape/portrait)
+ * - Safe areas (mobile notch)
+ * - ResizeObserver for smooth container resizing
+ *
+ * @example
+ * ```ts
+ * const viewport = new ViewportManager(app, container, {
+ *   designWidth: 1920,
+ *   designHeight: 1080,
+ *   scaleMode: ScaleMode.FIT,
+ *   orientation: Orientation.LANDSCAPE,
+ * });
+ *
+ * viewport.on('resize', ({ width, height, scale }) => {
+ *   console.log(`New size: ${width}x${height} @ ${scale}x`);
+ * });
+ * ```
+ */
+export class ViewportManager extends EventEmitter<ViewportEvents> {
+  private _app: Application;
+  private _container: HTMLElement;
+  private _config: ViewportConfig;
+  private _resizeObserver: ResizeObserver | null = null;
+  private _currentOrientation: Orientation = Orientation.LANDSCAPE;
+  private _currentWidth = 0;
+  private _currentHeight = 0;
+  private _currentScale = 1;
+  private _destroyed = false;
+  private _resizeTimeout: number | null = null;
+
+  constructor(app: Application, container: HTMLElement, config: ViewportConfig) {
+    super();
+    this._app = app;
+    this._container = container;
+    this._config = config;
+
+    this.setupObserver();
+  }
+
+  /** Current canvas width in game units */
+  get width(): number {
+    return this._currentWidth;
+  }
+
+  /** Current canvas height in game units */
+  get height(): number {
+    return this._currentHeight;
+  }
+
+  /** Current scale factor */
+  get scale(): number {
+    return this._currentScale;
+  }
+
+  /** Current orientation */
+  get orientation(): Orientation {
+    return this._currentOrientation;
+  }
+
+  /** Design reference width */
+  get designWidth(): number {
+    return this._config.designWidth;
+  }
+
+  /** Design reference height */
+  get designHeight(): number {
+    return this._config.designHeight;
+  }
+
+  /**
+   * Force a resize calculation. Called automatically on container size change.
+   */
+  refresh(): void {
+    if (this._destroyed) return;
+
+    const containerWidth = this._container.clientWidth || window.innerWidth;
+    const containerHeight = this._container.clientHeight || window.innerHeight;
+
+    if (containerWidth === 0 || containerHeight === 0) return;
+
+    const { designWidth, designHeight, scaleMode } = this._config;
+    const designRatio = designWidth / designHeight;
+    const containerRatio = containerWidth / containerHeight;
+
+    let gameWidth: number;
+    let gameHeight: number;
+    let scale: number;
+
+    switch (scaleMode) {
+      case ScaleMode.FIT: {
+        if (containerRatio > designRatio) {
+          // Container is wider → pillarbox
+          scale = containerHeight / designHeight;
+          gameWidth = designWidth;
+          gameHeight = designHeight;
+        } else {
+          // Container is taller → letterbox
+          scale = containerWidth / designWidth;
+          gameWidth = designWidth;
+          gameHeight = designHeight;
+        }
+        break;
+      }
+
+      case ScaleMode.FILL: {
+        if (containerRatio > designRatio) {
+          // Container is wider → crop top/bottom
+          scale = containerWidth / designWidth;
+        } else {
+          // Container is taller → crop left/right
+          scale = containerHeight / designHeight;
+        }
+        gameWidth = containerWidth / scale;
+        gameHeight = containerHeight / scale;
+        break;
+      }
+
+      case ScaleMode.STRETCH: {
+        gameWidth = designWidth;
+        gameHeight = designHeight;
+        scale = 1; // stretch is handled by CSS
+        break;
+      }
+
+      default:
+        gameWidth = designWidth;
+        gameHeight = designHeight;
+        scale = 1;
+    }
+
+    // Resize the renderer
+    this._app.renderer.resize(
+      Math.round(containerWidth),
+      Math.round(containerHeight),
+    );
+
+    // Scale the stage
+    const stageScale = scaleMode === ScaleMode.STRETCH
+      ? Math.min(containerWidth / designWidth, containerHeight / designHeight)
+      : scale;
+
+    this._app.stage.scale.set(stageScale);
+
+    // Center the stage for FIT mode
+    if (scaleMode === ScaleMode.FIT) {
+      this._app.stage.x = Math.round((containerWidth - designWidth * stageScale) / 2);
+      this._app.stage.y = Math.round((containerHeight - designHeight * stageScale) / 2);
+    } else if (scaleMode === ScaleMode.FILL) {
+      this._app.stage.x = Math.round((containerWidth - gameWidth * stageScale) / 2);
+      this._app.stage.y = Math.round((containerHeight - gameHeight * stageScale) / 2);
+    } else {
+      this._app.stage.x = 0;
+      this._app.stage.y = 0;
+    }
+
+    this._currentWidth = gameWidth;
+    this._currentHeight = gameHeight;
+    this._currentScale = stageScale;
+
+    // Check orientation
+    const newOrientation =
+      containerWidth >= containerHeight ? Orientation.LANDSCAPE : Orientation.PORTRAIT;
+
+    if (newOrientation !== this._currentOrientation) {
+      this._currentOrientation = newOrientation;
+      this.emit('orientationChange', newOrientation);
+    }
+
+    this.emit('resize', {
+      width: gameWidth,
+      height: gameHeight,
+      scale: stageScale,
+    });
+  }
+
+  /**
+   * Destroy the viewport manager.
+   */
+  destroy(): void {
+    this._destroyed = true;
+    this._resizeObserver?.disconnect();
+    this._resizeObserver = null;
+    if (this._resizeTimeout !== null) {
+      clearTimeout(this._resizeTimeout);
+    }
+    this.removeAllListeners();
+  }
+
+  // ─── Private ───────────────────────────────────────────
+
+  private setupObserver(): void {
+    if (typeof ResizeObserver !== 'undefined') {
+      this._resizeObserver = new ResizeObserver(() => {
+        this.debouncedRefresh();
+      });
+      this._resizeObserver.observe(this._container);
+    } else {
+      // Fallback for older browsers
+      window.addEventListener('resize', this.onWindowResize);
+    }
+  }
+
+  private onWindowResize = (): void => {
+    this.debouncedRefresh();
+  };
+
+  private debouncedRefresh(): void {
+    if (this._resizeTimeout !== null) {
+      clearTimeout(this._resizeTimeout);
+    }
+    this._resizeTimeout = window.setTimeout(() => {
+      this.refresh();
+      this._resizeTimeout = null;
+    }, 16); // ~1 frame
+  }
+}

package/src/viewport/index.ts

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

package/src/vite/index.ts

@@ -0,0 +1,153 @@
+import type { UserConfig, Plugin } from 'vite';
+
+export interface GameViteConfig {
+  /** Base path for production builds (e.g., '/games/my-slot/') */
+  base?: string;
+  /** Output directory (default: 'dist') */
+  outDir?: string;
+  /** Enable DevBridge auto-injection in dev mode */
+  devBridge?: boolean;
+  /** Asset file extensions to include */
+  assetExtensions?: string[];
+  /** Additional Vite config overrides */
+  vite?: UserConfig;
+}
+
+/**
+ * Vite plugin that injects the DevBridge mock host in development mode.
+ *
+ * In dev mode, wraps the game page to simulate the casino host environment,
+ * allowing SDK communication to work without a real backend.
+ */
+const VIRTUAL_DEV_BRIDGE_ID = 'virtual:game-engine-dev-bridge';
+const RESOLVED_VIRTUAL_ID = '\0' + VIRTUAL_DEV_BRIDGE_ID;
+
+function gameEngineDevPlugin(options: { devBridge?: boolean } = {}): Plugin {
+  return {
+    name: 'game-engine-dev',
+    apply: 'serve',
+
+    resolveId(id) {
+      if (id === VIRTUAL_DEV_BRIDGE_ID) return RESOLVED_VIRTUAL_ID;
+    },
+
+    load(id) {
+      if (id === RESOLVED_VIRTUAL_ID) {
+        // This module goes through Vite's transform pipeline,
+        // so bare specifiers like '@energy8platform/game-engine/debug' resolve correctly.
+        return `
+import { DevBridge } from '@energy8platform/game-engine/debug';
+
+async function initDevBridge() {
+  let config = {};
+  try {
+    const mod = await import('/dev.config.ts');
+    config = mod.default || mod.devBridgeConfig || {};
+  } catch {
+    // No dev config — use defaults
+  }
+
+  const bridge = new DevBridge(config);
+  bridge.start();
+  window.__devBridge = bridge;
+  console.log('[GameEngine] DevBridge started in development mode');
+}
+
+initDevBridge();
+`;
+      }
+    },
+
+    transformIndexHtml(html) {
+      if (options.devBridge === false) return html;
+
+      // Inject a script that imports the virtual module — Vite resolves it properly
+      const devScript = `<script type="module" src="/${VIRTUAL_DEV_BRIDGE_ID}"></script>`;
+
+      return html.replace('</head>', `${devScript}\n</head>`);
+    },
+  };
+}
+
+/**
+ * Create a pre-configured Vite config for game projects.
+ *
+ * Includes:
+ * - PixiJS optimization (exclude from dep optimization)
+ * - DevBridge injection in dev mode
+ * - HTML minification
+ * - Gzip-friendly output
+ * - Configurable base path for S3/CDN deploy
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { defineGameConfig } from '@energy8platform/game-engine/vite';
+ *
+ * export default defineGameConfig({
+ *   base: '/games/my-slot/',
+ *   devBridge: true,
+ * });
+ * ```
+ */
+export function defineGameConfig(config: GameViteConfig = {}): UserConfig {
+  const assetExtensions = config.assetExtensions ?? [
+    'png', 'jpg', 'jpeg', 'gif', 'webp', 'avif', 'svg',
+    'mp3', 'ogg', 'wav', 'webm',
+    'json', 'atlas', 'skel',
+    'fnt', 'ttf', 'otf', 'woff', 'woff2',
+    'mp4', 'm4v',
+  ];
+
+  return {
+    base: config.base ?? '/',
+
+    plugins: [
+      gameEngineDevPlugin({ devBridge: config.devBridge ?? true }),
+      ...(config.vite?.plugins ?? []) as Plugin[],
+    ],
+
+    build: {
+      outDir: config.outDir ?? 'dist',
+      target: 'es2022',
+      minify: 'terser',
+      sourcemap: false,
+      assetsInlineLimit: 4096,
+      rollupOptions: {
+        output: {
+          assetFileNames: 'assets/[name]-[hash][extname]',
+          chunkFileNames: 'js/[name]-[hash].js',
+          entryFileNames: 'js/[name]-[hash].js',
+        },
+      },
+      ...(config.vite?.build ?? {}),
+    },
+
+    optimizeDeps: {
+      // Pre-bundle libs for fast dev startup
+      include: ['pixi.js'],
+      exclude: ['@esotericsoftware/spine-pixi-v8'],
+    },
+
+    assetsInclude: assetExtensions.map((ext) => `**/*.${ext}`),
+
+    server: {
+      port: 3000,
+      open: true,
+      ...(config.vite?.server ?? {}),
+    },
+
+    resolve: {
+      ...(config.vite?.resolve ?? {}),
+    },
+
+    // Spread any additional user overrides
+    ...Object.fromEntries(
+      Object.entries(config.vite ?? {}).filter(
+        ([key]) => !['plugins', 'build', 'server', 'resolve'].includes(key),
+      ),
+    ),
+  };
+}
+
+export { gameEngineDevPlugin };