diff --git a/Moose/Base.lua b/Moose/Base.lua index 6e9a563ee..a8efec0fc 100644 --- a/Moose/Base.lua +++ b/Moose/Base.lua @@ -1,6 +1,6 @@ ---- BASE The base class for all the classes defined within MOOSE. +--- The BASE class for all the classes defined within MOOSE. -- @module Base --- @author Flightcontrol +-- @author FlightControl Include.File( "Routines" ) @@ -33,7 +33,6 @@ local _TraceClass = { -- @field ClassName The name of the class. -- @field ClassID The ID number of the class. BASE = { - ClassName = "BASE", ClassID = 0, Events = {} @@ -48,8 +47,8 @@ FORMATION = { --- The base constructor. This is the top top class of all classed defined within the MOOSE. -- Any new class needs to be derived from this class for proper inheritance. --- @param self --- @return #BASE +-- @param #BASE self +-- @return #BASE The new instance of the BASE class. -- @usage -- function TASK:New() -- @@ -76,9 +75,10 @@ function BASE:New() end --- This is the worker method to inherit from a parent class. +-- @param #BASE self -- @param Child is the Child class that inherits. --- @param Parent is the Parent class that the Child inherits from. --- @return Child +-- @param #BASE Parent is the Parent class that the Child inherits from. +-- @return #BASE Child function BASE:Inherit( Child, Parent ) local Child = routines.utils.deepCopy( Child ) local Parent = routines.utils.deepCopy( Parent ) @@ -92,6 +92,7 @@ function BASE:Inherit( Child, Parent ) end --- This is the worker method to retrieve the Parent class. +-- @param #BASE self -- @param #BASE Child is the Child class from which the Parent class needs to be retrieved. -- @return #BASE function BASE:Inherited( Child ) @@ -122,7 +123,11 @@ function BASE:GetClassID() return self.ClassID end - +--- Set a new listener for the class. +-- @param self +-- @param DCSTypes#Event Event +-- @param #function EventFunction +-- @return #BASE function BASE:AddEvent( Event, EventFunction ) self:F( Event ) @@ -134,7 +139,9 @@ function BASE:AddEvent( Event, EventFunction ) return self end - +--- Enable the event listeners for the class. +-- @param #BASE self +-- @return #BASE function BASE:EnableEvents() self:F( #self.Events ) @@ -147,6 +154,10 @@ function BASE:EnableEvents() return self end + +--- Disable the event listeners for the class. +-- @param #BASE self +-- @return #BASE function BASE:DisableEvents() self:F() @@ -198,7 +209,13 @@ local BaseEventCodes = { -- weapon = Weapon -- } - +--- Creation of a Birth Event. +-- @param #BASE self +-- @param DCSTypes#Time EventTime The time stamp of the event. +-- @param DCSObject#Object Initiator The initiating object of the event. +-- @param #string IniUnitName The initiating unit name. +-- @param place +-- @param subplace function BASE:CreateEventBirth( EventTime, Initiator, IniUnitName, place, subplace ) self:F( { EventTime, Initiator, IniUnitName, place, subplace } ) @@ -214,6 +231,10 @@ function BASE:CreateEventBirth( EventTime, Initiator, IniUnitName, place, subpla world.onEvent( Event ) end +--- Creation of a Crash Event. +-- @param #BASE self +-- @param DCSTypes#Time EventTime The time stamp of the event. +-- @param DCSObject#Object Initiator The initiating object of the event. function BASE:CreateEventCrash( EventTime, Initiator ) self:F( { EventTime, Initiator } ) @@ -225,7 +246,11 @@ function BASE:CreateEventCrash( EventTime, Initiator ) world.onEvent( Event ) end - + +-- TODO: Complete DCSTypes#Event structure. +--- The main event handling function... This function captures all events generated for the class. +-- @param #BASE self +-- @param DCSTypes#Event event function BASE:onEvent(event) --env.info( 'onEvent Table self = ' .. tostring(self) ) @@ -250,7 +275,6 @@ function BASE:onEvent(event) end end end - end -- Trace section @@ -258,6 +282,9 @@ end -- Log a trace (only shown when trace is on) -- TODO: Make trace function using variable parameters. +--- Trace a function call. Must be at the beginning of the function logic. +-- @param #BASE self +-- @param Arguments A #table or any field. function BASE:F( Arguments ) if _TraceOn and _TraceClass[self.ClassName] then @@ -279,6 +306,9 @@ function BASE:F( Arguments ) end end +--- Trace a function call level 2. Must be at the beginning of the function logic. +-- @param #BASE self +-- @param Arguments A #table or any field. function BASE:F2( Arguments ) if _TraceLevel >= 2 then @@ -287,6 +317,9 @@ function BASE:F2( Arguments ) end +--- Trace a function call level 3. Must be at the beginning of the function logic. +-- @param #BASE self +-- @param Arguments A #table or any field. function BASE:F3( Arguments ) if _TraceLevel >= 3 then @@ -295,6 +328,9 @@ function BASE:F3( Arguments ) end +--- Trace a function logic. Can be anywhere within the function logic. +-- @param #BASE self +-- @param Arguments A #table or any field. function BASE:T( Arguments ) if _TraceOn and _TraceClass[self.ClassName] then @@ -316,6 +352,9 @@ function BASE:T( Arguments ) end end +--- Trace a function logic level 2. Can be anywhere within the function logic. +-- @param #BASE self +-- @param Arguments A #table or any field. function BASE:T2( Arguments ) if _TraceLevel >= 2 then @@ -324,6 +363,9 @@ function BASE:T2( Arguments ) end +--- Trace a function logic level 3. Can be anywhere within the function logic. +-- @param #BASE self +-- @param Arguments A #table or any field. function BASE:T3( Arguments ) if _TraceLevel >= 3 then @@ -332,9 +374,9 @@ function BASE:T3( Arguments ) end - - --- Log an exception +--- Log an exception which will be traced always. Can be anywhere within the function logic. +-- @param #BASE self +-- @param Arguments A #table or any field. function BASE:E( Arguments ) local DebugInfoCurrent = debug.getinfo( 2, "nl" ) diff --git a/Moose/Client.lua b/Moose/Client.lua index d91618860..b18c3085b 100644 --- a/Moose/Client.lua +++ b/Moose/Client.lua @@ -1,4 +1,6 @@ ---- CLIENT Classes +--- The CLIENT models client units in multi player missions. +-- Clients are those groups defined within the Mission Editor that have the skillset defined as "Client" or "Player". +-- Note that clients are NOT the same as groups, they are NOT necessarily alive. -- @module Client -- @author FlightControl @@ -7,8 +9,6 @@ Include.File( "Base" ) Include.File( "Cargo" ) Include.File( "Message" ) ---- Clients are those Groups defined within the Mission Editor that have the skillset defined as "Client" or "Player". --- These clients are defined within the Mission Orchestration Framework (MOF) --- The CLIENT class -- @type CLIENT @@ -58,8 +58,30 @@ function CLIENT:New( ClientName, ClientBriefing ) return self end +--- Transport defines that the Client is a Transport. Transports show cargo. +-- @param #CLIENT self +-- @return #CLIENT +function CLIENT:Transport() + self:F() + + self.ClientTransport = true + return self +end + +--- AddBriefing adds a briefing to a CLIENT when a player joins a mission. +-- @param #CLIENT self +-- @param #string ClientBriefing is the text defining the Mission briefing. +-- @return #CLIENT +function CLIENT:AddBriefing( ClientBriefing ) + self:F() + self.ClientBriefing = ClientBriefing + return self +end + + --- Resets a CLIENT. --- @param string ClientName Name of the Group as defined within the Mission Editor. The Group must have a Unit with the type Client. +-- @param #CLIENT self +-- @param #string ClientName Name of the Group as defined within the Mission Editor. The Group must have a Unit with the type Client. function CLIENT:Reset( ClientName ) self:F() self._Menus = {} @@ -68,12 +90,13 @@ end --- Checks for a client alive event and calls a function on a continuous basis. -- @param #CLIENT self -- @param #function CallBack Function. +-- @return #CLIENT function CLIENT:Alive( CallBack ) self:F() self.ClientAlive2 = false self.ClientCallBack = CallBack - self.AliveCheckFunction = routines.scheduleFunction( self._AliveCheckCallBack, { self }, timer.getTime() + 1, 5 ) + self.AliveCheckScheduler = routines.scheduleFunction( self._AliveCheckScheduler, { self }, timer.getTime() + 1, 5 ) return self end @@ -97,7 +120,7 @@ end --- @param #CLIENT self -function CLIENT:_AliveCheckCallBack() +function CLIENT:_AliveCheckScheduler() self:F( { self.ClientName, self.ClientAlive2 } ) if self:IsAlive() then @@ -115,6 +138,7 @@ end --- Return the DCSGroup of a Client. -- This function is modified to deal with a couple of bugs in DCS 1.5.3 +-- @param #CLIENT self -- @return DCSGroup#Group function CLIENT:GetDCSGroup() self:F3() @@ -185,9 +209,12 @@ function CLIENT:GetDCSGroup() end +-- TODO: Check DCSTypes#Group.ID +--- Get the group ID of the client. +-- @param #CLIENT self +-- @return DCSTypes#Group.ID function CLIENT:GetClientGroupID() - if not self.ClientGroupID then local ClientGroup = self:GetDCSGroup() if ClientGroup and ClientGroup:isExist() then @@ -202,6 +229,9 @@ function CLIENT:GetClientGroupID() end +--- Get the name of the group of the client. +-- @param #CLIENT self +-- @return #string function CLIENT:GetClientGroupName() if not self.ClientGroupName then @@ -217,7 +247,8 @@ function CLIENT:GetClientGroupName() return self.ClientGroupName end ---- Returns the Unit of the @{CLIENT}. +--- Returns the UNIT of the CLIENT. +-- @param #CLIENT self -- @return Unit#UNIT function CLIENT:GetClientGroupUnit() self:F() @@ -231,8 +262,9 @@ function CLIENT:GetClientGroupUnit() end end ---- Returns the DCSUnit of the @{CLIENT}. --- @return DCSUnit +--- Returns the DCSUnit of the CLIENT. +-- @param #CLIENT self +-- @return DCSTypes#Unit function CLIENT:GetClientGroupDCSUnit() self:F2() @@ -245,13 +277,15 @@ function CLIENT:GetClientGroupDCSUnit() end end +-- TODO what is this??? check. possible double function. function CLIENT:GetUnit() self:F() return UNIT:New( self:GetClientGroupDCSUnit() ) end ---- Returns the Point of the @{CLIENT}. +--- Returns the position of the CLIENT in @{DCSTypes#Vec2} format.. +-- @param #CLIENT self -- @return DCSTypes#Vec2 function CLIENT:GetPointVec2() self:F() @@ -273,8 +307,9 @@ function CLIENT:GetPointVec2() end ---- Returns the Position of the @{CLIENT}. --- @return DCSTypes#Position +--- Returns the position of the CLIENT in @{DCSTypes#Vec3} format. +-- @param #CLIENT self +-- @return DCSTypes#Vec3 function CLIENT:ClientPosition() self:F() @@ -289,7 +324,8 @@ function CLIENT:ClientPosition() return nil end ---- Returns the altitude of the @{CLIENT}. +--- Returns the altitude of the CLIENT. +-- @param #CLIENT self -- @return DCSTypes#Distance function CLIENT:GetAltitude() self:F() @@ -307,33 +343,17 @@ function CLIENT:GetAltitude() end ---- Transport defines that the Client is a Transport. --- @return CLIENT -function CLIENT:Transport() - self:F() - - self.ClientTransport = true - return self -end - ---- AddBriefing adds a briefing to a Client when a Player joins a Mission. --- @param string ClientBriefing is the text defining the Mission briefing. --- @return CLIENT -function CLIENT:AddBriefing( ClientBriefing ) - self:F() - self.ClientBriefing = ClientBriefing - return self -end - ---- IsTransport returns if a Client is a transport. --- @return bool +--- Evaluates if the CLIENT is a transport. +-- @param #CLIENT self +-- @return #boolean true is a transport. function CLIENT:IsTransport() self:F() return self.ClientTransport end ---- ShowCargo shows the @{CARGO} within the CLIENT to the Player. --- The @{CARGO} is shown throught the MESSAGE system of DCS World. +--- Shows the @{Cargo#CARGO} contained within the CLIENT to the player as a message. +-- The @{Cargo#CARGO} is shown using the @{Message#MESSAGE} distribution system. +-- @param #CLIENT self function CLIENT:ShowCargo() self:F() @@ -353,18 +373,20 @@ function CLIENT:ShowCargo() end ---- SwitchMessages is a local function called by the DCS World Menu system to switch off messages. +-- TODO (1) I urgently need to revise this. +--- A local function called by the DCS World Menu system to switch off messages. function CLIENT.SwitchMessages( PrmTable ) PrmTable[1].MessageSwitch = PrmTable[2] end ---- Message is the key Message driver for the CLIENT class. +--- The main message driver for the CLIENT. -- This function displays various messages to the Player logged into the CLIENT through the DCS World Messaging system. --- @param string Message is the text describing the message. --- @param number MessageDuration is the duration in seconds that the Message should be displayed. --- @param string MessageId is a text identifying the Message in the MessageQueue. The Message system overwrites Messages with the same MessageId --- @param string MessageCategory is the category of the message (the title). --- @param number MessageInterval is the interval in seconds between the display of the Message when the CLIENT is in the air. +-- @param #CLIENT self +-- @param #string Message is the text describing the message. +-- @param #number MessageDuration is the duration in seconds that the Message should be displayed. +-- @param #string MessageId is a text identifying the Message in the MessageQueue. The Message system overwrites Messages with the same MessageId +-- @param #string MessageCategory is the category of the message (the title). +-- @param #number MessageInterval is the interval in seconds between the display of the @{Message#MESSAGE} when the CLIENT is in the air. function CLIENT:Message( Message, MessageDuration, MessageId, MessageCategory, MessageInterval ) self:F()