03 Library

3.1 - Common states

The behavior machine includes several predefined common states that may be useful in the creation of a machine as detailed below.

3.1.1 - IdleState

The idle state does nothing functionally but can be used as a placeholder or end state for a machine.

state = IdleState()

3.1.2 - WaitState

The wait state is designed to wait for a duration of seconds before exiting. It is frequently used as a time-out switch alongside another long-running state in an AtLeastOne.

state = WaitStates(duration: float)

3.1.3 - SaveFlowState

State to save the flow into the board at a specified key.

state = SaveFlowState(key: str)

3.1.4 - SetFlowState

State to set the flow out from this state.

state = SetFlowState(value: any)

3.1.5 - SetFlowFromBoardState

State to set the flow out from this state to the value under a key in the board.

state = SetFlowFromBoardState(key: str)

3.1.6 - SetBoardState

Set a specific board key-value pair.

state = SetBoardState(key: str, val: any)

3.1.7 - GetBoardState

Get the value for a given key from the board.

state = GetBoardState(key: str)

3.1.8 - Print State

State to print the passed string.

state = PrintState(text: str)

3.2 - Nested States

Multiple states can be nested together inside a single state to perform different functionalities as inspired by behavior trees.

3.2.1 - Parallel State

State to run multiple states in parallel to each other. This state does not terminate until all states have terminated. The return value of this state is dependent on the return value of its children. If the state as a whole is interrupted, StateStatus.INTERRUPTED is returned. If any child ends in an exception StateStatus.EXCEPTION is returned. If all states succeed, StateStatus.SUCCESS is returned, otherwise StateStatus.FAILED is returned.

Flow in and out of a parallel state is unique because of the nature of having multiple children. Flow in to a parallel state is deepcopied and a unique copy is passed to each child. Flow out of the state is complied into a list in the order the children were added to the parallel state. Each child's state is appended individually to the list and the whole list is then passed as the flow out of the parallel state.

Parallel states can be instantiated with their children, or child states can be added to the state after instantiation using parallel_state.add_children(state: State).

from behavior_machine.library import ParallelState

state1 = State()
state2 = State()
state3 = State()

parallel_state = ParallelState([state1, state2, state3], name="parallel_state")

3.2.2 - At Least One State

At least one state inherits from parallel states to run multiple states in parallel to each other. Unlike parallel states, once any state finishes successfully, the remaining states are all interrupted in the middle of running. Because it inherits from parallel state, flow functions identically to parallel states.

from behavior_machine.library import AtLeastOneState

state1 = State()
state2 = State()
state3 = State()

atleastone_state = AtLeastOneState([state1, state2, state3], name="atleastone_state")

3.2.3 - Sequential State

State to execute a number of states sequentially. Each state must return StateStatus.SUCCESS so the state knows to transition to the next one. Flow in is passed to the first state and flow out is the flow out from the last state. Intermediate flow is passed between states as normal.

from behavior_machine.library import SequentialState

state1 = State()
state2 = State()
state3 = State()

sequential_state = SequentialState([state1, state2, state3], name="sequential_state")

3.2.4 - Selector State

Selector state functions inherits from sequential states to run multiple state in sequence. However, unlike the sequential state, the selector state does not run all states but instead runs the states until the first one that returns success and then quits. Flow is identical to sequential state and flow out is the flow out from the last state that is run

from behavior_machine.library import SelectorState

state1 = State()
state2 = State()
state3 = State()

selector_state = SelectorState([state1, state2, state3], name="selector_state")

3.2.5 - Random Pick State

Random pick state randomly runs any of its children and ignores the rest.

from behavior_machine.library import RandomPickState

state1 = State()
state2 = State()
state3 = State()

randompick_state = RandomPickState([state1, state2, state3], name="randompick_state")