Merge remote-tracking branch 'refs/remotes/origin/FlightControl' into FlightControl-task-cargo-transport

# Conflicts:
#	Moose Mission Setup/Moose Mission Update/l10n/DEFAULT/Moose.lua
#	Moose Mission Setup/Moose.lua
#	Moose Test Missions/TSK - Task Modelling/TSK-020 - Task Modelling -
Pickup/TSK-020 - Task Modelling - Pickup.miz

Moose Development/Moose/Wrapper/Group.lua

@@ -1,4 +1,6 @@
---- This module contains the GROUP class.
+--- **Wrapper** -- GROUP is a wrapper class for the DCS Class Group.
+-- 
+-- ===
 -- 
 -- The @{#GROUP} class is a wrapper class to handle the DCS Group objects:
 --
@@ -55,8 +57,6 @@
 --- 
 -- # GROUP class, extends @{Controllable#CONTROLLABLE}
 -- 
--- ## GROUP reference methods
--- 
 -- For each DCS Group object alive within a running mission, a GROUP wrapper object (instance) will be created within the _@{DATABASE} object.
 -- This is done at the beginning of the mission (when the mission starts), and dynamically when new DCS Group objects are spawned (using the @{SPAWN} class).
 --
@@ -183,19 +183,33 @@ function GROUP:GetPositionVec3() -- Overridden from POSITIONABLE:GetPositionVec3
   return nil
 end
 
---- Returns if the DCS Group is alive.
--- When the group exists at run-time, this method will return true, otherwise false.
+--- Returns if the Group is alive.
+-- The Group must:
+-- 
+--   * Exist at run-time.
+--   * Has at least one unit.
+-- 
+-- When the first @{Unit} of the Group is active, it will return true.
+-- If the first @{Unit} of the Group is inactive, it will return false.
+-- 
 -- @param #GROUP self
--- @return #boolean true if the DCS Group is alive.
+-- @return #boolean true if the Group is alive and active.
+-- @return #boolean false if the Group is alive but inactive.
+-- @return #nil if the group does not exist anymore.
 function GROUP:IsAlive()
   self:F2( self.GroupName )
 
-  local DCSGroup = self:GetDCSObject()
+  local DCSGroup = self:GetDCSObject() -- Dcs.DCSGroup#Group
 
   if DCSGroup then
-    local GroupIsAlive = DCSGroup:isExist() and DCSGroup:getUnit(1) ~= nil
-    self:T3( GroupIsAlive )
-    return GroupIsAlive
+    if DCSGroup:isExist() then
+      local DCSUnit = DCSGroup:getUnit(1) -- Dcs.DCSUnit#Unit
+      if DCSUnit then
+        local GroupIsAlive = DCSUnit:isActive()
+        self:T3( GroupIsAlive )
+        return GroupIsAlive
+      end
+    end
   end
 
   return nil
@@ -442,6 +456,7 @@ function GROUP:GetVec2()
 end
 
 --- Returns the current Vec3 vector of the first DCS Unit in the GROUP.
+-- @param #GROUP self
 -- @return Dcs.DCSTypes#Vec3 Current Vec3 of the first DCS Unit of the GROUP.
 function GROUP:GetVec3()
   self:F2( self.GroupName )
@@ -451,7 +466,65 @@ function GROUP:GetVec3()
   return GroupVec3
 end
 
+--- Returns a POINT_VEC2 object indicating the point in 2D of the first UNIT of the GROUP within the mission.
+-- @param #GROUP self
+-- @return Core.Point#POINT_VEC2 The 2D point vector of the first DCS Unit of the GROUP.
+-- @return #nil The first UNIT is not existing or alive.  
+function GROUP:GetPointVec2()
+  self:F2(self.GroupName)
 
+  local FirstUnit = self:GetUnit(1)
+  
+  if FirstUnit then
+    local FirstUnitPointVec2 = FirstUnit:GetPointVec2()
+    self:T3(FirstUnitPointVec2)
+    return FirstUnitPointVec2
+  end
+  
+  return nil
+end
+
+--- Returns a random @{DCSTypes#Vec3} vector (point in 3D of the UNIT within the mission) within a range around the first UNIT of the GROUP.
+-- @param #GROUP self
+-- @param #number Radius
+-- @return Dcs.DCSTypes#Vec3 The random 3D point vector around the first UNIT of the GROUP.
+-- @return #nil The GROUP is invalid or empty
+-- @usage 
+-- -- If Radius is ignored, returns the Dcs.DCSTypes#Vec3 of first UNIT of the GROUP
+function GROUP:GetRandomVec3(Radius)
+  self:F2(self.GroupName)
+  
+  local FirstUnit = self:GetUnit(1)
+  
+  if FirstUnit then
+    local FirstUnitRandomPointVec3 = FirstUnit:GetRandomVec3(Radius)
+    self:T3(FirstUnitRandomPointVec3)
+    return FirstUnitRandomPointVec3
+  end
+  
+  return nil
+end
+
+--- Returns the mean heading of every UNIT in the GROUP in degrees
+-- @param #GROUP self
+-- @return #number mean heading of the GROUP
+-- @return #nil The first UNIT is not existing or alive.
+function GROUP:GetHeading()
+  self:F2(self.GroupName)
+
+  local GroupSize = self:GetSize()
+  local HeadingAccumulator = 0
+  
+  if GroupSize then
+    for i = 1, GroupSize do
+      HeadingAccumulator = HeadingAccumulator + self:GetUnit(i):GetHeading()
+    end
+    return math.floor(HeadingAccumulator / GroupSize)
+  end
+  
+  return nil
+  
+end
 
 do -- Is Zone methods
 

Moose Development/Moose/Wrapper/Identifiable.lua

@@ -59,16 +59,18 @@ function IDENTIFIABLE:New( IdentifiableName )
 end
 
 --- Returns if the Identifiable is alive.  
+-- If the Identifiable is not alive, nil is returned.  
+-- If the Identifiable is alive, true is returned.  
 -- @param #IDENTIFIABLE self
 -- @return #boolean true if Identifiable is alive.
--- @return #nil The DCS Identifiable is not existing or alive.  
+-- @return #nil if the Identifiable is not existing or is not alive.  
 function IDENTIFIABLE:IsAlive()
   self:F3( self.IdentifiableName )
 
-  local DCSIdentifiable = self:GetDCSObject()
+  local DCSIdentifiable = self:GetDCSObject() -- Dcs.DCSObject#Object
   
   if DCSIdentifiable then
-    local IdentifiableIsAlive = DCSIdentifiable:isExist()
+    local IdentifiableIsAlive  = DCSIdentifiable:isExist()
     return IdentifiableIsAlive
   end 
   

Moose Development/Moose/Wrapper/Positionable.lua

@@ -135,8 +135,11 @@ end
 
 --- Returns a random @{DCSTypes#Vec3} vector within a range, indicating the point in 3D of the POSITIONABLE within the mission.
 -- @param Wrapper.Positionable#POSITIONABLE self
+-- @param #number Radius
 -- @return Dcs.DCSTypes#Vec3 The 3D point vector of the POSITIONABLE.
 -- @return #nil The POSITIONABLE is not existing or alive.  
+-- @usage 
+-- -- If Radius is ignored, returns the Dcs.DCSTypes#Vec3 of first UNIT of the GROUP
 function POSITIONABLE:GetRandomVec3( Radius )
   self:F2( self.PositionableName )
 
@@ -144,14 +147,20 @@ function POSITIONABLE:GetRandomVec3( Radius )
   
   if DCSPositionable then
     local PositionablePointVec3 = DCSPositionable:getPosition().p
-    local PositionableRandomVec3 = {}
-    local angle = math.random() * math.pi*2;
-    PositionableRandomVec3.x = PositionablePointVec3.x + math.cos( angle ) * math.random() * Radius;
-    PositionableRandomVec3.y = PositionablePointVec3.y
-    PositionableRandomVec3.z = PositionablePointVec3.z + math.sin( angle ) * math.random() * Radius;
     
-    self:T3( PositionableRandomVec3 )
-    return PositionableRandomVec3
+    if Radius then
+      local PositionableRandomVec3 = {}
+      local angle = math.random() * math.pi*2;
+      PositionableRandomVec3.x = PositionablePointVec3.x + math.cos( angle ) * math.random() * Radius;
+      PositionableRandomVec3.y = PositionablePointVec3.y
+      PositionableRandomVec3.z = PositionablePointVec3.z + math.sin( angle ) * math.random() * Radius;
+    
+      self:T3( PositionableRandomVec3 )
+      return PositionableRandomVec3
+    else 
+      self:E("Radius is nil, returning the PointVec3 of the POSITIONABLE", PositionablePointVec3)
+      return PositionablePointVec3
+    end
   end
   
   return nil
@@ -219,6 +228,7 @@ end
 --- Returns the POSITIONABLE heading in degrees.
 -- @param Wrapper.Positionable#POSITIONABLE self
 -- @return #number The POSTIONABLE heading
+-- @return #nil The POSITIONABLE is not existing or alive.
 function POSITIONABLE:GetHeading()
   local DCSPositionable = self:GetDCSObject()
 

Moose Development/Moose/Wrapper/Unit.lua

@@ -1,7 +1,7 @@
---- This module contains the UNIT class.
+--- **Wrapper** - UNIT is a wrapper class for the DCS Class Unit.
+-- 
+-- ===
 -- 
--- 1) @{#UNIT} class, extends @{Controllable#CONTROLLABLE}
--- ===========================================================
 -- The @{#UNIT} class is a wrapper class to handle the DCS Unit objects:
 -- 
 --  * Support all DCS Unit APIs.
@@ -9,9 +9,14 @@
 --  * Handle local Unit Controller.
 --  * Manage the "state" of the DCS Unit.
 --  
+-- @module Unit
+
+--- @type UNIT
+-- @extends Wrapper.Controllable#CONTROLLABLE
+
+--- 
+-- # UNIT class, extends @{Controllable#CONTROLLABLE}
 -- 
--- 1.1) UNIT reference methods
--- ----------------------
 -- For each DCS Unit object alive within a running mission, a UNIT wrapper object (instance) will be created within the _@{DATABASE} object.
 -- This is done at the beginning of the mission (when the mission starts), and dynamically when new DCS Unit objects are spawned (using the @{SPAWN} class).
 --  
@@ -29,15 +34,15 @@
 --  
 -- IMPORTANT: ONE SHOULD NEVER SANATIZE these UNIT OBJECT REFERENCES! (make the UNIT object references nil).
 -- 
--- 1.2) DCS UNIT APIs
--- ------------------
+-- ## DCS UNIT APIs
+-- 
 -- The DCS Unit APIs are used extensively within MOOSE. The UNIT class has for each DCS Unit API a corresponding method.
 -- To be able to distinguish easily in your code the difference between a UNIT API call and a DCS Unit API call,
 -- the first letter of the method is also capitalized. So, by example, the DCS Unit method @{DCSWrapper.Unit#Unit.getName}()
 -- is implemented in the UNIT class as @{#UNIT.GetName}().
 -- 
--- 1.3) Smoke, Flare Units
--- -----------------------
+-- ## Smoke, Flare Units
+-- 
 -- The UNIT class provides methods to smoke or flare units easily. 
 -- The @{#UNIT.SmokeBlue}(), @{#UNIT.SmokeGreen}(),@{#UNIT.SmokeOrange}(), @{#UNIT.SmokeRed}(), @{#UNIT.SmokeRed}() methods
 -- will smoke the unit in the corresponding color. Note that smoking a unit is done at the current position of the DCS Unit. 
@@ -45,36 +50,29 @@
 -- The @{#UNIT.FlareGreen}(), @{#UNIT.FlareRed}(), @{#UNIT.FlareWhite}(), @{#UNIT.FlareYellow}() 
 -- methods will fire off a flare in the air with the corresponding color. Note that a flare is a one-off shot and its effect is of very short duration.
 -- 
--- 1.4) Location Position, Point
--- -----------------------------
+-- ## Location Position, Point
+-- 
 -- The UNIT class provides methods to obtain the current point or position of the DCS Unit.
 -- The @{#UNIT.GetPointVec2}(), @{#UNIT.GetVec3}() will obtain the current **location** of the DCS Unit in a Vec2 (2D) or a **point** in a Vec3 (3D) vector respectively.
 -- If you want to obtain the complete **3D position** including ori<72>ntation and direction vectors, consult the @{#UNIT.GetPositionVec3}() method respectively.
 -- 
--- 1.5) Test if alive
--- ------------------
+-- ## Test if alive
+-- 
 -- The @{#UNIT.IsAlive}(), @{#UNIT.IsActive}() methods determines if the DCS Unit is alive, meaning, it is existing and active.
 -- 
--- 1.6) Test for proximity
--- -----------------------
+-- ## Test for proximity
+-- 
 -- The UNIT class contains methods to test the location or proximity against zones or other objects.
 -- 
--- ### 1.6.1) Zones
+-- ### Zones
+-- 
 -- To test whether the Unit is within a **zone**, use the @{#UNIT.IsInZone}() or the @{#UNIT.IsNotInZone}() methods. Any zone can be tested on, but the zone must be derived from @{Zone#ZONE_BASE}. 
 -- 
--- ### 1.6.2) Units
+-- ### Units
+-- 
 -- Test if another DCS Unit is within a given radius of the current DCS Unit, use the @{#UNIT.OtherUnitInRadius}() method.
 -- 
--- @module Unit
--- @author FlightControl
-
-
-
-
-
---- The UNIT class
--- @type UNIT
--- @extends Wrapper.Controllable#CONTROLLABLE
+-- @field #UNIT UNIT
 UNIT = {
 	ClassName="UNIT",
 }
@@ -216,7 +214,7 @@ function UNIT:ReSpawn( SpawnVec3, Heading )
   end
 
   -- Remove obscolete units from the group structure
-  i = 1
+  local i = 1
   while i <= #SpawnGroupTemplate.units do
 
     local UnitTemplateData = SpawnGroupTemplate.units[i]
@@ -252,6 +250,27 @@ function UNIT:IsActive()
   return nil
 end
 
+--- Returns if the Unit is alive.  
+-- If the Unit is not alive, nil is returned.  
+-- If the Unit is alive and active, true is returned.    
+-- If the Unit is alive but not active, false is returned.  
+-- @param #UNIT self
+-- @return #boolean true if Unit is alive and active.
+-- @return #boolean false if Unit is alive but not active.
+-- @return #nil if the Unit is not existing or is not alive.  
+function UNIT:IsAlive()
+  self:F3( self.UnitName )
+
+  local DCSUnit = self:GetDCSObject() -- Dcs.DCSUnit#Unit
+  
+  if DCSUnit then
+    local UnitIsAlive  = DCSUnit:isExist() and DCSUnit:isActive()
+    return UnitIsAlive
+  end 
+  
+  return nil
+end
+
 
 
 --- Returns the Unit's callsign - the localized string.