Unit#

Unit represents an individual airplane, helicopter, ground vehicle, ship, or armed ground structure. It extends CoalitionObject (and, transitively, Object).

class Unit#

Inherits all member functions of CoalitionObject and Object.

Static functions#

static getByName(name)#

Returns the Unit with the given Mission Editor name, or nil if it does not exist (or has not spawned yet).

Parameters:: name (string) – Unit name.
Returns:: The matching unit, or nil.
Return type:: Unit

static getDescByName(typeName)#

Returns a description table for a unit type, without needing an actual instance in the mission.

Parameters:: typeName (string) – Unit type name (e.g. "Su-27").
Returns:: Description table.
Return type:: table

Member functions#

isActive()#

Returns whether the unit is active (spawned and not late-activated).

Returns:: Whether the unit is active.
Return type:: boolean

getPlayerName()#

Returns the name of the human player controlling the unit, or nil if AI-controlled.

Returns:: Player name, or nil.
Return type:: string

getID()#

Returns the unit’s numeric ID.

Returns:: Unit ID.
Return type:: number

getNumber()#

Returns the unit’s number within its group (its “unit number” in the Mission Editor).

Returns:: Unit number.
Return type:: number

getCategoryEx()#

Returns the unit’s more specific category (see Unit.Category). Equivalent to unit:getDesc().category.

Returns:: Unit category.
Return type:: number

getObjectID()#

Returns the unit’s low-level engine object ID.

Returns:: Object ID.
Return type:: number

getController()#

Returns the unit’s individual Controller. Only meaningful for units that can be controlled individually (planes and helicopters); other unit types are controlled at the group level.

Returns:: The unit’s controller.
Return type:: Controller

getGroup()#

Returns the Group the unit belongs to.

Returns:: The unit’s group.
Return type:: Group

getCallsign()#

Returns the unit’s callsign, as shown in the F10 map and various UI elements.

Returns:: Callsign.
Return type:: string

getLife()#

Returns the unit’s current hit points.

Returns:: Current life.
Return type:: number

getLife0()#

Returns the unit’s maximum (starting) hit points.

Returns:: Maximum life.
Return type:: number

getFuel()#

Returns the unit’s current fuel state, as a fraction of maximum internal fuel (1.0 = full internal tanks; external fuel may push this above 1.0).

Returns:: Fuel fraction.
Return type:: number

getAmmo()#

Returns a table describing the unit’s current ammunition/weapon loadout.

Returns:: Ammo descriptor table.
Return type:: table

getSensors()#

Returns a table describing the sensors mounted on the unit.

Returns:: Sensor descriptor table.
Return type:: table

hasSensors(sensorType, subCategory)#

Returns whether the unit has a sensor of the given type (and, optionally, subcategory).

Parameters:

sensorType (number) – Sensor type (see Unit.SensorType).
subCategory (number) – Optional subcategory (e.g. optic/radar subtype).

Returns:

Whether the sensor is present.

Return type:

boolean

getRadar()#

Returns whether the unit’s radar is active, and the currently tracked target object if any.

Returns:: Whether radar is active, and the tracked target (if any).
Return type:: boolean, Object

getDrawArgumentValue(argument)#

Returns the current value of a 3D model animation argument (as used by the unit’s visual model, e.g. landing gear position).

Parameters:: argument (number) – Animation argument index.
Returns:: Current argument value.
Return type:: number

getNearestCargos()#

Returns a table of the nearest cargo objects available to this unit (used for troop/cargo transport).

Returns:: Nearby cargo objects.
Return type:: table

enableEmission(enabled)#

Enables or disables all of the unit’s radar/sensor/radio emissions.

Parameters:: enabled (boolean) – Whether emissions should be enabled.

getDescentCapacity()#

Returns the number of paratroopers the unit can carry/deploy, if applicable.

Returns:: Descent capacity.
Return type:: number

Enumerators#

Unit.Category identifies the specific unit category (via unit:getDesc().category – not unit:getCategory(), which always returns Object.Category.UNIT):

Value	Meaning
`Unit.Category.AIRPLANE`	Airplane (`0`)
`Unit.Category.HELICOPTER`	Helicopter (`1`)
`Unit.Category.GROUND_UNIT`	Ground vehicle/infantry (`2`)
`Unit.Category.SHIP`	Ship (`3`)
`Unit.Category.STRUCTURE`	Armed structure (`4`)

Unit.SensorType identifies sensor types for Unit.hasSensors():

Value	Meaning
`Unit.SensorType.OPTIC`	Optic/TV/IR sensor (`0`)
`Unit.SensorType.RADAR`	Radar (`1`)
`Unit.SensorType.IRST`	Infra-red search and track (`2`)
`Unit.SensorType.RWR`	Radar warning receiver (`3`)

Footnotes#

Unit objects can be obtained from the Group they belong to, via events (many event types include an initiator unit), or via Unit.getByName.