Documentation
    Preparing search index...

    Class AnimationController

    §18's declarative animation state machine (§100 "state machines").

    See the module header for the channel model, the transition semantics, the determinism argument, and what is staged.

    Implements

    Index
    • Parameters

      Returns AnimationController

      FourError INVALID_APPLICATION_STATE — states is empty; a state option is out of range; a transition names an undeclared state; a condition names an undeclared parameter or tests it with the wrong kind of predicate; a parameter name is declared in two kinds; or two states put tracks of different value kinds on one path.

    • get channelCount(): number

      Number of animated channels (the union of every state's tracks). Valid before play — the specs are known at construction.

      Returns number

    • get currentState(): string

      The active state's name — the destination while a transition runs, so conditions leaving it are what the machine evaluates next.

      Returns string

    • get finished(): boolean

      Always false — a state machine has no end (see ControllerPlaybackState). Present because AnimationSystem advances anything that satisfies Advanceable.

      Returns boolean

    • get playbackSpeed(): number

      The AnimationController.speed multiplier.

      Returns number

    • get previousState(): string | undefined

      The name of the state fading out, or undefined when no transition runs or when the running one was interrupted (its source is then a frozen pose, not a state).

      Returns string | undefined

    • get stateLocalTime(): number

      Clip-local seconds of the active state, wrapped on its clip duration (§9).

      Returns number

    • get stateTime(): number

      Seconds the active state has played, clamped to its total duration.

      Returns number

    • get target(): object

      The object every track path is resolved against.

      Returns object

    • get transitioning(): boolean

      Whether a cross-fade is currently running.

      Returns boolean

    • get transitionWeight(): number

      The destination state's blend weight, in [0, 1]. 1 whenever no transition is running, because the destination then owns the whole pose.

      Returns number

    • Detaches this controller from the §16 claim registry and from writing properties. AnimationLayerStack calls this before AnimationController.play so the stack is the sole writer.

      Returns this

      FourError INVALID_APPLICATION_STATE — already played.

    • Advances the machine by one step: move the clocks, finish a cross-fade that has run its length, evaluate the transitions leaving the active state, then write the pose.

      That order is what makes exit time and automatic sequencing work — a transition gated on exitTime fires on the step whose advanced clock reaches it — and it means a transition firing this step poses at weight 0, i.e. exactly the pose the previous step wrote.

      A no-op unless the controller is "running"; a controller never advances itself and never reads a clock (§33). Called by AnimationSystem with the fixed delta.

      Parameters

      Returns this

      FourError INVALID_APPLICATION_STATE — the delta is negative or non-finite.

    • Value adapter of channel index.

      Parameters

      • index: number

      Returns ValueAdapter<unknown>

    • Index of the channel on path, or -1 when this controller does not animate it. Used by AnimationLayerStack.

      Parameters

      • path: string

      Returns number

    • Authored path of channel index.

      Parameters

      • index: number

      Returns string

    • Reads a declared Boolean parameter.

      Parameters

      • name: string

      Returns boolean

      FourError INVALID_APPLICATION_STATE — undeclared name.

    • Reads a declared number parameter.

      Parameters

      • name: string

      Returns number

      FourError INVALID_APPLICATION_STATE — undeclared name.

    • Whether a declared trigger's latch is currently raised.

      Parameters

      • name: string

      Returns boolean

      FourError INVALID_APPLICATION_STATE — undeclared name.

    • Registers a clip-event listener (§16 (from, to] crossing). Returns an unsubscriber. Events fire while a state or a contributing blend-tree child plays forward; AnimationController.advance with { seek: true } suppresses them.

      Parameters

      Returns () => void

    • Suspends advancing. A no-op unless the controller is "running".

      Returns this

    • Resolves one binding per channel, claims the properties (§16), captures the baselines, and writes the initial state's pose at state time 0.

      A no-op on a controller that is not "idle" — §16 resolves bindings once, and re-resolving them would silently redirect a running machine.

      Returns this

      FourError INVALID_APPLICATION_STATE — a channel path resolves to a property whose type its tracks' adapter cannot write.

      FourError from createBinding — a channel path does not resolve.

    • Lowers a declared trigger's latch without any transition consuming it.

      Parameters

      • name: string

      Returns this

      FourError INVALID_APPLICATION_STATE — undeclared name.

    • Resumes advancing. A no-op unless the controller is "paused".

      Returns this

    • Sets a declared Boolean parameter.

      Parameters

      • name: string
      • value: boolean

      Returns this

      FourError INVALID_APPLICATION_STATE — undeclared name.

    • Sets a declared number parameter.

      Parameters

      • name: string
      • value: number

      Returns this

      FourError INVALID_APPLICATION_STATE — the name is not a declared number parameter, or the value is not finite.

    • Raises a declared trigger's latch. It stays raised until a transition that tests it fires, or AnimationController.resetTrigger clears it.

      Parameters

      • name: string

      Returns this

      FourError INVALID_APPLICATION_STATE — undeclared name.

    • Sets the machine-wide speed multiplier, which scales the state clocks and the transition clock. Must be finite and > 0.

      Parameters

      • multiplier: number

      Returns this

      FourError INVALID_APPLICATION_STATE — not finite and > 0.

    • Stops the machine and releases every §16 property claim, leaving all animated values exactly where the last write put them.

      A stopped controller never writes again and the properties it held are free for another writer to claim without a conflict warning. A no-op on an "idle" controller, which holds nothing.

      Returns this