VisualComponent

Defined in: renderer/src/VisualComponent.ts:90

Shared base for the renderer’s five visual components (Sprite, AnimatedSprite, Graphics, Text, SplitText). Carries the render-layer field, lazy effects host, mask lifecycle, scene-tree parenting, and the generic visible/tint/alpha/interactive vocabulary — every underlying Pixi display object supports all four directly on Container, so this operates on renderObject rather than each subclass re-deriving the same three-liner.

Subclasses provide renderObject (their concrete Pixi display object, created in their own constructor) and call applyVisualOptions once it exists — options can’t be applied during VisualComponent’s own constructor since renderObject isn’t assigned yet at that point.

Extends

• Component

Extended by

• SpriteComponent
• GraphicsComponent
• TextComponent
• SplitTextComponent
• AnimatedSpriteComponent

Constructors

Constructor

new VisualComponent(layer): VisualComponent

Defined in: renderer/src/VisualComponent.ts:118

Parameters

layer

string | undefined

Returns

VisualComponent

Overrides

Component.constructor

Properties

entity

entity: Entity

Defined in: core/dist/index.d.ts:3217

Back-reference to the owning entity. Set by the engine when the component is added to an entity. Do not set manually.

Inherited from

Component.entity

---

fx

readonly fx: EffectsHost

Defined in: renderer/src/VisualComponent.ts:100

Component-scope effects host. .fx.addEffect(...) attaches a filter to this component’s render object; the effect is torn down automatically when the entity or component is destroyed. .fx.findEffect(definition) recovers the handle for the first matching effect.

---

modifiers

readonly modifiers: VisualModifierHost

Defined in: renderer/src/VisualComponent.ts:105

Render-only transform, opacity, and visibility contributions. Modifiers combine with the component’s live base values and are never serialized.

---

renderObject

abstract readonly renderObject: DisplayContainer

Defined in: renderer/src/VisualComponent.ts:92

The underlying Pixi display object.

---

inspectExclude?

static optional inspectExclude?: readonly string[]

Defined in: core/dist/index.d.ts:3420

Own fields and getters the Inspector leaves out of this component’s reflected state. Use it for bulk data that is not worth a diagnostic copy — a parsed tilemap, a large lookup table. Lists merge down the class chain, so a subclass adds to its base class’s exclusions.

class TilemapComponent extends VisualComponent {
  static inspectExclude = ["data"];
}

Inherited from

Component.inspectExclude

---

updatePriority?

static optional updatePriority?: number

Defined in: core/dist/index.d.ts:3407

Class-level default for updatePriority: every instance runs at this priority unless its own updatePriority is written. Undeclared = 0. Subclasses inherit their base class’s value unless they declare their own. Declare it on a component whose behavior depends on running after (or before) a sibling, so the entity that adds it does not have to control the add order.

class BoundsClamp extends Component {
  static updatePriority = 10; // after the follow that moves the camera
}

Inherited from

Component.updatePriority

Accessors

alpha

Get Signature

get alpha(): number

Defined in: renderer/src/VisualComponent.ts:226

Get the requested alpha before transient opacity modifiers.

Returns

number

Set Signature

set alpha(alpha): void

Defined in: renderer/src/VisualComponent.ts:220

Set the container’s alpha (opacity).

Parameters

alpha

number

Returns

void

---

blendMode

Get Signature

get blendMode(): BLEND_MODES

Defined in: renderer/src/VisualComponent.ts:236

Get the container’s blend mode.

Returns

BLEND_MODES

Set Signature

set blendMode(mode): void

Defined in: renderer/src/VisualComponent.ts:231

Set how the container combines with what is drawn beneath it.

Parameters

mode

BLEND_MODES

Returns

void

---

context

Get Signature

get context(): EngineContext

Defined in: core/dist/index.d.ts:3272

Access the EngineContext from the entity’s scene. Throws if the entity is not in a scene.

Returns

EngineContext

Inherited from

Component.context

---

effectiveEnabled

Get Signature

get effectiveEnabled(): boolean

Defined in: core/dist/index.d.ts:3242

Whether the component is actually running: enabled, on an active entity, and past onAdd. This is the state onEnable and onDisable track — read it when a method has to behave one way live and another way dormant.

Returns

boolean

Inherited from

Component.effectiveEnabled

---

enabled

Get Signature

get enabled(): boolean

Defined in: core/dist/index.d.ts:3234

Whether this component runs. Disabled components are skipped by ComponentUpdateSystem.

Writing this fires onEnable / onDisable when the effective state changes — enabled && entity.isActive. A component disabled here stays disabled through a setActive(false) / setActive(true) cycle on its entity.

Returns

boolean

Set Signature

set enabled(value): void

Defined in: core/dist/index.d.ts:3235

Parameters

value

boolean

Returns

void

Inherited from

SpriteComponent.enabled

---

layerName

Get Signature

get layerName(): string

Defined in: renderer/src/VisualComponent.ts:179

The layer this visual draws on. See setLayer.

Returns

string

---

mask

Get Signature

get mask(): MaskHandle | undefined

Defined in: renderer/src/VisualComponent.ts:273

The currently attached mask handle, if any.

Returns

MaskHandle | undefined

---

renderAboveEffects

Get Signature

get renderAboveEffects(): boolean

Defined in: renderer/src/VisualComponent.ts:163

Whether this visual draws after the scene’s layers, outside every layer- and scene-scope effect and mask, while keeping its logical parent (position, alpha, visibility, camera). Screen-scope effects still cover it, and hit testing follows the logical tree — a UI element drawn under an escaped visual still receives the pointer first.

Set while the visual is out of the display tree — in a subclass constructor, or on a component not yet added — it records the flag and applies it on add.

Returns

boolean

Set Signature

set renderAboveEffects(value): void

Defined in: renderer/src/VisualComponent.ts:167

Parameters

value

boolean

Returns

void

---

scene

Get Signature

get scene(): Scene

Defined in: core/dist/index.d.ts:3267

Access the entity’s scene. Throws if the entity is not in a scene. Prefer this over threading through this.entity.scene in component code.

Returns

Scene

Inherited from

Component.scene

---

tint

Get Signature

get tint(): number

Defined in: renderer/src/VisualComponent.ts:215

Get the container’s tint color.

Returns

number

Set Signature

set tint(color): void

Defined in: renderer/src/VisualComponent.ts:210

Set the container’s tint color.

Parameters

color

ColorSource

Returns

void

---

updatePriority

Get Signature

get updatePriority(): number

Defined in: core/dist/index.d.ts:3260

Where this component runs among its siblings. ComponentUpdateSystem calls update / fixedUpdate on an entity’s components in ascending priority; equal priorities run in add order. Undeclared = 0, so a negative value runs before siblings that keep the default and a positive value runs after them. Writable at any time, before or after add(). Defaults to the class’s static updatePriority.

class Player extends Entity {
  setup() {
    this.add(new Mover());
    this.add(new Brain()).updatePriority = -1; // decides before Mover moves
  }
}

Returns

number

Set Signature

set updatePriority(value): void

Defined in: core/dist/index.d.ts:3261

Parameters

value

number

Returns

void

Inherited from

Component.updatePriority

---

visible

Get Signature

get visible(): boolean

Defined in: renderer/src/VisualComponent.ts:250

Get the requested visibility, whatever the entity’s activeness.

Returns

boolean

Set Signature

set visible(value): void

Defined in: renderer/src/VisualComponent.ts:244

Set the container’s visibility. Written while the entity is dormant, it is remembered and applied when the entity is activated.

Parameters

value

boolean

Returns

void

Methods

_applyEnabled()

_applyEnabled(effective): void

Defined in: core/dist/index.d.ts:3355

Internal

Force an effective-enabled transition, firing the hook on a flip. Used by Entity for teardown, where enabled and the entity’s activeness both still read true.

Parameters

effective

boolean

Returns

void

Inherited from

Component._applyEnabled

---

_isTornDown()

_isTornDown(): boolean

Defined in: core/dist/index.d.ts:3336

Internal

Internal: true once this component has been removed or its entity destroyed. Components are terminal — Entity.add uses this to reject re-attaching an instance whose cleanups and onDestroy already ran.

Returns

boolean

Inherited from

Component._isTornDown

---

_markTornDown()

_markTornDown(): void

Defined in: core/dist/index.d.ts:3342

Internal

Internal: mark this component torn down. Called by Entity.remove() and Entity._performDestroy() after onDestroy runs.

Returns

void

Inherited from

Component._markTornDown

---

_refreshEnabled()

_refreshEnabled(): void

Defined in: core/dist/index.d.ts:3348

Internal

Recompute effective enabled-ness from enabled and the entity’s activeness, firing the hook on a flip.

Returns

void

Inherited from

Component._refreshEnabled

---

_runCleanups()

_runCleanups(onError?): void

Defined in: core/dist/index.d.ts:3323

Internal

Run and clear all registered cleanups. Called by Entity.remove() and Entity._performDestroy() before onDestroy.

Parameters

onError?

(error) => void

Returns

void

Inherited from

Component._runCleanups

---

addCleanup()

protected addCleanup(fn): void

Defined in: core/dist/index.d.ts:3317

Register a cleanup function to run when this component is removed or destroyed, before onDestroy. Use it for what listen, listenScene and listenBus do not cover, such as an unsubscribe from a custom emitter.

Parameters

fn

() => void

Returns

void

Inherited from

Component.addCleanup

---

applyEffectiveAlpha()

protected applyEffectiveAlpha(alpha): void

Defined in: renderer/src/VisualComponent.ts:328

Apply the final alpha after transient modifiers.

Parameters

alpha

number

Returns

void

---

applyVisualOptions()

protected applyVisualOptions(options): void

Defined in: renderer/src/VisualComponent.ts:134

Apply the shared visible/tint/alpha/interactive options to renderObject. Call once from the subclass constructor, after the concrete Pixi object is created.

Parameters

options

VisualComponentOptions

Returns

void

---

clearMask()

clearMask(): void

Defined in: renderer/src/VisualComponent.ts:267

Detach and destroy the current mask, if any.

Returns

void

---

destroy()

destroy(): void

Defined in: core/dist/index.d.ts:3329

End this component’s life on its own — the same as entity.remove(SomeClass), without having to name its own class from inside itself, which breaks under subclassing.

Returns

void

Inherited from

Component.destroy

---

destroyOptions()

protected destroyOptions(): DestroyOptions | undefined

Defined in: renderer/src/VisualComponent.ts:323

Pixi destroy options passed to renderObject.destroy(). Default: undefined (Pixi’s own defaults). Override for a component whose destroy must cascade to children (SplitText’s per-segment display objects).

Returns

DestroyOptions | undefined

---

fixedUpdate()?

optional fixedUpdate(dt): void

Defined in: core/dist/index.d.ts:3392

Called every fixed timestep by the built-in ComponentUpdateSystem.

Parameters

dt

number

Fixed timestep in seconds, scaled by scene and entity timeScale.

Returns

void

Inherited from

Component.fixedUpdate

---

inspectRender()

inspectRender(): object

Defined in: renderer/src/VisualComponent.ts:283

Derived render facet for the Inspector — world-space bounds and the component’s own (local, non-inherited) visible flag, computed on demand from the live render object. See computeRenderFacet for the bounds coordinate space.

Returns

bounds

bounds: { height: number; width: number; x: number; y: number; } | null

Axis-aligned bounding box of the component’s geometry, in world space (the same coordinate space the Inspector reports for entity.transform — pixels, before camera/viewport projection). Measured from the geometry itself, so a sized-but-hidden object still reports its real box; null means there is no measurable geometry at all (an empty Graphics, a zero-area object), NOT that the object is hidden. Read RenderFacetSnapshot.visible for the hidden/shown state.

visible

visible: boolean

The component’s own (local, non-inherited) visibility flag at snapshot time. A hidden ancestor (e.g. a parent/layer container set invisible) is NOT folded in — read the relevant parent separately if you need the fully resolved on-screen state.

---

listen()

protected listen<T>(entity, token, handler): void

Defined in: core/dist/index.d.ts:3299

Subscribe to events on any entity, auto-unsubscribe on removal.

Type Parameters

T

T

Parameters

entity

Entity

token

EventToken<T>

handler

(data) => void

Returns

void

Inherited from

Component.listen

---

listenBus()

protected listenBus<K>(event, handler): void

Defined in: core/dist/index.d.ts:3310

Subscribe to an engine EventBus event, auto-unsubscribe on removal. Throws when the entity is not in a scene, like listenScene.

Type Parameters

K

K extends keyof EngineEvents

Parameters

event

K

handler

(data) => void

Returns

void

Inherited from

Component.listenBus

---

listenScene()

protected listenScene<T>(token, handler): void

Defined in: core/dist/index.d.ts:3305

Subscribe to scene-level events, auto-unsubscribe on removal. Handlers fire for bubbled entity events (entity = source) and scene.emit events (entity = undefined).

Type Parameters

T

T

Parameters

token

EventToken<T>

handler

(data, entity?) => void

Returns

void

Inherited from

Component.listenScene

---

onAdd()

onAdd(): void

Defined in: renderer/src/VisualComponent.ts:287

Called when the component is added to an entity. Validate dependencies here — a service, a sibling component, a render layer — and throw when one is missing. The throw is attributed to this component, recorded in Inspector.getErrors().callbackErrors, and rethrown, so it reaches the caller of entity.add() unchanged.

Returns

void

Overrides

Component.onAdd

---

onDestroy()

onDestroy(): void

Defined in: renderer/src/VisualComponent.ts:308

Called when the component is destroyed (entity destroyed or component removed).

Returns

void

Overrides

Component.onDestroy

---

onDisable()

onDisable(): void

Defined in: renderer/src/VisualComponent.ts:304

Called when the component stops being effectively enabled — enabled went false, the entity (or an ancestor) was deactivated, or the component is being removed or destroyed. Put live resources to sleep here; the component is reused afterwards, so do not free anything onEnable cannot rebuild.

Returns

void

Overrides

Component.onDisable

---

onEnable()

onEnable(): void

Defined in: renderer/src/VisualComponent.ts:300

Called when the component becomes effectively enabled — enabled is true and the entity is active. Fires right after onAdd() for a component added to an active entity, and again on every later flip. Bring live resources back online here (unpause a sound, show a display object, re-enable a physics body). Game-state reset does not belong here: the hook sees whatever state the component held while dormant.

Returns

void

Overrides

Component.onEnable

---

service()

protected service<T>(key): T

Defined in: core/dist/index.d.ts:3289

Lazy proxy-based service resolution. Can be used at field-declaration time:

readonly input = this.service(InputManagerKey);

The actual resolution is deferred until first property access.

Type Parameters

T

T extends object

Parameters

key

ServiceKey<T>

Returns

T

Inherited from

Component.service

---

setLayer()

setLayer(name): void

Defined in: renderer/src/VisualComponent.ts:195

Draw this visual on another layer.

Called before the component reaches the display tree — in a subclass constructor, or on a component that has not been added yet — it records the name and nothing else. Called afterwards it detaches the render object and re-parents it through the same resolution onAdd uses, so a SortGroupComponent on the new layer still claims it.

The visual joins its new parent last, which on a layer with no sort means it draws in front of everything already there.

Parameters

name

string

Returns

void

---

setMask()

setMask(factory): MaskHandle

Defined in: renderer/src/VisualComponent.ts:260

Attach a mask to this component’s render object, replacing any existing mask. Returns a handle for inverse toggling, redraw (graphicsMask), or removal. The mask is torn down automatically when the component is destroyed.

Parameters

factory

MaskFactory

Returns

MaskHandle

---

sibling()

protected sibling<C>(cls): C

Defined in: core/dist/index.d.ts:3297

Lazy proxy-based sibling component resolution. Can be used at field-declaration time:

readonly anim = this.sibling(AnimatedSpriteComponent);

The actual resolution is deferred until first property access.

Type Parameters

C

C extends Component

Parameters

cls

ComponentClass<C>

Returns

C

Inherited from

Component.sibling

---

update()?

optional update(dt): void

Defined in: core/dist/index.d.ts:3387

Called every frame by the built-in ComponentUpdateSystem.

Parameters

dt

number

Frame delta in seconds, scaled by scene and entity timeScale.

Returns

void

Inherited from

Component.update

---

use()

protected use<T>(key): T

Defined in: core/dist/index.d.ts:3280

Resolve a service by key, cached after first lookup. Scene-scoped values (registered via scene._registerScoped) take precedence over engine scope. A key declared with scope: "scene" that falls back to engine scope emits a one-shot dev warning — almost always signals a missed beforeEnter hook.

Type Parameters

T

T

Parameters

key

ServiceKey<T>

Returns

T

Inherited from

Component.use