@energy8platform/game-engine 0.43.4 → 0.43.5

package/src/host/autoplay.ts

@@ -10,6 +10,12 @@
  * it (a lost connection cut the run short; the spins are still owed, and the shell shows them so
  * the player can resume).
  *
+ * `hold()`/`release()` are a THIRD thing, and not an ending at all: the tab went to the background,
+ * so the host freezes the ticker and no new round may start — but the player did nothing, and the
+ * run must come back by itself when they return. A hold is forgotten the moment anything else ends
+ * the run (`stop`, `halt`, a new `start`), so a run killed by a lost connection or a failed round
+ * while the tab was hidden does not spring back to life on the way in.
+ *
  * Sequential by construction: it awaits each round (incl. its bonus drain) before the next, so
  * there is never more than one round in flight. Pure over injected deps — unit-testable.
  */
@@ -38,6 +44,18 @@ export interface Autoplay {
    * "autoplay stops, and after reconnection the counter is displayed correctly".
    */
   halt(): void;
+  /**
+   * Hold the run for a pause the player did not ask for — the tab went to the background. Halts it
+   * (counter kept) and remembers that it is owed a resume. No-op when no run is active.
+   *
+   * A certification lab reads "the autoplay sequence stops when the Stop button is pressed" as
+   * *only* the Stop button: switching tabs must not end a run. The host still freezes everything
+   * while hidden — this is what makes that freeze temporary rather than terminal.
+   */
+  hold(): void;
+  /** Resume a run `hold()` put on ice, with the spins it still had. No-op unless a hold is
+   *  outstanding — anything that ended the run in the meantime cancels it. */
+  release(): void;
   readonly active: boolean;
   readonly remaining: number;
 }
@@ -46,8 +64,10 @@ export function createAutoplayLoop(deps: AutoplayDeps): Autoplay {
   let active = false;
   let remaining = 0;
   let running = false; // guards against a second concurrent loop
+  let held = false; // a hold() is outstanding — the tab is hidden and the run is owed a resume
 
   const stop = (): void => {
+    held = false;
     if (!active && remaining === 0) return;
     active = false;
     remaining = 0;
@@ -55,6 +75,7 @@ export function createAutoplayLoop(deps: AutoplayDeps): Autoplay {
   };
 
   const halt = (): void => {
+    held = false; // whatever is halting the run outranks a pending hold — see hold()'s doc comment
     if (!active) return; // nothing running — nothing to preserve
     active = false;
     deps.onState({ active: false, remaining });
@@ -66,7 +87,10 @@ export function createAutoplayLoop(deps: AutoplayDeps): Autoplay {
     try {
       while (active && remaining > 0) {
         const action = deps.resolveAction();
-        if (!deps.canAfford(action)) { stop(); return; }
+        if (!deps.canAfford(action)) {
+          stop();
+          return;
+        }
         // Decrement at spin START (so the spin in flight is `total − remaining`), then play it out.
         remaining -= 1;
         deps.onState({ active: true, remaining });
@@ -85,24 +109,41 @@ export function createAutoplayLoop(deps: AutoplayDeps): Autoplay {
     }
   }
 
+  const start = (count: number): void => {
+    if (active || count <= 0) return;
+    held = false; // a run that is starting is no longer one that owes a resume
+    active = true;
+    remaining = count;
+    deps.onState({ active: true, remaining });
+    // `running` bars a SECOND loop, not a new run. After stop(), the round already in flight keeps
+    // animating and the loop stays parked on `await playRound`, so `running` is still true for as
+    // long as that takes — several seconds through a win. Bailing here made the restart a silent
+    // no-op, and silent is what hurt: ShellController.startAutoplay has already lit the disc with
+    // the chosen count, so the player saw autoplay running with a counter that never moved.
+    // The parked loop re-reads `active`/`remaining` on its next turn and simply carries on with
+    // the new budget — no second loop, nothing dropped.
+    if (!running) void loop();
+  };
+
   return {
-    start(count: number): void {
-      if (active || count <= 0) return;
-      active = true;
-      remaining = count;
-      deps.onState({ active: true, remaining });
-      // `running` bars a SECOND loop, not a new run. After stop(), the round already in flight keeps
-      // animating and the loop stays parked on `await playRound`, so `running` is still true for as
-      // long as that takes — several seconds through a win. Bailing here made the restart a silent
-      // no-op, and silent is what hurt: ShellController.startAutoplay has already lit the disc with
-      // the chosen count, so the player saw autoplay running with a counter that never moved.
-      // The parked loop re-reads `active`/`remaining` on its next turn and simply carries on with
-      // the new budget — no second loop, nothing dropped.
-      if (!running) void loop();
-    },
+    start,
     stop,
     halt,
-    get active() { return active; },
-    get remaining() { return remaining; },
+    hold(): void {
+      if (!active) return; // nothing running — nothing to hold, and nothing to bring back
+      halt(); // clears `held`; we set it again below, so only a hold() ever leaves it set
+      held = true;
+    },
+    release(): void {
+      if (!held) return;
+      held = false;
+      start(remaining); // no-op when the remainder is gone (something retired it while hidden)
+    },
+    get active() {
+      return active;
+    },
+    get remaining() {
+      return remaining;
+    },
   };
 }

package/src/host/connectionRecovery.ts

@@ -11,14 +11,21 @@
  * cleared to zero on the way. Reconnecting healed the link but nothing took the screen back down.
  *
  * So, per transition:
- *  - **lost** — halt autoplay (the counter survives, see `autoplay.halt()`) and put up the
- *    reconnect overlay. Repeated `lost` (one per failed reconnect attempt) doesn't restack it.
+ *  - **lost** — halt autoplay (the counter survives the drop, see `autoplay.halt()`) and put up
+ *    the reconnect overlay. Repeated `lost` (one per failed reconnect attempt) doesn't restack it.
  *  - **lost + `ConnectionGone`** — the bridge gave up retrying. That is terminal and honest about
  *    it: a Reload modal, not a "Reconnecting…" that will never resolve.
- *  - **restored** — take the overlay down and finish what the drop interrupted: if the platform
- *    still holds an open round, play it out silently to settlement. No modal asks the player to
- *    confirm this — it is their own round, they already paid for it, and an extra screen here is
- *    the very thing the remark objected to.
+ *  - **restored** — reset autoplay, take the overlay down, and finish what the drop interrupted:
+ *    if the platform still holds an open round, play it out silently to settlement. No modal asks
+ *    the player to confirm this — it is their own round, they already paid for it, and an extra
+ *    screen here is the very thing the remark objected to.
+ *
+ * Why halt on the way down but reset on the way up: while the link is down the run is stopped yet
+ * its remaining spins are still the player's, so the counter must keep showing them rather than
+ * snap to zero (the lab's original finding was exactly "the autoplay counter is reset"). Once the
+ * link is back, Artube wants the run **over**, not parked one tap from resuming: a run the player
+ * ordered before a network drop must not carry on across it, and the player re-orders autoplay
+ * deliberately. So `restored` clears the counter and the disc goes back to a plain SPIN.
  *
  * A `restored` that never followed a `lost` does nothing at all: it must not close a modal that
  * belongs to someone else.
@@ -35,8 +42,12 @@ export interface ConnectionState {
 }
 
 export interface ConnectionRecoveryDeps {
-  /** Stop an autoplay run WITHOUT clearing its counter (`Autoplay.halt`). */
+  /** Stop an autoplay run WITHOUT clearing its counter (`Autoplay.halt`) — used while the link
+   *  is down, so the spins still owed stay on screen. */
   haltAutoplay(): void;
+  /** End the run and clear its counter (`Autoplay.stop`) — used once the link is back: autoplay
+   *  does not survive a reconnect. */
+  resetAutoplay(): void;
   /** Put up the blocking "Reconnecting…" overlay. */
   showReconnecting(): void;
   /** Put up the terminal "the connection is gone — reload" modal. */
@@ -106,6 +117,9 @@ export function createConnectionRecovery(deps: ConnectionRecoveryDeps): Connecti
 
       if (!linkLost) return; // nothing of ours is on screen; nothing of ours to recover
       linkLost = false;
+      // The run does not resume across a reconnect. Like the halt above, this runs even when a
+      // modal owns the screen — the counter must not outlive the drop that ended the run.
+      deps.resetAutoplay();
       if (!blocked()) deps.dismiss();
       await recover();
     },

package/src/host/createSlotGame.ts

@@ -506,6 +506,8 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
     let playErrorOpen = false;
     let stopAutoplay: () => void = () => {}; // wired to the autoplay loop once it's created (below)
     let haltAutoplay: () => void = () => {}; // ditto — stops the run but KEEPS its counter
+    let holdAutoplay: () => void = () => {}; // ditto — pauses the run, owing it a resume
+    let releaseAutoplay: () => void = () => {}; // ditto — gives back a run that hold() paused
     const reload = () => {
       try {
         window.location.reload();
@@ -549,6 +551,9 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
     const { createConnectionRecovery } = await import('./connectionRecovery');
     const connection = createConnectionRecovery({
       haltAutoplay: () => haltAutoplay(),
+      // A reconnect ends the run for good (Artube): the counter the halt preserved while the link
+      // was down is cleared here, and the disc goes back to a plain SPIN.
+      resetAutoplay: () => stopAutoplay(),
       showReconnecting: () =>
         shell!.openModal({
           availableClose: false,
@@ -595,8 +600,10 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
     game.scenes.root.on('pointertap', () => skip.tap(performance.now()));
 
     // Full auto-pause: on tab blur, freeze the ticker (stops tweens/onUpdate/in-flight onSpin),
-    // duck music to silence, hold autoplay, and notify the scene. On focus, reverse it all.
-    // `stopAutoplay` is reassigned in the base-mode block below — the closure reads it live.
+    // duck music to silence, hold autoplay, and notify the scene. On focus, reverse it all —
+    // autoplay included: a tab switch is not the player pressing STOP.
+    // `holdAutoplay`/`releaseAutoplay` are reassigned in the base-mode block below — the closures
+    // read them live.
     const { createPauseController } = await import('./pauseController');
     createPauseController({
       isHidden: () => typeof document !== 'undefined' && document.hidden,
@@ -608,12 +615,19 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
       onHidden: () => {
         game.app.ticker.stop(); // freezes tweens, onUpdate, in-flight onSpin animation
         game.audio.duckMusic(0); // silence music (ducked to 0; restored on resume)
-        stopAutoplay(); // hold autoplay — don't start the next auto-round
+        // Hold, don't stop. No auto-round may start while the tab is hidden (the ticker is frozen,
+        // so an animation would never finish, and a play fired here spends the player's money out
+        // of sight) — but the run is owed back: the lab reads "the autoplay sequence stops when the
+        // Stop button is pressed" as ONLY the Stop button, and stopAutoplay() here ended the run and
+        // zeroed its counter on every alt-tab. `hold()` forgets itself if anything else ends the run
+        // meanwhile (a lost connection, a failed round), so those don't come back on the way in.
+        holdAutoplay();
         gameScene()?.onPause?.();
       },
       onVisible: () => {
         game.app.ticker.start();
         game.audio.unduckMusic();
+        releaseAutoplay(); // the run the blur paused picks up where it left off
         gameScene()?.onResume?.();
       },
     });
@@ -849,6 +863,8 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
       });
       stopAutoplay = () => autoplay.stop();
       haltAutoplay = () => autoplay.halt();
+      holdAutoplay = () => autoplay.hold();
+      releaseAutoplay = () => autoplay.release();
       shell.on('autoplayStart', (o: { remaining?: number }) => autoplay.start(o?.remaining ?? 0));
       shell.on('autoplayStop', () => autoplay.stop());