Module `Unit`

This module contains the UNIT class.

1) Unit#UNIT class, extends Controllable#CONTROLLABLE

The Unit#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.

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

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

1.2) 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 DCSUnit#Unit.getName() is implemented in the UNIT class as UNIT.GetName().

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

1.4) Location Position, Point

The UNIT class provides methods to obtain the current point or position of the DCS Unit. The UNIT.GetPointVec2(), UNIT.GetPointVec3() 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.

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

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

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

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

Global(s)

UNIT

Type `UNIT`

UNIT.ClassName
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:Flare(FlareColor)	Signal a flare at the position of the UNIT.
UNIT.FlareColor
UNIT:FlareGreen()	Signal a green flare at the position of the UNIT.
UNIT:FlareRed()	Signal a red flare at the position of the UNIT.
UNIT:FlareWhite()	Signal a white flare at the position of the UNIT.
UNIT:FlareYellow()	Signal a yellow flare at the position of the UNIT.
UNIT:GetAmmo()	Returns the Unit's ammunition.
UNIT:GetCallSign()	Returns the Unit's callsign - the localized string.
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:IsActive()	Returns if the unit is activated.
UNIT:IsAir()	Returns if the unit is of an air category.
UNIT:IsInZone(Zone)	Returns true if the unit is within a Zone.
UNIT:IsNotInZone(Zone)	Returns true if the unit is not within a Zone.
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:Register(UnitName)	Create a new UNIT from DCSUnit.
UNIT:Smoke(SmokeColor)	Smoke the UNIT.
UNIT:SmokeBlue()	Smoke the UNIT Blue.
UNIT.SmokeColor
UNIT:SmokeGreen()	Smoke the UNIT Green.
UNIT:SmokeOrange()	Smoke the UNIT Orange.
UNIT:SmokeRed()	Smoke the UNIT Red.
UNIT:SmokeWhite()	Smoke the UNIT White.

Type `UNIT.FlareColor`

UNIT.FlareColor.Green
UNIT.FlareColor.Red
UNIT.FlareColor.White
UNIT.FlareColor.Yellow

Type `UNIT.SmokeColor`

UNIT.SmokeColor.Blue
UNIT.SmokeColor.Green
UNIT.SmokeColor.Orange
UNIT.SmokeColor.Red
UNIT.SmokeColor.White

Global(s)

#UNIT UNIT

Type `Unit`

Type `UNIT`

The UNIT class

Field(s)

#string UNIT.ClassName

UNIT:Find(DCSUnit)

Finds a UNIT from the _DATABASE using a DCSUnit object.

Parameter

DCSUnit#Unit DCSUnit : An existing DCS Unit object reference.

Return value

Unit#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#UNIT: self

UNIT:Flare(FlareColor)

Signal a flare at the position of the UNIT.

Parameter

FlareColor :

#UNIT.FlareColor UNIT.FlareColor

UNIT:FlareGreen(): Signal a green flare at the position of the UNIT.

UNIT:FlareRed(): Signal a red flare at the position of the UNIT.

UNIT:FlareWhite(): Signal a white flare at the position of the UNIT.

UNIT:FlareYellow(): Signal a yellow flare at the position of the UNIT.

UNIT:GetAmmo()

Returns the Unit's ammunition.

Return values

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

UNIT:GetCallSign()

Returns the Unit's callsign - the localized string.

Return values

#string: The Callsign of the Unit.
#nil: The DCS Unit is not existing or alive.

UNIT:GetDCSObject(): Return value

DCSUnit#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

#number: The relative amount of fuel (from 0.0 to 1.0).
#nil: The DCS Unit is not existing or alive.

UNIT:GetGroup()

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

Return values

Group#GROUP: The Group of the Unit.
#nil: The DCS Unit is not existing or alive.

UNIT:GetLife()

Returns the unit's health.

Dead units has health <= 1.0.

Return values

#number: The Unit's health value.
#nil: The DCS Unit is not existing or alive.

UNIT:GetLife0()

Returns the Unit's initial health.

Return values

#number: The Unit's initial health value.
#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

#number: The Unit number.
#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

#string: Player Name
#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

#string: The name of the DCS Unit.
#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

#boolean: Indicates if at least one of the unit's radar(s) is on.
DCSObject#Object: The object of the radar's interest. Not nil only if at least one radar of the unit is tracking a target.
#nil: The DCS Unit is not existing or alive.

UNIT:GetSensors()

Returns the unit sensors.