@energy8platform/game-engine 0.17.0 → 0.19.0

package/src/host/freeSpinsCounter.ts

@@ -0,0 +1,44 @@
+/**
+ * Free-spins counter for the shell readout (current / total / totalWin), with RETRIGGER support.
+ *
+ * A bonus awards an initial pool of spins; a retrigger mid-bonus awards MORE. The full-event book
+ * already contains every segment (incl. retriggered spins), but the player-facing counter must grow
+ * dynamically: start at the awarded total, and each spin that awards extra bumps the total. The
+ * remaining spins the shell shows are `total - current`.
+ *
+ * Example (the canonical case): enter(10) → 0/10. After two spins → 2/10. The third spin retriggers
+ * +5 → 3/15 (i.e. 12 remaining). `awarded` per spin is the spins granted by THAT spin (0 normally,
+ * the retrigger amount on a retrigger). Pure + unit-testable; the host feeds it `result.freeSpins`.
+ */
+export interface FreeSpinsView {
+  /** Free spins played so far (1-based once spinning). */
+  current: number;
+  /** Total free spins awarded so far (initial + every retrigger). */
+  total: number;
+  /** Cumulative bonus win (the host passes the round's cumulative totalWin). */
+  totalWin: number;
+}
+
+export interface FreeSpinsCounter {
+  /** Bonus start: seed the total with the trigger's awarded spins. Resets current + totalWin. */
+  enter(awarded: number): FreeSpinsView;
+  /** One free spin presented: count it, fold in any retrigger `awarded`, carry the cumulative win. */
+  spin(awarded: number, totalWin: number): FreeSpinsView;
+}
+
+export function createFreeSpinsCounter(): FreeSpinsCounter {
+  let total = 0;
+  let current = 0;
+  return {
+    enter(awarded: number): FreeSpinsView {
+      total = awarded;
+      current = 0;
+      return { current, total, totalWin: 0 };
+    },
+    spin(awarded: number, totalWin: number): FreeSpinsView {
+      current += 1;
+      total += awarded; // a retrigger grows the pool
+      return { current, total, totalWin };
+    },
+  };
+}

package/src/host/index.ts

@@ -0,0 +1,21 @@
+// packages/game-engine/src/host/index.ts
+export { createSlotGame } from './createSlotGame';
+export type {
+  CreateSlotGameOptions,
+  SlotGameHandle,
+  StakeIntegration,
+  SceneRegistration,
+  SceneNavData,
+  SceneEntry,
+} from './types';
+export { buildShellConfig, stakeForAction } from './shellConfig';
+export type { SlotShellOptions } from './shellConfig';
+export { resolveReplayBonusId } from './replay';
+export { resolveStartScene } from './sceneStart';
+export type {
+  SlotSceneController, RenderContext, SceneApi, SceneAudio, SceneOverlay, SceneShell,
+  OverlayShowOptions, AutoplaySceneState,
+} from './sceneController';
+// Social-casino word-swap. The shell auto-socializes all gameInfo/buyBonus text in social mode;
+// authors only need this to socialize strings they render themselves (e.g. inside a custom DOM node).
+export { socialize } from '@energy8platform/platform-core/shell';

package/src/host/overlayController.ts

@@ -0,0 +1,81 @@
+import { Container, Graphics } from 'pixi.js';
+import type { SceneOverlay, OverlayShowOptions } from './sceneController';
+
+interface OverlayDeps {
+  /** Container mounted above the shell on the stage. */
+  parent: Container;
+  /** Live canvas size getter (for the hit area + build size). */
+  size(): { width: number; height: number };
+}
+
+interface ActiveOverlay {
+  layer: Container;
+  resolve(): void;
+  timer: ReturnType<typeof setTimeout> | null;
+  dim: number;
+}
+
+export function createOverlayController(deps: OverlayDeps): {
+  overlay: SceneOverlay;
+  resize(w: number, h: number): void;
+  destroy(): void;
+} {
+  let current: ActiveOverlay | null = null;
+
+  const teardown = (): void => {
+    if (!current) return;
+    if (current.timer) clearTimeout(current.timer);
+    const { layer, resolve } = current;
+    current = null;
+    layer.removeFromParent();
+    layer.destroy({ children: true });
+    resolve();
+  };
+
+  const overlay: SceneOverlay = {
+    show(opts: OverlayShowOptions): Promise<void> {
+      if (current) {
+        console.warn('[overlay] show() ignored — an overlay is already open');
+        return Promise.reject(new Error('Overlay already open'));
+      }
+      const { width, height } = deps.size();
+      const layer = new Container();
+      layer.eventMode = 'static';
+
+      // Pointer-eating + (optional) dim backdrop sized to the canvas.
+      const hit = new Graphics().rect(0, 0, width, height).fill({
+        color: 0x000000,
+        alpha: opts.dim ?? 0.0001, // ~0 keeps it transparent but hit-testable
+      });
+      hit.eventMode = 'static';
+      layer.addChild(hit);
+
+      const content = new Container();
+      layer.addChild(content);
+      opts.build(content, { width, height });
+
+      deps.parent.addChild(layer);
+
+      return new Promise<void>((resolve) => {
+        const dimValue = opts.dim ?? 0.0001;
+        current = { layer, resolve, timer: null, dim: dimValue };
+        const closeOn = opts.closeOn ?? 'tap';
+        if (closeOn === 'tap') hit.on('pointertap', teardown);
+        if (typeof opts.autoCloseMs === 'number') {
+          current.timer = setTimeout(teardown, opts.autoCloseMs);
+        }
+      });
+    },
+    close(): void { teardown(); },
+  };
+
+  return {
+    overlay,
+    resize(w: number, h: number): void {
+      if (!current) return;
+      const hit = current.layer.getChildAt(0) as Graphics;
+      hit.clear().rect(0, 0, w, h).fill({ color: 0x000000, alpha: current.dim });
+    },
+    destroy(): void { teardown(); },
+  };
+}

package/src/host/pauseController.ts

@@ -0,0 +1,21 @@
+interface PauseDeps {
+  isHidden(): boolean;
+  onHidden(): void;
+  onVisible(): void;
+  /** Register a change listener; return an unsubscribe fn. */
+  subscribe(cb: () => void): () => void;
+}
+
+/** Edge-triggers onHidden/onVisible from a visibility source. Effects (ticker/music/autoplay/scene)
+ *  are supplied by the host so this stays pure + testable. */
+export function createPauseController(deps: PauseDeps): { destroy(): void } {
+  let paused = deps.isHidden();
+  const unsub = deps.subscribe(() => {
+    const hidden = deps.isHidden();
+    if (hidden === paused) return;
+    paused = hidden;
+    if (hidden) deps.onHidden();
+    else deps.onVisible();
+  });
+  return { destroy: () => unsub() };
+}

package/src/host/playError.ts

@@ -0,0 +1,64 @@
+/**
+ * Classify a play/settle error into a player-facing modal payload.
+ *
+ * The SDK rejects `play()` with an `SDKError` carrying a `.code` (e.g. `ACTIVE_SESSION_EXISTS`,
+ * `INSUFFICIENT_FUNDS`, `TIMEOUT`). The bridge ALSO emits a `connectionStateChanged: 'lost'` for
+ * some of these, which would otherwise surface a misleading "Reconnecting…" overlay while the real
+ * fix is "reload to resume". The host routes every play error through this classifier so the player
+ * sees the right message + action, and suppresses the connection overlay while a play-error modal
+ * is up.
+ *
+ * `reload: true` → the round must be recovered by reloading (an unfinished round blocks new plays);
+ * the modal offers a Reload button. Otherwise it's a dismissible OK.
+ */
+export interface PlayErrorView {
+  title: string;
+  body: string;
+  /** Offer a Reload action (the round can only be recovered by reloading). */
+  reload: boolean;
+}
+
+/** Pull a Stake/SDK error code off an unknown thrown value. */
+export function errorCode(err: unknown): string | undefined {
+  const code = (err as { code?: unknown })?.code;
+  return typeof code === 'string' ? code : undefined;
+}
+
+export function resolvePlayError(err: unknown): PlayErrorView {
+  const code = errorCode(err);
+  const message = err instanceof Error ? err.message : typeof err === 'string' ? err : '';
+  switch (code) {
+    case 'ACTIVE_SESSION_EXISTS':
+      return {
+        title: 'Round in progress',
+        body: 'You have an unfinished round. Reload to resume it.',
+        reload: true,
+      };
+    case 'NO_ACTIVE_SESSION':
+      return {
+        title: 'Round expired',
+        body: 'This round is no longer active. Reload to continue.',
+        reload: true,
+      };
+    case 'INSUFFICIENT_FUNDS':
+      return {
+        title: 'Insufficient balance',
+        body: 'You don’t have enough balance for this bet. Lower your bet or top up.',
+        reload: false,
+      };
+    case 'TIMEOUT':
+      return {
+        title: 'Connection timed out',
+        body: 'The game server did not respond in time. Please try again.',
+        reload: false,
+      };
+    default:
+      // Unknown code: surface the server message verbatim under a generic heading (never the
+      // connection overlay), so an operator can diagnose without a code change.
+      return {
+        title: 'Game error',
+        body: message || 'Something went wrong. Please reload the game.',
+        reload: true,
+      };
+  }
+}

package/src/host/preboot.ts

@@ -0,0 +1,25 @@
+import { TextureSource } from 'pixi.js';
+
+/** Preload web fonts so Pixi text rasterizes with the right glyphs. Never throws. */
+export async function loadFonts(specs?: string[]): Promise<void> {
+  if (!specs || specs.length === 0) return;
+  try {
+    await Promise.all(specs.map((s) => document.fonts.load(s)));
+    await document.fonts.ready;
+  } catch {
+    /* font CDN unreachable → fall back to system fonts */
+  }
+}
+
+/** Smoother default downscaling for art-heavy slots. Pixel-art games omit this. */
+export function applyTextureDefaults(): void {
+  TextureSource.defaultOptions.autoGenerateMipmaps = true;
+}
+
+/** Idempotent double-boot guard. Returns true the first time, false thereafter. */
+export function bootGuard(flag = '__e8SlotBooted__'): boolean {
+  const w = window as unknown as Record<string, boolean>;
+  if (w[flag]) return false;
+  w[flag] = true;
+  return true;
+}

package/src/host/replay.ts

@@ -0,0 +1,9 @@
+import type { GameModel } from '@energy8platform/platform-core/game-spec';
+
+/** Reverse the model's modeMap (Stake bet mode → SDK action key) for replay labelling/cost. */
+export function resolveReplayBonusId(model: GameModel, stakeMode: string): string {
+  for (const [action, mode] of Object.entries(model.modeMap)) {
+    if (mode === stakeMode) return action;
+  }
+  return stakeMode;
+}

package/src/host/runRound.ts

@@ -0,0 +1,55 @@
+import type { SlotSpinResultBase } from '@energy8platform/platform-core/slot-result';
+import type { RenderContext, SlotSceneController } from './sceneController';
+
+export interface RunRoundDeps<T extends SlotSpinResultBase> {
+  play(action: string, bet: number, roundId?: string): Promise<T>;
+  ack(): void;
+  scene: Pick<SlotSceneController<T>, 'onSpin'>;
+  /** Build the per-round render context (without signal — runRound injects it per segment). */
+  context(action: string): Omit<RenderContext, 'signal'> & { signal?: AbortSignal };
+  roleOf(action: string): string | undefined;
+  afterPresent?(result: T): void;
+  /** Once, before the first segment is played (player pressed spin). */
+  onSpinStart?(): void;
+  /** Once, after the full drain. */
+  onSpinEnd?(last: T, ctx: RenderContext): void;
+  /** Fires when entering a non-BASE mode (first free segment). */
+  onEnterMode?(trigger: T, ctx: RenderContext): Promise<void>;
+  /** Fires after the last segment of a mode. */
+  onExitMode?(last: T, ctx: RenderContext): Promise<void>;
+  /** Hands the host the AbortController for the segment about to present (for skip). */
+  beforeSegment?(ac: AbortController): void;
+}
+
+export async function runRound<T extends SlotSpinResultBase>(
+  deps: RunRoundDeps<T>,
+  action: string,
+): Promise<void> {
+  deps.onSpinStart?.();
+
+  const ctxBet = deps.context(action).bet;
+
+  const segment = async (a: string, roundId: string | undefined): Promise<{ r: T; ctx: RenderContext }> => {
+    const ac = new AbortController();
+    deps.beforeSegment?.(ac);
+    const r = await deps.play(a, ctxBet, roundId);
+    const ctx = { ...deps.context(action), signal: ac.signal } as RenderContext;
+    await deps.scene.onSpin(r, ctx);
+    deps.ack();
+    deps.afterPresent?.(r);
+    return { r, ctx };
+  };
+  let { r, ctx } = await segment(action, undefined);
+
+  let inMode = false;
+  while (!r.complete && r.nextActions && r.nextActions.length > 0) {
+    const next = r.nextActions[0];
+    if (!inMode && deps.roleOf(next) === 'free') {
+      inMode = true;
+      await deps.onEnterMode?.(r, ctx);
+    }
+    ({ r, ctx } = await segment(next, r.roundId));
+  }
+  if (inMode) await deps.onExitMode?.(r, ctx);
+  deps.onSpinEnd?.(r, ctx);
+}

package/src/host/sceneAudio.ts

@@ -0,0 +1,14 @@
+import type { AudioManager } from '../audio/AudioManager';
+import type { SceneAudio } from './sceneController';
+
+/** Wrap the engine's AudioManager into the playback-only handle a scene receives. Volume/mute are
+ *  deliberately omitted — those are driven by the shell's settingChange → host. */
+export function createSceneAudio(audio: AudioManager): SceneAudio {
+  return {
+    play: (alias, opts) => audio.play(alias, 'sfx', opts),
+    playMusic: (alias, fadeMs) => audio.playMusic(alias, fadeMs),
+    stopMusic: () => audio.stopMusic(),
+    duck: (factor) => audio.duckMusic(factor),
+    unduck: () => audio.unduckMusic(),
+  };
+}

package/src/host/sceneController.ts

@@ -0,0 +1,96 @@
+import type { Container } from 'pixi.js';
+import type { SlotSpinResultBase } from '@energy8platform/platform-core/slot-result';
+
+/** Everything a scene needs to render one segment. The host builds it per segment. */
+export interface RenderContext {
+  /** Bet for this round (major units). Stable for the whole round. */
+  bet: number;
+  /** Trigger action in the game's own vocabulary ('spin' | 'ante' | 'buy_bonus' | …). */
+  action: string;
+  /** Stake bet-mode of the round ('BASE' | 'ANTE' | 'BONUS' | …). */
+  mode: string;
+  /** Currency-aware money formatter. */
+  formatAmount(value: number): string;
+  /** LIVE turbo level (0 = off, 1..3 = escalating speed). Read at access. */
+  readonly turbo: number;
+  /** Aborted when the player skips this segment (double-tap). The scene's async pacing can race or
+   *  cancel on it; on abort the scene must collapse to the segment's final visual state. */
+  signal: AbortSignal;
+}
+
+/** Playback-only audio handle. Volume/mute are shell settings → host, never the scene. */
+export interface SceneAudio {
+  play(alias: string, opts?: { volume?: number; loop?: boolean; speed?: number }): void;
+  playMusic(alias: string, fadeMs?: number): void;
+  stopMusic(): void;
+  duck(factor: number): void;
+  unduck(): void;
+}
+
+export interface OverlayShowOptions {
+  /** Draw the overlay content into `container` (sized to the canvas). */
+  build(container: Container, size: { width: number; height: number }): void;
+  /** Auto-close after N ms (combine with closeOn — whichever fires first). */
+  autoCloseMs?: number;
+  /** Dismiss on a single tap. Default 'tap'. Set false to require an explicit close(). */
+  closeOn?: 'tap' | false;
+  /** Optional host-drawn backdrop alpha (0..1). Default: none (game draws its own). */
+  dim?: number;
+}
+
+/** Single host-owned layer above scene + shell. Eats pointer events so shell controls are
+ *  unreachable while open. */
+export interface SceneOverlay {
+  /** Resolves when the overlay closes. Rejects if one is already open. */
+  show(opts: OverlayShowOptions): Promise<void>;
+  close(): void;
+}
+
+export interface SceneShell {
+  /** Live insets (px). `bottom` = the shell bar height; read inside onResize. */
+  readonly safeArea: { top: number; right: number; bottom: number; left: number };
+}
+
+export interface AutoplaySceneState {
+  running: boolean;
+  remaining: number;
+}
+
+/** Stable capabilities injected once via onCreate. */
+export interface SceneApi {
+  audio: SceneAudio;
+  overlay: SceneOverlay;
+  shell: SceneShell;
+  formatAmount(value: number): string;
+  readonly bet: number;
+  readonly mode: string;
+  readonly turbo: number;
+}
+
+/** The contract a slot scene implements. The HOST owns the play→present→ack→drain loop and the
+ *  shell; the scene only renders + reacts. The core spin-lifecycle hooks are REQUIRED (implement
+ *  them — empty bodies are fine where a game has nothing to do); the incidental reactions below
+ *  stay optional. */
+export interface SlotSceneController<T extends SlotSpinResultBase = SlotSpinResultBase> {
+  /** Injected ONCE before the first round — capabilities, subscriptions, one-time setup. */
+  onCreate(api: SceneApi): void;
+  /** Fires once per round when the player presses spin (before the network result). */
+  onSpinStart(): void;
+  /** Render ONE segment (a spin or one free spin). Await your own pacing. */
+  onSpin(result: T, ctx: RenderContext): Promise<void>;
+  /** Fires when ctx.mode changes between segments (entering a non-BASE mode/bonus). */
+  onEnterMode(result: T, ctx: RenderContext): Promise<void>;
+  /** Fires when leaving a mode (back toward BASE). */
+  onExitMode(result: T, ctx: RenderContext): Promise<void>;
+  /** Fires once per round after the full drain (controls unlocked). */
+  onSpinEnd(result: T, ctx: RenderContext): void;
+  /** Shell events (may fire while idle) — optional. */
+  onBetChanged?(bet: number): void;
+  onTurboChanged?(level: number): void;
+  onAutoplayChanged?(state: AutoplaySceneState): void;
+  /** Double-tap skip during an active onSpin (gated by the skipGesture setting). */
+  onSkip?(): void;
+  /** Tab focus lost / regained. */
+  onPause?(): void;
+  onResume?(): void;
+}

package/src/host/sceneStart.ts

@@ -0,0 +1,25 @@
+import type { SceneRegistration } from './types';
+
+/**
+ * Pick the scene to START with, given the registered scenes (in order) and the launch mode.
+ *
+ * Rules:
+ *  - On a replay launch, scenes flagged `skipOnReplay` are NOT eligible to start (they stay
+ *    registered for `goto`, they just aren't auto-started) — so a leading intro is skipped and
+ *    the game scene starts directly.
+ *  - An explicit `startScene` wins, but only if that scene is itself eligible; otherwise the first
+ *    eligible scene wins.
+ *  - Falls back to the first scene unconditionally if nothing is eligible (degenerate config).
+ */
+export function resolveStartScene(
+  scenes: SceneRegistration[],
+  isReplay: boolean,
+  explicitStart?: string,
+): string {
+  const eligible = scenes.filter((s) => !(isReplay && s.skipOnReplay));
+  if (explicitStart) {
+    const ok = eligible.find((s) => s.key === explicitStart);
+    if (ok) return ok.key;
+  }
+  return eligible[0]?.key ?? scenes[0]?.key;
+}