@energy8platform/game-engine 0.15.1 → 0.16.0

package/README.md

@@ -1,6 +1,8 @@
 # @energy8platform/game-engine
 
-A casino game engine built on [PixiJS v8](https://pixijs.com/) and [@energy8platform/game-sdk](https://github.com/energy8platform/game-sdk). Provides scene management, responsive scaling, audio, state machines, tweens, UI components, Lua scripting, and React integration for developing slot machines, card games, and other iGaming titles.
+A casino game engine built on [PixiJS v8](https://pixijs.com/) and [@energy8platform/game-sdk](https://github.com/energy8platform/game-sdk). Provides scene management, responsive scaling, audio, state machines, tweens, UI components, and React integration for developing slot machines, card games, and other iGaming titles.
+
+> **Building on a different renderer?** The platform-specific bits (Lua engine, RTP simulation, DevBridge, branded loading screen, SDK session orchestration) live in the renderer-agnostic [`@energy8platform/platform-core`](../platform-core/README.md). `game-engine` is the Pixi front-end on top of it; Phaser, Three.js, and custom-engine consumers depend only on `platform-core`.
 
 ---
 
@@ -31,14 +33,15 @@ A casino game engine built on [PixiJS v8](https://pixijs.com/) and [@energy8plat
 ## Quick Start
 
 ```bash
-# Install dependencies
+# Install dependencies. platform-core comes in transitively as a
+# regular dependency of game-engine — you don't list it explicitly.
 npm install pixi.js @energy8platform/game-sdk @energy8platform/game-engine
 
 # Optional peer dependencies
 npm install @pixi/sound                           # Audio
 npm install @esotericsoftware/spine-pixi-v8       # Spine animations
 npm install react react-dom react-reconciler      # React integration
-npm install fengari                               # Lua engine
+npm install fengari                               # Lua engine (in dev/sim)
 ```
 
 ```typescript
@@ -91,7 +94,9 @@ bootstrap();
 | `@esotericsoftware/spine-pixi-v8` | `~4.2.0` | Optional — Spine animations |
 | `react`, `react-dom` | `>=18.0.0` | Optional — ReactScene |
 | `react-reconciler` | `>=0.29.0` | Optional — ReactScene (custom PixiJS reconciler) |
-| `fengari` | `^0.1.4` | Optional — Lua engine |
+| `fengari` | `^0.1.4` | Optional — Lua engine (peer of `platform-core`, install only if you use Lua locally) |
+
+`@energy8platform/platform-core` is a regular dependency (not a peer) — npm pulls it in automatically when you install `game-engine`.
 
 ### Sub-path Exports
 
@@ -710,6 +715,8 @@ export default defineGameConfig({
 
 Runs platform Lua game scripts in the browser via `fengari` (Lua 5.3, pure JS). Replicates server-side execution for development — no backend required.
 
+> The Lua engine, simulation runners, and game-definition types ship from [`@energy8platform/platform-core`](../platform-core/README.md). `game-engine` re-exports them at `@energy8platform/game-engine/lua` so existing import paths keep working.
+
 ### DevBridge Integration (recommended)
 
 ```typescript
@@ -764,20 +771,20 @@ engine.destroy();
 
 ### RTP Simulation (CLI)
 
-Run the same Lua script from `dev.config.ts` through millions of iterations to verify math:
+Run the same Lua script from `dev.config.ts` through millions of iterations to verify math. The CLI ships with [`@energy8platform/platform-core`](../platform-core/README.md) (a transitive dep when you install `game-engine`):
 
 ```bash
 # Regular spins (1M iterations, default)
-npx game-engine-simulate
+npx platform-core-simulate
 
 # Buy bonus simulation
-npx game-engine-simulate --action buy_bonus
+npx platform-core-simulate --action buy_bonus
 
-# Ante bet
-npx game-engine-simulate --params '{"ante_bet":true}'
+# Ante bet (v5: regular action, not a params flag)
+npx platform-core-simulate --action ante_spin
 
 # Custom parameters
-npx game-engine-simulate --iterations 5000000 --bet 1 --seed 42 --config ./dev.config.ts
+npx platform-core-simulate --iterations 5000000 --bet 1 --seed 42 --config ./dev.config.ts
 ```
 
 Output matches the platform's server-side simulation format:
@@ -824,7 +831,7 @@ console.log(formatSimulationResult(result));
 
 ## DevBridge
 
-Simulates a casino host for local development using SDK's `Bridge` in `devMode` (shared `MemoryChannel`, no iframe needed).
+Simulates a casino host for local development using SDK's `Bridge` in `devMode` (shared `MemoryChannel`, no iframe needed). DevBridge is implemented in [`@energy8platform/platform-core`](../platform-core/README.md); the imports below resolve through the re-export shim shipped by `game-engine`.
 
 ```typescript
 import { DevBridge } from '@energy8platform/game-engine/debug';
@@ -847,10 +854,13 @@ bridge.setBalance(5000);
 bridge.destroy();
 ```
 
-**Handled messages:** `GAME_READY`, `PLAY_REQUEST`, `PLAY_RESULT_ACK`, `GET_BALANCE`, `GET_STATE`, `OPEN_DEPOSIT`.
+**Handled (in):** `GAME_READY`, `PLAY_REQUEST`, `PLAY_RESULT_ACK`, `GET_BALANCE`, `GET_STATE`, `OPEN_DEPOSIT`.
+**Emitted (out):** `INIT`, `PLAY_RESULT`, `PLAY_ERROR`, `BALANCE_UPDATE`, `STATE_RESPONSE`.
 
 > With the Vite plugin (`devBridge: true`), DevBridge is injected automatically before your app entry point.
 
+> **Error codes & session contract.** In Lua mode, DevBridge emits the same `PLAY_ERROR` codes the platform does (`INVALID_AMOUNT`, `INSUFFICIENT_FUNDS`, `ACTIVE_SESSION_EXISTS`, `NO_ACTIVE_SESSION`, `SESSION_EXPIRED`, `ENGINE_ERROR`, …) — see the [platform-core DevBridge section](../platform-core/README.md#platform-parity-behavior-lua-mode) for the full table and the contract details (server-generated round IDs, `session.history`, `STATE_RESPONSE` shape, `creditPending` semantics).
+
 ---
 
 ## React Integration

package/dist/assets.d.ts

@@ -1,16 +1,5 @@
-interface AssetEntry {
-    alias: string;
-    src: string | string[];
-    /** Optional data to pass to the loader */
-    data?: Record<string, unknown>;
-}
-interface AssetBundle {
-    name: string;
-    assets: AssetEntry[];
-}
-interface AssetManifest {
-    bundles: AssetBundle[];
-}
+import { AssetManifest } from '@energy8platform/platform-core';
+export { AssetBundle, AssetEntry, AssetManifest } from '@energy8platform/platform-core';
 
 /**
  * Manages game asset loading with progress tracking, bundle support, and
@@ -94,4 +83,3 @@ declare class AssetManager {
 }
 
 export { AssetManager };
-export type { AssetBundle, AssetEntry, AssetManifest };

package/dist/core.cjs.js

@@ -1,7 +1,8 @@
 'use strict';
 
 var pixi_js = require('pixi.js');
-var gameSdk = require('@energy8platform/game-sdk');
+var platformCore = require('@energy8platform/platform-core');
+var loading = require('@energy8platform/platform-core/loading');
 
 // ─── Scale Modes ───────────────────────────────────────────
 var ScaleMode;
@@ -1429,81 +1430,12 @@ class Scene {
     }
 }
 
-/**
- * Shared Energy8 SVG logo with an embedded loader bar.
- *
- * The loader bar fill is controlled via a `<clipPath>` whose `<rect>` width
- * is animatable. Different consumers customise gradient IDs and the clip
- * element's ID/class to avoid collisions when both CSSPreloader and
- * LoadingScene appear in the same DOM.
- */
-/** SVG path data for the Energy8 wordmark — reused across loaders */
-const WORDMARK_PATHS = `
-  <path d="m241 81.75h-19.28c-1.77 0-6.73 4.98-7.43 6.99l-4.36 12.22c-0.49 1.37 0.05 2.92 1.06 4.32-2.07 1.19-3.69 3.08-4.36 5.43l-3.25 10.41c-0.86 2.89 2.39 6.63 4.31 6.63h19.28c1.96 0 7.4-5.56 7.96-7.51l2.96-10.22c0.63-2.25 0.1-3.98-1.22-4.99 2.55-1.56 3.86-4.14 4.55-6.31l2.77-9.31c0.74-2.57-1.37-7.66-2.99-7.66zm-13.36 28.31-2.27 7.03h-8.28l2.58-8.28h8.28l-0.31 1.25zm4.06-16.97-2.11 6.7h-7.04l2.25-7.34h7.26l-0.36 0.64z" fill="url(#GID0)"/>
-  <path d="m202.5 81.75-9.31 14.97-2.32-14.97h-11.82l4.32 25.15-0.57 4.91-8.64 26.44 15.31-12.76 5.63-16.48 19.96-27.26h-12.56z" fill="url(#GID1)"/>
-  <path d="m174.2 81.75h-19.78l-5.75 5.16-10.79 33.2c-0.77 2.53 2.48 6.93 4.87 6.93h17.38c2.63 0 7.85-5.34 8.32-6.83l5.37-18.14h-15.17l-2.2 7.64h3.78l-2.25 7.2h-8.01l7.1-25.52h7.58l-1.48 8.4 12.78-5.98c1.28-0.63 1.97-3.99 1.61-6.61-0.36-2.34-1.64-5.45-3.36-5.45z" fill="url(#GID2)"/>
-  <path d="m140.6 81.75h-70.6l-5.36 19.37-4.26-19.37h-46.76l2.95 5.88-10.58 39.28h26.84l2.95-9.52-15.63-0.13 2.55-8.34h8.74l8.47-9.81h-14.61l2.11-7.3h15.47l2.54-8.71 2.58 4.74-11.4 39.07h11.05l6.46-21.49 8.84 36.33 19.18-55.67-1.83-3.36 3.68 4.09-12.07 40.1h28.18l3.39-10.31h-17.01l2.67-8.03h9.98l7.58-9.52h-14.28l1.93-6.6h14.61l3.25-9.73 2.81 5.12-11.3 38.89h11.05l5.23-17.81h1.62l1.48 17.6h10.69l-1.48-16.81c4.75-1.28 7.52-5.9 8.64-9.81l2.95-11.3c0.86-2.73-1.43-6.85-3.3-6.85zm-9.8 17.3h-8.69l2.54-7.84h8.35l-2.2 7.84z" fill="url(#GID3)"/>
-  <path d="m205.9 148.9h-122.6l-2.61-3.12h-32.4l-2.51 3.12h-1.59c-5.34 0-7.94 4.88-7.94 7.65v0.03c0 4.2 3.55 7.6 7.74 7.6h103.6l2.11 3.12h36.09l1.82-3.12h18.3c5.25 0 6.64-5.3 6.64-7.35v-0.25c0-4.23-2.9-7.68-6.64-7.68zm-0.7 12.83h-160.6c-3.69 0-6.11-2.58-6.11-5.47v-0.03c0-2.89 2.1-5.47 5.61-5.47h161.1c3.45 0 4.89 3.12 4.89 5.65v0.17c0 2.57-2.11 5.15-4.89 5.15z" fill="url(#GID4)"/>`;
-/** Gradient definitions template (gradient IDs are replaced per-consumer) */
-const GRADIENT_DEFS = `
-    <linearGradient id="GID0" x1="223.7" x2="223.7" y1="81.75" y2="127.8" gradientUnits="userSpaceOnUse">
-      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
-    </linearGradient>
-    <linearGradient id="GID1" x1="194.6" x2="194.6" y1="81.75" y2="138.3" gradientUnits="userSpaceOnUse">
-      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
-    </linearGradient>
-    <linearGradient id="GID2" x1="157.8" x2="157.8" y1="81.75" y2="127" gradientUnits="userSpaceOnUse">
-      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
-    </linearGradient>
-    <linearGradient id="GID3" x1="79.96" x2="79.96" y1="81.75" y2="141.8" gradientUnits="userSpaceOnUse">
-      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
-    </linearGradient>
-    <linearGradient id="GID4" x1="36.18" x2="212.5" y1="156.6" y2="156.6" gradientUnits="userSpaceOnUse">
-      <stop stop-color="#316FB0"/><stop stop-color="#1FCDE6" offset=".5"/><stop stop-color="#29FEE7" offset="1"/>
-    </linearGradient>
-    <linearGradient id="GID5" x1="40.27" x2="208.2" y1="156.4" y2="156.4" gradientUnits="userSpaceOnUse">
-      <stop stop-color="#316FB0"/><stop stop-color="#1FCDE6" offset=".5"/><stop stop-color="#29FEE7" offset="1"/>
-    </linearGradient>`;
-/** Max width of the loader bar in SVG units */
-const LOADER_BAR_MAX_WIDTH = 174;
-/**
- * Build the Energy8 SVG logo with a loader bar, using unique IDs.
- *
- * @param opts - Configuration to avoid element ID collisions
- * @returns SVG markup string
- */
-function buildLogoSVG(opts) {
-    const { idPrefix, svgClass, svgStyle, clipRectClass, clipRectId, textId, textContent, textClass } = opts;
-    // Replace gradient ID placeholders with prefixed versions
-    const paths = WORDMARK_PATHS.replace(/GID(\d)/g, `${idPrefix}$1`);
-    const defs = GRADIENT_DEFS.replace(/GID(\d)/g, `${idPrefix}$1`);
-    const clipId = `${idPrefix}-loader-clip`;
-    const fillGradientId = `${idPrefix}5`;
-    const classAttr = svgClass ? ` class="${svgClass}"` : '';
-    const styleAttr = svgStyle ? ` style="${svgStyle}"` : '';
-    const rectClassAttr = clipRectClass ? ` class="${clipRectClass}"` : '';
-    const rectIdAttr = clipRectId ? ` id="${clipRectId}"` : '';
-    const txtIdAttr = textId ? ` id="${textId}"` : '';
-    const txtClassAttr = textClass ? ` class="${textClass}"` : '';
-    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 250 200" fill="none"${classAttr}${styleAttr}>
-${paths}
-  <clipPath id="${clipId}">
-    <rect${rectIdAttr} x="37" y="148" width="0" height="20"${rectClassAttr}/>
-  </clipPath>
-  <path d="m204.5 152.6h-159.8c-2.78 0-4.45 1.69-4.45 3.99v0.11c0 2.04 1.42 3.43 3.64 3.43h160.6c2.88 0 3.67-2.07 3.67-3.43v-0.25c0-2.04-1.48-3.85-3.67-3.85z" fill="url(#${fillGradientId})" clip-path="url(#${clipId})"/>
-  <text${txtIdAttr} x="125" y="196" text-anchor="middle" fill="rgba(255,255,255,0.6)" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif" font-size="8" font-weight="600" letter-spacing="1.5"${txtClassAttr}>${textContent ?? 'Loading...'}</text>
-  <defs>
-${defs}
-  </defs>
-</svg>`;
-}
-
 /**
  * Build the loading scene variant of the logo SVG.
  * Uses unique IDs (prefixed with 'ls') to avoid collisions with CSSPreloader.
  */
 function buildLoadingLogoSVG() {
-    return buildLogoSVG({
+    return loading.buildLogoSVG({
         idPrefix: 'ls',
         svgStyle: 'width:100%;height:auto;',
         clipRectId: 'ge-loader-rect',
@@ -1684,7 +1616,7 @@ class LoadingScene extends Scene {
     // ─── Progress ──────────────────────────────────────────
     updateLoaderBar(progress) {
         if (this._loaderRect) {
-            this._loaderRect.setAttribute('width', String(LOADER_BAR_MAX_WIDTH * progress));
+            this._loaderRect.setAttribute('width', String(loading.LOADER_BAR_MAX_WIDTH * progress));
         }
         if (this._percentEl) {
             const pct = Math.round(progress * 100);
@@ -1766,120 +1698,6 @@ class LoadingScene extends Scene {
     }
 }
 
-const PRELOADER_ID = '__ge-css-preloader__';
-/**
- * Inline SVG logo with animated loader bar.
- * The `#loader` path acts as the progress fill — animated via clipPath.
- */
-const LOGO_SVG = buildLogoSVG({
-    idPrefix: 'pl',
-    svgClass: 'ge-logo-svg',
-    clipRectClass: 'ge-clip-rect',
-    textClass: 'ge-preloader-svg-text',
-});
-/**
- * Creates a lightweight CSS-only preloader that appears instantly,
- * BEFORE PixiJS/WebGL is initialized.
- *
- * Displays the Energy8 logo SVG with an animated loader bar.
- */
-function createCSSPreloader(container, config) {
-    if (document.getElementById(PRELOADER_ID))
-        return;
-    const bgColor = typeof config?.backgroundColor === 'string'
-        ? config.backgroundColor
-        : typeof config?.backgroundColor === 'number'
-            ? `#${config.backgroundColor.toString(16).padStart(6, '0')}`
-            : '#0a0a1a';
-    const bgGradient = config?.backgroundGradient ?? `linear-gradient(135deg, ${bgColor} 0%, #1a1a3e 100%)`;
-    const customHTML = config?.cssPreloaderHTML ?? '';
-    const el = document.createElement('div');
-    el.id = PRELOADER_ID;
-    el.innerHTML = customHTML || `
-    <div class="ge-preloader-content">
-      ${LOGO_SVG}
-    </div>
-  `;
-    const style = document.createElement('style');
-    style.textContent = `
-    #${PRELOADER_ID} {
-      position: absolute;
-      top: 0; left: 0;
-      width: 100%; height: 100%;
-      background: ${bgGradient};
-      display: flex;
-      align-items: center;
-      justify-content: center;
-      z-index: 10000;
-      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-      transition: opacity 0.4s ease-out;
-    }
-
-    #${PRELOADER_ID}.ge-preloader-hidden {
-      opacity: 0;
-      pointer-events: none;
-    }
-
-    .ge-preloader-content {
-      display: flex;
-      flex-direction: column;
-      align-items: center;
-      width: 80%;
-      max-width: 700px;
-    }
-
-    .ge-logo-svg {
-      width: 100%;
-      height: auto;
-      filter: drop-shadow(0 0 30px rgba(121, 57, 194, 0.4));
-    }
-
-    /* Animate the loader clip-rect to shimmer while waiting */
-    .ge-clip-rect {
-      animation: ge-loader-fill 2s ease-in-out infinite;
-    }
-
-    @keyframes ge-loader-fill {
-      0%   { width: 0; }
-      50%  { width: 174; }
-      100% { width: 0; }
-    }
-
-    /* Animate the SVG text opacity */
-    .ge-preloader-svg-text {
-      animation: ge-pulse 1.5s ease-in-out infinite;
-    }
-
-    @keyframes ge-pulse {
-      0%, 100% { opacity: 0.4; }
-      50% { opacity: 1; }
-    }
-  `;
-    container.style.position = container.style.position || 'relative';
-    container.appendChild(style);
-    container.appendChild(el);
-}
-/**
- * Remove the CSS preloader with a smooth fade-out transition.
- */
-function removeCSSPreloader(container) {
-    const el = document.getElementById(PRELOADER_ID);
-    if (!el)
-        return;
-    el.classList.add('ge-preloader-hidden');
-    // Remove after transition
-    el.addEventListener('transitionend', () => {
-        el.remove();
-        // Also remove the style element
-        const styles = container.querySelectorAll('style');
-        for (const style of styles) {
-            if (style.textContent?.includes(PRELOADER_ID)) {
-                style.remove();
-            }
-        }
-    });
-}
-
 /**
  * FPS overlay for debugging performance.
  *
@@ -2021,6 +1839,8 @@ class GameApplication extends EventEmitter {
     fpsOverlay = null;
     /** Data received from SDK initialization */
     initData = null;
+    /** Platform session (SDK + optional DevBridge). null until start() runs. */
+    platformSession = null;
     /** Configuration */
     config;
     // ─── Private state ──────────────────────────────────────
@@ -2077,7 +1897,7 @@ class GameApplication extends EventEmitter {
             // 1. Resolve container element
             this._container = this.resolveContainer();
             // 2. Show CSS preloader immediately (before PixiJS)
-            createCSSPreloader(this._container, this.config.loading);
+            loading.createCSSPreloader(this._container, this.config.loading);
             // 3. Initialize PixiJS
             await this.initPixi();
             // 4. Initialize SDK (if enabled)
@@ -2088,7 +1908,7 @@ class GameApplication extends EventEmitter {
             this.initSubSystems();
             this.emit('initialized');
             // 7. Remove CSS preloader, show Canvas loading screen
-            removeCSSPreloader(this._container);
+            loading.removeCSSPreloader(this._container);
             // 8. Load assets with loading screen
             await this.loadAssets(firstScene, sceneData);
             this.emit('loaded');
@@ -2114,7 +1934,7 @@ class GameApplication extends EventEmitter {
         this.input?.destroy();
         this.audio?.destroy();
         this.viewport?.destroy();
-        this.sdk?.destroy();
+        this.platformSession?.destroy();
         this.app?.destroy(true, { children: true, texture: true });
         this.emit('destroyed');
         this.removeAllListeners();
@@ -2150,20 +1970,15 @@ class GameApplication extends EventEmitter {
         this.app.canvas.style.height = '100%';
     }
     async initSDK() {
-        if (this.config.sdk === false) {
-            // Offline / development mode — no SDK
-            this.initData = null;
-            return;
-        }
-        const sdkOpts = typeof this.config.sdk === 'object' ? this.config.sdk : {};
-        this.sdk = new gameSdk.CasinoGameSDK(sdkOpts);
-        // Perform the handshake
-        this.initData = await this.sdk.ready();
-        // Forward SDK events
-        this.sdk.on('error', (err) => {
+        // Delegate the SDK handshake (and any optional in-process DevBridge
+        // wiring) to platform-core. The session forwards SDK events upward.
+        this.platformSession = await platformCore.createPlatformSession({ sdk: this.config.sdk });
+        this.sdk = this.platformSession.sdk;
+        this.initData = this.platformSession.initData;
+        this.platformSession.on('error', (err) => {
             this.emit('error', err);
         });
-        this.sdk.on('balanceUpdate', (data) => {
+        this.platformSession.on('balanceUpdate', (data) => {
             this.emit('balanceUpdate', data);
         });
     }