@energy8platform/platform-core 0.16.0

package/dist/vite.esm.js

@@ -0,0 +1,176 @@
+// ─── DevBridge Plugin ────────────────────────────────────
+/**
+ * Vite plugin that auto-injects the DevBridge mock-host bootstrapper
+ * into the HTML during development, so the game can communicate with
+ * a mock casino host without manual setup.
+ *
+ * Pair with `luaPlugin` to also enable `.lua` raw imports and serve a
+ * Lua execution endpoint at POST /__lua-play.
+ */
+const VIRTUAL_ID = '/@dev-bridge-entry.js';
+function devBridgePlugin(configPath) {
+    let entrySrc = '';
+    let viteRoot = '';
+    let resolvedConfigPath = configPath;
+    return {
+        name: 'platform-core:dev-bridge',
+        apply: 'serve', // dev only
+        enforce: 'pre',
+        configResolved(config) {
+            viteRoot = config.root;
+            // Resolve relative config path against Vite root so the virtual
+            // module can import it with an absolute path.
+            if (configPath.startsWith('.')) {
+                resolvedConfigPath = config.root + '/' + configPath.replace(/^\.\//, '');
+            }
+        },
+        resolveId(id) {
+            if (id === VIRTUAL_ID)
+                return id;
+        },
+        load(id) {
+            if (id === VIRTUAL_ID) {
+                // This goes through Vite's pipeline so bare imports are resolved
+                return `
+import { DevBridge } from '@energy8platform/platform-core/dev-bridge';
+
+try {
+  const mod = await import('${resolvedConfigPath}');
+  const config = mod.default ?? mod.config ?? mod;
+  new DevBridge(config).start();
+} catch (e) {
+  console.warn('[DevBridge] Failed to load config:', e);
+}
+
+await import('${entrySrc}');
+`;
+            }
+        },
+        transformIndexHtml(html) {
+            // Find the app's entry module script (skip Vite internal /@... scripts)
+            const scriptRegex = /<script\s+type="module"\s+src="((?!\/@)[^"]+)"\s*>\s*<\/script>/;
+            const match = html.match(scriptRegex);
+            if (!match) {
+                console.warn('[DevBridge] Could not find entry module script in index.html');
+                return html;
+            }
+            entrySrc = match[1];
+            if (entrySrc.startsWith('.')) {
+                entrySrc = viteRoot + '/' + entrySrc.replace(/^\.\//, '');
+            }
+            else if (entrySrc.startsWith('/')) {
+                entrySrc = viteRoot + entrySrc;
+            }
+            return html.replace(match[0], `<script type="module" src="${VIRTUAL_ID}"></script>`);
+        },
+    };
+}
+// ─── Lua Plugin ─────────────────────────────────────────
+/**
+ * Vite plugin that:
+ * 1. Enables importing `.lua` files as raw strings with HMR
+ * 2. Runs a LuaEngine on the Vite dev server (Node.js) via POST /__lua-play
+ *
+ * fengari runs server-side only — no browser shims needed.
+ */
+function luaPlugin(configPath) {
+    let luaEngine = null;
+    let viteServer = null;
+    async function initEngine() {
+        if (!viteServer)
+            return;
+        try {
+            // Invalidate cached modules so HMR picks up changes
+            const root = viteServer.config.root;
+            const fullConfigPath = configPath.startsWith('.')
+                ? root + '/' + configPath.replace(/^\.\//, '')
+                : configPath;
+            // Invalidate the config module and its dependencies
+            const configMod = viteServer.moduleGraph.getModuleById(fullConfigPath);
+            if (configMod)
+                viteServer.moduleGraph.invalidateModule(configMod);
+            // ssrLoadModule handles TS transpilation and resolves all imports
+            const mod = await viteServer.ssrLoadModule(fullConfigPath);
+            const config = mod.default ?? mod.config ?? mod;
+            if (!config.luaScript || !config.gameDefinition) {
+                console.log('[LuaPlugin] No luaScript/gameDefinition in config — Lua server disabled');
+                luaEngine = null;
+                return;
+            }
+            // Load LuaEngine via SSR (fengari runs natively in Node.js)
+            const luaMod = await viteServer.ssrLoadModule('@energy8platform/platform-core/lua');
+            const { LuaEngine } = luaMod;
+            if (luaEngine)
+                luaEngine.destroy();
+            luaEngine = new LuaEngine({
+                script: config.luaScript,
+                gameDefinition: config.gameDefinition,
+                seed: config.luaSeed,
+            });
+            console.log('[LuaPlugin] LuaEngine initialized (server-side)');
+        }
+        catch (e) {
+            console.warn('[LuaPlugin] Failed to initialize LuaEngine:', e.message);
+            luaEngine = null;
+        }
+    }
+    return {
+        name: 'platform-core:lua',
+        apply: 'serve',
+        async configureServer(server) {
+            viteServer = server;
+            await initEngine();
+            // POST /__lua-play — execute Lua on the server
+            server.middlewares.use('/__lua-play', (req, res) => {
+                if (req.method !== 'POST') {
+                    res.statusCode = 405;
+                    res.end('Method Not Allowed');
+                    return;
+                }
+                let body = '';
+                req.on('data', (chunk) => { body += chunk; });
+                req.on('end', () => {
+                    try {
+                        if (!luaEngine) {
+                            res.statusCode = 503;
+                            res.setHeader('Content-Type', 'application/json');
+                            res.end(JSON.stringify({ error: 'LuaEngine not initialized' }));
+                            return;
+                        }
+                        const params = JSON.parse(body);
+                        const result = luaEngine.execute(params);
+                        res.statusCode = 200;
+                        res.setHeader('Content-Type', 'application/json');
+                        res.end(JSON.stringify(result));
+                    }
+                    catch (e) {
+                        res.statusCode = 500;
+                        res.setHeader('Content-Type', 'application/json');
+                        res.end(JSON.stringify({ error: e.message }));
+                    }
+                });
+            });
+        },
+        transform(code, id) {
+            if (id.endsWith('.lua')) {
+                return {
+                    code: `export default ${JSON.stringify(code)};`,
+                    map: null,
+                };
+            }
+        },
+        async handleHotUpdate({ file, server }) {
+            if (file.endsWith('.lua') || file.includes('dev.config')) {
+                console.log('[LuaPlugin] Reloading LuaEngine...');
+                // Invalidate all SSR modules so ssrLoadModule picks up fresh code
+                server.moduleGraph.invalidateAll();
+                await initEngine();
+                server.ws.send({ type: 'full-reload' });
+                return [];
+            }
+        },
+    };
+}
+
+export { devBridgePlugin, luaPlugin };
+//# sourceMappingURL=vite.esm.js.map

package/dist/vite.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.esm.js","sources":["../src/vite/index.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@energy8platform/platform-core",
+  "version": "0.16.0",
+  "description": "Energy8 platform core: Lua engine, DevBridge, RTP simulation, and SDK session orchestration. Renderer-agnostic — pair with any game framework (Pixi, Phaser, Three.js, custom).",
+  "type": "module",
+  "main": "./dist/index.cjs.js",
+  "module": "./dist/index.esm.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "platform-core-simulate": "./bin/simulate.ts"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.cjs.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./lua": {
+      "import": "./dist/lua.esm.js",
+      "require": "./dist/lua.cjs.js",
+      "types": "./dist/lua.d.ts"
+    },
+    "./simulation": {
+      "import": "./dist/simulation.esm.js",
+      "require": "./dist/simulation.cjs.js",
+      "types": "./dist/simulation.d.ts"
+    },
+    "./dev-bridge": {
+      "import": "./dist/dev-bridge.esm.js",
+      "require": "./dist/dev-bridge.cjs.js",
+      "types": "./dist/dev-bridge.d.ts"
+    },
+    "./vite": {
+      "import": "./dist/vite.esm.js",
+      "require": "./dist/vite.cjs.js",
+      "types": "./dist/vite.d.ts"
+    },
+    "./loading": {
+      "import": "./dist/loading.esm.js",
+      "require": "./dist/loading.cjs.js",
+      "types": "./dist/loading.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "bin/simulate.ts",
+    "scripts"
+  ],
+  "scripts": {
+    "simulate": "tsx bin/simulate.ts",
+    "build": "rollup -c rollup.config.mjs",
+    "dev": "rollup -c rollup.config.mjs -w",
+    "lint": "eslint src/ --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "postinstall": "node scripts/install-simulate.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@energy8platform/game-sdk": "^2.7.0",
+    "fengari": "^0.1.4",
+    "vite": "^5.0.0 || ^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@energy8platform/game-sdk": "^2.7.0",
+    "@rollup/plugin-typescript": "^12.1.0",
+    "@types/node": "^25.6.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "fengari": "^0.1.5",
+    "fengari-web": "^0.1.4",
+    "rollup": "^4.24.0",
+    "rollup-plugin-dts": "^6.1.0",
+    "tslib": "^2.8.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.0.0"
+  },
+  "keywords": [
+    "casino",
+    "energy8",
+    "lua",
+    "rtp-simulation",
+    "igaming"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/energy8platform/game-engine.git",
+    "directory": "packages/platform-core"
+  }
+}

package/scripts/install-simulate.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+
+/**
+ * Postinstall script: downloads the native simulation binary for the current
+ * platform from GitHub Releases. Falls back silently — the JS simulation
+ * will be used if the binary is unavailable.
+ */
+
+import { createWriteStream, chmodSync, existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { get } from 'https';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BIN_DIR = join(__dirname, '..', 'bin');
+
+// ─── Config ─────────────────────────────────────────────
+
+const REPO = 'energy8platform/game-engine';
+// Binary version — update this when new Go binaries are built and uploaded to GitHub Releases.
+// The binary is backwards-compatible: it runs any Lua script, so it doesn't need to match
+// the engine version exactly. Only bump when the Go simulate CLI itself changes.
+const BINARY_VERSION = '0.13.0';
+
+const PLATFORM_MAP = {
+  'darwin-arm64': 'simulate-darwin-arm64',
+  'darwin-x64': 'simulate-darwin-amd64',
+  'linux-x64': 'simulate-linux-amd64',
+  'linux-arm64': 'simulate-linux-arm64',
+  'win32-x64': 'simulate-windows-amd64.exe',
+};
+
+// ─── Main ───────────────────────────────────────────────
+
+async function main() {
+  const key = `${process.platform}-${process.arch}`;
+  const binaryName = PLATFORM_MAP[key];
+
+  if (!binaryName) {
+    console.log(`[simulate] No native binary available for ${key}, will use JS simulation.`);
+    return;
+  }
+
+  const dest = join(BIN_DIR, binaryName);
+
+  // Skip if already downloaded
+  if (existsSync(dest)) {
+    return;
+  }
+
+  const tag = `v${BINARY_VERSION}`;
+
+  const url = `https://github.com/${REPO}/releases/download/${tag}/${binaryName}`;
+
+  console.log(`[simulate] Downloading native binary for ${key}...`);
+
+  try {
+    if (!existsSync(BIN_DIR)) {
+      mkdirSync(BIN_DIR, { recursive: true });
+    }
+    await download(url, dest);
+    chmodSync(dest, 0o755);
+    console.log(`[simulate] Installed ${binaryName}`);
+  } catch (err) {
+    // Non-fatal — JS simulation is the fallback
+    console.log(`[simulate] Could not download native binary: ${err.message}`);
+    console.log(`[simulate] Will use JS simulation instead.`);
+  }
+}
+
+// ─── Download with redirect following ───────────────────
+
+function download(url, dest, redirects = 5) {
+  return new Promise((resolve, reject) => {
+    if (redirects <= 0) {
+      return reject(new Error('Too many redirects'));
+    }
+
+    get(url, { headers: { 'User-Agent': 'game-engine-postinstall' } }, (res) => {
+      // Follow redirects (GitHub sends 302 to S3)
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        res.resume();
+        return download(res.headers.location, dest, redirects - 1).then(resolve, reject);
+      }
+
+      if (res.statusCode !== 200) {
+        res.resume();
+        return reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+      }
+
+      const file = createWriteStream(dest);
+      res.pipe(file);
+      file.on('finish', () => file.close(resolve));
+      file.on('error', reject);
+    }).on('error', reject);
+  });
+}
+
+main().catch(() => {
+  // Never fail the install
+});

package/src/EventEmitter.ts

@@ -0,0 +1,55 @@
+/**
+ * Minimal typed event emitter — internal utility for platform-core.
+ *
+ * Supports `void` event types — events that carry no data can be emitted
+ * without arguments: `emitter.emit('eventName')`.
+ *
+ * Mirrors the EventEmitter shipped from game-engine's core, copied here
+ * so platform-core has no upward dependency on game-engine.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export class EventEmitter<TEvents extends {}> {
+  private listeners = new Map<keyof TEvents, Set<(data: any) => void>>();
+
+  on<K extends keyof TEvents>(event: K, handler: (data: TEvents[K]) => void): this {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, new Set());
+    }
+    this.listeners.get(event)!.add(handler);
+    return this;
+  }
+
+  once<K extends keyof TEvents>(event: K, handler: (data: TEvents[K]) => void): this {
+    const wrapper = (data: TEvents[K]) => {
+      this.off(event, wrapper);
+      handler(data);
+    };
+    return this.on(event, wrapper);
+  }
+
+  off<K extends keyof TEvents>(event: K, handler: (data: TEvents[K]) => void): this {
+    this.listeners.get(event)?.delete(handler);
+    return this;
+  }
+
+  emit<K extends keyof TEvents>(
+    ...args: TEvents[K] extends void ? [event: K] : [event: K, data: TEvents[K]]
+  ): void {
+    const [event, data] = args as [K, TEvents[K]];
+    const handlers = this.listeners.get(event);
+    if (handlers) {
+      for (const handler of handlers) {
+        handler(data);
+      }
+    }
+  }
+
+  removeAllListeners(event?: keyof TEvents): this {
+    if (event) {
+      this.listeners.delete(event);
+    } else {
+      this.listeners.clear();
+    }
+    return this;
+  }
+}

package/src/PlatformSession.ts

@@ -0,0 +1,156 @@
+import { CasinoGameSDK } from '@energy8platform/game-sdk';
+import type {
+  InitData,
+  PlayParams,
+  PlayResultData,
+  BalanceData,
+} from '@energy8platform/game-sdk';
+import { DevBridge, type DevBridgeConfig } from './dev-bridge/DevBridge';
+import { EventEmitter } from './EventEmitter';
+
+/**
+ * Options for {@link createPlatformSession}.
+ */
+export interface PlatformSessionConfig {
+  /**
+   * Optional DevBridge mock-host config. When provided, a DevBridge is started
+   * in-process and the SDK connects to it via in-memory channel — no real
+   * casino backend required. Use this for local development and offline
+   * testing.
+   */
+  dev?: DevBridgeConfig;
+
+  /**
+   * SDK configuration. Pass an options object, or `false` to skip SDK
+   * initialization entirely (no host communication, used by tests and
+   * head-less simulation).
+   */
+  sdk?: SDKOptions | false;
+}
+
+export interface SDKOptions {
+  parentOrigin?: string;
+  timeout?: number;
+  debug?: boolean;
+  /** Use in-memory channel instead of postMessage (no iframe required) */
+  devMode?: boolean;
+}
+
+/**
+ * Events forwarded from the underlying SDK by the PlatformSession.
+ */
+export interface PlatformSessionEvents {
+  /** Player balance changed (forwarded from CasinoGameSDK) */
+  balanceUpdate: BalanceData;
+  /** SDK or transport error */
+  error: Error;
+}
+
+/**
+ * Lifecycle wrapper around CasinoGameSDK + (optional) DevBridge.
+ *
+ * Use `createPlatformSession()` to construct one. The session owns the SDK
+ * handshake, optional in-process dev host, and a typed event bus that
+ * forwards SDK events upward.
+ *
+ * Phaser/Three/custom-engine consumers use this directly:
+ *
+ * ```ts
+ * const session = await createPlatformSession({
+ *   dev: { luaScript, gameDefinition, balance: 10000, currency: 'EUR' },
+ * });
+ *
+ * session.on('balanceUpdate', ({ balance }) => updateHud(balance));
+ * const result = await session.play({ action: 'spin', bet: 1 });
+ * ```
+ */
+export class PlatformSession extends EventEmitter<PlatformSessionEvents> {
+  /** SDK instance, or null when `sdk: false` was passed. */
+  public readonly sdk: CasinoGameSDK | null;
+  /** Data returned by the SDK handshake, or null in offline mode. */
+  public readonly initData: InitData | null;
+  /** DevBridge mock host, or null when `dev` was not provided. */
+  public readonly devBridge: DevBridge | null;
+
+  constructor(opts: {
+    sdk: CasinoGameSDK | null;
+    initData: InitData | null;
+    devBridge: DevBridge | null;
+  }) {
+    super();
+    this.sdk = opts.sdk;
+    this.initData = opts.initData;
+    this.devBridge = opts.devBridge;
+  }
+
+  /** Current player balance from the SDK (0 if no SDK). */
+  get balance(): number {
+    return this.sdk?.balance ?? 0;
+  }
+
+  /** Current currency from the SDK ('USD' fallback). */
+  get currency(): string {
+    return this.sdk?.currency ?? 'USD';
+  }
+
+  /**
+   * Send a play request through the SDK and resolve with the host result.
+   * Throws if the session was constructed with `sdk: false`.
+   */
+  async play(params: PlayParams): Promise<PlayResultData> {
+    if (!this.sdk) {
+      throw new Error('[PlatformSession] play() requires an active SDK (constructed with sdk: false)');
+    }
+    return this.sdk.play(params);
+  }
+
+  /** Tear down the SDK, DevBridge, and clear listeners. */
+  destroy(): void {
+    this.sdk?.destroy();
+    this.devBridge?.destroy();
+    this.removeAllListeners();
+  }
+}
+
+/**
+ * Build a PlatformSession.
+ *
+ * Steps performed:
+ *   1. If `config.dev` is set → start a DevBridge with those options
+ *   2. Unless `config.sdk === false` → construct CasinoGameSDK and await its handshake
+ *   3. Forward `error` and `balanceUpdate` events from the SDK
+ */
+export async function createPlatformSession(
+  config: PlatformSessionConfig = {},
+): Promise<PlatformSession> {
+  // 1. Optionally start the DevBridge mock host
+  let devBridge: DevBridge | null = null;
+  if (config.dev) {
+    devBridge = new DevBridge(config.dev);
+    devBridge.start();
+  }
+
+  // 2. Initialize SDK (unless explicitly disabled)
+  let sdk: CasinoGameSDK | null = null;
+  let initData: InitData | null = null;
+
+  if (config.sdk !== false) {
+    const sdkOpts = typeof config.sdk === 'object' ? config.sdk : {};
+    sdk = new CasinoGameSDK(sdkOpts);
+    initData = await sdk.ready();
+  }
+
+  // 3. Build the session and wire SDK event forwarding
+  const session = new PlatformSession({ sdk, initData, devBridge });
+
+  if (sdk) {
+    sdk.on('error', (err: Error) => {
+      session.emit('error', err);
+    });
+    sdk.on('balanceUpdate', (data: BalanceData) => {
+      session.emit('balanceUpdate', data);
+    });
+  }
+
+  return session;
+}