AnimationController

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

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

enabled

enabled: boolean

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

Whether this component is active. Disabled components are skipped by ComponentUpdateSystem.

Inherited from

Component.enabled

entity

entity: Entity

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

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

Accessors

context

Get Signature

get context(): EngineContext

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

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

Currently playing animation name, or "" if none.

Returns

"" | T

frame

Get Signature

get frame(): number

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

Current frame index of the underlying AnimatedSprite.

Returns

number

locked

Get Signature

get locked(): boolean

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

True if a one-shot animation is blocking.

Returns

boolean

scene

Get Signature

get scene(): Scene

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

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

Runtime speed multiplier (default 1).

Returns

number

Set Signature

set speed(value): void

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

Parameters

value

number

Returns

void

Methods

_runCleanups()

_runCleanups(): void

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

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

Parameters

fn

() => void

Returns

void

Inherited from

Component.addCleanup

afterRestore()?

optional afterRestore(data, resolve): void

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

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

Calculate the wall-clock duration (ms) of a named animation.

Frame-rate independent: PixiJS normalises deltaTime via Ticker.targetFPMS (0.06), so the formula holds at any actual fps. Inaccurate only if Ticker.shared.speed is changed from 1.

Parameters

name

T

Returns

number

fixedUpdate()?

optional fixedUpdate(dt): void

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

Called every fixed timestep by the built-in ComponentUpdateSystem.

Parameters

dt

number

Returns

void

Inherited from

Component.fixedUpdate

forcePlay()

forcePlay(name): void

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

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

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

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

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

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

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

Returns

void

Inherited from

Component.onDestroy

onRemove()?

optional onRemove(): void

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

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

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

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 | null

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

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

Returns

AnimationControllerData | null

Overrides

Component.serialize

service()

protected service<T>(key): T

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

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

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

Manually release the one-shot lock.

Returns

void

update()

update(dt): void

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

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

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

Parameters

data

AnimationControllerData

Returns

AnimationController