Added lots of DCS functions, reworked to the UNIT class

To enable tracing, error checking etc...

Moose/Unit.lua

@@ -58,57 +58,335 @@ function UNIT:New( DCSUnit )
 	local self = BASE:Inherit( self, BASE:New() )
 	self:F( DCSUnit )
 
-	self.DCSUnit = DCSUnit
 	if DCSUnit then
   	self.UnitName = DCSUnit:getName()
-  	self.UnitID = DCSUnit:getID()
+  	return self
   end
 
+  self.UnitName = nil
+	return nil
+end
+
+--- Create a new UNIT from a Unit Name.
+-- @param #UNIT self
+-- @param #string Unit Name
+-- @return Unit#UNIT
+function UNIT:NewFromName( UnitName )
+  local self = BASE:Inherit( self, BASE:New() )
+  self:F( UnitName )
+
+  local DCSUnit = Unit.getByName( UnitName )
+  if DCSUnit then
+    self.UnitName = DCSUnit:getName()
     return self
+  end
+
+  self.UnitName = nil -- Sanitize
+  return nil
 end
 
-function UNIT:IsAlive()
-	self:F( self.UnitName )
-	
-	return ( self.DCSUnit and self.DCSUnit:isExist() )
-end
-
-
 function UNIT:GetDCSUnit()
-	self:F( self.DCSUnit )
+  local DCSUnit = Unit.getByName( self.UnitName )
   
-	return self.DCSUnit
+  if DCSUnit then
+    return DCSUnit
+  end
+    
+  return nil
 end
 
-function UNIT:GetID()
+--- Returns coalition of the object.
-	self:F( self.UnitID )
+-- @param Unit#UNIT self
+-- @return #DCSCoalitionObject#coalition.side
+function UNIT:GetCoalition()
+  self:F( self.UnitName )
+
+  local DCSUnit = self:GetDCSUnit()
+  
+  if DCSUnit then
+    local UnitCoalition = DCSUnit:getCoalition()
+    self:T( UnitCoalition )
+    return UnitCoalition
+  end 
+  
+  return nil
 
-	return self.UnitID
 end
 
-
+--- Returns unit object by the name assigned to the unit in Mission Editor. 
+-- If there is unit with such name or the unit is destroyed the function will return nil. 
+-- The function provides access to non-activated units too.
+--   
 function UNIT:GetName()
   self:F( self.UnitName )
 
-	return self.UnitName
+  local DCSUnit = self:GetDCSUnit()
+  
+  if DCSUnit then
+    local UnitName = self.UnitName
+    return UnitName
+  end 
+  
+  return nil
 end
 
+
+--- Returns if the unit is alive.
+-- @param Unit#UNIT self
+-- @return #boolean true if Unit is alive.
+function UNIT:IsAlive()
+  self:F( self.UnitName )
+
+  local DCSUnit = self:GetDCSUnit()
+  
+  if DCSUnit then
+    local UnitIsAlive = DCSUnit:isExist()
+    return UnitIsAlive
+  end	
+	
+	return nil
+end
+
+--- Returns if the unit is activated.
+-- @param Unit#UNIT self
+-- @return #boolean true if Unit is activated.
+function UNIT:IsActive()
+  self:F( self.UnitName )
+
+  local DCSUnit = self:GetDCSUnit()
+  
+  if DCSUnit then
+  
+    local UnitIsActive = DCSUnit:isActive()
+    return UnitIsActive 
+  end
+
+  return nil
+end
+
+--- Returns name of the player that control the unit or nil if the unit is controlled by A.I.
+-- @param Unit#UNIT self
+-- @return #string Player Name
 function UNIT:GetPlayerName()
   self:F( self.UnitName )
 
-  local DCSUnit = Unit.getByName( self.UnitName )
+  local DCSUnit = self:GetDCSUnit()
+  
+  if DCSUnit then
   
     local PlayerName = DCSUnit:getPlayerName()
     if PlayerName == nil then
       PlayerName = ""
     end
-  
     return PlayerName
+  end
+
+  return nil
 end
+
+--- Returns the unit's unique identifier.
+-- @param Unit#UNIT self
+-- @return DCSUnit#Unit.ID Unit ID
+function UNIT:GetID()
+  self:F( self.UnitName )
+
+  local DCSUnit = self:GetDCSUnit()
+  
+  if DCSUnit then
+    local UnitID = DCSUnit:getID()
+    return UnitID
+  end	
+
+  return nil
+end
+
+--- Returns the unit's number in the group. 
+-- The number is the same number the unit has in ME. 
+-- It may not be changed during the mission. 
+-- If any unit in the group is destroyed, the numbers of another units will not be changed.
+-- @param Unit#UNIT self
+-- @return #number The Unit number. 
+function UNIT:GetNumber()
+  self:F( self.UnitName )
+
+  local DCSUnit = self:GetDCSUnit()
+  
+  if DCSUnit then
+    local UnitNumber = DCSUnit:getNumber()
+    return UnitNumber
+  end
+
+  return nil
+end
+
+--- Returns the unit's group if it exist and nil otherwise.
+-- @param Unit#UNIT self
+-- @return Group#GROUP The Group of the Unit.
+function UNIT:GetGroup()
+  self:F( self.UnitName )
+
+  local DCSUnit = self:GetDCSUnit()
+  
+  if DCSUnit then
+    local UnitGroup = DCSUnit:getGroup()
+    return UnitGroup
+  end
+
+  return nil
+end
+
+
+--- Returns the unit's callsign - the localized string.
+-- @param Unit#UNIT self
+-- @return #string The Callsign of the Unit.
+function UNIT:GetCallSign()
+  self:F( self.UnitName )
+
+  local DCSUnit = self:GetDCSUnit()
+  
+  if DCSUnit then
+    local UnitCallSign = DCSUnit:getCallsign()
+    return UnitCallSign
+  end
+  
+  return nil
+end
+
+--- Returns the unit's health. Dead units has health <= 1.0.
+-- @param Unit#UNIT self
+-- @return #number The Unit's health value.
+function UNIT:GetLife()
+  self:F( self.UnitName )
+
+  local DCSUnit = self:GetDCSUnit()
+  
+  if DCSUnit then
+    local UnitLife = DCSUnit:getLife()
+    return UnitLife
+  end
+  
+  return nil
+end
+
+--- Returns the Unit's initial health.
+-- @param Unit#UNIT self
+-- @return #number The Unit's initial health value.
+function UNIT:GetLife0()
+  self:F( self.UnitName )
+
+  local DCSUnit = self:GetDCSUnit()
+  
+  if DCSUnit then
+    local UnitLife0 = DCSUnit:getLife0()
+    return UnitLife0
+  end
+  
+  return nil
+end
+
+--- Returns relative amount of fuel (from 0.0 to 1.0) the unit has in its internal tanks. If there are additional fuel tanks the value may be greater than 1.0.
+-- @param Unit#UNIT self
+-- @return #number The relative amount of fuel (from 0.0 to 1.0).
+function UNIT:GetFuel()
+  self:F( self.UnitName )
+
+  local DCSUnit = self:GetDCSUnit()
+  
+  if DCSUnit then
+    local UnitFuel = DCSUnit:getFuel()
+    return UnitFuel
+  end
+  
+  return nil
+end
+
+--- Returns the Unit's ammunition.
+-- @param Unit#UNIT self
+-- @return DCSUnit#Unit.Ammo
+function UNIT:GetAmmo()
+  self:F( self.UnitName )
+
+  local DCSUnit = self:GetDCSUnit()
+  
+  if DCSUnit then
+    local UnitAmmo = DCSUnit:getAmmo()
+    return UnitAmmo
+  end
+  
+  return nil
+end
+
+--- Returns the unit sensors.
+-- @param Unit#UNIT self
+-- @return DCSUnit#Unit.Sensors
+function UNIT:GetSensors()
+  self:F( self.UnitName )
+
+  local DCSUnit = self:GetDCSUnit()
+  
+  if DCSUnit then
+    local UnitSensors = DCSUnit:getSensors()
+    return UnitSensors
+  end
+  
+  return nil
+end
+
+-- Need to add here a function per sensortype
+--  unit:hasSensors(Unit.SensorType.RADAR, Unit.RadarType.AS)
+
+--- Returns two values:
+-- 
+--  * First value indicates if at least one of the unit's radar(s) is on.
+--  * Second value is the object of the radar's interest. Not nil only if at least one radar of the unit is tracking a target.
+-- @param Unit#UNIT self
+-- @return #boolean  Indicates if at least one of the unit's radar(s) is on.
+-- @return DCSObject#Object The object of the radar's interest. Not nil only if at least one radar of the unit is tracking a target.
+function UNIT:GetRadar()
+  self:F( self.UnitName )
+
+  local DCSUnit = self:GetDCSUnit()
+  
+  if DCSUnit then
+    local UnitRadarOn, UnitRadarObject = DCSUnit:getRadar()
+    return UnitRadarOn, UnitRadarObject
+  end
+  
+  return nil, nil
+end
+
+-- Need to add here functions to check if radar is on and which object etc.
+
+--- Returns unit descriptor. Descriptor type depends on unit category.
+-- @param Unit#UNIT self
+-- @return DCSUnit#Unit.Desc The Unit descriptor.
+function UNIT:GetDesc()
+  self:F( self.UnitName )
+
+  local DCSUnit = self:GetDCSUnit()
+  
+  if DCSUnit then
+    local UnitDesc = DCSUnit:getDesc()
+    return UnitDesc
+  end
+  
+  return nil
+end
+
+
+
 function UNIT:GetTypeName()
 	self:F( self.UnitName )
 	
-	return self.DCSUnit:getTypeName()
+  local DCSUnit = self:GetDCSUnit()
+  
+  if DCSUnit then
+    local UnitTypeName = DCSUnit:getTypeName()
+    self:T( UnitTypeName )
+    return UnitTypeName
+  end
+
+	return nil
 end
 
 function UNIT:GetPrefix()
@@ -116,22 +394,18 @@ function UNIT:GetPrefix()
 	
 	local UnitPrefix = string.match( self.UnitName, ".*#" ):sub( 1, -2 )
 	self:T( UnitPrefix )
-
 	return UnitPrefix
 end
 
 
-function UNIT:GetCallSign()
-	self:F( self.UnitName )
-	
-	return self.DCSUnit:getCallsign()
-end
-
 
 function UNIT:GetPointVec2()
   self:F( self.UnitName )
 
-	local UnitPos = self.DCSUnit:getPosition().p
+  local DCSUnit = self:GetDCSUnit()
+	
+  if DCSUnit then
+  	local UnitPos = DCSUnit:getPosition().p
   	
   	local UnitPoint = {}
   	UnitPoint.x = UnitPos.x
@@ -139,16 +413,22 @@ function UNIT:GetPointVec2()
   
   	self:T( UnitPoint )
   	return UnitPoint
+  end
+  
+  return nil
 end
 
 
 function UNIT:GetPositionVec3()
-	self:F( self.UnitName )
+  local DCSUnit = self:GetDCSUnit()
-	
-	local UnitPos = self.DCSUnit:getPosition().p
   
+  if DCSUnit then
+  	local UnitPos = DCSUnit:getPosition().p
   	self:T( UnitPos )
   	return UnitPos
+  end
+	
+	return nil
 end
 
 function UNIT:OtherUnitInRadius( AwaitUnit, Radius )
@@ -169,8 +449,18 @@ function UNIT:OtherUnitInRadius( AwaitUnit, Radius )
 	return false
 end
 
+--- Returns the Unit's Category Name as defined within the Unit's Descriptor.
+-- @param Unit#UNIT self
+-- @return #string Unit's Category Name
 function UNIT:GetCategoryName()
-  return self.CategoryName[ self.DCSUnit:getDesc().category ]
+  local DCSUnit = self:GetDCSUnit()
+  
+  if DCSUnit then
+    local UnitCategoryName = self.CategoryName[ self:GetDesc().category ]
+    return UnitCategoryName
+  end
+  
+  return nil
 end
 
 --- Signal a flare at the position of the UNIT.