StateMachine

Defined in: StateMachine.ts:213

A typed state machine driven by its owner’s clock.

States are named, edges are declared, and illegal moves throw. Call tick from the update path whose clock the machine should follow; a component’s dt already includes scene and entity time scaling, so pass it through unchanged.

class Guard extends Component {
  readonly mode = this.stateMachine(
    defineStates({
      patrol: { to: ["alert"] },
      alert: { to: ["patrol"], for: 1, next: "patrol" },
    }),
    "patrol",
  );

  update(dt: number): void {
    if (this.mode.is("patrol") && this.seesPlayer()) this.mode.go("alert");
    this.mode.tick(dt);
  }
}

The machine owns when the state changes. The owner owns what each state does, in its own update.

Type Parameters

S

S extends string

Implements

• Serializable<StateMachineSaveData<S>>

Constructors

Constructor

new StateMachine<S>(states, initial, options?): StateMachine<S>

Defined in: StateMachine.ts:240

Parameters

states

StateDefinitions<S>

initial

NoInfer<S>

options?

StateMachineOptions

Returns

StateMachine<S>

Properties

events

readonly events: StateMachineEvents<S>

Defined in: StateMachine.ts:220

Tokens for on, and for entity.on when the machine was given an events name.

Accessors

elapsed

Get Signature

get elapsed(): number

Defined in: StateMachine.ts:279

Seconds accumulated in the current state.

Returns

number

---

lastTransition

Get Signature

get lastTransition(): StateTransition<S> | null

Defined in: StateMachine.ts:284

Most recent completed transition, or null before the first one.

Returns

StateTransition<S> | null

---

state

Get Signature

get state(): S

Defined in: StateMachine.ts:274

Current state. A parent is never current; its child is.

Returns

S

Methods

_setOwner()

_setOwner(owner): this

Defined in: StateMachine.ts:268

Internal

Attribute game callbacks, and reach the entity, through an owner.

Parameters

owner

StateMachineOwner

Returns

this

---

canGo()

canGo(to): boolean

Defined in: StateMachine.ts:332

Whether the current state can reach to, so a go would move the machine rather than throw or do nothing. Use it where a callback can arrive after the state moved on, such as an animation finishing after the entity already died.

Parameters

to

NoInfer<S>

Returns

boolean

---

go()

go(to): void

Defined in: StateMachine.ts:313

Enter a state the current one declares in to. A child also reaches everything its parent declares. Naming a parent enters that parent’s start child.

Illegal moves throw before any hook runs. Naming the current state restarts it when it lists itself in to, and does nothing otherwise.

Parameters

to

NoInfer<S>

Returns

void

---

hydrate()

hydrate(raw): void

Defined in: StateMachine.ts:420

Restore state and elapsed time without running exit or enter hooks. A snapshot that carries a computed duration resumes on that duration; one that does not asks the state’s for callback for a fresh value.

Parameters

raw

StateMachineSaveData<S>

Returns

void

Implementation of

Serializable.hydrate

---

is()

is(state): boolean

Defined in: StateMachine.ts:289

Whether state is the current state or its parent.

Parameters

state

NoInfer<S>

Returns

boolean

---

on()

on<T>(token, handler): () => void

Defined in: StateMachine.ts:386

Subscribe to one of this machine’s events. Returns an unsubscribe function. Handlers run inside the transition, so they may not call go, tick, start or hydrate on this machine; they may on another.

Type Parameters

T

T

Parameters

token

EventToken<T>

handler

(payload) => void

Returns

() => void

---

serialize()

serialize(): StateMachineSaveData<S>

Defined in: StateMachine.ts:400

Returns

StateMachineSaveData<S>

Implementation of

Serializable.serialize

---

start()

start(): void

Defined in: StateMachine.ts:299

Run the initial state’s enter hook. Optional: the first tick does the same. Call it from onAdd to run the hook before the first frame. Construction and hydrate run no hooks, so an owner can finish assigning dependencies first.

Returns

void

---

tick()

tick(dt): void

Defined in: StateMachine.ts:344

Advance the current state’s timer by a finite, non-negative dt, entering next when the duration is reached. Time past a boundary is discarded, so one call advances the current state once. Inside a sequence the parent’s own deadline is checked after that, and can end the sequence in the same call. The first call also runs the initial enter hook if start has not.

Parameters

dt

number

Returns

void

---

toJSON()

toJSON(): StateMachineInspection<S>

Defined in: StateMachine.ts:468

Plain data used by the Inspector’s component-field reflection.

Returns

StateMachineInspection<S>