SpriteSymbol

pixi-reels

pixi-reels / index / SpriteSymbol

Class: SpriteSymbol

Defined in: symbols/SpriteSymbol.ts:23

Symbol implementation using a simple PixiJS Sprite. Swaps texture on activate. Win animation is a scale pulse via GSAP.

On a curved reel it draws the same texture through a PerspectiveMesh instead, so the cell is a real projected trapezoid rather than a rectangle that has been scaled down. See ReelSymbol.applyCellQuad.

Extends#

• ReelSymbol

Constructors#

Constructor#

new SpriteSymbol(options: SpriteSymbolOptions): SpriteSymbol;

Defined in: symbols/SpriteSymbol.ts:29

Parameters#

Returns#

SpriteSymbol

Overrides#

ReelSymbol.constructor

Properties#

Accessors#

cellInset#

Get Signature#

get cellInset(): ReelCellInset | null;

Defined in: symbols/SpriteSymbol.ts:55

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

Overrides#

ReelSymbol.cellInset

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

Inherited from#

ReelSymbol.gsap

isDestroyed#

Get Signature#

get isDestroyed(): boolean;

Defined in: symbols/ReelSymbol.ts:125

Returns

boolean

Inherited from#

ReelSymbol.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

Inherited from#

ReelSymbol.landing

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"

Inherited from#

ReelSymbol.mainAxis

symbolId#

Get Signature#

get symbolId(): string;

Defined in: symbols/ReelSymbol.ts:89

Returns

string

Inherited from#

ReelSymbol.symbolId

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#

Returns#

void

Inherited from#

ReelSymbol.activate

applyCellQuad()#

applyCellQuad(quad: ReelCellQuad | null): void;

Defined in: symbols/SpriteSymbol.ts:59

Parameters#

Returns#

void

Overrides#

ReelSymbol.applyCellQuad

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#

Returns#

void

Inherited from#

ReelSymbol.bindGsap

bindMainAxis()#

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

Defined in: symbols/ReelSymbol.ts:85

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

Parameters#

Returns#

void

Inherited from#

ReelSymbol.bindMainAxis

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

Inherited from#

ReelSymbol.deactivate

destroy()#

destroy(): void;

Defined in: symbols/ReelSymbol.ts:176

Returns#

void

Inherited from#

ReelSymbol.destroy

onActivate()#

protected onActivate(symbolId: string): void;

Defined in: symbols/SpriteSymbol.ts:39

Subclass hook: set up visuals for the given symbolId.

Parameters#

Returns#

void

Overrides#

ReelSymbol.onActivate

onDeactivate()#

protected onDeactivate(): void;

Defined in: symbols/SpriteSymbol.ts:49

Subclass hook: clean up visuals.

Returns#

void

Overrides#

ReelSymbol.onDeactivate

onDestroy()#

protected onDestroy(): void;

Defined in: symbols/SpriteSymbol.ts:102

Subclass hook: additional cleanup on destroy.

Returns#

void

Overrides#

ReelSymbol.onDestroy

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

Inherited from#

ReelSymbol.onReelAnticipationStart

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#

Returns#

void

Inherited from#

ReelSymbol.onReelLanded

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

Inherited from#

ReelSymbol.onReelSpinEnd

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#

Returns#

void

Inherited from#

ReelSymbol.onReelSpinStart

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#

Returns#

Promise<void>

Inherited from#

ReelSymbol.playDestroy

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#

Returns#

Promise<void>

Inherited from#

ReelSymbol.playIn

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>

Inherited from#

ReelSymbol.playLanding

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#

Returns#

Promise<void>

Inherited from#

ReelSymbol.playOut

playWin()#

playWin(): Promise<void>;

Defined in: symbols/SpriteSymbol.ts:72

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

Returns#

Promise<void>

Overrides#

ReelSymbol.playWin

reset()#

reset(): void;

Defined in: symbols/ReelSymbol.ts:172

Pool reset. aliases deactivate.

Returns#

void

Inherited from#

ReelSymbol.reset

resize()#

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

Defined in: symbols/SpriteSymbol.ts:97

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

Parameters#

Returns#

void

Overrides#

ReelSymbol.resize

stopAnimation()#

stopAnimation(): void;

Defined in: symbols/SpriteSymbol.ts:91

Immediately stop any running animation and return to idle.

Returns#

void

Overrides#

ReelSymbol.stopAnimation

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#

Returns#

Promise<void>

Inherited from#

ReelSymbol.trackLanding