@energy8platform/game-engine 0.39.0 → 0.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@energy8platform/game-engine",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "description": "Universal casino game engine built on PixiJS v8 and @energy8platform/game-sdk",
   "type": "module",
   "main": "./dist/index.cjs.js",

package/src/slot/config/ReelSystemConfig.ts

@@ -92,6 +92,10 @@ export type MotionStyle =
   | 'cascade-drop'; // symbols drop in from above (tumble-style boards)
 
 export type StopMode = 'sequential' | 'sync' | 'random';
+/** `cascade-drop` fill direction within one reel. */
+export type DropOrder = 'top-down' | 'bottom-up';
+/** How `cascade-drop` spaces reels: by formula, or one strictly after the other. */
+export type DropSequence = 'parallel' | 'chained' | 'chained-when-anticipated';
 export type StopOrder = 'ltr' | 'rtl';
 export type Intensity = 'full' | 'reduced' | 'minimal';
 
@@ -147,6 +151,25 @@ export 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;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -161,6 +184,8 @@ export 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>;
 }
 
 export interface AnticipationConfig {
@@ -190,6 +215,16 @@ export 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; scale: number; ms: number };
 }
@@ -467,6 +502,8 @@ export const DEFAULT_REEL_CONFIG: ReelSystemConfig = {
     cellStagger: 24,
     reelStaggerFactor: 0.4,
     dropFallFactor: 0.6,
+    dropOrder: 'top-down',
+    dropSequence: 'parallel',
   },
   anticipation: {
     enabled: false,
@@ -478,6 +515,7 @@ export const DEFAULT_REEL_CONFIG: ReelSystemConfig = {
     decide: null,
     progressiveSlowdown: 1,
     progressiveHoldMs: 0,
+    progressiveCellStagger: 1,
     zoom: { enabled: false, scale: 1.15, ms: 600 },
   },
   cascade: {

package/src/slot/devtools/fieldSchema.ts

@@ -137,6 +137,8 @@ export const REEL_FIELD_SCHEMA: Section[] = [
       { kind: 'range', path: 'motion.cellStagger', label: 'Cell stagger (ms)', min: 0, max: 700, step: 5 },
       { kind: 'range', path: 'motion.reelStaggerFactor', label: 'Reel stagger ×', min: 0, max: 3, step: 0.05 },
       { kind: 'range', path: 'motion.dropFallFactor', label: 'Drop fall ×', min: 0.1, max: 3, step: 0.05 },
+      { kind: 'select', path: 'motion.dropOrder', label: 'Drop order', options: ['top-down', 'bottom-up'] },
+      { kind: 'select', path: 'motion.dropSequence', label: 'Drop sequence', options: ['parallel', 'chained', 'chained-when-anticipated'] },
     ],
   },
   {
@@ -149,6 +151,7 @@ export const REEL_FIELD_SCHEMA: Section[] = [
       { kind: 'range', path: 'anticipation.holdMs', label: 'Hold (ms)', min: 0, max: 1200, step: 50 },
       { kind: 'range', path: 'anticipation.progressiveSlowdown', label: 'Slowdown ramp ×/reel', min: 0.3, max: 1, step: 0.05 },
       { kind: 'range', path: 'anticipation.progressiveHoldMs', label: 'Hold ramp (ms/reel)', min: 0, max: 600, step: 25 },
+      { kind: 'range', path: 'anticipation.progressiveCellStagger', label: 'Cell ramp ×/cell', min: 1, max: 2.5, step: 0.05 },
       { kind: 'toggle', path: 'anticipation.zoom.enabled', label: 'Reel zoom' },
       { kind: 'range', path: 'anticipation.zoom.scale', label: 'Zoom scale', min: 1, max: 1.6, step: 0.05 },
       { kind: 'range', path: 'anticipation.zoom.ms', label: 'Zoom (ms)', min: 200, max: 1200, step: 50 },

package/src/slot/index.ts

@@ -33,6 +33,8 @@ export type {
   MotionStyle,
   StopMode,
   StopOrder,
+  DropOrder,
+  DropSequence,
   Intensity,
   GridConfig,
   MotionConfig,

package/src/slot/motion/AnticipationController.ts

@@ -18,10 +18,18 @@ export 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>;
 }
 
 /** Fresh "nothing to anticipate" decision (fresh, so callers may mutate `reels` freely). */
-const none = (): AnticipationDecision => ({ active: false, reels: [], slowdown: 1, holdMs: 0 });
+const none = (): AnticipationDecision => ({
+  active: false,
+  reels: [],
+  slowdown: 1,
+  holdMs: 0,
+  cellStaggerRamp: 1,
+});
 
 export class AnticipationController {
   private _cfg: AnticipationConfig;
@@ -53,7 +61,7 @@ export class AnticipationController {
       if (!custom) return none();
       const o: AnticipationOverride = 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)) {
@@ -86,10 +94,12 @@ export class AnticipationController {
     reels: number[],
     slowdown?: PerReel<number>,
     holdMs?: PerReel<number>,
+    cellStaggerRamp?: PerReel<number>,
   ): AnticipationDecision {
     return {
       active: true,
       reels,
+      cellStaggerRamp: cellStaggerRamp ?? this._cfg.progressiveCellStagger,
       slowdown:
         slowdown ??
         this.ramp(reels, this._cfg.slowdownFactor, (base, i) =>

package/src/slot/motion/SpinEngine.ts

@@ -38,6 +38,12 @@ export 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
@@ -68,6 +74,13 @@ export 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[];
 }
 
 export class SpinEngine {
@@ -129,6 +142,8 @@ export class SpinEngine {
     const order = (reel: number) => (this._cfg.stopOrder === 'rtl' ? cols - 1 - reel : reel);
     const anticipate = new Set(opts?.anticipateReels ?? []);
     const defer = new Set(opts?.deferReveal ?? []);
+    const holds: number[] = [];
+    const ramps: number[] = [];
     const out: ReelStopPlan[] = [];
     for (let reel = 0; reel < cols; reel++) {
       const idx = order(reel);
@@ -143,7 +158,10 @@ export 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({
@@ -156,9 +174,62 @@ export 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.
+   */
+  private _planDrop(
+    out: ReelStopPlan[],
+    holds: number[],
+    ramps: number[],
+    f: number,
+    order: (reel: number) => number,
+  ): void {
+    const bottomUp = this._cfg.dropOrder === 'bottom-up';
+    // walk the reels in STOP order, so `stopOrder: 'rtl'` reverses the drop as well
+    const byPosition: number[] = [];
+    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: number[] = [];
+      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: SpinData, opts?: SpinRunOpts): Promise<void> {
     this._killed = false;
@@ -328,6 +399,8 @@ export 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;
@@ -337,18 +410,10 @@ export 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);

package/src/slot/system/ReelSystem.ts

@@ -215,12 +215,15 @@ export function createReelSystem(opts: CreateReelSystemOptions): ReelSystem {
   function resolveAnticipation(target: CellData[][], runOpts?: SpinRunOpts): AnticipationDecision {
     const explicit = runOpts?.anticipateReels;
     if (!explicit) return anticipation.decide(target);
-    if (!explicit.length) return { active: false, reels: [], slowdown: 1, holdMs: 0 };
+    if (!explicit.length)
+      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,
     };
   }
 
@@ -234,6 +237,7 @@ export function createReelSystem(opts: CreateReelSystemOptions): ReelSystem {
       anticipateReels: decision.active ? decision.reels : undefined,
       anticipateSlowdown: decision.slowdown,
       anticipateHoldMs: decision.holdMs,
+      anticipateCellStaggerRamp: decision.cellStaggerRamp,
     };
   }