@energy8platform/game-engine 0.38.0 → 0.40.0

package/dist/slot.d.ts

@@ -366,6 +366,14 @@ declare function easingByName(name?: string): EasingFunction;
 
 /** Names of easing functions available in the engine's `Easing` map (see anim/easing-map.ts). */
 type EasingName = 'linear' | 'easeInQuad' | 'easeOutQuad' | 'easeInOutQuad' | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic' | 'easeInBack' | 'easeOutBack' | 'easeInOutBack' | 'easeOutBounce' | 'easeInBounce' | 'easeOutElastic' | 'easeInSine' | 'easeOutSine' | 'easeInOutSine';
+/**
+ * A value that is either flat across the board, or per-reel: an array indexed by REEL INDEX
+ * (holes fall back to the scalar default). Used for anticipation timings so a game can make
+ * each successive reel slower than the last.
+ */
+type PerReel<T> = T | (T | undefined)[];
+/** Resolve a `PerReel<T>` for one reel. `undefined` (or a hole in the array) yields `fallback`. */
+declare function perReelValue<T>(value: PerReel<T> | undefined, reel: number, fallback: T): T;
 /** Win-evaluation model. Purely presentational here (affects geometry + highlight), the math lives in Lua. */
 type EvaluationMode = 'lines' | 'ways' | 'anywhere' | 'cluster' | 'megaways' | 'infinity';
 interface GridConfig {
@@ -403,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 {
@@ -448,6 +460,40 @@ interface MotionConfig {
     slamStop: boolean;
     /** Symbols visible on a reel tape while spinning (swap/strip). */
     symbolsPerReel: number;
+    /** `cascade-drop`: ms between consecutive cells of ONE reel (top→bottom). Default 24. */
+    cellStagger: number;
+    /** `cascade-drop`: multiplier on `stopStagger` for the per-reel offset. Default 0.4. */
+    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 {
+    /** Reels to anticipate, in the order the progression should ramp. Empty = no anticipation. */
+    reels: number[];
+    /** Speed factor (lower = slower). Scalar, or per-reel indexed by reel index. */
+    slowdown?: PerReel<number>;
+    /** Extra hold before landing. Scalar, or per-reel indexed by reel index. */
+    holdMs?: PerReel<number>;
 }
 interface AnticipationConfig {
     enabled: boolean;
@@ -461,6 +507,21 @@ interface AnticipationConfig {
     slowdownFactor: number;
     /** Extra hold (ms) before the final anticipation reel lands (300–500 typical). */
     holdMs: number;
+    /**
+     * Game-supplied decision, REPLACING the built-in `triggerSymbols`/`threshold` counting.
+     * Return the reels to anticipate (or an `AnticipationOverride`); `null` / `[]` = no anticipation.
+     * Use this when the trigger is not expressible as "N of symbol X landed" — e.g. "the round is
+     * still alive on every reel so far", or "reel 3 missed its symbol, so let 4 and 5 stop normally".
+     */
+    decide?: ((targetGrid: CellData[][]) => number[] | AnticipationOverride | null) | null;
+    /**
+     * Ramp the slowdown across successive anticipated reels: reel #i of the decision gets
+     * `slowdownFactor * progressiveSlowdown ** i`. 1 = flat (default); < 1 = each reel slower
+     * than the last.
+     */
+    progressiveSlowdown: number;
+    /** Extra hold (ms) added per successive anticipated reel: reel #i gets `holdMs + i * this`. */
+    progressiveHoldMs: number;
     /** Optional grid zoom while anticipating (magnum-opus uses 1.3×). */
     zoom: {
         enabled: boolean;
@@ -701,8 +762,25 @@ interface SpinRunOpts {
     turbo?: boolean;
     /** Reels to slow for anticipation (computed by the ReelSystem from config + targetGrid). */
     anticipateReels?: number[];
-    anticipateSlowdown?: number;
-    anticipateHoldMs?: number;
+    /** Speed factor for anticipated reels (lower = slower). Scalar, or per-reel indexed by reel. */
+    anticipateSlowdown?: PerReel<number>;
+    /** Extra hold (ms) for anticipated reels. Scalar, or per-reel indexed by reel. */
+    anticipateHoldMs?: 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
+     * their data and visibility from that point (and `skip()` will not reveal them either).
+     */
+    deferReveal?: number[];
+    /** The resolved schedule, handed over before the first frame runs. Schedule against THESE
+     *  numbers rather than re-deriving `plan()`'s formula. */
+    onPlan?: (plan: ReelStopPlan[]) => void;
+    /** Fires on the frame a reel lands — after its cells are seated, before settle/squash/shake.
+     *  For a deferred reel it still fires (the reel DID stop); nothing was seated. */
+    onReelStop?: (reel: number, plan: ReelStopPlan) => void;
+    /** Fires as each cell takes its landing symbol. In `cascade-drop` this is the per-cell impact
+     *  frame (after the fall, before the squash) — the hook for a per-cell sound or shake. */
+    onCellSeated?: (reel: number, row: number, data: CellData) => void;
 }
 interface ReelStopPlan {
     reel: number;
@@ -714,6 +792,17 @@ interface ReelStopPlan {
         ms: number;
     };
     anticipated: boolean;
+    /** Time-stretch applied to this reel's tape (>= 1, longer = slower). 1 when not anticipated. */
+    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;
@@ -723,6 +812,7 @@ declare class SpinEngine {
     private _killed;
     private _shaking;
     private _temp;
+    private _deferred;
     constructor(grid: ReelGrid, resolve: SymbolResolver, cfg: MotionConfig, win?: WinConfig);
     setConfig(cfg: MotionConfig): void;
     setWin(win: WinConfig): void;
@@ -731,10 +821,17 @@ 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;
-    /** Anticipation time-stretch factor for a reel (>=1, longer = slower). */
+    /** Anticipation time-stretch factor for a reel (>=1, longer = slower). Resolved in `plan()`. */
     private slowOf;
     private _runSwap;
     private _runStrip;
@@ -750,10 +847,13 @@ declare class SpinEngine {
 
 interface AnticipationDecision {
     active: boolean;
-    /** Reel indices that should spin slower / longer. */
+    /** Reel indices that should spin slower / longer, in the order the ramp applies. */
     reels: number[];
-    slowdown: number;
-    holdMs: number;
+    /** Speed factor. A scalar when flat; a per-reel array when the decision ramps (see
+     *  `progressiveSlowdown` / a game-supplied `decide`). Resolve with `perReelValue`. */
+    slowdown: PerReel<number>;
+    /** Extra hold before landing. Scalar or per-reel array, same as `slowdown`. */
+    holdMs: PerReel<number>;
 }
 declare class AnticipationController {
     private _cfg;
@@ -767,6 +867,13 @@ declare class AnticipationController {
      * is flagged for the slow treatment (this mirrors "searching for the last scatter").
      */
     decide(targetGrid: CellData[][]): AnticipationDecision;
+    /** Assemble a decision, applying the configured progression unless the caller pinned values. */
+    private build;
+    /**
+     * A flat scalar when the progression is a no-op, else an array INDEXED BY REEL so the engine can
+     * read a per-reel value straight out of `plan()`.
+     */
+    private ramp;
     /** Optionally zoom the grid in while anticipating, then settle back. Returns a reset fn. */
     zoomIn(grid: ReelGrid): Promise<() => Promise<void>>;
 }
@@ -947,6 +1054,14 @@ interface ReelSystem {
     /** Replace the whole config. */
     setConfig(config: ReelSystemConfig): void;
     spin(target: CellData[][], opts?: SpinRunOpts): Promise<void>;
+    /**
+     * The schedule `spin(target, opts)` WOULD run, without running it — same anticipation decision,
+     * same numbers. Schedule landing sounds / camera moves against this instead of re-deriving the
+     * engine's formula. (`spin`'s `onPlan` hands you the same array once the spin is under way.)
+     */
+    planSpin(target: CellData[][], opts?: SpinRunOpts): ReelStopPlan[];
+    /** The anticipation decision `spin(target, opts)` would use (run options override the config). */
+    anticipationFor(target: CellData[][], opts?: SpinRunOpts): AnticipationDecision;
     /** Run a cascade chain. With `freeSpins` + `cascade.multiplier.persistInFreeSpins`, the multiplier
      *  carries over instead of resetting. Generic in the step type, so `onStep` hands back the game's
      *  own step (with its per-step win) rather than the bare TumbleStep. */
@@ -1056,5 +1171,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, 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, StepRunOpts, 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, 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, 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 };