@energy8platform/game-engine 0.39.0 → 0.41.0

package/dist/slot.d.ts

@@ -411,6 +411,10 @@ interface GridConfig {
 }
 type MotionStyle = 'swap' | 'strip' | 'cascade-drop';
 type StopMode = 'sequential' | 'sync' | 'random';
+/** `cascade-drop` fill direction within one reel. */
+type DropOrder = 'top-down' | 'bottom-up';
+/** How `cascade-drop` spaces reels: by formula, or one strictly after the other. */
+type DropSequence = 'parallel' | 'chained' | 'chained-when-anticipated';
 type StopOrder = 'ltr' | 'rtl';
 type Intensity = 'full' | 'reduced' | 'minimal';
 interface SettleConfig {
@@ -462,6 +466,25 @@ interface MotionConfig {
     reelStaggerFactor: number;
     /** `cascade-drop`: fall duration as a fraction of `spinUp`. Default 0.6. */
     dropFallFactor: number;
+    /**
+     * `cascade-drop`: which cell of a reel lands first. `'top-down'` (default, the engine's original
+     * behaviour) deals the reel like cards from the top; `'bottom-up'` fills it the way gravity
+     * would — the lowest cell arrives first and the rest stack on top of it.
+     */
+    dropOrder: DropOrder;
+    /**
+     * `cascade-drop`: how reels are spaced.
+     * - `'parallel'` (default) starts every reel at its own formula offset —
+     *   `reel * stopStagger * reelStaggerFactor` — so a reel can open while the previous one is
+     *   still dropping. Fast, and what a normal spin wants.
+     * - `'chained'` starts a reel only once the previous one has seated its LAST cell, plus that
+     *   same offset as the gap. One reel at a time, always — correct, but it makes every spin as
+     *   long as the sum of its reels.
+     * - `'chained-when-anticipated'` runs the un-armed reels in parallel and switches to the chain
+     *   from the first ANTICIPATED reel onwards. The base spin keeps its stop window; the hunt for
+     *   the last scatter goes strictly reel by reel, each slower than the last.
+     */
+    dropSequence: DropSequence;
 }
 /** What a game-supplied `AnticipationConfig.decide` may return instead of a bare reel list. */
 interface AnticipationOverride {
@@ -471,6 +494,8 @@ interface AnticipationOverride {
     slowdown?: PerReel<number>;
     /** Extra hold before landing. Scalar, or per-reel indexed by reel index. */
     holdMs?: PerReel<number>;
+    /** Growth of the gap between successive cells within a reel. Scalar, or per-reel. */
+    cellStaggerRamp?: PerReel<number>;
 }
 interface AnticipationConfig {
     enabled: boolean;
@@ -499,6 +524,16 @@ interface AnticipationConfig {
     progressiveSlowdown: number;
     /** Extra hold (ms) added per successive anticipated reel: reel #i gets `holdMs + i * this`. */
     progressiveHoldMs: number;
+    /**
+     * `cascade-drop`: how the gap between SUCCESSIVE CELLS grows inside an anticipated reel. The
+     * gap before cell #i is `cellStagger * <reel slowdown> * progressiveCellStagger ** i`, so 1
+     * (the default) keeps the reel's cells evenly spaced and > 1 makes each symbol land later than
+     * the last — the drip that turns a reel into a countdown.
+     *
+     * It compounds with `progressiveSlowdown`: that widens the base gap reel by reel, this widens
+     * it cell by cell, so a later reel drips both slower AND with a steeper ramp.
+     */
+    progressiveCellStagger: number;
     /** Optional grid zoom while anticipating (magnum-opus uses 1.3×). */
     zoom: {
         enabled: boolean;
@@ -743,6 +778,12 @@ interface SpinRunOpts {
     anticipateSlowdown?: PerReel<number>;
     /** Extra hold (ms) for anticipated reels. Scalar, or per-reel indexed by reel. */
     anticipateHoldMs?: PerReel<number>;
+    /**
+     * `cascade-drop`: growth of the gap between successive cells inside an anticipated reel — the
+     * gap before cell #i is `cellStagger * <reel slowdown> * ramp ** i`. 1 keeps the reel evenly
+     * spaced. Scalar, or per-reel indexed by reel.
+     */
+    anticipateCellStaggerRamp?: 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
@@ -773,6 +814,13 @@ interface ReelStopPlan {
     slowdown: number;
     /** True when `deferReveal` withheld this reel's landing (see `SpinRunOpts.deferReveal`). */
     deferred: boolean;
+    /**
+     * `cascade-drop` only: ms from spin start at which each cell of this reel seats, INDEXED BY ROW.
+     * The reel's fill direction lives in these numbers (`motion.dropOrder` decides which row is the
+     * smallest), as does its place in the chain (`motion.dropSequence`). `stopTime` is the largest
+     * of them — the frame the whole reel has landed.
+     */
+    cellStopTimes?: number[];
 }
 declare class SpinEngine {
     private _grid;
@@ -791,6 +839,13 @@ declare class SpinEngine {
     private scale;
     /** PURE: per-reel stop schedule. No Pixi mutation. */
     plan(data: SpinData, opts?: SpinRunOpts): ReelStopPlan[];
+    /**
+     * `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.
+     */
+    private _planDrop;
     /** Execute the spin for every reel concurrently. */
     run(data: SpinData, opts?: SpinRunOpts): Promise<void>;
     private _runReel;
@@ -817,6 +872,8 @@ interface AnticipationDecision {
     slowdown: PerReel<number>;
     /** Extra hold before landing. Scalar or per-reel array, same as `slowdown`. */
     holdMs: PerReel<number>;
+    /** `cascade-drop`: growth of the gap between successive cells inside the reel (1 = even). */
+    cellStaggerRamp: PerReel<number>;
 }
 declare class AnticipationController {
     private _cfg;
@@ -1135,4 +1192,4 @@ declare 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, 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 };
+export type { AnimatedSymbolConfig, AnticipationConfig, AnticipationDecision, AnticipationOverride, BigWinOverlayConfig, BlurConfig, CarryPolicy, CascadeAnim, CascadeConfig, CascadeStepData, CascadeTimings, CellData, CellFrameStyle, CellSizeSpec, CellState, CountUpConfig, CreateReelSystemOptions, DecorationConfig, DeepPartial, DropOrder, DropSequence, 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

@@ -1129,6 +1129,8 @@ const DEFAULT_REEL_CONFIG = {
         cellStagger: 24,
         reelStaggerFactor: 0.4,
         dropFallFactor: 0.6,
+        dropOrder: 'top-down',
+        dropSequence: 'parallel',
     },
     anticipation: {
         enabled: false,
@@ -1140,6 +1142,7 @@ const DEFAULT_REEL_CONFIG = {
         decide: null,
         progressiveSlowdown: 1,
         progressiveHoldMs: 0,
+        progressiveCellStagger: 1,
         zoom: { enabled: false, scale: 1.15, ms: 600 },
     },
     cascade: {
@@ -1569,6 +1572,8 @@ class SpinEngine {
         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 ramps = [];
         const out = [];
         for (let reel = 0; reel < cols; reel++) {
             const idx = order(reel);
@@ -1584,8 +1589,10 @@ class SpinEngine {
             else
                 stopTime = (this._cfg.spinUp + this._cfg.hold + idx * this._cfg.stopStagger) * f;
             const isAnticipated = anticipate.has(reel);
-            if (isAnticipated)
-                stopTime += perReelValue(opts?.anticipateHoldMs, reel, 0) * f;
+            const hold = isAnticipated ? perReelValue(opts?.anticipateHoldMs, reel, 0) * f : 0;
+            stopTime += hold;
+            holds[reel] = hold;
+            ramps[reel] = isAnticipated ? perReelValue(opts?.anticipateCellStaggerRamp, reel, 1) : 1;
             const speed = isAnticipated ? perReelValue(opts?.anticipateSlowdown, reel, 1) : 1;
             out.push({
                 reel,
@@ -1597,8 +1604,53 @@ class SpinEngine {
                 deferred: defer.has(reel),
             });
         }
+        if (this._cfg.style === 'cascade-drop')
+            this._planDrop(out, holds, ramps, 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, ramps, 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);
+            // The gap before cell #i is `cellStagger * scale * ramp**i` — accumulate rather than
+            // multiply, so a ramp of 1 stays exactly the old evenly-spaced schedule.
+            const ramp = ramps[p.reel] ?? 1;
+            const cells = [];
+            let offset = 0;
+            for (let i = 0; i < rows; i++) {
+                const row = bottomUp ? rows - 1 - i : i;
+                cells[row] = start + offset + fall;
+                offset += this._cfg.cellStagger * scale * Math.pow(ramp, i);
+            }
+            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;
@@ -1740,6 +1792,8 @@ class SpinEngine {
         }
         const step = this._grid.cellPosition(p.reel, 1).y - this._grid.cellPosition(p.reel, 0).y;
         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;
@@ -1749,13 +1803,11 @@ class SpinEngine {
             cell.setData(data);
             cell.position.set(to.x, to.y - step * (rows + 1));
             cell.alpha = 1;
-            const delay = (p.reel * this._cfg.stopStagger * this._cfg.reelStaggerFactor +
-                r * this._cfg.cellStagger) *
-                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 * this._cfg.dropFallFactor * 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);
@@ -1848,7 +1900,13 @@ 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 });
+const none = () => ({
+    active: false,
+    reels: [],
+    slowdown: 1,
+    holdMs: 0,
+    cellStaggerRamp: 1,
+});
 class AnticipationController {
     _cfg;
     constructor(cfg) {
@@ -1881,7 +1939,7 @@ class AnticipationController {
             const o = Array.isArray(custom) ? { reels: custom } : custom;
             if (!o.reels?.length)
                 return none();
-            return this.build(o.reels.slice(), o.slowdown, o.holdMs);
+            return this.build(o.reels.slice(), o.slowdown, o.holdMs, o.cellStaggerRamp);
         }
         if (Array.isArray(this._cfg.reels)) {
             // explicit reel list — arm only if the threshold is met somewhere on the board
@@ -1910,10 +1968,11 @@ class AnticipationController {
         return this.build(reels);
     }
     /** Assemble a decision, applying the configured progression unless the caller pinned values. */
-    build(reels, slowdown, holdMs) {
+    build(reels, slowdown, holdMs, cellStaggerRamp) {
         return {
             active: true,
             reels,
+            cellStaggerRamp: cellStaggerRamp ?? this._cfg.progressiveCellStagger,
             slowdown: slowdown ??
                 this.ramp(reels, this._cfg.slowdownFactor, (base, i) => i === 0 ? base : base * Math.pow(this._cfg.progressiveSlowdown, i)),
             holdMs: holdMs ??
@@ -2993,12 +3052,13 @@ function createReelSystem(opts) {
         if (!explicit)
             return anticipation.decide(target);
         if (!explicit.length)
-            return { active: false, reels: [], slowdown: 1, holdMs: 0 };
+            return { active: false, reels: [], slowdown: 1, holdMs: 0, cellStaggerRamp: 1 };
         return {
             active: true,
             reels: explicit.slice(),
             slowdown: runOpts?.anticipateSlowdown ?? config.anticipation.slowdownFactor,
             holdMs: runOpts?.anticipateHoldMs ?? config.anticipation.holdMs,
+            cellStaggerRamp: runOpts?.anticipateCellStaggerRamp ?? config.anticipation.progressiveCellStagger,
         };
     }
     /** Fold a resolved decision back onto the caller's run options (everything else passes through). */
@@ -3008,6 +3068,7 @@ function createReelSystem(opts) {
             anticipateReels: decision.active ? decision.reels : undefined,
             anticipateSlowdown: decision.slowdown,
             anticipateHoldMs: decision.holdMs,
+            anticipateCellStaggerRamp: decision.cellStaggerRamp,
         };
     }
     buildGrid();