FSM documentation

This commit is contained in:
FlightControl 2017-01-04 11:13:49 +01:00
parent 6bd4442d84
commit f79539965f
8 changed files with 171 additions and 50 deletions

View File

@ -8,14 +8,18 @@
--
-- ===
--
-- ![Banner Image](..\Presentations\FSM\Dia1.jpg)
--
-- # 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.
-- * An **Event** describes an action, that can be triggered both internally as externally in the FSM.
--
-- ![Test Image](..\Presentations\FSM\Dia1.jpg)
-- ## 1.1) Event Handling
--
-- ![Event Handlers](..\Presentations\FSM\Dia3.jpg)
--
-- 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,
@ -27,24 +31,33 @@
--
-- ** The OnLeave and OnBefore transition methods may return false to cancel the transition.**
--
-- ![Test Image](..\Presentations\FSM\Dia3.jpg)
-- ## 1.2) Event Triggers
--
-- The FSM creates for each Event **two Event trigger methods**.
-- ![Event Triggers](..\Presentations\FSM\Dia4.jpg)
--
-- 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](..\Presentations\FSM\Dia4.jpg)
-- ## 1.3) FSM Transition Rules
--
-- 1.1) Define the FSM Rules
-- -------------------------
-- The FSM has transition rules that it follows and validates, as it walks the process.
-- These rules define when an FSM can transition from a specific state towards an other specific state upon a triggered event.
--
-- The FSM can be defined by using 3 methods:
-- The method @{#FSM.AddTransition}() specifies a new possible Transition Rule for the FSM.
--
-- * @{#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.
-- The initial state can be defined using the method @{#FSM.SetStartState}(). The default start state of an FSM is "None".
--
-- ## 1.4) FSM Process Rules
--
-- The FSM can implement sub-processes that will execute and return multiple possible states.
-- Depending upon which state is returned, the main FSM can continue tiggering different events.
--
-- The method @{#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.
--
-- ====
--
@ -115,6 +128,9 @@ do -- FSM
end
--- Sets the start state of the FSM.
-- @param #FSM self
-- @param #string State A string defining the start state.
function FSM:SetStartState( State )
self._StartState = State
@ -122,11 +138,20 @@ do -- FSM
end
--- Returns the start state of the FSM.
-- @param #FSM self
-- @return #string A string containing the start state.
function FSM:GetStartState()
return self._StartState or {}
end
--- Add a new transition rule to the FSM.
-- A transition rule defines when and if the FSM can transition from a state towards another state upon a triggered event.
-- @param #FSM self
-- @param #table From Can contain a string indicating the From state or a table of strings containing multiple From states.
-- @param #string Event The Event name.
-- @param #string To The To state.
function FSM:AddTransition( From, Event, To )
local Transition = {}
@ -139,14 +164,22 @@ do -- FSM
self._Transitions[Transition] = Transition
self:_eventmap( self.Events, Transition )
end
--- Returns a table of the transition rules defined within the FSM.
-- @return #table
function FSM:GetTransitions()
return self._Transitions or {}
end
--- 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.
-- @return Core.Fsm#FSM_PROCESS
-- @param #FSM self
-- @param #table From Can contain a string indicating the From state or a table of strings containing multiple From states.
-- @param #string Event The Event name.
-- @param Core.Fsm#FSM_PROCESS Process An sub-process FSM.
-- @param #table ReturnEvents A table indicating for which returned events of the SubFSM which Event must be triggered in the FSM.
-- @return Core.Fsm#FSM_PROCESS The SubFSM.
function FSM:AddProcess( From, Event, Process, ReturnEvents )
self:E( { From, Event, Process, ReturnEvents } )
@ -166,6 +199,9 @@ do -- FSM
return Process
end
--- Returns a table of the SubFSM rules defined within the FSM.
-- @return #table
function FSM:GetProcesses()
return self._Processes or {}
@ -183,12 +219,14 @@ do -- FSM
error( "Sub-Process from state " .. From .. " with event " .. Event .. " not found!" )
end
--- Adds an End state.
function FSM:AddEndState( State )
self._EndStates[State] = State
self.endstates[State] = State
end
--- Returns the End states.
function FSM:GetEndStates()
return self._EndStates or {}
@ -232,12 +270,13 @@ do -- FSM
return Process
end
--- Returns a table with the scores defined.
function FSM:GetScores()
return self._Scores or {}
end
--- Returns a table with the Subs defined.
function FSM:GetSubs()
return self.options.subs

View File

@ -2411,6 +2411,7 @@ The UNIT carrying the package.</p>
<dl class="function">
<dt>
<em></em>
<a id="#(AI_CARGO_UNIT).CargoCarrier" >
<strong>AI_CARGO_UNIT.CargoCarrier</strong>
</a>

View File

@ -80,16 +80,20 @@ It is a fantastic development, this module.</p>
<hr/>
<p><img src="..\Presentations\FSM\Dia1.jpg" alt="Banner Image"/></p>
<h1>1) <a href="Core.Fsm.html##(FSM)">Core.Fsm#FSM</a> class, extends <a href="Core.Base.html##(BASE)">Core.Base#BASE</a></h1>
<p>A Finite State Machine (FSM) defines the rules of transitioning between various States triggered by Events.</p>
<ul>
<li>A <strong>State</strong> defines a moment in the process.</li>
<li>An <strong>Event</strong> describes an action, that can be triggered both internally as externally in the FSM. An Event can be triggered Embedded or Delayed over time.</li>
<li>An <strong>Event</strong> describes an action, that can be triggered both internally as externally in the FSM. </li>
</ul>
<p><img src="..\Presentations\FSM\Dia1.jpg" alt="Test Image"/></p>
<h2>1.1) Event Handling</h2>
<p><img src="..\Presentations\FSM\Dia3.jpg" alt="Event Handlers"/></p>
<p>An FSM transitions in <strong>4 moments</strong> when an Event is being handled. <br/>
Each moment can be catched by handling methods defined by the mission designer, <br/>
@ -103,9 +107,11 @@ These methods define the flow of the FSM process; because in those methods the F
<p><em>* The OnLeave and OnBefore transition methods may return false to cancel the transition.</em>*</p>
<p> <img src="..\Presentations\FSM\Dia3.jpg" alt="Test Image"/></p>
<h2>1.2) Event Triggers</h2>
<p>The FSM creates for each Event <strong>two Event trigger methods</strong>. <br/>
<p><img src="..\Presentations\FSM\Dia4.jpg" alt="Event Triggers"/></p>
<p>The FSM creates for each Event <strong>two Event Trigger methods</strong>. <br/>
There are two modes how Events can be triggered, which is <strong>embedded</strong> and <strong>delayed</strong>:</p>
<ul>
@ -113,17 +119,23 @@ There are two modes how Events can be triggered, which is <strong>embedded</stro
<li>The method <strong>FSM:__Event( seconds )</strong> triggers an Event that will be processed <strong>delayed</strong> over time, waiting x seconds.</li>
</ul>
<p> <img src="..\Presentations\FSM\Dia4.jpg" alt="Test Image"/></p>
<h2>1.3) FSM Transition Rules</h2>
<h2>1.1) Define the FSM Rules</h2>
<p>The FSM has transition rules that it follows and validates, as it walks the process.
These rules define when an FSM can transition from a specific state towards an other specific state upon a triggered event.</p>
<p>The FSM can be defined by using 3 methods:</p>
<p>The method <a href="##(FSM).AddTransition">FSM.AddTransition</a>() specifies a new possible Transition Rule for the FSM. </p>
<ul>
<li><a href="##(FSM).SetStartState">FSM.SetStartState</a>(): Define the <strong>Start State</strong> of the FSM. This is the State the FSM will have when nothing is processed yet.</li>
<li><a href="##(FSM).AddTransition">FSM.AddTransition</a>(): Adds a new possible Transition Rule to the FSM. A Transition will change the State of the FSM upon the defined triggered Event.</li>
<li><a href="##(FSM).AddProcess">FSM.AddProcess</a>(): 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.</li>
</ul>
<p>The initial state can be defined using the method <a href="##(FSM).SetStartState">FSM.SetStartState</a>(). The default start state of an FSM is "None".</p>
<h2>1.4) FSM Process Rules</h2>
<p>The FSM can implement sub-processes that will execute and return multiple possible states. <br/>
Depending upon which state is returned, the main FSM can continue tiggering different events.</p>
<p>The method <a href="##(FSM).AddProcess">FSM.AddProcess</a>() adds a new Sub-Process FSM to the FSM. <br/>
A Sub-Process will start the Sub-Process of the FSM upon the defined triggered Event,
with multiple possible States as a result.</p>
<hr/>
@ -200,7 +212,7 @@ YYYY-MM-DD: CLASS:<strong>NewFunction( Params )</strong> added</p>
<tr>
<td class="name" nowrap="nowrap"><a href="##(FSM).AddEndState">FSM:AddEndState(State)</a></td>
<td class="summary">
<p>Adds an End state.</p>
</td>
</tr>
<tr>
@ -224,7 +236,7 @@ YYYY-MM-DD: CLASS:<strong>NewFunction( Params )</strong> added</p>
<tr>
<td class="name" nowrap="nowrap"><a href="##(FSM).AddTransition">FSM:AddTransition(From, Event, To)</a></td>
<td class="summary">
<p>Add a new transition rule to the FSM.</p>
</td>
</tr>
<tr>
@ -236,7 +248,7 @@ YYYY-MM-DD: CLASS:<strong>NewFunction( Params )</strong> added</p>
<tr>
<td class="name" nowrap="nowrap"><a href="##(FSM).GetEndStates">FSM:GetEndStates()</a></td>
<td class="summary">
<p>Returns the End states.</p>
</td>
</tr>
<tr>
@ -248,19 +260,19 @@ YYYY-MM-DD: CLASS:<strong>NewFunction( Params )</strong> added</p>
<tr>
<td class="name" nowrap="nowrap"><a href="##(FSM).GetProcesses">FSM:GetProcesses()</a></td>
<td class="summary">
<p>Returns a table of the SubFSM rules defined within the FSM.</p>
</td>
</tr>
<tr>
<td class="name" nowrap="nowrap"><a href="##(FSM).GetScores">FSM:GetScores()</a></td>
<td class="summary">
<p>Returns a table with the scores defined.</p>
</td>
</tr>
<tr>
<td class="name" nowrap="nowrap"><a href="##(FSM).GetStartState">FSM:GetStartState()</a></td>
<td class="summary">
<p>Returns the start state of the FSM.</p>
</td>
</tr>
<tr>
@ -272,13 +284,13 @@ YYYY-MM-DD: CLASS:<strong>NewFunction( Params )</strong> added</p>
<tr>
<td class="name" nowrap="nowrap"><a href="##(FSM).GetSubs">FSM:GetSubs()</a></td>
<td class="summary">
<p>Returns a table with the Subs defined.</p>
</td>
</tr>
<tr>
<td class="name" nowrap="nowrap"><a href="##(FSM).GetTransitions">FSM:GetTransitions()</a></td>
<td class="summary">
<p>Returns a table of the transition rules defined within the FSM.</p>
</td>
</tr>
<tr>
@ -302,6 +314,12 @@ YYYY-MM-DD: CLASS:<strong>NewFunction( Params )</strong> added</p>
<tr>
<td class="name" nowrap="nowrap"><a href="##(FSM).SetStartState">FSM:SetStartState(State)</a></td>
<td class="summary">
<p>Sets the start state of the FSM.</p>
</td>
</tr>
<tr>
<td class="name" nowrap="nowrap"><a href="##(FSM)._StartState">FSM._StartState</a></td>
<td class="summary">
</td>
</tr>
@ -369,6 +387,12 @@ YYYY-MM-DD: CLASS:<strong>NewFunction( Params )</strong> added</p>
<td class="name" nowrap="nowrap"><a href="##(FSM).cannot">FSM:cannot(e)</a></td>
<td class="summary">
</td>
</tr>
<tr>
<td class="name" nowrap="nowrap"><a href="##(FSM).current">FSM.current</a></td>
<td class="summary">
</td>
</tr>
<tr>
@ -668,7 +692,7 @@ YYYY-MM-DD: CLASS:<strong>NewFunction( Params )</strong> added</p>
</dt>
<dd>
<p>Adds an End state.</p>
<h3>Parameter</h3>
<ul>
@ -695,29 +719,33 @@ YYYY-MM-DD: CLASS:<strong>NewFunction( Params )</strong> added</p>
<ul>
<li>
<p><code><em> From </em></code>: </p>
<p><code><em>#table From </em></code>:
Can contain a string indicating the From state or a table of strings containing multiple From states.</p>
</li>
<li>
<p><code><em> Event </em></code>: </p>
<p><code><em>#string Event </em></code>:
The Event name.</p>
</li>
<li>
<p><code><em> Process </em></code>: </p>
<p><code><em><a href="Core.Fsm.html##(FSM_PROCESS)">Core.Fsm#FSM_PROCESS</a> Process </em></code>:
An sub-process FSM.</p>
</li>
<li>
<p><code><em> ReturnEvents </em></code>: </p>
<p><code><em>#table ReturnEvents </em></code>:
A table indicating for which returned events of the SubFSM which Event must be triggered in the FSM.</p>
</li>
</ul>
<h3>Return value</h3>
<p><em><a href="Core.Fsm.html##(FSM_PROCESS)">Core.Fsm#FSM_PROCESS</a>:</em></p>
<p><em><a href="Core.Fsm.html##(FSM_PROCESS)">Core.Fsm#FSM_PROCESS</a>:</em>
The SubFSM.</p>
</dd>
</dl>
@ -820,23 +848,29 @@ self</p>
</dt>
<dd>
<p>Add a new transition rule to the FSM.</p>
<p>A transition rule defines when and if the FSM can transition from a state towards another state upon a triggered event.</p>
<h3>Parameters</h3>
<ul>
<li>
<p><code><em> From </em></code>: </p>
<p><code><em>#table From </em></code>:
Can contain a string indicating the From state or a table of strings containing multiple From states.</p>
</li>
<li>
<p><code><em> Event </em></code>: </p>
<p><code><em>#string Event </em></code>:
The Event name.</p>
</li>
<li>
<p><code><em> To </em></code>: </p>
<p><code><em>#string To </em></code>:
The To state.</p>
</li>
</ul>
@ -865,7 +899,7 @@ self</p>
</dt>
<dd>
<p>Returns the End states.</p>
</dd>
</dl>
@ -904,6 +938,11 @@ self</p>
</dt>
<dd>
<p>Returns a table of the SubFSM rules defined within the FSM.</p>
<h3>Return value</h3>
<p><em>#table:</em></p>
</dd>
@ -917,7 +956,7 @@ self</p>
</dt>
<dd>
<p>Returns a table with the scores defined.</p>
</dd>
</dl>
@ -930,7 +969,12 @@ self</p>
</dt>
<dd>
<p>Returns the start state of the FSM.</p>
<h3>Return value</h3>
<p><em>#string:</em>
A string containing the start state.</p>
</dd>
</dl>
@ -956,7 +1000,7 @@ self</p>
</dt>
<dd>
<p>Returns a table with the Subs defined.</p>
</dd>
</dl>
@ -969,6 +1013,11 @@ self</p>
</dt>
<dd>
<p>Returns a table of the transition rules defined within the FSM.</p>
<h3>Return value</h3>
<p><em>#table:</em></p>
</dd>
@ -1050,16 +1099,31 @@ self</p>
</dt>
<dd>
<p>Sets the start state of the FSM.</p>
<h3>Parameter</h3>
<ul>
<li>
<p><code><em> State </em></code>: </p>
<p><code><em>#string State </em></code>:
A string defining the start state.</p>
</li>
</ul>
</dd>
</dl>
<dl class="function">
<dt>
<em></em>
<a id="#(FSM)._StartState" >
<strong>FSM._StartState</strong>
</a>
</dt>
<dd>
</dd>
</dl>
<dl class="function">
@ -1326,6 +1390,20 @@ self</p>
</li>
</ul>
</dd>
</dl>
<dl class="function">
<dt>
<em></em>
<a id="#(FSM).current" >
<strong>FSM.current</strong>
</a>
</dt>
<dd>
</dd>
</dl>
<dl class="function">

View File

@ -1692,6 +1692,9 @@ The group that was spawned. You can use this group for further actions.</p>
<p> Don't repeat the group from Take-Off till Landing and back Take-Off by ReSpawning.</p>
</dd>
</dl>
<dl class="function">
@ -2166,7 +2169,7 @@ when nothing was spawned.</p>
<dl class="function">
<dt>
<em></em>
<em>#number</em>
<a id="#(SPAWN).SpawnMaxGroups" >
<strong>SPAWN.SpawnMaxGroups</strong>
</a>
@ -2183,7 +2186,7 @@ when nothing was spawned.</p>
<dl class="function">
<dt>
<em></em>
<em>#number</em>
<a id="#(SPAWN).SpawnMaxUnitsAlive" >
<strong>SPAWN.SpawnMaxUnitsAlive</strong>
</a>

Binary file not shown.

Before

Width:  |  Height:  |  Size: 182 KiB

After

Width:  |  Height:  |  Size: 76 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 220 KiB

After

Width:  |  Height:  |  Size: 103 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 195 KiB

After

Width:  |  Height:  |  Size: 85 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 191 KiB

After

Width:  |  Height:  |  Size: 83 KiB