@energy8platform/game-engine 0.10.11 → 0.12.0

package/src/react/applyProps.ts

@@ -1,4 +1,92 @@
 const RESERVED = new Set(['children', 'key', 'ref']);
+/** Props handled by the reconciler as flex item config, not forwarded to components */
+const FLEX_ITEM_PROPS = new Set(['flexGrow', 'flexShrink', 'layoutWidth', 'layoutHeight', 'alignSelf', 'flexExclude']);
+
+// ─── UI Component helpers ────────────────────────────────
+
+/**
+ * Extract a config object from React props.
+ * - Strips reserved keys (children, key, ref) and event props
+ * - Unfolds dash-notation into nested objects: `colors-default` → `{ colors: { default: ... } }`
+ */
+export function extractConfig(props: Record<string, any>): Record<string, any> {
+  const config: Record<string, any> = {};
+
+  for (const key in props) {
+    if (RESERVED.has(key) || FLEX_ITEM_PROPS.has(key) || isEventProp(key)) continue;
+
+    if (key.includes('-')) {
+      const parts = key.split('-');
+      const root = parts[0];
+      const nested = parts.slice(1).join('-');
+      if (!config[root] || typeof config[root] !== 'object') {
+        config[root] = {};
+      }
+      config[root][nested] = props[key];
+    } else {
+      config[key] = props[key];
+    }
+  }
+
+  return config;
+}
+
+/**
+ * Diff two prop sets and return a config object with only changed values.
+ * Uses extractConfig format (dash-notation unfolded).
+ */
+export function diffConfig(
+  newProps: Record<string, any>,
+  oldProps: Record<string, any>,
+): Record<string, any> {
+  const changed: Record<string, any> = {};
+
+  // New or changed props
+  for (const key in newProps) {
+    if (RESERVED.has(key) || FLEX_ITEM_PROPS.has(key) || isEventProp(key)) continue;
+    if (newProps[key] !== oldProps[key]) {
+      if (key.includes('-')) {
+        const parts = key.split('-');
+        const root = parts[0];
+        const nested = parts.slice(1).join('-');
+        if (!changed[root] || typeof changed[root] !== 'object') {
+          changed[root] = {};
+        }
+        changed[root][nested] = newProps[key];
+      } else {
+        changed[key] = newProps[key];
+      }
+    }
+  }
+
+  return changed;
+}
+
+/**
+ * Apply only event props from React props to a PixiJS instance.
+ */
+export function applyEventProps(
+  instance: any,
+  newProps: Record<string, any>,
+  oldProps: Record<string, any> = {},
+): void {
+  // Remove old event handlers
+  for (const key in oldProps) {
+    if (!isEventProp(key) || key in newProps) continue;
+    instance[REACT_TO_PIXI_EVENTS[key]] = null;
+  }
+  // Apply new/changed event handlers + onPress (component-level callback)
+  for (const key in newProps) {
+    if (key === 'onPress') {
+      instance.onPress = newProps[key];
+      continue;
+    }
+    if (!isEventProp(key)) continue;
+    if (newProps[key] !== oldProps[key]) {
+      instance[REACT_TO_PIXI_EVENTS[key]] = newProps[key];
+    }
+  }
+}
 
 const REACT_TO_PIXI_EVENTS: Record<string, string> = {
   onClick: 'onclick',
@@ -63,7 +151,7 @@ export function applyProps(
 ): void {
   // Remove old props not in newProps
   for (const key in oldProps) {
-    if (RESERVED.has(key) || key in newProps) continue;
+    if (RESERVED.has(key) || FLEX_ITEM_PROPS.has(key) || key in newProps) continue;
 
     const pixiEvent = REACT_TO_PIXI_EVENTS[key];
     if (pixiEvent) {
@@ -83,7 +171,7 @@ export function applyProps(
 
   // Apply new props
   for (const key in newProps) {
-    if (RESERVED.has(key)) continue;
+    if (RESERVED.has(key) || FLEX_ITEM_PROPS.has(key)) continue;
 
     const value = newProps[key];
     const pixiEvent = REACT_TO_PIXI_EVENTS[key];

package/src/react/extendAll.ts

@@ -14,6 +14,11 @@ import {
   HTMLText,
 } from 'pixi.js';
 import { extend } from './catalogue';
+import {
+  Button, Label, Panel, FlexContainer, ProgressBar,
+  ScrollContainer, Modal, Toast, BalanceDisplay, WinDisplay, Layout,
+  Slider, Toggle,
+} from '../ui';
 
 /**
  * Register all standard PixiJS display objects for JSX use.
@@ -38,14 +43,32 @@ 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,
+    Slider, Toggle,
+  });
+}
+
+/**
+ * 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,249 @@
+/**
+ * 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, FlexItemConfig, AlignSelf } 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';
+import type { SliderConfig } from '../ui/Slider';
+import type { ToggleConfig } from '../ui/Toggle';
+
+// ─── 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 };
+
+  // Flex item props (used when child of <flexContainer>)
+  flexGrow?: number;
+  flexShrink?: number;
+  layoutWidth?: number;
+  layoutHeight?: number;
+  alignSelf?: AlignSelf;
+  flexExclude?: boolean;
+}
+
+// ─── 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 {}
+
+interface SliderComponentProps extends BaseProps, Omit<SliderConfig, 'width' | 'height'> {
+  width?: number;
+  height?: number;
+  onUpdate?: (value: number) => void;
+  onChange?: (value: number) => void;
+}
+
+interface ToggleComponentProps extends BaseProps, Omit<ToggleConfig, 'width' | 'height'> {
+  width?: number;
+  height?: number;
+  onView?: ViewInput;
+  offView?: ViewInput;
+  onChange?: (value: boolean) => void;
+}
+
+// ─── 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;
+      slider: SliderComponentProps;
+      toggle: ToggleComponentProps;
+    }
+  }
+}
+
+export {};

package/src/react/reconciler.ts

@@ -2,7 +2,34 @@ 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';
+import { FlexContainer } from '../ui/FlexContainer';
+import type { FlexItemConfig } from '../ui/FlexContainer';
+
+/** Flex item prop names that should be forwarded to _flexConfig on the child */
+const FLEX_ITEM_PROPS = ['flexGrow', 'flexShrink', 'layoutWidth', 'layoutHeight', 'alignSelf', 'flexExclude'] as const;
+
+/** Extract FlexItemConfig from props if any flex item props are present */
+function extractFlexItemConfig(props: Record<string, any>): FlexItemConfig | undefined {
+  let config: FlexItemConfig | undefined;
+  for (const key of FLEX_ITEM_PROPS) {
+    if (key in props) {
+      if (!config) config = {};
+      (config as any)[key] = props[key];
+    }
+  }
+  return config;
+}
+
+/** Apply flex item config to a child being added to a FlexContainer */
+function addChildToFlex(parent: FlexContainer, child: Container & { _flexConfig?: FlexItemConfig }): void {
+  const flexConfig = child._flexConfig;
+  if (flexConfig && Object.keys(flexConfig).length > 0) {
+    parent.addFlexChild(child, flexConfig);
+  } else {
+    parent.addChild(child);
+  }
+}
 
 function toPascalCase(str: string): string {
   return str.charAt(0).toUpperCase() + str.slice(1);
@@ -37,14 +64,29 @@ 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';
     }
 
+    // Store flex item config for when this child is added to a FlexContainer parent
+    const flexItemConfig = extractFlexItemConfig(props);
+    if (flexItemConfig) {
+      instance._flexConfig = { ...instance._flexConfig, ...flexItemConfig };
+    }
+
     return instance;
   },
 
@@ -55,11 +97,23 @@ const hostConfig: Reconciler.HostConfig<
   },
 
   appendInitialChild(parent, child) {
-    if (child instanceof Container) parent.addChild(child);
+    if (child instanceof Container) {
+      if (parent instanceof FlexContainer) {
+        addChildToFlex(parent, child);
+      } else {
+        parent.addChild(child);
+      }
+    }
   },
 
   appendChild(parent, child) {
-    if (child instanceof Container) parent.addChild(child);
+    if (child instanceof Container) {
+      if (parent instanceof FlexContainer) {
+        addChildToFlex(parent, child);
+      } else {
+        parent.addChild(child);
+      }
+    }
   },
 
   appendChildToContainer(container, child) {
@@ -97,7 +151,26 @@ 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);
+    }
+
+    // Update flex item config if parent is FlexContainer
+    const newFlexConfig = extractFlexItemConfig(newProps);
+    const oldFlexConfig = extractFlexItemConfig(oldProps);
+    if (newFlexConfig || oldFlexConfig) {
+      instance._flexConfig = { ...instance._flexConfig, ...newFlexConfig };
+      // Trigger parent relayout
+      if (instance.parent instanceof FlexContainer) {
+        instance.parent.updateLayout();
+      }
+    }
 
     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);
+  }
 }