StateMachine

State Machine extension

Zenroom may optionally include a simple extension to implement finite state machines logics in a straightforward way.

In its simplest form, create a standalone state machine using:

machine = require "statemachine"

local fsm = machine.create({
  initial = 'green',
  events = {
    { name = 'warn',  from = 'green',  to = 'yellow' },
    { name = 'panic', from = 'yellow', to = 'red'    },
    { name = 'calm',  from = 'red',    to = 'yellow' },
    { name = 'clear', from = 'yellow', to = 'green'  }
}})

... will create an object with a method for each event:

• fsm:warn() - transition from 'green' to 'yellow'
• fsm:panic() - transition from 'yellow' to 'red'
• fsm:calm() - transition from 'red' to 'yellow'
• fsm:clear() - transition from 'yellow' to 'green'

along with the following members:

• fsm.current - contains the current state
• fsm.currentTransitioningEvent - contains the current event that is in a transition.
• fsm:is(s) - return true if state s is the current state
• fsm:can(e) - return true if event e can be fired in the current state
• fsm:cannot(e) - return true if event e cannot be fired in the current state

Multiple 'from' and 'to' states for a single event

If an event is allowed from multiple states, and always transitions to the same state, then simply provide an array of states in the from attribute of an event. However, if an event is allowed from multiple states, but should transition to a different state depending on the current state, then provide multiple event entries with the same name:

machine = require "statemachine"

local fsm = machine.create({
  initial = 'hungry',
  events = {
    { name = 'eat',  from = 'hungry',                                to = 'satisfied' },
    { name = 'eat',  from = 'satisfied',                             to = 'full'      },
    { name = 'eat',  from = 'full',                                  to = 'sick'      },
    { name = 'rest', from = {'hungry', 'satisfied', 'full', 'sick'}, to = 'hungry'    },
}})

This example will create an object with 2 event methods:

• fsm:eat()
• fsm:rest()

The rest event will always transition to the hungry state, while the eat event will transition to a state that is dependent on the current state.

NOTE: The rest event could use a wildcard '*' for the 'from' state if it should be allowed from any current state.

NOTE: The rest event in the above example can also be specified as multiple events with the same name if you prefer the verbose approach.

Callbacks

4 callbacks are available if your state machine has methods using the following naming conventions:

• onbeforeevent - fired before the event
• onleavestate - fired when leaving the old state
• onenterstate - fired when entering the new state
• onafterevent - fired after the event

You can affect the event in 3 ways:

• return false from an onbeforeevent handler to cancel the event.
• return false from an onleavestate handler to cancel the event.
• return ASYNC from an onleavestate or onenterstate handler to perform an asynchronous state transition (see next section)

For convenience, the 2 most useful callbacks can be shortened:

• onevent - convenience shorthand for onafterevent
• onstate - convenience shorthand for onenterstate

In addition, a generic onstatechange() callback can be used to call a single function for all state changes:

All callbacks will be passed the same arguments:

• self
• event name
• from state
• to state
• (followed by any arguments you passed into the original event method)

Callbacks can be specified when the state machine is first created:

machine = require "statemachine"

local fsm = machine.create({
  initial = 'green',
  events = {
    { name = 'warn',  from = 'green',  to = 'yellow' },
    { name = 'panic', from = 'yellow', to = 'red'    },
    { name = 'calm',  from = 'red',    to = 'yellow' },
    { name = 'clear', from = 'yellow', to = 'green'  }
  },
  callbacks = {
    onpanic =  function(self, event, from, to, msg) print('panic! ' .. msg)    end,
    onclear =  function(self, event, from, to, msg) print('thanks to ' .. msg) end,
    ongreen =  function(self, event, from, to)      print('green light')       end,
    onyellow = function(self, event, from, to)      print('yellow light')      end,
    onred =    function(self, event, from, to)      print('red light')         end,
  }
})

fsm:warn()
fsm:panic('killer bees')
fsm:calm()
fsm:clear('sedatives in the honey pots')
...

Additionally, they can be added and removed from the state machine at any time:

fsm.ongreen       = nil
fsm.onyellow      = nil
fsm.onred         = nil
fsm.onstatechange = function(self, event, from, to) print(to) end

or

function fsm:onstatechange(event, from, to) print(to) end

Initialization Options

How the state machine should initialize can depend on your application requirements, so the library provides a number of simple options.

By default, if you dont specify any initial state, the state machine will be in the 'none' state and you would need to provide an event to take it out of this state:

machine = require "statemachine"

local fsm = machine.create({
  events = {
    { name = 'startup', from = 'none',  to = 'green' },
    { name = 'panic',   from = 'green', to = 'red'   },
    { name = 'calm',    from = 'red',   to = 'green' },
}})

print(fsm.current) -- "none"
fsm:startup()
print(fsm.current) -- "green"

If you specify the name of your initial event (as in all the earlier examples), then an implicit startup event will be created for you and fired when the state machine is constructed.

local machine = require "statemachine"

local fsm = machine.create({
  inital = 'green',
  events = {
    { name = 'panic',   from = 'green', to = 'red'   },
    { name = 'calm',    from = 'red',   to = 'green' },
}})
print(fsm.current) -- "green"