@energy8platform/game-engine 0.2.1 → 0.4.0

package/dist/index.d.ts

@@ -1,6 +1,11 @@
-import { Container, ApplicationOptions, Application, Texture, TextStyle } from 'pixi.js';
+import { Container, ApplicationOptions, Application, Texture, AnimatedSprite, Spritesheet, TextStyle, ColorSource } from 'pixi.js';
 import { CasinoGameSDK, InitData, GameConfigData, SessionData, PlayResultData } from '@energy8platform/game-sdk';
 export { GameConfigData, InitData, PlayParams, PlayResultData, SessionData } from '@energy8platform/game-sdk';
+export { LayoutStyles } from '@pixi/layout';
+import { FancyButton, ScrollBox } from '@pixi/ui';
+export { ButtonContainer, FancyButton, ScrollBox } from '@pixi/ui';
+import { LayoutContainer } from '@pixi/layout/components';
+export { LayoutContainer } from '@pixi/layout/components';
 
 declare enum ScaleMode {
     /** Fit inside container, maintain aspect ratio (letterbox/pillarbox) */
@@ -83,6 +88,8 @@ interface GameApplicationConfig {
         parentOrigin?: string;
         timeout?: number;
         debug?: boolean;
+        /** Use in-memory channel instead of postMessage (no iframe required) */
+        devMode?: boolean;
     } | false;
     /** PixiJS Application options (pass-through) */
     pixi?: Partial<ApplicationOptions>;
@@ -91,6 +98,7 @@ interface GameApplicationConfig {
 }
 interface SceneConstructor {
     new (): IScene;
+    [key: string]: any;
 }
 interface IScene {
     /** Root display container for this scene */
@@ -155,13 +163,16 @@ interface TweenOptions {
 /**
  * Minimal typed event emitter.
  * Used internally by GameApplication, SceneManager, AudioManager, etc.
+ *
+ * Supports `void` event types — events that carry no data can be emitted
+ * without arguments: `emitter.emit('eventName')`.
  */
 declare class EventEmitter<TEvents extends {}> {
     private listeners;
     on<K extends keyof TEvents>(event: K, handler: (data: TEvents[K]) => void): this;
     once<K extends keyof TEvents>(event: K, handler: (data: TEvents[K]) => void): this;
     off<K extends keyof TEvents>(event: K, handler: (data: TEvents[K]) => void): this;
-    emit<K extends keyof TEvents>(event: K, data: TEvents[K]): void;
+    emit<K extends keyof TEvents>(...args: TEvents[K] extends void ? [event: K] : [event: K, data: TEvents[K]]): void;
     removeAllListeners(event?: keyof TEvents): this;
 }
 
@@ -438,6 +449,10 @@ declare class AudioManager {
      * Destroy the audio manager and free resources.
      */
     destroy(): void;
+    /**
+     * Smoothly fade a sound's volume from `fromVol` to `toVol` over `durationMs`.
+     */
+    private fadeVolume;
     private applyVolumes;
     private setupMobileUnlock;
     private removeMobileUnlock;
@@ -505,6 +520,9 @@ declare class InputManager extends EventEmitter<InputEvents> {
     private _locked;
     private _keysDown;
     private _destroyed;
+    private _viewportScale;
+    private _viewportOffsetX;
+    private _viewportOffsetY;
     private _pointerStart;
     private _swipeThreshold;
     private _swipeMaxTime;
@@ -517,6 +535,19 @@ declare class InputManager extends EventEmitter<InputEvents> {
     unlock(): void;
     /** Check if a key is currently pressed */
     isKeyDown(key: string): boolean;
+    /**
+     * Update the viewport transform used for DOM→world coordinate mapping.
+     * Called automatically by GameApplication when ViewportManager emits resize.
+     */
+    setViewportTransform(scale: number, offsetX: number, offsetY: number): void;
+    /**
+     * Convert a DOM canvas position to game-world coordinates,
+     * accounting for viewport scaling and offset.
+     */
+    getWorldPosition(canvasX: number, canvasY: number): {
+        x: number;
+        y: number;
+    };
     /** Destroy the input manager */
     destroy(): void;
     private setupPointerEvents;
@@ -607,6 +638,37 @@ declare class ViewportManager extends EventEmitter<ViewportEvents> {
     private debouncedRefresh;
 }
 
+/**
+ * FPS overlay for debugging performance.
+ *
+ * Shows FPS, frame time, and draw call count in the corner of the screen.
+ *
+ * @example
+ * ```ts
+ * const fps = new FPSOverlay(app);
+ * fps.show();
+ * ```
+ */
+declare class FPSOverlay {
+    private _app;
+    private _container;
+    private _fpsText;
+    private _visible;
+    private _samples;
+    private _maxSamples;
+    private _lastUpdate;
+    private _tickFn;
+    constructor(app: Application);
+    /** Show the FPS overlay */
+    show(): void;
+    /** Hide the FPS overlay */
+    hide(): void;
+    /** Toggle visibility */
+    toggle(): void;
+    /** Destroy the overlay */
+    destroy(): void;
+}
+
 /**
  * The main entry point for a game built on @energy8platform/game-engine.
  *
@@ -653,6 +715,8 @@ declare class GameApplication extends EventEmitter<GameEngineEvents> {
     viewport: ViewportManager;
     /** SDK instance (null in offline mode) */
     sdk: CasinoGameSDK | null;
+    /** FPS overlay instance (only when debug: true) */
+    fpsOverlay: FPSOverlay | null;
     /** Data received from SDK initialization */
     initData: InitData | null;
     /** Configuration */
@@ -887,6 +951,7 @@ declare class Tween {
     static fromTo(target: any, fromProps: Record<string, number>, toProps: Record<string, number>, duration: number, easing?: EasingFunction, onUpdate?: (progress: number) => void): Promise<void>;
     /**
      * Wait for a given duration (useful in timelines).
+     * Uses PixiJS Ticker for consistent timing with other tweens.
      */
     static delay(ms: number): Promise<void>;
     /**
@@ -899,6 +964,11 @@ declare class Tween {
     static killAll(): void;
     /** Number of active tweens */
     static get activeTweens(): number;
+    /**
+     * Reset the tween system — kill all tweens and remove the ticker.
+     * Useful for cleanup between game instances, tests, or hot-reload.
+     */
+    static reset(): void;
     private static ensureTicker;
     private static tick;
     /**
@@ -1078,7 +1148,114 @@ declare class SpineHelper {
     static setSkin(spine: any, skinName: string): void;
 }
 
-type ButtonState = 'normal' | 'hover' | 'pressed' | 'disabled';
+interface SpriteAnimationConfig {
+    /** Frames per second (default: 24) */
+    fps?: number;
+    /** Whether to loop (default: true) */
+    loop?: boolean;
+    /** Start playing immediately (default: true) */
+    autoPlay?: boolean;
+    /** Callback when animation completes (non-looping) */
+    onComplete?: () => void;
+    /** Anchor point (default: 0.5 = center) */
+    anchor?: number | {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Helper for creating frame-based animations from spritesheets.
+ *
+ * Wraps PixiJS `AnimatedSprite` with a convenient API for
+ * common iGaming effects: coin showers, symbol animations,
+ * sparkle trails, win celebrations.
+ *
+ * Cheaper than Spine for simple frame sequences.
+ *
+ * @example
+ * ```ts
+ * // From an array of textures
+ * const coinAnim = SpriteAnimation.create(coinTextures, {
+ *   fps: 30,
+ *   loop: true,
+ * });
+ * scene.addChild(coinAnim);
+ *
+ * // From a spritesheet with a naming pattern
+ * const sheet = Assets.get('effects');
+ * const sparkle = SpriteAnimation.fromSpritesheet(sheet, 'sparkle_');
+ * sparkle.play();
+ *
+ * // From a numbered range
+ * const explosion = SpriteAnimation.fromRange(sheet, 'explosion_{i}', 0, 24, {
+ *   fps: 60,
+ *   loop: false,
+ *   onComplete: () => explosion.destroy(),
+ * });
+ * ```
+ */
+declare class SpriteAnimation {
+    /**
+     * Create an animated sprite from an array of textures.
+     *
+     * @param textures - Array of PixiJS Textures
+     * @param config - Animation options
+     * @returns Configured AnimatedSprite
+     */
+    static create(textures: Texture[], config?: SpriteAnimationConfig): AnimatedSprite;
+    /**
+     * Create an animated sprite from a spritesheet using a name prefix.
+     *
+     * Collects all textures whose keys start with `prefix`, sorted alphabetically.
+     *
+     * @param sheet - PixiJS Spritesheet instance
+     * @param prefix - Texture name prefix (e.g., 'coin_')
+     * @param config - Animation options
+     * @returns Configured AnimatedSprite
+     */
+    static fromSpritesheet(sheet: Spritesheet, prefix: string, config?: SpriteAnimationConfig): AnimatedSprite;
+    /**
+     * Create an animated sprite from a numbered range of frames.
+     *
+     * The `pattern` string should contain `{i}` as a placeholder for the frame number.
+     * Numbers are zero-padded to match the length of `start`.
+     *
+     * @param sheet - PixiJS Spritesheet instance
+     * @param pattern - Frame name pattern, e.g. 'explosion_{i}'
+     * @param start - Start frame index (inclusive)
+     * @param end - End frame index (inclusive)
+     * @param config - Animation options
+     * @returns Configured AnimatedSprite
+     */
+    static fromRange(sheet: Spritesheet, pattern: string, start: number, end: number, config?: SpriteAnimationConfig): AnimatedSprite;
+    /**
+     * Create an AnimatedSprite from texture aliases (loaded via AssetManager).
+     *
+     * @param aliases - Array of texture aliases
+     * @param config - Animation options
+     * @returns Configured AnimatedSprite
+     */
+    static fromAliases(aliases: string[], config?: SpriteAnimationConfig): AnimatedSprite;
+    /**
+     * Play a one-shot animation and auto-destroy when complete.
+     * Useful for fire-and-forget effects like coin bursts.
+     *
+     * @param textures - Array of textures
+     * @param config - Animation options (loop will be forced to false)
+     * @returns Promise that resolves when animation completes
+     */
+    static playOnce(textures: Texture[], config?: SpriteAnimationConfig): {
+        sprite: AnimatedSprite;
+        finished: Promise<void>;
+    };
+    /**
+     * Get all textures from a spritesheet that start with a given prefix.
+     * Results are sorted alphabetically by key.
+     */
+    static getTexturesByPrefix(sheet: Spritesheet, prefix: string): Texture[];
+}
+
+type ButtonState = 'default' | 'hover' | 'pressed' | 'disabled';
 interface ButtonConfig {
     /** Default texture/sprite for each state (optional — uses Graphics if not provided) */
     textures?: Partial<Record<ButtonState, string | Texture>>;
@@ -1096,48 +1273,38 @@ interface ButtonConfig {
     animationDuration?: number;
     /** Start disabled */
     disabled?: boolean;
+    /** Button text */
+    text?: string;
+    /** Button text style */
+    textStyle?: Record<string, unknown>;
 }
 /**
- * Interactive button component with state management and animation.
+ * Interactive button component powered by `@pixi/ui` FancyButton.
  *
- * Supports both texture-based and Graphics-based rendering.
+ * Supports both texture-based and Graphics-based rendering with
+ * per-state views, press animation, and text.
  *
  * @example
  * ```ts
  * const btn = new Button({
  *   width: 200, height: 60, borderRadius: 12,
- *   colors: { normal: 0x22aa22, hover: 0x33cc33 },
+ *   colors: { default: 0x22aa22, hover: 0x33cc33 },
+ *   text: 'SPIN',
  * });
  *
- * btn.onTap = () => console.log('Clicked!');
+ * btn.onPress.connect(() => console.log('Clicked!'));
  * scene.container.addChild(btn);
  * ```
  */
-declare class Button extends Container {
-    private _state;
-    private _bg;
-    private _sprites;
-    private _config;
-    /** Called when the button is tapped/clicked */
-    onTap?: () => void;
-    /** Called when the button state changes */
-    onStateChange?: (state: ButtonState) => void;
+declare class Button extends FancyButton {
+    private _buttonConfig;
     constructor(config?: ButtonConfig);
-    /** Current button state */
-    get state(): ButtonState;
     /** Enable the button */
     enable(): void;
     /** Disable the button */
     disable(): void;
     /** Whether the button is disabled */
     get disabled(): boolean;
-    private setState;
-    private render;
-    private onPointerOver;
-    private onPointerOut;
-    private onPointerDown;
-    private onPointerUp;
-    private onPointerTap;
 }
 
 interface ProgressBarConfig {
@@ -1154,7 +1321,9 @@ interface ProgressBarConfig {
     animationSpeed?: number;
 }
 /**
- * Horizontal progress bar with optional smooth fill animation.
+ * Horizontal progress bar powered by `@pixi/ui` ProgressBar.
+ *
+ * Provides optional smooth animated fill via per-frame `update()`.
  *
  * @example
  * ```ts
@@ -1164,9 +1333,8 @@ interface ProgressBarConfig {
  * ```
  */
 declare class ProgressBar extends Container {
-    private _track;
-    private _fill;
-    private _border;
+    private _bar;
+    private _borderGfx;
     private _config;
     private _progress;
     private _displayedProgress;
@@ -1177,10 +1345,7 @@ declare class ProgressBar extends Container {
     /**
      * Call each frame if animated is true.
      */
-    update(dt: number): void;
-    private drawTrack;
-    private drawBorder;
-    private drawFill;
+    update(_dt: number): void;
 }
 
 interface LabelConfig {
@@ -1254,7 +1419,10 @@ interface PanelConfig {
     padding?: number;
 }
 /**
- * Background panel that can use either Graphics or 9-slice sprite.
+ * Background panel powered by `@pixi/layout` LayoutContainer.
+ *
+ * Supports both Graphics-based (color + border) and 9-slice sprite backgrounds.
+ * Children added to `content` participate in flexbox layout automatically.
  *
  * @example
  * ```ts
@@ -1269,16 +1437,13 @@ interface PanelConfig {
  * });
  * ```
  */
-declare class Panel extends Container {
-    private _bg;
-    private _content;
-    private _config;
+declare class Panel extends LayoutContainer {
+    private _panelConfig;
     constructor(config?: PanelConfig);
-    /** Content container — add children here */
+    /** Access the content container (children added here participate in layout) */
     get content(): Container;
     /** Resize the panel */
     setSize(width: number, height: number): void;
-    private drawGraphicsBg;
 }
 
 interface BalanceDisplayConfig {
@@ -1319,6 +1484,7 @@ declare class BalanceDisplay extends Container {
     private _currentValue;
     private _displayedValue;
     private _animating;
+    private _animationCancelled;
     constructor(config?: BalanceDisplayConfig);
     /** Current displayed value */
     get value(): number;
@@ -1398,6 +1564,8 @@ interface ModalConfig {
  * Modal overlay component.
  * Shows content on top of a dark overlay with enter/exit animations.
  *
+ * The content container uses `@pixi/layout` for automatic centering.
+ *
  * @example
  * ```ts
  * const modal = new Modal({ closeOnOverlay: true });
@@ -1438,6 +1606,8 @@ interface ToastConfig {
 /**
  * Toast notification component for displaying transient messages.
  *
+ * Uses `@pixi/layout` LayoutContainer for auto-sized background.
+ *
  * @example
  * ```ts
  * const toast = new Toast();
@@ -1461,6 +1631,146 @@ declare class Toast extends Container {
     dismiss(): Promise<void>;
 }
 
+type LayoutDirection = 'horizontal' | 'vertical' | 'grid' | 'wrap';
+type LayoutAlignment = 'start' | 'center' | 'end' | 'stretch';
+type LayoutAnchor = 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+interface LayoutConfig {
+    /** Layout direction (default: 'vertical') */
+    direction?: LayoutDirection;
+    /** Gap between children in pixels (default: 0) */
+    gap?: number;
+    /** Padding inside the layout container [top, right, bottom, left] or a single number */
+    padding?: number | [number, number, number, number];
+    /** Alignment of children on the cross axis (default: 'start') */
+    alignment?: LayoutAlignment;
+    /** Anchor point determining where the layout is positioned relative to its coordinates */
+    anchor?: LayoutAnchor;
+    /** Number of columns (only for 'grid' direction) */
+    columns?: number;
+    /** Maximum width for 'wrap' direction before wrapping to next line */
+    maxWidth?: number;
+    /** Whether to auto-layout when children change (default: true) */
+    autoLayout?: boolean;
+    /** Breakpoints: map of max viewport widths to override configs */
+    breakpoints?: Record<number, Partial<LayoutConfig>>;
+}
+/**
+ * Responsive layout container powered by `@pixi/layout` (Yoga flexbox engine).
+ *
+ * Supports horizontal, vertical, grid, and wrap layout modes with
+ * alignment, padding, gap, and viewport-anchor positioning.
+ * Breakpoints allow different layouts for different screen sizes.
+ *
+ * @example
+ * ```ts
+ * 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);
+ * scene.container.addChild(toolbar);
+ *
+ * toolbar.updateViewport(width, height);
+ * ```
+ */
+declare class Layout extends Container {
+    private _layoutConfig;
+    private _padding;
+    private _anchor;
+    private _maxWidth;
+    private _breakpoints;
+    private _items;
+    private _viewportWidth;
+    private _viewportHeight;
+    constructor(config?: LayoutConfig);
+    /** Add an item to the layout */
+    addItem(child: Container): this;
+    /** Remove an item from the layout */
+    removeItem(child: Container): this;
+    /** Remove all items */
+    clearItems(): this;
+    /** Get all layout items */
+    get items(): readonly Container[];
+    /**
+     * Update the viewport size and recalculate layout.
+     * Should be called from `Scene.onResize()`.
+     */
+    updateViewport(width: number, height: number): void;
+    private applyLayoutStyles;
+    private applyGridChildWidth;
+    private applyAnchor;
+    private resolveConfig;
+}
+
+type ScrollDirection = 'vertical' | 'horizontal' | 'both';
+interface ScrollContainerConfig {
+    /** Visible viewport width */
+    width: number;
+    /** Visible viewport height */
+    height: number;
+    /** Scroll direction (default: 'vertical') */
+    direction?: ScrollDirection;
+    /** Background color (undefined = transparent) */
+    backgroundColor?: ColorSource;
+    /** Border radius for the mask (default: 0) */
+    borderRadius?: number;
+    /** Gap between items (default: 0) */
+    elementsMargin?: number;
+    /** Padding */
+    padding?: number;
+    /** Disable dynamic rendering (render all items even when offscreen) */
+    disableDynamicRendering?: boolean;
+    /** Disable easing/inertia */
+    disableEasing?: boolean;
+    /** Global scroll — scroll even when mouse is not over the component */
+    globalScroll?: boolean;
+}
+/**
+ * Scrollable container powered by `@pixi/ui` ScrollBox.
+ *
+ * Provides touch/drag scrolling, mouse wheel support, inertia, and
+ * dynamic rendering optimization for off-screen items.
+ *
+ * @example
+ * ```ts
+ * const scroll = new ScrollContainer({
+ *   width: 600,
+ *   height: 400,
+ *   direction: 'vertical',
+ *   elementsMargin: 8,
+ * });
+ *
+ * for (let i = 0; i < 50; i++) {
+ *   scroll.addItem(createRow(i));
+ * }
+ *
+ * scene.container.addChild(scroll);
+ * ```
+ */
+declare class ScrollContainer extends ScrollBox {
+    private _scrollConfig;
+    constructor(config: ScrollContainerConfig);
+    /** Set scrollable content. Replaces any existing content. */
+    setContent(content: Container): void;
+    /** Add a single item */
+    addItem(...items: Container[]): Container;
+    /** Scroll to make a specific item/child visible */
+    scrollToItem(index: number): void;
+    /** Current scroll position */
+    get scrollPosition(): {
+        x: number;
+        y: number;
+    };
+}
+
 /**
  * Built-in loading screen using the Energy8 SVG logo with animated loader bar.
  *
@@ -1521,8 +1831,9 @@ interface DevBridgeConfig {
 /**
  * Mock host bridge for local development.
  *
- * Intercepts postMessage communication from the SDK and responds
- * with mock data, simulating a real casino host environment.
+ * Uses the SDK's `Bridge` class in `devMode` to communicate with
+ * `CasinoGameSDK` via a shared in-memory `MemoryChannel`, removing
+ * the need for postMessage and iframes.
  *
  * This allows games to be developed and tested without a real backend.
  *
@@ -1550,8 +1861,7 @@ declare class DevBridge {
     private _config;
     private _balance;
     private _roundCounter;
-    private _listening;
-    private _handler;
+    private _bridge;
     constructor(config?: DevBridgeConfig);
     /** Current mock balance */
     get balance(): number;
@@ -1563,7 +1873,6 @@ declare class DevBridge {
     setBalance(balance: number): void;
     /** Destroy the dev bridge */
     destroy(): void;
-    private handleMessage;
     private handleGameReady;
     private handlePlayRequest;
     private handlePlayAck;
@@ -1571,39 +1880,7 @@ declare class DevBridge {
     private handleGetState;
     private handleOpenDeposit;
     private delayedSend;
-    private sendMessage;
-}
-
-/**
- * FPS overlay for debugging performance.
- *
- * Shows FPS, frame time, and draw call count in the corner of the screen.
- *
- * @example
- * ```ts
- * const fps = new FPSOverlay(app);
- * fps.show();
- * ```
- */
-declare class FPSOverlay {
-    private _app;
-    private _container;
-    private _fpsText;
-    private _visible;
-    private _samples;
-    private _maxSamples;
-    private _lastUpdate;
-    private _tickFn;
-    constructor(app: Application);
-    /** Show the FPS overlay */
-    show(): void;
-    /** Hide the FPS overlay */
-    hide(): void;
-    /** Toggle visibility */
-    toggle(): void;
-    /** Destroy the overlay */
-    destroy(): void;
 }
 
-export { AssetManager, AudioManager, BalanceDisplay, Button, DevBridge, Easing, EventEmitter, FPSOverlay, GameApplication, InputManager, Label, LoadingScene, Modal, Orientation, Panel, ProgressBar, ScaleMode, Scene, SceneManager, SpineHelper, StateMachine, Timeline, Toast, TransitionType, Tween, ViewportManager, WinDisplay };
-export type { AssetBundle, AssetEntry, AssetManifest, AudioConfig, DevBridgeConfig, EasingFunction, GameApplicationConfig, GameEngineEvents, IScene, LoadingScreenConfig, SceneConstructor, TransitionConfig, TweenOptions };
+export { AssetManager, AudioManager, BalanceDisplay, Button, DevBridge, Easing, EventEmitter, FPSOverlay, GameApplication, InputManager, Label, Layout, LoadingScene, Modal, Orientation, Panel, ProgressBar, ScaleMode, Scene, SceneManager, ScrollContainer, SpineHelper, SpriteAnimation, StateMachine, Timeline, Toast, TransitionType, Tween, ViewportManager, WinDisplay };
+export type { AssetBundle, AssetEntry, AssetManifest, AudioConfig, BalanceDisplayConfig, ButtonConfig, ButtonState, DevBridgeConfig, EasingFunction, GameApplicationConfig, GameEngineEvents, IScene, LabelConfig, LayoutAlignment, LayoutAnchor, LayoutConfig, LayoutDirection, LoadingScreenConfig, ModalConfig, PanelConfig, ProgressBarConfig, SceneConstructor, ScrollContainerConfig, ScrollDirection, SpriteAnimationConfig, ToastConfig, ToastType, TransitionConfig, TweenOptions, WinDisplayConfig };