@energy8platform/game-engine 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Container, ApplicationOptions, Application, Texture, TextStyle } from 'pixi.js';
+import { Container, ApplicationOptions, Application, Texture, AnimatedSprite, Spritesheet, TextStyle } from 'pixi.js';
 import { CasinoGameSDK, InitData, GameConfigData, SessionData, PlayResultData } from '@energy8platform/game-sdk';
 export { GameConfigData, InitData, PlayParams, PlayResultData, SessionData } from '@energy8platform/game-sdk';
 
@@ -83,6 +83,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 +93,7 @@ interface GameApplicationConfig {
 }
 interface SceneConstructor {
     new (): IScene;
+    [key: string]: any;
 }
 interface IScene {
     /** Root display container for this scene */
@@ -155,13 +158,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 +444,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 +515,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 +530,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 +633,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 +710,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 +946,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 +959,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,6 +1143,113 @@ declare class SpineHelper {
     static setSkin(spine: any, skinName: string): void;
 }
 
+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 = 'normal' | 'hover' | 'pressed' | 'disabled';
 interface ButtonConfig {
     /** Default texture/sprite for each state (optional — uses Graphics if not provided) */
@@ -1319,6 +1491,7 @@ declare class BalanceDisplay extends Container {
     private _currentValue;
     private _displayedValue;
     private _animating;
+    private _animationCancelled;
     constructor(config?: BalanceDisplayConfig);
     /** Current displayed value */
     get value(): number;
@@ -1461,6 +1634,211 @@ 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 that automatically arranges its children.
+ *
+ * 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);
+ *
+ * // On resize, update layout position relative to viewport
+ * toolbar.updateViewport(width, height);
+ * ```
+ */
+declare class Layout extends Container {
+    private _config;
+    private _padding;
+    private _anchor;
+    private _maxWidth;
+    private _breakpoints;
+    private _content;
+    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;
+    /**
+     * Recalculate layout positions of all children.
+     */
+    layout(): void;
+    private layoutLinear;
+    private layoutGrid;
+    private layoutWrap;
+    private applyAnchor;
+    private resolveConfig;
+    private getItemSize;
+    private static normalizePadding;
+}
+
+type ScrollDirection = 'vertical' | 'horizontal' | 'both';
+interface ScrollContainerConfig {
+    /** Visible viewport width */
+    width: number;
+    /** Visible viewport height */
+    height: number;
+    /** Scroll direction (default: 'vertical') */
+    direction?: ScrollDirection;
+    /** Show scrollbar(s) (default: true) */
+    showScrollbar?: boolean;
+    /** Scrollbar width in pixels (default: 6) */
+    scrollbarWidth?: number;
+    /** Scrollbar color (default: 0xffffff) */
+    scrollbarColor?: number;
+    /** Scrollbar opacity (default: 0.4) */
+    scrollbarAlpha?: number;
+    /** Elasticity factor for overscroll bounce (0 = none, 1 = infinite, default: 0.3) */
+    elasticity?: number;
+    /** Inertia deceleration factor (0 = instant stop, 1 = infinite drift, default: 0.92) */
+    inertia?: number;
+    /** Snap to items of fixed height/width (0 = no snap) */
+    snapSize?: number;
+    /** Background color (undefined = transparent) */
+    backgroundColor?: number;
+    /** Background alpha (default: 1) */
+    backgroundAlpha?: number;
+    /** Border radius for the mask (default: 0) */
+    borderRadius?: number;
+}
+/**
+ * Scrollable container with touch/drag, mouse wheel, inertia, and optional scrollbar.
+ *
+ * Perfect for paytables, settings panels, bet history, and any scrollable content
+ * that doesn't fit on screen.
+ *
+ * @example
+ * ```ts
+ * const scroll = new ScrollContainer({
+ *   width: 600,
+ *   height: 400,
+ *   direction: 'vertical',
+ *   showScrollbar: true,
+ *   elasticity: 0.3,
+ * });
+ *
+ * // Add content taller than 400px
+ * 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);
+ * ```
+ */
+declare class ScrollContainer extends Container {
+    private _config;
+    private _viewport;
+    private _content;
+    private _mask;
+    private _bg;
+    private _scrollbarV;
+    private _scrollbarH;
+    private _scrollbarFadeTimeout;
+    private _scrollX;
+    private _scrollY;
+    private _velocityX;
+    private _velocityY;
+    private _isDragging;
+    private _dragStart;
+    private _scrollStart;
+    private _lastDragPos;
+    private _lastDragTime;
+    private _isAnimating;
+    private _animationFrame;
+    constructor(config: ScrollContainerConfig);
+    /** Set scrollable content. Replaces any existing content. */
+    setContent(content: Container): void;
+    /** Get the content container */
+    get content(): Container | null;
+    /** Scroll to a specific position (in content coordinates) */
+    scrollTo(x: number, y: number, animate?: boolean): void;
+    /** Scroll to make a specific item/child visible */
+    scrollToItem(index: number): void;
+    /** Current scroll position */
+    get scrollPosition(): {
+        x: number;
+        y: number;
+    };
+    /** Resize the scroll viewport */
+    resize(width: number, height: number): void;
+    /** Destroy and clean up */
+    destroy(options?: any): void;
+    private get contentWidth();
+    private get contentHeight();
+    private get maxScrollX();
+    private get maxScrollY();
+    private canScrollX;
+    private canScrollY;
+    private clampScroll;
+    private applyScroll;
+    private onPointerDown;
+    private onPointerMove;
+    private onPointerUp;
+    private onWheel;
+    private startInertia;
+    private snapAndBounce;
+    private animateScrollTo;
+    private stopAnimation;
+    private updateScrollbars;
+    private showScrollbars;
+    private scheduleScrollbarFade;
+    private fadeScrollbars;
+}
+
 /**
  * Built-in loading screen using the Energy8 SVG logo with animated loader bar.
  *
@@ -1521,8 +1899,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 +1929,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 +1941,6 @@ declare class DevBridge {
     setBalance(balance: number): void;
     /** Destroy the dev bridge */
     destroy(): void;
-    private handleMessage;
     private handleGameReady;
     private handlePlayRequest;
     private handlePlayAck;
@@ -1571,39 +1948,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, DevBridgeConfig, EasingFunction, GameApplicationConfig, GameEngineEvents, IScene, LayoutAlignment, LayoutAnchor, LayoutConfig, LayoutDirection, LoadingScreenConfig, SceneConstructor, ScrollContainerConfig, ScrollDirection, SpriteAnimationConfig, TransitionConfig, TweenOptions };