Abstract Class: ReelSymbol

Defined in: symbols/ReelSymbol.ts:36

One visible cell on a reel. the thing that actually draws.

ReelSymbol is the abstract base class. Subclass it to pick a rendering technology (SpriteSymbol, AnimatedSpriteSymbol, SpineSymbol, or a custom class of your own). The reel set pools instances aggressively: one instance is reused many times as it scrolls off one identity and on to another, so implementations must never assume “I was just created”.

Required lifecycle hooks:

onActivate(symbolId). the pool just handed me a new identity. Swap texture, restart animations, bring myself out of any “ended” pose.
onDeactivate(). I am about to be pooled. Pause animations, clear listeners, leave myself in a clean state for the next activation.
playWin(). the spotlight is celebrating me. Return a promise that resolves when the one-shot animation is done.
stopAnimation(). spotlight is over, return to idle.
resize(w, h). the reel’s cell size changed (on every symbol swap). Store the dimensions and reposition internal children. Forgetting this is the single most common “why do my symbols scatter” bug.

create → activate(symbolId) → [playWin / stopAnimation]
                            → deactivate
                            → activate(newId) → ...

There’s no hidden GC. Hold resources? Override onDestroy().

Extended by#

Implements#

Disposable

Constructors#

Constructor#

new ReelSymbol(): ReelSymbol;

Defined in: symbols/ReelSymbol.ts:46

Returns#

ReelSymbol

Properties#

Property	Modifier	Type	Description	Defined in
`view`	`readonly`	`Container`	The PixiJS container that holds this symbol’s visual.	symbols/ReelSymbol.ts:38

Accessors#

cellInset#

Get Signature#

get cellInset(): ReelCellInset | null;

Defined in: symbols/ReelSymbol.ts:501

The part of its cell this symbol’s art actually covers, or null (the default) for “all of it”.

Slot art is usually smaller than its cell - a trimmed atlas frame is a shape floating in a much bigger transparent box - and the reel needs to know that to project the rectangle the art is really in. Overriding this is what stops a small symbol being inflated to the cell’s edges and given the cell’s keystone instead of its own, milder one.

Read once per projection, so it may change with the symbol’s identity.

Returns

ReelCellInset | null

gsap#

Get Signature#

get protected gsap(): typeof gsap;

Defined in: symbols/ReelSymbol.ts:59

The gsap instance this symbol should animate on. Use it instead of importing gsap in a subclass: under a symlinked-workspace module resolution your import and the engine’s can be different instances, and only this one is on the timeline the reel set actually drives.

Bound to the owning set by SymbolFactory; falls back to the instance resolved at lib-load time for a symbol built outside a set.

Returns

typeof gsap

isDestroyed#

Get Signature#

get isDestroyed(): boolean;

Defined in: symbols/ReelSymbol.ts:125

Returns

boolean

Implementation of#

Disposable.isDestroyed

landing#

Get Signature#

get landing(): Promise<void> | null;

Defined in: symbols/ReelSymbol.ts:106

The landing beat this symbol started on its latest onReelLanded(), or null if it started none. Stays set (resolved) until the reel moves again or the symbol is pooled, so a presenter that lands cells one at a time - HoldAndWinBoard on a lock, a win spotlight - can sequence after the landing (await symbol.landing) instead of stomping it, and can tell a symbol that already landed from one that still needs playLanding().

Subclasses report a landing through trackLanding.

Returns

Promise<void> | null

mainAxis#

Get Signature#

get protected mainAxis(): "x" | "y";

Defined in: symbols/ReelSymbol.ts:80

The screen axis the owning set’s strips travel along: 'y' for a vertical set, 'x' for a horizontal one.

Symbols are otherwise orientation-agnostic - resize(width, height) is screen-space and always will be. This exists for the few effects that genuinely follow travel, motion blur being the one in the box.

Returns

"x" | "y"

symbolId#

Get Signature#

get symbolId(): string;

Defined in: symbols/ReelSymbol.ts:89

Returns

string

Methods#

activate()#

activate(symbolId: string): void;

Defined in: symbols/ReelSymbol.ts:134

Activate the symbol with a new identity. Called when the symbol enters the visible reel or is recycled from the pool. Resets container transform / filter state for parity with deactivate().

Parameters#

Parameter	Type
`symbolId`	`string`

Returns#

void

applyCellQuad()#

applyCellQuad(quad: ReelCellQuad | null): void;

Defined in: symbols/ReelSymbol.ts:505

Parameters#

Parameter	Type
`quad`	`ReelCellQuad` \| `null`

Returns#

void

bindGsap()#

bindGsap(instance: typeof gsap): void;

Defined in: symbols/ReelSymbol.ts:68

@internal. Called by SymbolFactory when the symbol is created, so a pooled symbol animates on its own set’s gsap rather than whichever set happened to build last.

Parameters#

Parameter	Type
`instance`	typeof `gsap`

Returns#

void

bindMainAxis()#

bindMainAxis(prop: "x" | "y"): void;

Defined in: symbols/ReelSymbol.ts:85

@internal. Bound by SymbolFactory from the set’s orientation.

Parameters#

Parameter	Type
`prop`	`"x"` \| `"y"`

Returns#

void

deactivate()#

deactivate(): void;

Defined in: symbols/ReelSymbol.ts:154

Deactivate the symbol before returning it to the pool. Stops animations, hides the view, and resets container transform / filter state so subclass decorations don’t leak across recycles.

Returns#

void

destroy()#

destroy(): void;

Defined in: symbols/ReelSymbol.ts:176

Returns#

void

Implementation of#

Disposable.destroy

onActivate()#

abstract protected onActivate(symbolId: string): void;

Defined in: symbols/ReelSymbol.ts:193

Subclass hook: set up visuals for the given symbolId.

Parameters#

Parameter	Type
`symbolId`	`string`

Returns#

void

onDeactivate()#

abstract protected onDeactivate(): void;

Defined in: symbols/ReelSymbol.ts:196

Subclass hook: clean up visuals.

Returns#

void

onDestroy()#

protected onDestroy(): void;

Defined in: symbols/ReelSymbol.ts:199

Subclass hook: additional cleanup on destroy.

Returns#

void

onReelAnticipationStart()#

onReelAnticipationStart(): void;

Defined in: symbols/ReelSymbol.ts:575

Lifecycle hook: the owning reel entered its anticipation (tease) phase. it is still spinning, but slowed enough that the strip is readable. Spin presentations that obscure symbols (blur textures, smear animations) should relax so the player can follow the tease. Also fired on symbols installed while the reel is anticipating. Implementations MUST be idempotent. Default: no-op.

Returns#

void

onReelLanded()#

onReelLanded(ctx?: ReelLandingContext): void;

Defined in: symbols/ReelSymbol.ts:588

Lifecycle hook: the owning reel has landed on its final symbols. Default: no-op. Override (e.g. SpineReelSymbol.autoPlayLanding) to fire a landing animation concurrently with the bounce.

ctx says which reel and cell this symbol landed in, so an override can play a different beat - or none - on a particular reel. The engine always supplies it; it is optional only so an override written as onReelLanded() keeps compiling. Fired before the reel’s landing event and the set’s spin:reelLanding, by contract.

Parameters#

Parameter	Type
`ctx?`	`ReelLandingContext`

Returns#

void

onReelSpinEnd()#

onReelSpinEnd(): void;

Defined in: symbols/ReelSymbol.ts:565

Lifecycle hook: the owning reel is about to stop (just before bounce). Default: no-op.

Returns#

void

onReelSpinStart()#

onReelSpinStart(joinedMidSpin?: boolean): void;

Defined in: symbols/ReelSymbol.ts:559

Lifecycle hook: the owning reel is spinning. Default: no-op. Override (e.g. SpineReelSymbol.autoPlayBlur, StaticSpinSymbol) to swap to a spin presentation automatically.

Fired on every strip symbol (visible AND buffer cells) when the reel enters the spin phase, and again with joinedMidSpin: true on each symbol freshly installed while the reel is already spinning (pool recycling wipes symbol state, so a wrapped-in symbol can’t know the reel is moving without this). Implementations MUST be idempotent. the same instance can be notified more than once per spin.

Parameters#

Parameter	Type	Description
`joinedMidSpin?`	`boolean`	true when this symbol was installed into a reel already at speed (skip start-of-spin transitions like blur ramps).

Returns#

void

playDestroy()#

playDestroy(opts?: {
  delay?: number;
  signal?: AbortSignal;
}): Promise<void>;

Defined in: symbols/ReelSymbol.ts:251

Play the cascade-destruction animation for this symbol. Called by consumers (typically via reelSet.destroySymbols(...)) to disintegrate a winning cell before the next cascade refill drops fresh symbols in.

Override in subclasses for art-appropriate destruction, e.g. a Spine symbol can play its disintegration track here, or a sprite symbol can swap to a shatter atlas. The promise must resolve when the symbol is no longer visible.

Default: a snappy “poof” centered on the symbol’s bounds regardless of the view’s anchor. Tiny anticipation pop (~60 ms) then a fast implode to scale: 0 + alpha: 0 (~140 ms), ~200 ms total, no rotation. Reads cleanly under win-cluster pacing without competing with the win presenter. The view is left at alpha: 0 (destroyed); position / pivot are restored so pool reuse via _replaceSymbol’s same-id fast path doesn’t inherit a stale pivot offset.

opts.delay. seconds to wait before the animation starts. Use to stagger a cluster of winners (e.g. i * 0.015). opts.signal. abort signal. If aborted (now or mid-animation), the tween is killed and the view is snapped to its destroyed pose (alpha: 0, transform restored). The promise resolves normally. abort means “skip to the end,” not “fail”. Subclasses that override this method MUST honor the signal or document why they can’t (e.g. a Spine disintegration track is uninterruptible).

Parameters#

Parameter	Type
`opts?`	{ `delay?`: `number`; `signal?`: `AbortSignal`; }
`opts.delay?`	`number`
`opts.signal?`	`AbortSignal`

Returns#

Promise<void>

playIn()#

playIn(opts?: {
  delay?: number;
  signal?: AbortSignal;
}): Promise<void>;

Defined in: symbols/ReelSymbol.ts:362

Animate this symbol IN, from nothing to its resting pose.

Owns its own start pose. A symbol that has just been re-activated is fully visible (activate() resets alpha and scale), so an entrance that assumed it started hidden would pop before it animated. This sets the hidden pose first, then plays.

Override for art-appropriate entrances - a Spine symbol plays its own in track here. Honour opts.signal: abort snaps to the RESTING pose (alpha 1, scale 1), because arriving is what the caller asked for.

Default: a ~200 ms fade and scale-up with a small overshoot.

Parameters#

Parameter	Type
`opts?`	{ `delay?`: `number`; `signal?`: `AbortSignal`; }
`opts.delay?`	`number`
`opts.signal?`	`AbortSignal`

Returns#

Promise<void>

playLanding()#

playLanding(): Promise<void>;

Defined in: symbols/ReelSymbol.ts:216

Play the landing beat for this symbol - the settle a symbol does as its reel stops, before (or instead of) any celebration. Resolves when done.

The reel engine never calls this itself: onReelLanded() is the engine-driven hook, fired on every landed symbol. This is the explicit counterpart for a caller that lands cells one at a time - HoldAndWinBoard calls it on each lock when built with lockAnimation('landing').

Default: resolves at once. SpineReelSymbol overrides it with the skeleton’s landing track; a sprite symbol can override it with a tween.

Returns#

Promise<void>

playOut()#

playOut(opts?: {
  delay?: number;
  signal?: AbortSignal;
}): Promise<void>;

Defined in: symbols/ReelSymbol.ts:344

Animate this symbol AWAY, without destroying it.

The counterpart to playIn, and the seam a mystery reveal needs: the cells on screen dissolve, their identities are swapped underneath, and the new ones arrive. playDestroy is the cascade’s version of the same beat and is deliberately separate - it is tuned as a “this cell was a winner and is being consumed” poof, and a reveal is not that.

Leaves the view hidden (alpha: 0) with its transform restored, so the caller may swap the identity and call playIn next.

Override for art-appropriate exits - a Spine symbol plays its own out track here. Honour opts.signal: abort means “snap to the end”, not “fail”, so the promise still resolves.

Default: a ~180 ms shrink-and-fade with no overshoot, centred on the symbol’s bounds rather than the view origin.

Parameters#

Parameter	Type
`opts?`	{ `delay?`: `number`; `signal?`: `AbortSignal`; }
`opts.delay?`	`number`
`opts.signal?`	`AbortSignal`

Returns#

Promise<void>

playWin()#

abstract playWin(): Promise<void>;

Defined in: symbols/ReelSymbol.ts:202

Play the win/highlight animation for this symbol. Resolves when complete.

Returns#

Promise<void>

reset()#

reset(): void;

Defined in: symbols/ReelSymbol.ts:172

Pool reset. aliases deactivate.

Returns#

void

resize()#

abstract resize(width: number, height: number): void;

Defined in: symbols/ReelSymbol.ts:222

Resize the symbol’s visual to fit the given dimensions.

Parameters#

Parameter	Type
`width`	`number`
`height`	`number`

Returns#

void

stopAnimation()#

abstract stopAnimation(): void;

Defined in: symbols/ReelSymbol.ts:219

Immediately stop any running animation and return to idle.

Returns#

void

trackLanding()#

protected trackLanding(run: Promise<void>): Promise<void>;

Defined in: symbols/ReelSymbol.ts:115

Subclass helper: record run as this symbol’s landing beat (see landing) and return it. SpineReelSymbol wraps its landing one-shot in it; a sprite symbol wraps its settle tween.

Parameters#

Parameter	Type
`run`	`Promise`<`void`>

Returns#

Promise<void>