Skip to main content

Class: StateMachine

Defined in: src/interaction/StateMachine.ts:223

StateMachine — a Rive-style, input-driven animation controller.

A machine holds named states, typed inputs (boolInput, numberInput, triggerInput) and transitions between states guarded by input conditions. Call update each frame to evaluate the transitions of the current state. On entering a state the machine runs that state's onEnter action, which is where an animation or a property change starts. This makes interactive, state-driven animations (hover to expand, toggle, multi-state UI flows) first-class, which manim-web lacked.

The core logic is headless and deterministic: it reads no DOM and, for the same input sequence, produces the same state sequence. To drive it from UI events, pass inputHandler / triggerHandler to a Clickable onClick, a Hoverable onHoverStart / onHoverEnd, or a Slider onChange.

Example​

const sm = new StateMachine();
sm.addState('idle');
sm.addState('open', { onEnter: () => box.animateTo({ scale: 2 }) });
sm.boolInput('hovering', false);
sm.triggerInput('click');
sm.addTransition('idle', 'open', when('hovering').isTrue());
sm.addTransition('open', 'idle', when('click').onTrigger());

makeHoverable(box, scene, {
  onHoverStart: () => sm.inputHandler('hovering')(true),
  onHoverEnd: () => sm.inputHandler('hovering')(false),
});
// Each frame:
sm.update(dt);

Constructors​

Constructor​

new StateMachine(options?): StateMachine

Defined in: src/interaction/StateMachine.ts:234

Create a StateMachine.

Parameters​

options?​

StateMachineOptions

Optional initial-state name.

Returns​

StateMachine

Methods​

addState()​

addState(name, config): this

Defined in: src/interaction/StateMachine.ts:246

Add a state. The first state added becomes the initial state unless an explicit initial was passed to the constructor.

Parameters​

name​

string

Unique state name.

config​

StateConfig = {}

Optional onEnter / onExit actions.

Returns​

this

this, for chaining.

addTransition()​

addTransition(from, to, guard?, config?): this

Defined in: src/interaction/StateMachine.ts:300

Add a transition from one state to another, guarded by an optional condition. Transitions are evaluated in the order they are added, and the first matching one fires.

Parameters​

from​

string

Source state name.

to​

string

Target state name.

guard?​

Guard

Condition that must pass; omit for an unconditional transition.

config?​

TransitionConfig = {}

Optional per-transition action.

Returns​

this

this, for chaining.

boolInput()​

boolInput(name, initial): this

Defined in: src/interaction/StateMachine.ts:263

Declare a boolean input.

Parameters​

name​

string

Unique input name.

initial​

boolean = false

Initial value (default: false).

Returns​

this

this, for chaining.

fire()​

fire(name): this

Defined in: src/interaction/StateMachine.ts:334

Make a trigger input pending for the next update. A no-op (with a warning) for an unknown input or for a non-trigger input.

Parameters​

name​

string

Trigger input name.

Returns​

this

this, for chaining.

getCurrentState()​

getCurrentState(): string

Defined in: src/interaction/StateMachine.ts:358

The current state name, or null when no state is defined.

Returns​

string

getInput()​

getInput(name): InputValue

Defined in: src/interaction/StateMachine.ts:353

Read an input value. Returns the pending flag for a trigger, or undefined for an unknown input.

Parameters​

name​

string

Input name.

Returns​

InputValue

inputHandler()​

inputHandler(name): (value) => void

Defined in: src/interaction/StateMachine.ts:367

A handler that sets a bool or number input, for wiring to a UI event such as a Slider onChange or a Hoverable callback.

Parameters​

name​

string

Input name.

Returns​

(value): void

Parameters​
value​

InputValue

Returns​

void

numberInput()​

numberInput(name, initial): this

Defined in: src/interaction/StateMachine.ts:274

Declare a numeric input.

Parameters​

name​

string

Unique input name.

initial​

number = 0

Initial value (default: 0).

Returns​

this

this, for chaining.

reset()​

reset(): this

Defined in: src/interaction/StateMachine.ts:412

Reset the machine to its initial state and clear all pending triggers. Does not run onEnter / onExit actions.

Returns​

this

this, for chaining.

setInput()​

setInput(name, value): this

Defined in: src/interaction/StateMachine.ts:314

Set a bool or number input value. A no-op (with a warning) for an unknown input or for a trigger input (use fire).

Parameters​

name​

string

Input name.

value​

InputValue

New value.

Returns​

this

this, for chaining.

triggerHandler()​

triggerHandler(name): () => void

Defined in: src/interaction/StateMachine.ts:378

A handler that fires a trigger input, for wiring to a UI event such as a Clickable onClick.

Parameters​

name​

string

Trigger input name.

Returns​

(): void

Returns​

void

triggerInput()​

triggerInput(name): this

Defined in: src/interaction/StateMachine.ts:285

Declare a trigger input. A trigger is pending for exactly one update evaluation after fire, then it auto-resets.

Parameters​

name​

string

Unique input name.

Returns​

this

this, for chaining.

update()​

update(dt): boolean

Defined in: src/interaction/StateMachine.ts:391

Evaluate the transitions of the current state once. At most one transition fires per call (the first matching, in insertion order). Any pending triggers are reset after the evaluation.

Parameters​

dt​

number = 0

Delta time (seconds) passed to action contexts. Default 0.

Returns​

boolean

true if a transition fired.