diff --git a/Moose Development/Moose/Core/Base.lua b/Moose Development/Moose/Core/Base.lua index 2eb7f97e9..40ed46274 100644 --- a/Moose Development/Moose/Core/Base.lua +++ b/Moose Development/Moose/Core/Base.lua @@ -1,34 +1,66 @@ ---- This module contains the BASE class. +--- **Core** - BASE forms **the basis of the MOOSE framework**. Each class within the MOOSE framework derives from BASE. -- --- 1) @{#BASE} class --- ================= --- The @{#BASE} class is the super class for all the classes defined within MOOSE. +-- ![Banner Image](..\Presentations\BASE\Dia1.JPG) -- --- It handles: +-- === -- --- * The construction and inheritance of child classes. --- * The tracing of objects during mission execution within the **DCS.log** file, under the **"Saved Games\DCS\Logs"** folder. +-- # 1) @{#BASE} class -- --- Note: Normally you would not use the BASE class unless you are extending the MOOSE framework with new classes. +-- All classes within the MOOSE framework are derived from the @{#BASE} class. +-- +-- BASE provides facilities for : +-- +-- * The construction and inheritance of MOOSE classes. +-- * The class naming and numbering system. +-- * The class hierarchy search system. +-- * The tracing of information or objects during mission execution for debuggin purposes. +-- * The subscription to DCS events for event handling in MOOSE objects. +-- +-- Note: The BASE class is an abstract class and is not meant to be used directly. -- -- ## 1.1) BASE constructor -- -- Any class derived from BASE, must use the @{Base#BASE.New) constructor within the @{Base#BASE.Inherit) method. -- See an example at the @{Base#BASE.New} method how this is done. -- --- ## 1.2) BASE Trace functionality +-- ## 1.2) Trace information for debugging -- -- The BASE class contains trace methods to trace progress within a mission execution of a certain object. --- Note that these trace methods are inherited by each MOOSE class interiting BASE. --- As such, each object created from derived class from BASE can use the tracing functions to trace its execution. +-- These trace methods are inherited by each MOOSE class interiting BASE, soeach object created from derived class from BASE can use the tracing methods to trace its execution. -- --- ### 1.2.1) Tracing functions +-- Any type of information can be passed to these tracing methods. See the following examples: +-- +-- self:E( "Hello" ) +-- +-- Result in the word "Hello" in the dcs.log. +-- +-- local Array = { 1, nil, "h", { "a","b" }, "x" } +-- self:E( Array ) +-- +-- Results with the text [1]=1,[3]="h",[4]={[1]="a",[2]="b"},[5]="x"} in the dcs.log. +-- +-- local Object1 = "Object1" +-- local Object2 = 3 +-- local Object3 = { Object 1, Object 2 } +-- self:E( { Object1, Object2, Object3 } ) +-- +-- Results with the text [1]={[1]="Object",[2]=3,[3]={[1]="Object",[2]=3}} in the dcs.log. +-- +-- local SpawnObject = SPAWN:New( "Plane" ) +-- local GroupObject = GROUP:FindByName( "Group" ) +-- self:E( { Spawn = SpawnObject, Group = GroupObject } ) +-- +-- Results with the text [1]={Spawn={....),Group={...}} in the dcs.log. +-- +-- Below a more detailed explanation of the different method types for tracing. +-- +-- ### 1.2.1) Tracing methods categories -- --- There are basically 3 types of tracing methods available within BASE: +-- There are basically 3 types of tracing methods available: -- --- * @{#BASE.F}: Trace the beginning of a function and its given parameters. An F is indicated at column 44 in the DCS.log file. --- * @{#BASE.T}: Trace further logic within a function giving optional variables or parameters. A T is indicated at column 44 in the DCS.log file. --- * @{#BASE.E}: Trace an exception within a function giving optional variables or parameters. An E is indicated at column 44 in the DCS.log file. An exception will always be traced. +-- * @{#BASE.F}: Used to trace the entrance of a function and its given parameters. An F is indicated at column 44 in the DCS.log file. +-- * @{#BASE.T}: Used to trace further logic within a function giving optional variables or parameters. A T is indicated at column 44 in the DCS.log file. +-- * @{#BASE.E}: Used to always trace information giving optional variables or parameters. An E is indicated at column 44 in the DCS.log file. -- -- ### 1.2.2) Tracing levels -- @@ -51,6 +83,7 @@ -- * Activate only the tracing of a certain class (name) through the @{#BASE.TraceClass}() method. -- * Activate only the tracing of a certain method of a certain class through the @{#BASE.TraceClassMethod}() method. -- * Activate only the tracing of a certain level through the @{#BASE.TraceLevel}() method. +-- -- ### 1.2.4) Check if tracing is on. -- -- The method @{#BASE.IsTrace}() will validate if tracing is activated or not. @@ -64,7 +97,7 @@ -- -- At first, the mission designer will need to **Subscribe** to a specific DCS event for the class. -- So, when the DCS event occurs, the class will be notified of that event. --- There are two functions which you use to subscribe to or unsubscribe from an event. +-- There are two methods which you use to subscribe to or unsubscribe from an event. -- -- * @{#BASE.HandleEvent}(): Subscribe to a DCS Event. -- * @{#BASE.UnHandleEvent}(): Unsubscribe from a DCS Event. @@ -114,10 +147,12 @@ -- -- ## 1.5) All objects derived from BASE can have "States" -- --- A mechanism is in place in MOOSE, that allows to let the objects administer **states**. --- States are essentially properties of objects, which are identified by a **Key** and a **Value**. --- The method @{#BASE.SetState}() can be used to set a Value with a reference Key to the object. --- To **read or retrieve** a state Value based on a Key, use the @{#BASE.GetState} method. +-- A mechanism is in place in MOOSE, that allows to let the objects administer **states**. +-- States are essentially properties of objects, which are identified by a **Key** and a **Value**. +-- +-- The method @{#BASE.SetState}() can be used to set a Value with a reference Key to the object. +-- To **read or retrieve** a state Value based on a Key, use the @{#BASE.GetState} method. +-- -- These two methods provide a very handy way to keep state at long lasting processes. -- Values can be stored within the objects, and later retrieved or changed when needed. -- There is one other important thing to note, the @{#BASE.SetState}() and @{#BASE.GetState} methods @@ -125,9 +160,9 @@ -- Thus, if the state is to be set for the same object as the object for which the method is used, then provide the same -- object name to the method. -- --- ## 1.10) BASE Inheritance (tree) support +-- ## 1.10) Inheritance -- --- The following methods are available to support inheritance: +-- The following methods are available to implement inheritance -- -- * @{#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. diff --git a/Moose Development/Moose/Core/Event.lua b/Moose Development/Moose/Core/Event.lua index 10aa2804e..03c0b34b3 100644 --- a/Moose Development/Moose/Core/Event.lua +++ b/Moose Development/Moose/Core/Event.lua @@ -1,5 +1,4 @@ ---- This core module models the dispatching of DCS Events to subscribed MOOSE classes, --- following a given priority. +--- **Core** - EVENT models DCS **event dispatching** using a **publish-subscribe** model. -- -- ![Banner Image](..\Presentations\EVENT\Dia1.JPG) -- diff --git a/Moose Development/Moose/Core/Fsm.lua b/Moose Development/Moose/Core/Fsm.lua index 809dcfdb1..c643f56bc 100644 --- a/Moose Development/Moose/Core/Fsm.lua +++ b/Moose Development/Moose/Core/Fsm.lua @@ -1,5 +1,5 @@ ---- This module contains the **FSM** (**F**inite **S**tate **M**achine) class and derived **FSM\_** classes. --- ## Finite State Machines (FSM) are design patterns allowing efficient (long-lasting) processes and workflows. +--- **Core** - The **FSM** (**F**inite **S**tate **M**achine) class and derived **FSM\_** classes +-- are design patterns allowing efficient (long-lasting) processes and workflows. -- -- ![Banner Image](..\Presentations\FSM\Dia1.JPG) -- diff --git a/Moose Development/Moose/Core/Menu.lua b/Moose Development/Moose/Core/Menu.lua index 6defc55d5..5dbab4fce 100644 --- a/Moose Development/Moose/Core/Menu.lua +++ b/Moose Development/Moose/Core/Menu.lua @@ -1,4 +1,4 @@ ---- This module contains the MENU classes. +--- **Core** -- MENU_ classes model the definition of **hierarchical menu structures** and **commands for players** within a mission. -- -- === -- diff --git a/Moose Development/Moose/Core/Message.lua b/Moose Development/Moose/Core/Message.lua index d263245e9..711b75585 100644 --- a/Moose Development/Moose/Core/Message.lua +++ b/Moose Development/Moose/Core/Message.lua @@ -1,26 +1,40 @@ ---- This module contains the MESSAGE class. +--- **Core** - MESSAGE class takes are of the **real-time notifications** and **messages to players** during a simulation. +-- +-- ![Banner Image](..\Presentations\MESSAGE\Dia1.JPG) +-- +-- === +-- +-- # 1) @{Message#MESSAGE} class, extends @{Base#BASE} -- --- 1) @{Message#MESSAGE} class, extends @{Base#BASE} --- ================================================= -- Message System to display Messages to Clients, Coalitions or All. -- Messages are shown on the display panel for an amount of seconds, and will then disappear. -- Messages can contain a category which is indicating the category of the message. -- --- 1.1) MESSAGE construction methods --- --------------------------------- +-- ## 1.1) MESSAGE construction +-- -- Messages are created with @{Message#MESSAGE.New}. Note that when the MESSAGE object is created, no message is sent yet. -- To send messages, you need to use the To functions. -- --- 1.2) Send messages with MESSAGE To methods --- ------------------------------------------ --- Messages are sent to: +-- ## 1.2) Send messages to an audience +-- +-- Messages are sent: -- --- * Clients with @{Message#MESSAGE.ToClient}. --- * Coalitions with @{Message#MESSAGE.ToCoalition}. --- * All Players with @{Message#MESSAGE.ToAll}. +-- * To a @{Client} using @{Message#MESSAGE.ToClient}(). +-- * To a @{Group} using @{Message#MESSAGE.ToGroup}() +-- * To a coalition using @{Message#MESSAGE.ToCoalition}(). +-- * To the red coalition using @{Message#MESSAGE.ToRed}(). +-- * To the blue coalition using @{Message#MESSAGE.ToBlue}(). +-- * To all Players using @{Message#MESSAGE.ToAll}(). +-- +-- ## 1.3) Send conditionally to an audience +-- +-- Messages can be sent conditionally to an audience (when a condition is true): -- +-- * To all players using @{Message#MESSAGE.ToAllIf}(). +-- * To a coalition using @{Message#MESSAGE.ToCoalitionIf}(). +-- +-- -- @module Message --- @author FlightControl --- The MESSAGE class -- @type MESSAGE @@ -229,80 +243,3 @@ function MESSAGE:ToAllIf( Condition ) return self end - - - ------ The MESSAGEQUEUE class ----- @type MESSAGEQUEUE ---MESSAGEQUEUE = { --- ClientGroups = {}, --- CoalitionSides = {} ---} --- ---function MESSAGEQUEUE:New( RefreshInterval ) --- local self = BASE:Inherit( self, BASE:New() ) --- self:F( { RefreshInterval } ) --- --- self.RefreshInterval = RefreshInterval --- --- --self.DisplayFunction = routines.scheduleFunction( self._DisplayMessages, { self }, 0, RefreshInterval ) --- self.DisplayFunction = SCHEDULER:New( self, self._DisplayMessages, {}, 0, RefreshInterval ) --- --- return self ---end --- ------ This function is called automatically by the MESSAGEQUEUE scheduler. ---function MESSAGEQUEUE:_DisplayMessages() --- --- -- First we display all messages that a coalition needs to receive... Also those who are not in a client (CA module clients...). --- for CoalitionSideID, CoalitionSideData in pairs( self.CoalitionSides ) do --- for MessageID, MessageData in pairs( CoalitionSideData.Messages ) do --- if MessageData.MessageSent == false then --- --trigger.action.outTextForCoalition( CoalitionSideID, MessageData.MessageCategory .. '\n' .. MessageData.MessageText:gsub("\n$",""):gsub("\n$",""), MessageData.MessageDuration ) --- MessageData.MessageSent = true --- end --- local MessageTimeLeft = ( MessageData.MessageTime + MessageData.MessageDuration ) - timer.getTime() --- if MessageTimeLeft <= 0 then --- MessageData = nil --- end --- end --- end --- --- -- Then we send the messages for each individual client, but also to be included are those Coalition messages for the Clients who belong to a coalition. --- -- Because the Client messages will overwrite the Coalition messages (for that Client). --- for ClientGroupName, ClientGroupData in pairs( self.ClientGroups ) do --- for MessageID, MessageData in pairs( ClientGroupData.Messages ) do --- if MessageData.MessageGroup == false then --- trigger.action.outTextForGroup( Group.getByName(ClientGroupName):getID(), MessageData.MessageCategory .. '\n' .. MessageData.MessageText:gsub("\n$",""):gsub("\n$",""), MessageData.MessageDuration ) --- MessageData.MessageGroup = true --- end --- local MessageTimeLeft = ( MessageData.MessageTime + MessageData.MessageDuration ) - timer.getTime() --- if MessageTimeLeft <= 0 then --- MessageData = nil --- end --- end --- --- -- Now check if the Client also has messages that belong to the Coalition of the Client... --- for CoalitionSideID, CoalitionSideData in pairs( self.CoalitionSides ) do --- for MessageID, MessageData in pairs( CoalitionSideData.Messages ) do --- local CoalitionGroup = Group.getByName( ClientGroupName ) --- if CoalitionGroup and CoalitionGroup:getCoalition() == CoalitionSideID then --- if MessageData.MessageCoalition == false then --- trigger.action.outTextForGroup( Group.getByName(ClientGroupName):getID(), MessageData.MessageCategory .. '\n' .. MessageData.MessageText:gsub("\n$",""):gsub("\n$",""), MessageData.MessageDuration ) --- MessageData.MessageCoalition = true --- end --- end --- local MessageTimeLeft = ( MessageData.MessageTime + MessageData.MessageDuration ) - timer.getTime() --- if MessageTimeLeft <= 0 then --- MessageData = nil --- end --- end --- end --- end --- --- return true ---end --- ------ The _MessageQueue object is created when the MESSAGE class module is loaded. -----_MessageQueue = MESSAGEQUEUE:New( 0.5 ) --- diff --git a/Moose Development/Moose/Core/Point.lua b/Moose Development/Moose/Core/Point.lua index c129b2122..3f6d7e995 100644 --- a/Moose Development/Moose/Core/Point.lua +++ b/Moose Development/Moose/Core/Point.lua @@ -1,4 +1,4 @@ ---- This module contains the POINT classes. +--- **Core** - **POINT\_VEC** classes define an **extensive API** to **manage 3D points** in the simulation space. -- -- 1) @{Point#POINT_VEC3} class, extends @{Base#BASE} -- ================================================== diff --git a/Moose Development/Moose/Core/Set.lua b/Moose Development/Moose/Core/Set.lua index f0638d088..f12e3312f 100644 --- a/Moose Development/Moose/Core/Set.lua +++ b/Moose Development/Moose/Core/Set.lua @@ -1,4 +1,4 @@ ---- This module contains the SET classes. +--- **Core** - SET classes define **collections** of objects to perform **bulk actions** and logically **group** objects. -- -- === -- diff --git a/Moose Development/Moose/Core/Zone.lua b/Moose Development/Moose/Core/Zone.lua index 59f951f81..4eb05b047 100644 --- a/Moose Development/Moose/Core/Zone.lua +++ b/Moose Development/Moose/Core/Zone.lua @@ -1,4 +1,6 @@ ---- This core module contains the ZONE classes, inherited from @{Zone#ZONE_BASE}. +--- **Core** - ZONE classes define **zones** within your mission of **various forms**, with **various capabilities**. +-- +-- === -- -- There are essentially two core functions that zones accomodate: -- diff --git a/Moose Presentations/BASE.pptx b/Moose Presentations/BASE.pptx new file mode 100644 index 000000000..c2e953d1f Binary files /dev/null and b/Moose Presentations/BASE.pptx differ diff --git a/Moose Presentations/MESSAGE.pptx b/Moose Presentations/MESSAGE.pptx new file mode 100644 index 000000000..164c27510 Binary files /dev/null and b/Moose Presentations/MESSAGE.pptx differ diff --git a/docs/Documentation/Base.html b/docs/Documentation/Base.html index 6f2cc7de4..526210e42 100644 --- a/docs/Documentation/Base.html +++ b/docs/Documentation/Base.html @@ -72,40 +72,78 @@

Module Base

-

This module contains the BASE class.

+

Core - BASE forms the basis of the MOOSE framework.

+

Each class within the MOOSE framework derives from BASE.

+ +

Banner Image

+ +

1) #BASE class

-

The #BASE class is the super class for all the classes defined within MOOSE.

-

It handles:

+

All classes within the MOOSE framework are derived from the #BASE class.

+ +

BASE provides facilities for :

-

Note: Normally you would not use the BASE class unless you are extending the MOOSE framework with new classes.

+

Note: The BASE class is an abstract class and is not meant to be used directly.

1.1) BASE constructor

Any class derived from BASE, must use the Base#BASE.New method how this is done.

-

1.2) BASE Trace functionality

+

1.2) Trace information for debugging

The BASE class contains trace methods to trace progress within a mission execution of a certain object. -Note that these trace methods are inherited by each MOOSE class interiting BASE. -As such, each object created from derived class from BASE can use the tracing functions to trace its execution.

+These trace methods are inherited by each MOOSE class interiting BASE, soeach object created from derived class from BASE can use the tracing methods to trace its execution.

-

1.2.1) Tracing functions

+

Any type of information can be passed to these tracing methods. See the following examples:

-

There are basically 3 types of tracing methods available within BASE:

+
self:E( "Hello" )
+
+ +

Result in the word "Hello" in the dcs.log.

+ +
local Array = { 1, nil, "h", { "a","b" }, "x" }
+self:E( Array )
+
+ +

Results with the text [1]=1,[3]="h",[4]={[1]="a",[2]="b"},[5]="x"} in the dcs.log.

+ +
local Object1 = "Object1"
+local Object2 = 3
+local Object3 = { Object 1, Object 2 }
+self:E( { Object1, Object2, Object3 } )
+
+ +

Results with the text [1]={[1]="Object",[2]=3,[3]={[1]="Object",[2]=3}} in the dcs.log.

+ +
local SpawnObject = SPAWN:New( "Plane" )
+local GroupObject = GROUP:FindByName( "Group" )
+self:E( { Spawn = SpawnObject, Group = GroupObject } )
+
+ +

Results with the text [1]={Spawn={....),Group={...}} in the dcs.log.

+ +

Below a more detailed explanation of the different method types for tracing.

+ +

1.2.1) Tracing methods categories

+ +

There are basically 3 types of tracing methods available:

1.2.2) Tracing levels

@@ -131,10 +169,11 @@ These tracing levels were defined to avoid bulks of tracing to be generated by l
  • Activate all tracing through the BASE.TraceAll() method.
  • Activate only the tracing of a certain class (name) through the BASE.TraceClass() method.
  • Activate only the tracing of a certain method of a certain class through the BASE.TraceClassMethod() method.
    • -
  • Activate only the tracing of a certain level through the BASE.TraceLevel() method. -

    1.2.4) Check if tracing is on.

    • +
  • Activate only the tracing of a certain level through the BASE.TraceLevel() method.
    • +

    1.2.4) Check if tracing is on.

    +

    The method BASE.IsTrace() will validate if tracing is activated or not.

    1.3 DCS simulator Event Handling

    @@ -146,7 +185,7 @@ and handled through lua scripting. MOOSE provides an encapsulation to handle the

    At first, the mission designer will need to Subscribe to a specific DCS event for the class. So, when the DCS event occurs, the class will be notified of that event. -There are two functions which you use to subscribe to or unsubscribe from an event.

    +There are two methods which you use to subscribe to or unsubscribe from an event.