FSM Documentation

Moose Development/Moose/Core/Fsm.lua

@@ -11,12 +11,40 @@
 -- # 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.
 -- 
+--    * 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.
 -- 
--- 1.1) Add or remove objects from the FSM
--- --------------------------------------------
+--    ![Test Image](../Presentations/MOOSE - FSM - 1. Concepts/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,  
+-- 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 catch State moments, create methods starting with OnLeave or OnEnter concatenated with the State name.
+--    * To catch 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](../Presentations/MOOSE - FSM - 1. Concepts/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 **FSM:Event()** creates an Event that will be processed **embedded** or immediately.
+--    * The **FSM:__Event( seconds )** creates an Event that will be processed **delayed** over time, waiting x seconds.
+-- 
+--    ![Test Image](../Presentations/MOOSE - FSM - 1. Concepts/Dia5.jpg)
+-- 
+-- 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.
 --
 -- ====
 -- 

docs/Documentation/AI_Balancer.html

@@ -238,7 +238,7 @@ SET_GROUP and additional event parameters provided during the event.</p>
 </td>
 		</tr>
 		<tr>
-		<td class="name" nowrap="nowrap"><a href="##(AI_BALANCER).onenterDestroying">AI_BALANCER:onenterDestroying(SetGroup, AIGroup, Event, From, To)</a></td>
+		<td class="name" nowrap="nowrap"><a href="##(AI_BALANCER).onenterDestroying">AI_BALANCER:onenterDestroying(SetGroup, AIGroup, From, Event, To)</a></td>
 		<td class="summary">
 
 </td>
@@ -250,13 +250,13 @@ SET_GROUP and additional event parameters provided during the event.</p>
 </td>
 		</tr>
 		<tr>
-		<td class="name" nowrap="nowrap"><a href="##(AI_BALANCER).onenterReturning">AI_BALANCER:onenterReturning(SetGroup, AIGroup, Event, From, To)</a></td>
+		<td class="name" nowrap="nowrap"><a href="##(AI_BALANCER).onenterReturning">AI_BALANCER:onenterReturning(SetGroup, AIGroup, From, Event, To)</a></td>
 		<td class="summary">
 
 </td>
 		</tr>
 		<tr>
-		<td class="name" nowrap="nowrap"><a href="##(AI_BALANCER).onenterSpawning">AI_BALANCER:onenterSpawning(SetGroup, ClientName, AIGroup, Event, From, To)</a></td>
+		<td class="name" nowrap="nowrap"><a href="##(AI_BALANCER).onenterSpawning">AI_BALANCER:onenterSpawning(SetGroup, ClientName, AIGroup, From, Event, To)</a></td>
 		<td class="summary">
 
 </td>
@@ -487,7 +487,7 @@ The SET of <a href="Core.Set.html##(SET_AIRBASE)">Core.Set#SET_AIRBASE</a>s to e
 <dt>
 
 <a id="#(AI_BALANCER).onenterDestroying" >
-<strong>AI_BALANCER:onenterDestroying(SetGroup, AIGroup, Event, From, To)</strong>
+<strong>AI_BALANCER:onenterDestroying(SetGroup, AIGroup, From, Event, To)</strong>
 </a>
 </dt>
 <dd>
@@ -508,12 +508,12 @@ The SET of <a href="Core.Set.html##(SET_AIRBASE)">Core.Set#SET_AIRBASE</a>s to e
 				</li>
 				<li>
 				
-<p><code><em> Event </em></code>: </p>
+<p><code><em> From </em></code>: </p>
 
 				</li>
 				<li>
 				
-<p><code><em> From </em></code>: </p>
+<p><code><em> Event </em></code>: </p>
 
 				</li>
 				<li>
@@ -549,7 +549,7 @@ The SET of <a href="Core.Set.html##(SET_AIRBASE)">Core.Set#SET_AIRBASE</a>s to e
 <dt>
 
 <a id="#(AI_BALANCER).onenterReturning" >
-<strong>AI_BALANCER:onenterReturning(SetGroup, AIGroup, Event, From, To)</strong>
+<strong>AI_BALANCER:onenterReturning(SetGroup, AIGroup, From, Event, To)</strong>
 </a>
 </dt>
 <dd>
@@ -570,12 +570,12 @@ The SET of <a href="Core.Set.html##(SET_AIRBASE)">Core.Set#SET_AIRBASE</a>s to e
 				</li>
 				<li>
 				
-<p><code><em> Event </em></code>: </p>
+<p><code><em> From </em></code>: </p>
 
 				</li>
 				<li>
 				
-<p><code><em> From </em></code>: </p>
+<p><code><em> Event </em></code>: </p>
 
 				</li>
 				<li>
@@ -590,7 +590,7 @@ The SET of <a href="Core.Set.html##(SET_AIRBASE)">Core.Set#SET_AIRBASE</a>s to e
 <dt>
 
 <a id="#(AI_BALANCER).onenterSpawning" >
-<strong>AI_BALANCER:onenterSpawning(SetGroup, ClientName, AIGroup, Event, From, To)</strong>
+<strong>AI_BALANCER:onenterSpawning(SetGroup, ClientName, AIGroup, From, Event, To)</strong>
 </a>
 </dt>
 <dd>
@@ -616,12 +616,12 @@ The SET of <a href="Core.Set.html##(SET_AIRBASE)">Core.Set#SET_AIRBASE</a>s to e
 				</li>
 				<li>
 				
-<p><code><em> Event </em></code>: </p>
+<p><code><em> From </em></code>: </p>
 
 				</li>
 				<li>
 				
-<p><code><em> From </em></code>: </p>
+<p><code><em> Event </em></code>: </p>
 
 				</li>
 				<li>

docs/Documentation/Base.html

@@ -225,12 +225,37 @@ The <a href="Core.Event.html##(EVENTDATA)">Core.Event#EVENTDATA</a> structure co
     <li><a href="##(BASE).GetParent">BASE.GetParent</a>: Returns the parent object from the object it is handling, or nil if there is no parent object.</li>
 </ul>
 
-<h1>Future</h1>
-<p>Further methods may be added to BASE whenever there is a need to make "overall" functions available within MOOSE.</p>
+<hr/>
+
+<h1><strong>API CHANGE HISTORY</strong></h1>
+
+<p>The underlying change log documents the API changes. Please read this carefully. The following notation is used:</p>
+
+<ul>
+    <li><strong>Added</strong> parts are expressed in bold type face.</li>
+    <li><em>Removed</em> parts are expressed in italic type face.</li>
+</ul>
+
+<p>YYYY-MM-DD: CLASS:<strong>NewFunction</strong>( Params ) replaces CLASS:<em>OldFunction</em>( Params )
+YYYY-MM-DD: CLASS:<strong>NewFunction( Params )</strong> added</p>
+
+<p>Hereby the change log:</p>
 
 <hr/>
 
-<h3>Author: FlightControl</h3>
+<h1><strong>AUTHORS and CONTRIBUTIONS</strong></h1>
+
+<h3>Contributions:</h3>
+
+<ul>
+    <li>None.</li>
+</ul>
+
+<h3>Authors:</h3>
+
+<ul>
+    <li><strong>FlightControl</strong>: Design &amp; Programming</li>
+</ul>
 
 
 	<h2>Global(s)</h2>

docs/Documentation/Fsm.html

@@ -84,20 +84,99 @@
 	<div id="content">
    <h1>Module <code>Fsm</code></h1>
    
-<p>This module contains the FSM class.</p>
+<p>This module contains the FSM class and derived FSM_ classes.</p>
 
    
+
 <p>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</p>
 
-<p>I've taken the development and enhanced it to make the state machine hierarchical...
+<p>I've taken the development and enhanced it (actually rewrote it) to make the state machine hierarchical...
 It is a fantastic development, this module.</p>
 
 <hr/>
 
-<h1>1) <a href="Workflow.html##(FSM)">Workflow#FSM</a> class, extends <a href="Core.Base.html##(BASE)">Core.Base#BASE</a></h1>
+<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>
+</ul>
+
+<p>   <img src="../Presentations/MOOSE - FSM - 1. Concepts/Dia3.jpg" alt="Test Image"/></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/>
+that will be called by the FSM while executing the transition. <br/>
+These methods define the flow of the FSM process; because in those methods the FSM Internal Events will be fired.</p>
+
+<ul>
+    <li>To catch State moments, create methods starting with OnLeave or OnEnter concatenated with the State name.</li>
+    <li>To catch Event moments, create methods starting with OnBefore or OnAfter concatenated with the Event name.</li>
+</ul>
+
+<p><em>* The OnLeave and OnBefore transition methods may return false to cancel the transition.</em>*</p>
+
+<p>   <img src="../Presentations/MOOSE - FSM - 1. Concepts/Dia4.jpg" alt="Test Image"/></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>
+    <li>The <strong>FSM:Event()</strong> creates an Event that will be processed <strong>embedded</strong> or immediately.</li>
+    <li>The <strong>FSM:__Event( seconds )</strong> creates an Event that will be processed <strong>delayed</strong> over time, waiting x seconds.</li>
+</ul>
+
+<p>   <img src="../Presentations/MOOSE - FSM - 1. Concepts/Dia5.jpg" alt="Test Image"/></p>
+
+<h2>1.1) Define the FSM Rules</h2>
+
+<p>The FSM can be defined by using 3 methods:</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>
+
+<hr/>
+
+<h1><strong>API CHANGE HISTORY</strong></h1>
+
+<p>The underlying change log documents the API changes. Please read this carefully. The following notation is used:</p>
+
+<ul>
+    <li><strong>Added</strong> parts are expressed in bold type face.</li>
+    <li><em>Removed</em> parts are expressed in italic type face.</li>
+</ul>
+
+<p>YYYY-MM-DD: CLASS:<strong>NewFunction</strong>( Params ) replaces CLASS:<em>OldFunction</em>( Params )
+YYYY-MM-DD: CLASS:<strong>NewFunction( Params )</strong> added</p>
+
+<p>Hereby the change log:</p>
+
+<ul>
+    <li>2016-12-18: Released.</li>
+</ul>
+
+<hr/>
+
+<h1><strong>AUTHORS and CONTRIBUTIONS</strong></h1>
+
+<h3>Contributions:</h3>
+
+<ul>
+    <li>None.</li>
+</ul>
+
+<h3>Authors:</h3>
+
+<ul>
+    <li><strong>FlightControl</strong>: Design &amp; Programming</li>
+</ul>
 
-<h2>1.1) Add or remove objects from the FSM</h2>
 
 	<h2>Global(s)</h2>
 	<table class="function_list">

docs/Documentation/Spawn.html

@@ -89,6 +89,7 @@
    
 
 <h1>1) <a href="Functional.Spawn.html##(SPAWN)">Functional.Spawn#SPAWN</a> class, extends <a href="Core.Base.html##(BASE)">Core.Base#BASE</a></h1>
+
 <p>The <a href="##(SPAWN)">#SPAWN</a> class allows to spawn dynamically new groups, based on pre-defined initialization settings, modifying the behaviour when groups are spawned.
 For each group to be spawned, within the mission editor, a group has to be created with the "late activation flag" set. We call this group the <em>"Spawn Template"</em> of the SPAWN object.
 A reference to this Spawn Template needs to be provided when constructing the SPAWN object, by indicating the name of the group within the mission editor in the constructor methods.</p>
@@ -116,6 +117,7 @@ Groups will follow the following naming structure when spawned at run-time:</p>
 </ul>
 
 <h2>1.1) SPAWN construction methods</h2>
+
 <p>Create a new SPAWN object with the <a href="##(SPAWN).New">SPAWN.New</a>() or the <a href="##(SPAWN).NewWithAlias">SPAWN.NewWithAlias</a>() methods:</p>
 
 <ul>
@@ -128,6 +130,7 @@ The initialization methods will modify this list of groups so that when a group
 So in principle, the group list will contain all parameters and configurations after initialization, and when groups get actually spawned, this spawning can be done quickly and efficient.</p>
 
 <h2>1.2) SPAWN initialization methods</h2>
+
 <p>A spawn object will behave differently based on the usage of <strong>initialization</strong> methods, which all start with the <strong>Init</strong> prefix:  </p>
 
 <ul>
@@ -142,6 +145,7 @@ So in principle, the group list will contain all parameters and configurations a
 </ul>
 
 <h2>1.3) SPAWN spawning methods</h2>
+
 <p>Groups can be spawned at different times and methods:</p>
 
 <ul>
@@ -159,6 +163,7 @@ So in principle, the group list will contain all parameters and configurations a
 You can use the <a href="GROUP.html">GROUP</a> object to do further actions with the DCSGroup.</p>
 
 <h2>1.4) Retrieve alive GROUPs spawned by the SPAWN object</h2>
+
 <p>The SPAWN class administers which GROUPS it has reserved (in stock) or has created during mission execution.
 Every time a SPAWN object spawns a new GROUP object, a reference to the GROUP object is added to an internal table of GROUPS.
 SPAWN provides methods to iterate through that internal GROUP object reference table:</p>
@@ -173,6 +178,7 @@ SPAWN provides methods to iterate through that internal GROUP object reference t
 The method <a href="##(SPAWN).GetGroupFromIndex">SPAWN.GetGroupFromIndex</a>() will return the GROUP object reference from the given Index, dead or alive...</p>
 
 <h2>1.5) SPAWN object cleaning</h2>
+
 <p>Sometimes, it will occur during a mission run-time, that ground or especially air objects get damaged, and will while being damged stop their activities, while remaining alive.
 In such cases, the SPAWN object will just sit there and wait until that group gets destroyed, but most of the time it won't, 
 and it may occur that no new groups are or can be spawned as limits are reached.
@@ -184,6 +190,7 @@ This models AI that has succesfully returned to their airbase, to restart their
 Check the <a href="##(SPAWN).InitCleanUp">SPAWN.InitCleanUp</a>() for further info.</p>
 
 <h2>1.6) Catch the <a href="Group.html">Group</a> spawn event in a callback function!</h2>
+
 <p>When using the SpawnScheduled method, new <a href="Group.html">Group</a>s are created following the schedule timing parameters.
 When a new <a href="Group.html">Group</a> is spawned, you maybe want to execute actions with that group spawned at the spawn event.
 To SPAWN class supports this functionality through the <a href="##(SPAWN).OnSpawnGroup">SPAWN.OnSpawnGroup</a>( <em>*function( SpawnedGroup ) end *</em> ) method, which takes a function as a parameter that you can define locally. 
@@ -297,7 +304,7 @@ A coding example is provided at the description of the <a href="##(SPAWN).OnSpaw
 
 <hr/>
 
-<h1>AUTHORS and CONTRIBUTIONS</h1>
+<h1><strong>AUTHORS and CONTRIBUTIONS</strong></h1>
 
 <h3>Contributions:</h3>
 
@@ -312,7 +319,6 @@ A coding example is provided at the description of the <a href="##(SPAWN).OnSpaw
 </ul>
 
 
-
 	<h2>Global(s)</h2>
 	<table class="function_list">
 		<tr>
@@ -2496,7 +2502,7 @@ Spawn_BE_KA50 = SPAWN:New( 'BE KA-50@RAMP-Ground Defense' ):Schedule( 600, 0.5 )
 
 
 	
-<p> When the first Spawn executes, all the Groups need to be made visible before start.</p>
+<p> Flag that indicates if all the Groups of the SpawnGroup need to be visible when Spawned.</p>
 
 </dd>
 </dl>

docs/Documentation/index.html

@@ -255,7 +255,7 @@
 			<tr>
 			<td class="name" nowrap="nowrap"><a href="Fsm.html">Fsm</a></td>
 			<td class="summary">
-<p>This module contains the FSM class.</p>
+<p>This module contains the FSM class and derived FSM_ classes.</p>
 </td>
 			</tr>
 			<tr>