@energy8platform/game-engine 0.33.8 → 0.33.9

package/dist/host.d.ts

@@ -956,6 +956,43 @@ declare function resolveReplayBonusId(model: GameModel, stakeMode: string): stri
  */
 declare function resolveStartScene(scenes: SceneRegistration[], isReplay: boolean, explicitStart?: string): string;
 
+/**
+ * Gate for the PROGRESSIVE (cascade / tumble) WIN readout.
+ *
+ * By default the WIN readout is entirely host-driven: cleared to 0 when a segment starts, set to
+ * that segment's win once `onSpin` resolves. A cascade game pays in steps, so its scene wants the
+ * number to climb WHILE the segment presents — `api.shell.reportWin(amountSoFar)`.
+ *
+ * The gate keeps the host in charge:
+ *   - reports are honoured ONLY between `open()` (segment start, WIN already cleared) and `close()`
+ *     (the host paints the segment's final value) — a scene still animating after an abort, or one
+ *     reporting from a mode transition, can't overwrite the host's number,
+ *   - `amountSoFar` is ABSOLUTE (the segment's win up to now, not the step delta), so a re-report or
+ *     a collapse-to-final on skip is idempotent. Reports should be non-decreasing within a segment;
+ *     a lower value counts the readout back DOWN,
+ *   - garbage (NaN / Infinity) is dropped and negatives clamp to 0, so a math bug can't paint "NaN"
+ *     into the bar.
+ *
+ * Pure + unit-testable: the shell paint is injected.
+ */
+interface WinReportOptions {
+    /** `false` snaps instead of counting up (e.g. collapsing to the final value on skip). */
+    animate?: boolean;
+    /** Count-up length in ms (shell default 450) — pass the cascade step's length. */
+    durationMs?: number;
+}
+interface WinReporter {
+    /** Scene-facing (`api.shell.reportWin`): the win accumulated by the presenting segment so far. */
+    report(amountSoFar: number, opts?: WinReportOptions): void;
+    /** A segment starts presenting — the scene may now grow WIN. */
+    open(): void;
+    /** The host takes the readout back (final value, round end, or an error). */
+    close(): void;
+    /** True while reports are honoured. */
+    readonly accepting: boolean;
+}
+declare function createWinReporter(paint: (amount: number, opts?: WinReportOptions) => void): WinReporter;
+
 /** Everything a scene needs to render one segment. The host builds it per segment. */
 interface RenderContext {
     /** Bet for this round (major units). Stable for the whole round. */
@@ -1023,6 +1060,25 @@ interface SceneShell {
         bottom: number;
         left: number;
     };
+    /**
+     * Grow the shell's WIN readout WHILE a segment presents — for cascade/tumble games that pay in
+     * steps instead of one lump at the end.
+     *
+     * `amountSoFar` is ABSOLUTE: the win accumulated by this segment up to now (not the step's
+     * delta), so a re-report, a skip, or an aborted step can just restate the truth. The host owns
+     * the readout around it — it clears WIN to 0 when the segment starts and sets the segment's
+     * final value once `onSpin` resolves (counting up from your last report, so matching numbers
+     * produce no jump). In a bonus this moves WIN only; the Total Win accumulator still lands once
+     * per segment.
+     *
+     * Only honoured while a segment is presenting (inside `onSpin`); calls from anywhere else are
+     * ignored, so a scene still ticking after an abort can't overwrite the host's final number.
+     *
+     * `durationMs` sets this count-up's length (default 450ms) — pass your step length (or a shorter
+     * one under turbo) so each count-up finishes before the next step lands. `{ animate: false }`
+     * snaps, e.g. when collapsing to the final value on skip.
+     */
+    reportWin(amountSoFar: number, opts?: WinReportOptions): void;
 }
 interface AutoplaySceneState {
     running: boolean;
@@ -1070,5 +1126,5 @@ interface SlotSceneController<T extends SlotSpinResultBase = SlotSpinResultBase>
     onResume?(): void;
 }
 
-export { buildShellConfig, createSlotGame, resolveReplayBonusId, resolveStartScene, stakeForAction };
-export type { AutoplaySceneState, CreateSlotGameOptions, OverlayShowOptions, RenderContext, SceneApi, SceneAudio, SceneNavData, SceneOverlay, SceneRegistration, SceneShell, ShellFactory, SlotGameHandle, SlotSceneController, SlotShellOptions, StakeIntegration };
+export { buildShellConfig, createSlotGame, createWinReporter, resolveReplayBonusId, resolveStartScene, stakeForAction };
+export type { AutoplaySceneState, CreateSlotGameOptions, OverlayShowOptions, RenderContext, SceneApi, SceneAudio, SceneNavData, SceneOverlay, SceneRegistration, SceneShell, ShellFactory, SlotGameHandle, SlotSceneController, SlotShellOptions, StakeIntegration, WinReportOptions, WinReporter };

package/dist/host.esm.js

@@ -2501,6 +2501,11 @@ async function createSlotGame(opts) {
             size: () => ({ width: game.app.screen.width, height: game.app.screen.height }),
         });
         game.on('resize', ({ width, height }) => overlayCtl.resize(width, height));
+        // Progressive WIN readout for cascade/tumble scenes. The window is open from the moment a
+        // segment starts (WIN cleared to 0) until the host has painted that segment's final win; outside
+        // it the host owns the readout alone. See winReporter.ts.
+        const { createWinReporter } = await Promise.resolve().then(function () { return winReporter; });
+        const winReporter$1 = createWinReporter((amount, opts) => shell.setWin(amount, opts));
         // Capabilities injected once per controller scene via onCreate (see `gameScene`/`ensureCreated`).
         sceneApi = {
             audio: createSceneAudio(game.audio),
@@ -2509,6 +2514,7 @@ async function createSlotGame(opts) {
                 get safeArea() {
                     return shell.safeArea;
                 },
+                reportWin: winReporter$1.report,
             },
             formatAmount: (v) => shell.formatWin(v),
             get bet() {
@@ -2748,12 +2754,15 @@ async function createSlotGame(opts) {
                     // then counts UP to this segment's delta. prevWin (the cumulative-delta tracker) is
                     // untouched; this only resets the DISPLAY.
                     shell.setWin(0, { animate: false });
+                    winReporter$1.open(); // the scene may now grow WIN per cascade step
                 },
                 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
-                    // bonus counter (totalWin) via settle(), not the WIN readout.
+                    // bonus counter (totalWin) via settle(), not the WIN readout. A scene that reported
+                    // per-step wins already landed on this number, so the count-up is a no-op there.
+                    winReporter$1.close();
                     shell.setWin(r.totalWin - prevWin);
                     prevWin = r.totalWin;
                     balanceGate.afterPresent();
@@ -2765,6 +2774,7 @@ async function createSlotGame(opts) {
                 .catch(showPlayError)
                 .finally(() => {
                 presenting = false;
+                winReporter$1.close(); // also closes the window when a segment threw mid-flight
                 shell.setBusy(false);
             });
         };
@@ -2809,6 +2819,8 @@ async function createSlotGame(opts) {
                     shell.setMode(bonusShellMode);
                 }
                 shell.setWin(0, { animate: false }); // clear WIN before this segment animates (see playRound)
+                if (animate)
+                    winReporter$1.open(); // a fast-forward drain doesn't present → no reports expected
                 if (animate)
                     await scene.onSpin(r, ctx);
                 if (inBonus) {
@@ -2816,6 +2828,7 @@ async function createSlotGame(opts) {
                     if (v)
                         applyBonusReadout(r, v, ctx.mode);
                 }
+                winReporter$1.close();
                 shell.setWin(r.totalWin - prevWin); // THIS spin's win, not the cumulative bonus total
                 prevWin = r.totalWin;
                 ps.playAck(raw); // settles via /wallet/end-round on the FINAL segment
@@ -2840,6 +2853,7 @@ async function createSlotGame(opts) {
                 }
             }
             finally {
+                winReporter$1.close(); // also closes the window when a drained segment threw
                 shell.setBusy(false);
             }
         };
@@ -3369,6 +3383,31 @@ var sceneStart = /*#__PURE__*/Object.freeze({
     resolveStartScene: resolveStartScene
 });
 
+function createWinReporter(paint) {
+    let accepting = false;
+    return {
+        report(amountSoFar, opts) {
+            if (!accepting || !Number.isFinite(amountSoFar))
+                return;
+            paint(Math.max(0, amountSoFar), opts);
+        },
+        open() {
+            accepting = true;
+        },
+        close() {
+            accepting = false;
+        },
+        get accepting() {
+            return accepting;
+        },
+    };
+}
+
+var winReporter = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    createWinReporter: createWinReporter
+});
+
 // packages/game-engine/src/host/index.ts
 
 /**
@@ -3776,5 +3815,5 @@ var autoplay = /*#__PURE__*/Object.freeze({
     createAutoplayLoop: createAutoplayLoop
 });
 
-export { buildShellConfig, createSlotGame, resolveReplayBonusId, resolveStartScene, stakeForAction };
+export { buildShellConfig, createSlotGame, createWinReporter, resolveReplayBonusId, resolveStartScene, stakeForAction };
 //# sourceMappingURL=host.esm.js.map