@energy8platform/game-engine 0.32.2 → 0.32.4

package/dist/slot.cjs.js

@@ -539,6 +539,7 @@ class SymbolCell extends pixi_js.Container {
     _style;
     _frame;
     _view = null;
+    _data = { symbol: null };
     _badges = new pixi_js.Container();
     _multBadge = null;
     _bonusBadge = null;
@@ -559,9 +560,14 @@ class SymbolCell extends pixi_js.Container {
     get view() {
         return this._view;
     }
+    /** The last applied cell data (symbol + badges). Read by motion controllers that rebuild tapes. */
+    get data() {
+        return this._data;
+    }
     setData(data) {
         if (this.destroyed)
             return; // a killed-tween chain may resume after the cell is gone
+        this._data = data;
         // symbol view
         if (data.symbol == null) {
             if (this._view) {
@@ -2025,6 +2031,227 @@ class TumbleController {
     }
 }
 
+// packages/game-engine/src/slot/cascade/ReelStepController.ts
+//
+// ReelStep™ mechanic. Flow: reels stop → winning lines are paid → each reel scrolls DOWN by N
+// positions (N = winning symbols that played on that reel) → the board is re-evaluated → repeat,
+// until no wins remain. Unlike a cascade/tumble, nothing is removed: the existing symbols ride
+// down and N fresh symbols enter from the top. Reels with N=0 stay put; each reel moves
+// independently by its own N.
+//
+// Presentation only — the caller supplies each step's per-reel shift vector and the post-shift
+// board. Fits classic fixed-line grids (5×3, 5×4, 5×5, …), not ways/cluster.
+/**
+ * PURE: lay out one reel's scroll tape (top→bottom). The `shift` fresh symbols (the top of the
+ * settled reel) stack above the reel's current symbols; the tape starts `shift` cells high so the
+ * current symbols fill the window, then slides down by `shift` to reveal the fresh ones. `shift` is
+ * clamped to the visible window height. Returns the stacked cells and the start offset (in cells,
+ * relative to row 0) the tape animates from.
+ */
+function buildReelStepTape(before, settledCol, shift) {
+    const rows = before.length;
+    const s = Math.max(0, Math.min(shift, rows));
+    const incoming = Array.from({ length: s }, (_, i) => settledCol[i] ?? { symbol: null });
+    return { stack: [...incoming, ...before], shift: s, startOffsetCells: 0 - s };
+}
+class ReelStepController {
+    _grid;
+    _resolve;
+    _cfg;
+    _win = DEFAULT_REEL_CONFIG.win;
+    _killed = false;
+    _mult;
+    _temp = [];
+    /** Board the in-flight step settles to — used to snap on skip(). */
+    _pending = null;
+    constructor(grid, resolve, cfg, win) {
+        this._grid = grid;
+        this._resolve = resolve;
+        this._cfg = cfg;
+        this._mult = cfg.multiplier.start;
+        if (win)
+            this._win = win;
+    }
+    setConfig(cfg) {
+        this._cfg = cfg;
+    }
+    setWin(win) {
+        this._win = win;
+    }
+    /** Killed, or the grid was torn down underneath us (rebuild mid-chain). */
+    get _dead() {
+        return this._killed || this._grid.destroyed;
+    }
+    get multiplier() {
+        return this._mult;
+    }
+    resetMultiplier() {
+        this._mult = this._cfg.multiplier.start;
+    }
+    advanceMultiplier() {
+        const m = this._cfg.multiplier;
+        if (!m.enabled)
+            return;
+        const next = m.mode === 'mul' ? this._mult * m.step : this._mult + m.step;
+        this._mult = m.cap != null ? Math.min(next, m.cap) : next;
+    }
+    /** Run one ReelStep: pay the winning cells, then scroll each reel down by shifts[col]. */
+    async step(step, stepIndex = 0, opts) {
+        if (this._grid.destroyed)
+            return;
+        this._killed = false;
+        this._pending = step.settledGrid;
+        // 1. celebrate/pay the winning cells.
+        await this._payWins(step, opts);
+        if (this._dead)
+            return;
+        // No shift → just settle the board (defensive; a real ReelStep always shifts something).
+        const hasShift = step.shifts.some((n) => n > 0);
+        if (!this._cfg.enabled || !hasShift) {
+            this._grid.setGrid(step.settledGrid);
+            if (step.winningCells.length)
+                this.advanceMultiplier();
+            this._pending = null;
+            return;
+        }
+        // 2. scroll every reel down by its own N (0 = untouched), all reels concurrently.
+        const turbo = opts?.turbo ? 0.5 : 1;
+        const decel = Math.min(this._cfg.perStepDecelCap, 1 + stepIndex * this._cfg.perStepDecel);
+        const f = turbo * decel;
+        await Promise.all(step.shifts.map((n, col) => n > 0 ? this._scrollReel(col, n, step.settledGrid, f) : Promise.resolve()));
+        if (this._dead) {
+            this._cleanupTemp();
+            return;
+        }
+        // 3. normalise + advance multiplier.
+        this._grid.setGrid(step.settledGrid);
+        this._resetPositions();
+        this._cleanupTemp();
+        this._pending = null;
+        if (step.winningCells.length)
+            this.advanceMultiplier();
+    }
+    /** Highlight + hold the winning cells, then release them back to rest before the shift. */
+    async _payWins(step, opts) {
+        if (!step.winningCells.length)
+            return;
+        const turbo = opts?.turbo ? 0.5 : 1;
+        const t = this._cfg.timings;
+        const hs = this._win.highlightScale;
+        const winSet = new Set(step.winningCells.map((w) => `${w.col}:${w.row}`));
+        if (this._cfg.dimNonWinners)
+            this._dim(winSet);
+        await Promise.all(step.winningCells.map((w) => {
+            const cell = this._grid.getCell(w.col, w.row);
+            if (this._win.glow)
+                cell.setState({ winning: true });
+            return Tween.to(cell, { 'scale.x': hs, 'scale.y': hs }, t.highlight * turbo, easingByName(this._cfg.easings.highlight));
+        }));
+        if (this._dead) {
+            this._undim();
+            return;
+        }
+        await Tween.delay(t.wait * turbo);
+        for (const w of step.winningCells) {
+            const cell = this._grid.getCell(w.col, w.row);
+            cell.setState({});
+            cell.scale.set(1);
+        }
+        this._undim();
+    }
+    /**
+     * Scroll one reel down by `n` positions. A tape carrying the reel's current symbols with `n`
+     * fresh symbols stacked on top slides down by `n` cells: the fresh symbols enter from the top,
+     * the existing ones ride down, and the bottom `n` ride off below the window. Ends on
+     * settledGrid[col]. The tape shares the cells' parent (so the reel mask, if any, clips it).
+     */
+    async _scrollReel(col, n, settledGrid, f) {
+        const rows = this._grid.rowsOf(col);
+        if (rows === 0 || this._dead)
+            return;
+        const realCells = Array.from({ length: rows }, (_, r) => this._grid.getCell(col, r));
+        const layer = realCells[0].parent ?? this._grid;
+        const base = this._grid.cellPosition(col, 0);
+        const step = rows > 1 ? this._grid.cellPosition(col, 1).y - base.y : this._grid.cellSize(col).height;
+        // current visible symbols (top→bottom), captured before we hide them
+        const before = realCells.map((c) => ({ ...c.data }));
+        const { stack, startOffsetCells } = buildReelStepTape(before, settledGrid[col] ?? [], n);
+        // Tape laid out top→bottom at local y = i*step: [incoming(shift)] above [before(rows)].
+        const tape = new pixi_js.Container();
+        tape.x = base.x;
+        for (let i = 0; i < stack.length; i++) {
+            const cell = new SymbolCell({ size: this._grid.cellSize(col), resolve: this._resolve });
+            cell.setData(stack[i]);
+            cell.position.set(0, i * step);
+            tape.addChild(cell);
+        }
+        // Start: the `before` block fills the window; the incoming block sits above it (masked off).
+        tape.y = base.y + startOffsetCells * step;
+        realCells.forEach((c) => (c.visible = false));
+        layer.addChild(tape);
+        this._temp.push(tape);
+        // Slide down by `shift` positions, with a small overshoot then settle-back.
+        const overshoot = step * 0.12;
+        await Tween.to(tape, { y: base.y + overshoot }, this._cfg.timings.drop * f, easingByName(this._cfg.easings.drop));
+        if (this._dead)
+            return;
+        await Tween.to(tape, { y: base.y }, Math.max(90, this._cfg.timings.refill * f), easingByName('easeOutQuad'));
+        if (this._dead)
+            return;
+        // Hand the settled symbols back to the real cells.
+        for (let r = 0; r < rows; r++)
+            realCells[r].setData(settledGrid[col]?.[r] ?? { symbol: null });
+        realCells.forEach((c) => (c.visible = true));
+        tape.destroy();
+        this._temp = this._temp.filter((tp) => tp !== tape);
+    }
+    _dim(winSet) {
+        for (let c = 0; c < this._grid.cols; c++)
+            for (let r = 0; r < this._grid.rowsOf(c); r++)
+                if (!winSet.has(`${c}:${r}`))
+                    this._grid.getCell(c, r).alpha = this._cfg.dimAlpha;
+    }
+    _undim() {
+        for (let c = 0; c < this._grid.cols; c++)
+            for (let r = 0; r < this._grid.rowsOf(c); r++) {
+                const cell = this._grid.getCell(c, r);
+                if (cell.alpha !== 0)
+                    cell.alpha = 1;
+            }
+    }
+    _resetPositions() {
+        if (this._grid.destroyed)
+            return;
+        for (let c = 0; c < this._grid.cols; c++)
+            for (let r = 0; r < this._grid.rowsOf(c); r++) {
+                const cell = this._grid.getCell(c, r);
+                const { x, y } = this._grid.cellPosition(c, r);
+                cell.position.set(x, y);
+                cell.scale.set(1);
+                cell.alpha = 1;
+                cell.visible = true;
+            }
+    }
+    _cleanupTemp() {
+        for (const t of this._temp)
+            if (!t.destroyed)
+                t.destroy();
+        this._temp = [];
+    }
+    /** Hard-cancel: kill tweens, drop tapes, snap to the in-flight step's settled board. */
+    skip() {
+        this._killed = true;
+        for (let c = 0; c < this._grid.cols; c++)
+            for (let r = 0; r < this._grid.rowsOf(c); r++)
+                Tween.killTweensOf(this._grid.getCell(c, r));
+        this._cleanupTemp();
+        if (this._pending && !this._grid.destroyed)
+            this._grid.setGrid(this._pending);
+        this._pending = null;
+        this._resetPositions();
+    }
+}
+
 // packages/game-engine/src/slot/features/types.ts
 //
 // Uniform interface for special reel feature mechanics. Each feature is a presentation module:
@@ -2573,6 +2800,7 @@ function createReelSystem(opts) {
     let spin;
     let anticipation;
     let tumble;
+    let reelStepCtl;
     let board = opts.board ?? emptyBoard(config);
     // custom features keyed by id; built-ins live in FEATURES/FEATURE_LIST
     const custom = new Map();
@@ -2595,6 +2823,7 @@ function createReelSystem(opts) {
         if (grid) {
             spin?.skip();
             tumble?.skip();
+            reelStepCtl?.skip();
             for (const child of fx?.children.slice() ?? [])
                 Tween.killTweensOf(child);
             grid.destroy({ children: true });
@@ -2623,6 +2852,7 @@ function createReelSystem(opts) {
         spin = new SpinEngine(grid, resolve, config.motion, config.win);
         anticipation = new AnticipationController(config.anticipation);
         tumble = new TumbleController(grid, config.cascade, config.win);
+        reelStepCtl = new ReelStepController(grid, resolve, config.cascade, config.win);
         grid.setGrid(board);
     }
     function geometryChanged(next) {
@@ -2678,6 +2908,8 @@ function createReelSystem(opts) {
                 anticipation.setConfig(config.anticipation);
                 tumble.setConfig(config.cascade);
                 tumble.setWin(config.win);
+                reelStepCtl.setConfig(config.cascade);
+                reelStepCtl.setWin(config.win);
             }
         },
         update(partial) {
@@ -2702,7 +2934,8 @@ function createReelSystem(opts) {
             board = target;
         },
         get multiplier() {
-            return tumble.multiplier;
+            // cascade and reelStep share the same config start; only the active mechanic climbs.
+            return Math.max(tumble.multiplier, reelStepCtl.multiplier);
         },
         async cascade(steps, cOpts) {
             // keep the multiplier climbing across free-spins when configured; otherwise reset per spin
@@ -2716,6 +2949,17 @@ function createReelSystem(opts) {
             if (config.cascade.multiplier.enabled)
                 log?.(`Cascade multiplier ×${tumble.multiplier}`);
         },
+        async reelStep(steps, rOpts) {
+            const persist = config.cascade.multiplier.persistInFreeSpins && !!rOpts?.freeSpins;
+            if (!persist)
+                reelStepCtl.resetMultiplier();
+            for (let i = 0; i < steps.length; i++) {
+                await reelStepCtl.step(steps[i], i, rOpts);
+                board = steps[i].settledGrid;
+            }
+            if (config.cascade.multiplier.enabled)
+                log?.(`ReelStep multiplier ×${reelStepCtl.multiplier}`);
+        },
         registerFeature(feature) {
             custom.set(feature.key, feature);
         },
@@ -2747,6 +2991,7 @@ function createReelSystem(opts) {
         skip() {
             spin.skip();
             tumble.skip();
+            reelStepCtl.skip();
             // kill in-flight overlay tweens (labels/rings) so a rebuild never animates destroyed nodes
             for (const child of fx.children.slice())
                 Tween.killTweensOf(child);
@@ -2942,9 +3187,11 @@ exports.PRESETS = PRESETS;
 exports.PRESET_LIST = PRESET_LIST;
 exports.ReelGrid = ReelGrid;
 exports.ReelSpinController = ReelSpinController;
+exports.ReelStepController = ReelStepController;
 exports.SpinEngine = SpinEngine;
 exports.SymbolCell = SymbolCell;
 exports.TumbleController = TumbleController;
+exports.buildReelStepTape = buildReelStepTape;
 exports.cellPositionOf = cellPositionOf;
 exports.createReelSystem = createReelSystem;
 exports.easingByName = easingByName;