@energy8platform/game-engine 0.18.0 → 0.20.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,16 @@
 // packages/game-engine/src/host/shellConfig.ts
-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 {
-  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
@@ -25,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`).
@@ -129,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';
@@ -138,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) {
@@ -156,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. */
@@ -205,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);
@@ -223,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 };
@@ -319,8 +334,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.
@@ -330,18 +350,17 @@ export function buildShellConfig(opts: SlotShellOptions, model: GameModel, runti
   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) {
@@ -351,8 +370,8 @@ export function buildShellConfig(opts: SlotShellOptions, model: GameModel, runti
   }
   // 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,
@@ -363,7 +382,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;
 }