@energy8platform/game-engine 0.11.0 → 0.13.0

package/src/lua/NativeSimulationRunner.ts

@@ -0,0 +1,367 @@
+import { spawn } from 'child_process';
+import { writeFile, unlink } from 'fs/promises';
+import { join, dirname } from 'path';
+import { tmpdir } from 'os';
+import { randomBytes } from 'crypto';
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import type { GameDefinition, SimulationResult } from './types';
+
+// ─── Types ──────────────────────────────────────────────
+
+export interface NativeSimulationConfig {
+  /** Path to native simulation binary */
+  binaryPath: string;
+  /** Lua script source code */
+  script: string;
+  /** Platform game definition */
+  gameDefinition: GameDefinition;
+  /** Number of iterations */
+  iterations: number;
+  /** Bet amount */
+  bet: number;
+  /** Action to simulate (default: auto-detect by binary) */
+  action?: string;
+  /** Action params (buy_bonus, ante_bet, etc.) */
+  params?: Record<string, unknown>;
+  /** Progress callback */
+  onProgress?: (completed: number, total: number) => void;
+}
+
+export interface StageStats {
+  totalWin: number;
+  spinCount: number;
+  hitCount: number;
+  maxWin: number;
+  rtp: number;
+  perSpinRtp: number;
+  hitFrequency: number;
+  avgWin: number;
+}
+
+export interface DistributionBucket {
+  label: string;
+  count: number;
+  pct: number;
+}
+
+export interface NativeSimulationResult extends SimulationResult {
+  /** Iterations per second */
+  speed?: number;
+  /** Number of parallel workers used */
+  workersUsed?: number;
+  /** Per-stage breakdown */
+  perStage?: Record<string, StageStats>;
+  /** Win distribution histogram */
+  winDistribution?: DistributionBucket[];
+}
+
+// ─── Go JSON output shape (snake_case) ──────────────────
+
+interface GoSimulationOutput {
+  game_id: string;
+  speed: number;
+  total_rtp: number;
+  hit_frequency: number;
+  max_win: number;
+  max_win_hits: number;
+  total_bet: number;
+  total_win: number;
+  iterations: number;
+  workers_used: number;
+  duration_sec: number;
+  bonus_triggered: number;
+  bonus_spins_total: number;
+  per_stage_stats?: Record<string, {
+    total_win: number;
+    spin_count: number;
+    hit_count: number;
+    max_win: number;
+    rtp: number;
+    per_spin_rtp: number;
+    hit_frequency: number;
+    avg_win: number;
+  }>;
+  win_distribution?: Array<{
+    label: string;
+    count: number;
+    pct: number;
+  }>;
+}
+
+// ─── Runner ─────────────────────────────────────────────
+
+export class NativeSimulationRunner {
+  private config: NativeSimulationConfig;
+
+  constructor(config: NativeSimulationConfig) {
+    this.config = config;
+  }
+
+  async run(): Promise<NativeSimulationResult> {
+    const { binaryPath, script, gameDefinition, iterations, bet, action, params } = this.config;
+    const id = randomBytes(8).toString('hex');
+    const tmpDir = tmpdir();
+    const luaPath = join(tmpDir, `sim-${id}.lua`);
+    const configPath = join(tmpDir, `sim-${id}.json`);
+
+    try {
+      // Write temp files
+      await Promise.all([
+        writeFile(luaPath, script, 'utf-8'),
+        writeFile(configPath, JSON.stringify({ ...gameDefinition, script_path: luaPath }), 'utf-8'),
+      ]);
+
+      // Build CLI args
+      const args = [
+        '-config', configPath,
+        '-iterations', String(iterations),
+        '-bet', String(bet),
+        '-format', 'json',
+      ];
+      if (action) {
+        args.push('-action', action);
+      }
+      if (params && Object.keys(params).length > 0) {
+        args.push('-params', JSON.stringify(params));
+      }
+
+      // Execute binary
+      const output = await this.exec(binaryPath, args);
+
+      // Parse JSON output
+      const json: GoSimulationOutput = JSON.parse(output);
+      return mapGoResult(json);
+    } finally {
+      // Cleanup temp files
+      await Promise.allSettled([unlink(luaPath), unlink(configPath)]);
+    }
+  }
+
+  private exec(binary: string, args: string[]): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const child = spawn(binary, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+
+      let stdout = '';
+      let stderr = '';
+
+      child.stdout.on('data', (chunk: Buffer) => {
+        stdout += chunk.toString();
+      });
+
+      child.stderr.on('data', (chunk: Buffer) => {
+        stderr += chunk.toString();
+      });
+
+      child.on('error', (err) => {
+        reject(new Error(`Failed to execute simulation binary: ${err.message}`));
+      });
+
+      child.on('close', (code) => {
+        if (code !== 0) {
+          reject(new Error(`Simulation binary exited with code ${code}: ${stderr.trim()}`));
+        } else {
+          resolve(stdout);
+        }
+      });
+    });
+  }
+}
+
+// ─── Result mapping ─────────────────────────────────────
+
+function mapGoResult(json: GoSimulationOutput): NativeSimulationResult {
+  const baseStage = json.per_stage_stats?.base_game;
+  const baseGameRtp = baseStage?.rtp ?? 0;
+  const baseGameWin = baseStage?.total_win ?? 0;
+
+  const perStage = json.per_stage_stats
+    ? Object.fromEntries(
+        Object.entries(json.per_stage_stats).map(([key, s]) => [
+          key,
+          {
+            totalWin: s.total_win,
+            spinCount: s.spin_count,
+            hitCount: s.hit_count,
+            maxWin: s.max_win,
+            rtp: s.rtp,
+            perSpinRtp: s.per_spin_rtp,
+            hitFrequency: s.hit_frequency,
+            avgWin: s.avg_win,
+          },
+        ]),
+      )
+    : undefined;
+
+  return {
+    gameId: json.game_id,
+    action: 'spin',
+    iterations: json.iterations,
+    durationMs: Math.round(json.duration_sec * 1000),
+    totalRtp: json.total_rtp,
+    baseGameRtp,
+    bonusRtp: json.total_rtp - baseGameRtp,
+    hitFrequency: json.hit_frequency,
+    maxWin: json.max_win,
+    maxWinHits: json.max_win_hits,
+    bonusTriggered: json.bonus_triggered,
+    bonusSpinsPlayed: json.bonus_spins_total,
+    speed: json.speed,
+    workersUsed: json.workers_used,
+    perStage,
+    winDistribution: json.win_distribution,
+    _raw: {
+      totalWagered: json.total_bet,
+      totalWon: json.total_win,
+      baseGameWin,
+      bonusWin: json.total_win - baseGameWin,
+      hits: json.iterations > 0 ? Math.round((json.hit_frequency * json.iterations) / 100) : 0,
+    },
+  };
+}
+
+// ─── Binary discovery ───────────────────────────────────
+
+/**
+ * Search for a native simulation binary in standard locations.
+ * Returns the absolute path if found, null otherwise.
+ */
+export function findNativeBinary(baseDir?: string): string | null {
+  // 1. Explicit env var
+  const envPath = process.env.SIMULATE_BINARY;
+  if (envPath && isExecutable(envPath)) {
+    return envPath;
+  }
+
+  const platform = process.platform; // darwin, linux, win32
+  const nodeArch = process.arch; // arm64, x64
+  const goArch = nodeArch === 'x64' ? 'amd64' : nodeArch;
+  const goPlatform = platform === 'win32' ? 'windows' : platform;
+  const ext = platform === 'win32' ? '.exe' : '';
+
+  const names = [
+    `simulate-${goPlatform}-${goArch}${ext}`,
+    `simulation-${goPlatform}-${goArch}${ext}`,
+    `simulate${ext}`,
+    `simulation${ext}`,
+  ];
+
+  // Search directories: user's project first, then this package's bin/
+  const searchDirs: string[] = [];
+  if (baseDir) searchDirs.push(baseDir);
+
+  // This package's root (where postinstall downloads the binary)
+  try {
+    const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+    if (!searchDirs.includes(pkgRoot)) searchDirs.push(pkgRoot);
+  } catch {
+    // fallback for CJS
+    if (typeof __dirname !== 'undefined') {
+      const pkgRoot = join(__dirname, '..');
+      if (!searchDirs.includes(pkgRoot)) searchDirs.push(pkgRoot);
+    }
+  }
+
+  for (const dir of searchDirs) {
+    for (const name of names) {
+      const candidate = join(dir, 'bin', name);
+      if (isExecutable(candidate)) return candidate;
+    }
+  }
+
+  // Check $PATH
+  for (const bin of ['simulate', 'simulation']) {
+    try {
+      const cmd = platform === 'win32' ? `where ${bin}` : `which ${bin}`;
+      const result = execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'] }).trim();
+      if (result) return result.split('\n')[0];
+    } catch {
+      // not found
+    }
+  }
+
+  return null;
+}
+
+function isExecutable(path: string): boolean {
+  try {
+    const { accessSync, constants } = require('fs');
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ─── Extended formatting ────────────────────────────────
+
+/** Format a NativeSimulationResult with per-stage and distribution data */
+export function formatNativeResult(result: NativeSimulationResult): string {
+  const lines: string[] = [
+    '',
+    '--- Simulation Results ---',
+    `Game: ${result.gameId}`,
+    `Iterations: ${result.iterations.toLocaleString()}`,
+    `Duration: ${(result.durationMs / 1000).toFixed(1)}s`,
+  ];
+
+  if (result.speed) {
+    lines.push(`Speed: ${Math.round(result.speed).toLocaleString()} iterations/sec`);
+  }
+  if (result.workersUsed) {
+    lines.push(`Workers: ${result.workersUsed}`);
+  }
+
+  lines.push(
+    '',
+    '--- Total ---',
+    `Total RTP: ${result.totalRtp.toFixed(2)}%`,
+    `Base Game RTP: ${result.baseGameRtp.toFixed(2)}%`,
+    `Bonus RTP: ${result.bonusRtp.toFixed(2)}%`,
+    `Hit Frequency: ${result.hitFrequency.toFixed(2)}%`,
+    `Max Win: ${result.maxWin.toFixed(2)}x`,
+    `Max Win Cap Hits: ${result.maxWinHits}`,
+  );
+
+  if (result.bonusTriggered > 0) {
+    const frequency = Math.round(result.iterations / result.bonusTriggered);
+    lines.push(
+      '',
+      '--- Bonus Stats ---',
+      `Bonus Triggered: ${result.bonusTriggered.toLocaleString()} (1 in ${frequency} spins)`,
+      `Bonus Spins Total: ${result.bonusSpinsPlayed.toLocaleString()}`,
+    );
+  }
+
+  // Per-stage breakdown
+  if (result.perStage && Object.keys(result.perStage).length > 0) {
+    lines.push('', '--- Per-Stage Breakdown ---');
+    const header = 'Stage                | Spins      | RTP (contrib) | Per-Spin RTP | Hit Freq  | Avg Win   | Max Win';
+    lines.push(header);
+    lines.push('-'.repeat(header.length));
+
+    for (const [stage, stats] of Object.entries(result.perStage)) {
+      lines.push(
+        `${stage.padEnd(20)} | ${String(stats.spinCount).padStart(10)} | ` +
+        `${stats.rtp.toFixed(2).padStart(12)}% | ` +
+        `${stats.perSpinRtp.toFixed(2).padStart(11)}% | ` +
+        `${stats.hitFrequency.toFixed(2).padStart(8)}% | ` +
+        `${stats.avgWin.toFixed(3).padStart(8)}x | ` +
+        `${stats.maxWin.toFixed(2).padStart(8)}x`,
+      );
+    }
+  }
+
+  // Win distribution
+  if (result.winDistribution && result.winDistribution.length > 0) {
+    lines.push('', '--- Win Distribution ---');
+    for (const bucket of result.winDistribution) {
+      const bar = '█'.repeat(Math.round(bucket.pct / 2));
+      lines.push(
+        `${bucket.label.padEnd(10)} ${String(bucket.count).padStart(10)} (${bucket.pct.toFixed(2).padStart(6)}%) ${bar}`,
+      );
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/lua/index.ts

@@ -5,6 +5,13 @@ export { SessionManager } from './SessionManager';
 export { PersistentState } from './PersistentState';
 export { SimulationRunner, formatSimulationResult } from './SimulationRunner';
 export { ParallelSimulationRunner } from './ParallelSimulationRunner';
+export { NativeSimulationRunner, findNativeBinary, formatNativeResult } from './NativeSimulationRunner';
+export type {
+  NativeSimulationConfig,
+  NativeSimulationResult,
+  StageStats,
+  DistributionBucket,
+} from './NativeSimulationRunner';
 export type {
   GameDefinition,
   ActionDefinition,

package/src/react/applyProps.ts

@@ -1,4 +1,6 @@
 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 ────────────────────────────────
 
@@ -11,7 +13,7 @@ export function extractConfig(props: Record<string, any>): Record<string, any> {
   const config: Record<string, any> = {};
 
   for (const key in props) {
-    if (RESERVED.has(key) || isEventProp(key)) continue;
+    if (RESERVED.has(key) || FLEX_ITEM_PROPS.has(key) || isEventProp(key)) continue;
 
     if (key.includes('-')) {
       const parts = key.split('-');
@@ -41,7 +43,7 @@ export function diffConfig(
 
   // New or changed props
   for (const key in newProps) {
-    if (RESERVED.has(key) || isEventProp(key)) continue;
+    if (RESERVED.has(key) || FLEX_ITEM_PROPS.has(key) || isEventProp(key)) continue;
     if (newProps[key] !== oldProps[key]) {
       if (key.includes('-')) {
         const parts = key.split('-');
@@ -149,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) {
@@ -169,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

@@ -17,6 +17,7 @@ import { extend } from './catalogue';
 import {
   Button, Label, Panel, FlexContainer, ProgressBar,
   ScrollContainer, Modal, Toast, BalanceDisplay, WinDisplay, Layout,
+  Slider, Toggle,
 } from '../ui';
 
 /**
@@ -60,6 +61,7 @@ export function extendUIElements(): void {
   extend({
     Button, Label, Panel, FlexContainer, ProgressBar,
     ScrollContainer, Modal, Toast, BalanceDisplay, WinDisplay, Layout,
+    Slider, Toggle,
   });
 }
 

package/src/react/jsx.d.ts

@@ -14,7 +14,7 @@ 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 { FlexContainerConfig, FlexItemConfig, AlignSelf } from '../ui/FlexContainer';
 import type { ProgressBarConfig } from '../ui/ProgressBar';
 import type { ScrollContainerConfig } from '../ui/ScrollContainer';
 import type { ModalConfig } from '../ui/Modal';
@@ -22,6 +22,8 @@ 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 ─────────────────────────────────────────
 
@@ -80,6 +82,14 @@ interface BaseProps extends PixiEventProps {
 
   // 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 ───────────────────────────
@@ -189,6 +199,21 @@ 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 {
@@ -215,6 +240,8 @@ declare global {
       balanceDisplay: BalanceDisplayComponentProps;
       winDisplay: WinDisplayComponentProps;
       layout: LayoutComponentProps;
+      slider: SliderComponentProps;
+      toggle: ToggleComponentProps;
     }
   }
 }

package/src/react/reconciler.ts

@@ -3,6 +3,33 @@ import { DefaultEventPriority } from 'react-reconciler/constants';
 import { Container } from 'pixi.js';
 import { catalogue } from './catalogue';
 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);
@@ -54,6 +81,12 @@ const hostConfig: Reconciler.HostConfig<
       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;
   },
 
@@ -64,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) {
@@ -116,6 +161,17 @@ const hostConfig: Reconciler.HostConfig<
       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';
     }