01 State

States are the basis of the Behavior Machine. All logic is contained in states which can be executed as determined by outside logic dependent on their results.

1.1 - Initialization

States are initialized using the following and may be passed any other arguments as needed. Names are not required for state instantiation, but can make debugging and clarity of code simpler.

from behavior_machine.core import State
class NewState(State):
    def __init__(self, arg1, arg2, ..., name=None):
        super().__init__(name=name)
        # Further initalization logic

# Class instantiation
new_state = NewState(arg1, arg2, name="new_state")

All states are initialized together when they are instantiated.

1.2 - Execute

The execute function is the defining feature of any State and is required to be implemented by every State. This is where the actual logic of the state occurs and where the information may be set for any subsequent logical flow decisions to be made. This function can perform any task desired and may call additionally defined helper functions as needed. See details about the board parameter.

def execute(self, board):
    # Implementation required!

1.3 - Flow

Information can be transfered between states in a number of ways. One of these is flow, a direct passing of information down the tree from one state to the next sequentially. States must set and access this manually in their execute function. Flow can be of any type and is only available to a State's immediate successor in the executed logic of a behavior machine. Flow has two corresponding versions: flow in and flow out.

Flow in is the information a state is passed by its predecessor.

def execute(self, board):
    passed_in_info = self.flow_in

Flow out is the information a state passes its successor.

def execute(self, board):
    self.flow_out = info_to_pass_along

Note

Flow in to a specific state cannot be accessed before its execute function runs (i.e. the __init__ function cannot access it).

1.4 - StateStatus

Some states may choose to return a StateStatus from their execute function. This can be necesary for the success of some common states. The status can be any one of the following values:

UNKNOWN = -1        # Unknown
NOT_RUNNING = 0     # The default state before a state runs
RUNNING = 1         # The state is currently running
SUCCESS = 2         # The state finished successfully
FAILED = 3          # The state failed
INTERRUPTED = 4     # The state was interrupted
EXCEPTION = 5       # An internal uncatched exception was thrown.
NOT_SPECIFIED = 6   # execute() didn't say

Of these, a state may return the following:

from behavior_machine.core import StateStatus

def execute(self, board):
    return StateStatus.SUCCESS
    return StateStatus.FAILED
    return StateStatus.INTERRUPTED
    return StateStatus.EXCEPTION

If the state doesn't return a status value it is assigned StateStatus.NOT_SPECIFIED for the purposes of the larger machine upon its execute function's return.

1.5 - Interruption

At any point in its execution, a state can be interrupted by the larger machine, generally when part of a combined state which will do so (see At least one states). This is especially important for states with long running loops or other tasks that they may need to wait for but that may asked to exit prematurely by external factors. States can check their own interruption status via the self.is_interrupted() function and act accordingly.

from behavior_machine.core import StateStatus
import time

def execute(self, board):
    while not self.is_interrupted():
        time.sleep(0.1)
    return StateStatus.INTERRUPTED