RefillOptions

Interface: RefillOptions

Defined in: core/ReelSet.ts:105

Options for ReelSet.refill. The two required fields encode what just happened (winners) and what the next visible state should be (grid). Everything else is timing / cancellation / animation flavor with sensible defaults.

Use this directly when you’re driving your own cascade loop. For the common case of “destroy → refill → check → repeat”, use ReelSet.runCascade instead. it composes refill, destroySymbols, and win-detection into one call with the same cancellation semantics.

Properties

Property	Type	Description	Defined in
`gravityHold?`	`Promise`<`void`> \| (() => `Promise`<`void`>)	Promise (or zero-arg factory) gating the drop-in stage. Only applies when `mode === 'gravity-then-drop'`. - `Promise<void>`. pass an already-in-flight animation / SFX / network call’s completion handle when you want the drop-in to wait for it. The promise is awaited as-is. - `() => Promise<void>`. pass a factory when the side effects of starting the promise should fire AT gravity-end, not at refill-start. Combines via `Promise.all` with `gravityHoldMs`. pass both to floor the hold to a minimum wall-clock duration even if the promise resolves earlier.	core/ReelSet.ts:148
`gravityHoldMs?`	`number`	Fixed wall-clock pause (ms) between the gravity stage and the drop-in stage. Only applies when `mode === 'gravity-then-drop'`. Default `250`. Combines via `Promise.all` with `gravityHold` if both are provided. whichever finishes LAST gates the drop-in.	core/ReelSet.ts:132
`grid`	`ColumnTarget`[]	Target grid after refill. Convention: the top `winners.length` rows per reel are new symbols falling in from above; the rest are survivors in their original top-to-bottom order. Same contract as the `nextGrid` callback in `runCascade`.	core/ReelSet.ts:114
`mode?`	`"combined"` \| `"gravity-then-drop"`	Pick the refill animation flavor. - `'combined'` (default). survivors and new symbols animate together in one drop-in beat. The Sweet Bonanza / Sugar Rush feel. - `'gravity-then-drop'`. survivors slide down to fill holes FIRST, then a global pause (`gravityHoldMs` + `gravityHold`), then new symbols enter from above. Useful when you want a multiplier or SFX beat between the two motions.	core/ReelSet.ts:125
`onGravityComplete?`	() => `void` \| `Promise`<`void`>	Awaitable callback fired AFTER `gravityHoldMs` + `gravityHold` both resolve, BEFORE the drop-in stage. Only fires when `mode === 'gravity-then-drop'`. Use for last-mile side effects that need to read the post-hold state.	core/ReelSet.ts:155
`signal?`	`AbortSignal`	Abort signal. Aborting mid-refill slams the in-flight animation so the await unblocks immediately rather than waiting for the drop-in to finish. The returned promise still resolves normally with `wasSkipped: true`. Mirrors the abort contract on RunCascadeOptions.signal and DestroySymbolsOptions.signal.	core/ReelSet.ts:163
`winners`	readonly `Cell`[]	Winners that were just destroyed. Their cells will be refilled per gravity.	core/ReelSet.ts:107