@energy8platform/game-engine 0.30.0 → 0.32.0

package/src/core/GameApplication.ts

@@ -241,9 +241,10 @@ export class GameApplication extends EventEmitter<GameEngineEvents> {
 
     const pixiOpts = {
       preference: 'webgl' as const,
-      background: typeof this.config.loading?.backgroundColor === 'number'
-        ? this.config.loading.backgroundColor
-        : 0x000000,
+      background:
+        typeof this.config.loading?.backgroundColor === 'number'
+          ? this.config.loading.backgroundColor
+          : 0x000000,
       antialias: true,
       resolution: Math.min(window.devicePixelRatio, 2),
       autoDensity: true,
@@ -286,8 +287,9 @@ export class GameApplication extends EventEmitter<GameEngineEvents> {
   }
 
   private initSubSystems(): void {
-    // Asset Manager
-    const basePath = this.initData?.assetsUrl ?? '';
+    // Asset Manager. Base defaults to '/' (site root) when the bridge sends no assetsUrl — the
+    // asset folder lives in the manifest paths, not the base, so it needn't be named `assets`.
+    const basePath = this.initData?.assetsUrl ?? '/';
     this.assets = new AssetManager(basePath, this.config.manifest);
 
     // Audio Manager

package/src/host/createSlotGame.ts

@@ -7,7 +7,7 @@ import { showFatalError, installGlobalErrorHandlers } from './fatalError';
 import type { CreateSlotGameOptions, SlotGameHandle } from './types';
 import type { SlotSpinResultBase } from '@energy8platform/platform-core/slot-result';
 import type { ShellMode } from '@energy8platform/shell/pixi';
-import type { SceneApi, SlotSceneController } from './sceneController';
+import type { SceneApi, SlotSceneController, RenderContext } from './sceneController';
 import type { FreeSpinsView } from './freeSpinsCounter';
 
 /**
@@ -319,6 +319,12 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
     };
 
     const roleOf = (action: string) => opts.model.spec.actions[action]?.role;
+    const isBonusAction = (action: string) => roleOf(action) === 'free';
+    // Per-SEGMENT mode string. modeMap intentionally excludes `free` actions (they'd pollute the
+    // Game-Info modes table), so a free segment falls back to its spec `mode` (or the action key).
+    // This is what distinguishes nested bonuses (FREESPINS vs ADVENTURE) at the transition boundary.
+    const segmentModeOf = (action: string) =>
+      opts.model.spec.actions[action]?.mode ?? opts.model.modeMap[action] ?? action.toUpperCase();
     // The signal-less context. runRound injects a per-segment `signal` (for skip); resumeDrain
     // attaches its own. So makeContext returns everything BUT `signal`.
     const makeContext = (
@@ -326,7 +332,7 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
     ): Omit<import('./sceneController').RenderContext, 'signal'> => ({
       bet: currentBet,
       action,
-      mode: opts.model.modeMap[action] ?? action.toUpperCase(),
+      mode: segmentModeOf(action),
       formatAmount: (v) => shell!.formatWin(v),
       get turbo() {
         return currentTurbo;
@@ -450,18 +456,86 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
      *  else 'freeSpins' (the back-compat default the shell already renders). */
     const bonusShellMode: ShellMode = opts.bonus ? 'bonus' : 'freeSpins';
 
+    /** Apply an authoritative book override (freeSpins.total/remaining) onto an accumulated view —
+     *  the host counts by default, but if the book resends the count (e.g. a resumed parent after a
+     *  nested sub-bonus) that wins. */
+    const overrideView = (
+      view: FreeSpinsView,
+      fs?: SlotSpinResultBase['freeSpins'],
+    ): FreeSpinsView => {
+      if (!fs) return view;
+      const total = fs.total ?? view.total;
+      const current = fs.remaining != null ? Math.max(0, total - fs.remaining) : view.current;
+      return { current, total, totalWin: view.totalWin };
+    };
+
+    interface BonusLevel {
+      mode: string;
+      counter: ReturnType<typeof createFreeSpinsCounter>;
+      view: FreeSpinsView;
+    }
+    /** A per-round stack of active bonus levels driving the shell bar as levels push/pop. Supports
+     *  NESTED bonuses (e.g. free spins → adventure → free spins): each level keeps its own counter,
+     *  so a resumed parent restores its remaining count. A single-bonus round pushes once and
+     *  unwinds once — byte-identical to the pre-nesting behaviour. */
+    const createBonusStack = (scene: SlotSceneController<T>) => {
+      const stack: BonusLevel[] = [];
+      return {
+        inBonus: (): boolean => stack.length > 0,
+        /** A bonus level becomes active — a fresh push, or a resumed parent (already on the stack). */
+        async enter(mode: string, trigger: T, ctx: RenderContext, resumed: boolean): Promise<void> {
+          if (resumed) {
+            const lvl = stack[stack.length - 1]; // the parent stayed on the stack; the child popped
+            lvl.view = overrideView(lvl.view, trigger.freeSpins);
+            applyBonusReadout(trigger, lvl.view, lvl.mode);
+          } else {
+            const counter = createFreeSpinsCounter();
+            const view = overrideView(
+              counter.enter(trigger.freeSpins?.awarded ?? trigger.freeSpins?.total ?? 0),
+              trigger.freeSpins,
+            );
+            stack.push({ mode, counter, view });
+            if (stack.length === 1) shell!.setMode(bonusShellMode); // base → bonus
+            applyBonusReadout(trigger, view, mode);
+          }
+          // ctx.mode is overridden to the mode being ENTERED so the scene reads the right level.
+          await scene.onEnterMode?.(trigger, { ...ctx, mode, resumed });
+        },
+        /** A bonus level ends — a nested pop back to its parent, or the last level back to base. */
+        async exit(mode: string, last: T, ctx: RenderContext): Promise<void> {
+          stack.pop();
+          await scene.onExitMode?.(last, { ...ctx, mode });
+          if (stack.length === 0) {
+            shell!.setMode('base');
+            // Back in base the FS "Total win" block is gone, so WIN must carry the round's
+            // CUMULATIVE total (what got credited) — not the last segment's per-spin delta.
+            shell!.setWin(last.totalWin);
+          }
+          // else: an intermediate pop; the following resume-enter (or next exit) re-paints the bar.
+        },
+        /** Advance the active level's counter with a settled segment. */
+        settle(r: T): void {
+          if (stack.length === 0) return;
+          const top = stack[stack.length - 1];
+          top.view = overrideView(
+            top.counter.spin(r.freeSpins?.awarded ?? 0, r.totalWin),
+            r.freeSpins,
+          );
+          applyBonusReadout(r, top.view, top.mode);
+        },
+      };
+    };
+
     /** Drive a full round (trigger + drain) against the current scene. HUD readouts (win + balance)
      *  update only AFTER each onSpin(), per the HUD-timing requirement. */
     const playRound = (action: string) => {
       const scene = gameScene();
       if (!scene) return;
-      // Per-round free-spins state: the shell enters FS mode on bonus-enter and shows current/total
-      // (growing on retriggers) + cumulative win per spin. `inBonus` gates the per-spin counter so
-      // the trigger segment (rendered by onSpin before onEnterMode) doesn't count as a free spin.
-      let inBonus = false;
-      let bonusMode = ''; // the mode string captured on bonus-enter, reused for each settled spin
+      // Per-round bonus stack: the shell enters bonus mode on the first level's push and shows the
+      // active level's counter + cumulative win. The stack handles NESTED bonuses (free spins →
+      // adventure → free spins); a single-bonus round pushes/unwinds once (unchanged).
+      const bonus = createBonusStack(scene);
       let prevWin = 0; // cumulative win up to the previous segment — the WIN readout shows the delta
-      const fsCounter = createFreeSpinsCounter();
       shell!.setBusy(true); // block re-spin / spacebar while the round plays out
       presenting = true; // open the skip window for the whole play→drain
       // RETURN the promise: the replay modal awaits onReplay() and only reopens once the round's
@@ -476,7 +550,8 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
           ack: slotPlay.ack,
           scene,
           context: makeContext,
-          roleOf,
+          modeOf: segmentModeOf,
+          isBonusAction,
           // Hand the host the per-segment AbortController so a double-tap can skip the live segment.
           beforeSegment: (ac) => {
             currentSegmentAbort = ac;
@@ -485,33 +560,14 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
           onSpinEnd: (last, ctx) => scene.onSpinEnd?.(last, ctx),
           afterPresent: (r) => {
             // WIN readout = THIS spin's win (cumulative delta); the cumulative total goes to the
-            // free-spins counter (totalWin) below, not the WIN readout.
+            // bonus counter (totalWin) via settle(), not the WIN readout.
             shell!.setWin(r.totalWin - prevWin);
             prevWin = r.totalWin;
             balanceGate.afterPresent();
-            if (inBonus)
-              applyBonusReadout(
-                r,
-                fsCounter.spin(r.freeSpins?.awarded ?? 0, r.totalWin),
-                bonusMode,
-              );
-          },
-          onEnterMode: async (trigger, ctx) => {
-            inBonus = true;
-            bonusMode = ctx.mode;
-            shell!.setMode(bonusShellMode);
-            applyBonusReadout(
-              trigger,
-              fsCounter.enter(trigger.freeSpins?.awarded ?? trigger.freeSpins?.total ?? 0),
-              bonusMode,
-            );
-            await scene.onEnterMode?.(trigger, ctx);
-          },
-          onExitMode: async (last, ctx) => {
-            inBonus = false;
-            await scene.onExitMode?.(last, ctx);
-            shell!.setMode('base');
+            bonus.settle(r);
           },
+          onModeEnter: (mode, trigger, ctx, resumed) => bonus.enter(mode, trigger, ctx, resumed),
+          onModeExit: (mode, last, ctx) => bonus.exit(mode, last, ctx),
         },
         action,
       )
@@ -536,8 +592,10 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
       const scene = gameScene();
       if (!scene || !ps) return;
       // A recovered drain isn't skippable (no live skip gesture wired to it), so it gets a stable,
-      // never-aborted signal to satisfy onSpin's RenderContext.
-      const ctx: import('./sceneController').RenderContext = {
+      // never-aborted signal to satisfy onSpin's RenderContext. ctx carries the round identity (built
+      // once from the trigger action) — recovery drains a single flat bonus using the bridge session
+      // counts; the full per-level nesting is a LIVE-play concern (playRound).
+      const ctx: RenderContext = {
         ...makeContext((firstRaw as { action?: string }).action ?? 'spin'),
         signal: new AbortController().signal,
       };
@@ -556,7 +614,7 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
       let inBonus = false;
       let prevWin = 0; // cumulative win up to the previous segment — WIN readout shows the delta
       const applySegment = async (): Promise<void> => {
-        // A recovered open round with remaining segments is a bonus → show FS mode + counter.
+        // A recovered open round with remaining segments is a bonus → show bonus mode + counter.
         if (!inBonus && !r.complete) {
           inBonus = true;
           shell!.setMode(bonusShellMode);
@@ -582,7 +640,12 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
           r = enrichRoundMeta(opts.normalize(raw), raw);
           await applySegment();
         }
-        if (inBonus) shell!.setMode('base');
+        if (inBonus) {
+          shell!.setMode('base');
+          // Same as playRound: on return to base the WIN readout must show the round's cumulative
+          // total (r is the final drained segment), not the last segment's per-spin delta.
+          shell!.setWin(r.totalWin);
+        }
       } finally {
         shell!.setBusy(false);
       }

package/src/host/runRound.ts

@@ -5,22 +5,63 @@ 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). */
+  /** Build the render context (without signal — runRound injects it per segment). Called with the
+   *  ROUND action, so `ctx.action`/`ctx.mode` carry the round identity across every drained segment
+   *  (a buy_bonus round's free spins still read as BONUS). Nested-bonus detection uses `modeOf`, not
+   *  `ctx.mode`, and the scene learns level changes via onModeEnter/onModeExit. */
   context(action: string): Omit<RenderContext, 'signal'> & { signal?: AbortSignal };
-  roleOf(action: string): string | undefined;
+  /** Bonus mode string for a segment action (FREESPINS / ADVENTURE / …) — drives nested-bonus
+   *  transition detection. Defaults to `action.toUpperCase()`. */
+  modeOf?(action: string): string;
+  /** True when an action is a bonus (free-play) segment, false for base/trigger segments.
+   *  Omit for base-only games (no bonus transitions ever fire). */
+  isBonusAction?(action: string): boolean;
   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>;
+  /** Fires when a bonus LEVEL becomes active — a fresh push (`resumed=false`) or a return to a
+   *  suspended parent after a nested sub-bonus popped (`resumed=true`). Fires per boundary, so a
+   *  round may enter several levels. `trigger`/`ctx` are the segment that caused the transition. */
+  onModeEnter?(mode: string, trigger: T, ctx: RenderContext, resumed: boolean): Promise<void>;
+  /** Fires when a bonus LEVEL ends (pop) — either descending past it into base, or unwinding at
+   *  round end. Fires once per popped level, top-first. */
+  onModeExit?(mode: string, last: T, ctx: RenderContext): Promise<void>;
   /** Hands the host the AbortController for the segment about to present (for skip). */
   beforeSegment?(ac: AbortController): void;
 }
 
+/** A planned move of the mode stack toward a target (or to base when `target` is null). Pure. */
+export interface TransitionPlan {
+  /** Modes to exit, top-first (each is popped). */
+  exit: string[];
+  /** The level that becomes active after the exits, or null when none (same level, or unwind to
+   *  base). `resumed` distinguishes returning to an existing parent from a fresh push. */
+  enter: { mode: string; resumed: boolean } | null;
+}
+
+/**
+ * Pure: given the CURRENT bonus-mode stack (bottom→top) and the next segment's target mode
+ * (null = a base segment / round end), decide which levels to exit and whether a level enters.
+ *
+ *  - target null            → unwind everything (exit all, top-first).
+ *  - target === top          → same level, no transition.
+ *  - target already deeper   → RESUME: exit the levels above it; it re-activates (resumed).
+ *  - target not on the stack → PUSH: a fresh level enters.
+ *
+ * The caller owns the actual stack array and applies the plan (pop per `exit`, push when
+ * `enter && !resumed`).
+ */
+export function planTransition(stack: readonly string[], target: string | null): TransitionPlan {
+  if (target == null) return { exit: [...stack].reverse(), enter: null };
+  if (stack.length > 0 && stack[stack.length - 1] === target) return { exit: [], enter: null };
+  const depth = stack.lastIndexOf(target);
+  if (depth >= 0)
+    return { exit: stack.slice(depth + 1).reverse(), enter: { mode: target, resumed: true } };
+  return { exit: [], enter: { mode: target, resumed: false } };
+}
+
 export async function runRound<T extends SlotSpinResultBase>(
   deps: RunRoundDeps<T>,
   action: string,
@@ -28,28 +69,48 @@ export async function runRound<T extends SlotSpinResultBase>(
   deps.onSpinStart?.();
 
   const ctxBet = deps.context(action).bet;
+  const modeOf = deps.modeOf ?? ((a: string) => a.toUpperCase());
+  const isBonus = deps.isBonusAction ?? (() => false);
 
-  const segment = async (a: string, roundId: string | undefined): Promise<{ r: T; ctx: RenderContext }> => {
+  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);
+    // ctx carries the ROUND identity (built from the round action), stable across drained segments.
     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;
+  // Active bonus-mode levels (bottom→top). Empty in the base game.
+  const stack: string[] = [];
+  // Emit the exits/enter to move the stack toward `nextAction` (null → unwind to base). Called
+  // BEFORE the target segment presents, with the CURRENT (triggering) r/ctx — mirrors the classic
+  // onEnterMode(trigger) timing so the host reads awarded spins off the segment that granted them.
+  const transition = async (nextAction: string | null, r: T, ctx: RenderContext): Promise<void> => {
+    const target = nextAction != null && isBonus(nextAction) ? modeOf(nextAction) : null;
+    const plan = planTransition(stack, target);
+    for (const mode of plan.exit) {
+      stack.pop();
+      await deps.onModeExit?.(mode, r, ctx);
+    }
+    if (plan.enter) {
+      if (!plan.enter.resumed) stack.push(plan.enter.mode);
+      await deps.onModeEnter?.(plan.enter.mode, r, ctx, plan.enter.resumed);
+    }
+  };
+
+  let { r, ctx } = await segment(action, undefined);
   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);
-    }
+    await transition(next, r, ctx);
     ({ r, ctx } = await segment(next, r.roundId));
   }
-  if (inMode) await deps.onExitMode?.(r, ctx);
+  await transition(null, r, ctx); // round end: unwind any remaining levels to base
   deps.onSpinEnd?.(r, ctx);
 }

package/src/host/sceneController.ts

@@ -13,6 +13,10 @@ export interface RenderContext {
   formatAmount(value: number): string;
   /** LIVE turbo level (0 = off, 1..3 = escalating speed). Read at access. */
   readonly turbo: number;
+  /** Only meaningful in `onEnterMode`: true when RETURNING to a suspended parent bonus after a
+   *  nested sub-bonus finished (e.g. back to free spins after an adventure), false on a fresh
+   *  entry. Lets a scene restore vs rebuild. Undefined outside `onEnterMode`. */
+  resumed?: boolean;
   /** 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;
@@ -82,9 +86,13 @@ export interface SlotSceneController<T extends SlotSpinResultBase = SlotSpinResu
   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). */
+  /** Fires when a bonus LEVEL begins. With nested bonuses this fires once per level (free spins,
+   *  then adventure, …) — check `ctx.mode` for which. `ctx.resumed` is true when returning to a
+   *  suspended parent after a nested sub-bonus finished, so a scene can restore instead of rebuild.
+   *  A single-bonus round fires it exactly once (as before). */
   onEnterMode(result: T, ctx: RenderContext): Promise<void>;
-  /** Fires when leaving a mode (back toward BASE). */
+  /** Fires when a bonus LEVEL ends — popping a nested sub-bonus back to its parent, or unwinding
+   *  the last level back to BASE. `ctx.mode` is the level being left. Fires once per level. */
   onExitMode(result: T, ctx: RenderContext): Promise<void>;
   /** Fires once per round after the full drain (controls unlocked). */
   onSpinEnd(result: T, ctx: RenderContext): void;