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 the emitter, for chaining. Unsubscribe with off(name, fn) — keep a reference to the same function. The library cleans up its own listeners on destroy(). A thrown exception inside a listener does stop the remaining listeners for that event and propagates out of emit() into the engine — emit() has no try/catch, and nothing is logged. Wrap anything that can throw.

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#

Anticipation#

Only fires for reels that actually tease: in the anticipation set AND with a hold above 0.

interface SpinResult {
  symbols: string[][];              // final visible grid [reelIndex][cellIndex]
  wasSkipped: boolean;              // true if skipSpin() / requestSkip() / slamStop() ended the spin
  skipMode: SkipMode | null;        // the mode of the last press that freed reels
  skipContext: SkipContext | null;  // that press: { mode, speed?, payload? }; { mode: 'slam' } for an engine slam
  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
  skipContext: SkipContext | null;  // the press that ended it, or null; an abort is { mode: 'slam' }
}

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, winnerCells }) => {
  const newRowSet = new Set(isInitial ? placedSymbols.map((_, i) => i) : winnerCells);
  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 });
});

Nudge#

Fired by reelSet.nudge(reel, opts). landed does not fire for a nudge — that belongs to the spin pipeline.

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.

Every bus (reelSet.events, reel.events, a board’s events) also takes onAny((event, ...args) => ...) / offAny(fn): every event, name first, after the event’s own listeners. For a trace, an events panel, a recorder; game logic names the events it wants. Engine notices are not events; onNotice(fn) hears them the same way, whatever the log level.

type ReelEvents = {
  'phase:enter':     [phaseName: string];
    // 'start' | 'spin' | 'stop' | 'anticipation' | 'adjust' | 'nudge'
    // (+ 'cascade:fall' | 'cascade:place' | 'cascade:dropIn' on a tumble set)
    // | 'cascade:fall' | 'cascade:place' | 'cascade:dropIn'
  'phase:exit':      [phaseName: string];
  'phase:step':      [{ phase: string, step: string, status: PhaseStepStatus }];
    // a step of a phase on runSteps(): 'start' | 'end' | 'skipped' (a cut
    // step a quicken never started) | 'cut' (the cut step a quicken stopped
    // in flight) | 'cancelled' (the step a slam or a destroy stopped)
  'symbol:created':  [symbolId: string, stripIndex: number];
  'landed':          [symbols: string[]];
  'destroyed':       [];
};

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

Listener etiquette#

• Subscribe once at startup; for hot-swap modules keep the function reference and call off(name, fn).
• 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; cell: number } (column = reel, visible cell = cell). Same shape as destroySymbols input.

Console notices#

Everything the library prints goes through one channel, so notices all look the same and all carry a stable CODE you can grep for, search the docs for, or quote in a bug report.

import { setLogLevel } from 'pixi-reels';

setLogLevel('warn');   // drop the advisory notices, keep problems
setLogLevel('silent'); // production

'silent' | 'error' | 'warn' | 'info', each level including the ones before it. Default 'info' (everything) - see the debugging guide for what each level covers and why the default is not quieter. In a browser a notice prints as a styled badge - pixi-reels, then the code, then the message; elsewhere it degrades to [pixi-reels] warn(code) message, since %c is a browser console feature.

Notices keep using console.warn / console.error / console.info rather than one console.log, so devtools level filtering and stack capture still work, and detail arguments pass through untouched (an Error keeps its stack).