MOOSE generated documentation [skip ci]

This commit is contained in:
Applevangelist
2021-12-20 12:06:00 +00:00
parent 1e732ea232
commit be8c95fcfd
69 changed files with 2023 additions and 1676 deletions

View File

@@ -1518,12 +1518,12 @@ Controls a network of short range air/missile defense groups.</p>
<p>A Finite State Machine (FSM) models a process flow that transitions between various <strong>States</strong> through triggered <strong>Events</strong>.</p>
<p>A FSM can only be in one of a finite number of states.
The machine is in only one state at a time; the state it is in at any given time is called the <strong>current state</strong>.
It can change from one state to another when initiated by an <strong><strong>internal</strong> or <strong>external</strong> triggering event</strong>, which is called a <strong>transition</strong>.
The machine is in only one state at a time; the state it is in at any given time is called the <strong>current state</strong>.
It can change from one state to another when initiated by an <strong><strong>internal</strong> or <strong>external</strong> triggering event</strong>, which is called a <strong>transition</strong>.
An <strong>FSM implementation</strong> is defined by <strong>a list of its states</strong>, <strong>its initial state</strong>, and <strong>the triggering events</strong> for <strong>each possible transition</strong>.
An FSM implementation is composed out of <strong>two parts</strong>, a set of <strong>state transition rules</strong>, and an implementation set of <strong>state transition handlers</strong>, implementing those transitions.</p>
<p>The FSM class supports a <strong>hierarchical implementation of a Finite State Machine</strong>,
<p>The FSM class supports a <strong>hierarchical implementation of a Finite State Machine</strong>,
that is, it allows to <strong>embed existing FSM implementations in a master FSM</strong>.
FSM hierarchies allow for efficient FSM re-use, <strong>not having to re-invent the wheel every time again</strong> when designing complex processes.</p>
@@ -1531,7 +1531,7 @@ FSM hierarchies allow for efficient FSM re-use, <strong>not having to re-invent
<p>The above diagram shows a graphical representation of a FSM implementation for a <strong>Task</strong>, which guides a Human towards a Zone,
orders him to destroy x targets and account the results.
Other examples of ready made FSM could be: </p>
Other examples of ready made FSM could be:</p>
<ul>
<li>route a plane to a zone flown by a human</li>
@@ -1541,10 +1541,10 @@ Other examples of ready made FSM could be: </p>
<li>let an AI patrol a zone</li>
</ul>
<p>The <strong>MOOSE framework</strong> uses extensively the FSM class and derived FSM_ classes,
<p>The <strong>MOOSE framework</strong> uses extensively the FSM class and derived FSM_ classes,
because <strong>the goal of MOOSE is to simplify mission design complexity for mission building</strong>.
By efficiently utilizing the FSM class and derived classes, MOOSE allows mission designers to quickly build processes.
<strong>Ready made FSM-based implementations classes</strong> exist within the MOOSE framework that <strong>can easily be re-used,
<strong>Ready made FSM-based implementations classes</strong> exist within the MOOSE framework that <strong>can easily be re-used,
and tailored</strong> by mission designers through <strong>the implementation of Transition Handlers</strong>.
Each of these FSM implementation classes start either with:</p>
@@ -1556,7 +1556,7 @@ Each of these FSM implementation classes start either with:</p>
<p>Detailed explanations and API specifics are further below clarified and FSM derived class specifics are described in those class documentation sections.</p>
<h2><strong>Dislaimer:</strong></h2>
<h2><strong>Disclaimer:</strong></h2>
<p>The FSM class development is based on a finite state machine implementation made by Conroy Kyle.
The state machine can be found on <a href="https://github.com/kyleconroy/lua-state-machine">github</a>
I've reworked this development (taken the concept), and created a <strong>hierarchical state machine</strong> out of it, embedded within the DCS simulator.
@@ -1574,7 +1574,6 @@ Additionally, I've added extendability and created an API that allows seamless F
<hr/>
<h3>Author: <strong>FlightControl</strong></h3>
<h3>Contributions: <strong>funkyfranky</strong></h3>
@@ -1604,12 +1603,12 @@ Additionally, I've added extendability and created an API that allows seamless F
<p>A FSM can only be in one of a finite number of states.
The machine is in only one state at a time; the state it is in at any given time is called the <strong>current state</strong>.
It can change from one state to another when initiated by an <strong><strong>internal</strong> or <strong>external</strong> triggering event</strong>, which is called a <strong>transition</strong>.
The machine is in only one state at a time; the state it is in at any given time is called the <strong>current state</strong>.
It can change from one state to another when initiated by an <strong><strong>internal</strong> or <strong>external</strong> triggering event</strong>, which is called a <strong>transition</strong>.
An <strong>FSM implementation</strong> is defined by <strong>a list of its states</strong>, <strong>its initial state</strong>, and <strong>the triggering events</strong> for <strong>each possible transition</strong>.
An FSM implementation is composed out of <strong>two parts</strong>, a set of <strong>state transition rules</strong>, and an implementation set of <strong>state transition handlers</strong>, implementing those transitions.</p>
<p>The FSM class supports a <strong>hierarchical implementation of a Finite State Machine</strong>,
<p>The FSM class supports a <strong>hierarchical implementation of a Finite State Machine</strong>,
that is, it allows to <strong>embed existing FSM implementations in a master FSM</strong>.
FSM hierarchies allow for efficient FSM re-use, <strong>not having to re-invent the wheel every time again</strong> when designing complex processes.</p>
@@ -1617,20 +1616,20 @@ FSM hierarchies allow for efficient FSM re-use, <strong>not having to re-invent
<p>The above diagram shows a graphical representation of a FSM implementation for a <strong>Task</strong>, which guides a Human towards a Zone,
orders him to destroy x targets and account the results.
Other examples of ready made FSM could be: </p>
Other examples of ready made FSM could be:</p>
<ul>
<li>route a plane to a zone flown by a human</li>
<li>detect targets by an AI and report to humans</li>
<li>account for destroyed targets by human players</li>
<li>handle AI infantry to deploy from or embark to a helicopter or airplane or vehicle </li>
<li>handle AI infantry to deploy from or embark to a helicopter or airplane or vehicle</li>
<li>let an AI patrol a zone</li>
</ul>
<p>The <strong>MOOSE framework</strong> uses extensively the FSM class and derived FSM_ classes,
<p>The <strong>MOOSE framework</strong> uses extensively the FSM class and derived FSM_ classes,
because <strong>the goal of MOOSE is to simplify mission design complexity for mission building</strong>.
By efficiently utilizing the FSM class and derived classes, MOOSE allows mission designers to quickly build processes.
<strong>Ready made FSM-based implementations classes</strong> exist within the MOOSE framework that <strong>can easily be re-used,
<strong>Ready made FSM-based implementations classes</strong> exist within the MOOSE framework that <strong>can easily be re-used,
and tailored</strong> by mission designers through <strong>the implementation of Transition Handlers</strong>.
Each of these FSM implementation classes start either with:</p>
@@ -1647,9 +1646,9 @@ The derived FSM_ classes extend the Finite State Machine functionality to run a
<p>Finite State Machines have <strong>Transition Rules</strong>, <strong>Transition Handlers</strong> and <strong>Event Triggers</strong>.</p>
<p>The <strong>Transition Rules</strong> define the "Process Flow Boundaries", that is,
<p>The <strong>Transition Rules</strong> define the "Process Flow Boundaries", that is,
the path that can be followed hopping from state to state upon triggered events.
If an event is triggered, and there is no valid path found for that event,
If an event is triggered, and there is no valid path found for that event,
an error will be raised and the FSM will stop functioning.</p>
<p>The <strong>Transition Handlers</strong> are special methods that can be defined by the mission designer, following a defined syntax.
@@ -1660,20 +1659,20 @@ The method can then define its own custom logic to implement the FSM workflow, a
Most of the time, these Event Triggers are used within the Transition Handler methods, so that a workflow is created running through the state machine.</p>
<p>As explained above, a FSM supports <strong>Linear State Transitions</strong> and <strong>Hierarchical State Transitions</strong>, and both can be mixed to make a comprehensive FSM implementation.
The below documentation has a seperate chapter explaining both transition modes, taking into account the <strong>Transition Rules</strong>, <strong>Transition Handlers</strong> and <strong>Event Triggers</strong>.</p>
The below documentation has a separate chapter explaining both transition modes, taking into account the <strong>Transition Rules</strong>, <strong>Transition Handlers</strong> and <strong>Event Triggers</strong>.</p>
<h2>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 <strong>current state</strong> of the FSM.
The Linear 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>FSM Transition Rules</h3>
<p>The FSM has transition rules that it follows and validates, as it walks the process.
<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 method <a href="##(FSM).AddTransition">FSM.AddTransition</a>() specifies a new possible Transition Rule for the FSM. </p>
<p>The method <a href="##(FSM).AddTransition">FSM.AddTransition</a>() specifies a new possible Transition Rule for the FSM.</p>
<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>
@@ -1705,7 +1704,7 @@ These rules define when an FSM can transition from a specific state towards an o
<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>
<p>The below code snippet shows how the two last lines can be rewritten and condensed.</p>
<pre><code> FsmSwitch:AddTransition( { "On", "Middle" }, "SwitchOff", "Off" )
</code></pre>
@@ -1714,8 +1713,8 @@ These rules define when an FSM can transition from a specific state towards an o
<p><img src="..\Presentations\FSM\Dia4.JPG" alt="Transition Handlers"/></p>
<p>An FSM transitions in <strong>4 moments</strong> when an Event is being triggered and processed. <br/>
The mission designer can define for each moment specific logic within methods implementations following a defined API syntax. <br/>
<p>An FSM transitions in <strong>4 moments</strong> when an Event is being triggered and processed.
The mission designer can define for each moment specific logic within methods implementations following a defined API syntax.
These methods define the flow of the FSM process; because in those methods the FSM Internal Events will be triggered.</p>
<ul>
@@ -1740,7 +1739,7 @@ These parameters are on the correct order: From, Event, To:</p>
<p><img src="..\Presentations\FSM\Dia5.JPG" alt="Event Triggers"/></p>
<p>The FSM creates for each Event two <strong>Event Trigger methods</strong>. <br/>
<p>The FSM creates for each Event two <strong>Event Trigger methods</strong>.
There are two modes how Events can be triggered, which is <strong>synchronous</strong> and <strong>asynchronous</strong>:</p>
<ul>
@@ -1748,26 +1747,26 @@ There are two modes how Events can be triggered, which is <strong>synchronous</s
<li>The method <strong>FSM:<strong>Event( __seconds</strong> )</strong> triggers an Event that will be processed <strong>asynchronously</strong> over time, waiting <strong>x seconds</strong>.</li>
</ul>
<p>The destinction between these 2 Event Trigger methods are important to understand. An asynchronous call will "log" the Event Trigger to be executed at a later time.
<p>The distinction between these 2 Event Trigger methods are important to understand. An asynchronous call will "log" the Event Trigger to be executed at a later time.
Processing will just continue. Synchronous Event Trigger methods are useful to change states of the FSM immediately, but may have a larger processing impact.</p>
<p>The following example provides a little demonstration on the difference between synchronous and asynchronous Event Triggering.</p>
<pre><code> function FSM:OnAfterEvent( From, Event, To, Amount )
self:T( { Amount = Amount } )
self:T( { Amount = Amount } )
end
local Amount = 1
FSM:__Event( 5, Amount )
FSM:__Event( 5, Amount )
Amount = Amount + 1
FSM:Event( Text, Amount )
</code></pre>
<p>In this example, the <strong>:OnAfterEvent</strong>() Transition Handler implementation will get called when <strong>Event</strong> is being triggered.
Before we go into more detail, let's look at the last 4 lines of the example.
Before we go into more detail, let's look at the last 4 lines of the example.
The last line triggers synchronously the <strong>Event</strong>, and passes Amount as a parameter.
The 3rd last line of the example triggers asynchronously <strong>Event</strong>.
The 3rd last line of the example triggers asynchronously <strong>Event</strong>.
Event will be processed after 5 seconds, and Amount is given as a parameter.</p>
<p>The output of this little code fragment will be:</p>
@@ -1823,7 +1822,7 @@ The next code implements this through the event handling method <strong>OnAfterS
<p>The OnAfterSwitch implements a loop. The last line of the code fragment triggers the Switch Event within 5 seconds.
Upon the event execution (after 5 seconds), the OnAfterSwitch method is called of FsmDemo (cfr. the double point notation!!! ":").
The OnAfterSwitch method receives from the FSM the 3 transition parameter details ( From, Event, To ),
The OnAfterSwitch method receives from the FSM the 3 transition parameter details ( From, Event, To ),
and one additional parameter that was given when the event was triggered, which is in this case the Unit that is used within OnSwitchAfter.</p>
<pre><code> function FsmDemo:OnAfterSwitch( From, Event, To, FsmUnit )
@@ -1872,13 +1871,13 @@ And there is no transition handling method defined for that transition, thus, no
<h2>FSM Hierarchical Transitions</h2>
<p>Hierarchical Transitions allow to re-use readily available and implemented FSMs.
This becomes in very useful for mission building, where mission designers build complex processes and workflows,
This becomes in very useful for mission building, where mission designers build complex processes and workflows,
combining smaller FSMs to one single FSM.</p>
<p>The FSM can embed <strong>Sub-FSMs</strong> that will execute and return <strong>multiple possible Return (End) States</strong>. <br/>
<p>The FSM can embed <strong>Sub-FSMs</strong> that will execute and return <strong>multiple possible Return (End) States</strong>.
Depending upon <strong>which state is returned</strong>, the main FSM can continue the flow <strong>triggering specific events</strong>.</p>
<p>The method <a href="##(FSM).AddProcess">FSM.AddProcess</a>() adds a new Sub-FSM to the FSM. </p>
<p>The method <a href="##(FSM).AddProcess">FSM.AddProcess</a>() adds a new Sub-FSM to the FSM.</p>
<hr/>
@@ -5652,7 +5651,7 @@ When Moose is loaded statically, (as one file), tracing is switched off by defau
<div>
<div class="w3-card-2 w3-padding-small w3-margin-top">
#string
<a id="#(FSM)._StartState" ><strong>FSM._StartState</strong></a>
@@ -6083,7 +6082,7 @@ When Moose is loaded statically, (as one file), tracing is switched off by defau
</div>
<div class="w3-half">
<p>Current FSM state. </p>
<p>Current FSM state.</p>
</div>
</div>
@@ -6412,7 +6411,7 @@ When Moose is loaded statically, (as one file), tracing is switched off by defau
</div>
<div class="w3-half">
<p>Table of call backs. </p>
<p>Table of call backs.</p>
</div>
</div>
@@ -6686,7 +6685,7 @@ When Moose is loaded statically, (as one file), tracing is switched off by defau
</div>
<div class="w3-half">
<p>Event name. </p>
<p>Event name.</p>
</div>
</div>
@@ -6697,7 +6696,7 @@ When Moose is loaded statically, (as one file), tracing is switched off by defau
</div>
<div class="w3-half">
<p>Function. </p>
<p>Function.</p>
</div>
</div>
@@ -6730,7 +6729,7 @@ When Moose is loaded statically, (as one file), tracing is switched off by defau
</div>
<div class="w3-half">
<p>Event name. </p>
<p>Event name.</p>
</div>
</div>
@@ -7000,7 +6999,7 @@ When Moose is loaded statically, (as one file), tracing is switched off by defau
</div>
<div class="w3-half">
<p>Name. </p>
<p>Name.</p>
</div>
</div>
@@ -7142,7 +7141,7 @@ When Moose is loaded statically, (as one file), tracing is switched off by defau
</div>
<div class="w3-half">
<p>true, FSM is in this state. </p>
<p>true, FSM is in this state.</p>
</div>
</div>
@@ -7255,7 +7254,7 @@ When Moose is loaded statically, (as one file), tracing is switched off by defau
<div>
<div class="w3-card-2 w3-padding-small w3-margin-top">
#string
<a id="#(FSM)._StartState" ><strong>FSM._StartState</strong></a>
@@ -11508,7 +11507,7 @@ When moose is loading dynamically (for moose class development), tracing is swit
</div>
<div class="w3-half">
<p>Current FSM state. </p>
<p>Current FSM state.</p>
</div>
</div>
@@ -11837,7 +11836,7 @@ When moose is loading dynamically (for moose class development), tracing is swit
</div>
<div class="w3-half">
<p>Table of call backs. </p>
<p>Table of call backs.</p>
</div>
</div>
@@ -12111,7 +12110,7 @@ When moose is loading dynamically (for moose class development), tracing is swit
</div>
<div class="w3-half">
<p>Event name. </p>
<p>Event name.</p>
</div>
</div>
@@ -12122,7 +12121,7 @@ When moose is loading dynamically (for moose class development), tracing is swit
</div>
<div class="w3-half">
<p>Function. </p>
<p>Function.</p>
</div>
</div>
@@ -12155,7 +12154,7 @@ When moose is loading dynamically (for moose class development), tracing is swit
</div>
<div class="w3-half">
<p>Event name. </p>
<p>Event name.</p>
</div>
</div>
@@ -12425,7 +12424,7 @@ When moose is loading dynamically (for moose class development), tracing is swit
</div>
<div class="w3-half">
<p>Name. </p>
<p>Name.</p>
</div>
</div>
@@ -12567,7 +12566,7 @@ When moose is loading dynamically (for moose class development), tracing is swit
</div>
<div class="w3-half">
<p>true, FSM is in this state. </p>
<p>true, FSM is in this state.</p>
</div>
</div>
@@ -17388,7 +17387,7 @@ When moose is loading dynamically (for moose class development), tracing is swit
</div>
<div class="w3-half">
<p>Current FSM state. </p>
<p>Current FSM state.</p>
</div>
</div>
@@ -17717,7 +17716,7 @@ When moose is loading dynamically (for moose class development), tracing is swit
</div>
<div class="w3-half">
<p>Table of call backs. </p>
<p>Table of call backs.</p>
</div>
</div>
@@ -17991,7 +17990,7 @@ When moose is loading dynamically (for moose class development), tracing is swit
</div>
<div class="w3-half">
<p>Event name. </p>
<p>Event name.</p>
</div>
</div>
@@ -18002,7 +18001,7 @@ When moose is loading dynamically (for moose class development), tracing is swit
</div>
<div class="w3-half">
<p>Function. </p>
<p>Function.</p>
</div>
</div>
@@ -18035,7 +18034,7 @@ When moose is loading dynamically (for moose class development), tracing is swit
</div>
<div class="w3-half">
<p>Event name. </p>
<p>Event name.</p>
</div>
</div>
@@ -18305,7 +18304,7 @@ When moose is loading dynamically (for moose class development), tracing is swit
</div>
<div class="w3-half">
<p>Name. </p>
<p>Name.</p>
</div>
</div>
@@ -18447,7 +18446,7 @@ When moose is loading dynamically (for moose class development), tracing is swit
</div>
<div class="w3-half">
<p>true, FSM is in this state. </p>
<p>true, FSM is in this state.</p>
</div>
</div>
@@ -22278,7 +22277,7 @@ When moose is loading dynamically (for moose class development), tracing is swit
</div>
<div class="w3-half">
<p>Current FSM state. </p>
<p>Current FSM state.</p>
</div>
</div>
@@ -22607,7 +22606,7 @@ When moose is loading dynamically (for moose class development), tracing is swit
</div>
<div class="w3-half">
<p>Table of call backs. </p>
<p>Table of call backs.</p>
</div>
</div>
@@ -22881,7 +22880,7 @@ When moose is loading dynamically (for moose class development), tracing is swit
</div>
<div class="w3-half">
<p>Event name. </p>
<p>Event name.</p>
</div>
</div>
@@ -22892,7 +22891,7 @@ When moose is loading dynamically (for moose class development), tracing is swit
</div>
<div class="w3-half">
<p>Function. </p>
<p>Function.</p>
</div>
</div>
@@ -22925,7 +22924,7 @@ When moose is loading dynamically (for moose class development), tracing is swit
</div>
<div class="w3-half">
<p>Event name. </p>
<p>Event name.</p>
</div>
</div>
@@ -23195,7 +23194,7 @@ When moose is loading dynamically (for moose class development), tracing is swit
</div>
<div class="w3-half">
<p>Name. </p>
<p>Name.</p>
</div>
</div>
@@ -23337,7 +23336,7 @@ When moose is loading dynamically (for moose class development), tracing is swit
</div>
<div class="w3-half">
<p>true, FSM is in this state. </p>
<p>true, FSM is in this state.</p>
</div>
</div>