FSM documentation

Moose Development/Moose/Core/Fsm.lua

@@ -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.
+-- The initial state can be defined using the method @{#FSM.SetStartState}(). The default start state of an FSM is "None".
---    * @{#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.
+-- ## 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

docs/Documentation/Cargo.html

@@ -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>

docs/Documentation/Fsm.html

@@ -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>
+<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>
-    <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>
+<h2>1.4) FSM Process Rules</h2>
-    <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 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">

docs/Documentation/Spawn.html

@@ -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>