@energy8platform/game-engine 0.40.0 → 0.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@energy8platform/game-engine",
-  "version": "0.40.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

@@ -184,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 {
@@ -213,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 };
 }
@@ -503,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

@@ -151,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/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
@@ -137,6 +143,7 @@ export class SpinEngine {
     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);
@@ -154,6 +161,7 @@ export class SpinEngine {
       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({
@@ -166,7 +174,7 @@ export class SpinEngine {
         deferred: defer.has(reel),
       });
     }
-    if (this._cfg.style === 'cascade-drop') this._planDrop(out, holds, f, order);
+    if (this._cfg.style === 'cascade-drop') this._planDrop(out, holds, ramps, f, order);
     return out;
   }
 
@@ -179,6 +187,7 @@ export class SpinEngine {
   private _planDrop(
     out: ReelStopPlan[],
     holds: number[],
+    ramps: number[],
     f: number,
     order: (reel: number) => number,
   ): void {
@@ -205,10 +214,15 @@ export class SpinEngine {
       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 + i * this._cfg.cellStagger * scale + fall;
+        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;

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,
     };
   }