arcade2d
Class

Sprite

graphics/sprite.ts:49

Extends AbstractGraphics<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: SpriteOptions): Sprite

Parameters

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). See SpriteOptions.alpha.

readonly #
anchor: Point

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

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 #
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 this sprite is currently drawing.

#
tint: number

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

#
visible: boolean

Whether the sprite is drawn. A hidden sprite still ticks 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

#
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

Returns

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

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

Parameters

  • x number
  • y number

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

Returns

void
ESC