From dc3ce7226e9175284474b74472de10310d09acf3 Mon Sep 17 00:00:00 2001 From: FlightControl Date: Mon, 19 Dec 2016 21:42:17 +0100 Subject: [PATCH] Documentation --- Moose Development/Moose/Core/Base.lua | 28 +++++++++--- Moose Development/Moose/Core/Fsm.lua | 41 ++++++++++++++++-- Moose Development/Moose/Functional/Spawn.lua | 35 +++++++-------- .../Presentations/Core/FSM/MOOSE - FSM.pptx | Bin 4053148 -> 4053136 bytes 4 files changed, 76 insertions(+), 28 deletions(-) diff --git a/Moose Development/Moose/Core/Base.lua b/Moose Development/Moose/Core/Base.lua index 2b2caa6d1..8e6a06e2b 100644 --- a/Moose Development/Moose/Core/Base.lua +++ b/Moose Development/Moose/Core/Base.lua @@ -122,13 +122,31 @@ -- * @{#BASE.Inherit}: Inherits from a class. -- * @{#BASE.GetParent}: Returns the parent object from the object it is handling, or nil if there is no parent object. -- --- Future --- ====== --- Further methods may be added to BASE whenever there is a need to make "overall" functions available within MOOSE. --- -- ==== -- --- ### Author: FlightControl +-- # **API CHANGE HISTORY** +-- +-- The underlying change log documents the API changes. Please read this carefully. The following notation is used: +-- +-- * **Added** parts are expressed in bold type face. +-- * _Removed_ parts are expressed in italic type face. +-- +-- YYYY-MM-DD: CLASS:**NewFunction**( Params ) replaces CLASS:_OldFunction_( Params ) +-- YYYY-MM-DD: CLASS:**NewFunction( Params )** added +-- +-- Hereby the change log: +-- +-- === +-- +-- # **AUTHORS and CONTRIBUTIONS** +-- +-- ### Contributions: +-- +-- * None. +-- +-- ### Authors: +-- +-- * **FlightControl**: Design & Programming -- -- @module Base diff --git a/Moose Development/Moose/Core/Fsm.lua b/Moose Development/Moose/Core/Fsm.lua index 736c9c6e7..ac979ee6b 100644 --- a/Moose Development/Moose/Core/Fsm.lua +++ b/Moose Development/Moose/Core/Fsm.lua @@ -1,4 +1,5 @@ ---- This module contains the FSM class. +--- This module contains the FSM class and derived FSM_ classes. +-- -- 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 -- @@ -7,13 +8,45 @@ -- -- === -- --- 1) @{Workflow#FSM} class, extends @{Core.Base#BASE} --- ============================================== +-- # 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. +-- +-- -- 1.1) Add or remove objects from the FSM -- -------------------------------------------- +-- +-- ==== +-- +-- # **API CHANGE HISTORY** +-- +-- The underlying change log documents the API changes. Please read this carefully. The following notation is used: +-- +-- * **Added** parts are expressed in bold type face. +-- * _Removed_ parts are expressed in italic type face. +-- +-- YYYY-MM-DD: CLASS:**NewFunction**( Params ) replaces CLASS:_OldFunction_( Params ) +-- YYYY-MM-DD: CLASS:**NewFunction( Params )** added +-- +-- Hereby the change log: +-- +-- * 2016-12-18: Released. +-- +-- === +-- +-- # **AUTHORS and CONTRIBUTIONS** +-- +-- ### Contributions: +-- +-- * None. +-- +-- ### Authors: +-- +-- * **FlightControl**: Design & Programming +-- -- @module Fsm --- @author FlightControl do -- FSM diff --git a/Moose Development/Moose/Functional/Spawn.lua b/Moose Development/Moose/Functional/Spawn.lua index 2f6b0bec5..b5812fffa 100644 --- a/Moose Development/Moose/Functional/Spawn.lua +++ b/Moose Development/Moose/Functional/Spawn.lua @@ -1,7 +1,7 @@ --- This module contains the SPAWN class. -- --- 1) @{Functional.Spawn#SPAWN} class, extends @{Core.Base#BASE} --- ============================================= +-- # 1) @{Functional.Spawn#SPAWN} class, extends @{Core.Base#BASE} +-- -- The @{#SPAWN} 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 *"Spawn Template"* 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. @@ -24,8 +24,8 @@ -- * It is important to defined BEFORE you spawn new groups, a proper initialization of the SPAWN instance is done with the options you want to use. -- * When designing a mission, NEVER name groups using a "#" within the name of the group Spawn Template(s), or the SPAWN module logic won't work anymore. -- --- 1.1) SPAWN construction methods --- ------------------------------- +-- ## 1.1) SPAWN construction methods +-- -- Create a new SPAWN object with the @{#SPAWN.New}() or the @{#SPAWN.NewWithAlias}() methods: -- -- * @{#SPAWN.New}(): Creates a new SPAWN object taking the name of the group that represents the GROUP Template (definition). @@ -35,8 +35,8 @@ -- The initialization methods will modify this list of groups so that when a group gets spawned, ALL information is already prepared when spawning. This is done for performance reasons. -- 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. -- --- 1.2) SPAWN initialization methods --- --------------------------------- +-- ## 1.2) SPAWN initialization methods +-- -- A spawn object will behave differently based on the usage of **initialization** methods, which all start with the **Init** prefix: -- -- * @{#SPAWN.InitLimit}(): Limits the amount of groups that can be alive at the same time and that can be dynamically spawned. @@ -48,8 +48,8 @@ -- * @{#SPAWN.InitRandomizeUnits}(): Randomizes the @{Unit}s in the @{Group} that is spawned within a **radius band**, given an Outer and Inner radius. -- * @{#SPAWN.InitRandomizeZones}(): Randomizes the spawning between a predefined list of @{Zone}s that are declared using this function. Each zone can be given a probability factor. -- --- 1.3) SPAWN spawning methods --- --------------------------- +-- ## 1.3) SPAWN spawning methods +-- -- Groups can be spawned at different times and methods: -- -- * @{#SPAWN.Spawn}(): Spawn one new group based on the last spawned index. @@ -64,8 +64,8 @@ -- Note that @{#SPAWN.Spawn} and @{#SPAWN.ReSpawn} return a @{GROUP#GROUP.New} object, that contains a reference to the DCSGroup object. -- You can use the @{GROUP} object to do further actions with the DCSGroup. -- --- 1.4) Retrieve alive GROUPs spawned by the SPAWN object --- ------------------------------------------------------ +-- ## 1.4) Retrieve alive GROUPs spawned by the SPAWN object +-- -- 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: @@ -77,8 +77,8 @@ -- You can use the methods @{#SPAWN.GetFirstAliveGroup}() and sequently @{#SPAWN.GetNextAliveGroup}() to iterate through the alive GROUPS within the SPAWN object, and to actions... See the respective methods for an example. -- The method @{#SPAWN.GetGroupFromIndex}() will return the GROUP object reference from the given Index, dead or alive... -- --- 1.5) SPAWN object cleaning --- -------------------------- +-- ## 1.5) SPAWN object cleaning +-- -- 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. @@ -89,8 +89,8 @@ -- This models AI that has succesfully returned to their airbase, to restart their combat activities. -- Check the @{#SPAWN.InitCleanUp}() for further info. -- --- 1.6) Catch the @{Group} spawn event in a callback function! --- ----------------------------------------------------------- +-- ## 1.6) Catch the @{Group} spawn event in a callback function! +-- -- When using the SpawnScheduled method, new @{Group}s are created following the schedule timing parameters. -- When a new @{Group} is spawned, you maybe want to execute actions with that group spawned at the spawn event. -- To SPAWN class supports this functionality through the @{#SPAWN.OnSpawnGroup}( **function( SpawnedGroup ) end ** ) method, which takes a function as a parameter that you can define locally. @@ -100,8 +100,7 @@ -- -- ==== -- --- **API CHANGE HISTORY** --- ====================== +-- # **API CHANGE HISTORY** -- -- The underlying change log documents the API changes. Please read this carefully. The following notation is used: -- @@ -177,8 +176,7 @@ -- -- === -- --- AUTHORS and CONTRIBUTIONS --- ========================= +-- # **AUTHORS and CONTRIBUTIONS** -- -- ### Contributions: -- @@ -188,7 +186,6 @@ -- -- * **FlightControl**: Design & Programming -- --- -- @module Spawn diff --git a/Moose Training/Presentations/Core/FSM/MOOSE - FSM.pptx b/Moose Training/Presentations/Core/FSM/MOOSE - FSM.pptx index 0a0405589ccb447a623aba6cd2a1a26c438fe7bd..8d4a6afd898acec0f4402243e3f3f47cf5d11252 100644 GIT binary patch delta 1712 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 AGXMYp