fsm
(For high level concepts about how to use Lua to write scripted tasks, please see VR-Forces User's Guide.)
A design pattern for doing finite state machines (FSMs) in Lua.
==========================================================================================
Finite State Machine Class for Lua 5.1 & Corona SDK
Written by Erik Cornelisse, inspired by Luiz Henrique de Figueiredo
E-mail: e.cornelisse@gmail.com
Version 1.0 April 27, 2011
Class is MIT Licensed
Copyright (c) 2011 Erik Cornelisse
Feel free to change but please send new versions, improvements or
new features to me and help us to make it better.
==========================================================================================
The FSM is described with: old_state, event, new_state and action.
The general approach to supporting FSMs is to create a table stt with
(state, event) pairs as the keys and (new, action) pairs as the values.
Stt is a single-dimension array, constructed as stt[state .. SEPARATOR .. event]
where SEPARATOR is a constant and defined as '.'
There are three special state transitions:
- any state but a specific event
- any event but a specific state
- unknown state-event combination to be used for exception handling
The any state and event are defined by the ANY constant, defined as '*'
The unknown state-event is defined as the combination of ANY.ANY (*.*)
A default exception handler for unknown state-event combinations is
provided and therefore a specification a your own exception handling is
optional.
After creating a new FSM, the initial state is set to the first defined
state in your state transition table. With add(t) and delete(t), new state
transition can be added and removed later.
A DEBUG-like method called silent is included to prevent wise-guy remarks
about things you shouldn't be doing.
USAGE EXAMPLES:
FSM = require "fsm"
function action1() print("Performing action 1") end
function action2() print("Performing action 2") end
- Define your state transitions here
local myStateTransitionTable = {
{"state1", "event1", "state2", action1},
{"state2", "event2", "state3", action2},
{"*", "event3", "state2", action1}, -- for any state
{"*", "*", "state2", action2} -- exception handler
}
-- Create your finite state machine
fsm = FSM.new(myStateTransitionTable)
-- Use your finite state machine
-- which starts by default with the first defined state
print("Current FSM state: " .. fsm:get())
-- Or you can set another state
fsm:set("state2")
print("Current FSM state: " .. fsm:get())
-- Resond on "event" and last set "state"
fsm:fire("event2")
print("Current FSM state: " .. fsm:get())
Output:
-------
Current FSM state: state1
Current FSM state: state2
Performing action 2
Current FSM state: state3
Function List
| add (t) | Add new state transitions to the FSM |
| delete (t) | Remove state transitions from the FSM. |
| fire (event) | Respond based on current state and event. |
| get () | Get the current state of the state machine. |
| new (t) | Creates a new FSM instance and returns it. |
| set (s) | Sets the current state |
Functions
- add (t)
-
Add new state transitions to the FSM
Parameters:
-
t: The state transitions to add. It should be a table in the form
{{state, event, newstate, action},...}
where state, event, and newstate are names (strings), and action is a function.
Return value:
- The size of t (the number of transition additions requested).
-
- delete (t)
-
Remove state transitions from the FSM.
Parameters:
-
t: The transitions to delete. It should be a table in the form
{{state, event},...}
Return value:
- The size of t (the number of deletions requested).
-
- fire (event)
-
Respond based on current state and event.
Parameters:
-
event: The event name (string), as defined in the initial state transition table.
Return value:
- The result of the action function associated with the transition.
-
- get ()
-
Get the current state of the state machine.
Return value:
- The current state string.
- new (t)
-
Creates a new FSM instance and returns it.
Parameters:
-
t: The state transition table that defines this FSM. This table has the form {
{state, event, newstate, action}
}
Where state, event, and newstate are strings, and action is a function that takes no arguments.
Usage:
FSM = require "fsm"
myStt = {{"s1", "event1","s2", function() print("event 1") end}
{"s2", "*", "s2", function () vrf:endTask(true) end} }
myFsm = FSM.new(myStt)
myFsm:fire("event1") --transition to state "s2"
Return value:
- A table defining the FSM. Use the FSM methods to set states, add or remove transitions, and fire events.
-
- set (s)
-
Sets the current state
Parameters:
-
s: The new state name to become the current state. Must be a state definined in the initail state transition table.
-