Module Unit

Wrapper - UNIT is a wrapper class for the DCS Class Unit.

The #UNIT class is a wrapper class to handle the DCS Unit objects:

  • Support all DCS Unit APIs.
  • Enhance with Unit specific APIs not in the DCS Unit API set.
  • Handle local Unit Controller.
  • Manage the "state" of the DCS Unit.

Author: FlightControl

Contributions:

Global(s)

UNIT

UNIT class, extends Controllable#CONTROLLABLE

For each DCS Unit object alive within a running mission, a UNIT wrapper object (instance) will be created within the _DATABASE object.

Type UNIT

UNIT:Destroy(GenerateEvent)

Destroys the UNIT.
UNIT:Find(DCSUnit)

Finds a UNIT from the _DATABASE using a DCSUnit object.
UNIT:FindByName(UnitName)

Find a UNIT in the _DATABASE using the name of an existing DCS Unit.
UNIT:GetAmmo()

Returns the Unit's ammunition.
UNIT:GetCallsign()

Returns the Unit's callsign - the localized string.
UNIT:GetCategoryName()

Returns the category name of the #UNIT.
UNIT:GetDCSObject()
UNIT:GetFuel()

Returns relative amount of fuel (from 0.0 to 1.0) the UNIT has in its internal tanks.
UNIT:GetGroup()

Returns the unit's group if it exist and nil otherwise.
UNIT:GetLife()

Returns the unit's health.
UNIT:GetLife0()

Returns the Unit's initial health.
UNIT:GetNumber()

Returns the unit's number in the group.
UNIT:GetPlayerName()

Returns name of the player that control the unit or nil if the unit is controlled by A.I.
UNIT:GetPrefix()

Returns the prefix name of the DCS Unit.
UNIT:GetRadar()

Returns two values:

  • First value indicates if at least one of the unit's radar(s) is on.
UNIT:GetSensors()

Returns the unit sensors.
UNIT:GetThreatLevel()

Returns the Unit's A2G threat level on a scale from 1 to 10 ...
UNIT:GetUnits()

Returns a list of one Unit.
UNIT:HandleEvent(Event, EventFunction)

Subscribe to a DCS Event.
UNIT:HasSEAD()

Returns if the unit is SEADable.
UNIT:HasSensors(...)

Returns if the unit has sensors of a certain type.
UNIT:InAir()

Returns true if the UNIT is in the air.
UNIT:IsActive()

Returns if the unit is activated.
UNIT:IsAir()

Returns if the unit is of an air category.
UNIT:IsAlive()

Returns if the Unit is alive.
UNIT:IsDetected(TargetUnit)

Returns if a unit is detecting the TargetUnit.
UNIT:IsFriendly(FriendlyCoalition)

Returns if the unit is a friendly unit.
UNIT:IsGround()

Returns if the unit is of an ground category.
UNIT:IsInZone(Zone)

Returns true if the unit is within a Zone.
UNIT:IsLOS(TargetUnit)

Returns if a unit has Line of Sight (LOS) with the TargetUnit.
UNIT:IsNotInZone(Zone)

Returns true if the unit is not within a Zone.
UNIT:IsShip()

Returns if the unit is of a ship category.
UNIT:Name()

Return the name of the UNIT.
UNIT:OtherUnitInRadius(AwaitUnit, Radius)

Returns true if there is an other DCS Unit within a radius of the current 2D point of the DCS Unit.
UNIT:ReSpawnAt(Coordinate, Heading)

Respawn the Unit using a (tweaked) template of the parent Group.
UNIT:Register(UnitName)

Create a new UNIT from DCSUnit.
UNIT:ResetEvents()

Reset the subscriptions.
UNIT:UnHandleEvent(Event)

UnSubscribe to a DCS event.

Type Unit.SensorType

Unit.SensorType.IRST
Unit.SensorType.OPTIC
Unit.SensorType.RADAR
Unit.SensorType.RWR

Global(s)

#UNIT UNIT

UNIT class, extends Controllable#CONTROLLABLE

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).

The UNIT class does not contain a :New() method, rather it provides :Find() methods to retrieve the object reference using the DCS Unit or the DCS UnitName.

Another thing to know is that UNIT objects do not "contain" the DCS Unit object. The UNIT methods will reference the DCS Unit object by name when it is needed during API execution. If the DCS Unit object does not exist or is nil, the UNIT methods will return nil and log an exception in the DCS.log file.

The UNIT class provides the following functions to retrieve quickly the relevant UNIT instance:

  • UNIT.Find(): Find a UNIT instance from the _DATABASE object using a DCS Unit object.
  • UNIT.FindByName(): Find a UNIT instance from the _DATABASE object using a DCS Unit name.

IMPORTANT: ONE SHOULD NEVER SANATIZE these UNIT OBJECT REFERENCES! (make the UNIT object references nil).

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().

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. When the DCS Unit moves for whatever reason, the smoking will still continue! 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.

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�ntation and direction vectors, consult the UNIT.GetPositionVec3() method respectively.

Test if alive

The UNIT.IsAlive(), UNIT.IsActive() methods determines if the DCS Unit is alive, meaning, it is existing and active.

Test for proximity

The UNIT class contains methods to test the location or proximity against zones or other objects.

Zones range

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.

Unit range

  • Test if another DCS Unit is within a given radius of the current DCS Unit, use the UNIT.OtherUnitInRadius() method.

Test Line of Sight

  • Use the UNIT.IsLOS() method to check if the given unit is within line of sight.

Type Unit

Type UNIT

Extends Wrapper.Controllable#CONTROLLABLE

Field(s)

UNIT:Destroy(GenerateEvent)

Destroys the UNIT.

Parameter

  • #boolean GenerateEvent : (Optional) true if you want to generate a crash or dead event for the unit.

Return value

#nil: The DCS Unit is not existing or alive.

UNIT:Find(DCSUnit)

Finds a UNIT from the _DATABASE using a DCSUnit object.

Parameter

Return value

#UNIT: self

UNIT:FindByName(UnitName)

Find a UNIT in the _DATABASE using the name of an existing DCS Unit.

Parameter

  • #string UnitName : The Unit Name.

Return value

#UNIT: self

UNIT:GetAmmo()

Returns the Unit's ammunition.

Return values

  1. Dcs.DCSWrapper.Unit#Unit.Ammo:

  2. #nil: The DCS Unit is not existing or alive.

UNIT:GetCallsign()

Returns the Unit's callsign - the localized string.

Return values

  1. #string: The Callsign of the Unit.

  2. #nil: The DCS Unit is not existing or alive.

UNIT:GetCategoryName()

Returns the category name of the #UNIT.

Return value

#string: Category name = Helicopter, Airplane, Ground Unit, Ship

UNIT:GetDCSObject()

Return value

Dcs.DCSWrapper.Unit#Unit:

UNIT:GetFuel()

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.

Return values

  1. #number: The relative amount of fuel (from 0.0 to 1.0).

  2. #nil: The DCS Unit is not existing or alive.

UNIT:GetGroup()

Returns the unit's group if it exist and nil otherwise.

Return values

  1. Wrapper.Group#GROUP: The Group of the Unit.

  2. #nil: The DCS Unit is not existing or alive.

UNIT:GetLife()

Returns the unit's health.

Dead units has health <= 1.0.

Return values

  1. #number: The Unit's health value.

  2. #nil: The DCS Unit is not existing or alive.

UNIT:GetLife0()

Returns the Unit's initial health.

Return values

  1. #number: The Unit's initial health value.

  2. #nil: The DCS Unit is not existing or alive.

UNIT:GetNumber()

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.

Return values

  1. #number: The Unit number.

  2. #nil: The DCS Unit is not existing or alive.

UNIT:GetPlayerName()

Returns name of the player that control the unit or nil if the unit is controlled by A.I.

Return values

  1. #string: Player Name

  2. #nil: The DCS Unit is not existing or alive.

UNIT:GetPrefix()

Returns the prefix name of the DCS Unit.

A prefix name is a part of the name before a '#'-sign. DCS Units spawned with the SPAWN class contain a '#'-sign to indicate the end of the (base) DCS Unit name. The spawn sequence number and unit number are contained within the name after the '#' sign.

Return values

  1. #string: The name of the DCS Unit.

  2. #nil: The DCS Unit is not existing or alive.

UNIT:GetRadar()

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.

Return values

  1. #boolean: Indicates if at least one of the unit's radar(s) is on.

  2. Dcs.DCSWrapper.Object#Object: The object of the radar's interest. Not nil only if at least one radar of the unit is tracking a target.

  3. #nil: The DCS Unit is not existing or alive.

UNIT:GetSensors()

Returns the unit sensors.

Return values

  1. Dcs.DCSWrapper.Unit#Unit.Sensors:

  2. #nil: The DCS Unit is not existing or alive.

UNIT:GetThreatLevel()

Returns the Unit's A2G threat level on a scale from 1 to 10 ...

The following threat levels are foreseen:

  • Threat level 0: Unit is unarmed.
  • Threat level 1: Unit is infantry.
  • Threat level 2: Unit is an infantry vehicle.
  • Threat level 3: Unit is ground artillery.
  • Threat level 4: Unit is a tank.
  • Threat level 5: Unit is a modern tank or ifv with ATGM.
  • Threat level 6: Unit is a AAA.
  • Threat level 7: Unit is a SAM or manpad, IR guided.
  • Threat level 8: Unit is a Short Range SAM, radar guided.
  • Threat level 9: Unit is a Medium Range SAM, radar guided.
  • Threat level 10: Unit is a Long Range SAM, radar guided.
UNIT:GetUnits()

Returns a list of one Unit.

Return value

#list<Wrapper.Unit#UNIT>: A list of one Unit.

UNIT:HandleEvent(Event, EventFunction)

Subscribe to a DCS Event.

Parameters

  • Core.Event#EVENTS Event :

  • #function EventFunction : (optional) The function to be called when the event occurs for the unit.

Return value

#UNIT:

UNIT:HasSEAD()

Returns if the unit is SEADable.

Return values

  1. #boolean: returns true if the unit is SEADable.

  2. #nil: The DCS Unit is not existing or alive.

UNIT:HasSensors(...)

Returns if the unit has sensors of a certain type.

Parameter

  • ... :

Return values

  1. #boolean: returns true if the unit has specified types of sensors. This function is more preferable than Unit.getSensors() if you don't want to get information about all the unit's sensors, and just want to check if the unit has specified types of sensors.

  2. #nil: The DCS Unit is not existing or alive.

UNIT:InAir()

Returns true if the UNIT is in the air.

Return values

  1. #boolean: true if in the air.

  2. #nil: The UNIT is not existing or alive.

UNIT:IsActive()

Returns if the unit is activated.

Return values

  1. #boolean: true if Unit is activated.

  2. #nil: The DCS Unit is not existing or alive.

UNIT:IsAir()

Returns if the unit is of an air category.

If the unit is a helicopter or a plane, then this method will return true, otherwise false.

Return value

#boolean: Air category evaluation result.

UNIT:IsAlive()

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.

Return values

  1. #boolean: true if Unit is alive and active.

  2. #boolean: false if Unit is alive but not active.

  3. #nil: if the Unit is not existing or is not alive.

UNIT:IsDetected(TargetUnit)

Returns if a unit is detecting the TargetUnit.

Parameter

Return value

#boolean: true If the TargetUnit is detected by the unit, otherwise false.

UNIT:IsFriendly(FriendlyCoalition)

Returns if the unit is a friendly unit.

Parameter

  • FriendlyCoalition :

Return value

#boolean: IsFriendly evaluation result.

UNIT:IsGround()

Returns if the unit is of an ground category.

If the unit is a ground vehicle or infantry, this method will return true, otherwise false.

Return value

#boolean: Ground category evaluation result.

UNIT:IsInZone(Zone)

Returns true if the unit is within a Zone.

Parameter

Return value

#boolean: Returns true if the unit is within the Zone#ZONE_BASE

UNIT:IsLOS(TargetUnit)

Returns if a unit has Line of Sight (LOS) with the TargetUnit.

Parameter

Return value

#boolean: true If the TargetUnit has LOS with the unit, otherwise false.

UNIT:IsNotInZone(Zone)

Returns true if the unit is not within a Zone.

Parameter

Return value

#boolean: Returns true if the unit is not within the Zone#ZONE_BASE

UNIT:IsShip()

Returns if the unit is of a ship category.

If the unit is a ship, this method will return true, otherwise false.

Return value

#boolean: Ship category evaluation result.

UNIT:Name()

Return the name of the UNIT.

Return value

#string: The UNIT name.

UNIT:OtherUnitInRadius(AwaitUnit, Radius)

Returns true if there is an other DCS Unit within a radius of the current 2D point of the DCS Unit.

Parameters

  • #UNIT AwaitUnit : The other UNIT wrapper object.

  • Radius : The radius in meters with the DCS Unit in the centre.

Return values

  1. true If the other DCS Unit is within the radius of the 2D point of the DCS Unit.

  2. #nil: The DCS Unit is not existing or alive.

UNIT:ReSpawnAt(Coordinate, Heading)

Respawn the Unit using a (tweaked) template of the parent Group.

This function will:

  • Get the current position and heading of the group.
  • When the unit is alive, it will tweak the template x, y and heading coordinates of the group and the embedded units to the current units positions.
  • Then it will respawn the re-modelled group.

Parameters

  • Core.Point#COORDINATE Coordinate : The position where to Spawn the new Unit at.

  • #number Heading : The heading of the unit respawn.

UNIT:Register(UnitName)

Create a new UNIT from DCSUnit.

Parameter

  • #string UnitName : The name of the DCS unit.

Return value

#UNIT:

UNIT:ResetEvents()

Reset the subscriptions.

Return value

#UNIT:

UNIT:UnHandleEvent(Event)

UnSubscribe to a DCS event.

Parameter

Return value

#UNIT:

Type Unit.SensorType

Unit.SensorType

Field(s)

Unit.SensorType.IRST
Unit.SensorType.OPTIC
Unit.SensorType.RADAR
Unit.SensorType.RWR