@energy8platform/game-engine 0.18.0 → 0.19.0

package/src/host/runRound.ts

@@ -1,63 +1,55 @@
 import type { SlotSpinResultBase } from '@energy8platform/platform-core/slot-result';
 import type { RenderContext, SlotSceneController } from './sceneController';
 
-/** Injected dependencies for one round. All host-agnostic + unit-testable. */
 export interface RunRoundDeps<T extends SlotSpinResultBase> {
-  /** play → normalize → enrich (roundId/nextActions/complete). From createSlotPlay. */
   play(action: string, bet: number, roundId?: string): Promise<T>;
-  /** Settle the most recent result (post-animation). From createSlotPlay. */
   ack(): void;
-  /** The scene to render into (resolved by the caller at call time — it can change between rounds). */
-  scene: Pick<SlotSceneController<T>, 'present'>;
-  /** Build the per-round render context for the trigger action. */
-  context(action: string): RenderContext;
-  /** Role of an action from the spec ('base'|'buy'|'feature'|'free'); drives bonus detection. */
+  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;
-  /** Fires after each segment is presented + acked. The host updates HUD readouts (win/balance)
-   *  here so they change WITH the animation, never eagerly when the play result arrives. */
   afterPresent?(result: T): void;
-  /** Fires EXACTLY before the first free spin of a bonus. The host drives the shell free-spins mode
-   *  + counter and delegates to the scene's onBonusEnter. `trigger` is the round's trigger result. */
-  onBonusEnter?(trigger: T, ctx: RenderContext): Promise<void>;
-  /** Fires after the last free spin of a bonus. The host exits the shell free-spins mode + delegates
-   *  to the scene's onBonusExit. `last` is the final free-spin result (cumulative totalWin). */
-  onBonusExit?(last: T, ctx: RenderContext): Promise<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;
 }
 
-/**
- * Drive ONE round end-to-end: play the trigger, present it, ack; then drain the remaining segments
- * (a bonus's free spins) by replaying nextActions[0] with the SAME roundId until the round reports
- * `complete`. Fires `onBonusEnter` EXACTLY before the first free-role segment and `onBonusExit`
- * after the last. A plain spin with no bonus is already `complete`, so the while-loop is a no-op.
- *
- * `ctx.bet` is captured once (bet can't change mid-round); `ctx.turbo` is a live getter so a
- * mid-round toggle is honoured on the next segment.
- */
 export async function runRound<T extends SlotSpinResultBase>(
   deps: RunRoundDeps<T>,
   action: string,
 ): Promise<void> {
-  const ctx = deps.context(action);
-  let r = await deps.play(action, ctx.bet);
-  await deps.scene.present(r, ctx);
-  deps.ack();
-  deps.afterPresent?.(r); // HUD readouts update AFTER the animation, not before
+  deps.onSpinStart?.();
 
-  let inBonus = false;
+  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 (!inBonus && deps.roleOf(next) === 'free') {
-      inBonus = true;
-      await deps.onBonusEnter?.(r, ctx);
+    if (!inMode && deps.roleOf(next) === 'free') {
+      inMode = true;
+      await deps.onEnterMode?.(r, ctx);
     }
-    // Snapshot the TRIGGER context per segment: { ... } freezes the live `turbo` getter into a data
-    // property (so a mid-round toggle is reflected on the NEXT segment), while action/mode/bet stay
-    // the round's (the trigger's) identity — a scene must see the same bonus identity all round.
-    const segCtx = { ...deps.context(action) } as RenderContext;
-    r = await deps.play(next, ctx.bet, r.roundId);
-    await deps.scene.present(r, segCtx);
-    deps.ack();
-    deps.afterPresent?.(r);
+    ({ r, ctx } = await segment(next, r.roundId));
   }
-  if (inBonus) await deps.onBonusExit?.(r, ctx);
+  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

@@ -1,31 +1,96 @@
+import type { Container } from 'pixi.js';
 import type { SlotSpinResultBase } from '@energy8platform/platform-core/slot-result';
 
-/** Everything a scene needs to render one result. The host builds it once per round. */
+/** 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 (a bonus is one round). */
+  /** Bet for this round (major units). Stable for the whole round. */
   bet: number;
-  /** Trigger action in the game's own vocabulary (gameSpec.actions keys): 'spin' | 'ante' |
-   *  'buy_bonus' | … Stable for the whole round. */
+  /** Trigger action in the game's own vocabulary ('spin' | 'ante' | 'buy_bonus' | …). */
   action: string;
-  /** Stake bet-mode of the round (model.spec.modeMap[action]): 'BASE' | 'ANTE' | 'BONUS' | …
-   *  Canonical per-round identifier of WHICH bonus/feature this is. Stable for the whole round. */
+  /** Stake bet-mode of the round ('BASE' | 'ANTE' | 'BONUS' | …). */
   mode: string;
-  /** Currency-aware money formatter. win/totalWin get variable decimals (0.0041 stays 0.0041). */
+  /** Currency-aware money formatter. */
   formatAmount(value: number): string;
-  /** LIVE turbo level (0 = off, 1..3 = escalating speed), matching the shell's state.turbo. Read at
-   *  the moment of access (getter) so a mid-round toggle is reflected. */
+  /** 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;
 }
 
-/** The contract a slot scene implements. The HOST owns the play→present→ack→drain loop and calls
- *  these; the scene only renders. The game never sees play/ack/roundId. */
+/** 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> {
-  /** Render ONE segment (a spin, or one free spin). All pacing/pauses/overlays live here
-   *  (await your own animations). The host calls this once per segment. */
-  present(result: T, ctx: RenderContext): Promise<void>;
-  /** Optional. Fires EXACTLY before the first free spin of a bonus (intro; spin counts in
-   *  trigger.freeSpins). */
-  onBonusEnter?(trigger: T, ctx: RenderContext): Promise<void>;
-  /** Optional. Fires after the last free spin of a bonus (summary; last.totalWin = bonus total). */
-  onBonusExit?(last: T, ctx: RenderContext): Promise<void>;
+  /** 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/shellConfig.ts

@@ -1,14 +1,15 @@
 // 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';
 import type {
-  ShellConfig, ShellMode, CurrencyConfig, GameInfoContent, GameInfoSection, PaytableRow,
+  PixiShellConfig, ShellMode, CurrencyConfig, GameInfoContent, GameInfoSection, PaytableRow,
   BonusOption, ShellFeatures, GameMode,
-} from '@energy8platform/platform-core/shell';
+} from '@energy8platform/pixi-shell';
 import type { GameModel } from '@energy8platform/platform-core/game-spec';
 import type { WinTier } from '../slot';
 
 export interface SlotShellOptions {
-  mount?: HTMLElement;
   /** Override the derived currency (normally taken from initData). */
   currency?: CurrencyConfig;
   /** Author-supplied info sections, MERGED over the host-derived set by section identity (an author
@@ -319,8 +320,13 @@ function socializeBonusOptions(options: BonusOption[], isSocial: boolean): Bonus
   return options.map((o) => ({ ...o, title: socialize(o.title), description: socialize(o.description) }));
 }
 
-/** Pure: assemble a ShellConfig from the model + runtime context (currency/balance/language/mode). */
-export function buildShellConfig(opts: SlotShellOptions, model: GameModel, runtime: ShellRuntime): ShellConfig {
+/** Pure: assemble the shell config (sans mount target) from the model + runtime context
+ *  (currency/balance/language/mode). The host adds `app` at the call site. */
+export function buildShellConfig(
+  opts: SlotShellOptions,
+  model: GameModel,
+  runtime: ShellRuntime,
+): Omit<PixiShellConfig, 'app' | 'parent'> {
   // Prefer the currency-specific ladder from /wallet/authenticate; fall back to the spec (dev/devBridge).
   const betLevels = runtime.betLevels?.length ? runtime.betLevels : model.spec.betLevels;
   // Stake requires the default to come from authenticate on every entry; spec default is the dev fallback.
@@ -363,7 +369,6 @@ export function buildShellConfig(opts: SlotShellOptions, model: GameModel, runti
   } as ShellFeatures;
   applyJurisdiction(features, runtime.jurisdiction);
   return {
-    mount: opts.mount ?? (typeof document !== 'undefined' ? document.body : (undefined as never)),
     language: runtime.language ?? 'en',
     isSocial,
     currency,

package/src/host/skipGesture.ts

@@ -0,0 +1,24 @@
+interface SkipDeps {
+  /** The skipGesture setting is on. */
+  enabled(): boolean;
+  /** An onSpin is currently presenting (skippable window). */
+  active(): boolean;
+  onSkip(): void;
+  /** Max ms between the two taps. Default 300. */
+  thresholdMs?: number;
+}
+
+/** Pure double-tap recognizer. The host feeds it pointer `tap(now)` (e.g. performance.now()) and
+ *  supplies the enabled/active gates + the onSkip effect. */
+export function createDoubleTapSkip(deps: SkipDeps): { tap(now: number): void; destroy(): void } {
+  const threshold = deps.thresholdMs ?? 300;
+  let last = -Infinity;
+  return {
+    tap(now: number): void {
+      const isDouble = now - last <= threshold;
+      last = isDouble ? -Infinity : now; // consume the pair so a 3rd tap starts fresh
+      if (isDouble && deps.enabled() && deps.active()) deps.onSkip();
+    },
+    destroy(): void { last = -Infinity; },
+  };
+}

package/src/host/types.ts

@@ -2,7 +2,7 @@
 import type { ApplicationOptions } from 'pixi.js';
 import type { GameModel } from '@energy8platform/platform-core/game-spec';
 import type { AssetManifest, LoadingScreenConfig } from '@energy8platform/platform-core';
-import type { GameShell } from '@energy8platform/platform-core/shell';
+import type { PixiGameShell } from '@energy8platform/pixi-shell';
 import type { AudioConfig, ScaleMode, Orientation, SceneConstructor } from '../types';
 import type { BookAdapter, AdapterModule, StakeBridge } from '@energy8platform/stake-bridge';
 import type { GameApplication } from '../core';
@@ -61,11 +61,14 @@ export interface CreateSlotGameOptions<T extends SlotSpinResultBase = SlotSpinRe
   dev?: boolean;
   stake?: StakeIntegration;
   shell?: SlotShellOptions;
+  /** Double-tap on the play area to skip the current spin animation. Default `true`. Set `false`
+   *  to disable the gesture (e.g. games where a tap means something else). */
+  skipGesture?: boolean;
   onFatalError?: (message: string) => void;
 }
 
 export interface SlotGameHandle {
   game: GameApplication;
   stakeBridge: StakeBridge | null;
-  shell: GameShell | null;
+  shell: PixiGameShell | null;
 }

package/src/viewport/ViewportManager.ts

@@ -1,4 +1,4 @@
-import type { Application } from 'pixi.js';
+import type { Application, Container } from 'pixi.js';
 import { EventEmitter } from '../core/EventEmitter';
 import { ScaleMode, Orientation } from '../types';
 
@@ -45,6 +45,7 @@ export class ViewportManager extends EventEmitter<ViewportEvents> {
   private _app: Application;
   private _container: HTMLElement;
   private _config: ViewportConfig;
+  private _target: Container;
   private _resizeObserver: ResizeObserver | null = null;
   private _currentOrientation: Orientation = Orientation.LANDSCAPE;
   private _currentWidth = 0;
@@ -53,11 +54,20 @@ export class ViewportManager extends EventEmitter<ViewportEvents> {
   private _destroyed = false;
   private _resizeTimeout: number | null = null;
 
-  constructor(app: Application, container: HTMLElement, config: ViewportConfig) {
+  constructor(
+    app: Application,
+    container: HTMLElement,
+    config: ViewportConfig,
+    target?: Container,
+  ) {
     super();
     this._app = app;
     this._container = container;
     this._config = config;
+    // The container this manager scales/offsets. Defaults to app.stage for backward
+    // compatibility; the engine passes a dedicated scaled world root so app.stage stays
+    // identity (screen space) for unscaled UI layers.
+    this._target = target ?? app.stage;
 
     this.setupObserver();
   }
@@ -164,18 +174,18 @@ export class ViewportManager extends EventEmitter<ViewportEvents> {
       ? Math.min(containerWidth / designWidth, containerHeight / designHeight)
       : scale;
 
-    this._app.stage.scale.set(stageScale);
+    this._target.scale.set(stageScale);
 
     // Center the stage for FIT mode
     if (scaleMode === ScaleMode.FIT) {
-      this._app.stage.x = Math.round((containerWidth - designWidth * stageScale) / 2);
-      this._app.stage.y = Math.round((containerHeight - designHeight * stageScale) / 2);
+      this._target.x = Math.round((containerWidth - designWidth * stageScale) / 2);
+      this._target.y = Math.round((containerHeight - designHeight * stageScale) / 2);
     } else if (scaleMode === ScaleMode.FILL) {
-      this._app.stage.x = Math.round((containerWidth - gameWidth * stageScale) / 2);
-      this._app.stage.y = Math.round((containerHeight - gameHeight * stageScale) / 2);
+      this._target.x = Math.round((containerWidth - gameWidth * stageScale) / 2);
+      this._target.y = Math.round((containerHeight - gameHeight * stageScale) / 2);
     } else {
-      this._app.stage.x = 0;
-      this._app.stage.y = 0;
+      this._target.x = 0;
+      this._target.y = 0;
     }
 
     this._currentWidth = gameWidth;