@energy8platform/game-engine 0.33.7 → 0.33.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@energy8platform/game-engine",
-  "version": "0.33.7",
+  "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/balanceGate.ts

@@ -4,21 +4,24 @@
  * The wallet emits balance changes at two moments: the DEBIT lands when `play()` is called (before
  * the scene animates), and the CREDIT (win) lands when the round settles — `/wallet/end-round`
  * fires asynchronously AFTER the final segment's ack, i.e. after `present()`. The HUD-timing rule is
- * "balance updates only after present()", so:
- *   - while a segment is between `beginPlay()` and `afterPresent()`, balance changes are BUFFERED
- *     (the debit must not flash before the animation),
- *   - `afterPresent()` paints the latest buffered value (the debit),
- *   - any later change (the async win credit) paints immediately, because the gate is open again.
+ * "the stake leaves your balance the instant you spin; the win is only added after the animation":
+ *   - a DEBIT (balance goes DOWN) paints IMMEDIATELY, even between `beginPlay()` and
+ *     `afterPresent()` — the player must see the stake deducted the moment they press spin,
+ *   - a CREDIT (balance goes UP) that lands DURING that window is BUFFERED — the win must not
+ *     update the balance before the animation plays out,
+ *   - `afterPresent()` flushes any buffered credit,
+ *   - a credit that lands after the window (the usual case — end-round settles after the final ack)
+ *     paints immediately, because the gate is open again.
  *
  * `balance` always reflects the true latest wallet value (regardless of gating) so an affordability
  * guard can read it. Pure + unit-testable: the shell paint is injected.
  */
 export interface BalanceGate {
-  /** Record a wallet balance change. Paints it now unless a present is in flight. */
+  /** Record a wallet balance change. Debits paint now; a credit mid-present waits for afterPresent. */
   onBalance(amount: number): void;
-  /** A play() was issued — suppress painting until the matching afterPresent() (debit must wait). */
+  /** A play() was issued — buffer credits until the matching afterPresent() (debits still paint). */
   beginPlay(): void;
-  /** A segment finished animating — paint the latest balance and re-open the gate. */
+  /** A segment finished animating — flush any buffered credit and re-open the gate. */
   afterPresent(): void;
   /** The latest wallet balance, painted or not (for affordability checks). */
   readonly balance: number;
@@ -26,17 +29,25 @@ export interface BalanceGate {
 
 export function createBalanceGate(paint: (amount: number) => void, initial = 0): BalanceGate {
   let latest = initial;
+  let painted = initial;
   let suppressed = false;
+  const show = (amount: number): void => {
+    painted = amount;
+    paint(amount);
+  };
   return {
     onBalance(amount: number): void {
       latest = amount;
-      if (!suppressed) paint(amount);
+      // During play→present, hold a CREDIT (balance rising) back so the win doesn't post before the
+      // animation. A DEBIT (balance falling — the stake) always paints now: spin deducts instantly.
+      if (suppressed && amount > painted) return;
+      show(amount);
     },
     beginPlay(): void {
       suppressed = true;
     },
     afterPresent(): void {
-      paint(latest);
+      if (latest !== painted) show(latest); // flush a credit that landed mid-present
       suppressed = false;
     },
     get balance(): number {

package/src/host/createSlotGame.ts

@@ -245,10 +245,11 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
     // (hidden over the intro / non-slot scenes). Applies in BOTH base and replay modes.
     shell.setVisible(!!gameScene());
     game.scenes.on('change', () => shell!.setVisible(!!gameScene()));
-    // The gate tracks the live wallet (for the affordability guard) but only PAINTS the balance per
-    // the HUD-timing rule: the debit is buffered during play→present and shown at afterPresent; the
-    // 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`.
+    // The gate tracks the live wallet (for the affordability guard) and PAINTS the balance per the
+    // HUD-timing rule: the debit paints immediately (the stake leaves the balance on spin); a win
+    // credit landing during play→present is held to afterPresent so it doesn't post before the
+    // animation; the async 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: { balance: number }) => {
       balanceGate.onBalance(d.balance);
@@ -297,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),
@@ -305,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() {
@@ -542,7 +550,8 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
       // animation has finished — returning void would reopen it instantly, over a running animation.
       return runRound<T>(
         {
-          // Suppress the debit paint from play() until this segment's afterPresent (HUD timing).
+          // Open the play→present window: the debit still paints immediately, but a win credit that
+          // lands mid-animation is held until afterPresent (HUD timing).
           play: (a, b, rid) => {
             balanceGate.beginPlay();
             return slotPlay.play(a, b, rid);
@@ -560,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();
@@ -579,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);
         });
     };
@@ -625,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
@@ -653,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}`);