Controllable Detection Improvements/Fixes

- Fixed bug in detection functions for optical detection (enum incorrect)
- Fixed bug in order of return values of `CONTROLLABLE:IsTargetDetected` (both hoggit and DCS are WRONG and MOOSE adopted it).

Moose Development/Moose/Core/Message.lua

@@ -75,35 +75,37 @@ MESSAGE.Type = {
 
 --- Creates a new MESSAGE object. Note that these MESSAGE objects are not yet displayed on the display panel. You must use the functions @{#MESSAGE.ToClient} or @{#MESSAGE.ToCoalition} or @{#MESSAGE.ToAll} to send these Messages to the respective recipients.
 -- @param self
--- @param #string MessageText is the text of the Message.
--- @param #number MessageDuration is a number in seconds of how long the MESSAGE should be shown on the display panel.
--- @param #string MessageCategory (optional) is a string expressing the "category" of the Message. The category will be shown as the first text in the message followed by a ": ".
+-- @param #string Text is the text of the Message.
+-- @param #number Duration Duration in seconds how long the message text is shown.
+-- @param #string Category (Optional) String expressing the "category" of the Message. The category will be shown as the first text in the message followed by a ": ".
 -- @param #boolean ClearScreen (optional) Clear all previous messages if true.
--- @return #MESSAGE
+-- @return #MESSAGE self
 -- @usage
 --
---    -- Create a series of new Messages.
---    -- MessageAll is meant to be sent to all players, for 25 seconds, and is classified as "Score".
---    -- MessageRED is meant to be sent to the RED players only, for 10 seconds, and is classified as "End of Mission", with ID "Win".
---    -- MessageClient1 is meant to be sent to a Client, for 25 seconds, and is classified as "Score", with ID "Score".
---    -- MessageClient1 is meant to be sent to a Client, for 25 seconds, and is classified as "Score", with ID "Score".
+--   -- Create a series of new Messages.
+--   -- MessageAll is meant to be sent to all players, for 25 seconds, and is classified as "Score".
+--   -- MessageRED is meant to be sent to the RED players only, for 10 seconds, and is classified as "End of Mission", with ID "Win".
+--   -- MessageClient1 is meant to be sent to a Client, for 25 seconds, and is classified as "Score", with ID "Score".
+--   -- MessageClient1 is meant to be sent to a Client, for 25 seconds, and is classified as "Score", with ID "Score".
 --   MessageAll = MESSAGE:New( "To all Players: BLUE has won! Each player of BLUE wins 50 points!",  25, "End of Mission" )
 --   MessageRED = MESSAGE:New( "To the RED Players: You receive a penalty because you've killed one of your own units", 25, "Penalty" )
 --   MessageClient1 = MESSAGE:New( "Congratulations, you've just hit a target",  25, "Score" )
 --   MessageClient2 = MESSAGE:New( "Congratulations, you've just killed a target", 25, "Score")
 --
-function MESSAGE:New( MessageText, MessageDuration, MessageCategory, ClearScreen )
+function MESSAGE:New( Text, Duration, Category, ClearScreen )
+
   local self = BASE:Inherit( self, BASE:New() )
-  self:F( { MessageText, MessageDuration, MessageCategory } )
+
+  self:F( { Text, Duration, Category } )
 
   self.MessageType = nil
 
   -- When no MessageCategory is given, we don't show it as a title... 
-  if MessageCategory and MessageCategory ~= "" then
-    if MessageCategory:sub( -1 ) ~= "\n" then
-      self.MessageCategory = MessageCategory .. ": "
+  if Category and Category ~= "" then
+    if Category:sub( -1 ) ~= "\n" then
+      self.MessageCategory = Category .. ": "
     else
-      self.MessageCategory = MessageCategory:sub( 1, -2 ) .. ":\n"
+      self.MessageCategory = Category:sub( 1, -2 ) .. ":\n"
     end
   else
     self.MessageCategory = ""
@@ -114,9 +116,9 @@ function MESSAGE:New( MessageText, MessageDuration, MessageCategory, ClearScreen
     self.ClearScreen = ClearScreen
   end
 
-  self.MessageDuration = MessageDuration or 5
+  self.MessageDuration = Duration or 5
   self.MessageTime = timer.getTime()
-  self.MessageText = MessageText:gsub( "^\n", "", 1 ):gsub( "\n$", "", 1 )
+  self.MessageText = Text:gsub( "^\n", "", 1 ):gsub( "\n$", "", 1 )
 
   self.MessageSent = false
   self.MessageGroup = false

Moose Development/Moose/DCS.lua

@@ -407,7 +407,7 @@ do -- coalition
   -- @param #table groupData Group data table.
   -- @return DCS#Group The spawned Group object.
 
-  --- Dynamically spawns a static object. See [hoggit](https://wiki.hoggitworld.com/view/DCS_func_addGroup)
+  --- Dynamically spawns a static object. See [hoggit](https://wiki.hoggitworld.com/view/DCS_func_addStaticObject)
   -- @function [parent=#coalition] addStaticObject
   -- @param #number countryId Id of the country.
   -- @param #table groupData Group data table.
@@ -420,6 +420,7 @@ end -- coalition
 
 do -- Types
 
+  --- Descriptors.
   -- @type Desc
   -- @field #number speedMax0 Max speed in meters/second at zero altitude.
   -- @field #number massEmpty Empty mass in kg.
@@ -1013,14 +1014,16 @@ do -- Spot
 end -- Spot
 
 do -- Controller
+
   --- Controller is an object that performs A.I.-tasks. Other words controller is an instance of A.I.. Controller stores current main task, active enroute tasks and behavior options. Controller performs commands. Please, read DCS A-10C GUI Manual EN.pdf chapter "Task Planning for Unit Groups", page 91 to understand A.I. system of DCS:A-10C. 
   -- 
   -- This class has 2 types of functions:
   -- 
   -- * Tasks
-  -- * Commands: Commands are instant actions those required zero time to perform. Commands may be used both for control unit/group behavior and control game mechanics. 
+  -- * Commands: Commands are instant actions those required zero time to perform. Commands may be used both for control unit/group behavior and control game mechanics.
+  -- 
   -- @type Controller
-  -- @field #Controller.Detection Detection Enum contains identifiers of surface types. 
+  -- @field #Controller.Detection Detection Enum contains identifiers of surface types.
 
   --- Enables and disables the controller.
   -- Note: Now it works only for ground / naval groups!
@@ -1079,18 +1082,18 @@ do -- Controller
 
   -- Detection
 
-  --- Enum contains identifiers of surface types. 
+  --- Enum containing detection types.
   -- @type Controller.Detection
-  -- @field VISUAL
-  -- @field OPTIC
-  -- @field RADAR
-  -- @field IRST
-  -- @field RWR
-  -- @field DLINK
+  -- @field #number VISUAL Visual detection. Numeric value 1.
+  -- @field #number OPTIC Optical detection. Numeric value 2.
+  -- @field #number RADAR Radar detection. Numeric value 4.
+  -- @field #number IRST Infra-red search and track detection. Numeric value 8.
+  -- @field #number RWR Radar Warning Receiver detection. Numeric value 16.
+  -- @field #number DLINK Data link detection. Numeric value 32.
 
   --- Detected target. 
-  -- @type DetectedTarget
-  -- @field Wrapper.Object#Object object The target
+  -- @type Controller.DetectedTarget
+  -- @field DCS#Object object The target
   -- @field #boolean visible The target is visible
   -- @field #boolean type The target type is known
   -- @field #boolean distance Distance to the target is known
@@ -1103,9 +1106,9 @@ do -- Controller
   -- @param #Controller.Detection detection Controller.Detection detection1, Controller.Detection detection2, ... Controller.Detection detectionN 
   -- @return #boolean detected True if the target is detected. 
   -- @return #boolean visible Has effect only if detected is true. True if the target is visible now. 
+  -- @return #boolean type Has effect only if detected is true. True if the target type is known.
+  -- @return #boolean distance Has effect only if detected is true. True if the distance to the target is known.
   -- @return #ModelTime lastTime Has effect only if visible is false. Last time when target was seen. 
-  -- @return #boolean type Has effect only if detected is true. True if the target type is known. 
-  -- @return #boolean distance Has effect only if detected is true. True if the distance to the target is known. 
   -- @return #Vec3 lastPos Has effect only if visible is false. Last position of the target when it was seen. 
   -- @return #Vec3 lastVel Has effect only if visible is false. Last velocity of the target when it was seen. 
 
@@ -1131,6 +1134,7 @@ end -- Controller
 
 do -- Unit
 
+  --- Unit.
   -- @type Unit
   -- @extends #CoalitionObject
   -- @field ID Identifier of an unit. It assigned to an unit by the Mission Editor automatically. 

Moose Development/Moose/Functional/Detection.lua

@@ -652,7 +652,7 @@ do -- DETECTION_BASE
 
           if DetectedObject:isExist() then
 
-            local TargetIsDetected, TargetIsVisible, TargetLastTime, TargetKnowType, TargetKnowDistance, TargetLastPos, TargetLastVelocity = DetectionUnit:IsTargetDetected(
+            local TargetIsDetected, TargetIsVisible, TargetKnowType, TargetKnowDistance, TargetLastTime, TargetLastPos, TargetLastVelocity = DetectionUnit:IsTargetDetected(
               DetectedObject,
               self.DetectVisual,
               self.DetectOptical,

Moose Development/Moose/Wrapper/Controllable.lua

@@ -3005,7 +3005,7 @@ function CONTROLLABLE:GetDetectedTargets( DetectVisual, DetectOptical, DetectRad
   if DCSControllable then
 
     local DetectionVisual = (DetectVisual and DetectVisual == true) and Controller.Detection.VISUAL or nil
-    local DetectionOptical = (DetectOptical and DetectOptical == true) and Controller.Detection.OPTICAL or nil
+    local DetectionOptical = (DetectOptical and DetectOptical == true) and Controller.Detection.OPTIC or nil
     local DetectionRadar = (DetectRadar and DetectRadar == true) and Controller.Detection.RADAR or nil
     local DetectionIRST = (DetectIRST and DetectIRST == true) and Controller.Detection.IRST or nil
     local DetectionRWR = (DetectRWR and DetectRWR == true) and Controller.Detection.RWR or nil
@@ -3039,26 +3039,27 @@ function CONTROLLABLE:GetDetectedTargets( DetectVisual, DetectOptical, DetectRad
   return nil
 end
 
---- Check if a target is detected.
+--- Check if a DCS object (unit or static) is detected by the controllable. 
+-- Note that after a target is detected it remains "detected" for a certain amount of time, even if the controllable cannot "see" the target any more with it's sensors.
 -- The optional parametes specify the detection methods that can be applied.
+-- 
 -- If **no** detection method is given, the detection will use **all** the available methods by default.
 -- If **at least one** detection method is specified, only the methods set to *true* will be used.
 -- @param #CONTROLLABLE self
 -- @param DCS#Object DCSObject The DCS object that is checked.
--- @param #CONTROLLABLE self
 -- @param #boolean DetectVisual (Optional) If *false*, do not include visually detected targets.
 -- @param #boolean DetectOptical (Optional) If *false*, do not include optically detected targets.
 -- @param #boolean DetectRadar (Optional) If *false*, do not include targets detected by radar.
 -- @param #boolean DetectIRST (Optional) If *false*, do not include targets detected by IRST.
 -- @param #boolean DetectRWR (Optional) If *false*, do not include targets detected by RWR.
 -- @param #boolean DetectDLINK (Optional) If *false*, do not include targets detected by data link.
--- @return #boolean True if target is detected.
--- @return #boolean True if target is visible by line of sight.
--- @return #number Mission time when target was detected.
--- @return #boolean True if target type is known.
--- @return #boolean True if distance to target is known.
--- @return DCS#Vec3 Last known position vector of the target.
--- @return DCS#Vec3 Last known velocity vector of the target.
+-- @return #boolean `true` if target is detected.
+-- @return #boolean `true` if target is *currently* visible by line of sight. Target must be detected (first parameter returns `true`).
+-- @return #boolean `true` if target type is known. Target must be detected (first parameter returns `true`).
+-- @return #boolean `true` if distance to target is known. Target must be detected (first parameter returns `true`).
+-- @return #number Mission time in seconds when target was last detected. Only present if the target is currently not visible (second parameter returns `false`) otherwise `nil` is returned.
+-- @return DCS#Vec3 Last known position vector of the target. Only present if the target is currently not visible (second parameter returns `false`) otherwise `nil` is returned.
+-- @return DCS#Vec3 Last known velocity vector of the target. Only present if the target is currently not visible (second parameter returns `false`) otherwise `nil` is returned.
 function CONTROLLABLE:IsTargetDetected( DCSObject, DetectVisual, DetectOptical, DetectRadar, DetectIRST, DetectRWR, DetectDLINK )
   self:F2( self.ControllableName )
 
@@ -3067,25 +3068,26 @@ function CONTROLLABLE:IsTargetDetected( DCSObject, DetectVisual, DetectOptical,
   if DCSControllable then
 
     local DetectionVisual = (DetectVisual and DetectVisual == true) and Controller.Detection.VISUAL or nil
-    local DetectionOptical = (DetectOptical and DetectOptical == true) and Controller.Detection.OPTICAL or nil
+    local DetectionOptical = (DetectOptical and DetectOptical == true) and Controller.Detection.OPTIC or nil
     local DetectionRadar = (DetectRadar and DetectRadar == true) and Controller.Detection.RADAR or nil
     local DetectionIRST = (DetectIRST and DetectIRST == true) and Controller.Detection.IRST or nil
     local DetectionRWR = (DetectRWR and DetectRWR == true) and Controller.Detection.RWR or nil
     local DetectionDLINK = (DetectDLINK and DetectDLINK == true) and Controller.Detection.DLINK or nil
 
     local Controller = self:_GetController()
 
-    local TargetIsDetected, TargetIsVisible, TargetLastTime, TargetKnowType, TargetKnowDistance, TargetLastPos, TargetLastVelocity
+    local TargetIsDetected, TargetIsVisible, TargetKnowType, TargetKnowDistance, TargetLastTime, TargetLastPos, TargetLastVelocity
       = Controller:isTargetDetected( DCSObject, DetectionVisual, DetectionOptical, DetectionRadar, DetectionIRST, DetectionRWR, DetectionDLINK )
 
-    return TargetIsDetected, TargetIsVisible, TargetLastTime, TargetKnowType, TargetKnowDistance, TargetLastPos, TargetLastVelocity
+    return TargetIsDetected, TargetIsVisible, TargetKnowType, TargetKnowDistance, TargetLastTime, TargetLastPos, TargetLastVelocity
   end
 
   return nil
 end
 
 --- Check if a certain UNIT is detected by the controllable.
 -- The optional parametes specify the detection methods that can be applied.
+-- 
 -- If **no** detection method is given, the detection will use **all** the available methods by default.
 -- If **at least one** detection method is specified, only the methods set to *true* will be used.
 -- @param #CONTROLLABLE self
@@ -3096,13 +3098,13 @@ end
 -- @param #boolean DetectIRST (Optional) If *false*, do not include targets detected by IRST.
 -- @param #boolean DetectRWR (Optional) If *false*, do not include targets detected by RWR.
 -- @param #boolean DetectDLINK (Optional) If *false*, do not include targets detected by data link.
--- @return #boolean True if target is detected.
--- @return #boolean True if target is visible by line of sight.
--- @return #number Mission time when target was detected.
--- @return #boolean True if target type is known.
--- @return #boolean True if distance to target is known.
--- @return DCS#Vec3 Last known position vector of the target.
--- @return DCS#Vec3 Last known velocity vector of the target.
+-- @return #boolean `true` if target is detected.
+-- @return #boolean `true` if target is *currently* visible by line of sight. Target must be detected (first parameter returns `true`).
+-- @return #boolean `true` if target type is known. Target must be detected (first parameter returns `true`).
+-- @return #boolean `true` if distance to target is known. Target must be detected (first parameter returns `true`).
+-- @return #number Mission time in seconds when target was last detected. Only present if the target is currently not visible (second parameter returns `false`) otherwise `nil` is returned.
+-- @return DCS#Vec3 Last known position vector of the target. Only present if the target is currently not visible (second parameter returns `false`) otherwise `nil` is returned.
+-- @return DCS#Vec3 Last known velocity vector of the target. Only present if the target is currently not visible (second parameter returns `false`) otherwise `nil` is returned.
 function CONTROLLABLE:IsUnitDetected( Unit, DetectVisual, DetectOptical, DetectRadar, DetectIRST, DetectRWR, DetectDLINK )
   self:F2( self.ControllableName )