BoardGrid

pixi-reels

pixi-reels / index / BoardGrid

Class: BoardGrid

Defined in: board/BoardGrid.ts:208

A grid of cells that each spin independently - the generic “board of reels” primitive. Every cell is its own 1×1 ReelSet, so it inherits the engine’s phases, speed modes and pooling rather than a parallel lighter reel.

Deliberately mechanism-only: it knows nothing about coins, locks, respins, value or any game rule. It lays the grid out, hands back per-cell geometry and live symbol instances, places symbols instantly, and spins a caller-chosen set of cells to caller-chosen results. Build your own feature on top by owning the rules in your own code; HoldAndWinBoard is one such opinionated layer, built entirely on this public surface.

const grid = new BoardGrid({
  cols: 3, rows: 3, cellSize: { width: 100, height: 84 }, columnGap: 6, rowGap: 0,
  symbols: (r) => r.register('prize', PrizeSymbol, {}),
  weights: { prize: 1, empty: 4 },
  ticker: app.ticker,
});
app.stage.addChild(grid.container);

await grid.spinCells(
  grid.cells().map((cell) => ({ cell, id: pick() })),  // you decide each result
  (cell, id) => console.log('landed', cell, id),       // react as each settles
);

Implements#

• Disposable

Constructors#

Constructor#

new BoardGrid(opts: BoardGridOptions): BoardGrid;

Defined in: board/BoardGrid.ts:267

Parameters#

Returns#

BoardGrid

Properties#

Accessors#

cellSize#

Get Signature#

get cellSize(): number;

Defined in: board/BoardGrid.ts:795

Cell edge length. Only meaningful on a square board; a rectangular board reports its width here.

Deprecated

Read cellWidth / cellHeight.

Returns

number

dimmedCells#

Get Signature#

get dimmedCells(): BoardCell[];

Defined in: board/BoardGrid.ts:765

Cells a dim currently covers; empty when nothing is dimmed. A released dim reports empty from the moment it is released, while its fade out is still on screen.

Returns

BoardCell[]

dimmedSymbolCells#

Get Signature#

get dimmedSymbolCells(): BoardCell[];

Defined in: board/BoardGrid.ts:702

Cells whose symbol dimSymbols currently tints.

Returns

BoardCell[]

gap#

Get Signature#

get gap(): number;

Defined in: board/BoardGrid.ts:804

Gap between cells. Only meaningful when both gaps agree; otherwise this is the column gap.

Deprecated

Read columnGap / rowGap.

Returns

number

isDestroyed#

Get Signature#

get isDestroyed(): boolean;

Defined in: board/BoardGrid.ts:905

Returns

boolean

Implementation of#

Disposable.isDestroyed

liftedCells#

Get Signature#

get liftedCells(): BoardCell[];

Defined in: board/BoardGrid.ts:450

Currently lifted cells, in lift order. Debug / assertion surface.

Returns

BoardCell[]

liftedLayer#

Get Signature#

get liftedLayer(): RenderLayer;

Defined in: board/BoardGrid.ts:383

The layer every cell’s lifted (unmask: true, at rest) art renders in, above all cells. Escape hatch for an effect that must sit between the cells and their lifted art, or above both; the cellZIndex option is the supported way to order the cells themselves.

Returns

RenderLayer

Methods#

cellBounds()#

cellBounds(cell: BoardCell): {
  height: number;
  width: number;
  x: number;
  y: number;
};

Defined in: board/BoardGrid.ts:814

Board-local bounds of a cell. container.toGlobal for stage space.

Parameters#

Returns#

{
  height: number;
  width: number;
  x: number;
  y: number;
}

cellCenter()#

cellCenter(cell: BoardCell): {
  x: number;
  y: number;
};

Defined in: board/BoardGrid.ts:820

Board-local center of a cell - flight / trail start and end points.

Parameters#

Returns#

{
  x: number;
  y: number;
}

cells()#

cells(): BoardCell[];

Defined in: board/BoardGrid.ts:809

Every cell coordinate, reel-major: (0,0), (0,1), … then (1,0).

Returns#

BoardCell[]

clearDim()#

clearDim(): void;

Defined in: board/BoardGrid.ts:751

Drop the dim at once, whatever holds it and whatever it is mid-fade. A reset must not leave an overlay fading over a board that has already gone. Called by reset() and destroy() on a HoldAndWinBoard; a release handed out before this stays a safe no-op.

Returns#

void

clearSymbolDim()#

clearSymbolDim(): void;

Defined in: board/BoardGrid.ts:714

Drop the symbol dim at once, whatever it is mid-fade, and clear every tint it wrote. Called by reset() and destroy() on a HoldAndWinBoard.

Returns#

void

destroy()#

destroy(): void;

Defined in: board/BoardGrid.ts:909

Returns#

void

Implementation of#

Disposable.destroy

dim()#

dim(opts?: {
  amount?: number;
  except?: BoardCell[];
  fade?: number;
}): () => void;

Defined in: board/BoardGrid.ts:506

Push every cell except these into the background until the returned function is called - the board-level counterpart to a ReelSet’s spotlight dim, and the natural partner of lift: one cell forward, the rest back, for the length of one beat.

One black rectangle per dimmed cell, drawn above the cells’ lifted art and below anything lifted - so a lifted cell stays out in front of the dim whether or not it is excepted, while its cell background goes down with the rest unless you name it in except.

A dim covers CELLS, not symbol ids. To keep every coin of one kind bright, resolve the ids to cells first and pass those.

It fades rather than pops: fade milliseconds in, the same back out, off the board’s own ticker. Pass fade: 0 for an instant cut. A fade interrupted part-way (release during the fade in, or a fresh dim() during the fade out) starts from where it is and takes the proportional share of fade, so nothing jumps.

Only one dim at a time is meaningful, so a second call throws rather than silently replacing the first. Release is idempotent, and it ends the dim immediately as far as dimmedCells is concerned - the fade out is presentation the next dim() is free to interrupt.

Parameters#

Returns#

() => void

Example#

const undim = board.dim({ except: [cell], amount: 0.6 });
const drop = board.lift(cell);
await board.symbolAt(cell).playWin();
drop();
undim();

dimSymbols()#

dimSymbols(opts?: {
  amount?: number;
  except?: BoardCell[];
  fade?: number;
}): () => void;

Defined in: board/BoardGrid.ts:629

Push every cell’s SYMBOL except these into the background until the returned function is called. Same shape as dim, different channel: this darkens the art itself and leaves the cell alone, so the board’s chrome, backgrounds and gaps stay exactly as bright as they were and only the symbols sink.

It works by multiplying each symbol view’s tint towards black, which carries down the whole view - a Spine skeleton, its nested containers, anything the symbol class draws - without touching what the symbol class tints internally. amount is the strength: 0 leaves the art alone, 1 takes it to black, and 0.5 is the classic tint: 0x808080.

A dimmed cell that SWAPS its symbol keeps its dim: the new occupant is tinted as it arrives and the one that left is cleaned before the pool can hand it on. That is the difference from doing this by hand - deactivate() resets alpha, scale, rotation and filters but NOT tint, so a symbol released while dark stays dark in whatever cell reuses it next.

This owns symbol.view.tint for its duration; a game tinting the same property itself will be overwritten. Tint your own art on a child of the view and the two multiply cleanly.

Fades like dim, on its own slot, so the two can run together: one to sink the cells and one to sink the art.

Parameters#

Returns#

() => void

Example#

const undim = board.dimSymbols({ except: [collector], amount: 0.65 });
await sweep();
undim();

lift()#

lift(cell: BoardCell): () => void;

Defined in: board/BoardGrid.ts:421

Draw one cell’s lifted art in front of every other cell’s until the returned function is called - the transient exception to the board’s at-rest order (cellZIndex). For a symbol whose one-shot must not be overlapped by a neighbour’s art: a coin upgrading in place, a collect sweeping the board, a symbol firing at another cell.

Promotion is a SEPARATE channel from zIndex, so a lift survives refreshCellZIndex - which keeps writing the lifted cell’s zIndex throughout, ordering it for the moment it comes back - and releasing restores the cell’s place exactly, recomputing nothing.

Lifts are reference-counted per cell and the returned release is idempotent, so overlapping lifts of one cell cannot strand each other. Several lifted cells keep their relative at-rest order.

Scope: this promotes the cell’s LIFTED art - the views the engine hoists out of the cell for a symbol registered unmask: true, which is what the board renders above all cells in the first place. A cell showing a masked symbol has nothing in that layer, so lifting it is a no-op; masked art is clipped to its own cell and cannot overlap a neighbour anyway.

Lifting is presentation only: no ledger, no phase, no event. A lift held across a respin is legal - the caller owns its own choreography - and is released only by its own release, destroy, or (on a HoldAndWinBoard) reset().

Parameters#

Returns#

() => void

Example#

const release = board.lift(cell);
await board.symbolAt(cell).playWin();
release();

place()#

place(cell: BoardCell, id: string): void;

Defined in: board/BoardGrid.ts:841

Place a symbol instantly (no spin), with blank off-window buffers.

Parameters#

Returns#

void

reelAt()#

reelAt(cell: BoardCell): ReelSet;

Defined in: board/BoardGrid.ts:831

The cell’s underlying 1×1 ReelSet, for driving one cell directly.

Parameters#

Returns#

ReelSet

refreshCellZIndex()#

refreshCellZIndex(): void;

Defined in: board/BoardGrid.ts:775

Re-ask the cellZIndex resolver for every cell and write the answers onto the cells’ lifted containers. Called on every place and every cell landing; a no-op without a resolver. Fifteen property writes on a 5x3 board, so the contract is unconditional rather than incremental.

Returns#

void

releaseAllLifts()#

releaseAllLifts(): void;

Defined in: board/BoardGrid.ts:463

Drop every outstanding lift at once, whatever its reference count. Called by reset() and destroy() on a HoldAndWinBoard, so a feature that ends mid-animation cannot leave a cell stuck in front. Releases handed out before this stay safe to call - they become no-ops.

Returns#

void

setProfile()#

setProfile(cell: BoardCell, name: string): void;

Defined in: board/BoardGrid.ts:836

Select a registered speed profile by name for one cell.

Parameters#

Returns#

void

skipSpinning()#

skipSpinning(options?: SkipOptions): number;

Defined in: board/BoardGrid.ts:890

Press skip on every in-flight cell. 'slam' lands each on its result now; 'quicken' drops each cell’s spin floor (the stagger lives there, so the wave lands together) and lets it spin its symbol in and bounce, on options.speed if named. Returns the count.

Parameters#

Returns#

number

spinCells()#

spinCells(targets: BoardSpinTarget[], onLanded?: (cell: BoardCell, id: string) => void | Promise<void>): Promise<void>;

Defined in: board/BoardGrid.ts:863

Spin each target cell and stop it showing its id; onLanded fires per cell as it settles, in stagger order. The caller selects which cells spin and to what - this layer applies no lock/free policy of its own. Set profiles via setProfile first.

onLanded may be async: if it returns a promise, that cell’s task awaits it, so the returned promise resolves only once every cell has landed and its after-land work has finished. Cells still run concurrently, so an early cell’s reveal overlaps with later cells still spinning.

Parameters#

Returns#

Promise<void>

symbolAt()#

symbolAt(cell: BoardCell): ReelSymbol;

Defined in: board/BoardGrid.ts:826

Live symbol instance currently shown in a cell.

Parameters#

Returns#

ReelSymbol