@energy8platform/game-engine 0.19.0 → 0.21.0

package/dist/host.cjs.js

@@ -188,6 +188,10 @@ class Tween {
      * @param onUpdate - Progress callback (0..1)
      */
     static to(target, props, duration, easing, onUpdate) {
+        // A destroyed (Pixi) target has null transform fields — skip rather than throw. This guards
+        // animations whose target is torn down mid-flight (e.g. a reel grid rebuilt during a spin).
+        if (target == null || target.destroyed)
+            return Promise.resolve();
         return new Promise((resolve) => {
             // Capture starting values
             const from = {};
@@ -213,6 +217,8 @@ class Tween {
      * Animate properties from given values to current values.
      */
     static from(target, props, duration, easing, onUpdate) {
+        if (target == null || target.destroyed)
+            return Promise.resolve();
         // Capture current values as "to"
         const to = {};
         for (const key of Object.keys(props)) {
@@ -225,6 +231,8 @@ class Tween {
      * Animate from one set of values to another.
      */
     static fromTo(target, fromProps, toProps, duration, easing, onUpdate) {
+        if (target == null || target.destroyed)
+            return Promise.resolve();
         // Set starting values
         for (const key of Object.keys(fromProps)) {
             Tween.setProperty(target, key, fromProps[key]);
@@ -298,6 +306,11 @@ class Tween {
         const dt = ticker.deltaMS;
         const completed = [];
         for (const tw of Tween._tweens) {
+            // target torn down mid-tween → finish it quietly
+            if (tw.target?.destroyed) {
+                completed.push(tw);
+                continue;
+            }
             tw.elapsed += dt;
             if (tw.elapsed < tw.delay)
                 continue;
@@ -335,9 +348,9 @@ class Tween {
         const parts = key.split('.');
         let obj = target;
         for (let i = 0; i < parts.length - 1; i++) {
-            obj = obj[parts[i]];
+            obj = obj?.[parts[i]];
         }
-        return obj[parts[parts.length - 1]] ?? 0;
+        return obj?.[parts[parts.length - 1]] ?? 0;
     }
     /**
      * Set a potentially nested property.
@@ -346,8 +359,10 @@ class Tween {
         const parts = key.split('.');
         let obj = target;
         for (let i = 0; i < parts.length - 1; i++) {
-            obj = obj[parts[i]];
+            obj = obj?.[parts[i]];
         }
+        if (obj == null)
+            return;
         obj[parts[parts.length - 1]] = value;
     }
 }
@@ -1517,34 +1532,20 @@ class Scene {
 }
 
 /**
- * Build the loading scene variant of the logo SVG.
- * Uses unique IDs (prefixed with 'ls') to avoid collisions with CSSPreloader.
- */
-function buildLoadingLogoSVG() {
-    return loading.buildLogoSVG({
-        idPrefix: 'ls',
-        svgStyle: 'width:100%;height:auto;',
-        clipRectId: 'ge-loader-rect',
-        textId: 'ge-loader-pct',
-        textContent: '0%',
-    });
-}
-/**
- * Built-in loading screen using the Energy8 SVG logo with animated loader bar.
+ * Built-in loading screen.
  *
- * Renders as an HTML overlay on top of the canvas for crisp SVG quality.
- * The loader bar fill width is driven by asset loading progress.
+ * It does NOT render its own overlay — the CSS preloader created at boot
+ * (`createPlatformSession`/`GameApplication.start`) stays on screen, and this
+ * scene merely drives it: asset-load progress → `setCSSPreloaderProgress`,
+ * tap-to-start → `waitCSSPreloaderTap`, then fades it out via
+ * `removeCSSPreloader` before entering the game. One continuous overlay from
+ * boot to gameplay — no second logo, no mid-load flash.
  */
 class LoadingScene extends Scene {
     _engine;
     _targetScene;
     _targetData;
     _config;
-    // HTML overlay
-    _overlay = null;
-    _loaderRect = null;
-    _percentEl = null;
-    _tapToStartEl = null;
     // State
     _displayedProgress = 0;
     _targetProgress = 0;
@@ -1557,8 +1558,6 @@ class LoadingScene extends Scene {
         this._targetData = targetData;
         this._config = engine.config.loading ?? {};
         this._startTime = Date.now();
-        // Create the HTML overlay with the SVG logo
-        this.createOverlay();
         // Initialize asset manager
         await this._engine.assets.init();
         // Initialize audio manager
@@ -1604,110 +1603,29 @@ class LoadingScene extends Scene {
         // Final snap to 100%
         this._displayedProgress = 1;
         this.updateLoaderBar(1);
-        // Show "Tap to Start" or transition directly
-        if (this._config.tapToStart !== false) {
-            await this.showTapToStart();
-        }
-        else {
-            await this.transitionToGame();
-        }
+        // Wait for the player's tap — resolves immediately when tapToStart is
+        // false (the preloader honours that flag) — then enter the game.
+        await loading.waitCSSPreloaderTap();
+        await this.transitionToGame();
     }
     onUpdate(dt) {
-        // Smooth progress bar fill via HTML (during active loading)
+        // Smooth progress bar fill (during active loading)
         if (!this._loadingComplete && this._displayedProgress < this._targetProgress) {
             this._displayedProgress = Math.min(this._displayedProgress + dt * 1.5, this._targetProgress);
             this.updateLoaderBar(this._displayedProgress);
         }
     }
     onResize(_width, _height) {
-        // Overlay is CSS-based, auto-resizes
+        // The preloader overlay is CSS-based and auto-resizes.
     }
     onDestroy() {
-        this.removeOverlay();
-    }
-    // ─── HTML Overlay ──────────────────────────────────────
-    createOverlay() {
-        const bgColor = typeof this._config.backgroundColor === 'string'
-            ? this._config.backgroundColor
-            : typeof this._config.backgroundColor === 'number'
-                ? `#${this._config.backgroundColor.toString(16).padStart(6, '0')}`
-                : '#0a0a1a';
-        const bgGradient = this._config.backgroundGradient ??
-            `linear-gradient(135deg, ${bgColor} 0%, #1a1a3e 100%)`;
-        this._overlay = document.createElement('div');
-        this._overlay.id = '__ge-loading-overlay__';
-        this._overlay.innerHTML = `
-      <div class="ge-loading-content">
-        ${buildLoadingLogoSVG()}
-      </div>
-    `;
-        const style = document.createElement('style');
-        style.id = '__ge-loading-style__';
-        style.textContent = `
-      #__ge-loading-overlay__ {
-        position: absolute;
-        top: 0; left: 0;
-        width: 100%; height: 100%;
-        background: ${bgGradient};
-        display: flex;
-        align-items: center;
-        justify-content: center;
-        z-index: 9999;
-        transition: opacity 0.5s ease-out;
-        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-      }
-      #__ge-loading-overlay__.ge-fade-out {
-        opacity: 0;
-        pointer-events: none;
-      }
-      .ge-loading-content {
-        display: flex;
-        flex-direction: column;
-        align-items: center;
-        width: 75%;
-        max-width: 650px;
-      }
-      .ge-loading-content svg {
-        filter: drop-shadow(0 0 40px rgba(121, 57, 194, 0.5));
-        cursor: default;
-      }
-
-      .ge-svg-pulse {
-        animation: ge-tap-pulse 1.2s ease-in-out infinite;
-      }
-      @keyframes ge-tap-pulse {
-        0%, 100% { opacity: 0.5; }
-        50% { opacity: 1; }
-      }
-    `;
-        // Get the container that holds the canvas
-        const container = this._engine.app?.canvas?.parentElement;
-        if (container) {
-            container.style.position = container.style.position || 'relative';
-            container.appendChild(style);
-            container.appendChild(this._overlay);
-        }
-        // Cache the SVG loader rect for progress updates
-        this._loaderRect = this._overlay.querySelector('#ge-loader-rect');
-        this._percentEl = this._overlay.querySelector('#ge-loader-pct');
-    }
-    removeOverlay() {
-        this._overlay?.remove();
-        document.getElementById('__ge-loading-style__')?.remove();
-        this._overlay = null;
-        this._loaderRect = null;
-        this._percentEl = null;
-        this._tapToStartEl = null;
+        // Defensive: ensure the preloader is gone even if we never transitioned
+        // (e.g. the scene was popped externally). Idempotent.
+        void loading.removeCSSPreloader(this.hostElement());
     }
     // ─── Progress ──────────────────────────────────────────
     updateLoaderBar(progress) {
-        if (this._loaderRect) {
-            this._loaderRect.setAttribute('width', String(loading.LOADER_BAR_MAX_WIDTH * progress));
-        }
-        if (this._percentEl) {
-            const pct = Math.round(progress * 100);
-            this._percentEl.textContent = `${pct}%`;
-        }
+        loading.setCSSPreloaderProgress(Math.max(0, Math.min(1, progress)));
     }
     /**
      * Smoothly animate the displayed progress from its current value to `target`
@@ -1737,49 +1655,20 @@ class LoadingScene extends Scene {
             requestAnimationFrame(tick);
         });
     }
-    // ─── Tap to Start ─────────────────────────────────────
-    async showTapToStart() {
-        const tapText = this._config.tapToStartText ?? 'TAP TO START';
-        // Reuse the same SVG text element — replace percentage with tap text
-        if (this._percentEl) {
-            const el = this._percentEl;
-            el.textContent = tapText;
-            el.setAttribute('fill', '#ffffff');
-            el.classList.add('ge-svg-pulse');
-            this._tapToStartEl = el;
-        }
-        // Make overlay clickable
-        if (this._overlay) {
-            this._overlay.style.cursor = 'pointer';
-        }
-        // Wait for tap
-        return new Promise((resolve) => {
-            const handler = async () => {
-                this._overlay?.removeEventListener('click', handler);
-                await this.transitionToGame();
-                resolve();
-            };
-            // Listen on the full overlay for easier mobile tap
-            this._overlay?.addEventListener('click', handler);
-        });
-    }
     // ─── Transition ────────────────────────────────────────
+    /** The DOM element hosting the canvas + preloader overlay. */
+    hostElement() {
+        return this._engine?.app?.canvas?.parentElement ?? document.body;
+    }
     async transitionToGame() {
-        // Fade out the HTML overlay
-        if (this._overlay) {
-            this._overlay.classList.add('ge-fade-out');
-            await new Promise((resolve) => {
-                this._overlay.addEventListener('transitionend', () => resolve(), { once: true });
-                // Safety timeout
-                setTimeout(resolve, 600);
-            });
-        }
-        // Remove overlay
-        this.removeOverlay();
+        // Fade out and remove the shared CSS preloader (resolves after the fade).
+        await loading.removeCSSPreloader(this.hostElement());
         // Navigate to the target scene, always passing the engine reference
         await this._engine.scenes.goto(this._targetScene, {
             engine: this._engine,
-            ...(this._targetData && typeof this._targetData === 'object' ? this._targetData : { data: this._targetData }),
+            ...(this._targetData && typeof this._targetData === 'object'
+                ? this._targetData
+                : { data: this._targetData }),
         });
     }
 }
@@ -2006,17 +1895,20 @@ class GameApplication extends EventEmitter {
             // 6. Initialize sub-systems
             this.initSubSystems();
             this.emit('initialized');
-            // 7. Remove CSS preloader, show Canvas loading screen
-            loading.removeCSSPreloader(this._container);
-            // 8. Load assets with loading screen
+            // 7. Load assets. The CSS preloader stays on screen — LoadingScene drives
+            //    its progress/tap and removes it before entering the game, so there's
+            //    a single continuous overlay from boot to gameplay (no logo flash).
             await this.loadAssets(firstScene, sceneData);
             this.emit('loaded');
-            // 9. Start the game loop
+            // 8. Start the game loop
             this._running = true;
             this.emit('started');
         }
         catch (err) {
             console.error('[GameEngine] Failed to start:', err);
+            // Tear down the preloader so a failure doesn't strand the brand frame.
+            if (this._container)
+                loading.removeCSSPreloader(this._container);
             this.emit('error', err instanceof Error ? err : new Error(String(err)));
             throw err;
         }
@@ -2879,8 +2771,8 @@ async function createSlotGame(opts) {
 }
 
 // packages/game-engine/src/host/shellConfig.ts
-// `socialize` is a runtime helper that pixi-shell does NOT re-export (its index only re-exports
-// types), so it stays sourced from platform-core/shell; the shapes are structurally identical.
+// `socialize` / `createI18n` are runtime helpers sourced from platform-core/shell;
+// pixi-shell re-exports only types so we import directly from platform-core.
 /**
  * Apply jurisdiction restrictions over the resolved shell features, in place. A restriction ALWAYS
  * wins over the author's intent (a forbidden control must stay off even if the game enabled it).
@@ -2935,8 +2827,9 @@ function stakeForAction(model, action, bet) {
     const cost = (model.spec.actions?.[action]?.cost ?? 1);
     return cost * bet;
 }
-/** Derive shell buy cards + ante toggles from the spec's buy/feature actions (SSOT). */
-function toBonusOptions(model) {
+/** Derive shell buy cards + ante toggles from the spec's buy/feature actions (SSOT).
+ *  @param t Optional translator applied to `title` and `description` before they enter the shell. */
+function toBonusOptions(model, t = (s) => s) {
     const out = [];
     for (const [key, action] of Object.entries(model.spec.actions)) {
         const role = action.role ?? 'base';
@@ -2945,15 +2838,18 @@ function toBonusOptions(model) {
         out.push({
             id: key,
             type: role === 'buy' ? 'bonus' : 'feature',
-            title: action.title ?? key.replace(/_/g, ' ').toUpperCase(),
-            description: action.description ?? '',
+            title: t(action.title ?? key.replace(/_/g, ' ').toUpperCase()),
+            description: t(action.description ?? ''),
             priceMultiplier: action.cost ?? (role === 'buy' ? 100 : 1),
+            // Volatility (1–5 bolts) is part of the spec action SSOT; forward it so the buy card shows it.
+            ...(action.volatility != null ? { volatility: action.volatility } : {}),
         });
     }
     return out;
 }
-/** Build a paytable section from the model's derived paytable view (multipliers per symbol count). */
-function paytableSection(model) {
+/** Build a paytable section from the model's derived paytable view (multipliers per symbol count).
+ *  @param t Optional translator applied to symbol names before they enter the shell. */
+function paytableSection(model, t = (s) => s) {
     const symbols = model.paytable?.symbols ?? [];
     const rows = [];
     for (const s of symbols) {
@@ -2963,11 +2859,13 @@ function paytableSection(model) {
             .sort((a, b) => Number(a.count) - Number(b.count));
         if (!wins.length)
             continue;
-        rows.push({ symbol: { text: s.name ?? s.id }, wins });
+        rows.push({ symbol: { text: t(s.name ?? s.id) }, wins });
     }
     if (!rows.length)
         return null;
-    return { type: 'paytable', title: 'PAYTABLE', rows };
+    // No literal title — the shell renders `s.title ?? host.t('Paytable')`, so the heading is
+    // localized (matching how the modes/wins sections rely on the shell's translated fallback).
+    return { type: 'paytable', rows };
 }
 /** Build a "wins" illustration section sized to the grid; `kind` follows the spec mechanic hint. */
 function winsSection(model) {
@@ -3009,14 +2907,15 @@ function orderDisclaimerLast(sections) {
  * gets a real info panel for free (paytable, win illustration, controls, and the Stake
  * disclaimer when present). Author-supplied `opts.gameInfo` is MERGED over this set by
  * section identity (see `mergeGameInfo`), not wholesale-replaced.
+ * @param t Optional translator applied to spec-derived player-facing strings (symbol names, mode titles, etc.).
  */
-function defaultGameInfo(model, runtime) {
+function defaultGameInfo(model, runtime, t = (s) => s) {
     const sections = [];
     sections.push(winsSection(model));
-    const pay = paytableSection(model);
+    const pay = paytableSection(model, t);
     if (pay)
         sections.push(pay);
-    const modes = modesSection(model);
+    const modes = modesSection(model, t);
     if (modes)
         sections.push(modes);
     sections.push({ type: 'controls' });
@@ -3029,8 +2928,9 @@ function defaultGameInfo(model, runtime) {
  *  (`model.mathModes` + `spec.actions`) that drives the buy cards and the math pipeline. Stake
  *  compliance requires Cost / RTP / Max Win per mode; deriving it here means the author declares a
  *  mode once (in game.spec) and the info table can't drift. `free` actions are excluded (mathModes
- *  already drops them — free spins are part of a bonus, not a purchasable mode). */
-function modesSection(model) {
+ *  already drops them — free spins are part of a bonus, not a purchasable mode).
+ *  @param t Optional translator applied to row `title` and `description` before they enter the shell. */
+function modesSection(model, t = (s) => s) {
     const modes = model.mathModes ?? [];
     if (!modes.length)
         return null;
@@ -3038,7 +2938,7 @@ function modesSection(model) {
         const action = model.spec.actions[m.action];
         const isBase = (action?.role ?? 'base') === 'base' || m.mode === 'BASE';
         const row = {
-            title: action?.title ?? (isBase ? 'Base game' : m.mode.replace(/_/g, ' ')),
+            title: t(action?.title ?? (isBase ? 'Base game' : m.mode.replace(/_/g, ' '))),
             maxWin: `${m.maxWin.toLocaleString('en-US')}×`,
         };
         // Cost is a bet-multiplier; a base spin (1×) reads as no premium, so only show it for buys/features.
@@ -3047,7 +2947,7 @@ function modesSection(model) {
         if (typeof m.rtp === 'number')
             row.rtp = Math.round(m.rtp * 1000) / 10; // 0.965 → 96.5 (%)
         if (action?.description)
-            row.description = action.description;
+            row.description = t(action.description);
         return row;
     });
     return { type: 'modes', title: 'MODES', modes: rows };
@@ -3144,18 +3044,17 @@ function buildShellConfig(opts, model, runtime) {
     // host); opts.currency still wins. Fall back to the spec code, then a neutral euro.
     const currency = opts.currency ?? runtime.currency ?? resolveCurrency(null, model.spec.currency);
     const isSocial = runtime.social ?? false;
-    // Merge author sections over the host-derived defaults, THEN socialize the WHOLE merged set in
-    // social mode — so restricted gambling vocabulary is rewritten in BOTH the built-in copy AND any
-    // author-supplied text (title + custom HTML). A game can no longer surface a forbidden word in
-    // social mode just because the author wrote it in their own info section. (Custom sections built
-    // from a raw DOM `node` can't be rewritten automatically — author owns the node and can call the
-    // exported `socialize` from '@energy8platform/game-engine/host' on their own strings.)
-    // Author gameInfo may be a plain object or a `(t) => content` factory. `t` socializes when in
-    // social mode (identity otherwise) so authors can wrap copy explicitly; the full merged set is
-    // still socialized below as a safety net.
-    const t = isSocial ? shell.socialize : (text) => text;
+    // Build the merged resolver: game i18n map + shell LOCALES (via createI18n), then socialize on
+    // top for English social mode. For non-English languages, createI18n already handles the
+    // translation lookup; social rewriting is English-only and applied separately after.
+    // Author gameInfo may be a plain object or a `(t) => content` factory. `t` is the resolver so
+    // authors can wrap player-facing copy explicitly; the full merged set is still socialized below
+    // (section pass) as a safety net so restricted words can't slip through even if t() was missed.
+    const { t } = shell.createI18n({ language: runtime.language ?? 'en', isSocial, messages: opts.i18n });
     const authored = typeof opts.gameInfo === 'function' ? opts.gameInfo(t) : opts.gameInfo;
-    let gameInfo = mergeGameInfo(defaultGameInfo(model, runtime), authored);
+    // Pass t() through to spec-derived sections so symbol names, mode titles, and descriptions are
+    // pre-translated before they reach the shell renderer.
+    let gameInfo = mergeGameInfo(defaultGameInfo(model, runtime, t), authored);
     // The DISCLAIMER is required legal copy and must be shown VERBATIM — never socialized (its
     // wording is mandated, and word-swaps like "bet → play" would corrupt the legal text).
     if (isSocial) {
@@ -3165,8 +3064,8 @@ function buildShellConfig(opts, model, runtime) {
     }
     // The legal DISCLAIMER always renders LAST — author-merged or extra sections never push below it.
     gameInfo = { sections: orderDisclaimerLast(gameInfo.sections ?? []) };
-    // Buy-bonus cards: socialize the FINAL options (author override or spec-derived) in social mode.
-    const buyBonus = socializeBonusOptions(opts.buyBonus ?? toBonusOptions(model), isSocial);
+    // Buy-bonus cards: apply t() to spec-derived options (pre-translate), then socialize for en+social.
+    const buyBonus = socializeBonusOptions(opts.buyBonus ?? toBonusOptions(model, t), isSocial);
     // Features: defaults, then author overrides, THEN jurisdiction restrictions (a restriction wins).
     const features = {
         turbo: 0,