Documentation of the BASE class

2025-08-15 10:47:21 +00:00 · 2016-12-19 21:15:10 +01:00
parent 5bdb7db268
commit b21f1144fb
4 changed files with 226 additions and 68 deletions
--- a/Development/Moose/Core/Base.lua
+++ b/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