AbstractGraphics
graphics/abstract-graphics.ts:73 Extends AbstractWorldObjectComponent
Base class for WorldObject-attached components whose visual is a
Pixi display object. AbstractGraphics owns the boilerplate that every
such component needs:
- resolving the world's Scene so the display object has somewhere to live,
- parenting and unparenting the display object across the component's lifecycle,
- syncing the host WorldObject's fully-resolved world transform (its own position/rotation/scale composed with every ancestor's) into the display object once per frame, so the visual reflects every behavior change made during the tick and a parented object renders relative to its parent,
- exposing the underlying Pixi instance via AbstractGraphics.raw for advanced use cases the typed surface doesn't cover,
- applying and exposing the two visual properties every display object shares — AbstractGraphics.alpha and AbstractGraphics.visible.
Subclasses provide the concrete display object — typically a Pixi
Graphics for shape-drawing components, or one of the textured display
objects via AbstractTexturedGraphics, which layers anchor and
tint on top of this base.
Transform-sync timing
The host transform is copied into the display object during
AbstractGraphics.onPostUpdate rather than onUpdate. This way the
visual reflects every position/rotation/scale change made earlier in the
tick regardless of which component made it or what phase it ran in — a
controller's onUpdate move and a physics body's onPostUpdate snap both
end up on screen the same frame.
An initial sync also runs in AbstractGraphics.onAdded, immediately
after the display is parented to the Scene. Without this, an object
spawned mid-tick (after the world's onPostUpdate pass) — or spawned in
setup code between bootstrap and the first tick — would render at Pixi's
default (0, 0) for one frame before the next tick's sync caught up,
producing a single-frame flicker at the origin.
Lifecycle ownership
The base parents the display object to the Scene in onAdded and
removes it in onDestroy. Subclasses that allocate Pixi-side resources
(textures, geometries) should release them by overriding onDestroy,
calling super.onDestroy() first.
Example
import { Graphics as PixiGraphics } from 'pixi.js';
export class RingGraphics extends AbstractGraphics<PixiGraphics> {
constructor(host: WorldObject, radius: number, color = 0xffffff) {
const display = new PixiGraphics();
display.circle(0, 0, radius).stroke({ width: 2, color });
super(host, display);
}
}Constructors
constructor(host: WorldObject, display: T, options: GraphicsOptions): AbstractGraphics<T> Parameters
-
hostWorldObject -
displayT -
optionsGraphicsOptions
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.
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.
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