diff --git a/Moose Development/Moose/Core/Base.lua b/Moose Development/Moose/Core/Base.lua index e0cfd57ae..2b2caa6d1 100644 --- a/Moose Development/Moose/Core/Base.lua +++ b/Moose Development/Moose/Core/Base.lua @@ -11,27 +11,27 @@ -- -- Note: Normally you would not use the BASE class unless you are extending the MOOSE framework with new classes. -- --- 1.1) BASE constructor --- --------------------- +-- ## 1.1) BASE constructor +-- -- Any class derived from BASE, must use the @{Core.Base#BASE.New) constructor within the @{Core.Base#BASE.Inherit) method. -- See an example at the @{Core.Base#BASE.New} method how this is done. -- --- 1.2) BASE Trace functionality --- ----------------------------- +-- ## 1.2) BASE Trace functionality +-- -- 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. -- --- 1.2.1) Tracing functions --- ------------------------ +-- ### 1.2.1) Tracing functions +-- -- There are basically 3 types of tracing methods available within BASE: -- -- * @{#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. -- --- 1.2.2) Tracing levels --- --------------------- +-- ### 1.2.2) Tracing levels +-- -- There are 3 tracing levels within MOOSE. -- These tracing levels were defined to avoid bulks of tracing to be generated by lots of objects. -- @@ -42,13 +42,86 @@ -- * @{#BASE.T2}: Trace further logic within a function giving optional variables or parameters with tracing level 2. -- * @{#BASE.T3}: Trace further logic within a function giving optional variables or parameters with tracing level 3. -- --- 1.3) BASE Inheritance support --- =========================== +-- ### 1.2.3) Trace activation. +-- +-- Tracing can be activated in several ways: +-- +-- * Switch tracing on or off through the @{#BASE.TraceOnOff}() method. +-- * 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. +-- +-- The method @{#BASE.IsTrace}() will validate if tracing is activated or not. +-- +-- ## 1.3 DCS simulator Event Handling +-- +-- The BASE class provides methods to catch DCS Events. These are events that are triggered from within the DCS simulator, +-- and handled through lua scripting. MOOSE provides an encapsulation to handle these events more efficiently. +-- Therefore, the BASE class exposes the following event handling functions: +-- +-- * @{#BASE.EventOnBirth}(): Handle the birth of a new unit. +-- * @{#BASE.EventOnBaseCaptured}(): Handle the capturing of an airbase or a helipad. +-- * @{#BASE.EventOnCrash}(): Handle the crash of a unit. +-- * @{#BASE.EventOnDead}(): Handle the death of a unit. +-- * @{#BASE.EventOnEjection}(): Handle the ejection of a player out of an airplane. +-- * @{#BASE.EventOnEngineShutdown}(): Handle the shutdown of an engine. +-- * @{#BASE.EventOnEngineStartup}(): Handle the startup of an engine. +-- * @{#BASE.EventOnHit}(): Handle the hit of a shell to a unit. +-- * @{#BASE.EventOnHumanFailure}(): No a clue ... +-- * @{#BASE.EventOnLand}(): Handle the event when a unit lands. +-- * @{#BASE.EventOnMissionStart}(): Handle the start of the mission. +-- * @{#BASE.EventOnPilotDead}(): Handle the event when a pilot is dead. +-- * @{#BASE.EventOnPlayerComment}(): Handle the event when a player posts a comment. +-- * @{#BASE.EventOnPlayerEnterUnit}(): Handle the event when a player enters a unit. +-- * @{#BASE.EventOnPlayerLeaveUnit}(): Handle the event when a player leaves a unit. +-- * @{#BASE.EventOnBirthPlayerMissionEnd}(): Handle the event when a player ends the mission. (Not a clue what that does). +-- * @{#BASE.EventOnRefueling}(): Handle the event when a unit is refueling. +-- * @{#BASE.EventOnShootingEnd}(): Handle the event when a unit starts shooting (guns). +-- * @{#BASE.EventOnShootingStart}(): Handle the event when a unit ends shooting (guns). +-- * @{#BASE.EventOnShot}(): Handle the event when a unit shot a missile. +-- * @{#BASE.EventOnTakeOff}(): Handle the event when a unit takes off from a runway. +-- * @{#BASE.EventOnTookControl}(): Handle the event when a player takes control of a unit. +-- +-- The EventOn() methods provide the @{Core.Event#EVENTDATA} structure to the event handling function. +-- The @{Core.Event#EVENTDATA} structure contains an enriched data set of information about the event being handled. +-- +-- Find below an example of the prototype how to write an event handling function: +-- +-- CommandCenter:EventOnPlayerEnterUnit( +-- --- @param #COMMANDCENTER self +-- -- @param Core.Event#EVENTDATA EventData +-- function( self, EventData ) +-- local PlayerUnit = EventData.IniUnit +-- for MissionID, Mission in pairs( self:GetMissions() ) do +-- local Mission = Mission -- Tasking.Mission#MISSION +-- Mission:JoinUnit( PlayerUnit ) +-- Mission:ReportDetails() +-- end +-- end +-- ) +-- +-- Note the function( self, EventData ). It takes two parameters: +-- +-- * self = the object that is handling the EventOnPlayerEnterUnit. +-- * EventData = the @{Core.Event#EVENTDATA} structure, containing more information of the Event. +-- +-- ## 1.4) Class identification methods +-- +-- BASE provides methods to get more information of each object: +-- +-- * @{#BASE.GetClassID}(): Gets the ID (number) of the object. Each object created is assigned a number, that is incremented by one. +-- * @{#BASE.GetClassName}(): Gets the name of the object, which is the name of the class the object was instantiated from. +-- * @{#BASE.GetClassNameAndID}(): Gets the name and ID of the object. +-- +-- ## 1.10) BASE Inheritance (tree) support +-- -- The following methods are available to support inheritance: -- -- * @{#BASE.Inherit}: Inherits from a class. --- * @{#BASE.Inherited}: Returns the parent class from the 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. @@ -217,7 +290,7 @@ function BASE:EventRemoveAll() return self end ---- Subscribe to a S_EVENT_SHOT event. +--- Subscribe to a S_EVENT\_SHOT event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -228,7 +301,7 @@ function BASE:EventOnShot( EventFunction ) return self end ---- Subscribe to a S_EVENT_HIT event. +--- Subscribe to a S_EVENT\_HIT event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -239,7 +312,7 @@ function BASE:EventOnHit( EventFunction ) return self end ---- Subscribe to a S_EVENT_TAKEOFF event. +--- Subscribe to a S_EVENT\_TAKEOFF event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -250,7 +323,7 @@ function BASE:EventOnTakeOff( EventFunction ) return self end ---- Subscribe to a S_EVENT_LAND event. +--- Subscribe to a S_EVENT\_LAND event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -261,7 +334,7 @@ function BASE:EventOnLand( EventFunction ) return self end ---- Subscribe to a S_EVENT_CRASH event. +--- Subscribe to a S_EVENT\_CRASH event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -272,7 +345,7 @@ function BASE:EventOnCrash( EventFunction ) return self end ---- Subscribe to a S_EVENT_EJECTION event. +--- Subscribe to a S_EVENT\_EJECTION event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -284,7 +357,7 @@ function BASE:EventOnEjection( EventFunction ) end ---- Subscribe to a S_EVENT_REFUELING event. +--- Subscribe to a S_EVENT\_REFUELING event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -295,7 +368,7 @@ function BASE:EventOnRefueling( EventFunction ) return self end ---- Subscribe to a S_EVENT_DEAD event. +--- Subscribe to a S_EVENT\_DEAD event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -306,7 +379,7 @@ function BASE:EventOnDead( EventFunction ) return self end ---- Subscribe to a S_EVENT_PILOT_DEAD event. +--- Subscribe to a S_EVENT_PILOT\_DEAD event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -317,7 +390,7 @@ function BASE:EventOnPilotDead( EventFunction ) return self end ---- Subscribe to a S_EVENT_BASE_CAPTURED event. +--- Subscribe to a S_EVENT_BASE\_CAPTURED event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -328,7 +401,7 @@ function BASE:EventOnBaseCaptured( EventFunction ) return self end ---- Subscribe to a S_EVENT_MISSION_START event. +--- Subscribe to a S_EVENT_MISSION\_START event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -339,7 +412,7 @@ function BASE:EventOnMissionStart( EventFunction ) return self end ---- Subscribe to a S_EVENT_MISSION_END event. +--- Subscribe to a S_EVENT_MISSION\_END event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -350,7 +423,7 @@ function BASE:EventOnPlayerMissionEnd( EventFunction ) return self end ---- Subscribe to a S_EVENT_TOOK_CONTROL event. +--- Subscribe to a S_EVENT_TOOK\_CONTROL event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -361,7 +434,7 @@ function BASE:EventOnTookControl( EventFunction ) return self end ---- Subscribe to a S_EVENT_REFUELING_STOP event. +--- Subscribe to a S_EVENT_REFUELING\_STOP event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -372,7 +445,7 @@ function BASE:EventOnRefuelingStop( EventFunction ) return self end ---- Subscribe to a S_EVENT_BIRTH event. +--- Subscribe to a S_EVENT\_BIRTH event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -383,7 +456,7 @@ function BASE:EventOnBirth( EventFunction ) return self end ---- Subscribe to a S_EVENT_HUMAN_FAILURE event. +--- Subscribe to a S_EVENT_HUMAN\_FAILURE event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -394,7 +467,7 @@ function BASE:EventOnHumanFailure( EventFunction ) return self end ---- Subscribe to a S_EVENT_ENGINE_STARTUP event. +--- Subscribe to a S_EVENT_ENGINE\_STARTUP event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -405,7 +478,7 @@ function BASE:EventOnEngineStartup( EventFunction ) return self end ---- Subscribe to a S_EVENT_ENGINE_SHUTDOWN event. +--- Subscribe to a S_EVENT_ENGINE\_SHUTDOWN event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -416,7 +489,7 @@ function BASE:EventOnEngineShutdown( EventFunction ) return self end ---- Subscribe to a S_EVENT_PLAYER_ENTER_UNIT event. +--- Subscribe to a S_EVENT_PLAYER_ENTER\_UNIT event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -427,7 +500,7 @@ function BASE:EventOnPlayerEnterUnit( EventFunction ) return self end ---- Subscribe to a S_EVENT_PLAYER_LEAVE_UNIT event. +--- Subscribe to a S_EVENT_PLAYER_LEAVE\_UNIT event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -438,7 +511,7 @@ function BASE:EventOnPlayerLeaveUnit( EventFunction ) return self end ---- Subscribe to a S_EVENT_PLAYER_COMMENT event. +--- Subscribe to a S_EVENT_PLAYER\_COMMENT event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -449,7 +522,7 @@ function BASE:EventOnPlayerComment( EventFunction ) return self end ---- Subscribe to a S_EVENT_SHOOTING_START event. +--- Subscribe to a S_EVENT_SHOOTING\_START event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -460,7 +533,7 @@ function BASE:EventOnShootingStart( EventFunction ) return self end ---- Subscribe to a S_EVENT_SHOOTING_END event. +--- Subscribe to a S_EVENT_SHOOTING\_END event. -- @param #BASE self -- @param #function EventFunction The function to be called when the event occurs for the unit. -- @return #BASE @@ -661,10 +734,10 @@ end -- @param #boolean TraceOnOff Switch the tracing on or off. -- @usage -- -- Switch the tracing On --- BASE:TraceOn( true ) +-- BASE:TraceOnOff( true ) -- -- -- Switch the tracing Off --- BASE:TraceOn( false ) +-- BASE:TraceOnOff( false ) function BASE:TraceOnOff( TraceOnOff ) _TraceOnOff = TraceOnOff end diff --git a/docs/Documentation/Base.html b/docs/Documentation/Base.html index 762c164fd..4cc8e7812 100644 --- a/docs/Documentation/Base.html +++ b/docs/Documentation/Base.html @@ -101,14 +101,17 @@
Note: Normally you would not use the BASE class unless you are extending the MOOSE framework with new classes.
Any class derived from BASE, must use the Core.Base#BASE.New method how this is done.
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.
-There are basically 3 types of tracing methods available within BASE:
There are 3 tracing levels within MOOSE.
These tracing levels were defined to avoid bulks of tracing to be generated by lots of objects.
Tracing can be activated in several ways:
+ +The method BASE.IsTrace() will validate if tracing is activated or not.
+ +The BASE class provides methods to catch DCS Events. These are events that are triggered from within the DCS simulator, +and handled through lua scripting. MOOSE provides an encapsulation to handle these events more efficiently. +Therefore, the BASE class exposes the following event handling functions:
+ +The EventOn() methods provide the Core.Event#EVENTDATA structure to the event handling function. +The Core.Event#EVENTDATA structure contains an enriched data set of information about the event being handled.
+ +Find below an example of the prototype how to write an event handling function:
+ + CommandCenter:EventOnPlayerEnterUnit(
+ --- @param #COMMANDCENTER self
+ -- @param Core.Event#EVENTDATA EventData
+ function( self, EventData )
+ local PlayerUnit = EventData.IniUnit
+ for MissionID, Mission in pairs( self:GetMissions() ) do
+ local Mission = Mission -- Tasking.Mission#MISSION
+ Mission:JoinUnit( PlayerUnit )
+ Mission:ReportDetails()
+ end
+ end
+ )
+
+
+Note the function( self, EventData ). It takes two parameters:
+ +BASE provides methods to get more information of each object:
+ +The following methods are available to support inheritance:
Subscribe to a SEVENTBIRTH event.
+Subscribe to a S_EVENT_BIRTH event.
Subscribe to a SEVENTCRASH event.
+Subscribe to a S_EVENT_CRASH event.
Subscribe to a SEVENTDEAD event.
+Subscribe to a S_EVENT_DEAD event.
Subscribe to a SEVENTEJECTION event.
+Subscribe to a S_EVENT_EJECTION event.
Subscribe to a SEVENTHIT event.
+Subscribe to a S_EVENT_HIT event.
Subscribe to a SEVENTLAND event.
+Subscribe to a S_EVENT_LAND event.
Subscribe to a SEVENTPLAYERENTERUNIT event.
+Subscribe to a SEVENTPLAYER_ENTER_UNIT event.
Subscribe to a SEVENTPLAYERLEAVEUNIT event.
+Subscribe to a SEVENTPLAYER_LEAVE_UNIT event.
Subscribe to a SEVENTREFUELING event.
+Subscribe to a S_EVENT_REFUELING event.
Subscribe to a SEVENTSHOT event.
+Subscribe to a S_EVENT_SHOT event.
Subscribe to a SEVENTTAKEOFF event.
+Subscribe to a S_EVENT_TAKEOFF event.
Subscribe to a SEVENTBIRTH event.
+Subscribe to a S_EVENT_BIRTH event.
Subscribe to a SEVENTCRASH event.
+Subscribe to a S_EVENT_CRASH event.
Subscribe to a SEVENTDEAD event.
+Subscribe to a S_EVENT_DEAD event.
Subscribe to a SEVENTEJECTION event.
+Subscribe to a S_EVENT_EJECTION event.
Subscribe to a SEVENTHIT event.
+Subscribe to a S_EVENT_HIT event.
Subscribe to a SEVENTLAND event.
+Subscribe to a S_EVENT_LAND event.
Subscribe to a SEVENTPLAYERENTERUNIT event.
+Subscribe to a SEVENTPLAYER_ENTER_UNIT event.
Subscribe to a SEVENTPLAYERLEAVEUNIT event.
+Subscribe to a SEVENTPLAYER_LEAVE_UNIT event.
Subscribe to a SEVENTREFUELING event.
+Subscribe to a S_EVENT_REFUELING event.
Subscribe to a SEVENTSHOT event.
+Subscribe to a S_EVENT_SHOT event.
Subscribe to a SEVENTTAKEOFF event.
+Subscribe to a S_EVENT_TAKEOFF event.
-- Switch the tracing On
-BASE:TraceOn( true )
+BASE:TraceOnOff( true )
-- Switch the tracing Off
-BASE:TraceOn( false )
+BASE:TraceOnOff( false )
Don't repeat the group from Take-Off till Landing and back Take-Off by ReSpawning.
-