@energy8platform/game-engine 0.38.0 → 0.40.0

package/dist/slot.cjs.js

@@ -1075,6 +1075,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',
@@ -1120,6 +1128,11 @@ const DEFAULT_REEL_CONFIG = {
         intensity: 'full',
         slamStop: true,
         symbolsPerReel: 6,
+        cellStagger: 24,
+        reelStaggerFactor: 0.4,
+        dropFallFactor: 0.6,
+        dropOrder: 'top-down',
+        dropSequence: 'parallel',
     },
     anticipation: {
         enabled: false,
@@ -1128,6 +1141,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: {
@@ -1254,11 +1270,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) {
@@ -1495,6 +1528,7 @@ class SpinEngine {
     _killed = false;
     _shaking = false;
     _temp = [];
+    _deferred = new Set();
     constructor(grid, resolve, cfg, win) {
         this._grid = grid;
         this._resolve = resolve;
@@ -1538,6 +1572,8 @@ 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 holds = [];
         const out = [];
         for (let reel = 0; reel < cols; reel++) {
             const idx = order(reel);
@@ -1553,23 +1589,70 @@ class SpinEngine {
             else
                 stopTime = (this._cfg.spinUp + this._cfg.hold + idx * this._cfg.stopStagger) * f;
             const isAnticipated = anticipate.has(reel);
-            if (isAnticipated)
-                stopTime += (opts?.anticipateHoldMs ?? 0) * f;
+            const hold = isAnticipated ? perReelValue(opts?.anticipateHoldMs, reel, 0) * f : 0;
+            stopTime += hold;
+            holds[reel] = hold;
+            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),
             });
         }
+        if (this._cfg.style === 'cascade-drop')
+            this._planDrop(out, holds, f, order);
         return out;
     }
+    /**
+     * `cascade-drop` lays its reels out on a different clock from the tape styles: a reel is a
+     * sequence of per-cell arrivals, not one deceleration. Overwrite `stopTime` with the moment the
+     * reel has fully landed and fill in `cellStopTimes`, so `plan()` stays the single source of truth
+     * for WHEN anything happens — `_runDrop` below only executes these numbers.
+     */
+    _planDrop(out, holds, f, order) {
+        const bottomUp = this._cfg.dropOrder === 'bottom-up';
+        // walk the reels in STOP order, so `stopOrder: 'rtl'` reverses the drop as well
+        const byPosition = [];
+        for (let reel = 0; reel < out.length; reel++)
+            byPosition[order(reel)] = reel;
+        // the position from which reels stop overlapping and start queueing behind each other
+        const chainFrom = this._cfg.dropSequence === 'chained'
+            ? 0
+            : this._cfg.dropSequence === 'chained-when-anticipated'
+                ? byPosition.findIndex((reel) => out[reel].anticipated)
+                : -1;
+        let previousEnd = 0;
+        for (let position = 0; position < byPosition.length; position++) {
+            const p = out[byPosition[position]];
+            const rows = this._grid.rowsOf(p.reel);
+            const scale = f * p.slowdown;
+            const gap = this._cfg.stopStagger * this._cfg.reelStaggerFactor * scale;
+            const fall = this._cfg.spinUp * this._cfg.dropFallFactor * scale;
+            // by formula while reels may overlap; queued behind the previous reel once the chain starts
+            const chained = chainFrom >= 0 && position > 0 && position >= chainFrom;
+            const start = (chained ? previousEnd + gap : position * gap) + (holds[p.reel] ?? 0);
+            const cells = [];
+            for (let i = 0; i < rows; i++) {
+                const row = bottomUp ? rows - 1 - i : i;
+                cells[row] = start + i * this._cfg.cellStagger * scale + fall;
+            }
+            p.cellStopTimes = cells;
+            p.stopTime = cells.length ? Math.max(...cells) : start;
+            previousEnd = p.stopTime;
+        }
+    }
     /** Execute the spin for every reel concurrently. */
     async run(data, opts) {
         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();
@@ -1587,9 +1670,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) {
@@ -1600,7 +1683,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;
@@ -1609,8 +1692,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);
     }
@@ -1645,7 +1744,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'));
@@ -1655,12 +1754,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)));
@@ -1669,22 +1777,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
+        const fall = this._cfg.spinUp * this._cfg.dropFallFactor * f * slow;
+        const schedule = p.cellStopTimes ?? [];
         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;
+            // the plan says WHEN this cell seats; back off the fall to get when it must let go
+            const delay = Math.max(0, (schedule[r] ?? fall) - fall);
             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 }, fall, 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 ────────────────────────────────────────────────────────
@@ -1748,13 +1870,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);
             }
@@ -1767,6 +1893,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) {
@@ -1790,19 +1918,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;
@@ -1815,13 +1947,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) {
@@ -2873,6 +3029,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,
@@ -2915,20 +3098,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;
@@ -3199,6 +3384,7 @@ exports.createReelSystem = createReelSystem;
 exports.easingByName = easingByName;
 exports.effectiveRowsPerReel = effectiveRowsPerReel;
 exports.mergeReelConfig = mergeReelConfig;
+exports.perReelValue = perReelValue;
 exports.pickTier = pickTier;
 exports.resolveGeometry = resolveGeometry;
 exports.resolveGridGeometry = resolveGridGeometry;