Reel

pixi-reels

pixi-reels / index / Reel

Class: Reel

Defined in: core/Reel.ts:172

One vertical column of a slot board.

A Reel owns:

• the ReelSymbol[] currently on screen (a small buffer above the visible rows + the visible rows + a small buffer below. so symbols can fade in from off-screen cleanly)
• the ReelMotion that adds a Y delta each tick and wraps symbols that scroll off the ends
• a StopSequencer. the queue of target symbols the reel still has to land on before it can stop

You generally do not touch a Reel directly. Drive the ReelSet and let it fan out. Reels are exposed on reelSet.reels so you can read the current grid (reel.getSymbolAt(row)) or listen to per-reel events (phase:enter, landed, symbol:created, …).

Implements

• Disposable

Constructors

Constructor

new Reel(
   config: ReelConfig, 
   symbolFactory: SymbolFactory, 
   randomProvider: RandomSymbolProvider, 
   viewport: ReelViewport): Reel;

Defined in: core/Reel.ts:251

Parameters

Returns

Reel

Properties

Accessors

bufferAbove

Get Signature

get bufferAbove(): number;

Defined in: core/Reel.ts:330

Returns

number

bufferBelow

Get Signature

get bufferBelow(): number;

Defined in: core/Reel.ts:334

Returns

number

isDestroyed

Get Signature

get isDestroyed(): boolean;

Defined in: core/Reel.ts:313

Returns

boolean

Implementation of

Disposable.isDestroyed

isNudging

Get Signature

get isNudging(): boolean;

Defined in: core/Reel.ts:326

True while a nudge() tween is in flight on this reel.

Returns

boolean

isStopping

Get Signature

get isStopping(): boolean;

Defined in: core/Reel.ts:317

Returns

boolean

Set Signature

set isStopping(value: boolean): void;

Defined in: core/Reel.ts:321

Parameters

Returns

void

offsetY

Get Signature

get offsetY(): number;

Defined in: core/Reel.ts:363

Y offset of this reel relative to the viewport top. Set by builder, immutable.

Returns

number

reelHeight

Get Signature

get reelHeight(): number;

Defined in: core/Reel.ts:358

Pixel height of this reel’s box. Set by builder, immutable.

Returns

number

spinSymbolHeight

Get Signature

get spinSymbolHeight(): number;

Defined in: core/Reel.ts:372

SPIN-time uniform cell height. All reels in a slot use this value during the SPIN phase regardless of their per-reel symbolHeight. Frozen at construction.

Returns

number

symbolHeight

Get Signature

get symbolHeight(): number;

Defined in: core/Reel.ts:353

The symbol cell height (in pixels). Mutates on MultiWays reshape via reshape(). During SPIN this still equals spinSymbolHeight; the per-reel target value comes into effect when AdjustPhase commits the reshape. For non-MultiWays slots this is constant for the reel’s lifetime.

Returns

number

symbolWidth

Get Signature

get symbolWidth(): number;

Defined in: core/Reel.ts:343

The symbol cell width (in pixels). Constant for the reel’s lifetime.

Returns

number

visibleRows

Get Signature

get visibleRows(): number;

Defined in: core/Reel.ts:338

Returns

number

Methods

_setOccupancy()

_setOccupancy(visibleRow: number, anchorRow: number | null): void;

Defined in: core/Reel.ts:478

Record that the given visible row is the non-anchor cell of a big symbol whose anchor lives at anchorRow. Pass null to clear the occupancy mark.

@internal. called by _finalizeFrame and the big-symbol coordinator.

Parameters

Returns

void

destroy()

destroy(): void;

Defined in: core/Reel.ts:1105

Returns

void

Implementation of

Disposable.destroy

getSymbolAt()

getSymbolAt(visibleRow: number): ReelSymbol;

Defined in: core/Reel.ts:454

Get symbol at a visible row (0-indexed from top visible). For non-anchor cells of a big symbol, walks up to the anchor row and returns the anchor symbol so animations target the actual visual.

Parameters

Returns

ReelSymbol

getVisibleSymbols()

getVisibleSymbols(): string[];

Defined in: core/Reel.ts:418

Get visible symbol IDs (top to bottom, excluding buffers).

Big-symbol cells resolve to the anchor’s id. both same-reel (the anchor lives on this reel) and cross-reel (the anchor is on a leftward reel of a wider block). The cross-reel resolver is injected by ReelSet; without it, cross-reel OCCUPIED cells would return the OCCUPIED sentinel, which is the only difference vs. ReelSet.getVisibleGrid(). With the resolver wired, the two are equivalent for any reel. reels.map(r => r.getVisibleSymbols()) matches reelSet.getVisibleGrid().

Returns

string[]

nudge()

nudge(options: NudgeOptions, onPrepared?: () => void): Promise<{
  symbols: string[];
}>;

Defined in: core/Reel.ts:643

Shift the reel by distance symbol positions, animating the strip with a GSAP tween and revealing caller-supplied incoming symbols. The reel must be at rest (post-stop). throws otherwise.

The wrap pipeline drives identity changes during the tween: any incoming symbol whose final destination is reachable via pre-placement (within the leading buffer) is set up front; the rest stream through the wrap callback as the strip moves. incoming is always top-down by final on-strip position. see NudgeOptions.incoming for the overflow rules.

Big symbols are supported as long as every block on the strip (anchor + stubs) survives the rotation without crossing the wrap boundary:

• down: anchorRow + h - 1 + distance < total
• up: anchorRow ≥ distance

Blocks that wouldn’t survive throw, as do cross-reel blocks (w > 1). Use case: a 1xH block lands with stubs in bufferBelow. nudge up to bring the whole block into view.

Throws if:

• the reel is spinning, stopping, already nudging, or destroyed,
• distance < 1, >= total strip capacity, direction invalid, or incoming.length !== distance,
• any incoming id is unregistered or is a big symbol,
• any block on the reel wouldn’t survive the rotation,
• any cell on this reel is part of a cross-reel block (w > 1),
• the abort signal is already aborted on entry.

Resolves with { symbols }. the new visible column top-to-bottom. Rejects with an AbortError if options.signal aborts mid-tween or if the reel is destroyed before the tween completes.

Parameters

Returns

Promise<{ symbols: string[]; }>

placeSymbols()

placeSymbols(symbolIds: string[]): void;

Defined in: core/Reel.ts:977

Place symbols immediately at target positions (for skip/turbo).

symbolIds[0..n-1] is the visible area. symbolIds[n..] (if present) targets buffer-below slots. Buffer-above slots are addressed via negative-index string properties: symbolIds[-1] is the slot closest to the visible top row, symbolIds[-bufferAbove] the furthest above. Unset slots are filled with random symbols, matching the previous behaviour when only visible-area entries were provided.

Parameters

Returns

void

refreshZIndex()

refreshZIndex(): void;

Defined in: core/Reel.ts:1094

Recompute zIndex for every symbol in the reel.

Formula: symbolData.zIndex ?? 0 (scaled by 100 to leave room for row ordering), plus the symbol’s current array index. so bottom-row symbols render in front of top-row symbols and any symbol with a higher configured base zIndex (e.g. wild, bonus) renders above its neighbors.

Called automatically after wraps, snaps, and direct placement. Also called inline by _replaceSymbol for the single newly-placed symbol. so consumers who swap one symbol at a time (via the public APIs that funnel into _replaceSymbol) get correct layering for free, no manual refreshZIndex required. Call it manually after mutating symbolsData.zIndex at runtime.

Returns

void

reshape()

reshape(
   newVisibleRows: number, 
   newSymbolHeight: number, 
   bufferAbove: number, 
   bufferBelow: number): void;

Defined in: core/Reel.ts:1014

@internal. MultiWays orchestration only.

Commit a new visible-row count and per-reel cell height. Resizes every existing symbol on the strip to the new cell height, rebuilds the symbol array (extending or truncating buffers as needed), reshapes the motion layer, and recomputes _reelHeight from the new geometry so reelHeight stays consistent. Idempotent if the shape doesn’t change.

Only the engine should call this. SpinController._applyReshape is the single source of truth for reshape orchestration. Direct external calls are unsupported and may leave pin overlays, the cross-reel resolver, and the parent ReelSet’s shape state out of sync. Use ReelSet.setShape() instead, which gates this method on a MultiWays slot and migrates pins atomically.

Parameters

Returns

void

setSymbolAt()

setSymbolAt(visibleRow: number, symbolId: string): void;

Defined in: core/Reel.ts:560

Swap the symbol at a single visible row in-place, without restarting the spin or rebuilding the rest of the strip.

Useful for live presentation effects at rest. converting a wild after a cascade pop, swapping to a sticky variant after a win. without going through the full placeSymbols / setResult paths.

The symbol’s zIndex, parent (masked vs unmasked), and visual state are reset by _replaceSymbol so callers don’t need to follow up with refreshZIndex. The motion layer is not snapped. call snapToGrid() separately if you need to re-grid.

Throws if:

• the reel is currently moving (speed !== 0 or isStopping). A mid-spin swap would be overwritten by the next wrap/stop frame anyway; the fail-loud throw spares the caller the silent loss.
• visibleRow is out of [0, visibleRows).
• symbolId is not registered.
• the row is a non-anchor cell of an existing big-symbol block.
• the row currently holds the anchor of a big-symbol block. big blocks span multiple cells (and possibly reels) and require placeSymbols + the cross-reel OCCUPIED coordinator.
• symbolId itself is a big symbol. same reason.

Pin overlap is not detected at this layer (Reel doesn’t see the pin map). Use ReelSet.setSymbolAt(col, row, id) for the safe caller-facing surface that also throws on pinned cells.

Parameters

Returns

void

skipNudge()

skipNudge(): void;

Defined in: core/Reel.ts:957

Fast-forward the active nudge tween to its landed state and resolve. No-op if no nudge is in flight. The tween’s onComplete fires synchronously, the strip snaps to the final position, _nudgeQueue drains, and the original nudge() promise resolves on the next microtask.

Useful for player-driven “skip” buttons or accessibility paths that want to land immediately without waiting for the full animation.

Returns

void

update()

update(deltaMs: number): void;

Defined in: core/Reel.ts:377

Update reel for one frame. Called by SpinController via ticker.

Parameters

Returns

void