@energy8platform/game-engine 0.33.8 → 0.33.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@energy8platform/game-engine",
-  "version": "0.33.8",
+  "version": "0.33.9",
   "description": "Universal casino game engine built on PixiJS v8 and @energy8platform/game-sdk",
   "type": "module",
   "main": "./dist/index.cjs.js",
@@ -94,7 +94,7 @@
   },
   "dependencies": {
     "@energy8platform/platform-core": ">=0.30.1",
-    "@energy8platform/shell": ">=0.6.0"
+    "@energy8platform/shell": ">=0.6.6"
   },
   "peerDependencies": {
     "@energy8platform/game-sdk": "^2.9.0",

package/src/host/createSlotGame.ts

@@ -298,6 +298,12 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
       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 import('./winReporter');
+    const winReporter = createWinReporter((amount, opts) => shell!.setWin(amount, opts));
+
     // Capabilities injected once per controller scene via onCreate (see `gameScene`/`ensureCreated`).
     sceneApi = {
       audio: createSceneAudio(game.audio),
@@ -306,6 +312,7 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
         get safeArea() {
           return shell!.safeArea;
         },
+        reportWin: winReporter.report,
       },
       formatAmount: (v) => shell!.formatWin(v),
       get bet() {
@@ -562,12 +569,15 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
             // 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.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.close();
             shell!.setWin(r.totalWin - prevWin);
             prevWin = r.totalWin;
             balanceGate.afterPresent();
@@ -581,6 +591,7 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
         .catch(showPlayError)
         .finally(() => {
           presenting = false;
+          winReporter.close(); // also closes the window when a segment threw mid-flight
           shell!.setBusy(false);
         });
     };
@@ -627,11 +638,13 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
           shell!.setMode(bonusShellMode);
         }
         shell!.setWin(0, { animate: false }); // clear WIN before this segment animates (see playRound)
+        if (animate) winReporter.open(); // a fast-forward drain doesn't present → no reports expected
         if (animate) await scene.onSpin(r, ctx);
         if (inBonus) {
           const v = fsView(raw, r.totalWin);
           if (v) applyBonusReadout(r, v, ctx.mode);
         }
+        winReporter.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
@@ -655,6 +668,7 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
           shell!.setWin(r.totalWin);
         }
       } finally {
+        winReporter.close(); // also closes the window when a drained segment threw
         shell!.setBusy(false);
       }
     };

package/src/host/index.ts

@@ -25,6 +25,9 @@ export type {
   SlotSceneController, RenderContext, SceneApi, SceneAudio, SceneOverlay, SceneShell,
   OverlayShowOptions, AutoplaySceneState,
 } from './sceneController';
+// Progressive (cascade/tumble) WIN readout — the gate behind `api.shell.reportWin`.
+export { createWinReporter } from './winReporter';
+export type { WinReporter, WinReportOptions } from './winReporter';
 // Social-casino word-swap. The shell auto-socializes all gameInfo/buyBonus text in social mode;
 // authors only need this to socialize strings they render themselves (e.g. inside a custom DOM node).
 export { socialize } from '@energy8platform/shell';

package/src/host/sceneController.ts

@@ -1,5 +1,6 @@
 import type { Container } from 'pixi.js';
 import type { SlotSpinResultBase } from '@energy8platform/platform-core/slot-result';
+import type { WinReportOptions } from './winReporter';
 
 /** Everything a scene needs to render one segment. The host builds it per segment. */
 export interface RenderContext {
@@ -57,6 +58,25 @@ export interface SceneOverlay {
 export interface SceneShell {
   /** Live insets (px). `bottom` = the shell bar height; read inside onResize. */
   readonly safeArea: { top: number; right: number; 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;
 }
 
 export interface AutoplaySceneState {

package/src/host/winReporter.ts

@@ -0,0 +1,57 @@
+/**
+ * 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.
+ */
+export 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;
+}
+
+export 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;
+}
+
+export function createWinReporter(
+  paint: (amount: number, opts?: WinReportOptions) => void,
+): WinReporter {
+  let accepting = false;
+  return {
+    report(amountSoFar: number, opts?: WinReportOptions): void {
+      if (!accepting || !Number.isFinite(amountSoFar)) return;
+      paint(Math.max(0, amountSoFar), opts);
+    },
+    open(): void {
+      accepting = true;
+    },
+    close(): void {
+      accepting = false;
+    },
+    get accepting(): boolean {
+      return accepting;
+    },
+  };
+}

package/src/slot/index.ts

@@ -73,7 +73,7 @@ export { FEATURES, FEATURE_LIST } from './features';
 export type { ReelFeature, FeatureContext } from './features';
 
 export { createReelSystem } from './system/ReelSystem';
-export type { ReelSystem, CreateReelSystemOptions } from './system/ReelSystem';
+export type { ReelSystem, CreateReelSystemOptions, StepRunOpts } from './system/ReelSystem';
 
 export { pickTier, tierIndexAtValue } from './overlay/tiers';
 export type { WinTier } from './overlay/tiers';

package/src/slot/system/ReelSystem.ts

@@ -35,6 +35,19 @@ export interface CreateReelSystemOptions {
   features?: ReelFeature[];
 }
 
+/** Options for a stepped chain (`cascade` / `reelStep`). */
+export interface StepRunOpts<TStep> {
+  turbo?: boolean;
+  /** Carry the running multiplier across free spins (with `cascade.multiplier.persistInFreeSpins`). */
+  freeSpins?: boolean;
+  /**
+   * Fires after each step has settled, with the step's index and the running multiplier AFTER it.
+   * The hook for a step-by-step payout readout: report the win accrued so far to the shell via
+   * `api.shell.reportWin(...)`. Awaited, so an async hook paces the chain.
+   */
+  onStep?: (index: number, step: TStep, multiplier: number) => void | Promise<void>;
+}
+
 export interface ReelSystem {
   /** Root container — add this to your scene. */
   readonly view: Container;
@@ -52,14 +65,16 @@ export interface ReelSystem {
   /** Replace the whole config. */
   setConfig(config: ReelSystemConfig): void;
   spin(target: CellData[][], opts?: SpinRunOpts): Promise<void>;
-  /** Run a cascade chain. With `freeSpins` + `cascade.multiplier.persistInFreeSpins`, the multiplier carries over instead of resetting. */
-  cascade(steps: TumbleStep[], opts?: { turbo?: boolean; freeSpins?: boolean }): Promise<void>;
+  /** Run a cascade chain. With `freeSpins` + `cascade.multiplier.persistInFreeSpins`, the multiplier
+   *  carries over instead of resetting. Generic in the step type, so `onStep` hands back the game's
+   *  own step (with its per-step win) rather than the bare TumbleStep. */
+  cascade<TStep extends TumbleStep>(steps: TStep[], opts?: StepRunOpts<TStep>): Promise<void>;
   /**
    * Run a ReelStep™ chain: each step pays its winning cells, then scrolls every reel down by
    * `shifts[col]` positions (0 = reel stays put). Multiplier carries over with `freeSpins` +
    * `cascade.multiplier.persistInFreeSpins`, same as `cascade`.
    */
-  reelStep(steps: ReelStepData[], opts?: { turbo?: boolean; freeSpins?: boolean }): Promise<void>;
+  reelStep<TStep extends ReelStepData>(steps: TStep[], opts?: StepRunOpts<TStep>): Promise<void>;
   /** Current running cascade / reel-step multiplier. */
   readonly multiplier: number;
   /** Register a custom feature (or override a built-in by reusing its key). */
@@ -252,6 +267,7 @@ export function createReelSystem(opts: CreateReelSystemOptions): ReelSystem {
       for (let i = 0; i < steps.length; i++) {
         await tumble.step(steps[i], i, cOpts);
         board = steps[i].settledGrid;
+        await cOpts?.onStep?.(i, steps[i], tumble.multiplier);
       }
       if (config.cascade.multiplier.enabled) log?.(`Cascade multiplier ×${tumble.multiplier}`);
     },
@@ -262,6 +278,7 @@ export function createReelSystem(opts: CreateReelSystemOptions): ReelSystem {
       for (let i = 0; i < steps.length; i++) {
         await reelStepCtl.step(steps[i], i, rOpts);
         board = steps[i].settledGrid;
+        await rOpts?.onStep?.(i, steps[i], reelStepCtl.multiplier);
       }
       if (config.cascade.multiplier.enabled)
         log?.(`ReelStep multiplier ×${reelStepCtl.multiplier}`);