HoldAndWinBuilder\<TData = `unknown`\>

pixi-reels

pixi-reels / index / HoldAndWinBuilder

Class: HoldAndWinBuilder<TData = unknown>

Defined in: board/HoldAndWinBuilder.ts:22

Fluent builder for HoldAndWinBoard.

A Hold & Win board is a W×H grid of cells that spin independently - the mechanic’s atomic unit is the cell, the engine’s is the column, so each cell is its own 1×1 ReelSet. This builder wires that grid plus the round choreography; everything value-shaped stays in the game layer (see HoldAndWinBoard).

TData types the opaque payload carried on each coin’s data.

Type Parameters#

Constructors#

Constructor#

new HoldAndWinBuilder<TData = unknown>(): HoldAndWinBuilder<TData>;

Returns#

HoldAndWinBuilder<TData>

Methods#

anticipateWhen()#

anticipateWhen(fn: (state: {
  capacity: number;
  locked: number;
  respinsLeft: number;
}) => boolean): this;

Defined in: board/HoldAndWinBuilder.ts:246

When the predicate returns true for a wave, every spinning cell uses a drawn-out tension profile - the “one cell left for Grand” moment. Evaluated once per wave for the whole board (not per cell), against the pre-wave state.

Parameters#

Returns#

this

axis()#

axis(orientation: Orientation, direction?: Direction): this;

Defined in: board/HoldAndWinBuilder.ts:286

Which way each cell’s strip travels while it spins. Cells are 1x1 reel sets, so this picks the edge a coin scrolls in from; the board’s own cols x rows layout is unaffected. Defaults to vertical / forward.

Parameters#

Returns#

this

build()#

build(): HoldAndWinBoard<TData>;

Defined in: board/HoldAndWinBuilder.ts:303

Returns#

HoldAndWinBoard<TData>

cellChrome()#

cellChrome(draw: (g: Graphics, width: number, height: number) => void): this;

Defined in: board/HoldAndWinBuilder.ts:258

Per-cell background, drawn behind each mini reel, handed the cell’s width and height. A callback written for a square board that only reads the first argument keeps working.

Parameters#

Returns#

this

cellMask()#

cellMask(factory: (cell: HwCell, info: BoardCellMaskInfo) => MaskStrategy): this;

Defined in: board/HoldAndWinBuilder.ts:276

Mask for each cell, built once per cell. Default: a shared rect over the cell. () => new RoundedRectMaskStrategy({ radius: 8 }) rounds every cell’s corners to match a rounded frame drawn behind the board.

The factory receives the cell and the board corners it sits on, so a board framed as ONE rounded window keeps every cell a plain rect except the four corner cells, each rounded on its outer corner only:

.cellMask((_, { corners }) => new RoundedRectMaskStrategy({ radius: 18, corners }))

Parameters#

Returns#

this

cellSize()#

cellSize(size: 
  | number
  | {
  height: number;
  width: number;
}, opts?: HwCellSizeOptions): this;

Defined in: board/HoldAndWinBuilder.ts:65

Cell size in pixels - one number for square cells, { width, height } for rectangular ones - plus the gaps between cells. gap sets both axes; columnGap / rowGap override one each, so { columnGap: 6, rowGap: 0 } gives touching rows with a seam between columns.

Parameters#

Returns#

this

cellZIndex()#

cellZIndex(resolver: BoardCellZIndexResolver): this;

Defined in: board/HoldAndWinBuilder.ts:181

Draw order of the cells’ lifted art - the unmask: true coins the engine lifts above each cell’s mask at rest, rendered in one layer above every cell. Default: attach order (column-major), which lets the next column’s coin cover a lower coin’s overflow. Asked again on every place and every landing, so the answer may depend on the coin shown:

// Rows in front of columns, big coins on top.
.cellZIndex(({ cell, symbolId, cols }) =>
  (symbolId === 'grand' ? 1000 : 0) + cell.cell * cols + cell.reel)

Parameters#

Returns#

this

emptyId()#

emptyId(id: string): this;

Defined in: board/HoldAndWinBuilder.ts:99

Symbol id a cell shows when it holds no coin. Default 'empty'.

Parameters#

Returns#

this

grid()#

grid(cols: number, rows: number): this;

Defined in: board/HoldAndWinBuilder.ts:53

Parameters#

Returns#

this

inactive()#

inactive(cells: HwCell[], id?: string): this;

Defined in: board/HoldAndWinBuilder.ts:111

Cells that are built but dormant: they never spin, never take a coin and do not count toward the full board until HoldAndWinBoard.activate wakes them. id is the symbol shown on a dormant cell (default: the empty id) - register a distinct one to draw them as sealed. A board that grows from 5x3 to 5x5 mid-feature is a 5x5 board with two inactive rows.

Parameters#

Returns#

this

initialSpeed()#

initialSpeed(name: string): this;

Defined in: board/HoldAndWinBuilder.ts:214

Profile active when the board is built. Default 'normal'.

Parameters#

Returns#

this

lockAnimation()#

lockAnimation(mode: HwLockAnimationRule<TData>): this;

Defined in: board/HoldAndWinBuilder.ts:149

What a coin’s symbol plays the moment it locks. Default 'win' - the symbol’s playWin(). Pick 'landing' for a land beat only and call HoldAndWinBoard.playWin when the game wants the celebration, or 'none' to drive presentation entirely from the events.

A symbol that starts its own landing beat on land (autoPlayLanding on a Spine symbol, or a sprite reporting one through trackLanding) is never stomped: 'win' waits for that landing to finish before the celebration, and 'landing' does not replay it.

Pass a function to decide per coin: (coin) => coin.id === 'collector' ? 'win' : 'landing'.

Parameters#

Returns#

this

respins()#

respins(count: number): this;

Defined in: board/HoldAndWinBuilder.ts:130

Respins granted on enter and restored on every hit. Default 3.

Parameters#

Returns#

this

rng()#

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

Defined in: board/HoldAndWinBuilder.ts:298

Injected RNG for the spin strips (deterministic demos / tests).

Parameters#

Returns#

this

skipMode()#

skipMode(mode: SkipMode): this;

Defined in: board/HoldAndWinBuilder.ts:231

What board.skip() does when the call does not say: 'slam' places the in-flight cells (the default), 'quicken' lets each spin its symbol in and bounce with its stagger dropped. board.skip({ mode }) overrides it per press. See SkipMode.

Parameters#

Returns#

this

speedProfile()#

speedProfile(profile: SpeedProfile): this;

Defined in: board/HoldAndWinBuilder.ts:193

The 'normal' spin feel for every cell. Default: NORMAL with a 320ms floor. Shorthand for speeds({ normal: profile }).

Parameters#

Returns#

this

speeds()#

speeds(profiles: Record<string, SpeedProfile>): this;

Defined in: board/HoldAndWinBuilder.ts:208

Named speed profiles, registered into EVERY cell’s SpeedManager - the board’s speed.addProfile(). board.setSpeed(name) then switches all cells at once, exactly like reelSet.setSpeed() on one reel set. Merges with what is already registered ('normal' by default).

.speeds({ normal: NORMAL, turbo: TURBO, superTurbo: SUPER_TURBO })

Parameters#

Returns#

this

stagger()#

stagger(fn: (reel: number, cell: number, speed: string) => number): this;

Defined in: board/HoldAndWinBuilder.ts:236

Parameters#

Returns#

this

symbolData()#

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

Defined in: board/HoldAndWinBuilder.ts:124

Per-symbol engine overrides, exactly like ReelSetBuilder.symbolData. The headline use is { unmask: true } for coins whose art or lock/reveal animation is drawn past the cell. The lift applies at rest only - the engine re-masks a cell the moment it moves - so weighted strip ids are fine too: they scroll clipped and sit unclipped once landed.

Parameters#

Returns#

this

symbols()#

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

Defined in: board/HoldAndWinBuilder.ts:87

Register coin symbol classes, exactly like ReelSetBuilder.symbols. Applied to every cell. An EmptySymbol is auto-registered under emptyId unless the configurator registers one itself.

Parameters#

Returns#

this

symbolZIndex()#

symbolZIndex(resolver: SymbolZIndexResolver): this;

Defined in: board/HoldAndWinBuilder.ts:160

Per-symbol z-index resolver for every cell’s reel set, exactly like ReelSetBuilder.symbolZIndex. Orders symbols inside one cell (a cell holds one symbol plus its buffers, so most boards want cellZIndex instead).

Parameters#

Returns#

this

ticker()#

ticker(ticker: Ticker): this;

Defined in: board/HoldAndWinBuilder.ts:292

Parameters#

Returns#

this

weights()#

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

Defined in: board/HoldAndWinBuilder.ts:93

Strip weights during the spin (how often coins flash past empties).

Parameters#

Returns#

this