LayeredAnimationController

Defined in: renderer/src/LayeredAnimationController.ts:44

Fan-out wrapper around N sibling AnimationController instances.

Use this when a single logical character is composed of multiple sprite layers (head + body + outfit) — each layer has its own AnimatedSpriteComponent + AnimationController, but they all need to play("walk") or playOneShot("attack") in unison.

play(name) is forwarded to every child controller.
playOneShot(name, opts) computes a single shared duration from the first child (or opts.duration) and passes it to every child as options.duration — so all layers unlock on the same frame regardless of per-layer frame counts.
The wrapper owns the master lock timer and fires the user’s onComplete exactly once.

class Hero extends Entity {
  setup() {
    this.add(new Transform());
    const body = this.spawnChild("body", HeroLayer, { sheet: "body.png" });
    const head = this.spawnChild("head", HeroLayer, { sheet: "head.png" });
    this.add(new LayeredAnimationController({
      controllers: [body.get(AnimationController), head.get(AnimationController)],
    }));
  }
}

Extends

Component

Type Parameters

T

T extends string = string

Constructors

Constructor

new LayeredAnimationController<T>(options): LayeredAnimationController<T>

Defined in: renderer/src/LayeredAnimationController.ts:54

Parameters

options

LayeredAnimationControllerOptions<T>

Returns

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

controllers

Get Signature

get controllers(): readonly AnimationController<T>[]

Defined in: renderer/src/LayeredAnimationController.ts:65

Sibling controllers being driven.

Returns

readonly AnimationController<T>[]

current

Get Signature

get current(): "" | T

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

Currently playing animation name, or "" if none.

Returns

"" | T

locked

Get Signature

get locked(): boolean

Defined in: renderer/src/LayeredAnimationController.ts:75

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

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

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/LayeredAnimationController.ts:117

Clear the lock and force-switch every layer to the given animation.

Parameters

name

T

Returns

void

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()?

optional onAdd(): void

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

Called when the component is added to an entity.

Returns

void

Inherited from

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/LayeredAnimationController.ts:80

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

Parameters

name

T

Returns

void

playOneShot()

playOneShot(name, options?): void

Defined in: renderer/src/LayeredAnimationController.ts:97

Play a one-shot on every layer with a shared lock duration.

If options.duration is omitted, the duration is computed once from the first controller via AnimationController.calcDuration and stored on this wrapper as the single source of truth. Children are given an Infinity per-controller duration so their own lock timers never expire independently — clearing them happens through this wrapper’s unlock when the master timer fires. This avoids a race where a child’s update() could tick out a frame before the wrapper’s (e.g. if components are ordered differently in the scheduler, or accumulated float drift makes one timer cross the threshold a frame earlier).

Parameters

name

T

options?

duration?

number

onComplete?

() => void

Returns

void

serialize()

serialize(): null

Defined in: renderer/src/LayeredAnimationController.ts:147

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

Returns

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/LayeredAnimationController.ts:124

Manually release the one-shot lock on this wrapper and every child.

Returns

void

update()

update(dt): void

Defined in: renderer/src/LayeredAnimationController.ts:133

Tick the shared 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