@energy8platform/game-engine 0.10.11 → 0.11.0

package/src/react/extendAll.ts

@@ -14,6 +14,10 @@ import {
   HTMLText,
 } from 'pixi.js';
 import { extend } from './catalogue';
+import {
+  Button, Label, Panel, FlexContainer, ProgressBar,
+  ScrollContainer, Modal, Toast, BalanceDisplay, WinDisplay, Layout,
+} from '../ui';
 
 /**
  * Register all standard PixiJS display objects for JSX use.
@@ -38,14 +42,31 @@ export function extendPixiElements(): void {
 }
 
 /**
- * Register @pixi/layout components for JSX use.
- * Pass the dynamically imported module:
+ * Register all engine UI components for JSX use.
+ * Call once at app startup before rendering React scenes that use UI components.
  *
+ * @example
  * ```ts
- * const layout = await import('@pixi/layout/components');
- * extendLayoutElements(layout);
+ * extendPixiElements();
+ * extendUIElements();
+ *
+ * // Now you can use:
+ * // <button text="SPIN" onPress={handler} />
+ * // <flexContainer direction="row" gap={16}>...</flexContainer>
+ * // <label text="Hello" style-fontSize={24} />
  * ```
  */
-export function extendLayoutElements(layoutModule: Record<string, any>): void {
-  extend(layoutModule);
+export function extendUIElements(): void {
+  extend({
+    Button, Label, Panel, FlexContainer, ProgressBar,
+    ScrollContainer, Modal, Toast, BalanceDisplay, WinDisplay, Layout,
+  });
+}
+
+/**
+ * Register additional custom components for JSX use.
+ * Pass an object mapping component names to their constructors.
+ */
+export function extendCustomElements(components: Record<string, any>): void {
+  extend(components);
 }

package/src/react/index.ts

@@ -4,7 +4,7 @@ export type { PixiRoot } from './createPixiRoot';
 
 // Catalogue
 export { extend } from './catalogue';
-export { extendPixiElements, extendLayoutElements } from './extendAll';
+export { extendPixiElements, extendUIElements, extendCustomElements } from './extendAll';
 
 // Scene
 export { ReactScene } from './ReactScene';

package/src/react/jsx.d.ts

@@ -0,0 +1,222 @@
+/**
+ * JSX IntrinsicElements type declarations for the PixiJS React reconciler.
+ *
+ * Provides TypeScript autocompletion and type safety for:
+ * - Standard PixiJS elements: <container>, <sprite>, <text>, <graphics>
+ * - Engine UI components: <button>, <label>, <panel>, <flexContainer>, etc.
+ *
+ * Dash-notation is supported for nested config objects:
+ *   <button colors-default={0xff0000} colors-hover={0x00ff00} />
+ */
+
+import type { Container, Texture, TextStyle } from 'pixi.js';
+import type { ViewInput } from '../ui/view';
+import type { ButtonConfig, ButtonState } from '../ui/Button';
+import type { LabelConfig } from '../ui/Label';
+import type { PanelConfig } from '../ui/Panel';
+import type { FlexContainerConfig } from '../ui/FlexContainer';
+import type { ProgressBarConfig } from '../ui/ProgressBar';
+import type { ScrollContainerConfig } from '../ui/ScrollContainer';
+import type { ModalConfig } from '../ui/Modal';
+import type { ToastConfig } from '../ui/Toast';
+import type { BalanceDisplayConfig } from '../ui/BalanceDisplay';
+import type { WinDisplayConfig } from '../ui/WinDisplay';
+import type { LayoutConfig } from '../ui/Layout';
+
+// ─── Event props ─────────────────────────────────────────
+
+interface PixiEventProps {
+  onClick?: (e: any) => void;
+  onPointerDown?: (e: any) => void;
+  onPointerUp?: (e: any) => void;
+  onPointerMove?: (e: any) => void;
+  onPointerOver?: (e: any) => void;
+  onPointerOut?: (e: any) => void;
+  onPointerEnter?: (e: any) => void;
+  onPointerLeave?: (e: any) => void;
+  onPointerCancel?: (e: any) => void;
+  onPointerTap?: (e: any) => void;
+  onPointerUpOutside?: (e: any) => void;
+  onMouseDown?: (e: any) => void;
+  onMouseUp?: (e: any) => void;
+  onMouseMove?: (e: any) => void;
+  onMouseOver?: (e: any) => void;
+  onMouseOut?: (e: any) => void;
+  onWheel?: (e: any) => void;
+  onTap?: (e: any) => void;
+  onRightClick?: (e: any) => void;
+}
+
+// ─── Base container props (shared by all elements) ───────
+
+interface BaseProps extends PixiEventProps {
+  key?: React.Key;
+  ref?: React.Ref<any>;
+  children?: React.ReactNode;
+
+  // Container props
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  alpha?: number;
+  visible?: boolean;
+  rotation?: number;
+  angle?: number;
+  zIndex?: number;
+  label?: string;
+  cursor?: string;
+  eventMode?: 'auto' | 'none' | 'passive' | 'static' | 'dynamic';
+
+  // Nested via dash-notation
+  'scale-x'?: number;
+  'scale-y'?: number;
+  'pivot-x'?: number;
+  'pivot-y'?: number;
+  'position-x'?: number;
+  'position-y'?: number;
+  'anchor-x'?: number;
+  'anchor-y'?: number;
+
+  // Allow scale as number (uniform)
+  scale?: number | { x: number; y: number };
+}
+
+// ─── PixiJS primitive elements ───────────────────────────
+
+interface SpriteProps extends BaseProps {
+  texture?: string | Texture;
+  anchor?: number | { x: number; y: number };
+  tint?: number;
+}
+
+interface TextProps extends BaseProps {
+  text?: string;
+  style?: Partial<TextStyle>;
+  anchor?: number | { x: number; y: number };
+  // Dash-notation for style
+  'style-fontSize'?: number;
+  'style-fill'?: number | string;
+  'style-fontFamily'?: string;
+  'style-fontWeight'?: string;
+  'style-letterSpacing'?: number;
+}
+
+interface GraphicsProps extends BaseProps {
+  /** Draw function: receives the Graphics instance, called on mount and updates */
+  draw?: (g: any) => void;
+}
+
+// ─── Engine UI component props ───────────────────────────
+
+interface ButtonComponentProps extends BaseProps, Omit<ButtonConfig, 'colors' | 'textStyle'> {
+  // Full object form
+  colors?: Partial<Record<ButtonState, number>>;
+  textStyle?: Record<string, unknown>;
+  // Custom views (ViewInput: string texture name, Texture, or Container)
+  defaultView?: ViewInput;
+  hoverView?: ViewInput;
+  pressedView?: ViewInput;
+  disabledView?: ViewInput;
+  // Dash-notation for nested objects
+  'colors-default'?: number;
+  'colors-hover'?: number;
+  'colors-pressed'?: number;
+  'colors-disabled'?: number;
+  'textStyle-fontSize'?: number;
+  'textStyle-fill'?: number | string;
+  'textStyle-fontFamily'?: string;
+  'textStyle-fontWeight'?: string;
+  'textStyle-fontStyle'?: string;
+  'textStyle-letterSpacing'?: number;
+  // Component callbacks
+  onPress?: () => void;
+}
+
+interface LabelComponentProps extends BaseProps, Omit<LabelConfig, 'style'> {
+  style?: Partial<TextStyle>;
+  'style-fontSize'?: number;
+  'style-fill'?: number | string;
+  'style-fontFamily'?: string;
+  'style-fontWeight'?: string;
+  'style-letterSpacing'?: number;
+}
+
+interface PanelComponentProps extends BaseProps, Omit<PanelConfig, 'layout'> {
+  layout?: Partial<FlexContainerConfig>;
+}
+
+interface FlexContainerComponentProps extends BaseProps, FlexContainerConfig {
+  padding?: number | [number, number, number, number];
+}
+
+interface ProgressBarComponentProps extends BaseProps, ProgressBarConfig {
+  progress?: number;
+  /** Custom track background (string texture name, Texture, or Container) */
+  trackView?: ViewInput;
+  /** Custom fill bar */
+  fillView?: ViewInput;
+}
+
+interface ScrollContainerComponentProps extends BaseProps, Omit<ScrollContainerConfig, 'width' | 'height'> {
+  width: number;
+  height: number;
+  /** Show scrollbar indicator */
+  scrollbar?: boolean;
+  /** Custom scrollbar thumb view */
+  thumbView?: ViewInput;
+  scrollbarWidth?: number;
+  scrollbarPadding?: number;
+  scrollbarColor?: number;
+  scrollbarAlpha?: number;
+}
+
+interface ModalComponentProps extends BaseProps, ModalConfig {
+  onClose?: () => void;
+}
+
+interface ToastComponentProps extends BaseProps, ToastConfig {
+  /** Custom background view */
+  backgroundView?: ViewInput;
+}
+
+interface BalanceDisplayComponentProps extends BaseProps, BalanceDisplayConfig {
+  /** Current balance value */
+  value?: number;
+}
+
+interface WinDisplayComponentProps extends BaseProps, WinDisplayConfig {}
+
+interface LayoutComponentProps extends BaseProps, LayoutConfig {}
+
+// ─── JSX IntrinsicElements ───────────────────────────────
+
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      // PixiJS primitives
+      container: BaseProps;
+      sprite: SpriteProps;
+      text: TextProps;
+      graphics: GraphicsProps;
+      animatedSprite: BaseProps & { textures?: Texture[]; animationSpeed?: number; loop?: boolean; playing?: boolean };
+      nineSliceSprite: BaseProps & { texture?: string | Texture; leftWidth?: number; topHeight?: number; rightWidth?: number; bottomHeight?: number };
+      tilingSprite: BaseProps & { texture?: string | Texture; tilePosition?: { x: number; y: number } };
+
+      // Engine UI components
+      button: ButtonComponentProps;
+      label: LabelComponentProps;
+      panel: PanelComponentProps;
+      flexContainer: FlexContainerComponentProps;
+      progressBar: ProgressBarComponentProps;
+      scrollContainer: ScrollContainerComponentProps;
+      modal: ModalComponentProps;
+      toast: ToastComponentProps;
+      balanceDisplay: BalanceDisplayComponentProps;
+      winDisplay: WinDisplayComponentProps;
+      layout: LayoutComponentProps;
+    }
+  }
+}
+
+export {};

package/src/react/reconciler.ts

@@ -2,7 +2,7 @@ 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';
+import { applyProps, hasEventProps, extractConfig, diffConfig, applyEventProps } from './applyProps';
 
 function toPascalCase(str: string): string {
   return str.charAt(0).toUpperCase() + str.slice(1);
@@ -37,10 +37,19 @@ const hostConfig: Reconciler.HostConfig<
         `Call extend({ ${name} }) before rendering.`,
       );
     }
-    const instance = new Ctor();
-    applyProps(instance, props);
 
-    // Enable interactivity if any event prop is present
+    let instance;
+    if (Ctor.prototype.__uiComponent) {
+      // Config-based UI component: pass props as constructor config
+      const config = extractConfig(props);
+      instance = new Ctor(config);
+      applyEventProps(instance, props);
+    } else {
+      // Standard PixiJS element
+      instance = new Ctor();
+      applyProps(instance, props);
+    }
+
     if (hasEventProps(props) && instance.eventMode === 'auto') {
       instance.eventMode = 'static';
     }
@@ -97,7 +106,15 @@ const hostConfig: Reconciler.HostConfig<
   },
 
   commitUpdate(instance, _updatePayload, _type, oldProps, newProps) {
-    applyProps(instance, newProps, oldProps);
+    if (instance.__uiComponent && typeof instance.updateConfig === 'function') {
+      const changed = diffConfig(newProps, oldProps);
+      if (Object.keys(changed).length > 0) {
+        instance.updateConfig(changed);
+      }
+      applyEventProps(instance, newProps, oldProps);
+    } else {
+      applyProps(instance, newProps, oldProps);
+    }
 
     if (hasEventProps(newProps) && instance.eventMode === 'auto') {
       instance.eventMode = 'static';

package/src/ui/BalanceDisplay.ts

@@ -1,5 +1,6 @@
 import { Container } from 'pixi.js';
 import { Label } from './Label';
+import { Tween } from '../animation/Tween';
 import { Easing } from '../animation/Easing';
 
 export interface BalanceDisplayConfig {
@@ -23,7 +24,7 @@ export interface BalanceDisplayConfig {
  * Reactive balance display component.
  *
  * Automatically formats currency and can animate value changes
- * with a smooth countup/countdown effect.
+ * with a smooth countup/countdown effect using engine Tween.
  *
  * @example
  * ```ts
@@ -35,13 +36,15 @@ export interface BalanceDisplayConfig {
  * ```
  */
 export class BalanceDisplay extends Container {
+  readonly __uiComponent = true as const;
+
   private _prefixLabel: Label | null = null;
   private _valueLabel: Label;
   private _config: Required<Pick<BalanceDisplayConfig, 'currency' | 'locale' | 'animated' | 'animationDuration'>>;
   private _currentValue = 0;
   private _displayedValue = 0;
-  private _animating = false;
-  private _animationCancelled = false;
+  /** Internal target for Tween animation */
+  private _tweenTarget = { value: 0 };
 
   constructor(config: BalanceDisplayConfig = {}) {
     super();
@@ -111,42 +114,21 @@ export class BalanceDisplay extends Container {
     this.updateDisplay();
   }
 
-  private async animateValue(from: number, to: number): Promise<void> {
-    if (this._animating) {
-      this._animationCancelled = true;
-    }
-
-    this._animating = true;
-    this._animationCancelled = false;
-    const duration = this._config.animationDuration;
-    const startTime = Date.now();
-
-    return new Promise<void>((resolve) => {
-      const tick = () => {
-        if (this._animationCancelled) {
-          this._animating = false;
-          resolve();
-          return;
-        }
-
-        const elapsed = Date.now() - startTime;
-        const t = Math.min(elapsed / duration, 1);
-        const eased = Easing.easeOutCubic(t);
-
-        this._displayedValue = from + (to - from) * eased;
+  private animateValue(from: number, to: number): void {
+    // Cancel any running animation
+    Tween.killTweensOf(this._tweenTarget);
+
+    this._tweenTarget.value = from;
+    Tween.to(
+      this._tweenTarget,
+      { value: to },
+      this._config.animationDuration,
+      Easing.easeOutCubic,
+      () => {
+        this._displayedValue = this._tweenTarget.value;
         this.updateDisplay();
-
-        if (t < 1) {
-          requestAnimationFrame(tick);
-        } else {
-          this._displayedValue = to;
-          this.updateDisplay();
-          this._animating = false;
-          resolve();
-        }
-      };
-      requestAnimationFrame(tick);
-    });
+      },
+    );
   }
 
   private updateDisplay(): void {
@@ -163,4 +145,15 @@ export class BalanceDisplay extends Container {
       this._valueLabel.y = 14;
     }
   }
+
+  /** React reconciler update hook */
+  updateConfig(changed: Record<string, any>): void {
+    if ('value' in changed) this.setValue(changed.value);
+    if ('currency' in changed) this.setCurrency(changed.currency);
+  }
+
+  override destroy(options?: boolean | { children?: boolean; texture?: boolean; textureSource?: boolean }): void {
+    Tween.killTweensOf(this._tweenTarget);
+    super.destroy(options);
+  }
 }