@energy8platform/game-engine 0.1.0

package/src/core/GameApplication.ts

@@ -0,0 +1,306 @@
+import { Application, Assets, Ticker } from 'pixi.js';
+import { CasinoGameSDK } from '@energy8platform/game-sdk';
+import type { InitData, GameConfigData, SessionData } from '@energy8platform/game-sdk';
+import type { GameApplicationConfig, GameEngineEvents, AssetManifest } from '../types';
+import { ScaleMode, Orientation, TransitionType } from '../types';
+import { EventEmitter } from './EventEmitter';
+import { SceneManager } from './SceneManager';
+import { AssetManager } from '../assets/AssetManager';
+import { AudioManager } from '../audio/AudioManager';
+import { ViewportManager } from '../viewport/ViewportManager';
+import { LoadingScene } from '../loading/LoadingScene';
+import { createCSSPreloader, removeCSSPreloader } from '../loading/CSSPreloader';
+
+/**
+ * The main entry point for a game built on @energy8platform/game-engine.
+ *
+ * Orchestrates the full lifecycle:
+ * 1. Create PixiJS Application
+ * 2. Initialize SDK (or run offline)
+ * 3. Show CSS preloader → Canvas loading screen with progress bar
+ * 4. Load asset manifest
+ * 5. Transition to the first game scene
+ *
+ * @example
+ * ```ts
+ * import { GameApplication, ScaleMode } from '@energy8platform/game-engine';
+ * import { GameScene } from './scenes/GameScene';
+ *
+ * const game = new GameApplication({
+ *   container: '#game',
+ *   designWidth: 1920,
+ *   designHeight: 1080,
+ *   scaleMode: ScaleMode.FIT,
+ *   manifest: { bundles: [
+ *     { name: 'preload', assets: [{ alias: 'logo', src: 'logo.png' }] },
+ *     { name: 'game', assets: [{ alias: 'bg', src: 'background.png' }] },
+ *   ]},
+ *   loading: { tapToStart: true },
+ * });
+ *
+ * game.scenes.register('game', GameScene);
+ * await game.start('game');
+ * ```
+ */
+export class GameApplication extends EventEmitter<GameEngineEvents> {
+  // ─── Public references ──────────────────────────────────
+
+  /** PixiJS Application instance */
+  public app!: Application;
+
+  /** Scene manager */
+  public scenes!: SceneManager;
+
+  /** Asset manager */
+  public assets!: AssetManager;
+
+  /** Audio manager */
+  public audio!: AudioManager;
+
+  /** Viewport manager */
+  public viewport!: ViewportManager;
+
+  /** SDK instance (null in offline mode) */
+  public sdk: CasinoGameSDK | null = null;
+
+  /** Data received from SDK initialization */
+  public initData: InitData | null = null;
+
+  /** Configuration */
+  public readonly config: GameApplicationConfig;
+
+  // ─── Private state ──────────────────────────────────────
+
+  private _running = false;
+  private _destroyed = false;
+  private _container: HTMLElement | null = null;
+
+  constructor(config: GameApplicationConfig = {}) {
+    super();
+    this.config = {
+      designWidth: 1920,
+      designHeight: 1080,
+      scaleMode: ScaleMode.FIT,
+      orientation: Orientation.ANY,
+      debug: false,
+      ...config,
+    };
+
+    // Create SceneManager early so scenes can be registered before start()
+    this.scenes = new SceneManager();
+  }
+
+  // ─── Public getters ─────────────────────────────────────
+
+  /** Current game config from SDK (or null in offline mode) */
+  get gameConfig(): GameConfigData | null {
+    return this.initData?.config ?? null;
+  }
+
+  /** Current session data */
+  get session(): SessionData | null {
+    return this.initData?.session ?? null;
+  }
+
+  /** Current balance */
+  get balance(): number {
+    return this.sdk?.balance ?? 0;
+  }
+
+  /** Current currency */
+  get currency(): string {
+    return this.sdk?.currency ?? 'USD';
+  }
+
+  /** Whether the engine is running */
+  get isRunning(): boolean {
+    return this._running;
+  }
+
+  // ─── Lifecycle ──────────────────────────────────────────
+
+  /**
+   * Start the game engine. This is the main entry point.
+   *
+   * @param firstScene - Key of the first scene to show after loading (must be registered)
+   * @param sceneData - Optional data to pass to the first scene's onEnter
+   */
+  async start(firstScene: string, sceneData?: unknown): Promise<void> {
+    if (this._running) {
+      console.warn('[GameEngine] Already running');
+      return;
+    }
+
+    try {
+      // 1. Resolve container element
+      this._container = this.resolveContainer();
+
+      // 2. Show CSS preloader immediately (before PixiJS)
+      createCSSPreloader(this._container, this.config.loading);
+
+      // 3. Initialize PixiJS
+      await this.initPixi();
+
+      // 4. Initialize SDK (if enabled)
+      await this.initSDK();
+
+      // 5. Merge design dimensions from SDK config
+      this.applySDKConfig();
+
+      // 6. Initialize sub-systems
+      this.initSubSystems();
+
+      this.emit('initialized', undefined as any);
+
+      // 7. Remove CSS preloader, show Canvas loading screen
+      removeCSSPreloader(this._container);
+
+      // 8. Load assets with loading screen
+      await this.loadAssets(firstScene, sceneData);
+
+      // 9. Start the game loop
+      this._running = true;
+      this.emit('started', undefined as any);
+    } catch (err) {
+      console.error('[GameEngine] Failed to start:', err);
+      this.emit('error', err instanceof Error ? err : new Error(String(err)));
+      throw err;
+    }
+  }
+
+  /**
+   * Destroy the engine and free all resources.
+   */
+  destroy(): void {
+    if (this._destroyed) return;
+    this._destroyed = true;
+    this._running = false;
+
+    this.scenes?.destroy();
+    this.audio?.destroy();
+    this.viewport?.destroy();
+    this.sdk?.destroy();
+    this.app?.destroy(true, { children: true, texture: true });
+    this.removeAllListeners();
+
+    this.emit('destroyed', undefined as any);
+  }
+
+  // ─── Private initialization steps ──────────────────────
+
+  private resolveContainer(): HTMLElement {
+    if (typeof this.config.container === 'string') {
+      const el = document.querySelector<HTMLElement>(this.config.container);
+      if (!el) throw new Error(`[GameEngine] Container "${this.config.container}" not found`);
+      return el;
+    }
+    return this.config.container ?? document.body;
+  }
+
+  private async initPixi(): Promise<void> {
+    this.app = new Application();
+
+    const pixiOpts = {
+      background: typeof this.config.loading?.backgroundColor === 'number'
+        ? this.config.loading.backgroundColor
+        : 0x000000,
+      antialias: true,
+      resolution: Math.min(window.devicePixelRatio, 2),
+      autoDensity: true,
+      ...this.config.pixi,
+    };
+
+    await this.app.init(pixiOpts);
+
+    // Append canvas to container
+    this._container!.appendChild(this.app.canvas);
+
+    // Set canvas style
+    this.app.canvas.style.display = 'block';
+    this.app.canvas.style.width = '100%';
+    this.app.canvas.style.height = '100%';
+  }
+
+  private async initSDK(): Promise<void> {
+    if (this.config.sdk === false) {
+      // Offline / development mode — no SDK
+      this.initData = null;
+      return;
+    }
+
+    const sdkOpts = typeof this.config.sdk === 'object' ? this.config.sdk : {};
+    this.sdk = new CasinoGameSDK(sdkOpts);
+
+    // Perform the handshake
+    this.initData = await this.sdk.ready();
+
+    // Forward SDK events
+    this.sdk.on('error', (err: Error) => {
+      this.emit('error', err);
+    });
+  }
+
+  private applySDKConfig(): void {
+    // If SDK provides viewport dimensions, use them as design reference
+    if (this.initData?.config?.viewport) {
+      const vp = this.initData.config.viewport;
+      if (!this.config.designWidth) this.config.designWidth = vp.width;
+      if (!this.config.designHeight) this.config.designHeight = vp.height;
+    }
+  }
+
+  private initSubSystems(): void {
+    // Asset Manager
+    const basePath = this.initData?.assetsUrl ?? '';
+    this.assets = new AssetManager(basePath, this.config.manifest);
+
+    // Audio Manager
+    this.audio = new AudioManager(this.config.audio);
+
+    // Viewport Manager
+    this.viewport = new ViewportManager(
+      this.app,
+      this._container!,
+      {
+        designWidth: this.config.designWidth!,
+        designHeight: this.config.designHeight!,
+        scaleMode: this.config.scaleMode!,
+        orientation: this.config.orientation!,
+      },
+    );
+
+    // Wire SceneManager to the PixiJS stage
+    this.scenes.setRoot(this.app.stage);
+
+    // Wire viewport resize → scene manager
+    this.viewport.on('resize', ({ width, height }) => {
+      this.scenes.resize(width, height);
+      this.emit('resize', { width, height });
+    });
+
+    this.viewport.on('orientationChange', (orientation) => {
+      this.emit('orientationChange', orientation);
+    });
+
+    // Connect ticker → scene updates
+    this.app.ticker.add((ticker) => {
+      // Always update scenes (loading screen needs onUpdate before _running=true)
+      this.scenes.update(ticker.deltaTime / 60); // convert to seconds
+    });
+
+    // Trigger initial resize
+    this.viewport.refresh();
+  }
+
+  private async loadAssets(firstScene: string, sceneData?: unknown): Promise<void> {
+    // Register built-in loading scene
+    this.scenes.register('__loading__', LoadingScene as any);
+
+    // Enter loading scene
+    await this.scenes.goto('__loading__', {
+      engine: this,
+      targetScene: firstScene,
+      targetData: sceneData,
+    });
+  }
+}

package/src/core/Scene.ts

@@ -0,0 +1,48 @@
+import { Container } from 'pixi.js';
+import type { IScene } from '../types';
+
+/**
+ * Base class for all scenes.
+ * Provides a root PixiJS Container and lifecycle hooks.
+ *
+ * @example
+ * ```ts
+ * class MenuScene extends Scene {
+ *   async onEnter() {
+ *     const bg = Sprite.from('menu-bg');
+ *     this.container.addChild(bg);
+ *   }
+ *
+ *   onUpdate(dt: number) {
+ *     // per-frame logic
+ *   }
+ *
+ *   onResize(width: number, height: number) {
+ *     // reposition UI
+ *   }
+ * }
+ * ```
+ */
+export abstract class Scene implements IScene {
+  public readonly container: Container;
+
+  constructor() {
+    this.container = new Container();
+    this.container.label = this.constructor.name;
+  }
+
+  /** Called when this scene becomes active. Override in subclass. */
+  onEnter?(data?: unknown): Promise<void> | void;
+
+  /** Called when this scene is deactivated. Override in subclass. */
+  onExit?(): Promise<void> | void;
+
+  /** Called every frame with delta time (in seconds). Override in subclass. */
+  onUpdate?(dt: number): void;
+
+  /** Called when the viewport resizes. Override in subclass. */
+  onResize?(width: number, height: number): void;
+
+  /** Cleanup — called when the scene is permanently removed. */
+  onDestroy?(): void;
+}

package/src/core/SceneManager.ts

@@ -0,0 +1,258 @@
+import { Container } from 'pixi.js';
+import type { IScene, SceneConstructor, TransitionConfig, TransitionType } from '../types';
+import { TransitionType as TT } from '../types';
+import { Tween } from '../animation/Tween';
+import { EventEmitter } from './EventEmitter';
+
+interface SceneEntry {
+  scene: IScene;
+  key: string;
+}
+
+interface SceneManagerEvents {
+  change: { from: string | null; to: string };
+}
+
+/**
+ * Manages the scene stack and transitions between scenes.
+ *
+ * @example
+ * ```ts
+ * const scenes = new SceneManager(app.stage);
+ * scenes.register('loading', LoadingScene);
+ * scenes.register('game', GameScene);
+ * await scenes.goto('loading');
+ * ```
+ */
+export class SceneManager extends EventEmitter<SceneManagerEvents> {
+  /** Root container that scenes are added to */
+  public root!: Container;
+
+  private registry = new Map<string, SceneConstructor>();
+  private stack: SceneEntry[] = [];
+  private _transitioning = false;
+
+  /** Current viewport dimensions — set by ViewportManager */
+  private _width = 0;
+  private _height = 0;
+
+  constructor(root?: Container) {
+    super();
+    if (root) this.root = root;
+  }
+
+  /** @internal Set the root container (called by GameApplication after PixiJS init) */
+  setRoot(root: Container): void {
+    this.root = root;
+  }
+
+  /** Register a scene class by key */
+  register(key: string, ctor: SceneConstructor): this {
+    this.registry.set(key, ctor);
+    return this;
+  }
+
+  /** Get the current (topmost) scene entry */
+  get current(): SceneEntry | null {
+    return this.stack.length > 0 ? this.stack[this.stack.length - 1] : null;
+  }
+
+  /** Get the current scene key */
+  get currentKey(): string | null {
+    return this.current?.key ?? null;
+  }
+
+  /** Whether a scene transition is in progress */
+  get isTransitioning(): boolean {
+    return this._transitioning;
+  }
+
+  /**
+   * Navigate to a scene, replacing the entire stack.
+   */
+  async goto(
+    key: string,
+    data?: unknown,
+    transition?: TransitionConfig,
+  ): Promise<void> {
+    const prevKey = this.currentKey;
+
+    // Exit all current scenes
+    while (this.stack.length > 0) {
+      await this.popInternal(false);
+    }
+
+    // Enter new scene
+    await this.pushInternal(key, data, transition);
+    this.emit('change', { from: prevKey, to: key });
+  }
+
+  /**
+   * Push a scene onto the stack (the previous scene stays underneath).
+   * Useful for overlays, modals, pause screens.
+   */
+  async push(
+    key: string,
+    data?: unknown,
+    transition?: TransitionConfig,
+  ): Promise<void> {
+    const prevKey = this.currentKey;
+    await this.pushInternal(key, data, transition);
+    this.emit('change', { from: prevKey, to: key });
+  }
+
+  /**
+   * Pop the top scene from the stack.
+   */
+  async pop(transition?: TransitionConfig): Promise<void> {
+    if (this.stack.length <= 1) {
+      console.warn('[SceneManager] Cannot pop the last scene');
+      return;
+    }
+    const prevKey = this.currentKey;
+    await this.popInternal(true, transition);
+    this.emit('change', { from: prevKey, to: this.currentKey! });
+  }
+
+  /**
+   * Replace the top scene with a new one.
+   */
+  async replace(
+    key: string,
+    data?: unknown,
+    transition?: TransitionConfig,
+  ): Promise<void> {
+    const prevKey = this.currentKey;
+    await this.popInternal(false);
+    await this.pushInternal(key, data, transition);
+    this.emit('change', { from: prevKey, to: key });
+  }
+
+  /**
+   * Called every frame by GameApplication.
+   */
+  update(dt: number): void {
+    // Update only the top scene
+    this.current?.scene.onUpdate?.(dt);
+  }
+
+  /**
+   * Called on viewport resize.
+   */
+  resize(width: number, height: number): void {
+    this._width = width;
+    this._height = height;
+
+    // Notify all scenes in the stack
+    for (const entry of this.stack) {
+      entry.scene.onResize?.(width, height);
+    }
+  }
+
+  /**
+   * Destroy all scenes and clear the manager.
+   */
+  destroy(): void {
+    for (const entry of this.stack) {
+      entry.scene.onDestroy?.();
+      entry.scene.container.destroy({ children: true });
+    }
+    this.stack.length = 0;
+    this.registry.clear();
+    this.removeAllListeners();
+  }
+
+  // ─── Internal ──────────────────────────────────────────
+
+  private createScene(key: string): IScene {
+    const Ctor = this.registry.get(key);
+    if (!Ctor) {
+      throw new Error(`[SceneManager] Scene "${key}" is not registered`);
+    }
+    return new Ctor();
+  }
+
+  private async pushInternal(
+    key: string,
+    data?: unknown,
+    transition?: TransitionConfig,
+  ): Promise<void> {
+    this._transitioning = true;
+
+    const scene = this.createScene(key);
+    this.root.addChild(scene.container);
+
+    // Set initial size
+    if (this._width && this._height) {
+      scene.onResize?.(this._width, this._height);
+    }
+
+    // Transition in
+    await this.transitionIn(scene.container, transition);
+
+    await scene.onEnter?.(data);
+
+    this.stack.push({ scene, key });
+    this._transitioning = false;
+  }
+
+  private async popInternal(
+    showTransition: boolean,
+    transition?: TransitionConfig,
+  ): Promise<void> {
+    const entry = this.stack.pop();
+    if (!entry) return;
+
+    this._transitioning = true;
+
+    await entry.scene.onExit?.();
+
+    if (showTransition) {
+      await this.transitionOut(entry.scene.container, transition);
+    }
+
+    entry.scene.onDestroy?.();
+    entry.scene.container.destroy({ children: true });
+
+    this._transitioning = false;
+  }
+
+  private async transitionIn(
+    container: Container,
+    config?: TransitionConfig,
+  ): Promise<void> {
+    const type = config?.type ?? TT.NONE;
+    const duration = config?.duration ?? 300;
+
+    if (type === TT.NONE || duration <= 0) return;
+
+    if (type === TT.FADE) {
+      container.alpha = 0;
+      await Tween.to(container, { alpha: 1 }, duration, config?.easing);
+    } else if (type === TT.SLIDE_LEFT) {
+      container.x = this._width;
+      await Tween.to(container, { x: 0 }, duration, config?.easing);
+    } else if (type === TT.SLIDE_RIGHT) {
+      container.x = -this._width;
+      await Tween.to(container, { x: 0 }, duration, config?.easing);
+    }
+  }
+
+  private async transitionOut(
+    container: Container,
+    config?: TransitionConfig,
+  ): Promise<void> {
+    const type = config?.type ?? TT.FADE;
+    const duration = config?.duration ?? 300;
+
+    if (type === TT.NONE || duration <= 0) return;
+
+    if (type === TT.FADE) {
+      await Tween.to(container, { alpha: 0 }, duration, config?.easing);
+    } else if (type === TT.SLIDE_LEFT) {
+      await Tween.to(container, { x: -this._width }, duration, config?.easing);
+    } else if (type === TT.SLIDE_RIGHT) {
+      await Tween.to(container, { x: this._width }, duration, config?.easing);
+    }
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,4 @@
+export { GameApplication } from './GameApplication';
+export { SceneManager } from './SceneManager';
+export { Scene } from './Scene';
+export { EventEmitter } from './EventEmitter';