FSM Updates

Moose Development/Moose/Core/Fsm.lua

@@ -73,7 +73,7 @@
 -- ## 1.1) FSM Linear Transitions
 -- 
 -- Linear Transitions are Transition Rules allowing an FSM to transition from one or multiple possible **From** state(s) towards a **To** state upon a Triggered **Event**.
--- The Lineair transition rule evaluation will always be done from the **current state* of the FSM.
+-- The Lineair transition rule evaluation will always be done from the **current state** of the FSM.
 -- If no valid Transition Rule can be found in the FSM, the FSM will log an error and stop.
 -- 
 -- ### 1.1.1) FSM Transition Rules
@@ -85,6 +85,33 @@
 -- 
 -- The initial state can be defined using the method @{#FSM.SetStartState}(). The default start state of an FSM is "None".
 -- 
+-- Find below an example of a Linear Transition Rule definition for an FSM.
+-- 
+--      local Fsm3Switch = FSM:New() -- #FsmDemo
+--      FsmSwitch:SetStartState( "Off" )
+--      FsmSwitch:AddTransition( "Off", "SwitchOn", "On" )
+--      FsmSwitch:AddTransition( "Off", "SwitchMiddle", "Middle" )
+--      FsmSwitch:AddTransition( "On", "SwitchOff", "Off" )
+--      FsmSwitch:AddTransition( "Middle", "SwitchOff", "Off" )
+-- 
+-- The above code snippet models a 3-way switch Linear Transition:
+-- 
+--    * It can be switched **On** by triggering event **SwitchOn**.
+--    * It can be switched to the **Middle** position, by triggering event **SwitchMiddle**.
+--    * It can be switched **Off** by triggering event **SwitchOff**.
+--    * Note that once the Switch is **On** or **Middle**, it can only be switched **Off**.
+-- 
+-- ### Some additional comments:
+-- 
+-- Note that Linear Transition Rules **can be declared in a few variations**:
+-- 
+--    * The From states can be **a table of strings**, indicating that the transition rule will be valid **if the current state** of the FSM will be **one of the given From states**.
+--    * The From state can be a **"*"**, indicating that **the transition rule will always be valid**, regardless of the current state of the FSM.
+--   
+-- The below code snippet shows how the two last lines can be rewritten and consensed.
+-- 
+--      FsmSwitch:AddTransition( { "On",  "Middle" }, "SwitchOff", "Off" )
+-- 
 -- ### 1.1.2) Transition Handling
 -- 
 -- ![Transition Handlers](..\Presentations\FSM\Dia4.JPG)
@@ -105,7 +132,7 @@
 --    * Event = A string containing the Event name that was triggered.
 --    * To = A string containing the To state.
 -- 
--- On top, each of these methods can have a variable amount of parameters passed. See the example in section 1.3.
+-- On top, each of these methods can have a variable amount of parameters passed. See the example in section [1.1.3](#1.1.3\)-event-triggers).
 -- 
 -- ### 1.1.3) Event Triggers
 -- 
@@ -145,12 +172,18 @@
 -- 
 -- Because ... When Event was asynchronously processed after 5 seconds, Amount was set to 2. So be careful when processing and passing values and objects in asynchronous processing!
 -- 
--- ### 1.1.4) Linear Transitioning Example
+-- ### 1.1.4) Linear Transition Example
 -- 
--- This example creates a new FsmDemo object from class FSM.
+-- This example is fully implemented in the MOOSE test mission on GITHUB: [FSM-100 - Transition Explanation](https://github.com/FlightControl-Master/MOOSE/blob/master/Moose%20Test%20Missions/FSM%20-%20Finite%20State%20Machine/FSM-100%20-%20Transition%20Explanation/FSM-100%20-%20Transition%20Explanation.lua)
--- It will set the start state of FsmDemo to Green.
+-- 
--- Two Transition Rules are created, where upon the event Switch,
+-- It models a unit standing still near Batumi, and flaring every 5 seconds while switching between a Green flare and a Red flare.
--- the FsmDemo will transition from state Green to Red and vise versa.
+-- The purpose of this example is not to show how exciting flaring is, but it demonstrates how a Linear Transition FSM can be build.
+-- Have a look at the source code. The source code is also further explained below in this section.
+-- 
+-- The example creates a new FsmDemo object from class FSM.
+-- It will set the start state of FsmDemo to state **Green**.
+-- Two Linear Transition Rules are created, where upon the event **Switch**,
+-- the FsmDemo will transition from state **Green** to **Red** and from **Red** back to **Green**.
 -- 
 -- ![Transition Example](..\Presentations\FSM\Dia6.JPG)
 -- 
@@ -204,16 +237,7 @@
 -- 
 --        FsmDemo:__Switch( 5, FsmUnit ) -- Trigger the next Switch event to happen in 5 seconds.
 -- 
--- This example is fully implemented in the MOOSE test mission on GITHUB: [FSM-100 - Transition Explanation](https://github.com/FlightControl-Master/MOOSE/blob/master/Moose%20Test%20Missions/FSM%20-%20Finite%20State%20Machine/FSM-100%20-%20Transition%20Explanation/FSM-100%20-%20Transition%20Explanation.lua)
+-- The below code fragment extends the FsmDemo, demonstrating multiple **From states declared as a table**, adding a **Linear Transition Rule**.
--- 
--- ### Some additional comments:
--- 
--- Note that transition rules **can be declared with a few variations**:
--- 
---   * The From states can be **a table of strings**, indicating that the transition rule will be valid **if the current state** of the FSM will be **one of the given From states**.
---   * The From state can be a **"*"**, indicating that **the transition rule will always be valid**, regardless of the current state of the FSM.
--- 
--- The below code fragment extends the FsmDemo, demonstrating multiple **From states declared as a table**, in an additional transition rule.
 -- The new event **Stop** will cancel the Switching process.
 -- The transition for event Stop can be executed if the current state of the FSM is either "Red" or "Green".
 -- 

docs/Documentation/Cargo.html

@@ -2411,7 +2411,6 @@ 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

@@ -149,7 +149,7 @@ The below documentation has a seperate chapter explaining both transition modes,
 <h2>1.1) FSM Linear Transitions</h2>
 
 <p>Linear Transitions are Transition Rules allowing an FSM to transition from one or multiple possible <strong>From</strong> state(s) towards a <strong>To</strong> state upon a Triggered <strong>Event</strong>.
-The Lineair transition rule evaluation will always be done from the <em>*current state</em> of the FSM.
+The Lineair transition rule evaluation will always be done from the <strong>current state</strong> of the FSM.
 If no valid Transition Rule can be found in the FSM, the FSM will log an error and stop.</p>
 
 <h3>1.1.1) FSM Transition Rules</h3>
@@ -161,6 +161,39 @@ These rules define when an FSM can transition from a specific state towards an o
 
 <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>
 
+<p>Find below an example of a Linear Transition Rule definition for an FSM.</p>
+
+<pre><code> local Fsm3Switch = FSM:New() -- #FsmDemo
+ FsmSwitch:SetStartState( "Off" )
+ FsmSwitch:AddTransition( "Off", "SwitchOn", "On" )
+ FsmSwitch:AddTransition( "Off", "SwitchMiddle", "Middle" )
+ FsmSwitch:AddTransition( "On", "SwitchOff", "Off" )
+ FsmSwitch:AddTransition( "Middle", "SwitchOff", "Off" )
+</code></pre>
+
+<p>The above code snippet models a 3-way switch Linear Transition:</p>
+
+<ul>
+    <li>It can be switched <strong>On</strong> by triggering event <strong>SwitchOn</strong>.</li>
+    <li>It can be switched to the <strong>Middle</strong> position, by triggering event <strong>SwitchMiddle</strong>.</li>
+    <li>It can be switched <strong>Off</strong> by triggering event <strong>SwitchOff</strong>.</li>
+    <li>Note that once the Switch is <strong>On</strong> or <strong>Middle</strong>, it can only be switched <strong>Off</strong>.</li>
+</ul>
+
+<h3>Some additional comments:</h3>
+
+<p>Note that Linear Transition Rules <strong>can be declared in a few variations</strong>:</p>
+
+<ul>
+    <li>The From states can be <strong>a table of strings</strong>, indicating that the transition rule will be valid <strong>if the current state</strong> of the FSM will be <strong>one of the given From states</strong>.</li>
+    <li>The From state can be a <strong>"*"</strong>, indicating that <strong>the transition rule will always be valid</strong>, regardless of the current state of the FSM.</li>
+</ul>
+
+<p>The below code snippet shows how the two last lines can be rewritten and consensed.</p>
+
+<pre><code> FsmSwitch:AddTransition( { "On",  "Middle" }, "SwitchOff", "Off" )
+</code></pre>
+
 <h3>1.1.2) Transition Handling</h3>
 
 <p><img src="..\Presentations\FSM\Dia4.JPG" alt="Transition Handlers"/></p>
@@ -185,7 +218,7 @@ These parameters are on the correct order: From, Event, To:</p>
     <li>To = A string containing the To state.</li>
 </ul>
 
-<p>On top, each of these methods can have a variable amount of parameters passed. See the example in section 1.3.</p>
+<p>On top, each of these methods can have a variable amount of parameters passed. See the example in section <a href="#1.1.3)-event-triggers">1.1.3</a>.</p>
 
 <h3>1.1.3) Event Triggers</h3>
 
@@ -230,12 +263,18 @@ Event will be processed after 5 seconds, and Amount is given as a parameter.</p>
 
 <p>Because ... When Event was asynchronously processed after 5 seconds, Amount was set to 2. So be careful when processing and passing values and objects in asynchronous processing!</p>
 
-<h3>1.1.4) Linear Transitioning Example</h3>
+<h3>1.1.4) Linear Transition Example</h3>
 
-<p>This example creates a new FsmDemo object from class FSM.
+<p>This example is fully implemented in the MOOSE test mission on GITHUB: <a href="https://github.com/FlightControl-Master/MOOSE/blob/master/Moose%20Test%20Missions/FSM%20-%20Finite%20State%20Machine/FSM-100%20-%20Transition%20Explanation/FSM-100%20-%20Transition%20Explanation.lua">FSM-100 - Transition Explanation</a></p>
-It will set the start state of FsmDemo to Green.
+
-Two Transition Rules are created, where upon the event Switch,
+<p>It models a unit standing still near Batumi, and flaring every 5 seconds while switching between a Green flare and a Red flare.
-the FsmDemo will transition from state Green to Red and vise versa.</p>
+The purpose of this example is not to show how exciting flaring is, but it demonstrates how a Linear Transition FSM can be build.
+Have a look at the source code. The source code is also further explained below in this section.</p>
+
+<p>The example creates a new FsmDemo object from class FSM.
+It will set the start state of FsmDemo to state <strong>Green</strong>.
+Two Linear Transition Rules are created, where upon the event <strong>Switch</strong>,
+the FsmDemo will transition from state <strong>Green</strong> to <strong>Red</strong> and from <strong>Red</strong> back to <strong>Green</strong>.</p>
 
 <p><img src="..\Presentations\FSM\Dia6.JPG" alt="Transition Example"/></p>
 
@@ -295,18 +334,7 @@ and one additional parameter that was given when the event was triggered, which
 <pre><code>   FsmDemo:__Switch( 5, FsmUnit ) -- Trigger the next Switch event to happen in 5 seconds.
 </code></pre>
 
-<p>This example is fully implemented in the MOOSE test mission on GITHUB: <a href="https://github.com/FlightControl-Master/MOOSE/blob/master/Moose%20Test%20Missions/FSM%20-%20Finite%20State%20Machine/FSM-100%20-%20Transition%20Explanation/FSM-100%20-%20Transition%20Explanation.lua">FSM-100 - Transition Explanation</a></p>
+<p>The below code fragment extends the FsmDemo, demonstrating multiple <strong>From states declared as a table</strong>, adding a <strong>Linear Transition Rule</strong>.
-
-<h3>Some additional comments:</h3>
-
-<p>Note that transition rules <strong>can be declared with a few variations</strong>:</p>
-
-<ul>
-    <li>The From states can be <strong>a table of strings</strong>, indicating that the transition rule will be valid <strong>if the current state</strong> of the FSM will be <strong>one of the given From states</strong>.</li>
-    <li>The From state can be a <strong>"*"</strong>, indicating that <strong>the transition rule will always be valid</strong>, regardless of the current state of the FSM.</li>
-</ul>
-
-<p>The below code fragment extends the FsmDemo, demonstrating multiple <strong>From states declared as a table</strong>, in an additional transition rule.
 The new event <strong>Stop</strong> will cancel the Switching process.
 The transition for event Stop can be executed if the current state of the FSM is either "Red" or "Green".</p>
 

docs/Documentation/Spawn.html

@@ -1692,9 +1692,6 @@ 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">