AnimatedSprite
graphics/animated-sprite.ts:78 Extends AbstractTexturedGraphics<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
-
hostWorldObject -
framesreadonly Texture[] -
optionsAnimatedSpriteOptions
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.
An EngineError with code ErrorCode.ANIMATED_SPRITE_INVALID_FPS when AnimatedSpriteOptions.fps is not a positive, finite number.
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.
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 (fully transparent) to 1 (fully opaque). Applies to
the whole graphic, including any children the display object holds.
anchor: Point The anchor point as a fresh Point of per-axis fractions (0–1).
See TexturedGraphicsOptions.anchor for the meaning. Returned by
value; mutating the result does not affect the graphic — use
AbstractTexturedGraphics.setAnchor.
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.
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.
isPlaying: boolean Whether the playhead is currently advancing. false after
AnimatedSprite.pause, AnimatedSprite.stop, or a non-looping
animation reaching its final frame.
layer: undefined | Layer The render layer this graphic is in, or undefined in a layer-less world.
Assigning a different Layer re-parents the display into that layer's
container, moving the graphic between bands at runtime (e.g. dropping a
dying enemy below the living). The same opt-in rules as
GraphicsOptions.layer apply: a layered world rejects undefined
(ErrorCode.LAYER_UNSPECIFIED), a layer-less world rejects a token
(ErrorCode.LAYER_SET_ABSENT), and a foreign token is rejected by
Scene.containerForLayer (ErrorCode.LAYER_NOT_IN_SET).
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.
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.
tint: number Multiplicative tint as a 24-bit RGB integer; 0xffffff is untinted. See
TexturedGraphicsOptions.tint.
visible: boolean Whether the graphic is drawn. A hidden graphic still ticks and stays transform-synced; it is simply skipped by the renderer.
Methods
_destroyOptions(): DestroyOptions The options handed to the underlying Pixi display object's destroy
during AbstractGraphics.onDestroy. The base returns {} —
destroy the node itself but leave shared resources alone, since
textures are owned by the asset layer and shared across instances.
Subclasses that construct an owned, non-shared Pixi resource
override this to release it (e.g. Text returns { style: true }
to free the TextStyle Pixi created for it).
Returns
DestroyOptions 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
-
indexnumber
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
-
updateWorldUpdate
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 the graphic that sits on the host's position — as a fraction of the graphic's size.
Parameters
-
xnumber -
ynumber
Returns
void stop(): this Halts the playhead and resets it to the first frame.
Returns
this this, for chaining.