Sprite
graphics/sprite.ts:49 Extends AbstractTexturedGraphics<PixiSprite>
Renders a Texture attached to a WorldObject — the standard way to put an image (or one frame of a spritesheet) on screen.
Sprite wraps a renderer Sprite internally and builds on
AbstractGraphics, so it inherits the scene-parenting and
once-per-frame transform sync every graphics component gets: the sprite
tracks the host's position, rotation, and scale automatically. What it adds
is the textured-quad surface — the Texture to draw, plus anchor,
tint, opacity, and visibility.
Sizing
A sprite's intrinsic size is its texture's pixel size. It is not sized
with a width/height setter — doing so would fight the per-frame transform
sync, which copies the host's WorldObject.scale onto the display
every tick. To draw the image larger or smaller in world units, scale the
host: host.scale.set(2, 2). This is the same model the shape graphics use
(local-space geometry scaled by the host).
Frames and animation
Frame selection lives on the Texture, not here — give the sprite a
sub-region Texture to draw one cell of a sheet. Swapping frames at
runtime (the basis of animation) is just Sprite.setTexture with the
next frame's Texture.
Example
const player = world.createObject();
const texture = new Texture(game.assets.get('player') as ImageAsset);
player.addComponentFromFactory(
'sprite',
(host) => new Sprite(host, texture, { anchor: 0.5, tint: 0xffeecc }),
);Constructors
constructor(host: WorldObject, texture: Texture, options: TexturedGraphicsOptions): Sprite Parameters
-
hostWorldObject -
textureTexture -
optionsTexturedGraphicsOptions
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.
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.
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).
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 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, _deps: Record): void Lifecycle hook for the main update phase. Called once per world
tick, after every component's onPreUpdate and before any
onPostUpdate.
Parameters
-
_updateWorldUpdate -
_depsRecord
Returns
void 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 setTexture(texture: Texture): void Swaps the drawn Texture. The previous texture is left intact — texture lifetime belongs to the owning ImageAsset, not the sprite — so swapping between frames of a spritesheet is cheap and safe. This is the seam an animated sprite drives.
Parameters
-
textureTexture
Returns
void