Class

AnimatedSprite

Extends AbstractGraphics<PixiSprite>

Renders a sequence of Texture frames attached to a WorldObject, advancing through them on a timer to produce a flip-book animation — the standard way to put a walk cycle, an idle loop, or a one-shot effect on screen.

Like Sprite, it wraps a renderer Sprite and builds on AbstractGraphics, so it inherits scene-parenting and the once-per-frame transform sync (position, rotation, scale track the host). What it adds is a playhead over a fixed Texture[]: each tick it accumulates elapsed time and swaps the displayed frame whenever a frame's duration has passed.

Frames and timing

The frames are supplied once at construction — typically from Texture.grid, which slices a strip or sheet into ordered cells — and are not mutated afterward. Playback speed is set in frames per second (AnimatedSpriteOptions.fps); the per-frame duration is 1000 / fps milliseconds. Time is accumulated rather than snapped to ticks, so a fast animation on a slow frame still advances by the right number of frames (it can skip frames if a tick is long).

Looping and completion

By default the playhead wraps from the last frame back to the first forever. With AnimatedSpriteOptions.loop false, it instead holds on the final frame, stops, and fires AnimatedSpriteOptions.onComplete once — the model for one-shot effects (an explosion, a pickup sparkle) that should play through and freeze.

Sizing

Identical to Sprite: the intrinsic size is the current frame's pixel size, and there is no width/height setter — scale the host (host.scale.set(2, 2)) to draw larger or smaller. Frames are assumed to share a size (the Texture.grid case); mixing sizes is allowed but the anchor is a per-frame fraction, so off-size frames anchor by their own size.

Example

// A 4-frame idle loop sliced from a horizontal strip, at 8 fps.
const frames = Texture.grid(game.assets.getAs('coin', ImageAsset), {
  frameWidth: 16,
  frameHeight: 16,
  columns: 4,
  rows: 1,
});

coin.addComponentFromFactory(
  'sprite',
  (host) => new AnimatedSprite(host, frames, { fps: 8 }),
);

// A one-shot effect that plays once and removes its object when done.
new AnimatedSprite(host, explosionFrames, {
  fps: 24,
  loop: false,
  onComplete: () => host.destroy(),
});

Constructors

constructor(host: WorldObject, frames: readonly Texture[], options: AnimatedSpriteOptions): AnimatedSprite

Parameters

host WorldObject
frames readonly Texture[]
options AnimatedSpriteOptions

Throws

An EngineError with code ErrorCode.ANIMATED_SPRITE_EMPTY_FRAMES when frames is empty — an animation with no frames has nothing to draw and is always a programming error.

Properties

enabled: boolean

Per-component gate on the three update hooks (onPreUpdate, onUpdate, onPostUpdate). When explicitly false, the engine skips all three for this component during the host's tick — useful for temporarily pausing behaviour (e.g. a freeze powerup) without removing the component and losing its internal state.

Does not gate onAdded or onDestroy; those always fire so a host can never end up with a half-attached component.

readonly #

host: WorldObject

The host this component is attached to. Stored read-only; subclasses access it as this.host directly, or through the tier-appropriate aliases (this.world, this.game) on the per-tier abstract bases.

Accessors

alpha: number

Opacity from 0 (transparent) to 1 (opaque).

readonly #

anchor: Point

The anchor point as a fresh Point of per-axis fractions (0–1). Returned by value; mutating the result does not affect the sprite — use AnimatedSprite.setAnchor.

readonly #

currentFrame: number

The index of the frame currently displayed (0-based).

fps: number

Playback rate in frames per second. Setting it changes the per-frame duration immediately; the current frame's already-banked time is kept, so a rate change takes effect from the next frame boundary.

readonly #

frameCount: number

The number of frames in the animation.

readonly #

game: Game

The Game the host's world belongs to. Always non-null — the world's game field is a mandatory construction argument, not an option.

readonly #

isPlaying: boolean

Whether the playhead is currently advancing. false after AnimatedSprite.pause, AnimatedSprite.stop, or a non-looping animation reaching its final frame.

loop: boolean

Whether playback wraps from the last frame back to the first. Settable at runtime — flip a one-shot to looping or vice versa mid-playback.

readonly #

raw: T

Direct access to the underlying Pixi display object.

Use with care. raw is an intentional escape hatch for cases the arcade2d API doesn't cover — custom shaders, filter chains, advanced blend modes, mask assignment, world-space bounds queries, anything we haven't decided how to model yet. Code that touches raw is coupled to Pixi's public API and may break when:

arcade2d upgrades Pixi (including minor versions).
Pixi itself ships a breaking change.
arcade2d swaps Pixi for a different renderer.

None of those will be treated as breaking changes to arcade2d's own surface. Prefer the typed methods on this component; reach for raw only when no equivalent exists, and isolate the access behind your own helper so the coupling is in one place.

readonly #

texture: Texture

The Texture currently displayed.

tint: number

Multiplicative tint as a 24-bit RGB integer; 0xffffff is untinted.

visible: boolean

Whether the sprite is drawn. A hidden sprite still advances and stays transform-synced; it is just skipped by the renderer.

readonly #

world: World

The World the host WorldObject lives in. Shorthand for this.host.world.

Methods

gotoFrame(index: number): this

Jumps the playhead to a specific frame, leaving the play/pause state unchanged. The banked time is cleared so the new frame gets its full duration.

Parameters

index number

Returns

this

this, for chaining.

onAdded(): void

Lifecycle hook that is called when the component is added to the host object. Should not be called directly.

Returns

void

onDestroy(): void

Lifecycle hook that is called when the host object is destroyed. Should not be called directly.

Returns

void

onPostUpdate(): void

Returns

void

onUpdate(update: WorldUpdate): void

Lifecycle hook for the main update phase. Called once per world tick, after every component's onPreUpdate and before any onPostUpdate.

Parameters

update WorldUpdate

Returns

void

pause(): this

Halts the playhead on the current frame without resetting it.

Returns

this

this, for chaining.

play(): this

Resumes (or begins) advancing the playhead from the current frame. A no-op if already playing. To replay a finished one-shot from the start, call AnimatedSprite.stop first (or AnimatedSprite.gotoFrame).

Returns

this

this, for chaining.

setAnchor(x: number, y: number): void

Sets the anchor point — the spot on each frame that sits on the host's position — as a fraction of the frame's size.

Parameters

x number
y number

Returns

void

stop(): this

Halts the playhead and resets it to the first frame.

Returns

this

this, for chaining.