ReelSetBuilder

pixi-reels

pixi-reels / index / ReelSetBuilder

Class: ReelSetBuilder

Defined in: core/ReelSetBuilder.ts:65

The configurator you call before every reel set.

ReelSetBuilder is a fluent, chainable builder: every call returns the builder so you can string setup onto one expression. It hides the twenty-odd subsystems you would otherwise have to wire by hand, and its .build() step validates that every required piece is present (throws at construction, not at first spin).

Required calls (in any order): .reels(n), .visibleRows(n), .symbolSize(w, h), .symbols((registry) => ...), .ticker(app.ticker). Optional: .symbolGap(), .weights(), .symbolData(), .speed(), .bufferSymbols(), .offset(), .frameMiddleware(), .phases(), .spinningMode().

const reelSet = new ReelSetBuilder()
  .reels(5)
  .visibleRows(3)
  .symbolSize(200, 200)
  .symbols((r) => {
    r.register('cherry', SpriteSymbol, { textures: { cherry: tex } });
  })
  .weights({ cherry: 20 })
  .ticker(app.ticker)
  .build();

Constructors

Constructor

new ReelSetBuilder(): ReelSetBuilder;

Returns

ReelSetBuilder

Methods

bufferSymbols()

bufferSymbols(count: number): this;

Defined in: core/ReelSetBuilder.ts:259

Set number of buffer symbols above/below the visible area. Default: 1.

Buffer rows are off-screen cells the reel keeps around the visible window so symbols can fade/slide in cleanly. The motion layer’s wrap detection assumes at least one buffer row above and one below. the minimum supported value is 1. Passing 0 (or a negative number) is clamped to 1 and a single console warning is printed; the builder does not throw, so existing user code keeps running.

Parameters

Returns

this

build()

build(): ReelSet;

Defined in: core/ReelSetBuilder.ts:482

Build the ReelSet. Validates configuration and assembles all internal objects.

Returns

ReelSet

frameMiddleware()

frameMiddleware(middleware: FrameMiddleware): this;

Defined in: core/ReelSetBuilder.ts:409

Add custom frame middleware.

Parameters

Returns

this

gsap()

gsap(instance: typeof gsap): this;

Defined in: core/ReelSetBuilder.ts:397

Inject the GSAP instance the engine should use for tweens.

When you need this: if your app already imports gsap and your bundler resolves gsap to a different module instance than the one pixi-reels resolved (common with symlinked workspaces, npm-link, or misconfigured dedupe), every tween you start on a target the engine also tweens will fight a separate timeline. Symptoms: spotlights that render but never finish, animations that double-fire, tweens that silently drop on hidden tabs in only one of the two instances.

Calling .gsap(myGsap) rebinds every internal phase, motion tween, pin-flight tween, and SpriteSymbol win pulse to the GSAP you pass. guaranteed to be the same instance that drives your own animations.

Default: the gsap import resolved at the engine’s own node_modules/gsap path. If your app and the engine resolve to the same instance (the common case in production bundles with proper dedupe), you do NOT need to call this.

Idempotent. calling again with the same instance is a no-op. Calling with a different instance after .build() only affects tweens started after the swap.

Parameters

Returns

this

Example

import { gsap } from 'gsap';
const reelSet = new ReelSetBuilder()
  .reels(5).visibleRows(3).symbolSize(200, 200)
  .symbols(...)
  .ticker(app.ticker)
  .gsap(gsap)              // ensure engine and app share one instance
  .build();

initialFrame()

initialFrame(frame: ColumnTarget[]): this;

Defined in: core/ReelSetBuilder.ts:472

Set the initial symbol grid the reels show before the first spin.

One ColumnTarget per reel. visible lists the symbols in the visible window; optional bufferAbove / bufferBelow prefill cells outside it ([0] is the slot closest to the visible window, later indices go further out).

Parameters

Returns

this

Example

builder.initialFrame([
  { visible: ['A','B','C'] },
  { visible: ['A','B','C'], bufferAbove: ['COIN'] },
  { visible: ['A','B','C'], bufferBelow: ['SCATTER'] },
]);

initialSpeed()

initialSpeed(name: string): this;

Defined in: core/ReelSetBuilder.ts:313

Set which speed profile to use initially. Default: ‘normal’.

Parameters

Returns

this

maskStrategy()

maskStrategy(strategy: MaskStrategy): this;

Defined in: core/ReelSetBuilder.ts:175

Custom mask strategy for the viewport. Defaults to RectMaskStrategy (one clip rect per reel. clean for pyramid + uniform layouts).

Use SharedRectMaskStrategy when reels have horizontal gaps AND symbols (typically big symbols) need to overlap across reel boundaries. the per-reel default would clip them at the gaps.

Or pass any custom MaskStrategy for non-rectangular masks (rounded frames, hexagonal grids, etc.).

Parameters

Returns

this

Example

import { SharedRectMaskStrategy } from 'pixi-reels';
builder.maskStrategy(new SharedRectMaskStrategy())

multiways()

multiways(config: MultiWaysConfig): this;

Defined in: core/ReelSetBuilder.ts:202

Configure this slot as MultiWays: per-spin row variation. Pass minRows, maxRows, and the fixed reel pixel height. After build, call reelSet.setShape(rowsPerReel) mid-spin to set the next stop’s shape.

Mutually exclusive with big-symbol registration (SymbolData.size). Mutually exclusive with cascade mode in v1.

Parameters

Returns

this

offsetConfig()

offsetConfig(config: OffsetConfig): this;

Defined in: core/ReelSetBuilder.ts:319

Set X-axis offset config (e.g., trapezoid perspective). Default: ‘none’.

Parameters

Returns

this

phases()

phases(configurator: (factory: PhaseFactory) => void): this;

Defined in: core/ReelSetBuilder.ts:415

Override default phases.

Parameters

Returns

this

pinMigrationDuration()

pinMigrationDuration(value: number | ((reelIndex: number) => number)): this;

Defined in: core/ReelSetBuilder.ts:216

AdjustPhase tween duration in ms (MultiWays only). Pass a number for a uniform duration across reels, or a function (reelIndex) => number for per-reel control. Default: 200. Pass 0 for an instant snap (no tween).

AdjustPhase plays on top of whatever stop staggering you’ve configured . its duration is independent of stopDelay.

Parameters

Returns

this

pinMigrationEase()

pinMigrationEase(ease: string): this;

Defined in: core/ReelSetBuilder.ts:231

GSAP easing string used by AdjustPhase tweens (MultiWays only). Applied to both the cell-resize tween and any pin-overlay migration tween. Defaults to 'power2.out'. See gsap.com/docs/v3/Eases for the full vocabulary.

Parameters

Returns

this

Example

builder.pinMigrationEase('back.out(1.4)')          // pop-in feel
builder.pinMigrationEase('expo.inOut')             // slow start + slow end

poolCapacity()

poolCapacity(maxPerSymbol: number): this;

Defined in: core/ReelSetBuilder.ts:359

Override the per-symbol-id recycle-pool capacity. By default the engine sizes the pool to the whole strip (every visible + buffer cell), so even a grid that is briefly all one symbol recycles instead of churning through destroy() + recreate. Set this only to cap memory on very large grids, or to raise headroom for unusually heavy simultaneous symbol swaps.

Parameters

Returns

this

reelAnchor()

reelAnchor(anchor: ReelAnchor): this;

Defined in: core/ReelSetBuilder.ts:155

Vertical alignment of short reels inside the tallest reel’s box. Default ‘center’.

Parameters

Returns

this

reelPixelHeights()

reelPixelHeights(heights: number[]): this;

Defined in: core/ReelSetBuilder.ts:149

Per-reel pixel-box heights. Length MUST equal reels().

• Pyramid: defaults to visibleRowsPerReel[i] * symbolHeight. Override to make all reels the same height with different cell heights per reel.
• MultiWays: every entry equals the same fixed reel height. Cell height per reel is derived as reelPixelHeight / visibleRows[i].

Precedence: when both reelPixelHeights and reelAnchor are set, reelPixelHeights wins. anchor is derived from the explicit boxes.

Parameters

Returns

this

reels()

reels(count: number): this;

Defined in: core/ReelSetBuilder.ts:107

Set number of reel columns.

Parameters

Returns

this

rng()

rng(fn: () => number): this;

Defined in: core/ReelSetBuilder.ts:347

Inject the source of randomness used to fill the scrolling strip (buffer fill, the symbols shown during SPIN before setResult lands, nudge padding). Must return a value in [0, 1). Default: Math.random.

Why you’d set this: server-authoritative outcomes do not make the on-screen strip reproducible — the symbols a player sees scrolling are drawn from this RNG. Injecting a seeded, audited PRNG lets you replay the exact visual sequence from a seed, which provably-fair and regulated real-money deployments are eventually required to produce.

Parameters

Returns

this

Example

import { ReelSetBuilder } from 'pixi-reels';
const seeded = mulberry32(serverSeed); // your audited PRNG
const reelSet = new ReelSetBuilder().reels(5).visibleRows(3)
  .symbols(...).ticker(app.ticker).rng(seeded).build();

speed()

speed(name: string, profile: SpeedProfile): this;

Defined in: core/ReelSetBuilder.ts:307

Add a named speed profile.

Parameters

Returns

this

spinningMode()

spinningMode(mode: SpinningMode): this;

Defined in: core/ReelSetBuilder.ts:403

Set the spinning mode. Default: StandardMode.

Parameters

Returns

this

symbolData()

symbolData(overrides: Record<string, Partial<SymbolData>>): this;

Defined in: core/ReelSetBuilder.ts:301

Per-symbol metadata overrides (zIndex, unmask, or a custom weight that replaces the one from weights()). Merged into the final symbolsData map . any field you don’t specify falls back to the default.

Parameters

Returns

this

Example

.symbolData({
  wild:  { zIndex: 5 },                // render above neighbours
  bonus: { zIndex: 10, unmask: true }, // render outside the reel mask
})

symbolGap()

symbolGap(x: number, y: number): this;

Defined in: core/ReelSetBuilder.ts:244

Set gap between symbols. Default: { x: 0, y: 0 }.

Parameters

Returns

this

symbols()

symbols(configurator: (registry: SymbolRegistry) => void): this;

Defined in: core/ReelSetBuilder.ts:279

Configure symbols via a registry callback.

Parameters

Returns

this

symbolSize()

symbolSize(width: number, height: number): this;

Defined in: core/ReelSetBuilder.ts:237

Set symbol dimensions in pixels.

Parameters

Returns

this

ticker()

ticker(ticker: Ticker): this;

Defined in: core/ReelSetBuilder.ts:325

Set the PixiJS ticker for frame updates.

Parameters

Returns

this

tumble()

tumble(config?: TumbleConfig): this;

Defined in: core/ReelSetBuilder.ts:451

Enable tumble cascade mechanics. Replaces strip-spin + bounce-stop with a three-phase pipeline:

1. cascade:fall. on spin(), existing visible symbols fall off the bottom of the viewport.
2. cascade:place. when setResult() arrives, new symbol identities swap into the buffer at their final grid positions.
3. cascade:dropIn. new symbols animate from above (and survivors slide down to fill holes) into the grid.

For a Moment B refill after wins are cleared, call reelSet.refill({ winners, grid }). that skips fall + wait and runs place + dropIn only, with gravity-correct geometry driven by the winners list (untouched symbols don’t animate; survivors slide; new symbols come from above).

Every phase boundary fires a cascade:* event on reelSet.events. per-symbol events (cascade:fall:symbol / cascade:dropIn:symbol) carry the symbol, view, and the timing the library is about to apply, so listeners can run parallel tweens on any other property in sync with the library’s view.y motion.

Override any individual phase via .phases(f => f.register('cascade:fall', MyPhase)).

Parameters

Returns

this

Example

builder.tumble({
  fall:   { duration: 300, ease: 'sine.in',    rowStagger: 60 },
  dropIn: { duration: 600, ease: 'power2.out', rowStagger: 60, distance: 'perHole' },
});

visibleRows()

visibleRows(count: number): this;

Defined in: core/ReelSetBuilder.ts:120

Number of visible rows per reel (uniform across all reels). Mutually exclusive with visibleRowsPerReel(). calling both throws at build().

Parameters

Returns

this

Example

builder.reels(5).visibleRows(3)  // classic 5x3

visibleRowsPerReel()

visibleRowsPerReel(rows: number[]): this;

Defined in: core/ReelSetBuilder.ts:132

Per-reel static row counts. Length MUST equal reels(). Mutually exclusive with visibleRows(); calling both throws at build().

Parameters

Returns

this

Example

builder.reels(5).visibleRowsPerReel([3, 5, 5, 5, 3])  // pyramid

weights()

weights(weights: Record<string, number>): this;

Defined in: core/ReelSetBuilder.ts:285

Set weights for random symbol generation.

Parameters

Returns

this