@energy8platform/game-engine 0.30.0 → 0.31.0

package/dist/host.esm.js

@@ -2519,12 +2519,17 @@ async function createSlotGame(opts) {
             },
         };
         const roleOf = (action) => opts.model.spec.actions[action]?.role;
+        const isBonusAction = (action) => 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) => 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 = (action) => ({
             bet: currentBet,
             action,
-            mode: opts.model.modeMap[action] ?? action.toUpperCase(),
+            mode: segmentModeOf(action),
             formatAmount: (v) => shell.formatWin(v),
             get turbo() {
                 return currentTurbo;
@@ -2647,19 +2652,75 @@ async function createSlotGame(opts) {
         /** The mode entered via setMode for a bonus — 'bonus' when the game customises the readout,
          *  else 'freeSpins' (the back-compat default the shell already renders). */
         const bonusShellMode = 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, fs) => {
+            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 };
+        };
+        /** 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) => {
+            const stack = [];
+            return {
+                inBonus: () => stack.length > 0,
+                /** A bonus level becomes active — a fresh push, or a resumed parent (already on the stack). */
+                async enter(mode, trigger, ctx, resumed) {
+                    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, last, ctx) {
+                    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) {
+                    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) => {
             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
@@ -2673,7 +2734,8 @@ async function createSlotGame(opts) {
                 ack: slotPlay$1.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;
@@ -2682,25 +2744,14 @@ async function createSlotGame(opts) {
                 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)
                 .catch(showPlayError)
                 .finally(() => {
@@ -2720,7 +2771,9 @@ async function createSlotGame(opts) {
             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.
+            // 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 = {
                 ...makeContext(firstRaw.action ?? 'spin'),
                 signal: new AbortController().signal,
@@ -2741,7 +2794,7 @@ async function createSlotGame(opts) {
             let inBonus = false;
             let prevWin = 0; // cumulative win up to the previous segment — WIN readout shows the delta
             const applySegment = async () => {
-                // 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);
@@ -2769,8 +2822,12 @@ async function createSlotGame(opts) {
                     r = enrichRoundMeta(opts.normalize(raw), raw);
                     await applySegment();
                 }
-                if (inBonus)
+                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);
@@ -3335,36 +3392,75 @@ var slotPlay = /*#__PURE__*/Object.freeze({
     enrichRoundMeta: enrichRoundMeta
 });
 
+/**
+ * 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`).
+ */
+function planTransition(stack, target) {
+    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 } };
+}
 async function runRound(deps, action) {
     deps.onSpinStart?.();
     const ctxBet = deps.context(action).bet;
+    const modeOf = deps.modeOf ?? ((a) => a.toUpperCase());
+    const isBonus = deps.isBonusAction ?? (() => false);
     const segment = async (a, roundId) => {
         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 };
         await deps.scene.onSpin(r, ctx);
         deps.ack();
         deps.afterPresent?.(r);
         return { r, ctx };
     };
+    // Active bonus-mode levels (bottom→top). Empty in the base game.
+    const stack = [];
+    // 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, r, ctx) => {
+        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);
-    let inMode = false;
     while (!r.complete && r.nextActions && r.nextActions.length > 0) {
         const next = r.nextActions[0];
-        if (!inMode && deps.roleOf(next) === 'free') {
-            inMode = true;
-            await deps.onEnterMode?.(r, ctx);
-        }
+        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);
 }
 
 var runRound$1 = /*#__PURE__*/Object.freeze({
     __proto__: null,
+    planTransition: planTransition,
     runRound: runRound
 });