@energy8platform/game-engine 0.2.1 → 0.3.0

package/README.md

@@ -17,7 +17,21 @@ A universal casino game engine built on [PixiJS v8](https://pixijs.com/) and [@e
 - [Viewport & Scaling](#viewport--scaling)
 - [State Machine](#state-machine)
 - [Animation](#animation)
+  - [Tween](#tween)
+  - [Timeline](#timeline)
+  - [SpriteAnimation](#spriteanimation)
+  - [Spine Animations](#spine-animations)
 - [UI Components](#ui-components)
+  - [Layout](#layout)
+  - [ScrollContainer](#scrollcontainer)
+  - [Button](#button)
+  - [Label](#label)
+  - [BalanceDisplay](#balancedisplay)
+  - [WinDisplay](#windisplay)
+  - [ProgressBar](#progressbar)
+  - [Panel](#panel)
+  - [Modal](#modal)
+  - [Toast](#toast)
 - [Input](#input)
 - [Vite Configuration](#vite-configuration)
 - [DevBridge](#devbridge)
@@ -83,7 +97,7 @@ async function bootstrap() {
     debug: true,
   });
 
-  game.scenes.register('game', GameScene as any);
+  game.scenes.register('game', GameScene);
 
   game.on('initialized', () => console.log('Engine initialized'));
   game.on('loaded', () => console.log('Assets loaded'));
@@ -105,7 +119,7 @@ bootstrap();
 | Package | Version | Required |
 | --- | --- | --- |
 | `pixi.js` | `^8.16.0` | Yes |
-| `@energy8platform/game-sdk` | `^2.5.0` | Yes |
+| `@energy8platform/game-sdk` | `^2.6.0` | Yes |
 | `@pixi/sound` | `^6.0.0` | Optional — for audio |
 | `@esotericsoftware/spine-pixi-v8` | `~4.2.0` | Optional — for Spine animations |
 
@@ -118,8 +132,8 @@ import { GameApplication } from '@energy8platform/game-engine';        // full b
 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 { Button, Label, Modal, Layout, ScrollContainer } from '@energy8platform/game-engine/ui';
+import { Tween, Timeline, Easing, SpriteAnimation } from '@energy8platform/game-engine/animation';
 import { DevBridge, FPSOverlay } from '@energy8platform/game-engine/debug';
 import { defineGameConfig } from '@energy8platform/game-engine/vite';
 ```
@@ -146,7 +160,7 @@ import { defineGameConfig } from '@energy8platform/game-engine/vite';
 
 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).
+3. **SDK handshake** — connects to the casino host (or DevBridge in dev mode via shared `MemoryChannel`).
 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).
@@ -169,6 +183,10 @@ import { defineGameConfig } from '@energy8platform/game-engine/vite';
 | `manifest` | `AssetManifest` | — | Asset manifest |
 | `audio` | `AudioConfig` | — | Audio configuration |
 | `sdk` | `object \| false` | — | SDK options; `false` to disable |
+| `sdk.devMode` | `boolean` | `false` | Use in-memory channel instead of `postMessage` (no iframe needed) |
+| `sdk.parentOrigin` | `string` | — | Expected parent origin for `postMessage` validation |
+| `sdk.timeout` | `number` | — | SDK handshake timeout in ms |
+| `sdk.debug` | `boolean` | — | Enable SDK debug logging |
 | `pixi` | `Partial<ApplicationOptions>` | — | PixiJS pass-through options |
 | `debug` | `boolean` | `false` | Enable FPS overlay |
 
@@ -261,9 +279,9 @@ export class GameScene extends Scene {
 const scenes = game.scenes;
 
 // Register scenes
-scenes.register('menu', MenuScene as any);
-scenes.register('game', GameScene as any);
-scenes.register('bonus', BonusScene as any);
+scenes.register('menu', MenuScene);
+scenes.register('game', GameScene);
+scenes.register('bonus', BonusScene);
 
 // Navigate (replaces entire stack)
 await scenes.goto('game');
@@ -400,7 +418,7 @@ const audio = game.audio;
 audio.play('click', 'ui');
 audio.play('coin-drop', 'sfx', { volume: 0.8 });
 
-// Music with crossfade
+// Music with crossfade (smooth volume transition between tracks)
 audio.playMusic('main-theme', 1000); // 1s crossfade
 audio.stopMusic();
 
@@ -542,13 +560,17 @@ 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)
+// Wait (uses PixiJS Ticker for consistent timing)
 await Tween.delay(1000);
 
 // Cancel tweens
 Tween.killTweensOf(sprite);
 Tween.killAll();
 
+// Full reset — kill all tweens and remove ticker listener
+// Useful for cleanup between game instances, tests, or hot-reload
+Tween.reset();
+
 // Supports nested properties
 await Tween.to(sprite, { 'scale.x': 2, 'position.y': 300 }, 500);
 ```
@@ -592,6 +614,59 @@ All 24 easing functions:
 | | | | `easeOutElastic` |
 | | | | `easeInElastic` |
 
+### SpriteAnimation
+
+Frame-based animation helper wrapping PixiJS `AnimatedSprite`. Cheaper than Spine for simple frame sequences — perfect for coin showers, symbol animations, sparkle trails, and win celebrations.
+
+```typescript
+import { SpriteAnimation } from '@energy8platform/game-engine';
+import { Assets } from 'pixi.js';
+
+// From an array of textures
+const coinAnim = SpriteAnimation.create(coinTextures, {
+  fps: 30,
+  loop: true,
+});
+scene.container.addChild(coinAnim);
+
+// From a spritesheet using a name prefix
+const sheet = Assets.get('effects');
+const sparkle = SpriteAnimation.fromSpritesheet(sheet, 'sparkle_', {
+  fps: 24,
+  loop: true,
+});
+
+// From a numbered range (e.g., 'explosion_00' to 'explosion_24')
+const explosion = SpriteAnimation.fromRange(sheet, 'explosion_{i}', 0, 24, {
+  fps: 60,
+  loop: false,
+  onComplete: () => explosion.destroy(),
+});
+
+// From pre-loaded texture aliases
+const anim = SpriteAnimation.fromAliases(
+  ['frame_0', 'frame_1', 'frame_2', 'frame_3'],
+  { fps: 12 },
+);
+
+// Fire-and-forget: play once and auto-destroy
+const { sprite, finished } = SpriteAnimation.playOnce(coinTextures, {
+  fps: 30,
+});
+scene.container.addChild(sprite);
+await finished; // resolves when animation completes
+```
+
+#### SpriteAnimationConfig
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `fps` | `number` | `24` | Frames per second |
+| `loop` | `boolean` | `true` | Whether to loop |
+| `autoPlay` | `boolean` | `true` | Start playing immediately |
+| `onComplete` | `() => void` | — | Callback when animation completes (non-looping) |
+| `anchor` | `number \| { x, y }` | `0.5` | Anchor point |
+
 ### Spine Animations
 
 If `@esotericsoftware/spine-pixi-v8` is installed:
@@ -621,6 +696,136 @@ console.log(SpineHelper.getAnimationNames(spine));
 
 ## UI Components
 
+### Layout
+
+Responsive layout container that automatically arranges children. Supports horizontal, vertical, grid, and wrap modes with alignment, padding, gap, anchor positioning, and viewport breakpoints.
+
+```typescript
+import { Layout } from '@energy8platform/game-engine';
+
+// Horizontal toolbar anchored to bottom-center
+const toolbar = new Layout({
+  direction: 'horizontal',
+  gap: 20,
+  alignment: 'center',
+  anchor: 'bottom-center',
+  padding: 16,
+  breakpoints: {
+    768: { direction: 'vertical', gap: 10 },
+  },
+});
+
+toolbar.addItem(spinButton);
+toolbar.addItem(betLabel);
+toolbar.addItem(balanceDisplay);
+scene.container.addChild(toolbar);
+
+// Update position on resize
+toolbar.updateViewport(width, height);
+```
+
+```typescript
+// Grid layout for a symbol paytable
+const grid = new Layout({
+  direction: 'grid',
+  columns: 3,
+  gap: 16,
+  alignment: 'center',
+  anchor: 'center',
+  padding: [20, 40, 20, 40],
+});
+
+symbols.forEach((sym) => grid.addItem(sym));
+grid.updateViewport(viewWidth, viewHeight);
+```
+
+```typescript
+// Wrap layout — items flow and wrap to next line
+const tags = new Layout({
+  direction: 'wrap',
+  gap: 8,
+  maxWidth: 600,
+});
+```
+
+#### LayoutConfig
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `direction` | `'horizontal' \| 'vertical' \| 'grid' \| 'wrap'` | `'vertical'` | Layout direction |
+| `gap` | `number` | `0` | Gap between children (px) |
+| `padding` | `number \| [top, right, bottom, left]` | `0` | Inner padding |
+| `alignment` | `'start' \| 'center' \| 'end' \| 'stretch'` | `'start'` | Cross-axis alignment |
+| `anchor` | `LayoutAnchor` | `'top-left'` | Position relative to viewport |
+| `columns` | `number` | `2` | Column count (grid mode only) |
+| `maxWidth` | `number` | `Infinity` | Max width before wrapping (wrap mode) |
+| `autoLayout` | `boolean` | `true` | Auto-recalculate on add/remove |
+| `breakpoints` | `Record<number, Partial<LayoutConfig>>` | — | Override config per viewport width |
+
+**Anchor values:** `top-left`, `top-center`, `top-right`, `center-left`, `center`, `center-right`, `bottom-left`, `bottom-center`, `bottom-right`
+
+### ScrollContainer
+
+Scrollable container with touch/drag, mouse wheel, inertia deceleration, elastic overscroll bounce, snap-to-item, and auto-hiding scrollbars. Ideal for paytables, settings, bet history, and any content that doesn't fit on screen.
+
+```typescript
+import { ScrollContainer } from '@energy8platform/game-engine';
+
+const scroll = new ScrollContainer({
+  width: 600,
+  height: 400,
+  direction: 'vertical',
+  showScrollbar: true,
+  elasticity: 0.3,
+  inertia: 0.92,
+  borderRadius: 12,
+  backgroundColor: 0x1a1a2e,
+  backgroundAlpha: 0.8,
+});
+
+// Build scrollable content
+const list = new Container();
+for (let i = 0; i < 50; i++) {
+  const row = createRow(i);
+  row.y = i * 40;
+  list.addChild(row);
+}
+scroll.setContent(list);
+
+scene.container.addChild(scroll);
+```
+
+```typescript
+// Programmatic scrolling
+scroll.scrollTo(0, 200);            // scroll to y=200 with animation
+scroll.scrollTo(0, 200, false);     // instant jump
+scroll.scrollToItem(5);             // snap to item index (when snapSize is set)
+
+// Current position
+const { x, y } = scroll.scrollPosition;
+
+// Resize viewport
+scroll.resize(newWidth, newHeight);
+```
+
+#### ScrollContainerConfig
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `width` | `number` | — | Visible viewport width |
+| `height` | `number` | — | Visible viewport height |
+| `direction` | `'vertical' \| 'horizontal' \| 'both'` | `'vertical'` | Scroll direction |
+| `showScrollbar` | `boolean` | `true` | Show scrollbar(s) |
+| `scrollbarWidth` | `number` | `6` | Scrollbar width (px) |
+| `scrollbarColor` | `number` | `0xffffff` | Scrollbar color |
+| `scrollbarAlpha` | `number` | `0.4` | Scrollbar opacity |
+| `elasticity` | `number` | `0.3` | Overscroll bounce (0 = none) |
+| `inertia` | `number` | `0.92` | Deceleration factor (0 = instant stop) |
+| `snapSize` | `number` | `0` | Snap to fixed increments (0 = disabled) |
+| `backgroundColor` | `number` | — | Background color (transparent if omitted) |
+| `backgroundAlpha` | `number` | `1` | Background opacity |
+| `borderRadius` | `number` | `0` | Mask border radius |
+
 ### Button
 
 ```typescript
@@ -799,10 +1004,17 @@ if (input.isKeyDown('ArrowLeft')) {
 input.lock();
 // ... animation plays ...
 input.unlock();
+
+// Convert DOM canvas position to game-world coordinates
+// (accounts for viewport scaling and offset)
+const worldPos = input.getWorldPosition(canvasX, canvasY);
+console.log(worldPos.x, worldPos.y);
 ```
 
 **Events:** `tap`, `press`, `release`, `move`, `swipe`, `keydown`, `keyup`
 
+> **Note:** The viewport transform for coordinate mapping is wired up automatically by `GameApplication`. Call `getWorldPosition()` when you need to convert raw DOM coordinates to game-world space.
+
 ---
 
 ## Vite Configuration
@@ -815,28 +1027,31 @@ 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',
-  ],
+  devBridgeConfig: './dev.config', // Custom config path (optional)
   vite: {
     // Additional Vite config overrides
   },
 });
 ```
 
+### `GameConfig`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `base` | `string` | `'/'` | Vite `base` path for deployment |
+| `devBridge` | `boolean` | `false` | Auto-inject DevBridge in dev mode |
+| `devBridgeConfig` | `string` | `'./dev.config'` | Path to DevBridge config file |
+| `vite` | `UserConfig` | — | Additional Vite config to merge |
+
 ### What `defineGameConfig` Provides
 
-- **PixiJS optimizations** — tree-shaking, proper externals handling
+- **Build target: ES2020+** — modern output for all supported casino platforms
+- **Asset inlining** — files under 8KB are auto-inlined
+- **PixiJS chunk splitting** — `pixi.js` is extracted into a separate chunk for caching
 - **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
+- **Dev server** — port 3000, auto-open browser
+- **Dependency optimization** — `pixi.js` pre-bundled for faster dev starts
 
 ### Custom DevBridge Configuration
 
@@ -858,13 +1073,15 @@ export default {
 } satisfies DevBridgeConfig;
 ```
 
-This file is auto-imported by the Vite plugin when `devBridge: true`.
+This file is auto-imported by the Vite plugin when `devBridge: true`. The plugin injects a virtual module (`/@dev-bridge-entry.js`) that starts DevBridge **before** importing your app entry point, ensuring the `MemoryChannel` is ready when the SDK calls `ready()`.
 
 ---
 
 ## DevBridge
 
-`DevBridge` simulates a casino host for local development. It intercepts `postMessage` calls from the SDK and responds with mock data.
+`DevBridge` simulates a casino host for local development. It uses the SDK's `Bridge` class in `devMode`, communicating with `CasinoGameSDK` through a shared in-memory `MemoryChannel` — no `postMessage` or iframe required.
+
+> **Requires `@energy8platform/game-sdk` >= 2.6.0**
 
 ```typescript
 import { DevBridge } from '@energy8platform/game-engine/debug';
@@ -876,7 +1093,10 @@ const bridge = new DevBridge({
   networkDelay: 200,
   debug: true,
   gameConfig: {
+    id: 'my-slot',
+    type: 'slot',
     viewport: { width: 1920, height: 1080 },
+    betLevels: [0.1, 0.2, 0.5, 1, 2, 5, 10],
   },
   onPlay: ({ action, bet, roundId }) => {
     // Return custom play result
@@ -885,7 +1105,7 @@ const bridge = new DevBridge({
   },
 });
 
-bridge.start();
+bridge.start(); // Creates SDK Bridge({ devMode: true }) + registers handlers
 
 // Update balance programmatically
 bridge.setBalance(5000);
@@ -894,6 +1114,8 @@ bridge.setBalance(5000);
 bridge.destroy();
 ```
 
+When using the Vite plugin with `devBridge: true`, the SDK is automatically configured with `devMode: true` so both sides use the same `MemoryChannel`.
+
 ### Handled Messages
 
 | Message | Description |
@@ -920,7 +1142,7 @@ fps.toggle();
 fps.hide();
 ```
 
-When `debug: true` is set in `GameApplicationConfig`, the FPS overlay is enabled automatically.
+When `debug: true` is set in `GameApplicationConfig`, the FPS overlay is created and shown automatically — no manual setup needed.
 
 The overlay displays:
 - Average FPS
@@ -1077,9 +1299,10 @@ class Tween {
   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 delay(ms: number): Promise<void>;  // Uses PixiJS Ticker
   static killTweensOf(target: any): void;
   static killAll(): void;
+  static reset(): void;  // Kill all + remove ticker listener
 }
 ```
 
@@ -1110,10 +1333,56 @@ class InputManager extends EventEmitter<InputEvents> {
   lock(): void;
   unlock(): void;
   isKeyDown(key: string): boolean;
+  setViewportTransform(scale: number, offsetX: number, offsetY: number): void;
+  getWorldPosition(canvasX: number, canvasY: number): { x: number; y: number };
+  destroy(): void;
+}
+```
+
+### Layout
+
+```typescript
+class Layout extends Container {
+  get items(): readonly Container[];
+
+  constructor(config?: LayoutConfig);
+  addItem(child: Container): this;
+  removeItem(child: Container): this;
+  clearItems(): this;
+  updateViewport(width: number, height: number): void;
+  layout(): void;
+}
+```
+
+### ScrollContainer
+
+```typescript
+class ScrollContainer extends Container {
+  get content(): Container | null;
+  get scrollPosition(): { x: number; y: number };
+
+  constructor(config: ScrollContainerConfig);
+  setContent(content: Container): void;
+  scrollTo(x: number, y: number, animate?: boolean): void;
+  scrollToItem(index: number): void;
+  resize(width: number, height: number): void;
   destroy(): void;
 }
 ```
 
+### SpriteAnimation
+
+```typescript
+class SpriteAnimation {
+  static create(textures: Texture[], config?: SpriteAnimationConfig): AnimatedSprite;
+  static fromSpritesheet(sheet: Spritesheet, prefix: string, config?: SpriteAnimationConfig): AnimatedSprite;
+  static fromRange(sheet: Spritesheet, pattern: string, start: number, end: number, config?: SpriteAnimationConfig): AnimatedSprite;
+  static fromAliases(aliases: string[], config?: SpriteAnimationConfig): AnimatedSprite;
+  static playOnce(textures: Texture[], config?: SpriteAnimationConfig): { sprite: AnimatedSprite; finished: Promise<void> };
+  static getTexturesByPrefix(sheet: Spritesheet, prefix: string): Texture[];
+}
+```
+
 ### EventEmitter
 
 ```typescript
@@ -1121,7 +1390,8 @@ 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;
+  // Void events can be emitted without a data argument
+  emit<K>(event: K, ...args): void;
   removeAllListeners(event?: keyof TEvents): this;
 }
 ```