Text
graphics/text.ts:67 Extends AbstractGraphics<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
-
hostWorldObject -
textstring -
optionsTextOptions
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
anchor: Point The anchor point as a fresh Point of per-axis fractions
(0–1). See TextOptions.anchor for the meaning. Returned by
value; mutating the result does not affect the text — use
Text.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.
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.
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.
height: number Height of the rendered text in pixels, as the renderer measures it given the current string, font family, and size.
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.
visible: boolean Whether the text is drawn. A hidden text still ticks and stays transform-synced; it is just skipped by the renderer.
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.
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
-
_updateWorldUpdate -
_depsRecord
Returns
void setAnchor(x: number, y: number): void Sets the anchor point — the spot on the rendered text that sits on the host's position — as a fraction of the bounding box.
Parameters
-
xnumber -
ynumber
Returns
void setText(value: string): void Replaces the rendered string.
Parameters
-
valuestring
Returns
void