Documentation

Embedded/Moose_Embedded.lua

@@ -15263,6 +15263,40 @@ function ESCORT:_ReportTargetsScheduler()
   end
 end
 --- Provides missile training functions.
+--
+-- @{#MISSILETRAINER} class
+-- ========================
+-- The @{#MISSILETRAINER} class uses the DCS world messaging system to be alerted of any missiles fired, and when a missile would hit your aircraft,
+-- the class will destroy the missile within a certain range, to avoid damage to your aircraft.
+-- It suports the following functionality:
+--
+--  * Track the missiles fired at you and other players, providing bearing and range information of the missiles towards the airplanes.
+--  * Provide alerts of missile launches, including detailed information of the units launching, including bearing, range …
+--  * Provide alerts when a missile would have killed your aircraft.
+--  * Provide alerts when the missile self destructs.
+--  * Enable / Disable and Configure the Missile Trainer using the various menu options.
+--
+-- MISSILETRAINER construction methods:
+-- ====================================
+-- Create a new MISSILETRAINER object with the @{#MISSILETRAINER.New} method:
+--
+--   * @{#MISSILETRAINER.New}: Creates a new MISSILETRAINER object taking the maximum distance to your aircraft to evaluate when a missile needs to be destroyed.
+--
+-- MISSILETRAINER will collect each unit declared in the mission with a skill level "Client" and "Player", and will monitor the missiles shot at those.
+--
+-- MISSILETRAINER initialization methods:
+-- ======================================
+-- A MISSILETRAINER object will behave differently based on the usage of initialization methods:
+--
+--  * @{#MISSILETRAINER.InitMessagesOnOff}: Sets by default the display of any message to be ON or OFF.
+--  * @{#MISSILETRAINER.InitTrackingToAll}: Sets by default the missile tracking report for all players or only for those missiles targetted to you.
+--  * @{#MISSILETRAINER.InitTrackingOnOff}: Sets by default the display of missile tracking report to be ON or OFF.
+--  * @{#MISSILETRAINER.InitAlertsToAll}: Sets by default the display of alerts to be shown to all players or only to you.
+--  * @{#MISSILETRAINER.InitAlertsHitsOnOff}: Sets by default the display of hit alerts ON or OFF.
+--  * @{#MISSILETRAINER.InitAlertsLaunchesOnOff}: Sets by default the display of launch alerts ON or OFF.
+--  * @{#MISSILETRAINER.InitRangeOnOff}: Sets by default the display of range information of missiles ON of OFF.
+--  * @{#MISSILETRAINER.InitBearingOnOff}: Sets by default the display of bearing information of missiles ON of OFF.
+--
 -- @module MissileTrainer
 -- @author FlightControl
 
@@ -15314,22 +15348,22 @@ function MISSILETRAINER:New( Distance )
       Client.MenuTracking = MENU_CLIENT:New( Client, "Tracking", Client.MainMenu )
       Client.MenuTrackingToAll = MENU_CLIENT_COMMAND:New( Client, "To All", Client.MenuTracking, self._MenuMessages, { MenuSelf = self, TrackingToAll = true } )
       Client.MenuTrackingToTarget = MENU_CLIENT_COMMAND:New( Client, "To Target", Client.MenuTracking, self._MenuMessages, { MenuSelf = self, TrackingToAll = false } )
-       Client.MenuTrackOn = MENU_CLIENT_COMMAND:New( Client, "Tracking On", Client.MenuTracking, self._MenuMessages, { MenuSelf = self, Tracking = true } )
+      Client.MenuTrackOn = MENU_CLIENT_COMMAND:New( Client, "Tracking On", Client.MenuTracking, self._MenuMessages, { MenuSelf = self, TrackingOnOff = true } )
-       Client.MenuTrackOff = MENU_CLIENT_COMMAND:New( Client, "Tracking Off", Client.MenuTracking, self._MenuMessages, { MenuSelf = self, Tracking = false } )
+      Client.MenuTrackOff = MENU_CLIENT_COMMAND:New( Client, "Tracking Off", Client.MenuTracking, self._MenuMessages, { MenuSelf = self, TrackingOnOff = false } )
 
       Client.MenuAlerts = MENU_CLIENT:New( Client, "Alerts", Client.MainMenu )
       Client.MenuAlertsToAll = MENU_CLIENT_COMMAND:New( Client, "To All", Client.MenuAlerts, self._MenuMessages, { MenuSelf = self, AlertsToAll = true } )
       Client.MenuAlertsToTarget = MENU_CLIENT_COMMAND:New( Client, "To Target", Client.MenuAlerts, self._MenuMessages, { MenuSelf = self, AlertsToAll = false } )
-       Client.MenuHitsOn = MENU_CLIENT_COMMAND:New( Client, "Hits On", Client.MenuAlerts, self._MenuMessages, { MenuSelf = self, AlertsHits = true } )
+      Client.MenuHitsOn = MENU_CLIENT_COMMAND:New( Client, "Hits On", Client.MenuAlerts, self._MenuMessages, { MenuSelf = self, AlertsHitsOnOff = true } )
-       Client.MenuHitsOff = MENU_CLIENT_COMMAND:New( Client, "Hits Off", Client.MenuAlerts, self._MenuMessages, { MenuSelf = self, AlertsHits = false } )
+      Client.MenuHitsOff = MENU_CLIENT_COMMAND:New( Client, "Hits Off", Client.MenuAlerts, self._MenuMessages, { MenuSelf = self, AlertsHitsOnOff = false } )
-       Client.MenuLaunchesOn = MENU_CLIENT_COMMAND:New( Client, "Launches On", Client.MenuAlerts, self._MenuMessages, { MenuSelf = self, AlertsLaunches = true } )
+      Client.MenuLaunchesOn = MENU_CLIENT_COMMAND:New( Client, "Launches On", Client.MenuAlerts, self._MenuMessages, { MenuSelf = self, AlertsLaunchesOnOff = true } )
-       Client.MenuLaunchesOff = MENU_CLIENT_COMMAND:New( Client, "Launches Off", Client.MenuAlerts, self._MenuMessages, { MenuSelf = self, AlertsLaunches = false } )
+      Client.MenuLaunchesOff = MENU_CLIENT_COMMAND:New( Client, "Launches Off", Client.MenuAlerts, self._MenuMessages, { MenuSelf = self, AlertsLaunchesOnOff = false } )
 
       Client.MenuDetails = MENU_CLIENT:New( Client, "Details", Client.MainMenu )
-       Client.MenuDetailsDistanceOn = MENU_CLIENT_COMMAND:New( Client, "Range On", Client.MenuDetails, self._MenuMessages, { MenuSelf = self, DetailsRange = true } )
+      Client.MenuDetailsDistanceOn = MENU_CLIENT_COMMAND:New( Client, "Range On", Client.MenuDetails, self._MenuMessages, { MenuSelf = self, DetailsRangeOnOff = true } )
-       Client.MenuDetailsDistanceOff = MENU_CLIENT_COMMAND:New( Client, "Range Off", Client.MenuDetails, self._MenuMessages, { MenuSelf = self, DetailsRange = false } )
+      Client.MenuDetailsDistanceOff = MENU_CLIENT_COMMAND:New( Client, "Range Off", Client.MenuDetails, self._MenuMessages, { MenuSelf = self, DetailsRangeOnOff = false } )
-       Client.MenuDetailsBearingOn = MENU_CLIENT_COMMAND:New( Client, "Bearing On", Client.MenuDetails, self._MenuMessages, { MenuSelf = self, DetailsBearing = true } )
+      Client.MenuDetailsBearingOn = MENU_CLIENT_COMMAND:New( Client, "Bearing On", Client.MenuDetails, self._MenuMessages, { MenuSelf = self, DetailsBearingOnOff = true } )
-       Client.MenuDetailsBearingOff = MENU_CLIENT_COMMAND:New( Client, "Bearing Off", Client.MenuDetails, self._MenuMessages, { MenuSelf = self, DetailsBearing = false } )
+      Client.MenuDetailsBearingOff = MENU_CLIENT_COMMAND:New( Client, "Bearing Off", Client.MenuDetails, self._MenuMessages, { MenuSelf = self, DetailsBearingOnOff = false } )
 
       Client.MenuDistance = MENU_CLIENT:New( Client, "Set distance to plane", Client.MainMenu )
       Client.MenuDistance50 = MENU_CLIENT_COMMAND:New( Client, "50 meter", Client.MenuDistance, self._MenuMessages, { MenuSelf = self, Distance = 50 / 1000 } )
@@ -15352,24 +15386,24 @@ function MISSILETRAINER:New( Distance )
     Client:Alive( _Alive )
 
   end
---	self.DB:ForEachClient( 
+  --	self.DB:ForEachClient(
---	 --- @param Client#CLIENT Client
+  --	 --- @param Client#CLIENT Client
---	 function( Client )
+  --	 function( Client )
---     
+  --
---	 end 
+  --	 end
---	)
+  --	)
 
   self.MessagesOnOff = true
 
   self.TrackingToAll = false
-  self.Tracking = true
+  self.TrackingOnOff = true
 
   self.AlertsToAll = true
-  self.AlertsHits = true
+  self.AlertsHitsOnOff = true
-  self.AlertsLaunches = true
+  self.AlertsLaunchesOnOff = true
 
-  self.DetailsRange = true
+  self.DetailsRangeOnOff = true
-  self.DetailsBearing = true
+  self.DetailsBearingOnOff = true
 
   self.TrackingMissiles = {}
 
@@ -15378,81 +15412,181 @@ function MISSILETRAINER:New( Distance )
   return self
 end
 
-function MISSILETRAINER._MenuMessages( MenuParameters )
+-- Initialization methods.
 
-  local self = MenuParameters.MenuSelf
 
-  if MenuParameters.MessagesOnOff ~= nil then
+--- Sets by default the display of any message to be ON or OFF.
-    self.MessagesOnOff = MenuParameters.MessagesOnOff
+-- @param #MISSILETRAINER self
+-- @param #boolean MessagesOnOff true or false
+-- @return #MISSILETRAINER self
+function MISSILETRAINER:InitMessagesOnOff( MessagesOnOff )
+  self:F( MessagesOnOff )
+
+  self.MessagesOnOff = MessagesOnOff
   if self.MessagesOnOff == true then
     MESSAGE:New( "Messages ON", "Menu", 15, "ID" ):ToAll()
   else
     MESSAGE:New( "Messages OFF", "Menu", 15, "ID" ):ToAll()
   end
-  end
 
-  if MenuParameters.TrackingToAll ~= nil then
+  return self
-    self.TrackingToAll = MenuParameters.TrackingToAll
+end
+
+--- Sets by default the missile tracking report for all players or only for those missiles targetted to you.
+-- @param #MISSILETRAINER self
+-- @param #boolean TrackingToAll true or false
+-- @return #MISSILETRAINER self
+function MISSILETRAINER:InitTrackingToAll( TrackingToAll )
+  self:F( TrackingToAll )
+
+  self.TrackingToAll = TrackingToAll
   if self.TrackingToAll == true then
     MESSAGE:New( "Missile tracking to all players ON", "Menu", 15, "ID" ):ToAll()
   else
     MESSAGE:New( "Missile tracking to all players OFF", "Menu", 15, "ID" ):ToAll()
   end
-  end
 
-  if MenuParameters.Tracking ~= nil then
+  return self
-    self.Tracking = MenuParameters.Tracking
+end
-    if self.Tracking == true then
+
+--- Sets by default the display of missile tracking report to be ON or OFF.
+-- @param #MISSILETRAINER self
+-- @param #boolean TrackingOnOff true or false
+-- @return #MISSILETRAINER self
+function MISSILETRAINER:InitTrackingOnOff( TrackingOnOff )
+  self:F( TrackingOnOff )
+
+  self.TrackingOnOff = TrackingOnOff
+  if self.TrackingOnOff == true then
     MESSAGE:New( "Missile tracking ON", "Menu", 15, "ID" ):ToAll()
   else
     MESSAGE:New( "Missile tracking OFF", "Menu", 15, "ID" ):ToAll()
   end
-  end
 
-  if MenuParameters.AlertsToAll ~= nil then
+  return self
-    self.AlertsToAll = MenuParameters.AlertsToAll
+end
+
+--- Sets by default the display of alerts to be shown to all players or only to you.
+-- @param #MISSILETRAINER self
+-- @param #boolean AlertsToAll true or false
+-- @return #MISSILETRAINER self
+function MISSILETRAINER:InitAlertsToAll( AlertsToAll )
+  self:F( AlertsToAll )
+
+  self.AlertsToAll = AlertsToAll
   if self.AlertsToAll == true then
     MESSAGE:New( "Alerts to all players ON", "Menu", 15, "ID" ):ToAll()
   else
     MESSAGE:New( "Alerts to all players OFF", "Menu", 15, "ID" ):ToAll()
   end
-  end
 
-  if MenuParameters.AlertsHits ~= nil then
+  return self
-    self.AlertsHits = MenuParameters.AlertsHits
+end
-    if self.AlertsHits == true then
+
+--- Sets by default the display of hit alerts ON or OFF.
+-- @param #MISSILETRAINER self
+-- @param #boolean AlertsHitsOnOff true or false
+-- @return #MISSILETRAINER self
+function MISSILETRAINER:InitAlertsHitsOnOff( AlertsHitsOnOff )
+  self:F( AlertsHitsOnOff )
+
+  self.AlertsHitsOnOff = AlertsHitsOnOff
+  if self.AlertsHitsOnOff == true then
     MESSAGE:New( "Alerts Hits ON", "Menu", 15, "ID" ):ToAll()
   else
     MESSAGE:New( "Alerts Hits OFF", "Menu", 15, "ID" ):ToAll()
   end
-  end
 
-  if MenuParameters.AlertsLaunches ~= nil then
+  return self
-    self.AlertsLaunches = MenuParameters.AlertsLaunches
+end
-    if self.AlertsLaunches == true then
+
+--- Sets by default the display of launch alerts ON or OFF.
+-- @param #MISSILETRAINER self
+-- @param #boolean AlertsLaunchesOnOff true or false
+-- @return #MISSILETRAINER self
+function MISSILETRAINER:InitAlertsLaunchesOnOff( AlertsLaunchesOnOff )
+  self:F( AlertsLaunchesOnOff )
+
+  self.AlertsLaunchesOnOff = AlertsLaunchesOnOff
+  if self.AlertsLaunchesOnOff == true then
     MESSAGE:New( "Alerts Launches ON", "Menu", 15, "ID" ):ToAll()
   else
     MESSAGE:New( "Alerts Launches OFF", "Menu", 15, "ID" ):ToAll()
   end
 
-  end
+  return self
+end
 
-  if MenuParameters.DetailsRange ~= nil then
+--- Sets by default the display of range information of missiles ON of OFF.
-    self.DetailsRange = MenuParameters.DetailsRange
+-- @param #MISSILETRAINER self
-    if self.DetailsRange == true then
+-- @param #boolean DetailsRangeOnOff true or false
+-- @return #MISSILETRAINER self
+function MISSILETRAINER:InitRangeOnOff( DetailsRangeOnOff )
+  self:F( DetailsRangeOnOff )
+
+  self.DetailsRangeOnOff = DetailsRangeOnOff
+  if self.DetailsRangeOnOff == true then
     MESSAGE:New( "Range display ON", "Menu", 15, "ID" ):ToAll()
   else
     MESSAGE:New( "Range display OFF", "Menu", 15, "ID" ):ToAll()
   end
-  end
 
-  if MenuParameters.DetailsBearing ~= nil then
+  return self
-    self.DetailsBearing = MenuParameters.DetailsBearing
+end
-    if self.DetailsBearing == true then
+
+--- Sets by default the display of bearing information of missiles ON of OFF.
+-- @param #MISSILETRAINER self
+-- @param #boolean DetailsBearingOnOff true or false
+-- @return #MISSILETRAINER self
+function MISSILETRAINER:InitBearingOnOff( DetailsBearingOnOff )
+  self:F( DetailsBearingOnOff )
+
+  self.DetailsBearingOnOff = DetailsBearingOnOff
+  if self.DetailsBearingOnOff == true then
     MESSAGE:New( "Bearing display OFF", "Menu", 15, "ID" ):ToAll()
   else
     MESSAGE:New( "Bearing display OFF", "Menu", 15, "ID" ):ToAll()
   end
+
+  return self
+end
+
+-- Menu functions
+
+function MISSILETRAINER._MenuMessages( MenuParameters )
+
+  local self = MenuParameters.MenuSelf
+
+  if MenuParameters.MessagesOnOff ~= nil then
+    self:InitMessagesOnOff( MenuParameters.MessagesOnOff )
+  end
+
+  if MenuParameters.TrackingToAll ~= nil then
+    self:InitTrackingToAll( MenuParameters.TrackingToAll )
+  end
+
+  if MenuParameters.TrackingOnOff ~= nil then
+    self:InitTrackingOnOff( MenuParameters.TrackingOnOff )
+  end
+
+  if MenuParameters.AlertsToAll ~= nil then
+    self:InitAlertsToAll( MenuParameters.AlertsToAll )
+  end
+
+  if MenuParameters.AlertsHitsOnOff ~= nil then
+    self:InitAlertsHitsOnOff( MenuParameters.AlertsHitsOnOff )
+  end
+
+  if MenuParameters.AlertsLaunchesOnOff ~= nil then
+    self:InitAlertsLaunchesOnOff( MenuParameters.AlertsLaunchesOnOff )
+  end
+
+  if MenuParameters.DetailsRangeOnOff ~= nil then
+    self:InitRangeOnOff( MenuParameters.DetailsRangeOnOff )
+  end
+
+  if MenuParameters.DetailsBearingOnOff ~= nil then
+    self:InitBearingOnOff( MenuParameters.DetailsBearingOnOff )
   end
 
   if MenuParameters.Distance ~= nil then
@@ -15487,13 +15621,13 @@ function MISSILETRAINER:_EventShot( Event )
     local TrainerSourceUnit = UNIT:New(TrainerSourceDCSUnit)
     local TrainerTargetUnit = UNIT:New(TrainerTargetDCSUnit)
 
-    if self.MessagesOnOff and self.AlertsLaunches then
+    if self.MessagesOnOff and self.AlertsLaunchesOnOff then
 
       local Message = MESSAGE:New(
         string.format( "%s launched a %s",
           TrainerSourceUnit:GetTypeName(),
           TrainerWeaponName
-        ) .. self:AddRange( Client, TrainerWeapon ) .. self:AddBearing( Client, TrainerWeapon ),"Launch Alert", 5, "ID" )  
+        ) .. self:_AddRange( Client, TrainerWeapon ) .. self:_AddBearing( Client, TrainerWeapon ),"Launch Alert", 5, "ID" )
 
       if self.AlertsToAll then
         Message:ToAll()
@@ -15514,11 +15648,11 @@ function MISSILETRAINER:_EventShot( Event )
   end
 end
 
-function MISSILETRAINER:AddRange( Client, TrainerWeapon )
+function MISSILETRAINER:_AddRange( Client, TrainerWeapon )
 
   local RangeText = ""
 
-  if self.DetailsRange then
+  if self.DetailsRangeOnOff then
 
     local PositionMissile = TrainerWeapon:getPoint()
     local PositionTarget = Client:GetPositionVec3()
@@ -15534,11 +15668,11 @@ function MISSILETRAINER:AddRange( Client, TrainerWeapon )
   return RangeText
 end
 
-function MISSILETRAINER:AddBearing( Client, TrainerWeapon )
+function MISSILETRAINER:_AddBearing( Client, TrainerWeapon )
 
   local BearingText = ""
 
-  if self.DetailsBearing then
+  if self.DetailsBearingOnOff then
 
     local PositionMissile = TrainerWeapon:getPoint()
     local PositionTarget = Client:GetPositionVec3()
@@ -15562,10 +15696,6 @@ end
 
 ---
 -- @param #MISSILETRAINER self
--- @param Unit#UNIT TrainerSourceDCSUnit
--- @param DCSWeapon#Weapon TrainerWeapon
--- @param Unit#UNIT TrainerTargetDCSUnit
--- @param Client#CLIENT Client
 function MISSILETRAINER:_TrackMissiles()
   self:F2()
 
@@ -15608,7 +15738,7 @@ function MISSILETRAINER:_TrackMissiles()
           if Distance <= self.Distance then
             -- Hit alert
             TrainerWeapon:destroy()
-            if self.MessagesOnOff and self.AlertsHits then
+            if self.MessagesOnOff and self.AlertsHitsOnOff then
 
               self:T( "killed" )
 
@@ -15640,20 +15770,20 @@ function MISSILETRAINER:_TrackMissiles()
                 if ClientData.MessageToClient == "" then
                   ClientData.MessageToClient = "Missiles to You:\n"
                 end
-                ClientData.MessageToClient = ClientData.MessageToClient .. TrackingTo .. self:AddRange( ClientData.Client, TrainerWeapon ) .. self:AddBearing( ClientData.Client, TrainerWeapon ) .. "\n"
+                ClientData.MessageToClient = ClientData.MessageToClient .. TrackingTo .. self:_AddRange( ClientData.Client, TrainerWeapon ) .. self:_AddBearing( ClientData.Client, TrainerWeapon ) .. "\n"
               else
                 if self.TrackingToAll then
                   if ClientData.MessageToAll == "" then
                     ClientData.MessageToAll = "Missiles to other Players:\n"
                   end
-                  ClientData.MessageToAll = ClientData.MessageToAll .. TrackingTo .. self:AddRange( ClientData.Client, TrainerWeapon ) .. self:AddBearing( ClientData.Client, TrainerWeapon ) .. " ( " .. TrainerTargetUnit:GetPlayerName()  ..   " )\n"
+                  ClientData.MessageToAll = ClientData.MessageToAll .. TrackingTo .. self:_AddRange( ClientData.Client, TrainerWeapon ) .. self:_AddBearing( ClientData.Client, TrainerWeapon ) .. " ( " .. TrainerTargetUnit:GetPlayerName()  ..   " )\n"
                 end
               end
             end
           end
         else
           if not ( TrainerWeapon and TrainerWeapon:isExist() ) then
-            if self.MessagesOnOff and self.AlertsLaunches then
+            if self.MessagesOnOff and self.AlertsLaunchesOnOff then
               -- Weapon does not exist anymore. Delete from Table
               local Message = MESSAGE:New(
                 string.format( "%s launched by %s self destructed!",
@@ -15675,7 +15805,7 @@ function MISSILETRAINER:_TrackMissiles()
       end
     end
 
-    if self.MessagesOnOff and self.Tracking and ShowMessages then
+    if self.MessagesOnOff and self.TrackingOnOff and ShowMessages then
       if ClientData.MessageToClient ~= "" or ClientData.MessageToAll ~= "" then
         local Message = MESSAGE:New( ClientData.MessageToClient .. ClientData.MessageToAll, "Tracking", 1, "ID" ):ToClient( Client )
       end