ReelSet

ReelSet extends PIXI.Container. Construct via ReelSetBuilder, add it to your stage, then drive it with the verbs below.

Every method on this page is non-async unless its return type is Promise. Promises always resolve. the engine doesn’t reject on user error; it throws synchronously at the call site instead, so errors land in the same stack frame you wrote.

Spin

const result = await reelSet.spin({ holdReels: [0, 4] });
console.log(result.symbols);       // final visible grid
console.log(result.wasSkipped);    // true if slam ended the spin

Cascade (tumble)

Available when the builder was configured with .tumble({...}). See the cascades guide for the mental model.

import type { Cell, RunCascadeResult } from 'pixi-reels';

// Moment A. fall, wait, drop in.
const spinDone = reelSet.spin({ mode: 'cascade' });
reelSet.setResult(await server.spin());
await spinDone;

// Moment B. N refills until no more wins.
const summary: RunCascadeResult = await reelSet.runCascade({
  detectWinners: (grid): Cell[] => myClusterDetector(grid),
  nextGrid:      (_, winners) => server.cascade(winners),
  onCascade:     ({ chain }) => ui.bumpMultiplier(chain),
});
console.log(summary.chainLength, summary.totalWinners, summary.wasSkipped);

Types

// Cancellation via AbortSignal. the right shape for "player tapped slam
// between refills" (reelSet.skipSpin() is a no-op when the engine is idle).
const controller = new AbortController();
skipBtn.addEventListener('click', () => controller.abort());

const { wasSkipped } = await reelSet.runCascade({
  detectWinners, nextGrid,
  signal: controller.signal,
});

runCascade listens to skip:requested too. Calling reelSet.skipSpin() during an in-flight refill works as expected, but the AbortSignal pattern is the one that handles the idle-window case.

Two-stage refill

refill({ mode: 'gravity-then-drop' }) splits the refill into two beats: survivors slide first, then a global hold for anticipation visuals, then new symbols enter. This is the Reactoonz / Gates of Olympus / Mummyland feel. 'combined' (default) is the Sweet Bonanza / Sugar Rush feel.

// Single refill. pass the promise directly.
await reelSet.refill({
  winners,
  grid: nextGrid,
  mode: 'gravity-then-drop',
  gravityHoldMs: 150,                 // minimum wall-clock floor (default 250)
  gravityHold: multiplierRoll.done,   // OR an already-in-flight animation
  onGravityComplete: () => sfx.peak(),// awaitable hook between stages
});

gravityHoldMs and gravityHold race in parallel via Promise.all. whichever finishes LAST gates the drop-in. Pass both when you want a wall-clock floor under an animation that might be fast. onGravityComplete runs after both, so it can read post-hold state.

// Per-cascade. runCascade calls the builder once per chain stage.
await reelSet.runCascade({
  detectWinners, nextGrid,
  refillMode:    'gravity-then-drop',
  gravityHoldMs: 150,
  gravityHold:   ({ chain }) => multiplier.bumpTo(chain + 1).done,
});

The events cascade:gravity:start / cascade:gravity:symbol / cascade:gravity:end fire only in this mode. see the events reference.

Heads-up. If your gravityHold promise never resolves, the engine will wait forever. the cascade hangs. There’s no built-in timeout. If your animation source can stall (animation library error, missed user input, hung XHR), wrap it in your own Promise.race([yourPromise, timeoutReject]) before passing it in, or rely on gravityHoldMs alone. A rejection in gravityHold propagates through Promise.all and rejects the refill() / runCascade() call. handle it in your own try block.

MultiWays

Available when the builder was configured with .multiways({...}).

Speed

Spotlight + wins

The library ships WinPresenter as a higher-level events-driven win driver. listen to win:start, win:group, win:symbol, win:end.

Pins (persistent cell claims)

Cell / footprint queries

Frame middleware (runtime-mutable)

reelSet.frame.use(featureWildsMiddleware);
// ... feature exit
reelSet.frame.remove('feature-wilds');

Reel access

Events

reelSet.events is a typed EventEmitter<ReelSetEvents>. See the events reference for the full surface. Per-reel events live on reel.events.

reelSet.events.on('spin:complete', (r) => console.log(r.symbols));
const off = reelSet.events.on('cascade:dropIn:symbol', squishOnLand);
off(); // unsubscribe

Lifecycle

Example. minimal cascade slot

import { ReelSetBuilder, SpriteSymbol } from 'pixi-reels';

const reelSet = new ReelSetBuilder()
  .reels(6).visibleRows(5).symbolSize(95, 95).symbolGap(5, 5)
  .symbols((r) => { /* register your sprites */ })
  .tumble({
    fall:   { duration: 280, ease: 'sine.in',       rowStagger: 40 },
    dropIn: { duration: 480, ease: 'back.out(1.6)', rowStagger: 50 },
  })
  .ticker(app.ticker)
  .build();
app.stage.addChild(reelSet);

const spinDone = reelSet.spin();
reelSet.setResult(await server.spin());
await spinDone;

await reelSet.runCascade({
  detectWinners: detectWins,
  nextGrid:      (_, winners) => server.cascade(winners),
});