@energy8platform/game-engine 0.33.6 → 0.33.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@energy8platform/game-engine",
-  "version": "0.33.6",
+  "version": "0.33.8",
   "description": "Universal casino game engine built on PixiJS v8 and @energy8platform/game-sdk",
   "type": "module",
   "main": "./dist/index.cjs.js",

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);
@@ -542,7 +543,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);