Events

Two emitters:

• reelSet.events. typed EventEmitter<ReelSetEvents>. Domain-level events for the whole board.
• reel.events. typed EventEmitter<ReelEvents>. Per-column phase / symbol / land events.

Both emitters’ on(name, cb) returns an off() function for unsubscription. The library cleans up its own listeners on destroy(); a thrown exception inside a listener does not stop other listeners on the same event from running (but it is logged and may pollute your error console. handle your own errors).

Quick map

Every cascade event uses the same three-part shape: cascade:<scope>:<step>. Scopes are chain (one stage inside the runCascade loop), fall / place / dropIn / gravity (phase-level animation), destroy (one batch of destroySymbols). Steps are start / symbol / end. :symbol appears only on the per-cell variants of fall, dropIn, and gravity. :place has only :end because placement is a single-moment swap with no animation. The runCascade chain itself is delimited by the returned Promise. await the call to know when it’s done.

Spin lifecycle

interface SpinResult {
  symbols: string[][];   // final visible grid [reelIndex][rowIndex]
  wasSkipped: boolean;   // true if skip() / requestSkip() / slamStop() ended the spin
  duration: number;      // ms from spin:start to spin:complete
}

Skip / slam

reelSet.events.on('skip:boosted', ({ previous, current }) => {
  hud.flash(`SPEED: ${previous.name} → ${current.name}`);
});

Speed

Cascade (tumble)

Available only when the builder used .tumble({...}). The per-symbol events fire before the library’s view.y tween starts so listeners can run parallel tweens that finish in lockstep.

Chain-scoped (one stage inside the loop)

runCascade(...) returns Promise<RunCascadeResult>. await the call to know when the chain is over and read the summary. There’s no separate round-start / round-end event because “round” isn’t a reel-engine concept (the slot industry uses “round” for a bet→payout transaction; for the engine, a round is press-spin → all-stopped, which spin:start / spin:allLanded already cover).

interface RunCascadeResult {
  chainLength: number;     // refill stages that ran (0 = no wins on the initial grid)
  totalWinners: number;    // sum of winners.length across every refill
  finalGrid: string[][];   // grid after the last refill
  wasSkipped: boolean;     // true if the player slammed mid-chain
}

Phase-scoped (animation events on each refill or initial drop)

Destroy-batch-scoped

Event order inside one runCascade() call

Combined-mode refill (default. refillMode: 'combined'):

for each chain stage with winners:
  cascade:chain:start
    cascade:destroy:start
      (destroy tweens, one per cell, parallel)
    cascade:destroy:end
    onCascade callback (optional)
    pause (pauseAfterDestroyMs)
    (refill: per reel. cascade:place:end → cascade:dropIn:start → ... → cascade:dropIn:end)
  cascade:chain:end
// then the awaited runCascade promise resolves with RunCascadeResult

Two-stage refill (refillMode: 'gravity-then-drop') splits the refill into a gravity stage and a drop-in stage with an anticipation window between them:

for each chain stage with winners:
  cascade:chain:start
    cascade:destroy:start → ... → cascade:destroy:end
    onCascade callback (optional)
    pause (pauseAfterDestroyMs)
    (gravity stage: per reel. cascade:place:end → cascade:gravity:start → cascade:gravity:symbol* → cascade:gravity:end)
    hold (Promise.all of `gravityHoldMs` setTimeout + caller-supplied `gravityHold` promise)
    onGravityComplete callback (optional)
    (drop-in stage: per reel. cascade:dropIn:start → cascade:dropIn:symbol* → cascade:dropIn:end)
  cascade:chain:end

Common patterns

// Lock auto-play around the call itself. `await` IS the lifecycle.
hud.lock();
try {
  await reelSet.runCascade({ detectWinners, nextGrid });
} finally {
  hud.unlock();
}

// Per-chain SFX cues.
reelSet.events.on('cascade:chain:start', ({ chain }) => sfx.play(`chain_${Math.min(chain, 5)}`));

// Destroy cue, even when consumers call `destroySymbols` outside runCascade.
reelSet.events.on('cascade:destroy:start', ({ cells }) => sfx.play('shatter', cells.length));

// Decorate ONLY new arrivals (skip survivors).
reelSet.events.on('cascade:place:end', ({ placedSymbols, isInitial, winnerRows }) => {
  const newRowSet = new Set(isInitial ? placedSymbols.map((_, i) => i) : winnerRows);
  for (const [row, sym] of placedSymbols.entries()) {
    if (newRowSet.has(row)) addMultiplierBadge(sym);
  }
});

// Squish each symbol on land, in sync with the library's drop-in tween.
reelSet.events.on('cascade:dropIn:symbol', ({ view, duration }) => {
  // Library will animate view.y; you can animate view.scale on the same beat.
  gsap.to(view.scale, { x: 1.1, y: 0.9, duration: duration / 2000, yoyo: true, repeat: 1 });
});

Spotlight

Wins (WinPresenter)

Emitted by WinPresenter only. listeners are dead weight if you don’t use it.

Pins

MultiWays

Lifecycle

Per-reel events

reel.events is a smaller surface scoped to one column.

type ReelEvents = {
  'phase:enter':     [phaseName: string];
    // 'start' | 'spin' | 'stop' | 'anticipation' | 'adjust'
    // | 'cascade:fall' | 'cascade:place' | 'cascade:dropIn'
  'phase:exit':      [phaseName: string];
  'symbol:created':  [symbolId: string, row: number];
  'landed':          [symbols: string[]];
  'destroyed':       [];
};

reelSet.getReel(4).events.on('phase:enter', (name) => {
  if (name === 'anticipation') playTensionMusic();
});

Listener etiquette

• Subscribe once at startup; on() returns an off() you can store for hot-swap modules.
• Async listeners run “fire and forget.” If you must await per-event work, queue it yourself. the engine doesn’t.
• The library emits cascade:*:symbol events BEFORE its own tween starts. Your listener can read the same view and queue a parallel tween. they’ll run in lockstep.
• The Cell type used in cascade payloads is { reel: number; row: number } (column = reel, visible row = row). Same shape as destroySymbols input.