@energy8platform/game-engine 0.32.2 → 0.32.4

package/dist/slot.d.ts

@@ -96,6 +96,7 @@ declare class SymbolCell extends Container {
     private _style;
     private _frame;
     private _view;
+    private _data;
     private _badges;
     private _multBadge;
     private _bonusBadge;
@@ -103,6 +104,8 @@ declare class SymbolCell extends Container {
     frameStyleKey: 'idle' | 'winning' | 'removed' | 'fresh';
     constructor(config: SymbolCellConfig);
     get view(): SymbolView | null;
+    /** The last applied cell data (symbol + badges). Read by motion controllers that rebuild tapes. */
+    get data(): CellData;
     setData(data: CellData): void;
     setState(state: CellState): void;
     playWin(): Promise<void>;
@@ -816,6 +819,68 @@ declare class TumbleController {
     skip(): void;
 }
 
+interface ReelStepData {
+    /** Cells that won on the current board — highlighted/paid before the shift. */
+    winningCells: {
+        col: number;
+        row: number;
+    }[];
+    /** How far to scroll each reel down (length = cols). 0 = the reel stays put. */
+    shifts: number[];
+    /** Board after every reel has scrolled down by shifts[col]. */
+    settledGrid: CellData[][];
+}
+/**
+ * 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.
+ */
+declare function buildReelStepTape(before: CellData[], settledCol: CellData[], shift: number): {
+    stack: CellData[];
+    shift: number;
+    startOffsetCells: number;
+};
+declare class ReelStepController {
+    private _grid;
+    private _resolve;
+    private _cfg;
+    private _win;
+    private _killed;
+    private _mult;
+    private _temp;
+    /** Board the in-flight step settles to — used to snap on skip(). */
+    private _pending;
+    constructor(grid: ReelGrid, resolve: SymbolResolver, cfg: CascadeConfig, win?: WinConfig);
+    setConfig(cfg: CascadeConfig): void;
+    setWin(win: WinConfig): void;
+    /** Killed, or the grid was torn down underneath us (rebuild mid-chain). */
+    private get _dead();
+    get multiplier(): number;
+    resetMultiplier(): void;
+    private advanceMultiplier;
+    /** Run one ReelStep: pay the winning cells, then scroll each reel down by shifts[col]. */
+    step(step: ReelStepData, stepIndex?: number, opts?: {
+        turbo?: boolean;
+    }): Promise<void>;
+    /** Highlight + hold the winning cells, then release them back to rest before the shift. */
+    private _payWins;
+    /**
+     * 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).
+     */
+    private _scrollReel;
+    private _dim;
+    private _undim;
+    private _resetPositions;
+    private _cleanupTemp;
+    /** Hard-cancel: kill tweens, drop tapes, snap to the in-flight step's settled board. */
+    skip(): void;
+}
+
 interface FeatureContext {
     grid: ReelGrid;
     resolve: SymbolResolver;
@@ -875,7 +940,16 @@ interface ReelSystem {
         turbo?: boolean;
         freeSpins?: boolean;
     }): Promise<void>;
-    /** Current running cascade multiplier. */
+    /**
+     * Run a ReelStep™ chain: each step pays its winning cells, then scrolls every reel down by
+     * `shifts[col]` positions (0 = reel stays put). Multiplier carries over with `freeSpins` +
+     * `cascade.multiplier.persistInFreeSpins`, same as `cascade`.
+     */
+    reelStep(steps: ReelStepData[], opts?: {
+        turbo?: boolean;
+        freeSpins?: boolean;
+    }): Promise<void>;
+    /** Current running cascade / reel-step multiplier. */
     readonly multiplier: number;
     /** Register a custom feature (or override a built-in by reusing its key). */
     registerFeature(feature: ReelFeature): void;
@@ -974,5 +1048,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, SpinEngine, SymbolCell, TumbleController, 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, ReelStopPlan$1 as ReelStopPlan, ReelSystem, ReelSystemConfig, ResolvedGeometry, SettleConfig, SpinData, SpinRunOpts, ReelStopPlan as SpinStopPlan, SplitConfig, SquashConfig, StackedConfig, 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, 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, StickyConfig, StopMode, StopOrder, SymbolCellConfig, SymbolResolver, SymbolTextures, SymbolView, TransformConfig, TumbleStep, WalkingWildConfig, WinConfig, WinTier };

package/dist/slot.esm.js

@@ -537,6 +537,7 @@ class SymbolCell extends Container {
     _style;
     _frame;
     _view = null;
+    _data = { symbol: null };
     _badges = new Container();
     _multBadge = null;
     _bonusBadge = null;
@@ -557,9 +558,14 @@ class SymbolCell extends 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) {
@@ -2023,6 +2029,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 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:
@@ -2571,6 +2798,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();
@@ -2593,6 +2821,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 });
@@ -2621,6 +2850,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) {
@@ -2676,6 +2906,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) {
@@ -2700,7 +2932,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
@@ -2714,6 +2947,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);
         },
@@ -2745,6 +2989,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);
@@ -2924,5 +3169,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, SpinEngine, SymbolCell, TumbleController, 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, pickTier, resolveGeometry, resolveGridGeometry, resolveReelConfig, tierIndexAtValue, valueAt, waysCount };
 //# sourceMappingURL=slot.esm.js.map