State

A Stately state machine consists of a top-level state (known as the “root”) and various substates which are defined using Transitions. You will never reference Transition except through methods provided by State.

A State consists of a name, various conditions for transitions between states, and callback functions to execute when states are entered, updated, or exited.

Method Reference

Start()

The final step in initializing the state machine. Should be called once and only once on the root state before any updates are called.

StartAt(State subState)
Parameters:subState (State) – The substate to begin at.

Sets the starting sub-state of a state. Essentially, you can think of this method as creating a sub-level of the state.

Reset()

Resets a state to its starting sub-state.

Update(float deltaTime)
Parameters:deltaTime (float) – The change in time since the last call to Update.

Updates the state machine, checking for state transitions and updating timers. Should only be called on the root state.

FixedUpdate()

A convenience method intended for Unity. Allows for the OnFixedUpdate callback to be used. Should only be called on the root state.

ChangeTo(State otherState)
Parameters:otherState (State) – The state to create a Transition to.
Returns:The Transition object between the two states.

The bread and butter of Stately. Creates a Transition object from the calling state to the given state. Transition objects are never created or manipulated directly. Instead, use expressions on states to define transition conditions and callbacks.

Examples

idleState.ChangeTo(runningState).If(() => Input.GetButton("Run"));

The state will change from idleState to runningState if the Run button is down.

idleState.ChangeTo(jumpingState).If(() => Input.GetButton("Jump")).ThenDo(delegate {
  dustParticles.Emit(100);
});

The state will change from idleState to jumpingState if the Jump button is down, and then it will emit dust particles.

For a complete list of transition conditions and callback methods please refer to <transition>

ChangeToSubState(State otherState)
Parameters:otherState (State) – The state to create an AnyStateTransition to.
Returns:The AnyStateTransition to the substate.

Called from a higher-level state using a substate as a parameter. When the condition is met, it will transition from any substate into the given otherState. Useful when you have many substates that can change between each other.

States will not self-transition with this method.

Example

rootState = new State("root");

redState = new State("red");
blueState = new State("blue");
greenState = new State("green");
yellowState = new State("yellow");

rootState.ChangeToSubState(redState).IfSignalCaught("red");
rootState.ChangeToSubState(blueState).IfSignalCaught("blue");
rootState.ChangeToSubState(greenState).IfSignalCaught("green");
rootState.ChangeToSubState(yellowState).IfSignalCaught("yellow");

rootState.StartAt(redState);

Now, redState, blueState, greenState, and yellowState can all transition between each other, but we’ve narrowed this down to 4 transitions instead of 12. Nice!

SendSignal(string signal)
Parameters:signal (string) – The signal to send to the state.

For use with the IfSignalCaught transition condition. This signal propagates recursively until a state with no substate is reached.

OnTransitionTo(State otherState)
Parameters:otherState (State) – The other state.
Returns:The already existing Transition object between these two states.

Used to redefine transition callbacks in conjunction with the InsteadDo and AlsoDo methods. Useful for extending or modifying transition behavior when inheriting classes that implement a state machine.

Example

idleState.OnTransitionTo(jumpingState).InsteadDo(delegate {
  dustParticles.Emit(500);
});

Jumping now emits 500 dust particles instead of 100!

ReplaceTransitionCondition(State otherState)
Parameters:otherState (State) – The other state.
Returns:The already existing Transition object between these two states.

This function is similar to OnTransitionTo, except that it erases the transition condition so it can be replaced. Useful for extending or modifying transition behavior when inheriting classes that implement a state machine.

Example

idleState.ReplaceTransitionCondition(jumpingState).With.After(2f);

Now the idle state will transition to the jumping state after 2 seconds instead of waiting for a button press.

Callback Reference

OnEnter
Runs when the state is entered.
OnUpdate
Runs on each update tick.
OnFixedUpdate
Runs on each FixedUpdate tick (convenience method for Unity).
OnExit
Runs when the state is exited.

Property Reference

string Name
Returns:The name of the State.
State CurrentState
Returns:The current substate of the State.
State CurrentStateRecursive
Returns:The deepest substate of the State.
string CurrentStatePath
Returns:A string concatenating the names of each active substate.

Useful for debug purposes.

Example

rootState = new State("root");
idleState = new State("idle");
animatingState = new State("animating");

rootState.StartAt(idleState);
idleState.StartAt(animatingState);

In this case, rootState.CurrentStatePath would return "root.idle.animating".