@energy8platform/game-engine 0.1.0

package/README.md

@@ -0,0 +1,1134 @@
+# @energy8platform/game-engine
+
+A universal casino game engine built on [PixiJS v8](https://pixijs.com/) and [@energy8platform/game-sdk](https://github.com/energy8platform/game-sdk). Provides a batteries-included framework for developing slot machines, card games, and other iGaming titles with responsive scaling, animated loading screens, scene management, audio, state machines, tweens, and a rich UI component library.
+
+---
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Architecture](#architecture)
+- [Configuration](#configuration)
+- [Scenes](#scenes)
+- [Lifecycle](#lifecycle)
+- [Assets](#assets)
+- [Audio](#audio)
+- [Viewport & Scaling](#viewport--scaling)
+- [State Machine](#state-machine)
+- [Animation](#animation)
+- [UI Components](#ui-components)
+- [Input](#input)
+- [Vite Configuration](#vite-configuration)
+- [DevBridge](#devbridge)
+- [Debug](#debug)
+- [API Reference](#api-reference)
+- [License](#license)
+
+---
+
+## Quick Start
+
+```bash
+# Create a new project
+mkdir my-game && cd my-game
+npm init -y
+
+# Install dependencies
+npm install pixi.js @energy8platform/game-sdk @energy8platform/game-engine
+
+# (Optional) install spine and audio support
+npm install @pixi/sound @esotericsoftware/spine-pixi-v8
+```
+
+Create the entry point:
+
+```typescript
+// src/main.ts
+import { GameApplication, ScaleMode } from '@energy8platform/game-engine';
+import { GameScene } from './scenes/GameScene';
+
+async function bootstrap() {
+  const game = new GameApplication({
+    container: '#game',
+    designWidth: 1920,
+    designHeight: 1080,
+    scaleMode: ScaleMode.FIT,
+    loading: {
+      backgroundColor: 0x0a0a1a,
+      backgroundGradient:
+        'linear-gradient(135deg, #0a0a1a 0%, #1a1a3e 50%, #0a0a1a 100%)',
+      showPercentage: true,
+      tapToStart: true,
+      tapToStartText: 'TAP TO PLAY',
+      minDisplayTime: 2000,
+    },
+    manifest: {
+      bundles: [
+        { name: 'preload', assets: [] },
+        {
+          name: 'game',
+          assets: [
+            { alias: 'background', src: 'background.png' },
+            { alias: 'symbols', src: 'symbols.json' },
+          ],
+        },
+      ],
+    },
+    audio: {
+      music: 0.5,
+      sfx: 1.0,
+      persist: true,
+    },
+    debug: true,
+  });
+
+  game.scenes.register('game', GameScene as any);
+
+  game.on('initialized', () => console.log('Engine initialized'));
+  game.on('loaded', () => console.log('Assets loaded'));
+  game.on('started', () => console.log('Game started'));
+  game.on('error', (err) => console.error('Error:', err));
+
+  await game.start('game');
+}
+
+bootstrap();
+```
+
+---
+
+## Installation
+
+### Peer Dependencies
+
+| Package | Version | Required |
+| --- | --- | --- |
+| `pixi.js` | `^8.16.0` | Yes |
+| `@energy8platform/game-sdk` | `^2.5.0` | Yes |
+| `@pixi/sound` | `^6.0.0` | Optional — for audio |
+| `@esotericsoftware/spine-pixi-v8` | `~4.2.0` | Optional — for Spine animations |
+
+### Sub-path Exports
+
+The package exposes granular entry points for tree-shaking:
+
+```typescript
+import { GameApplication } from '@energy8platform/game-engine';        // full bundle
+import { Scene, SceneManager } from '@energy8platform/game-engine/core';
+import { AssetManager } from '@energy8platform/game-engine/assets';
+import { AudioManager } from '@energy8platform/game-engine/audio';
+import { Button, Label, Modal } from '@energy8platform/game-engine/ui';
+import { Tween, Timeline, Easing } from '@energy8platform/game-engine/animation';
+import { DevBridge, FPSOverlay } from '@energy8platform/game-engine/debug';
+import { defineGameConfig } from '@energy8platform/game-engine/vite';
+```
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────┐
+│                   GameApplication                    │
+│  (orchestrates lifecycle, holds all sub-systems)     │
+├──────────┬───────────┬───────────┬───────────────────┤
+│ Viewport │  Scenes   │  Assets   │  Audio  │  Input  │
+│ Manager  │  Manager  │  Manager  │ Manager │ Manager │
+├──────────┴───────────┴───────────┴─────────┴─────────┤
+│                    PixiJS v8 Application              │
+├──────────────────────────────────────────────────────┤
+│              @energy8platform/game-sdk                │
+└──────────────────────────────────────────────────────┘
+```
+
+### Boot Sequence
+
+1. **CSS Preloader** — an instant HTML/CSS overlay shown while PixiJS initializes (inline SVG logo with a shimmer animation and "Loading..." text).
+2. **PixiJS initialization** — creates `Application`, initializes `ResizeObserver`.
+3. **SDK handshake** — connects to the casino host (or DevBridge in dev mode).
+4. **Canvas Loading Screen** — `LoadingScene` displays the SVG logo with an animated progress bar, `preload` bundle is loaded first.
+5. **Asset loading** — remaining bundles are loaded; the progress bar fills in real time.
+6. **Tap-to-start** — optional screen shown after loading (required on mobile for audio unlock).
+7. **First scene** — transitions to the registered first scene.
+
+---
+
+## Configuration
+
+### `GameApplicationConfig`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `container` | `HTMLElement \| string` | `document.body` | Container element or CSS selector |
+| `designWidth` | `number` | `1920` | Reference design width |
+| `designHeight` | `number` | `1080` | Reference design height |
+| `scaleMode` | `ScaleMode` | `FIT` | Scaling strategy |
+| `orientation` | `Orientation` | `ANY` | Preferred orientation |
+| `loading` | `LoadingScreenConfig` | — | Loading screen options |
+| `manifest` | `AssetManifest` | — | Asset manifest |
+| `audio` | `AudioConfig` | — | Audio configuration |
+| `sdk` | `object \| false` | — | SDK options; `false` to disable |
+| `pixi` | `Partial<ApplicationOptions>` | — | PixiJS pass-through options |
+| `debug` | `boolean` | `false` | Enable FPS overlay |
+
+### `LoadingScreenConfig`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `backgroundColor` | `number \| string` | `0x0a0a1a` | Background color |
+| `backgroundGradient` | `string` | — | CSS gradient for the preloader background |
+| `logoAsset` | `string` | — | Logo texture alias from `preload` bundle |
+| `logoScale` | `number` | `1` | Logo scale factor |
+| `showPercentage` | `boolean` | `true` | Show loading percentage text |
+| `progressTextFormatter` | `(progress: number) => string` | — | Custom progress text formatter |
+| `tapToStart` | `boolean` | `false` | Show "Tap to start" overlay |
+| `tapToStartText` | `string` | `'TAP TO START'` | Tap-to-start label |
+| `minDisplayTime` | `number` | `0` | Minimum display time (ms) |
+| `cssPreloaderHTML` | `string` | — | Custom HTML for the CSS preloader |
+
+### `AudioConfig`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `music` | `number` | `1` | Default music volume (0–1) |
+| `sfx` | `number` | `1` | Default SFX volume |
+| `ui` | `number` | `1` | Default UI sounds volume |
+| `ambient` | `number` | `1` | Default ambient volume |
+| `persist` | `boolean` | `false` | Save mute state to localStorage |
+| `storageKey` | `string` | `'ge-audio'` | localStorage key prefix |
+
+### Enums
+
+```typescript
+enum ScaleMode {
+  FIT = 'FIT',       // Letterbox/pillarbox — preserves aspect ratio
+  FILL = 'FILL',     // Fill container, crop edges
+  STRETCH = 'STRETCH' // Stretch to fill (distorts)
+}
+
+enum Orientation {
+  LANDSCAPE = 'landscape',
+  PORTRAIT = 'portrait',
+  ANY = 'any'
+}
+
+enum TransitionType {
+  NONE = 'none',
+  FADE = 'fade',
+  SLIDE_LEFT = 'slide-left',
+  SLIDE_RIGHT = 'slide-right'
+}
+```
+
+---
+
+## Scenes
+
+All game screens are scenes. Extend the base `Scene` class and override lifecycle hooks:
+
+```typescript
+import { Scene } from '@energy8platform/game-engine';
+import { Sprite, Assets } from 'pixi.js';
+
+export class GameScene extends Scene {
+  async onEnter(data?: unknown) {
+    const bg = new Sprite(Assets.get('background'));
+    this.container.addChild(bg);
+  }
+
+  onUpdate(dt: number) {
+    // Called every frame (dt = delta time from PixiJS ticker)
+  }
+
+  onResize(width: number, height: number) {
+    // Called on viewport resize — use for responsive layout
+  }
+
+  async onExit() {
+    // Cleanup before leaving the scene
+  }
+
+  onDestroy() {
+    // Final cleanup when the scene is removed from the stack
+  }
+}
+```
+
+### Scene Navigation
+
+```typescript
+const scenes = game.scenes;
+
+// Register scenes
+scenes.register('menu', MenuScene as any);
+scenes.register('game', GameScene as any);
+scenes.register('bonus', BonusScene as any);
+
+// Navigate (replaces entire stack)
+await scenes.goto('game');
+
+// Push overlay/modal (previous scene stays rendered)
+await scenes.push('bonus', { multiplier: 3 });
+
+// Pop back
+await scenes.pop();
+
+// Replace top scene
+await scenes.replace('game');
+```
+
+### Transitions
+
+```typescript
+import { TransitionType } from '@energy8platform/game-engine';
+
+await scenes.goto('game', undefined, {
+  type: TransitionType.FADE,
+  duration: 500,    // ms
+});
+
+await scenes.push('bonus', { data: 42 }, {
+  type: TransitionType.SLIDE_LEFT,
+  duration: 300,
+  easing: Easing.easeOutCubic,
+});
+```
+
+---
+
+## Lifecycle
+
+`GameApplication` emits the following events:
+
+| Event | Payload | When |
+| --- | --- | --- |
+| `initialized` | `void` | Engine initialized, PixiJS and SDK are ready |
+| `loaded` | `void` | All asset bundles loaded |
+| `started` | `void` | First scene entered, game loop running |
+| `resize` | `{ width, height }` | Viewport resized |
+| `orientationChange` | `Orientation` | Device orientation changed |
+| `sceneChange` | `{ from, to }` | Scene transition completed |
+| `error` | `Error` | An error occurred |
+| `destroyed` | `void` | Engine destroyed |
+
+```typescript
+game.on('resize', ({ width, height }) => {
+  console.log(`New size: ${width}x${height}`);
+});
+
+game.once('started', () => {
+  // Runs once after the first scene starts
+});
+```
+
+---
+
+## Assets
+
+### Asset Manifest
+
+Assets are organized in named **bundles**:
+
+```typescript
+const manifest: AssetManifest = {
+  bundles: [
+    {
+      name: 'preload',
+      assets: [
+        { alias: 'logo', src: 'logo.png' },
+      ],
+    },
+    {
+      name: 'game',
+      assets: [
+        { alias: 'background', src: 'bg.webp' },
+        { alias: 'symbols', src: 'symbols.json' },
+        { alias: 'win-sound', src: 'sounds/win.mp3' },
+      ],
+    },
+    {
+      name: 'bonus',
+      assets: [
+        { alias: 'bonus-bg', src: 'bonus/bg.webp' },
+      ],
+    },
+  ],
+};
+```
+
+The `preload` bundle is loaded first (before the progress bar fills). All other bundles load together with a combined progress indicator.
+
+### AssetManager API
+
+```typescript
+const assets = game.assets;
+
+// Load on demand
+await assets.loadBundle('bonus', (progress) => {
+  console.log(`${Math.round(progress * 100)}%`);
+});
+
+// Synchronous cache access
+const texture = assets.get<Texture>('background');
+
+// Background preloading (low priority)
+await assets.backgroundLoad('bonus');
+
+// Unload to free memory
+await assets.unloadBundle('bonus');
+
+// Check state
+assets.isBundleLoaded('game');  // true
+assets.getBundleNames();         // ['preload', 'game', 'bonus']
+```
+
+---
+
+## Audio
+
+`AudioManager` wraps `@pixi/sound` with category-based volume management. If `@pixi/sound` is not installed, all methods work silently as no-ops.
+
+### Audio Categories
+
+Four categories with independent volume and mute controls: `music`, `sfx`, `ui`, `ambient`.
+
+```typescript
+const audio = game.audio;
+
+// Play a sound effect
+audio.play('click', 'ui');
+audio.play('coin-drop', 'sfx', { volume: 0.8 });
+
+// Music with crossfade
+audio.playMusic('main-theme', 1000); // 1s crossfade
+audio.stopMusic();
+
+// Volume control
+audio.setVolume('music', 0.3);
+audio.muteCategory('sfx');
+audio.unmuteCategory('sfx');
+audio.toggleCategory('sfx'); // returns new state
+
+// Global mute
+audio.muteAll();
+audio.unmuteAll();
+audio.toggleMute(); // returns new state
+
+// Music ducking (e.g., during a big win animation)
+audio.duckMusic(0.2);  // reduce to 20%
+audio.unduckMusic();    // restore
+```
+
+### Mobile Audio Unlock
+
+On iOS and many mobile browsers, audio cannot play until the first user interaction. The engine handles this automatically when `tapToStart: true` is set — the tap event serves as the audio context unlock.
+
+---
+
+## Viewport & Scaling
+
+`ViewportManager` handles responsive scaling using `ResizeObserver` with debouncing.
+
+### Scale Modes
+
+| Mode | Behavior |
+| --- | --- |
+| `FIT` | Fits the entire design area inside the container. Adds letterbox (horizontal bars) or pillarbox (vertical bars) as needed. **Industry standard for iGaming.** |
+| `FILL` | Fills the entire container, cropping edges. No bars, but some content may be hidden. |
+| `STRETCH` | Stretches to fill the container. Distorts aspect ratio. Not recommended. |
+
+```typescript
+const vp = game.viewport;
+
+// Current dimensions
+console.log(vp.width, vp.height, vp.scale);
+console.log(vp.orientation); // 'landscape' | 'portrait'
+
+// Reference design size
+console.log(vp.designWidth, vp.designHeight);
+
+// Force re-calculation
+vp.refresh();
+
+// Listen for changes
+game.on('resize', ({ width, height }) => {
+  // Respond to viewport changes
+});
+```
+
+---
+
+## State Machine
+
+`StateMachine` is a generic finite state machine with typed context, async hooks, guards, and per-frame updates.
+
+```typescript
+import { StateMachine } from '@energy8platform/game-engine';
+
+interface GameContext {
+  balance: number;
+  bet: number;
+  lastWin: number;
+}
+
+const fsm = new StateMachine<GameContext>({
+  balance: 10000,
+  bet: 100,
+  lastWin: 0,
+});
+
+fsm.addState('idle', {
+  enter: (ctx) => console.log('Waiting for player...'),
+  update: (ctx, dt) => { /* per-frame logic */ },
+});
+
+fsm.addState('spinning', {
+  enter: async (ctx) => {
+    // Play spin animation
+    await spinReels();
+    // Auto-transition to result
+    await fsm.transition('result');
+  },
+});
+
+fsm.addState('result', {
+  enter: async (ctx) => {
+    if (ctx.lastWin > 0) {
+      await showWinAnimation(ctx.lastWin);
+    }
+    await fsm.transition('idle');
+  },
+});
+
+// Guards
+fsm.addGuard('idle', 'spinning', (ctx) => ctx.balance >= ctx.bet);
+
+// Events
+fsm.on('transition', ({ from, to }) => {
+  console.log(`${from} → ${to}`);
+});
+
+// Start
+await fsm.start('idle');
+
+// Trigger transitions
+const success = await fsm.transition('spinning');
+if (!success) {
+  console.log('Transition blocked by guard');
+}
+
+// Per-frame update (usually called from Scene.onUpdate)
+fsm.update(dt);
+```
+
+---
+
+## Animation
+
+### Tween
+
+`Tween` provides a Promise-based animation system integrated with the PixiJS Ticker:
+
+```typescript
+import { Tween, Easing } from '@energy8platform/game-engine';
+
+// Animate to target values
+await Tween.to(sprite, { alpha: 0, y: 100 }, 500, Easing.easeOutCubic);
+
+// Animate from starting values to current
+await Tween.from(sprite, { scale: 0 }, 300, Easing.easeOutBack);
+
+// Animate between two sets of values
+await Tween.fromTo(sprite, { x: -100 }, { x: 500 }, 1000, Easing.easeInOutQuad);
+
+// Wait (useful in timelines or sequences)
+await Tween.delay(1000);
+
+// Cancel tweens
+Tween.killTweensOf(sprite);
+Tween.killAll();
+
+// Supports nested properties
+await Tween.to(sprite, { 'scale.x': 2, 'position.y': 300 }, 500);
+```
+
+### Timeline
+
+`Timeline` chains sequential and parallel animation steps:
+
+```typescript
+import { Timeline, Tween, Easing } from '@energy8platform/game-engine';
+
+const tl = new Timeline();
+
+tl.to(title, { alpha: 1, y: 0 }, 500, Easing.easeOutCubic)
+  .delay(200)
+  .parallel(
+    () => Tween.to(btn1, { alpha: 1 }, 300),
+    () => Tween.to(btn2, { alpha: 1 }, 300),
+    () => Tween.to(btn3, { alpha: 1 }, 300),
+  )
+  .call(() => console.log('Intro complete!'));
+
+await tl.play();
+```
+
+### Available Easings
+
+All 24 easing functions:
+
+| Linear | Quad | Cubic | Quart |
+| --- | --- | --- | --- |
+| `linear` | `easeInQuad` | `easeInCubic` | `easeInQuart` |
+| | `easeOutQuad` | `easeOutCubic` | `easeOutQuart` |
+| | `easeInOutQuad` | `easeInOutCubic` | `easeInOutQuart` |
+
+| Sine | Expo | Back | Bounce / Elastic |
+| --- | --- | --- | --- |
+| `easeInSine` | `easeInExpo` | `easeInBack` | `easeOutBounce` |
+| `easeOutSine` | `easeOutExpo` | `easeOutBack` | `easeInBounce` |
+| `easeInOutSine` | `easeInOutExpo` | `easeInOutBack` | `easeInOutBounce` |
+| | | | `easeOutElastic` |
+| | | | `easeInElastic` |
+
+### Spine Animations
+
+If `@esotericsoftware/spine-pixi-v8` is installed:
+
+```typescript
+import { SpineHelper } from '@energy8platform/game-engine';
+
+// Create a Spine instance
+const spine = await SpineHelper.create('character-skel', 'character-atlas', {
+  scale: 0.5,
+});
+container.addChild(spine);
+
+// Play animation (returns Promise that resolves on completion)
+await SpineHelper.playAnimation(spine, 'idle', true); // loop
+
+// Queue animation
+SpineHelper.addAnimation(spine, 'walk', 0.2, true);
+
+// Skins
+SpineHelper.setSkin(spine, 'warrior');
+console.log(SpineHelper.getSkinNames(spine));
+console.log(SpineHelper.getAnimationNames(spine));
+```
+
+---
+
+## UI Components
+
+### Button
+
+```typescript
+import { Button } from '@energy8platform/game-engine';
+
+const spinBtn = new Button({
+  width: 200,
+  height: 60,
+  borderRadius: 12,
+  colors: {
+    normal: 0xffd700,
+    hover: 0xffe44d,
+    pressed: 0xccac00,
+    disabled: 0x666666,
+  },
+  pressScale: 0.95,
+  animationDuration: 100,
+});
+
+spinBtn.onTap = () => {
+  console.log('Spin!');
+};
+
+// Or use texture-based states
+const btn = new Button({
+  textures: {
+    normal: 'btn-normal',
+    hover: 'btn-hover',
+    pressed: 'btn-pressed',
+    disabled: 'btn-disabled',
+  },
+});
+
+btn.enable();
+btn.disable();
+```
+
+### Label
+
+```typescript
+import { Label } from '@energy8platform/game-engine';
+
+const label = new Label({
+  text: 'TOTAL WIN',
+  style: { fontSize: 36, fill: 0xffffff },
+});
+```
+
+### BalanceDisplay
+
+Displays player balance with formatting:
+
+```typescript
+import { BalanceDisplay } from '@energy8platform/game-engine';
+
+const balance = new BalanceDisplay({
+  initialBalance: 10000,
+  currency: 'USD',
+  // ... text style options
+});
+
+balance.updateBalance(9500); // Animates the balance change
+```
+
+### WinDisplay
+
+Animated win amount display with countup:
+
+```typescript
+import { WinDisplay } from '@energy8platform/game-engine';
+
+const winDisplay = new WinDisplay({
+  // ... text style options
+});
+
+await winDisplay.show(5000, 2000); // Show $50.00, countup over 2 seconds
+winDisplay.hide();
+```
+
+### ProgressBar
+
+```typescript
+import { ProgressBar } from '@energy8platform/game-engine';
+
+const bar = new ProgressBar({
+  width: 400,
+  height: 20,
+  fillColor: 0x00ff00,
+  backgroundColor: 0x333333,
+  borderRadius: 10,
+});
+
+bar.setProgress(0.75); // 75%
+```
+
+### Panel
+
+Container with a background:
+
+```typescript
+import { Panel } from '@energy8platform/game-engine';
+
+const panel = new Panel({
+  width: 600,
+  height: 400,
+  backgroundColor: 0x1a1a2e,
+  borderRadius: 16,
+  alpha: 0.9,
+});
+```
+
+### Modal
+
+Full-screen overlay dialog:
+
+```typescript
+import { Modal } from '@energy8platform/game-engine';
+
+const modal = new Modal({
+  width: 500,
+  height: 350,
+  overlayAlpha: 0.7,
+  backgroundColor: 0x222244,
+  borderRadius: 16,
+});
+
+await modal.show();
+await modal.hide();
+```
+
+### Toast
+
+Brief notification messages:
+
+```typescript
+import { Toast } from '@energy8platform/game-engine';
+
+const toast = new Toast({
+  duration: 2000,
+  backgroundColor: 0x333333,
+  textStyle: { fill: 0xffffff, fontSize: 20 },
+});
+
+await toast.show('Free spins activated!');
+```
+
+---
+
+## Input
+
+`InputManager` provides unified touch/mouse/keyboard handling with gesture detection:
+
+```typescript
+const input = game.input;
+
+// Tap/click
+input.on('tap', ({ x, y }) => {
+  console.log(`Tap at ${x}, ${y}`);
+});
+
+// Swipe gesture
+input.on('swipe', ({ direction, velocity }) => {
+  console.log(`Swipe ${direction} at ${velocity}px/s`);
+  // direction: 'up' | 'down' | 'left' | 'right'
+});
+
+// Keyboard
+input.on('keydown', ({ key, code }) => {
+  if (code === 'Space') startSpin();
+});
+
+// Check current key state
+if (input.isKeyDown('ArrowLeft')) {
+  // Move left
+}
+
+// Lock input during animations
+input.lock();
+// ... animation plays ...
+input.unlock();
+```
+
+**Events:** `tap`, `press`, `release`, `move`, `swipe`, `keydown`, `keyup`
+
+---
+
+## Vite Configuration
+
+The engine provides a pre-configured Vite setup via `defineGameConfig`:
+
+```typescript
+// vite.config.ts
+import { defineGameConfig } from '@energy8platform/game-engine/vite';
+
+export default defineGameConfig({
+  base: '/games/my-slot/',
+  outDir: 'dist',
+  devBridge: true, // Auto-inject DevBridge in dev mode
+  assetExtensions: [
+    'png', 'jpg', 'webp', 'avif',
+    'mp3', 'ogg', 'wav',
+    'json', 'atlas', 'skel',
+    'fnt', 'ttf', 'woff2',
+  ],
+  vite: {
+    // Additional Vite config overrides
+  },
+});
+```
+
+### What `defineGameConfig` Provides
+
+- **PixiJS optimizations** — tree-shaking, proper externals handling
+- **DevBridge injection** — automatically available in dev mode via virtual module
+- **Asset handling** — preconfigured loader patterns for game assets
+- **HTML minification** — optimized production builds
+- **Gzip-friendly output** — chunking strategy optimized for compression
+- **Base path** — configurable for deployment subpaths
+
+### Custom DevBridge Configuration
+
+Create `dev.config.ts` at the project root:
+
+```typescript
+// dev.config.ts
+import type { DevBridgeConfig } from '@energy8platform/game-engine/debug';
+
+export default {
+  balance: 50000,
+  currency: 'EUR',
+  networkDelay: 100,
+  onPlay: ({ action, bet }) => {
+    // Custom play result logic
+    const win = Math.random() < 0.3 ? bet * 10 : 0;
+    return { win, balance: 50000 - bet + win };
+  },
+} satisfies DevBridgeConfig;
+```
+
+This file is auto-imported by the Vite plugin when `devBridge: true`.
+
+---
+
+## DevBridge
+
+`DevBridge` simulates a casino host for local development. It intercepts `postMessage` calls from the SDK and responds with mock data.
+
+```typescript
+import { DevBridge } from '@energy8platform/game-engine/debug';
+
+const bridge = new DevBridge({
+  balance: 10000,
+  currency: 'USD',
+  assetsUrl: '/assets/',
+  networkDelay: 200,
+  debug: true,
+  gameConfig: {
+    viewport: { width: 1920, height: 1080 },
+  },
+  onPlay: ({ action, bet, roundId }) => {
+    // Return custom play result
+    const win = Math.random() < 0.4 ? bet * 5 : 0;
+    return { win };
+  },
+});
+
+bridge.start();
+
+// Update balance programmatically
+bridge.setBalance(5000);
+
+// Cleanup
+bridge.destroy();
+```
+
+### Handled Messages
+
+| Message | Description |
+| --- | --- |
+| `GAME_READY` | SDK initialization handshake |
+| `PLAY_REQUEST` | Player action (spin, deal, etc.) |
+| `PLAY_RESULT_ACK` | Acknowledge play result |
+| `GET_BALANCE` | Balance query |
+| `GET_STATE` | Game state query |
+| `OPEN_DEPOSIT` | Deposit dialog request |
+
+---
+
+## Debug
+
+### FPS Overlay
+
+```typescript
+import { FPSOverlay } from '@energy8platform/game-engine/debug';
+
+const fps = new FPSOverlay(game.app);
+fps.show();
+fps.toggle();
+fps.hide();
+```
+
+When `debug: true` is set in `GameApplicationConfig`, the FPS overlay is enabled automatically.
+
+The overlay displays:
+- Average FPS
+- Minimum FPS
+- Frame time (ms)
+
+Updated every ~500ms, sampled over 60 frames.
+
+---
+
+## API Reference
+
+### GameApplication
+
+```typescript
+class GameApplication extends EventEmitter<GameEngineEvents> {
+  // Fields
+  app: Application;
+  scenes: SceneManager;
+  assets: AssetManager;
+  audio: AudioManager;
+  viewport: ViewportManager;
+  sdk: CasinoGameSDK | null;
+  initData: InitData | null;
+  readonly config: GameApplicationConfig;
+
+  // Getters
+  get gameConfig(): GameConfigData | null;
+  get session(): SessionData | null;
+  get balance(): number;
+  get currency(): string;
+  get isRunning(): boolean;
+
+  // Methods
+  constructor(config?: GameApplicationConfig);
+  async start(firstScene: string, sceneData?: unknown): Promise<void>;
+  destroy(): void;
+}
+```
+
+### SceneManager
+
+```typescript
+class SceneManager extends EventEmitter<{ change: { from: string | null; to: string } }> {
+  get current(): SceneEntry | null;
+  get currentKey(): string | null;
+  get isTransitioning(): boolean;
+
+  setRoot(root: Container): void;
+  register(key: string, ctor: SceneConstructor): this;
+  async goto(key: string, data?: unknown, transition?: TransitionConfig): Promise<void>;
+  async push(key: string, data?: unknown, transition?: TransitionConfig): Promise<void>;
+  async pop(transition?: TransitionConfig): Promise<void>;
+  async replace(key: string, data?: unknown, transition?: TransitionConfig): Promise<void>;
+  update(dt: number): void;
+  resize(width: number, height: number): void;
+  destroy(): void;
+}
+```
+
+### AssetManager
+
+```typescript
+class AssetManager {
+  get initialized(): boolean;
+  get basePath(): string;
+  get loadedBundles(): ReadonlySet<string>;
+
+  constructor(basePath?: string, manifest?: AssetManifest);
+  async init(): Promise<void>;
+  async loadBundle(name: string, onProgress?: (p: number) => void): Promise<Record<string, unknown>>;
+  async loadBundles(names: string[], onProgress?: (p: number) => void): Promise<Record<string, unknown>>;
+  async load<T>(urls: string | string[], onProgress?: (p: number) => void): Promise<T>;
+  get<T>(alias: string): T;
+  async unloadBundle(name: string): Promise<void>;
+  async backgroundLoad(name: string): Promise<void>;
+  getBundleNames(): string[];
+  isBundleLoaded(name: string): boolean;
+}
+```
+
+### AudioManager
+
+```typescript
+class AudioManager {
+  get initialized(): boolean;
+  get muted(): boolean;
+
+  constructor(config?: AudioConfig);
+  async init(): Promise<void>;
+  play(alias: string, category?: AudioCategoryName, options?: { volume?: number; loop?: boolean; speed?: number }): void;
+  playMusic(alias: string, fadeDuration?: number): void;
+  stopMusic(): void;
+  stopAll(): void;
+  setVolume(category: AudioCategoryName, volume: number): void;
+  getVolume(category: AudioCategoryName): number;
+  muteCategory(category: AudioCategoryName): void;
+  unmuteCategory(category: AudioCategoryName): void;
+  toggleCategory(category: AudioCategoryName): boolean;
+  muteAll(): void;
+  unmuteAll(): void;
+  toggleMute(): boolean;
+  duckMusic(factor: number): void;
+  unduckMusic(): void;
+  destroy(): void;
+}
+```
+
+### ViewportManager
+
+```typescript
+class ViewportManager extends EventEmitter<ViewportEvents> {
+  get width(): number;
+  get height(): number;
+  get scale(): number;
+  get orientation(): Orientation;
+  get designWidth(): number;
+  get designHeight(): number;
+
+  constructor(app: Application, container: HTMLElement, config: ViewportConfig);
+  refresh(): void;
+  destroy(): void;
+}
+```
+
+### StateMachine
+
+```typescript
+class StateMachine<TContext> extends EventEmitter<StateMachineEvents> {
+  get current(): string | null;
+  get isTransitioning(): boolean;
+  get context(): TContext;
+
+  constructor(context: TContext);
+  addState(name: string, config: { enter?, exit?, update? }): this;
+  addGuard(from: string, to: string, guard: (ctx: TContext) => boolean): this;
+  async start(initialState: string, data?: unknown): Promise<void>;
+  async transition(to: string, data?: unknown): Promise<boolean>;
+  update(dt: number): void;
+  hasState(name: string): boolean;
+  canTransition(to: string): boolean;
+  async reset(): Promise<void>;
+  async destroy(): Promise<void>;
+}
+```
+
+### Tween
+
+```typescript
+class Tween {
+  static get activeTweens(): number;
+
+  static to(target: any, props: Record<string, number>, duration: number, easing?: EasingFunction, onUpdate?: (p: number) => void): Promise<void>;
+  static from(target: any, props: Record<string, number>, duration: number, easing?, onUpdate?): Promise<void>;
+  static fromTo(target: any, fromProps: Record<string, number>, toProps: Record<string, number>, duration: number, easing?, onUpdate?): Promise<void>;
+  static delay(ms: number): Promise<void>;
+  static killTweensOf(target: any): void;
+  static killAll(): void;
+}
+```
+
+### Timeline
+
+```typescript
+class Timeline {
+  get isPlaying(): boolean;
+
+  to(target: any, props: Record<string, number>, duration: number, easing?: EasingFunction): this;
+  from(target: any, props: Record<string, number>, duration: number, easing?: EasingFunction): this;
+  delay(ms: number): this;
+  call(fn: () => void | Promise<void>): this;
+  parallel(...fns: Array<() => Promise<void>>): this;
+  async play(): Promise<void>;
+  cancel(): void;
+  clear(): this;
+}
+```
+
+### InputManager
+
+```typescript
+class InputManager extends EventEmitter<InputEvents> {
+  get locked(): boolean;
+
+  constructor(canvas: HTMLCanvasElement);
+  lock(): void;
+  unlock(): void;
+  isKeyDown(key: string): boolean;
+  destroy(): void;
+}
+```
+
+### EventEmitter
+
+```typescript
+class EventEmitter<TEvents extends {}> {
+  on<K>(event: K, handler: (data: TEvents[K]) => void): this;
+  once<K>(event: K, handler: (data: TEvents[K]) => void): this;
+  off<K>(event: K, handler: (data: TEvents[K]) => void): this;
+  emit<K>(event: K, data: TEvents[K]): void;
+  removeAllListeners(event?: keyof TEvents): this;
+}
+```
+
+---
+
+## License
+
+MIT