SplitTextComponent

Defined in: renderer/src/SplitTextComponent.ts:111

Displays text split into per-character / per-word / per-line display objects, for animated and rich text — typewriter reveals, per-letter colour / wave, staggered line entrances. Wraps Pixi v8’s SplitText (canvas) / SplitBitmapText (bitmap); the segments are exposed as SplitTextComponent.chars, SplitTextComponent.words, and SplitTextComponent.lines for the game to animate directly.

For static or simple dynamic strings prefer TextComponent — a single display object is cheaper and SplitText re-layout on every text change is not free.

Pixi marks SplitText experimental; its char spacing can differ slightly from Text (browser kerning is lost once glyphs are split).

Extends

VisualComponent

Constructors

Constructor

new SplitTextComponent(options): SplitTextComponent

Defined in: renderer/src/SplitTextComponent.ts:126

Parameters

options

SplitTextComponentOptions

Returns

SplitTextComponent

Overrides

VisualComponent.constructor

Properties

entity

entity: Entity

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

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

Inherited from

VisualComponent.entity

fx

readonly fx: EffectsHost

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

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 after save/load.

Inherited from

VisualComponent.fx

isBitmap

readonly isBitmap: boolean

Defined in: renderer/src/SplitTextComponent.ts:115

Whether this renders with a bitmap font (SplitBitmapText).

layerName

readonly layerName: string

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

Inherited from

VisualComponent.layerName

splitText

readonly splitText: SplitText | SplitBitmapText

Defined in: renderer/src/SplitTextComponent.ts:113

The underlying Pixi SplitText / SplitBitmapText container.

restorePriority

static restorePriority: number = 30

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

Snapshot restore order. On load, an entity’s components are re-added in ascending priority, so a component whose onAdd() reads a sibling can rely on lower-priority siblings being present and initialized. Undeclared = 100. Engine components reserve 0-99; game and addon components declare a value only when a sibling onAdd() dependency requires it. Equal priorities restore in save-time add order. Subclasses inherit their base class’s priority unless they declare their own.

Inherited from

VisualComponent.restorePriority

updatePriority?

static optional updatePriority?: number

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

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

VisualComponent.updatePriority

Accessors

alpha

Get Signature

get alpha(): number

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

Get the container’s alpha (opacity).

Returns

number

Set Signature

set alpha(alpha): void

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

Set the container’s alpha (opacity).

Parameters

alpha

number

Returns

void

Inherited from

VisualComponent.alpha

blendMode

Get Signature

get blendMode(): BLEND_MODES

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

Get the container’s blend mode.

Returns

BLEND_MODES

Set Signature

set blendMode(mode): void

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

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

Parameters

mode

BLEND_MODES

Returns

void

Inherited from

VisualComponent.blendMode

charAnchor

Get Signature

get charAnchor(): SegmentAnchor

Defined in: renderer/src/SplitTextComponent.ts:228

Returns

SegmentAnchor

Set Signature

set charAnchor(anchor): void

Defined in: renderer/src/SplitTextComponent.ts:224

Transform origin for each character (normalized 0–1).

Parameters

anchor

SegmentAnchor

Returns

void

chars

Get Signature

get chars(): (Text | BitmapText)[]

Defined in: renderer/src/SplitTextComponent.ts:181

Individual character segments (Text or BitmapText), in reading order.

Returns

(Text | BitmapText)[]

context

Get Signature

get context(): EngineContext

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

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

Returns

EngineContext

Inherited from

VisualComponent.context

effectiveEnabled

Get Signature

get effectiveEnabled(): boolean

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

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

VisualComponent.effectiveEnabled

enabled

Get Signature

get enabled(): boolean

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

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:2733

Parameters

value

boolean

Returns

void

Inherited from

AnimationController.enabled

lineAnchor

Get Signature

get lineAnchor(): SegmentAnchor

Defined in: renderer/src/SplitTextComponent.ts:246

Returns

SegmentAnchor

Set Signature

set lineAnchor(anchor): void

Defined in: renderer/src/SplitTextComponent.ts:242

Transform origin for each line (normalized 0–1).

Parameters

anchor

SegmentAnchor

Returns

void

lines

Get Signature

get lines(): DisplayContainer[]

Defined in: renderer/src/SplitTextComponent.ts:191

Line-group containers, each holding its word containers.

Returns

DisplayContainer[]

mask

Get Signature

get mask(): MaskHandle | undefined

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

The currently attached mask handle, if any. Useful after save/load to recover a handle whose caller-side reference went stale.

Returns

MaskHandle | undefined

Inherited from

VisualComponent.mask

renderObject

Get Signature

get renderObject(): SplitText | SplitBitmapText

Defined in: renderer/src/SplitTextComponent.ts:176

The underlying Pixi display object.

Returns

SplitText | SplitBitmapText

The underlying Pixi display object.

Overrides

VisualComponent.renderObject

scene

Get Signature

get scene(): Scene

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

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

VisualComponent.scene

tint

Get Signature

get tint(): number

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

Get the container’s tint color.

Returns

number

Set Signature

set tint(color): void

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

Set the container’s tint color.

Parameters

color

ColorSource

Returns

void

Inherited from

VisualComponent.tint

updatePriority

Get Signature

get updatePriority(): number

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

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:2759

Parameters

value

number

Returns

void

Inherited from

VisualComponent.updatePriority

visible

Get Signature

get visible(): boolean

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

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

Returns

boolean

Set Signature

set visible(value): void

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

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

Inherited from

VisualComponent.visible

wordAnchor

Get Signature

get wordAnchor(): SegmentAnchor

Defined in: renderer/src/SplitTextComponent.ts:237

Returns

SegmentAnchor

Set Signature

set wordAnchor(anchor): void

Defined in: renderer/src/SplitTextComponent.ts:233

Transform origin for each word (normalized 0–1).

Parameters

anchor

SegmentAnchor

Returns

void

words

Get Signature

get words(): DisplayContainer[]

Defined in: renderer/src/SplitTextComponent.ts:186

Word-group containers, each holding its character segments.

Returns

DisplayContainer[]

Methods

_applyEnabled()

_applyEnabled(effective): void

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

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

VisualComponent._applyEnabled

_refreshEnabled()

_refreshEnabled(): void

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

Internal

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

Returns

void

Inherited from

VisualComponent._refreshEnabled

_runCleanups()

_runCleanups(): void

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

Internal

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

Returns

void

Inherited from

VisualComponent._runCleanups

addCleanup()

protected addCleanup(fn): void

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

Parameters

fn

() => void

Returns

void

Inherited from

VisualComponent.addCleanup

afterRestore()

afterRestore(data): void

Defined in: renderer/src/SplitTextComponent.ts:269

Restore effects and mask after the split text is parented.

Parameters

data

SplitTextData

Returns

void

Overrides

VisualComponent.afterRestore

applyVisualOptions()

protected applyVisualOptions(options): void

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

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

Inherited from

VisualComponent.applyVisualOptions

clearMask()

clearMask(): void

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

Detach and destroy the current mask, if any.

Returns

void

Inherited from

VisualComponent.clearMask

destroyOptions()

protected destroyOptions(): DestroyOptions

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

{ children: true } so the per-line / word / char display objects that split() parented are destroyed too (not freed by the default destroy).

Returns

DestroyOptions

Overrides

VisualComponent.destroyOptions

fixedUpdate()?

optional fixedUpdate(dt): void

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

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

VisualComponent.fixedUpdate

inspectRender()

inspectRender(): SplitTextRenderFacet

Defined in: renderer/src/SplitTextComponent.ts:313

Derived render facet for the Inspector. Beyond the shared world-space bounds and container-level visible, this walks the per-character segments and reports glyphs (one { visible } per char in reading order) plus visibleText — the substring currently painted. This is the read-only window into a typewriter reveal: where serialize() reports the full declared string, visibleText reports only the glyphs whose chars[i].visible is still on. Not part of serialize(); see computeRenderFacet for the bounds coordinate space.

Note: Pixi’s chars array (and therefore glyphs / visibleText) contains only the rendered glyph segments — whitespace is laid out via words/lines and is NOT a char. So visibleText strips spaces: a fully revealed "Hello world" reports "Helloworld". Use it to compare which glyphs are on screen, not to reconstruct the original string verbatim.

Returns

SplitTextRenderFacet

Overrides

VisualComponent.inspectRender

listen()

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

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

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

VisualComponent.listen

listenScene()

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

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

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

VisualComponent.listenScene

onAdd()

onAdd(): void

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

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

Inherited from

VisualComponent.onAdd

onDestroy()

onDestroy(): void

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

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

Returns

void

Inherited from

VisualComponent.onDestroy

onDisable()

onDisable(): void

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

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

Inherited from

VisualComponent.onDisable

onEnable()

onEnable(): void

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

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

Inherited from

VisualComponent.onEnable

onRemove()?

optional onRemove(): void

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

Called when the component is removed from an entity.

Returns

void

Inherited from

VisualComponent.onRemove

resplit()

resplit(): void

Defined in: renderer/src/SplitTextComponent.ts:218

Re-split now. Only needed when constructed with autoSplit: false — after mutating text / style, call this to apply the change in one pass.

Returns

void

restoreVisual()

protected restoreVisual(data): void

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

Restore effects and mask from a snapshot’s shared fields. Call from the subclass’s afterRestore, after the render object is parented.

Parameters

data

Pick<VisualComponentData, "effects" | "mask">

Returns

void

Inherited from

VisualComponent.restoreVisual

serialize()

serialize(): SplitTextData

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

Return a JSON-serializable snapshot of this component’s state. Used by the save system.

Returns

SplitTextData

Overrides

VisualComponent.serialize

serializeVisual()

protected serializeVisual(): VisualComponentData

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

Serialise the shared layer/visible/tint/alpha/blendMode/interactive/ effects/mask fields. Subclasses spread this into their own Data object alongside their own-specific fields (texture key, text, anchor, …).

Returns

VisualComponentData

Inherited from

VisualComponent.serializeVisual

service()

protected service<T>(key): T

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

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

VisualComponent.service

setMask()

setMask(factory): MaskHandle

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

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

setStyle()

setStyle(style): void

Defined in: renderer/src/SplitTextComponent.ts:202

Replace the text style (re-splits when autoSplit is on).

Parameters

style

TextStyleOptions

Returns

void

setText()

setText(value): void

Defined in: renderer/src/SplitTextComponent.ts:196

Replace the displayed string (re-splits when autoSplit is on).

Parameters

value

string

Returns

void

sibling()

protected sibling<C>(cls): C

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

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

VisualComponent.sibling

update()?

optional update(dt): void

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

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

VisualComponent.update

use()

protected use<T>(key): T

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

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

VisualComponent.use

fromSnapshot()

static fromSnapshot(data): SplitTextComponent

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

Parameters

data

SplitTextData

Returns

SplitTextComponent