@energy8platform/game-engine 0.7.1 → 0.9.0

package/src/core/SceneManager.ts

@@ -25,17 +25,22 @@ interface SceneManagerEvents {
  * ```
  */
 export class SceneManager extends EventEmitter<SceneManagerEvents> {
+  private static MAX_TRANSITION_DEPTH = 10;
+
   /** Root container that scenes are added to */
   public root!: Container;
 
   private registry = new Map<string, SceneConstructor>();
   private stack: SceneEntry[] = [];
-  private _transitioning = false;
+  private _transitionDepth = 0;
 
   /** Current viewport dimensions — set by ViewportManager */
   private _width = 0;
   private _height = 0;
 
+  /** @internal GameApplication reference — passed to scenes */
+  private _app: any;
+
   constructor(root?: Container) {
     super();
     if (root) this.root = root;
@@ -46,6 +51,11 @@ export class SceneManager extends EventEmitter<SceneManagerEvents> {
     this.root = root;
   }
 
+  /** @internal Set the app reference (called by GameApplication) */
+  setApp(app: any): void {
+    this._app = app;
+  }
+
   /** Register a scene class by key */
   register(key: string, ctor: SceneConstructor): this {
     this.registry.set(key, ctor);
@@ -64,7 +74,7 @@ export class SceneManager extends EventEmitter<SceneManagerEvents> {
 
   /** Whether a scene transition is in progress */
   get isTransitioning(): boolean {
-    return this._transitioning;
+    return this._transitionDepth > 0;
   }
 
   /**
@@ -75,6 +85,9 @@ export class SceneManager extends EventEmitter<SceneManagerEvents> {
     data?: unknown,
     transition?: TransitionConfig,
   ): Promise<void> {
+    if (this._transitionDepth >= SceneManager.MAX_TRANSITION_DEPTH) {
+      throw new Error('[SceneManager] Max transition depth exceeded — possible infinite loop');
+    }
     const prevKey = this.currentKey;
 
     // Exit all current scenes
@@ -96,6 +109,9 @@ export class SceneManager extends EventEmitter<SceneManagerEvents> {
     data?: unknown,
     transition?: TransitionConfig,
   ): Promise<void> {
+    if (this._transitionDepth >= SceneManager.MAX_TRANSITION_DEPTH) {
+      throw new Error('[SceneManager] Max transition depth exceeded — possible infinite loop');
+    }
     const prevKey = this.currentKey;
     await this.pushInternal(key, data, transition);
     this.emit('change', { from: prevKey, to: key });
@@ -109,6 +125,9 @@ export class SceneManager extends EventEmitter<SceneManagerEvents> {
       console.warn('[SceneManager] Cannot pop the last scene');
       return;
     }
+    if (this._transitionDepth >= SceneManager.MAX_TRANSITION_DEPTH) {
+      throw new Error('[SceneManager] Max transition depth exceeded — possible infinite loop');
+    }
     const prevKey = this.currentKey;
     await this.popInternal(true, transition);
     this.emit('change', { from: prevKey, to: this.currentKey! });
@@ -122,6 +141,9 @@ export class SceneManager extends EventEmitter<SceneManagerEvents> {
     data?: unknown,
     transition?: TransitionConfig,
   ): Promise<void> {
+    if (this._transitionDepth >= SceneManager.MAX_TRANSITION_DEPTH) {
+      throw new Error('[SceneManager] Max transition depth exceeded — possible infinite loop');
+    }
     const prevKey = this.currentKey;
     await this.popInternal(false);
     await this.pushInternal(key, data, transition);
@@ -169,7 +191,11 @@ export class SceneManager extends EventEmitter<SceneManagerEvents> {
     if (!Ctor) {
       throw new Error(`[SceneManager] Scene "${key}" is not registered`);
     }
-    return new Ctor();
+    const scene = new Ctor();
+    if (this._app) {
+      scene.__engineApp = this._app;
+    }
+    return scene;
   }
 
   private async pushInternal(
@@ -177,7 +203,7 @@ export class SceneManager extends EventEmitter<SceneManagerEvents> {
     data?: unknown,
     transition?: TransitionConfig,
   ): Promise<void> {
-    this._transitioning = true;
+    this._transitionDepth++;
 
     const scene = this.createScene(key);
     this.root.addChild(scene.container);
@@ -195,7 +221,7 @@ export class SceneManager extends EventEmitter<SceneManagerEvents> {
 
     await scene.onEnter?.(data);
 
-    this._transitioning = false;
+    this._transitionDepth--;
   }
 
   private async popInternal(
@@ -205,7 +231,7 @@ export class SceneManager extends EventEmitter<SceneManagerEvents> {
     const entry = this.stack.pop();
     if (!entry) return;
 
-    this._transitioning = true;
+    this._transitionDepth++;
 
     await entry.scene.onExit?.();
 
@@ -216,7 +242,7 @@ export class SceneManager extends EventEmitter<SceneManagerEvents> {
     entry.scene.onDestroy?.();
     entry.scene.container.destroy({ children: true });
 
-    this._transitioning = false;
+    this._transitionDepth--;
   }
 
   private async transitionIn(

package/src/react/EngineContext.ts

@@ -0,0 +1,26 @@
+import { createContext, useContext } from 'react';
+import type { GameApplication } from '../core/GameApplication';
+import type { AudioManager } from '../audio/AudioManager';
+import type { InputManager } from '../input/InputManager';
+import type { ViewportManager } from '../viewport/ViewportManager';
+import type { CasinoGameSDK } from '@energy8platform/game-sdk';
+import type { GameConfigData } from '@energy8platform/game-sdk';
+
+export interface EngineContextValue {
+  app: GameApplication;
+  sdk: CasinoGameSDK | null;
+  audio: AudioManager;
+  input: InputManager;
+  viewport: ViewportManager;
+  gameConfig: GameConfigData | null;
+  screen: { width: number; height: number; scale: number };
+  isPortrait: boolean;
+}
+
+export const EngineContext = createContext<EngineContextValue | null>(null);
+
+export function useEngine(): EngineContextValue {
+  const ctx = useContext(EngineContext);
+  if (!ctx) throw new Error('useEngine() must be used inside a ReactScene');
+  return ctx;
+}

package/src/react/ReactScene.ts

@@ -0,0 +1,88 @@
+import { createElement } from 'react';
+import type { ReactElement } from 'react';
+import { Scene } from '../core/Scene';
+import { createPixiRoot } from './createPixiRoot';
+import type { PixiRoot } from './createPixiRoot';
+import { EngineContext } from './EngineContext';
+import type { EngineContextValue } from './EngineContext';
+import type { GameApplication } from '../core/GameApplication';
+import { Orientation } from '../types';
+
+export abstract class ReactScene extends Scene {
+  private _pixiRoot: PixiRoot | null = null;
+  private _contextValue: EngineContextValue | null = null;
+
+  /** Subclasses implement this to return their React element tree. */
+  abstract render(): ReactElement;
+
+  /** Access the GameApplication instance. */
+  protected getApp(): GameApplication {
+    const app = (this as any).__engineApp;
+    if (!app) {
+      throw new Error(
+        '[ReactScene] No GameApplication reference. ' +
+        'Ensure this scene is managed by SceneManager (not instantiated manually).',
+      );
+    }
+    return app;
+  }
+
+  override async onEnter(data?: unknown): Promise<void> {
+    const app = this.getApp();
+
+    this._contextValue = {
+      app,
+      sdk: app.sdk,
+      audio: app.audio,
+      input: app.input,
+      viewport: app.viewport,
+      gameConfig: app.gameConfig,
+      screen: {
+        width: app.viewport.width,
+        height: app.viewport.height,
+        scale: app.viewport.scale,
+      },
+      isPortrait: app.viewport.orientation === Orientation.PORTRAIT,
+    };
+
+    this._pixiRoot = createPixiRoot(this.container);
+    this._mountReactTree();
+  }
+
+  override async onExit(): Promise<void> {
+    this._pixiRoot?.unmount();
+    this._pixiRoot = null;
+    this._contextValue = null;
+  }
+
+  override onResize(width: number, height: number): void {
+    if (!this._contextValue) return;
+    const app = this.getApp();
+
+    this._contextValue = {
+      ...this._contextValue,
+      screen: { width, height, scale: app.viewport.scale },
+      isPortrait: height > width,
+    };
+
+    this._mountReactTree();
+  }
+
+  override onDestroy(): void {
+    this._pixiRoot?.unmount();
+    this._pixiRoot = null;
+    this._contextValue = null;
+  }
+
+  private _mountReactTree(): void {
+    if (!this._pixiRoot || !this._contextValue) return;
+
+    this._pixiRoot.render(
+      createElement(
+        EngineContext.Provider,
+        { value: this._contextValue },
+        this.render(),
+      ),
+    );
+  }
+}

package/src/react/applyProps.ts

@@ -0,0 +1,107 @@
+const RESERVED = new Set(['children', 'key', 'ref']);
+
+const REACT_TO_PIXI_EVENTS: Record<string, string> = {
+  onClick: 'onclick',
+  onPointerDown: 'onpointerdown',
+  onPointerUp: 'onpointerup',
+  onPointerMove: 'onpointermove',
+  onPointerOver: 'onpointerover',
+  onPointerOut: 'onpointerout',
+  onPointerEnter: 'onpointerenter',
+  onPointerLeave: 'onpointerleave',
+  onPointerCancel: 'onpointercancel',
+  onPointerTap: 'onpointertap',
+  onPointerUpOutside: 'onpointerupoutside',
+  onMouseDown: 'onmousedown',
+  onMouseUp: 'onmouseup',
+  onMouseMove: 'onmousemove',
+  onMouseOver: 'onmouseover',
+  onMouseOut: 'onmouseout',
+  onMouseEnter: 'onmouseenter',
+  onMouseLeave: 'onmouseleave',
+  onMouseUpOutside: 'onmouseupoutside',
+  onTouchStart: 'ontouchstart',
+  onTouchEnd: 'ontouchend',
+  onTouchMove: 'ontouchmove',
+  onTouchCancel: 'ontouchcancel',
+  onTouchEndOutside: 'ontouchendoutside',
+  onWheel: 'onwheel',
+  onRightClick: 'onrightclick',
+  onRightDown: 'onrightdown',
+  onRightUp: 'onrightup',
+  onRightUpOutside: 'onrightupoutside',
+  onTap: 'ontap',
+  onGlobalpointermove: 'onglobalpointermove',
+  onGlobalmousemove: 'onglobalmousemove',
+  onGlobaltouchmove: 'onglobaltouchmove',
+};
+
+export function isEventProp(key: string): boolean {
+  return key in REACT_TO_PIXI_EVENTS;
+}
+
+export function hasEventProps(props: Record<string, any>): boolean {
+  for (const key in props) {
+    if (isEventProp(key)) return true;
+  }
+  return false;
+}
+
+function setNestedValue(target: any, path: string[], value: any): void {
+  let obj = target;
+  for (let i = 0; i < path.length - 1; i++) {
+    obj = obj[path[i]];
+    if (obj == null) return;
+  }
+  obj[path[path.length - 1]] = value;
+}
+
+export function applyProps(
+  instance: any,
+  newProps: Record<string, any>,
+  oldProps: Record<string, any> = {},
+): void {
+  // Remove old props not in newProps
+  for (const key in oldProps) {
+    if (RESERVED.has(key) || key in newProps) continue;
+
+    const pixiEvent = REACT_TO_PIXI_EVENTS[key];
+    if (pixiEvent) {
+      instance[pixiEvent] = null;
+    } else if (key === 'draw') {
+      // no-op: can't un-draw
+    } else if (key.includes('-')) {
+      // Nested property reset not trivially possible, skip
+    } else {
+      try {
+        instance[key] = undefined;
+      } catch {
+        // read-only or non-configurable
+      }
+    }
+  }
+
+  // Apply new props
+  for (const key in newProps) {
+    if (RESERVED.has(key)) continue;
+
+    const value = newProps[key];
+    const pixiEvent = REACT_TO_PIXI_EVENTS[key];
+
+    if (pixiEvent) {
+      instance[pixiEvent] = value;
+    } else if (key === 'draw' && typeof value === 'function') {
+      instance.clear?.();
+      value(instance);
+    } else if (key.includes('-')) {
+      const parts = key.split('-');
+      setNestedValue(instance, parts, value);
+    } else {
+      try {
+        instance[key] = value;
+      } catch {
+        // read-only property
+      }
+    }
+  }
+}

package/src/react/catalogue.ts

@@ -0,0 +1,17 @@
+/** Mutable catalogue: PascalCase name -> PixiJS constructor */
+export const catalogue: Record<string, any> = {};
+
+/**
+ * Register PixiJS classes for use as JSX elements.
+ * Keys must be PascalCase; JSX uses the camelCase equivalent.
+ *
+ * @example
+ * ```ts
+ * import { Container, Sprite, Text } from 'pixi.js';
+ * extend({ Container, Sprite, Text });
+ * // Now <container>, <sprite>, <text> work in JSX
+ * ```
+ */
+export function extend(components: Record<string, any>): void {
+  Object.assign(catalogue, components);
+}

package/src/react/createPixiRoot.ts

@@ -0,0 +1,31 @@
+import { ConcurrentRoot } from 'react-reconciler/constants';
+import type { Container } from 'pixi.js';
+import type { ReactElement } from 'react';
+import { reconciler } from './reconciler';
+
+export interface PixiRoot {
+  render(element: ReactElement): void;
+  unmount(): void;
+}
+
+export function createPixiRoot(container: Container): PixiRoot {
+  const fiberRoot = reconciler.createContainer(
+    container,       // containerInfo
+    ConcurrentRoot,  // tag
+    null,            // hydrationCallbacks
+    false,           // isStrictMode
+    null,            // concurrentUpdatesByDefaultOverride
+    '',              // identifierPrefix
+    (err: Error) => console.error('[PixiRoot]', err),
+    null,            // transitionCallbacks
+  );
+
+  return {
+    render(element: ReactElement) {
+      reconciler.updateContainer(element, fiberRoot, null, () => {});
+    },
+    unmount() {
+      reconciler.updateContainer(null, fiberRoot, null, () => {});
+    },
+  };
+}

package/src/react/extendAll.ts

@@ -0,0 +1,51 @@
+import {
+  Container,
+  Sprite,
+  Graphics,
+  Text,
+  AnimatedSprite,
+  NineSliceSprite,
+  TilingSprite,
+  Mesh,
+  MeshPlane,
+  MeshRope,
+  MeshSimple,
+  BitmapText,
+  HTMLText,
+} from 'pixi.js';
+import { extend } from './catalogue';
+
+/**
+ * Register all standard PixiJS display objects for JSX use.
+ * Call once at app startup before rendering any React scenes.
+ */
+export function extendPixiElements(): void {
+  extend({
+    Container,
+    Sprite,
+    Graphics,
+    Text,
+    AnimatedSprite,
+    NineSliceSprite,
+    TilingSprite,
+    Mesh,
+    MeshPlane,
+    MeshRope,
+    MeshSimple,
+    BitmapText,
+    HTMLText,
+  });
+}
+
+/**
+ * Register @pixi/layout components for JSX use.
+ * Pass the dynamically imported module:
+ *
+ * ```ts
+ * const layout = await import('@pixi/layout/components');
+ * extendLayoutElements(layout);
+ * ```
+ */
+export function extendLayoutElements(layoutModule: Record<string, any>): void {
+  extend(layoutModule);
+}

package/src/react/hooks.ts

@@ -0,0 +1,46 @@
+import { useState, useEffect } from 'react';
+import { useEngine } from './EngineContext';
+import type { CasinoGameSDK, SessionData, GameConfigData } from '@energy8platform/game-sdk';
+import type { AudioManager } from '../audio/AudioManager';
+import type { InputManager } from '../input/InputManager';
+
+export function useSDK(): CasinoGameSDK | null {
+  return useEngine().sdk;
+}
+
+export function useAudio(): AudioManager {
+  return useEngine().audio;
+}
+
+export function useInput(): InputManager {
+  return useEngine().input;
+}
+
+export function useViewport(): { width: number; height: number; scale: number; isPortrait: boolean } {
+  const { screen, isPortrait } = useEngine();
+  return { ...screen, isPortrait };
+}
+
+export function useBalance(): number {
+  const { sdk } = useEngine();
+  const [balance, setBalance] = useState(sdk?.balance ?? 0);
+
+  useEffect(() => {
+    if (!sdk) return;
+    const handler = (data: { balance: number }) => setBalance(data.balance);
+    sdk.on('balanceUpdate', handler);
+    return () => {
+      sdk.off('balanceUpdate', handler);
+    };
+  }, [sdk]);
+
+  return balance;
+}
+
+export function useSession(): SessionData | null {
+  return useEngine().app.session;
+}
+
+export function useGameConfig<T = GameConfigData>(): T | null {
+  return useEngine().gameConfig as T | null;
+}

package/src/react/index.ts

@@ -0,0 +1,23 @@
+// Core
+export { createPixiRoot } from './createPixiRoot';
+export type { PixiRoot } from './createPixiRoot';
+
+// Catalogue
+export { extend } from './catalogue';
+export { extendPixiElements, extendLayoutElements } from './extendAll';
+
+// Scene
+export { ReactScene } from './ReactScene';
+
+// Context & Hooks
+export { EngineContext, useEngine } from './EngineContext';
+export type { EngineContextValue } from './EngineContext';
+export {
+  useSDK,
+  useAudio,
+  useInput,
+  useViewport,
+  useBalance,
+  useSession,
+  useGameConfig,
+} from './hooks';

package/src/react/reconciler.ts

@@ -0,0 +1,169 @@
+import Reconciler from 'react-reconciler';
+import { DefaultEventPriority } from 'react-reconciler/constants';
+import { Container } from 'pixi.js';
+import { catalogue } from './catalogue';
+import { applyProps, hasEventProps } from './applyProps';
+
+function toPascalCase(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+const hostConfig: Reconciler.HostConfig<
+  string,         // Type
+  Record<string, any>, // Props
+  Container,      // Container
+  any,            // Instance
+  any,            // TextInstance
+  any,            // SuspenseInstance
+  any,            // HydratableInstance
+  any,            // PublicInstance
+  any,            // HostContext
+  any,            // UpdatePayload
+  any,            // ChildSet
+  any,            // TimeoutHandle
+  any             // NoTimeout
+> = {
+  isPrimaryRenderer: false,
+  supportsMutation: true,
+  supportsPersistence: false,
+  supportsHydration: false,
+
+  createInstance(type, props) {
+    const name = toPascalCase(type);
+    const Ctor = catalogue[name];
+    if (!Ctor) {
+      throw new Error(
+        `[PixiReconciler] Unknown element "<${type}>". ` +
+        `Call extend({ ${name} }) before rendering.`,
+      );
+    }
+    const instance = new Ctor();
+    applyProps(instance, props);
+
+    // Enable interactivity if any event prop is present
+    if (hasEventProps(props) && instance.eventMode === 'auto') {
+      instance.eventMode = 'static';
+    }
+
+    return instance;
+  },
+
+  createTextInstance() {
+    throw new Error(
+      '[PixiReconciler] Text strings are not supported. Use a <text> element.',
+    );
+  },
+
+  appendInitialChild(parent, child) {
+    if (child instanceof Container) parent.addChild(child);
+  },
+
+  appendChild(parent, child) {
+    if (child instanceof Container) parent.addChild(child);
+  },
+
+  appendChildToContainer(container, child) {
+    if (child instanceof Container) container.addChild(child);
+  },
+
+  removeChild(parent, child) {
+    if (child instanceof Container) {
+      parent.removeChild(child);
+      child.destroy({ children: true });
+    }
+  },
+
+  removeChildFromContainer(container, child) {
+    if (child instanceof Container) {
+      container.removeChild(child);
+      child.destroy({ children: true });
+    }
+  },
+
+  insertBefore(parent, child, beforeChild) {
+    if (child instanceof Container && beforeChild instanceof Container) {
+      if (child.parent) child.parent.removeChild(child);
+      const index = parent.getChildIndex(beforeChild);
+      parent.addChildAt(child, index);
+    }
+  },
+
+  insertInContainerBefore(container, child, beforeChild) {
+    if (child instanceof Container && beforeChild instanceof Container) {
+      if (child.parent) child.parent.removeChild(child);
+      const index = container.getChildIndex(beforeChild);
+      container.addChildAt(child, index);
+    }
+  },
+
+  commitUpdate(instance, _updatePayload, _type, oldProps, newProps) {
+    applyProps(instance, newProps, oldProps);
+
+    if (hasEventProps(newProps) && instance.eventMode === 'auto') {
+      instance.eventMode = 'static';
+    }
+  },
+
+  finalizeInitialChildren() {
+    return false;
+  },
+
+  prepareUpdate() {
+    return true;
+  },
+
+  shouldSetTextContent() {
+    return false;
+  },
+
+  getRootHostContext() {
+    return null;
+  },
+
+  getChildHostContext(parentHostContext: any) {
+    return parentHostContext;
+  },
+
+  getPublicInstance(instance: any) {
+    return instance;
+  },
+
+  prepareForCommit() {
+    return null;
+  },
+
+  resetAfterCommit() {},
+
+  preparePortalMount() {},
+
+  scheduleTimeout: setTimeout,
+  cancelTimeout: clearTimeout,
+  noTimeout: -1,
+
+  getCurrentEventPriority() {
+    return DefaultEventPriority;
+  },
+
+  hideInstance(instance) {
+    instance.visible = false;
+  },
+
+  unhideInstance(instance) {
+    instance.visible = true;
+  },
+
+  hideTextInstance() {},
+  unhideTextInstance() {},
+
+  clearContainer() {},
+
+  detachDeletedInstance() {},
+
+  prepareScopeUpdate() {},
+  getInstanceFromNode() { return null; },
+  getInstanceFromScope() { return null; },
+  beforeActiveInstanceBlur() {},
+  afterActiveInstanceBlur() {},
+};
+
+export const reconciler = Reconciler(hostConfig);