@energy8platform/game-engine 0.29.0 → 0.31.0

package/dist/host.cjs.js

@@ -2270,10 +2270,19 @@ async function createSlotGame(opts) {
                 availableClose: false,
                 title: shell.t('Something went wrong'),
                 body: shell.t(message),
-                actions: [{ title: shell.t('Reload'), on: () => { try {
-                            location.reload();
-                        }
-                        catch { /* non-browser */ } } }],
+                actions: [
+                    {
+                        title: shell.t('Reload'),
+                        on: () => {
+                            try {
+                                location.reload();
+                            }
+                            catch {
+                                /* non-browser */
+                            }
+                        },
+                    },
+                ],
             });
             return;
         }
@@ -2403,7 +2412,9 @@ async function createSlotGame(opts) {
                 const { lookupCurrency } = await import('@energy8platform/stake-bridge');
                 currencyMeta = lookupCurrency(opts.model.spec.currency);
             }
-            catch { /* stake-bridge not installed — resolveCurrency falls back to the code */ }
+            catch {
+                /* stake-bridge not installed — resolveCurrency falls back to the code */
+            }
         }
         const runtime = {
             balance,
@@ -2430,7 +2441,11 @@ async function createSlotGame(opts) {
         // pixi-shell mounts its root onto the engine's unscaled, screen-space UI layer (above the
         // scaled world/scene root) so the control bar fills the real screen, not the letterboxed game.
         // The host adds the mount target (`app`) + parent; buildShellConfig produces everything else.
-        const pixiShellCfg = { ...buildShellConfig(opts.shell, opts.model, runtime), app: game.app, parent: game.uiLayer };
+        const pixiShellCfg = {
+            ...buildShellConfig(opts.shell, opts.model, runtime),
+            app: game.app,
+            parent: game.uiLayer,
+        };
         // The game may swap in its own shell (a custom renderer over the same core) via shellFactory;
         // default is the built-in Pixi shell. The host drives whichever it gets through the Shell contract.
         shell = (opts.shellFactory ?? createPixiShell)(pixiShellCfg);
@@ -2443,10 +2458,15 @@ async function createSlotGame(opts) {
         // async win credit (/wallet/end-round, after the final ack) paints when it lands. `balanceGate`
         // is the single source for both the displayed balance and `ensureAffordable`.
         const balanceGate = createBalanceGate((b) => shell.setBalance(b), balance);
-        ps?.on('balanceUpdate', (d) => { balanceGate.onBalance(d.balance); });
+        ps?.on('balanceUpdate', (d) => {
+            balanceGate.onBalance(d.balance);
+        });
         // Live turbo level (0..3) — read fresh on each ctx.turbo access so a mid-round toggle is honoured.
         let currentTurbo = shell.state.turbo;
-        shell.on('turboChange', (level) => { currentTurbo = level; gameScene()?.onTurboChanged?.(level); });
+        shell.on('turboChange', (level) => {
+            currentTurbo = level;
+            gameScene()?.onTurboChanged?.(level);
+        });
         // Double-tap-to-skip is a game-level option (default on), set once via createSlotGame({ skipGesture }).
         const skipEnabled = opts.skipGesture ?? true;
         // Shell settings → engine state. Sound/volume map onto the AudioManager.
@@ -2483,21 +2503,38 @@ async function createSlotGame(opts) {
         sceneApi = {
             audio: createSceneAudio(game.audio),
             overlay: overlayCtl.overlay,
-            shell: { get safeArea() { return shell.safeArea; } },
+            shell: {
+                get safeArea() {
+                    return shell.safeArea;
+                },
+            },
             formatAmount: (v) => shell.formatWin(v),
-            get bet() { return currentBet; },
-            get mode() { return opts.model.modeMap['spin'] ?? 'BASE'; },
-            get turbo() { return currentTurbo; },
+            get bet() {
+                return currentBet;
+            },
+            get mode() {
+                return opts.model.modeMap['spin'] ?? 'BASE';
+            },
+            get turbo() {
+                return currentTurbo;
+            },
         };
         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; },
+            get turbo() {
+                return currentTurbo;
+            },
         });
         // Play-error + connection handling. A play rejection is classified into a player-facing modal
         // (ACTIVE_SESSION_EXISTS → Reload, etc.) instead of a misleading reconnect overlay; the reconnect
@@ -2513,11 +2550,27 @@ async function createSlotGame(opts) {
                 title: shell.t(v.title),
                 body: shell.t(v.body),
                 actions: v.reload
-                    ? [{ title: shell.t('Reload'), on: () => { try {
-                                window.location.reload();
-                            }
-                            catch { /* non-browser */ } } }]
-                    : [{ title: shell.t('OK'), on: () => { playErrorOpen = false; } }],
+                    ? [
+                        {
+                            title: shell.t('Reload'),
+                            on: () => {
+                                try {
+                                    window.location.reload();
+                                }
+                                catch {
+                                    /* non-browser */
+                                }
+                            },
+                        },
+                    ]
+                    : [
+                        {
+                            title: shell.t('OK'),
+                            on: () => {
+                                playErrorOpen = false;
+                            },
+                        },
+                    ],
             });
         };
         ps?.on('connectionStateChanged', (s) => {
@@ -2546,7 +2599,10 @@ async function createSlotGame(opts) {
         const skip = createDoubleTapSkip({
             enabled: () => skipEnabled,
             active: () => presenting,
-            onSkip: () => { currentSegmentAbort?.abort(); gameScene()?.onSkip?.(); },
+            onSkip: () => {
+                currentSegmentAbort?.abort();
+                gameScene()?.onSkip?.();
+            },
         });
         // Listen for taps on the scene root (game.worldRoot — the scaled scene container). The shell
         // lives on the sibling uiLayer, so its bar taps never reach worldRoot — taps here are the play area.
@@ -2576,54 +2632,133 @@ async function createSlotGame(opts) {
                 gameScene()?.onResume?.();
             },
         });
+        /** Push a bonus segment's readout to the shell bar. Default (no `opts.bonus`) = the free-spins
+         *  counter (label 'Free spins', value current/total). With `opts.bonus`, the game supplies the
+         *  label + value string (adventure / hold-and-spin / respins) and we drive the generic 'bonus'
+         *  hero instead — the shell stays free of any per-game bonus concept. */
+        const applyBonusReadout = (result, view, mode) => {
+            const b = opts.bonus;
+            if (!b) {
+                shell.setFreeSpins(view);
+                return;
+            }
+            const label = typeof b.label === 'function' ? b.label(mode) : (b.label ?? 'Free spins');
+            const value = b.readout
+                ? b.readout(result, { view, mode })
+                : view.current == null
+                    ? String(view.total)
+                    : `${view.current} / ${view.total}`;
+            shell.setBonus({ label, value, totalWin: view.totalWin });
+        };
+        /** 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;
+            // 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
             // animation has finished — returning void would reopen it instantly, over a running animation.
             return runRound({
                 // Suppress the debit paint from play() until this segment's afterPresent (HUD timing).
-                play: (a, b, rid) => { balanceGate.beginPlay(); return slotPlay$1.play(a, b, rid); },
+                play: (a, b, rid) => {
+                    balanceGate.beginPlay();
+                    return slotPlay$1.play(a, b, rid);
+                },
                 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; },
+                beforeSegment: (ac) => {
+                    currentSegmentAbort = ac;
+                },
                 onSpinStart: () => scene.onSpinStart?.(),
                 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)
-                        shell.setFreeSpins(fsCounter.spin(r.freeSpins?.awarded ?? 0, r.totalWin));
-                },
-                onEnterMode: async (trigger, ctx) => {
-                    inBonus = true;
-                    shell.setMode('freeSpins');
-                    shell.setFreeSpins(fsCounter.enter(trigger.freeSpins?.awarded ?? trigger.freeSpins?.total ?? 0));
-                    await scene.onEnterMode?.(trigger, ctx);
+                    bonus.settle(r);
                 },
-                onExitMode: async (last, ctx) => {
-                    inBonus = false;
-                    await scene.onExitMode?.(last, ctx);
-                    shell.setMode('base');
-                },
-            }, action).catch(showPlayError).finally(() => { presenting = false; shell.setBusy(false); });
+                onModeEnter: (mode, trigger, ctx, resumed) => bonus.enter(mode, trigger, ctx, resumed),
+                onModeExit: (mode, last, ctx) => bonus.exit(mode, last, ctx),
+            }, action)
+                .catch(showPlayError)
+                .finally(() => {
+                presenting = false;
+                shell.setBusy(false);
+            });
         };
         /**
          * Drain a recovered open round to completion and settle it. Plays EVERY remaining segment from
@@ -2637,7 +2772,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,
@@ -2658,17 +2795,17 @@ 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('freeSpins');
+                    shell.setMode(bonusShellMode);
                 }
                 if (animate)
                     await scene.onSpin(r, ctx);
                 if (inBonus) {
                     const v = fsView(raw, r.totalWin);
                     if (v)
-                        shell.setFreeSpins(v);
+                        applyBonusReadout(r, v, ctx.mode);
                 }
                 shell.setWin(r.totalWin - prevWin); // THIS spin's win, not the cumulative bonus total
                 prevWin = r.totalWin;
@@ -2678,12 +2815,20 @@ async function createSlotGame(opts) {
             try {
                 await applySegment();
                 while (!r.complete && r.nextActions && r.nextActions.length > 0) {
-                    raw = (await ps.play({ action: r.nextActions[0], bet: ctx.bet, roundId: r.roundId }));
+                    raw = (await ps.play({
+                        action: r.nextActions[0],
+                        bet: ctx.bet,
+                        roundId: r.roundId,
+                    }));
                     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);
@@ -2691,8 +2836,12 @@ async function createSlotGame(opts) {
         };
         if (mode === 'base') {
             let activeFeature = null;
-            shell.on('featureActivate', ({ id }) => { activeFeature = id; });
-            shell.on('featureDeactivate', ({ id: _id }) => { activeFeature = null; });
+            shell.on('featureActivate', ({ id }) => {
+                activeFeature = id;
+            });
+            shell.on('featureDeactivate', ({ id: _id }) => {
+                activeFeature = null;
+            });
             const { stakeForAction } = await Promise.resolve().then(function () { return shellConfig; });
             // Guard a play: if the stake exceeds the balance, show a shell modal and DON'T play.
             const ensureAffordable = (action) => {
@@ -2712,7 +2861,10 @@ async function createSlotGame(opts) {
                     return;
                 void playRound(action);
             });
-            shell.on('betChange', (bet) => { currentBet = bet; gameScene()?.onBetChanged?.(bet); });
+            shell.on('betChange', (bet) => {
+                currentBet = bet;
+                gameScene()?.onBetChanged?.(bet);
+            });
             shell.on('buyBonusSelect', ({ id }) => {
                 if (!ensureAffordable(id))
                     return;
@@ -2743,7 +2895,7 @@ async function createSlotGame(opts) {
                 resumeOffered = true;
                 let snap = null;
                 try {
-                    snap = await ps?.getState() ?? null;
+                    snap = (await ps?.getState()) ?? null;
                 }
                 catch {
                     snap = null;
@@ -2756,13 +2908,25 @@ async function createSlotGame(opts) {
                     body: shell.t('You have an unfinished round. Continue it or finish it now?'),
                     actions: [
                         // Continue: replay the round from the start with animation, then settle.
-                        { title: shell.t('Continue'), on: () => { void resumeDrain(snap, true); } },
+                        {
+                            title: shell.t('Continue'),
+                            on: () => {
+                                void resumeDrain(snap, true);
+                            },
+                        },
                         // Finish: fast-forward the remaining segments (no animation) to settle the win now.
-                        { title: shell.t('Finish'), on: () => { void resumeDrain(snap, false); } },
+                        {
+                            title: shell.t('Finish'),
+                            on: () => {
+                                void resumeDrain(snap, false);
+                            },
+                        },
                     ],
                 });
             };
-            game.scenes.on('change', () => { void offerResume(); });
+            game.scenes.on('change', () => {
+                void offerResume();
+            });
             void offerResume();
         }
         else {
@@ -3229,36 +3393,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
 });