@energy8platform/game-engine 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@energy8platform/game-engine",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Universal casino game engine built on PixiJS v8 and @energy8platform/game-sdk",
   "type": "module",
   "main": "./dist/index.cjs.js",

package/src/core/GameApplication.ts

@@ -181,19 +181,20 @@ export class GameApplication extends EventEmitter<GameEngineEvents> {
 
       this.emit('initialized');
 
-      // 7. Remove CSS preloader, show Canvas loading screen
-      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) removeCSSPreloader(this._container);
       this.emit('error', err instanceof Error ? err : new Error(String(err)));
       throw err;
     }

package/src/host/shellConfig.ts

@@ -1,7 +1,8 @@
 // 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.
-import { socialize } from '@energy8platform/platform-core/shell';
+// `socialize` / `createI18n` are runtime helpers sourced from platform-core/shell;
+// pixi-shell re-exports only types so we import directly from platform-core.
+import { socialize, createI18n } from '@energy8platform/platform-core/shell';
+import type { Lang } from '@energy8platform/platform-core/shell';
 import type {
   PixiShellConfig, ShellMode, CurrencyConfig, GameInfoContent, GameInfoSection, PaytableRow,
   BonusOption, ShellFeatures, GameMode,
@@ -26,6 +27,11 @@ export interface SlotShellOptions {
   buyBonus?: BonusOption[];
   tiers?: WinTier[];
   features?: Partial<ShellFeatures>;
+  /** Per-game translation map. Keys are the English source strings (from the spec or copy);
+   *  values are the translated strings for each language. Merged with the shell's built-in
+   *  `LOCALES` catalog — game strings take precedence over the built-in entries for the same key.
+   *  When not supplied, English source strings pass through verbatim (socialised in social mode). */
+  i18n?: Partial<Record<Lang, Record<string, string>>>;
 }
 
 /** The currency metadata surfaced on `initData.config.currency` (game-sdk `CurrencyMetaData`).
@@ -130,8 +136,9 @@ export function stakeForAction(model: GameModel, action: string, bet: number): n
   return cost * bet;
 }
 
-/** Derive shell buy cards + ante toggles from the spec's buy/feature actions (SSOT). */
-export function toBonusOptions(model: GameModel): BonusOption[] {
+/** 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. */
+export function toBonusOptions(model: GameModel, t: (s: string) => string = (s) => s): BonusOption[] {
   const out: BonusOption[] = [];
   for (const [key, action] of Object.entries(model.spec.actions)) {
     const role = action.role ?? 'base';
@@ -139,16 +146,19 @@ export function toBonusOptions(model: GameModel): BonusOption[] {
     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: GameModel): GameInfoSection | null {
+/** 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: GameModel, t: (s: string) => string = (s) => s): GameInfoSection | null {
   const symbols = model.paytable?.symbols ?? [];
   const rows: PaytableRow[] = [];
   for (const s of symbols) {
@@ -157,10 +167,12 @@ function paytableSection(model: GameModel): GameInfoSection | null {
       .filter((w) => Number.isFinite(w.multiplier) && w.multiplier > 0)
       .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. */
@@ -206,13 +218,14 @@ function orderDisclaimerLast(sections: GameInfoSection[]): GameInfoSection[] {
  * 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.).
  */
-export function defaultGameInfo(model: GameModel, runtime: ShellRuntime): GameInfoContent {
+export function defaultGameInfo(model: GameModel, runtime: ShellRuntime, t: (s: string) => string = (s) => s): GameInfoContent {
   const sections: GameInfoSection[] = [];
   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' });
   const disclaimer = disclaimerSection(runtime.disclaimerLines);
@@ -224,21 +237,22 @@ export function defaultGameInfo(model: GameModel, runtime: ShellRuntime): GameIn
  *  (`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: GameModel): GameInfoSection | null {
+ *  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: GameModel, t: (s: string) => string = (s) => s): GameInfoSection | null {
   const modes = model.mathModes ?? [];
   if (!modes.length) return null;
   const rows: GameMode[] = modes.map((m) => {
     const action = model.spec.actions[m.action];
     const isBase = (action?.role ?? 'base') === 'base' || m.mode === 'BASE';
     const row: GameMode = {
-      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.
     if (m.costMultiplier && m.costMultiplier !== 1) row.price = `${m.costMultiplier}×`;
     if (typeof m.rtp === 'number') row.rtp = Math.round(m.rtp * 1000) / 10; // 0.965 → 96.5 (%)
-    if (action?.description) row.description = action.description;
+    if (action?.description) row.description = t(action.description);
     return row;
   });
   return { type: 'modes', title: 'MODES', modes: rows };
@@ -336,18 +350,17 @@ export function buildShellConfig(
   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 ? socialize : (text: string) => 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 } = 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) {
@@ -357,8 +370,8 @@ export function buildShellConfig(
   }
   // 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: ShellFeatures = {
     turbo: 0,

package/src/loading/LoadingScene.ts

@@ -1,23 +1,10 @@
-import { Container, Graphics, Text, Sprite, Assets } from 'pixi.js';
 import { Scene } from '../core/Scene';
-import { Tween } from '../animation/Tween';
-import { Easing } from '../animation/Easing';
 import type { LoadingScreenConfig } from '../types';
-import { buildLogoSVG, LOADER_BAR_MAX_WIDTH } from '@energy8platform/platform-core/loading';
-
-/**
- * Build the loading scene variant of the logo SVG.
- * Uses unique IDs (prefixed with 'ls') to avoid collisions with CSSPreloader.
- */
-function buildLoadingLogoSVG(): string {
-  return buildLogoSVG({
-    idPrefix: 'ls',
-    svgStyle: 'width:100%;height:auto;',
-    clipRectId: 'ge-loader-rect',
-    textId: 'ge-loader-pct',
-    textContent: '0%',
-  });
-}
+import {
+  setCSSPreloaderProgress,
+  waitCSSPreloaderTap,
+  removeCSSPreloader,
+} from '@energy8platform/platform-core/loading';
 
 interface LoadingSceneData {
   engine: any; // GameApplication — avoid circular import
@@ -26,10 +13,14 @@ interface LoadingSceneData {
 }
 
 /**
- * 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.
  */
 export class LoadingScene extends Scene {
   private _engine!: any;
@@ -37,12 +28,6 @@ export class LoadingScene extends Scene {
   private _targetData?: unknown;
   private _config!: LoadingScreenConfig;
 
-  // HTML overlay
-  private _overlay: HTMLDivElement | null = null;
-  private _loaderRect: SVGRectElement | null = null;
-  private _percentEl: Element | null = null;
-  private _tapToStartEl: Element | null = null;
-
   // State
   private _displayedProgress = 0;
   private _targetProgress = 0;
@@ -57,9 +42,6 @@ export class LoadingScene extends Scene {
     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();
 
@@ -122,16 +104,14 @@ export class LoadingScene extends Scene {
     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 waitCSSPreloaderTap();
+    await this.transitionToGame();
   }
 
   override onUpdate(dt: number): void {
-    // 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,
@@ -142,107 +122,19 @@ export class LoadingScene extends Scene {
   }
 
   override onResize(_width: number, _height: number): void {
-    // Overlay is CSS-based, auto-resizes
+    // The preloader overlay is CSS-based and auto-resizes.
   }
 
   override onDestroy(): void {
-    this.removeOverlay();
-  }
-
-  // ─── HTML Overlay ──────────────────────────────────────
-
-  private createOverlay(): void {
-    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');
-  }
-
-  private removeOverlay(): void {
-    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 removeCSSPreloader(this.hostElement());
   }
 
   // ─── Progress ──────────────────────────────────────────
 
   private updateLoaderBar(progress: number): void {
-    if (this._loaderRect) {
-      this._loaderRect.setAttribute('width', String(LOADER_BAR_MAX_WIDTH * progress));
-    }
-    if (this._percentEl) {
-      const pct = Math.round(progress * 100);
-      (this._percentEl as SVGTextElement).textContent = `${pct}%`;
-    }
+    setCSSPreloaderProgress(Math.max(0, Math.min(1, progress)));
   }
 
   /**
@@ -275,58 +167,23 @@ export class LoadingScene extends Scene {
     });
   }
 
-  // ─── Tap to Start ─────────────────────────────────────
-
-  private async showTapToStart(): Promise<void> {
-    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 as SVGTextElement;
-      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<void>((resolve) => {
-      const handler = async () => {
-        this._overlay?.removeEventListener('click', handler);
-        await this.transitionToGame();
-        resolve();
-      };
+  // ─── Transition ────────────────────────────────────────
 
-      // Listen on the full overlay for easier mobile tap
-      this._overlay?.addEventListener('click', handler);
-    });
+  /** The DOM element hosting the canvas + preloader overlay. */
+  private hostElement(): HTMLElement {
+    return this._engine?.app?.canvas?.parentElement ?? document.body;
   }
 
-  // ─── Transition ────────────────────────────────────────
-
   private async transitionToGame(): Promise<void> {
-    // Fade out the HTML overlay
-    if (this._overlay) {
-      this._overlay.classList.add('ge-fade-out');
-      await new Promise<void>((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 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 as Record<string, unknown> : { data: this._targetData }),
+      ...(this._targetData && typeof this._targetData === 'object'
+        ? (this._targetData as Record<string, unknown>)
+        : { data: this._targetData }),
     });
   }
 }