Module `Fsm`

This module contains the FSM class and derived FSM_ classes.

This development is based on a state machine implementation made by Conroy Kyle. The state machine can be found here: https://github.com/kyleconroy/lua-state-machine

I've taken the development and enhanced it (actually rewrote it) to make the state machine hierarchical... It is a fantastic development, this module.

1) Core.Fsm#FSM class, extends Core.Base#BASE

A Finite State Machine (FSM) defines the rules of transitioning between various States triggered by Events.

A State defines a moment in the process.
An Event describes an action, that can be triggered both internally as externally in the FSM. An Event can be triggered Embedded or Delayed over time.

Test Image

An FSM transitions in 4 moments when an Event is being handled.
Each moment can be catched by handling methods defined by the mission designer,
that will be called by the FSM while executing the transition.
These methods define the flow of the FSM process; because in those methods the FSM Internal Events will be fired.

To handle State moments, create methods starting with OnLeave or OnEnter concatenated with the State name.
To handle Event moments, create methods starting with OnBefore or OnAfter concatenated with the Event name.

* The OnLeave and OnBefore transition methods may return false to cancel the transition.*

Test Image

The FSM creates for each Event two Event trigger methods.
There are two modes how Events can be triggered, which is embedded and delayed:

The method FSM:Event() triggers an Event that will be processed embedded or immediately.
The method FSM:__Event( seconds ) triggers an Event that will be processed delayed over time, waiting x seconds.

Test Image

1.1) Define the FSM Rules

The FSM can be defined by using 3 methods:

FSM.SetStartState(): Define the Start State of the FSM. This is the State the FSM will have when nothing is processed yet.
FSM.AddTransition(): Adds a new possible Transition Rule to the FSM. A Transition will change the State of the FSM upon the defined triggered Event.
FSM.AddProcess(): Adds a new Sub-Process FSM to the FSM. A Sub-Process will start the Sub-Process of the FSM upon the defined triggered Event, with multiple possible States as a result.

API CHANGE HISTORY

The underlying change log documents the API changes. Please read this carefully. The following notation is used:

Added parts are expressed in bold type face.
Removed parts are expressed in italic type face.

YYYY-MM-DD: CLASS:NewFunction( Params ) replaces CLASS:OldFunction( Params ) YYYY-MM-DD: CLASS:NewFunction( Params ) added

Hereby the change log:

2016-12-18: Released.

AUTHORS and CONTRIBUTIONS

Contributions:

None.

Authors:

FlightControl: Design & Programming

Global(s)

FSM
FSM_CONTROLLABLE
FSM_PROCESS
FSM_SET
FSM_TASK

Type `FSM`

FSM:AddEndState(State)
FSM:AddProcess(From, Event, Process, ReturnEvents)	Set the default Process template with key ProcessName providing the ProcessClass and the process object when it is assigned to a Controllable by the task.
FSM:AddScore(State, ScoreText, Score)	Adds a score for the FSM to be achieved.
FSM:AddScoreProcess(From, Event, State, ScoreText, Score)	Adds a score for the FSM_PROCESS to be achieved.
FSM:AddTransition(From, Event, To)
FSM.ClassName
FSM:GetEndStates()
FSM:GetProcess(From, Event)
FSM:GetProcesses()
FSM:GetScores()
FSM:GetStartState()
FSM:GetState()
FSM:GetSubs()
FSM:GetTransitions()
FSM:Is(State)
FSM:LoadCallBacks(CallBackTable)
FSM:New(FsmT)	Creates a new FSM object.
FSM:SetStartState(State)
FSM:_add_to_map(Map, Event)
FSM:_call_handler(handler, params)
FSM:_create_transition(EventName)
FSM:_delayed_transition(EventName)
FSM:_eventmap(Events, EventStructure)
FSM:_gosub(ParentFrom, ParentEvent)
FSM:_handler(EventName, ...)
FSM:_isendstate(Current)
FSM:_submap(subs, sub, name)
FSM:can(e)
FSM:cannot(e)
FSM:is(state)

Type `FSM_CONTROLLABLE`

FSM_CONTROLLABLE.ClassName
FSM_CONTROLLABLE.Controllable
FSM_CONTROLLABLE:GetControllable()	Gets the CONTROLLABLE object that the FSM_CONTROLLABLE governs.
FSM_CONTROLLABLE:New(FSMT, Controllable)	Creates a new FSM_CONTROLLABLE object.
FSM_CONTROLLABLE:SetControllable(FSMControllable)	Sets the CONTROLLABLE object that the FSM_CONTROLLABLE governs.
FSM_CONTROLLABLE:_call_handler(handler, params)

Type `FSM_PROCESS`

FSM_PROCESS:AddScore(State, ScoreText, Score)	Adds a score for the FSM_PROCESS to be achieved.
FSM_PROCESS:Assign(Task, ProcessUnit)	Assign the process to a Unit and activate the process.
FSM_PROCESS.ClassName
FSM_PROCESS:Copy(Controllable, Task)	Creates a new FSMPROCESS object based on this FSMPROCESS.
FSM_PROCESS:GetCommandCenter()	Gets the mission of the process.
FSM_PROCESS:GetMission()	Gets the mission of the process.
FSM_PROCESS:GetTask()	Gets the task of the process.
FSM_PROCESS:Init(FsmProcess)
FSM_PROCESS:Message(Message)	Send a message of the Task to the Group of the Unit.
FSM_PROCESS:New(Controllable, Task)	Creates a new FSM_PROCESS object.
FSM_PROCESS:SetTask(Task)	Sets the task of the process.
FSM_PROCESS.Task
FSM_PROCESS:onenterAssigned(ProcessUnit)
FSM_PROCESS:onenterFailed(ProcessUnit)
FSM_PROCESS:onenterSuccess(ProcessUnit)
FSM_PROCESS:onstatechange(ProcessUnit, Event, From, To, Dummy)	StateMachine callback function for a FSM_PROCESS

Type `FSM_SET`

FSM_SET.ClassName
FSM_SET:Get()	Gets the SETBASE object that the FSMSET governs.
FSM_SET:New(FSMT, Set_SET_BASE, FSMSet)	Creates a new FSM_SET object.
FSM_SET.Set
FSM_SET:_call_handler(handler, params)

Type `FSM_TASK`

FSM_TASK.ClassName
FSM_TASK:New(FSMT, Task, TaskUnit)	Creates a new FSM_TASK object.
FSM_TASK.Task
FSM_TASK:_call_handler(handler, params)

Global(s)

#FSM FSM

#FSM_CONTROLLABLE FSM_CONTROLLABLE

#FSM_PROCESS FSM_PROCESS

#FSM_SET FSM_SET

#FSM_TASK FSM_TASK

Type `Fsm`

Type `FSM`

FSM class

Field(s)

FSM:AddEndState(State)

Parameter

State :

FSM:AddProcess(From, Event, Process, ReturnEvents)

Set the default Process template with key ProcessName providing the ProcessClass and the process object when it is assigned to a Controllable by the task.

Parameters

From :
Event :
Process :
ReturnEvents :

Return value

Core.Fsm#FSM_PROCESS:

FSM:AddScore(State, ScoreText, Score)

Adds a score for the FSM to be achieved.

Parameters

#string State : is the state of the process when the score needs to be given. (See the relevant state descriptions of the process).
#string ScoreText : is a text describing the score that is given according the status.
#number Score : is a number providing the score of the status.

Return value

#FSM: self

FSM:AddScoreProcess(From, Event, State, ScoreText, Score)

Adds a score for the FSM_PROCESS to be achieved.

Parameters

#string From : is the From State of the main process.
#string Event : is the Event of the main process.
#string State : is the state of the process when the score needs to be given. (See the relevant state descriptions of the process).
#string ScoreText : is a text describing the score that is given according the status.
#number Score : is a number providing the score of the status.

Return value

#FSM: self

FSM:AddTransition(From, Event, To)

Parameters

From :
Event :
To :

#string FSM.ClassName

FSM:GetEndStates()

FSM:GetProcess(From, Event)

Parameters

From :
Event :

FSM:GetProcesses()

FSM:GetScores()

FSM:GetStartState()

FSM:GetState()

FSM:GetSubs()

FSM:GetTransitions()

FSM:Is(State)

Parameter

State :

FSM:LoadCallBacks(CallBackTable)

Parameter

CallBackTable :

FSM:New(FsmT)

Creates a new FSM object.

Parameter

FsmT :

Return value

#FSM:

FSM:SetStartState(State)

Parameter

State :

FSM:_add_to_map(Map, Event)

Parameters

Map :
Event :

FSM:_call_handler(handler, params)

Parameters

handler :
params :

FSM:_create_transition(EventName)

Parameter

EventName :

FSM:_delayed_transition(EventName)

Parameter

EventName :

FSM:_eventmap(Events, EventStructure)

Parameters

Events :
EventStructure :

FSM:_gosub(ParentFrom, ParentEvent)

Parameters

ParentFrom :
ParentEvent :

FSM:_handler(EventName, ...)

Parameters

EventName :
... :

FSM:_isendstate(Current)

Parameter

Current :

FSM:_submap(subs, sub, name)

Parameters

subs :
sub :
name :

FSM:can(e)

Parameter

e :

FSM:cannot(e)

Parameter

e :

FSM:is(state)

Parameter

state :

Type `FSM_CONTROLLABLE`

FSM_CONTROLLABLE class

Field(s)

#string FSM_CONTROLLABLE.ClassName

Wrapper.Controllable#CONTROLLABLE FSM_CONTROLLABLE.Controllable

FSM_CONTROLLABLE:GetControllable()

Gets the CONTROLLABLE object that the FSM_CONTROLLABLE governs.

Return value

Wrapper.Controllable#CONTROLLABLE:

FSM_CONTROLLABLE:New(FSMT, Controllable)

Creates a new FSM_CONTROLLABLE object.

Parameters

#table FSMT : Finite State Machine Table
Wrapper.Controllable#CONTROLLABLE Controllable : (optional) The CONTROLLABLE object that the FSM_CONTROLLABLE governs.

Return value

#FSM_CONTROLLABLE:

FSM_CONTROLLABLE:SetControllable(FSMControllable)

Sets the CONTROLLABLE object that the FSM_CONTROLLABLE governs.

Parameter

Wrapper.Controllable#CONTROLLABLE FSMControllable :

Return value

#FSM_CONTROLLABLE:

FSM_CONTROLLABLE:_call_handler(handler, params)

Parameters

handler :
params :

Type `FSM_PROCESS`

FSM_PROCESS class

Field(s)

FSM_PROCESS:AddScore(State, ScoreText, Score)

Adds a score for the FSM_PROCESS to be achieved.

Parameters

#string State : is the state of the process when the score needs to be given. (See the relevant state descriptions of the process).
#string ScoreText : is a text describing the score that is given according the status.
#number Score : is a number providing the score of the status.