@energy8platform/game-engine 0.17.0 → 0.19.0

package/src/host/shellConfig.ts

@@ -0,0 +1,384 @@
+// 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 {
+  PixiShellConfig, ShellMode, CurrencyConfig, GameInfoContent, GameInfoSection, PaytableRow,
+  BonusOption, ShellFeatures, GameMode,
+} from '@energy8platform/pixi-shell';
+import type { GameModel } from '@energy8platform/platform-core/game-spec';
+import type { WinTier } from '../slot';
+
+export interface SlotShellOptions {
+  /** 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
+   *  section REPLACES the derived one of the same `type`/`kind`; a new `type` is appended; derived
+   *  sections without an override are kept).
+   *
+   *  Pass a plain `GameInfoContent`, OR a function `(t) => GameInfoContent` where `t` is the
+   *  social-aware translator (it rewrites restricted gambling words when in social mode, and is the
+   *  identity otherwise) — wrap player-facing copy in `t(...)` so it socializes. Either way the
+   *  merged result is also run through `socialize` in social mode as a safety net, so forbidden
+   *  words never leak even if `t()` was forgotten. */
+  gameInfo?: GameInfoContent | ((t: (text: string) => string) => GameInfoContent);
+  /** Override the derived buy/ante options. In social mode the card copy is socialized too. */
+  buyBonus?: BonusOption[];
+  tiers?: WinTier[];
+  features?: Partial<ShellFeatures>;
+}
+
+/** The currency metadata surfaced on `initData.config.currency` (game-sdk `CurrencyMetaData`).
+ *  Built by the Stake bridge via `lookupCurrency(code)` from the authoritative `CURRENCY_META`
+ *  table — the single source of truth for symbol/decimals/placement. */
+export interface CurrencyMeta {
+  code: string;
+  symbol: string;
+  decimals: number;
+  symbolAfter?: boolean;
+}
+
+/** Runtime context from the SDK handshake (initData) + the resolved mode. */
+export interface ShellRuntime {
+  balance: number;
+  /** Resolved shell currency, derived from `initData.config.currency` (the SAME meta the Stake
+   *  bridge builds). Pass a full `CurrencyConfig` — see `resolveCurrency`. */
+  currency?: CurrencyConfig;
+  language?: string;
+  mode: ShellMode;
+  /** Social-casino mode from initData (`config.socialMode`); swaps shell vocabulary. */
+  social?: boolean;
+  /** Stake-required disclaimer lines from initData (`config.disclaimerLines`); when
+   *  absent (non-stake/dev) no disclaimer section is rendered. */
+  disclaimerLines?: string[];
+  /** Jurisdiction flags from initData (`config.jurisdiction`). Restrict shell features — applied
+   *  OVER the author's features so a jurisdiction restriction always wins. */
+  jurisdiction?: JurisdictionRestrictions;
+  /** Bet ladder from `/wallet/authenticate` (`initData.config.betLevels`, major units). Stake ladders
+   *  are CURRENCY-SPECIFIC (us_/non_us_/social_), so this overrides the spec's static `betLevels` on a
+   *  Stake launch; falls back to the spec on dev/devBridge. */
+  betLevels?: number[];
+  /** Per-currency default bet from `/wallet/authenticate` (the bridge surfaces it as
+   *  `config.stake.defaultBetLevel`). Stake requires the selector to start here on every entry. */
+  defaultBet?: number;
+}
+
+/** The subset of Stake's jurisdiction flags the shell can enforce via `ShellFeatures`. */
+export interface JurisdictionRestrictions {
+  /** No turbo at all → `features.turbo = 0`. */
+  disabledTurbo?: boolean;
+  /** Basic turbo allowed, but no super-turbo → cap `features.turbo` at 1. */
+  disabledSuperTurbo?: boolean;
+  /** No spacebar quick-spin → `features.spacebar = false`. */
+  disabledSpacebar?: boolean;
+  /** No autoplay → `features.autoplay = null`. */
+  disabledAutoplay?: boolean;
+  /** No buy-feature → `features.buyBonus = false`. */
+  disabledBuyFeature?: boolean;
+}
+
+/**
+ * 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).
+ */
+export function applyJurisdiction(features: ShellFeatures, j?: JurisdictionRestrictions): void {
+  if (!j) return;
+  if (j.disabledTurbo) features.turbo = 0;
+  else if (j.disabledSuperTurbo && features.turbo > 1) features.turbo = 1;
+  if (j.disabledSpacebar) features.spacebar = false;
+  if (j.disabledAutoplay) features.autoplay = null;
+  if (j.disabledBuyFeature) features.buyBonus = false;
+}
+
+/**
+ * Resolve the shell `CurrencyConfig` from the SAME data the Stake bridge uses — the
+ * `CurrencyMetaData` it puts on `initData.config.currency` (symbol + placement from
+ * `symbolAfter`). No second symbol table lives here.
+ *
+ * Fallback chain (dev/devBridge with no Stake meta): `initData.config.currency`
+ * → the spec's currency `code` (neutral `{ symbol: code, position: 'left' }`)
+ * → `{ symbol: '€', position: 'left' }`.
+ */
+/** Extra precision for WIN / TOTAL-WIN readouts so small-bet wins (e.g. 0.0041 on a 0.01 bet) are
+ *  not rounded away to 0.00. Balance / bet stay at the currency's own decimals (`minDecimals`). */
+const WIN_MAX_DECIMALS = 4;
+
+/** Attach decimals: `minDecimals` (balance/bet/prices, fixed) = the currency's decimals; `maxDecimals`
+ *  (win/total-win, variable, trailing zeros trimmed) = up to WIN_MAX_DECIMALS — but only when the
+ *  currency actually has fraction digits (a 0-decimal currency like JPY keeps wins integer). */
+function withDecimals(base: { symbol: string; position: 'left' | 'right' }, decimals: number): CurrencyConfig {
+  return {
+    ...base,
+    minDecimals: decimals,
+    maxDecimals: decimals > 0 ? Math.max(decimals, WIN_MAX_DECIMALS) : 0,
+  };
+}
+
+export function resolveCurrency(meta?: CurrencyMeta | null, specCurrency?: string): CurrencyConfig {
+  const hasMeta = !!(meta && meta.symbol);
+  // Single expression, no early-return branches (the bundler was treeshaking the meta branch away).
+  const symbol = hasMeta ? meta!.symbol : (specCurrency || '€');
+  const position: 'left' | 'right' = hasMeta && meta!.symbolAfter ? 'right' : 'left';
+  const decimals = hasMeta && typeof meta!.decimals === 'number' ? meta!.decimals : 2;
+  return withDecimals({ symbol, position }, decimals);
+}
+
+/** Total stake for an action = bet × the action's cost multiplier (1 for a base spin; e.g. 100 for
+ *  a buy bonus). The host uses this to block a play the balance can't cover. */
+export function stakeForAction(model: GameModel, action: string, bet: number): number {
+  const cost = (model.spec.actions?.[action]?.cost ?? 1) as number;
+  return cost * bet;
+}
+
+/** Derive shell buy cards + ante toggles from the spec's buy/feature actions (SSOT). */
+export function toBonusOptions(model: GameModel): BonusOption[] {
+  const out: BonusOption[] = [];
+  for (const [key, action] of Object.entries(model.spec.actions)) {
+    const role = action.role ?? 'base';
+    if (role !== 'buy' && role !== 'feature') continue;
+    out.push({
+      id: key,
+      type: role === 'buy' ? 'bonus' : 'feature',
+      title: action.title ?? key.replace(/_/g, ' ').toUpperCase(),
+      description: action.description ?? '',
+      priceMultiplier: action.cost ?? (role === 'buy' ? 100 : 1),
+    });
+  }
+  return out;
+}
+
+/** Build a paytable section from the model's derived paytable view (multipliers per symbol count). */
+function paytableSection(model: GameModel): GameInfoSection | null {
+  const symbols = model.paytable?.symbols ?? [];
+  const rows: PaytableRow[] = [];
+  for (const s of symbols) {
+    const wins = Object.entries(s.pay ?? {})
+      .map(([count, multiplier]) => ({ count: String(count), multiplier: Number(multiplier) }))
+      .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 });
+  }
+  if (!rows.length) return null;
+  return { type: 'paytable', title: 'PAYTABLE', rows };
+}
+
+/** Build a "wins" illustration section sized to the grid; `kind` follows the spec mechanic hint. */
+function winsSection(model: GameModel): GameInfoSection {
+  const { cols, rows } = model.spec.grid;
+  const grid = { cols, rows };
+  switch (model.spec.mechanic) {
+    case 'cluster':
+      return { type: 'wins', kind: 'cluster', minCount: 5, grid } as GameInfoSection;
+    case 'ways':
+      return { type: 'wins', kind: 'ways', grid } as GameInfoSection;
+    default:
+      return { type: 'wins', kind: 'anywhere', minCount: 3, grid } as GameInfoSection;
+  }
+}
+
+/** Title of the legal disclaimer section — used to build it and to exempt it from socialization. */
+const DISCLAIMER_TITLE = 'DISCLAIMER';
+
+/** A disclaimer section from initData's disclaimer lines; null when none supplied. */
+function disclaimerSection(lines?: string[]): GameInfoSection | null {
+  const clean = (lines ?? []).map((l) => l.trim()).filter(Boolean);
+  if (!clean.length) return null;
+  const html = clean.map((l) => `<p>${l}</p>`).join('');
+  return { type: 'custom', title: DISCLAIMER_TITLE, html };
+}
+
+/** The legal disclaimer must be shown verbatim — this identifies it so socialization skips it. */
+function isDisclaimerSection(s: GameInfoSection): boolean {
+  return s.type === 'custom' && (s as { title?: string }).title === DISCLAIMER_TITLE;
+}
+
+/** Move the legal disclaimer to the very END of the section list — it must always render last,
+ *  regardless of where an author merge or an extra section would otherwise place it. */
+function orderDisclaimerLast(sections: GameInfoSection[]): GameInfoSection[] {
+  const disclaimer = sections.filter(isDisclaimerSection);
+  if (!disclaimer.length) return sections;
+  return [...sections.filter((s) => !isDisclaimerSection(s)), ...disclaimer];
+}
+
+/**
+ * Pure: derive a maximal default GameInfoContent from the model + runtime so every game
+ * 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.
+ */
+export function defaultGameInfo(model: GameModel, runtime: ShellRuntime): GameInfoContent {
+  const sections: GameInfoSection[] = [];
+  sections.push(winsSection(model));
+  const pay = paytableSection(model);
+  if (pay) sections.push(pay);
+  const modes = modesSection(model);
+  if (modes) sections.push(modes);
+  sections.push({ type: 'controls' });
+  const disclaimer = disclaimerSection(runtime.disclaimerLines);
+  if (disclaimer) sections.push(disclaimer);
+  return { sections };
+}
+
+/** Per-mode info table (BASE / ANTE / each buy tier) derived from the spec's modes — the SAME SSOT
+ *  (`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 {
+  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, ' ')),
+      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;
+    return row;
+  });
+  return { type: 'modes', title: 'MODES', modes: rows };
+}
+
+/** Identity key for merge. `wins` is keyed by `kind` (different mechanics coexist). `custom` has
+ *  no structural discriminant and several can coexist (MAX WIN, DISCLAIMER, …) so it is keyed by
+ *  its `title` (an author `custom` with a matching title replaces that derived block; a new title
+ *  is added). Every other type is a singleton keyed by `type`. */
+function sectionKey(s: GameInfoSection): string {
+  if (s.type === 'wins') return `wins:${s.kind}`;
+  if (s.type === 'custom') return `custom:${s.title ?? ''}`;
+  return s.type;
+}
+
+/**
+ * Merge author `gameInfo` over the host-derived set by section identity: an author section
+ * REPLACES the derived section of the same identity (same `type`, or same `wins` `kind`); a new
+ * identity is APPENDED (after the derived ones, in author order); derived sections without an
+ * author override are KEPT. `override` undefined → the pure derived set.
+ */
+export function mergeGameInfo(derived: GameInfoContent, override?: GameInfoContent): GameInfoContent {
+  if (!override) return derived;
+  const authorByKey = new Map<string, GameInfoSection>();
+  for (const s of override.sections ?? []) authorByKey.set(sectionKey(s), s);
+
+  const out: GameInfoSection[] = [];
+  const used = new Set<string>();
+  // Keep derived order; swap in the author's version where identities collide.
+  for (const s of derived.sections ?? []) {
+    const k = sectionKey(s);
+    const replacement = authorByKey.get(k);
+    if (replacement) { out.push(replacement); used.add(k); }
+    else out.push(s);
+  }
+  // Append author sections whose identity wasn't in the derived set, in author order.
+  for (const s of override.sections ?? []) {
+    const k = sectionKey(s);
+    if (!used.has(k)) { out.push(s); used.add(k); }
+  }
+  return { sections: out };
+}
+
+/** Run a section's player-facing text through `socialize`. Applied to the full MERGED set
+ *  (host-derived + author) in social mode. Covers section titles, custom HTML, and PAYTABLE row
+ *  symbol labels — the paytable's symbol text comes straight from the gameSpec's `symbols[].name`,
+ *  so a forbidden word in a spec symbol name is rewritten here too. A `node`-based custom section is
+ *  returned untouched — its DOM is author-owned and not introspected. */
+function socializeSection(s: GameInfoSection): GameInfoSection {
+  const next = { ...s } as GameInfoSection;
+  if ('title' in next && typeof next.title === 'string') {
+    (next as { title?: string }).title = socialize(next.title);
+  }
+  if (next.type === 'custom' && typeof next.html === 'string') {
+    (next as { html?: string }).html = socialize(next.html);
+  }
+  if (next.type === 'paytable' && Array.isArray((next as { rows?: PaytableRow[] }).rows)) {
+    (next as { rows: PaytableRow[] }).rows = (next as { rows: PaytableRow[] }).rows.map((r) =>
+      typeof r.symbol?.text === 'string'
+        ? { ...r, symbol: { ...r.symbol, text: socialize(r.symbol.text) } }
+        : r,
+    );
+  }
+  if (next.type === 'modes' && Array.isArray((next as { modes?: GameMode[] }).modes)) {
+    (next as { modes: GameMode[] }).modes = (next as { modes: GameMode[] }).modes.map((m) => ({
+      ...m,
+      title: socialize(m.title),
+      ...(m.description ? { description: socialize(m.description) } : {}),
+    }));
+  }
+  return next;
+}
+
+/** Socialize buy-bonus card copy (title/description) when in social mode; a no-op otherwise.
+ *  Applied to the final option set (author override or spec-derived) so forbidden words in author
+ *  card copy are rewritten too. */
+function socializeBonusOptions(options: BonusOption[], isSocial: boolean): BonusOption[] {
+  if (!isSocial) return options;
+  return options.map((o) => ({ ...o, title: socialize(o.title), description: socialize(o.description) }));
+}
+
+/** 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.
+  const defaultBet = runtime.defaultBet ?? model.spec.defaultBet ?? betLevels[0];
+  // runtime.currency is the resolved CurrencyConfig (derived from initData.config.currency by the
+  // 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 ? socialize : (text: string) => text;
+  const authored = typeof opts.gameInfo === 'function' ? opts.gameInfo(t) : opts.gameInfo;
+  let gameInfo = mergeGameInfo(defaultGameInfo(model, runtime), 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) {
+    gameInfo = {
+      sections: (gameInfo.sections ?? []).map((s) => (isDisclaimerSection(s) ? s : socializeSection(s))),
+    };
+  }
+  // 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);
+  // Features: defaults, then author overrides, THEN jurisdiction restrictions (a restriction wins).
+  const features: ShellFeatures = {
+    turbo: 0,
+    spacebar: true,
+    autoplay: {},
+    buyBonus,
+    ...(opts.features ?? {}),
+  } as ShellFeatures;
+  applyJurisdiction(features, runtime.jurisdiction);
+  return {
+    language: runtime.language ?? 'en',
+    isSocial,
+    currency,
+    gameInfo,
+    availableBets: [...betLevels],
+    defaultBet,
+    currentBet: defaultBet,
+    balance: runtime.balance,
+    win: 0,
+    mode: runtime.mode,
+    features,
+  };
+}

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/slotPlay.ts

@@ -0,0 +1,62 @@
+import type { SlotSpinResultBase, SlotResultNormalizer } from '@energy8platform/platform-core/slot-result';
+
+export interface SlotPlayDeps<T extends SlotSpinResultBase> {
+  play(params: { action: string; bet: number; roundId?: string }): Promise<unknown>;
+  normalize: SlotResultNormalizer<T>;
+  onWin?: (totalWin: number) => void;
+  /** Host hook to acknowledge a finished result (PlatformSession.playAck). Called by `ack()`
+   *  with the raw host result of the most recent play. On Stake this is what settles the round
+   *  (`/wallet/end-round`) AFTER the win animation — so the scene must call `ack()` once it has
+   *  finished presenting each result. */
+  ack?: (raw: unknown) => void;
+}
+
+/** A bound play/ack pair the host uses to drive the play loop (createSlotGame → runRound). */
+export interface SlotPlay<T extends SlotSpinResultBase> {
+  /** play → normalize → onWin(totalWin) → return T. Pass `roundId` to advance an in-flight round
+   *  (drain the next segment of a multi-segment bonus) instead of starting a new one. */
+  play(action: string, bet: number, roundId?: string): Promise<T>;
+  /** Acknowledge the most recent result (call AFTER its animation). Settles the round on Stake. */
+  ack(): void;
+}
+
+/**
+ * Enrich a normalized result with round-continuation metadata (roundId / nextActions / complete)
+ * read from the raw play result, so a caller can drain the remaining segments of a multi-segment
+ * round by replaying the SAME roundId. The game's normalizer stays focused on render data. Shared by
+ * `createSlotPlay` (normal play) and the host's resume path (draining a recovered open round).
+ */
+export function enrichRoundMeta<T extends SlotSpinResultBase>(result: T, raw: unknown): T {
+  const meta = (raw ?? {}) as {
+    roundId?: string;
+    nextActions?: string[];
+    session?: { completed?: boolean } | null;
+  };
+  result.roundId = meta.roundId;
+  result.nextActions = meta.nextActions;
+  // A round is complete when there is no open session, or the session reports completed. The host
+  // sets a session on every segment, so this is `session.completed` in practice.
+  result.complete = !meta.session || meta.session.completed === true;
+  return result;
+}
+
+/** Build the host play/ack pair. Host-agnostic wiring; unit-testable. The returned `play` stashes
+ *  the raw host result so the matching `ack()` can forward it to `deps.ack` (PlatformSession.playAck)
+ *  once the scene has finished animating. Plays are sequential (awaited), so a single stash is safe. */
+export function createSlotPlay<T extends SlotSpinResultBase>(
+  deps: SlotPlayDeps<T>,
+): SlotPlay<T> {
+  let lastRaw: unknown = null;
+  return {
+    play: async (action, bet, roundId) => {
+      const raw = await deps.play({ action, bet, roundId });
+      lastRaw = raw;
+      const result = enrichRoundMeta(deps.normalize(raw), raw);
+      deps.onWin?.(result.totalWin);
+      return result;
+    },
+    ack: () => {
+      if (lastRaw != null) deps.ack?.(lastRaw);
+    },
+  };
+}

package/src/host/types.ts

@@ -0,0 +1,74 @@
+// packages/game-engine/src/host/types.ts
+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 { 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';
+import type { SlotShellOptions } from './shellConfig';
+import type { SlotSpinResultBase, SlotResultNormalizer } from '@energy8platform/platform-core/slot-result';
+
+export interface StakeIntegration {
+  /** The game's BookAdapter (or its module). modeMap + gameId come from the model. */
+  adapter: BookAdapter | AdapterModule;
+}
+
+/** One scene registered with the host: a key + its constructor. The list order matters — the
+ *  first scene that is eligible for the current launch mode is the start scene (unless an explicit
+ *  `startScene` overrides it). */
+export interface SceneRegistration {
+  key: string;
+  scene: SceneConstructor;
+  /** Skip this scene as a START scene on a replay launch (e.g. an intro). It is still registered
+   *  (other scenes can `goto` it), it just isn't auto-started — the first non-skipped scene is. */
+  skipOnReplay?: boolean;
+}
+
+/** @deprecated alias kept for one release — use {@link SceneRegistration}. */
+export type SceneEntry = SceneRegistration;
+
+/** Navigation injected into the start data of EVERY scene the host registers.
+ *  Any scene (intro, game, …) reads it from its `onEnter(data)` to navigate. */
+export interface SceneNavData {
+  /** Switch to another registered scene by key. */
+  goto: (key: string, data?: unknown) => void;
+}
+
+export interface CreateSlotGameOptions<T extends SlotSpinResultBase = SlotSpinResultBase> {
+  model: GameModel;
+  /** REQUIRED: maps the raw play result into the game's typed result. The host calls it on every play. */
+  normalize: SlotResultNormalizer<T>;
+  /** ALL scenes the game uses, registered up front, in order. The first scene eligible for the
+   *  launch mode is the start scene — so a replay launch skips any leading `skipOnReplay` scene
+   *  (e.g. the intro) and starts directly on the game scene. */
+  scenes: SceneRegistration[];
+  /** Optional explicit start scene key. Defaults to the first scene eligible for the launch mode
+   *  (honoured only when that scene is itself eligible; otherwise the first eligible one wins). */
+  startScene?: string;
+  /** Start data passed to the start scene's `onEnter` (merged with the injected `goto`). */
+  startData?: unknown;
+  manifest: AssetManifest;
+  container?: HTMLElement | string;
+  design?: { width: number; height: number };
+  scaleMode?: ScaleMode;
+  orientation?: Orientation;
+  loading?: LoadingScreenConfig;
+  audio?: AudioConfig;
+  pixi?: Partial<ApplicationOptions>;
+  fonts?: string[];
+  textureDefaults?: boolean;
+  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: PixiGameShell | null;
+}

package/src/scenes/IntroScene.ts

@@ -0,0 +1,66 @@
+// packages/game-engine/src/scenes/IntroScene.ts
+import { Container, Graphics, Text } from 'pixi.js';
+import { Scene } from '../core/Scene';
+
+export interface IntroSceneConfig {
+  title?: string;
+  logo?: string;          // texture alias (optional; title text is the default)
+  tapToStart?: boolean;   // default true
+  /** Where to navigate on tap. Defaults to the conventional 'game' key. */
+  next?: string;
+  /** Optional explicit start callback. Takes precedence over `goto(next)`. */
+  onStart?: () => void;
+}
+
+/**
+ * Reusable splash scene: shows a title (or logo) + "tap to start", then advances.
+ *
+ * The host no longer special-cases the intro. Navigation works like every other
+ * scene: the host injects `goto(key)` into this scene's start data. On tap this
+ * scene calls `onStart` if the game supplied one, otherwise `goto(next ?? 'game')`.
+ * (The built-in can't know the game's scene key generically, so it falls back to
+ * the conventional 'game' key — override via `next`. Scaffold-generated intros
+ * skip this primitive and call `goto('game')` directly.)
+ */
+export class IntroScene extends Scene {
+  private layer?: Container;
+
+  async onEnter(data?: unknown): Promise<void> {
+    const cfg = (data ?? {}) as IntroSceneConfig & { goto?: (key: string, data?: unknown) => void };
+    const start = () =>
+      cfg.onStart ? cfg.onStart() : cfg.goto?.(cfg.next ?? 'game');
+    const layer = new Container();
+    this.layer = layer;
+    this.container.addChild(layer);
+
+    const title = new Text({
+      text: cfg.title ?? 'PLAY',
+      style: { fill: 0xffffff, fontSize: 96, fontFamily: 'Inter', align: 'center' },
+    });
+    title.anchor.set(0.5);
+    title.position.set(960, 460);
+    layer.addChild(title);
+
+    if (cfg.tapToStart !== false) {
+      const hint = new Text({
+        text: 'Tap to start',
+        style: { fill: 0xffd24a, fontSize: 36, fontFamily: 'Inter' },
+      });
+      hint.anchor.set(0.5);
+      hint.position.set(960, 600);
+      layer.addChild(hint);
+    }
+
+    // full-screen tap target
+    const hit = new Graphics().rect(0, 0, 1920, 1080).fill({ color: 0x000000, alpha: 0.001 });
+    hit.eventMode = 'static';
+    hit.cursor = 'pointer';
+    hit.once('pointerdown', () => start());
+    layer.addChild(hit);
+  }
+
+  onExit(): void {
+    this.layer?.destroy({ children: true });
+    this.layer = undefined;
+  }
+}

package/src/shell/index.ts

@@ -0,0 +1,20 @@
+// Re-export the renderer-agnostic branded game shell from platform-core so
+// game-engine consumers can import it via @energy8platform/game-engine/shell.
+export {
+  createGameShell,
+  removeGameShell,
+  GameShell,
+} from '@energy8platform/platform-core/shell';
+export type {
+  ShellConfig,
+  ShellMode,
+  ShellFeatures,
+  ShellState,
+  ShellEvents,
+  BonusOption,
+  CurrencyConfig,
+  ThemeConfig,
+  GameInfoContent,
+  AutoplayOptions,
+  FreeSpinsState,
+} from '@energy8platform/platform-core/shell';