@energy8platform/game-engine 0.37.0 → 0.39.0

package/dist/slot.d.ts

@@ -366,6 +366,14 @@ declare function easingByName(name?: string): EasingFunction;
 
 /** Names of easing functions available in the engine's `Easing` map (see anim/easing-map.ts). */
 type EasingName = 'linear' | 'easeInQuad' | 'easeOutQuad' | 'easeInOutQuad' | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic' | 'easeInBack' | 'easeOutBack' | 'easeInOutBack' | 'easeOutBounce' | 'easeInBounce' | 'easeOutElastic' | 'easeInSine' | 'easeOutSine' | 'easeInOutSine';
+/**
+ * A value that is either flat across the board, or per-reel: an array indexed by REEL INDEX
+ * (holes fall back to the scalar default). Used for anticipation timings so a game can make
+ * each successive reel slower than the last.
+ */
+type PerReel<T> = T | (T | undefined)[];
+/** Resolve a `PerReel<T>` for one reel. `undefined` (or a hole in the array) yields `fallback`. */
+declare function perReelValue<T>(value: PerReel<T> | undefined, reel: number, fallback: T): T;
 /** Win-evaluation model. Purely presentational here (affects geometry + highlight), the math lives in Lua. */
 type EvaluationMode = 'lines' | 'ways' | 'anywhere' | 'cluster' | 'megaways' | 'infinity';
 interface GridConfig {
@@ -448,6 +456,21 @@ interface MotionConfig {
     slamStop: boolean;
     /** Symbols visible on a reel tape while spinning (swap/strip). */
     symbolsPerReel: number;
+    /** `cascade-drop`: ms between consecutive cells of ONE reel (top→bottom). Default 24. */
+    cellStagger: number;
+    /** `cascade-drop`: multiplier on `stopStagger` for the per-reel offset. Default 0.4. */
+    reelStaggerFactor: number;
+    /** `cascade-drop`: fall duration as a fraction of `spinUp`. Default 0.6. */
+    dropFallFactor: number;
+}
+/** What a game-supplied `AnticipationConfig.decide` may return instead of a bare reel list. */
+interface AnticipationOverride {
+    /** Reels to anticipate, in the order the progression should ramp. Empty = no anticipation. */
+    reels: number[];
+    /** Speed factor (lower = slower). Scalar, or per-reel indexed by reel index. */
+    slowdown?: PerReel<number>;
+    /** Extra hold before landing. Scalar, or per-reel indexed by reel index. */
+    holdMs?: PerReel<number>;
 }
 interface AnticipationConfig {
     enabled: boolean;
@@ -461,6 +484,21 @@ interface AnticipationConfig {
     slowdownFactor: number;
     /** Extra hold (ms) before the final anticipation reel lands (300–500 typical). */
     holdMs: number;
+    /**
+     * Game-supplied decision, REPLACING the built-in `triggerSymbols`/`threshold` counting.
+     * Return the reels to anticipate (or an `AnticipationOverride`); `null` / `[]` = no anticipation.
+     * Use this when the trigger is not expressible as "N of symbol X landed" — e.g. "the round is
+     * still alive on every reel so far", or "reel 3 missed its symbol, so let 4 and 5 stop normally".
+     */
+    decide?: ((targetGrid: CellData[][]) => number[] | AnticipationOverride | null) | null;
+    /**
+     * Ramp the slowdown across successive anticipated reels: reel #i of the decision gets
+     * `slowdownFactor * progressiveSlowdown ** i`. 1 = flat (default); < 1 = each reel slower
+     * than the last.
+     */
+    progressiveSlowdown: number;
+    /** Extra hold (ms) added per successive anticipated reel: reel #i gets `holdMs + i * this`. */
+    progressiveHoldMs: number;
     /** Optional grid zoom while anticipating (magnum-opus uses 1.3×). */
     zoom: {
         enabled: boolean;
@@ -701,8 +739,25 @@ interface SpinRunOpts {
     turbo?: boolean;
     /** Reels to slow for anticipation (computed by the ReelSystem from config + targetGrid). */
     anticipateReels?: number[];
-    anticipateSlowdown?: number;
-    anticipateHoldMs?: number;
+    /** Speed factor for anticipated reels (lower = slower). Scalar, or per-reel indexed by reel. */
+    anticipateSlowdown?: PerReel<number>;
+    /** Extra hold (ms) for anticipated reels. Scalar, or per-reel indexed by reel. */
+    anticipateHoldMs?: PerReel<number>;
+    /**
+     * Reels whose tape runs normally but whose landing is NOT handed back. The engine stops and
+     * disposes of the tape as usual and leaves the real cells hidden and unseated; the caller owns
+     * their data and visibility from that point (and `skip()` will not reveal them either).
+     */
+    deferReveal?: number[];
+    /** The resolved schedule, handed over before the first frame runs. Schedule against THESE
+     *  numbers rather than re-deriving `plan()`'s formula. */
+    onPlan?: (plan: ReelStopPlan[]) => void;
+    /** Fires on the frame a reel lands — after its cells are seated, before settle/squash/shake.
+     *  For a deferred reel it still fires (the reel DID stop); nothing was seated. */
+    onReelStop?: (reel: number, plan: ReelStopPlan) => void;
+    /** Fires as each cell takes its landing symbol. In `cascade-drop` this is the per-cell impact
+     *  frame (after the fall, before the squash) — the hook for a per-cell sound or shake. */
+    onCellSeated?: (reel: number, row: number, data: CellData) => void;
 }
 interface ReelStopPlan {
     reel: number;
@@ -714,6 +769,10 @@ interface ReelStopPlan {
         ms: number;
     };
     anticipated: boolean;
+    /** Time-stretch applied to this reel's tape (>= 1, longer = slower). 1 when not anticipated. */
+    slowdown: number;
+    /** True when `deferReveal` withheld this reel's landing (see `SpinRunOpts.deferReveal`). */
+    deferred: boolean;
 }
 declare class SpinEngine {
     private _grid;
@@ -723,6 +782,7 @@ declare class SpinEngine {
     private _killed;
     private _shaking;
     private _temp;
+    private _deferred;
     constructor(grid: ReelGrid, resolve: SymbolResolver, cfg: MotionConfig, win?: WinConfig);
     setConfig(cfg: MotionConfig): void;
     setWin(win: WinConfig): void;
@@ -734,7 +794,7 @@ declare class SpinEngine {
     /** Execute the spin for every reel concurrently. */
     run(data: SpinData, opts?: SpinRunOpts): Promise<void>;
     private _runReel;
-    /** Anticipation time-stretch factor for a reel (>=1, longer = slower). */
+    /** Anticipation time-stretch factor for a reel (>=1, longer = slower). Resolved in `plan()`. */
     private slowOf;
     private _runSwap;
     private _runStrip;
@@ -750,10 +810,13 @@ declare class SpinEngine {
 
 interface AnticipationDecision {
     active: boolean;
-    /** Reel indices that should spin slower / longer. */
+    /** Reel indices that should spin slower / longer, in the order the ramp applies. */
     reels: number[];
-    slowdown: number;
-    holdMs: number;
+    /** Speed factor. A scalar when flat; a per-reel array when the decision ramps (see
+     *  `progressiveSlowdown` / a game-supplied `decide`). Resolve with `perReelValue`. */
+    slowdown: PerReel<number>;
+    /** Extra hold before landing. Scalar or per-reel array, same as `slowdown`. */
+    holdMs: PerReel<number>;
 }
 declare class AnticipationController {
     private _cfg;
@@ -767,6 +830,13 @@ declare class AnticipationController {
      * is flagged for the slow treatment (this mirrors "searching for the last scatter").
      */
     decide(targetGrid: CellData[][]): AnticipationDecision;
+    /** Assemble a decision, applying the configured progression unless the caller pinned values. */
+    private build;
+    /**
+     * A flat scalar when the progression is a no-op, else an array INDEXED BY REEL so the engine can
+     * read a per-reel value straight out of `plan()`.
+     */
+    private ramp;
     /** Optionally zoom the grid in while anticipating, then settle back. Returns a reset fn. */
     zoomIn(grid: ReelGrid): Promise<() => Promise<void>>;
 }
@@ -947,6 +1017,14 @@ interface ReelSystem {
     /** Replace the whole config. */
     setConfig(config: ReelSystemConfig): void;
     spin(target: CellData[][], opts?: SpinRunOpts): Promise<void>;
+    /**
+     * The schedule `spin(target, opts)` WOULD run, without running it — same anticipation decision,
+     * same numbers. Schedule landing sounds / camera moves against this instead of re-deriving the
+     * engine's formula. (`spin`'s `onPlan` hands you the same array once the spin is under way.)
+     */
+    planSpin(target: CellData[][], opts?: SpinRunOpts): ReelStopPlan[];
+    /** The anticipation decision `spin(target, opts)` would use (run options override the config). */
+    anticipationFor(target: CellData[][], opts?: SpinRunOpts): AnticipationDecision;
     /** 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. */
@@ -1056,5 +1134,5 @@ declare class MultiplierAccumulator {
     reset(boundary: CarryPolicy): void;
 }
 
-export { AnimatedSymbol, AnticipationController, BigWinOverlay, CascadeController, CountUpDisplay, DEFAULT_REEL_CONFIG, EASING_BY_NAME, FEATURES, FEATURE_KEYS, FEATURE_LIST, INTENSITY_SCALE, MultiplierAccumulator, PRESETS, PRESET_LIST, ReelGrid, ReelSpinController, ReelStepController, SpinEngine, SymbolCell, TumbleController, buildReelStepTape, cellPositionOf, createReelSystem, easingByName, effectiveRowsPerReel, mergeReelConfig, pickTier, resolveGeometry, resolveGridGeometry, resolveReelConfig, tierIndexAtValue, valueAt, waysCount };
-export type { AnimatedSymbolConfig, AnticipationConfig, AnticipationDecision, BigWinOverlayConfig, BlurConfig, CarryPolicy, CascadeAnim, CascadeConfig, CascadeStepData, CascadeTimings, CellData, CellFrameStyle, CellSizeSpec, CellState, CountUpConfig, CreateReelSystemOptions, DecorationConfig, DeepPartial, EasingName, EvaluationMode, ExpandingWildConfig, FeatureContext, FeatureKey, FeaturesConfig, GeometryInput, GiantConfig, GridConfig, HoldAndSpinConfig, Intensity, MotionConfig, MotionStyle, MultiplierConfig, MysteryConfig, NudgeConfig, PresetId, RandomWildConfig, ReelFeature, ReelGridConfig, ReelModifierConfig, ReelPreset, ReelSpinData, ReelSpinTimings, ReelStepData, ReelStopPlan$1 as ReelStopPlan, ReelSystem, ReelSystemConfig, ResolvedGeometry, SettleConfig, SpinData, SpinRunOpts, ReelStopPlan as SpinStopPlan, SplitConfig, SquashConfig, StackedConfig, StepRunOpts, StickyConfig, StopMode, StopOrder, SymbolCellConfig, SymbolResolver, SymbolTextures, SymbolView, TransformConfig, TumbleStep, WalkingWildConfig, WinConfig, WinTier };
+export { AnimatedSymbol, AnticipationController, BigWinOverlay, CascadeController, CountUpDisplay, DEFAULT_REEL_CONFIG, EASING_BY_NAME, FEATURES, FEATURE_KEYS, FEATURE_LIST, INTENSITY_SCALE, MultiplierAccumulator, PRESETS, PRESET_LIST, ReelGrid, ReelSpinController, ReelStepController, SpinEngine, SymbolCell, TumbleController, buildReelStepTape, cellPositionOf, createReelSystem, easingByName, effectiveRowsPerReel, mergeReelConfig, perReelValue, pickTier, resolveGeometry, resolveGridGeometry, resolveReelConfig, tierIndexAtValue, valueAt, waysCount };
+export type { AnimatedSymbolConfig, AnticipationConfig, AnticipationDecision, AnticipationOverride, BigWinOverlayConfig, BlurConfig, CarryPolicy, CascadeAnim, CascadeConfig, CascadeStepData, CascadeTimings, CellData, CellFrameStyle, CellSizeSpec, CellState, CountUpConfig, CreateReelSystemOptions, DecorationConfig, DeepPartial, EasingName, EvaluationMode, ExpandingWildConfig, FeatureContext, FeatureKey, FeaturesConfig, GeometryInput, GiantConfig, GridConfig, HoldAndSpinConfig, Intensity, MotionConfig, MotionStyle, MultiplierConfig, MysteryConfig, NudgeConfig, PerReel, PresetId, RandomWildConfig, ReelFeature, ReelGridConfig, ReelModifierConfig, ReelPreset, ReelSpinData, ReelSpinTimings, ReelStepData, ReelStopPlan$1 as ReelStopPlan, ReelSystem, ReelSystemConfig, ResolvedGeometry, SettleConfig, SpinData, SpinRunOpts, ReelStopPlan as SpinStopPlan, SplitConfig, SquashConfig, StackedConfig, StepRunOpts, StickyConfig, StopMode, StopOrder, SymbolCellConfig, SymbolResolver, SymbolTextures, SymbolView, TransformConfig, TumbleStep, WalkingWildConfig, WinConfig, WinTier };

package/dist/slot.esm.js

@@ -1073,6 +1073,14 @@ class ReelSpinController {
 // override only what they need.
 //
 // Design notes are in docs/reels-analysis-and-design.md.
+/** Resolve a `PerReel<T>` for one reel. `undefined` (or a hole in the array) yields `fallback`. */
+function perReelValue(value, reel, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (Array.isArray(value))
+        return value[reel] ?? fallback;
+    return value;
+}
 const FEATURE_KEYS = [
     'reelModifier', // pre-spin
     'giant',
@@ -1118,6 +1126,9 @@ const DEFAULT_REEL_CONFIG = {
         intensity: 'full',
         slamStop: true,
         symbolsPerReel: 6,
+        cellStagger: 24,
+        reelStaggerFactor: 0.4,
+        dropFallFactor: 0.6,
     },
     anticipation: {
         enabled: false,
@@ -1126,6 +1137,9 @@ const DEFAULT_REEL_CONFIG = {
         reels: 'trailing',
         slowdownFactor: 0.3,
         holdMs: 400,
+        decide: null,
+        progressiveSlowdown: 1,
+        progressiveHoldMs: 0,
         zoom: { enabled: false, scale: 1.15, ms: 600 },
     },
     cascade: {
@@ -1252,11 +1266,28 @@ function mergeReelConfig(base, partial) {
 function resolveReelConfig(partial) {
     return mergeReelConfig(DEFAULT_REEL_CONFIG, partial);
 }
+/** True only for `{}`-shaped objects — a class instance or a Date is NOT one. */
+function isCloneableRecord(v) {
+    if (typeof v !== 'object' || v === null || Array.isArray(v))
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Deep-clone a config. Hand-rolled rather than `structuredClone` because a config may carry
+ * functions (`anticipation.decide`), which `structuredClone` refuses to copy. Functions and
+ * anything that is not a plain object/array pass through by reference.
+ */
 function structuredCloneSafe(v) {
-    // structuredClone is available in modern browsers + Node 17+; fall back to JSON for safety.
-    if (typeof structuredClone === 'function')
-        return structuredClone(v);
-    return JSON.parse(JSON.stringify(v));
+    if (Array.isArray(v))
+        return v.map((item) => structuredCloneSafe(item));
+    if (isCloneableRecord(v)) {
+        const out = {};
+        for (const [k, val] of Object.entries(v))
+            out[k] = structuredCloneSafe(val);
+        return out;
+    }
+    return v;
 }
 /** Effective per-reel row counts (resolves Megaways `rowsPerReel`, else uniform `rows`). */
 function effectiveRowsPerReel(grid) {
@@ -1493,6 +1524,7 @@ class SpinEngine {
     _killed = false;
     _shaking = false;
     _temp = [];
+    _deferred = new Set();
     constructor(grid, resolve, cfg, win) {
         this._grid = grid;
         this._resolve = resolve;
@@ -1536,6 +1568,7 @@ class SpinEngine {
         const cols = this._grid.cols;
         const order = (reel) => (this._cfg.stopOrder === 'rtl' ? cols - 1 - reel : reel);
         const anticipate = new Set(opts?.anticipateReels ?? []);
+        const defer = new Set(opts?.deferReveal ?? []);
         const out = [];
         for (let reel = 0; reel < cols; reel++) {
             const idx = order(reel);
@@ -1552,13 +1585,16 @@ class SpinEngine {
                 stopTime = (this._cfg.spinUp + this._cfg.hold + idx * this._cfg.stopStagger) * f;
             const isAnticipated = anticipate.has(reel);
             if (isAnticipated)
-                stopTime += (opts?.anticipateHoldMs ?? 0) * f;
+                stopTime += perReelValue(opts?.anticipateHoldMs, reel, 0) * f;
+            const speed = isAnticipated ? perReelValue(opts?.anticipateSlowdown, reel, 1) : 1;
             out.push({
                 reel,
                 stopTime,
                 landing: data.targetGrid[reel] ?? [],
                 settle: { amp: this._cfg.settle.amp, ms: this._cfg.settle.ms * f },
                 anticipated: isAnticipated,
+                slowdown: Math.max(1, 1 / (speed || 1)),
+                deferred: defer.has(reel),
             });
         }
         return out;
@@ -1568,6 +1604,9 @@ class SpinEngine {
         this._killed = false;
         this._temp = [];
         const plan = this.plan(data, opts);
+        // remembered for skip(): a deferred reel's cells belong to the caller, not to us
+        this._deferred = new Set(plan.filter((p) => p.deferred).map((p) => p.reel));
+        opts?.onPlan?.(plan);
         const f = this.scale(opts);
         await Promise.all(plan.map((p) => this._runReel(p, data, opts, f)));
         this._cleanupTemp();
@@ -1585,9 +1624,9 @@ class SpinEngine {
                 return this._runSwap(p, data, opts, f);
         }
     }
-    /** Anticipation time-stretch factor for a reel (>=1, longer = slower). */
-    slowOf(p, opts) {
-        return p.anticipated ? Math.max(1, 1 / (opts?.anticipateSlowdown ?? 1)) : 1;
+    /** Anticipation time-stretch factor for a reel (>=1, longer = slower). Resolved in `plan()`. */
+    slowOf(p) {
+        return p.slowdown;
     }
     // ── swap: cycle symbols quickly in the real cells, then land ──────────────
     async _runSwap(p, data, opts, f) {
@@ -1598,7 +1637,7 @@ class SpinEngine {
         const blur = this._applyBlur(cells, true);
         const tickMs = 1000 / 30;
         // anticipation makes the reel spin longer before it lands
-        const ticks = Math.max(6, Math.floor((p.stopTime * this.slowOf(p, opts)) / tickMs));
+        const ticks = Math.max(6, Math.floor((p.stopTime * this.slowOf(p)) / tickMs));
         for (let i = 0; i < ticks; i++) {
             if (this._killed)
                 break;
@@ -1607,8 +1646,24 @@ class SpinEngine {
             await Tween.delay(tickMs);
         }
         blur?.();
-        for (let r = 0; r < cells.length; r++)
-            cells[r].setData(p.landing[r] ?? { symbol: null });
+        if (p.deferred) {
+            // the caller owns this reel's result — go dark and unseated instead of handing it back.
+            // NB 'swap' cycles the tape THROUGH the real cells, so a deferred reel only truly withholds
+            // its result when `SpinData.strip` supplies filler for it; otherwise the tape is built from
+            // the landing symbols. 'strip' and 'cascade-drop' have no such caveat.
+            cells.forEach((c) => {
+                c.setData({ symbol: null });
+                c.visible = false;
+            });
+            opts?.onReelStop?.(p.reel, p);
+            return;
+        }
+        for (let r = 0; r < cells.length; r++) {
+            const cell = p.landing[r] ?? { symbol: null };
+            cells[r].setData(cell);
+            opts?.onCellSeated?.(p.reel, r, cell);
+        }
+        opts?.onReelStop?.(p.reel, p);
         await this._settle(p.reel, p.settle, f);
         await this._frameShake(p.landing);
     }
@@ -1643,7 +1698,7 @@ class SpinEngine {
         this._grid.addChild(tape);
         this._temp.push(tape);
         const clearBlur = this._applyBlur([tape], true);
-        const slow = this.slowOf(p, opts);
+        const slow = this.slowOf(p);
         // overshoot/settle honour the configured settle (amp in px, easing)
         const overshoot = p.settle.amp || step * 0.18;
         await Tween.to(tape, { y: restY + overshoot }, p.stopTime * slow, easingByName('easeInOutQuad'));
@@ -1653,12 +1708,21 @@ class SpinEngine {
         }
         clearBlur?.();
         await Tween.to(tape, { y: restY }, Math.max(120, p.settle.ms), easingByName(this._cfg.settle.easing));
-        // hand the result back to the real cells
-        for (let r = 0; r < rows; r++)
-            realCells[r].setData(p.landing[r] ?? { symbol: null });
-        realCells.forEach((c) => (c.visible = true));
+        // hand the result back to the real cells — unless the caller deferred the reveal, in which
+        // case the tape simply goes away and the reel is left dark, unseated and owned by the caller
+        if (!p.deferred) {
+            for (let r = 0; r < rows; r++) {
+                const cell = p.landing[r] ?? { symbol: null };
+                realCells[r].setData(cell);
+                opts?.onCellSeated?.(p.reel, r, cell);
+            }
+            realCells.forEach((c) => (c.visible = true));
+        }
         tape.destroy();
         this._temp = this._temp.filter((t) => t !== tape);
+        opts?.onReelStop?.(p.reel, p);
+        if (p.deferred)
+            return;
         // squash the real cells on impact when enabled
         if (this._cfg.squash.enabled)
             await Promise.all(realCells.map((c) => this._squashCell(c, f)));
@@ -1667,22 +1731,36 @@ class SpinEngine {
     // ── cascade-drop: symbols drop in from above with stagger + bounce + squash ─
     async _runDrop(p, opts, f) {
         const rows = this._grid.rowsOf(p.reel);
+        if (p.deferred) {
+            // nothing to drop — the caller brings this reel in itself
+            for (let r = 0; r < rows; r++)
+                this._grid.getCell(p.reel, r).visible = false;
+            opts?.onReelStop?.(p.reel, p);
+            return;
+        }
         const step = this._grid.cellPosition(p.reel, 1).y - this._grid.cellPosition(p.reel, 0).y;
-        const slow = this.slowOf(p, opts); // anticipation drops the reel in more slowly
+        const slow = this.slowOf(p); // anticipation drops the reel in more slowly
         await Promise.all(Array.from({ length: rows }, (_, r) => r).map(async (r) => {
             if (this._killed)
                 return;
             const cell = this._grid.getCell(p.reel, r);
             const to = this._grid.cellPosition(p.reel, r);
-            cell.setData(p.landing[r] ?? { symbol: null });
+            const data = p.landing[r] ?? { symbol: null };
+            cell.setData(data);
             cell.position.set(to.x, to.y - step * (rows + 1));
             cell.alpha = 1;
-            const delay = (p.reel * this._cfg.stopStagger * 0.4 + r * 24) * f * slow;
+            const delay = (p.reel * this._cfg.stopStagger * this._cfg.reelStaggerFactor +
+                r * this._cfg.cellStagger) *
+                f *
+                slow;
             if (delay)
                 await Tween.delay(delay);
-            await Tween.to(cell, { 'position.y': to.y }, this._cfg.spinUp * 0.6 * f * slow, easingByName(this._cfg.settle.easing));
+            await Tween.to(cell, { 'position.y': to.y }, this._cfg.spinUp * this._cfg.dropFallFactor * f * slow, easingByName(this._cfg.settle.easing));
+            // the impact frame — fired before the squash so a game can sync its own hit feedback
+            opts?.onCellSeated?.(p.reel, r, data);
             await this._squashCell(cell, f);
         }));
+        opts?.onReelStop?.(p.reel, p);
         await this._frameShake(p.landing);
     }
     // ── shared helpers ────────────────────────────────────────────────────────
@@ -1746,13 +1824,17 @@ class SpinEngine {
         Tween.killTweensOf(this._grid);
         this._grid.x = 0; // undo any in-flight frame shake
         for (let c = 0; c < this._grid.cols; c++) {
+            // a deferred reel's visibility belongs to the caller — a slam stop must not reveal it
+            const deferred = this._deferred.has(c);
             for (let r = 0; r < this._grid.rowsOf(c); r++) {
                 const cell = this._grid.getCell(c, r);
                 if (cell.destroyed)
                     continue;
                 Tween.killTweensOf(cell);
-                cell.visible = true;
-                cell.alpha = 1;
+                if (!deferred) {
+                    cell.visible = true;
+                    cell.alpha = 1;
+                }
                 cell.filters = [];
                 cell.scale.set(1);
             }
@@ -1765,6 +1847,8 @@ class SpinEngine {
 //
 // Decides which trailing reels get the "anticipation" slow-down treatment, based purely on
 // the already-resolved landing grid (presentation only — never a secondary outcome decision).
+/** Fresh "nothing to anticipate" decision (fresh, so callers may mutate `reels` freely). */
+const none = () => ({ active: false, reels: [], slowdown: 1, holdMs: 0 });
 class AnticipationController {
     _cfg;
     constructor(cfg) {
@@ -1788,19 +1872,23 @@ class AnticipationController {
      */
     decide(targetGrid) {
         if (!this._cfg.enabled)
-            return { active: false, reels: [], slowdown: 1, holdMs: 0 };
+            return none();
+        // A game-supplied predicate replaces the symbol counting entirely.
+        if (this._cfg.decide) {
+            const custom = this._cfg.decide(targetGrid);
+            if (!custom)
+                return none();
+            const o = Array.isArray(custom) ? { reels: custom } : custom;
+            if (!o.reels?.length)
+                return none();
+            return this.build(o.reels.slice(), o.slowdown, o.holdMs);
+        }
         if (Array.isArray(this._cfg.reels)) {
             // explicit reel list — arm only if the threshold is met somewhere on the board
             const total = targetGrid.reduce((sum, reel) => sum + this.countOnReel(reel), 0);
-            const active = total >= this._cfg.threshold;
-            return active
-                ? {
-                    active,
-                    reels: this._cfg.reels.slice(),
-                    slowdown: this._cfg.slowdownFactor,
-                    holdMs: this._cfg.holdMs,
-                }
-                : { active: false, reels: [], slowdown: 1, holdMs: 0 };
+            if (total < this._cfg.threshold)
+                return none();
+            return this.build(this._cfg.reels.slice());
         }
         // 'trailing': find the reel where the cumulative count hits the threshold
         let running = 0;
@@ -1813,13 +1901,37 @@ class AnticipationController {
             }
         }
         if (armReel < 0)
-            return { active: false, reels: [], slowdown: 1, holdMs: 0 };
+            return none();
         const reels = [];
         for (let c = armReel + 1; c < targetGrid.length; c++)
             reels.push(c);
         if (reels.length === 0)
-            return { active: false, reels: [], slowdown: 1, holdMs: 0 };
-        return { active: true, reels, slowdown: this._cfg.slowdownFactor, holdMs: this._cfg.holdMs };
+            return none();
+        return this.build(reels);
+    }
+    /** Assemble a decision, applying the configured progression unless the caller pinned values. */
+    build(reels, slowdown, holdMs) {
+        return {
+            active: true,
+            reels,
+            slowdown: slowdown ??
+                this.ramp(reels, this._cfg.slowdownFactor, (base, i) => i === 0 ? base : base * Math.pow(this._cfg.progressiveSlowdown, i)),
+            holdMs: holdMs ??
+                this.ramp(reels, this._cfg.holdMs, (base, i) => base + this._cfg.progressiveHoldMs * i),
+        };
+    }
+    /**
+     * A flat scalar when the progression is a no-op, else an array INDEXED BY REEL so the engine can
+     * read a per-reel value straight out of `plan()`.
+     */
+    ramp(reels, base, at) {
+        if (at(base, 1) === base)
+            return base;
+        const out = [];
+        reels.forEach((reel, i) => {
+            out[reel] = at(base, i);
+        });
+        return out;
     }
     /** Optionally zoom the grid in while anticipating, then settle back. Returns a reset fn. */
     async zoomIn(grid) {
@@ -2871,6 +2983,33 @@ function createReelSystem(opts) {
     function ctx(freeSpins) {
         return { grid, resolve, cfg: config, fx, board, freeSpins, log };
     }
+    /**
+     * Which reels get the anticipation treatment for this spin. An explicit `anticipateReels` on the
+     * run options WINS over the configured decision — passing it is how a game drives anticipation
+     * from its own logic. Omit it and the configured `AnticipationController` decides.
+     */
+    function resolveAnticipation(target, runOpts) {
+        const explicit = runOpts?.anticipateReels;
+        if (!explicit)
+            return anticipation.decide(target);
+        if (!explicit.length)
+            return { active: false, reels: [], slowdown: 1, holdMs: 0 };
+        return {
+            active: true,
+            reels: explicit.slice(),
+            slowdown: runOpts?.anticipateSlowdown ?? config.anticipation.slowdownFactor,
+            holdMs: runOpts?.anticipateHoldMs ?? config.anticipation.holdMs,
+        };
+    }
+    /** Fold a resolved decision back onto the caller's run options (everything else passes through). */
+    function mergeAnticipation(runOpts, decision) {
+        return {
+            ...runOpts,
+            anticipateReels: decision.active ? decision.reels : undefined,
+            anticipateSlowdown: decision.slowdown,
+            anticipateHoldMs: decision.holdMs,
+        };
+    }
     buildGrid();
     const api = {
         view,
@@ -2913,20 +3052,22 @@ function createReelSystem(opts) {
         update(partial) {
             api.setConfig(mergeReelConfig(config, partial));
         },
+        anticipationFor(target, runOpts) {
+            return resolveAnticipation(target, runOpts);
+        },
+        planSpin(target, runOpts) {
+            const decision = resolveAnticipation(target, runOpts);
+            return spin.plan({ targetGrid: target }, mergeAnticipation(runOpts, decision));
+        },
         async spin(target, runOpts) {
             const data = { targetGrid: target };
-            const decision = anticipation.decide(target);
+            const decision = resolveAnticipation(target, runOpts);
             let resetZoom = null;
             if (decision.active) {
                 log?.(`Anticipation on reels [${decision.reels.join(', ')}]`);
                 resetZoom = await anticipation.zoomIn(grid);
             }
-            await spin.run(data, {
-                ...runOpts,
-                anticipateReels: decision.active ? decision.reels : undefined,
-                anticipateSlowdown: decision.slowdown,
-                anticipateHoldMs: decision.holdMs,
-            });
+            await spin.run(data, mergeAnticipation(runOpts, decision));
             if (resetZoom)
                 await resetZoom();
             board = target;
@@ -3171,5 +3312,5 @@ class MultiplierAccumulator {
     }
 }
 
-export { AnimatedSymbol, AnticipationController, BigWinOverlay, CascadeController, CountUpDisplay, DEFAULT_REEL_CONFIG, EASING_BY_NAME, FEATURES, FEATURE_KEYS, FEATURE_LIST, INTENSITY_SCALE, MultiplierAccumulator, PRESETS, PRESET_LIST, ReelGrid, ReelSpinController, ReelStepController, SpinEngine, SymbolCell, TumbleController, buildReelStepTape, cellPositionOf, createReelSystem, easingByName, effectiveRowsPerReel, mergeReelConfig, pickTier, resolveGeometry, resolveGridGeometry, resolveReelConfig, tierIndexAtValue, valueAt, waysCount };
+export { AnimatedSymbol, AnticipationController, BigWinOverlay, CascadeController, CountUpDisplay, DEFAULT_REEL_CONFIG, EASING_BY_NAME, FEATURES, FEATURE_KEYS, FEATURE_LIST, INTENSITY_SCALE, MultiplierAccumulator, PRESETS, PRESET_LIST, ReelGrid, ReelSpinController, ReelStepController, SpinEngine, SymbolCell, TumbleController, buildReelStepTape, cellPositionOf, createReelSystem, easingByName, effectiveRowsPerReel, mergeReelConfig, perReelValue, pickTier, resolveGeometry, resolveGridGeometry, resolveReelConfig, tierIndexAtValue, valueAt, waysCount };
 //# sourceMappingURL=slot.esm.js.map