AnimationController

Defined in: renderer/src/AnimationController.ts:70

High-level animation controller that manages named animations on top of a sibling AnimatedSpriteComponent.

Provides one-shot locking, per-animation anchors, and type-safe animation names via the generic parameter.

Narrowing the animation-name type — entity.get(AnimationController) returns AnimationController<string> (the default T); the runtime class isn’t generic, and a string-typed instance can’t substitute for a narrower one (the current: T | "" getter is covariant on T). Cast at the field declaration so every consumer downstream sees the narrow type:

type Anim = "idle" | "walk" | "shoot";

class HeroController extends Component {
  private readonly _anim = this.sibling(AnimationController) as
    AnimationController<Anim>;
}

For multi-sprite (head + body + outfit) characters, see LayeredAnimationController — it fans play()/playOneShot() across a list of sibling controllers with a single shared lock timer.

Extends

• Component

Type Parameters

T

T extends string = string

Constructors

Constructor

new AnimationController<T>(animations): AnimationController<T>

Defined in: renderer/src/AnimationController.ts:86

Parameters

animations

Record<T, AnimationDef>

Returns

AnimationController<T>

Overrides

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

Component.entity

---

restorePriority

static restorePriority: number = 40

Defined in: renderer/src/AnimationController.ts:74

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.

Overrides

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

Component.updatePriority

Accessors

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

Component.context

---

current

Get Signature

get current(): "" | T

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

Currently playing animation name, or "" if none.

Returns

"" | T

---

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

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

Component.enabled

---

frame

Get Signature

get frame(): number

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

Current frame index of the underlying AnimatedSprite.

Returns

number

---

locked

Get Signature

get locked(): boolean

Defined in: renderer/src/AnimationController.ts:110

True if a one-shot animation is blocking.

Returns

boolean

---

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

Component.scene

---

speed

Get Signature

get speed(): number

Defined in: renderer/src/AnimationController.ts:120

Runtime speed multiplier (default 1).

Returns

number

Set Signature

set speed(value): void

Defined in: renderer/src/AnimationController.ts:124

Parameters

value

number

Returns

void

---

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

Component.updatePriority

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

Component._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

Component._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

Component._runCleanups

---

addCleanup()

protected addCleanup(fn): void

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

Register a cleanup function to run when this component is removed or destroyed.

Parameters

fn

() => void

Returns

void

Inherited from

Component.addCleanup

---

afterRestore()?

optional afterRestore(data, resolve): void

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

Called after onAdd() during save/load restoration. Apply state that depends on onAdd() having run.

Parameters

data

unknown

resolve

SnapshotResolver

Returns

void

Inherited from

Component.afterRestore

---

calcDuration()

calcDuration(name): number

Defined in: renderer/src/AnimationController.ts:175

Calculate the engine-scaled duration (seconds) of a named animation.

Frame-rate independent: PixiJS normalises deltaTime via Ticker.targetFPMS (0.06), so the formula holds at any actual fps. The controller timer and animated sprite both receive engine-scaled time.

Parameters

name

T

Returns

number

---

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

Component.fixedUpdate

---

forcePlay()

forcePlay(name): void

Defined in: renderer/src/AnimationController.ts:155

Clear lock and force-switch to the given animation.

Parameters

name

T

Returns

void

---

inFrameRange()

inFrameRange(start, end): boolean

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

Check whether the current frame is within [start, end] inclusive.

Parameters

start

number

end

number

Returns

boolean

---

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

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

Component.listenScene

---

onAdd()

onAdd(): void

Defined in: renderer/src/AnimationController.ts:216

Auto-play the first defined animation (respects prior restore).

Returns

void

Overrides

Component.onAdd

---

onDestroy()?

optional onDestroy(): void

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

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

Returns

void

Inherited from

Component.onDestroy

---

onDisable()?

optional onDisable(): void

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

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

Component.onDisable

---

onEnable()?

optional onEnable(): void

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

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

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

Component.onRemove

---

play()

play(name): void

Defined in: renderer/src/AnimationController.ts:129

Play a named animation. No-op if already current or locked.

Parameters

name

T

Returns

void

---

playOneShot()

playOneShot(name, options?): void

Defined in: renderer/src/AnimationController.ts:141

Play an animation as a one-shot, locking out other plays until complete. No-op if already locked on the same animation (prevents restart flicker).

When options.duration is omitted, the lock duration is auto-calculated from this controller’s own frame count and speed via calcDuration. Pass an explicit duration to synchronise lock release across multiple controllers (see LayeredAnimationController).

Parameters

name

T

options?

duration?

number

onComplete?

() => void

Returns

void

---

serialize()

serialize(): AnimationControllerData

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

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

Returns

AnimationControllerData

Overrides

Component.serialize

---

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

Component.service

---

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

Component.sibling

---

unlock()

unlock(): void

Defined in: renderer/src/AnimationController.ts:161

Manually release the one-shot lock.

Returns

void

---

update()

update(dt): void

Defined in: renderer/src/AnimationController.ts:227

Tick the one-shot lock timer.

Parameters

dt

number

Returns

void

Overrides

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

Component.use

---

fromSnapshot()

static fromSnapshot(data): AnimationController

Defined in: renderer/src/AnimationController.ts:199

Parameters

data

AnimationControllerData

Returns

AnimationController