@energy8platform/game-engine 0.39.0 → 0.40.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 {
@@ -773,6 +796,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 +821,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;
@@ -1135,4 +1172,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,
@@ -1569,6 +1571,7 @@ 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 out = [];
         for (let reel = 0; reel < cols; reel++) {
             const idx = order(reel);
@@ -1584,8 +1587,9 @@ 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;
             const speed = isAnticipated ? perReelValue(opts?.anticipateSlowdown, reel, 1) : 1;
             out.push({
                 reel,
@@ -1597,8 +1601,48 @@ class SpinEngine {
                 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;
@@ -1740,6 +1784,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 +1795,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);