Class

Text

Extends AbstractTexturedGraphics<PixiText>

Renders a string attached to a WorldObject — the standard way to put dynamic text on screen.

Text wraps a renderer Text internally and builds on AbstractGraphics, so it inherits the scene-parenting and once-per-frame transform sync every graphics component gets: the text tracks the host's position, rotation, and scale automatically. What it adds is the typographic surface — the string, font family, size, fill, alignment, anchor, and opacity.

World-space, not screen-space

Like every other graphics component, Text lives in the world's scene graph and is therefore affected by the Camera. To draw a screen-anchored HUD label, position the host each frame to follow the camera — host.position = camera.position + offset — rather than expecting Text to opt out of the camera transform. The matching engine surface for menus and DOM-native UI is a React/HTML overlay, not a special text component.

Sizing

Text is sized by its TextOptions.fontSize — a pixel-space typographic size — not by host.scale. Scaling a Text via the host's scale resamples the underlying texture and looks soft; instead, pick a fontSize close to the size you want on screen, and leave the host's scale at (1, 1). The per-frame transform sync inherited from AbstractGraphics still applies, so any host scale you do set will multiply on top of the typographic size.

Font selection

Pass TextOptions.fontFamily as a preloaded FontAsset for any production text — the asset's FontAsset.family is read, keeping the rendered output deterministic across machines. A raw CSS family string is accepted as an escape hatch for system fonts during prototyping.

Example

const hud = world.createObject();
const pixel = game.assets.getAs('pixel', FontAsset);

hud.addComponentFromFactory(
  'score',
  (host) =>
    new Text(host, 'Score: 0', {
      fontFamily: pixel,
      fontSize: 16,
      fill: 0xffffff,
      anchor: 0,
    }),
);

Constructors

constructor(host: WorldObject, text: string, options: TextOptions): Text

Parameters

host WorldObject
text string
options TextOptions

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

align: TextAlign

Horizontal alignment of lines within a multi-line text. See TextOptions.align.

alpha: number

Opacity from 0 (fully transparent) to 1 (fully opaque). Applies to the whole graphic, including any children the display object holds.

readonly #

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.

fill: string | number

Fill colour of the glyphs. Always returns the underlying canvas-text fill value; for the colour models the renderer accepts on assignment, see TextOptions.fill.

readonly #

fontFamily: string

The font family the text is drawn in, as a CSS family string. To swap families pass either a FontAsset or a raw string to Text.setFontFamily.

fontSize: number

Font size in pixels. See TextOptions.fontSize for the sizing model — scaling via fontSize looks crisp, scaling via host.scale does not.

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 #

height: number

Height of the rendered text in pixels, as the renderer measures it given the current string, font family, and size.

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

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.

text: string

The rendered string. Setting this re-rasterises the underlying texture; setting it to the same value the text already holds is a cheap no-op in the renderer.

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.

readonly #

width: number

Width of the rendered text in pixels, as the renderer measures it given the current string, font family, and size. Useful for laying out HUD elements relative to the text's actual extent.

readonly #

world: World

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

Methods

protected #

_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

_update WorldUpdate
_deps Record

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

x number
y number

Returns

void

setFontFamily(value: string | FontAsset): void

Swaps the font family.

Parameters

value string | FontAsset

Returns

void

setText(value: string): void

Replaces the rendered string.

Parameters

value string

Returns

void