Module `Group`

Wrapper -- GROUP wraps the DCS Class Group objects.

The #GROUP class is a wrapper class to handle the DCS Group objects:

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

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

See the detailed documentation on the GROUP class.

Author: Sven Van de Velde (FlightControl)

Contributions:

Entropy, Afinegan: Came up with the requirement for AIOnOff().

Global(s)

GROUP

GROUP class, extends Controllable#CONTROLLABLE

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

GROUPTEMPLATE

Type `GROUP`

GROUP:Activate()	Activates a GROUP.
GROUP:AllOnGround()	Returns if all units of the group are on the ground or landed.
GROUP:CalculateThreatLevelA2G()	Calculate the maxium A2G threat level of the Group.
GROUP:CopyRoute(Begin, End, Randomize, Radius)	Return the route of a group by using the Database#DATABASE class.
GROUP:CountInZone(Zone)	Returns the number of UNITs that are in the Zone
GROUP:Destroy()	Destroys the DCS Group and all of its DCS Units.
GROUP:Find(DCSGroup)	Find the GROUP wrapper class instance using the DCS Group.
GROUP:FindByName(GroupName)	Find the created GROUP using the DCS Group Name.
GROUP:GetCallsign()	Gets the CallSign of the first DCS Unit of the DCS Group.
GROUP:GetCategory()	Returns category of the DCS Group.
GROUP:GetCategoryName()	Returns the category name of the #GROUP.
GROUP:GetCoalition()	Returns the coalition of the DCS Group.
GROUP:GetCoordinate()	Returns a COORDINATE object indicating the point of the first UNIT of the GROUP within the mission.
GROUP:GetCountry()	Returns the country of the DCS Group.
GROUP:GetDCSObject()	Returns the DCS Group.
GROUP:GetDCSUnit(UnitNumber)	Returns the DCS Unit with number UnitNumber.
GROUP:GetDCSUnits()	Returns the DCS Units of the DCS Group.
GROUP:GetFuel()	Returns relative amount of fuel (from 0.0 to 1.0) the group has in its internal tanks.
GROUP:GetHeading()	Returns the mean heading of every UNIT in the GROUP in degrees
GROUP:GetInitialSize()	Returns the initial size of the DCS Group.
GROUP:GetMaxHeight()	Returns the current maximum height of the group.
GROUP:GetMaxVelocity()	Returns the current maximum velocity of the group.
GROUP:GetMinHeight()	Returns the current minimum height of the group.
GROUP:GetPlayerName()	Gets the player name of the group.
GROUP:GetPlayerNames()	Get player names
GROUP:GetPointVec2()	Returns a POINT_VEC2 object indicating the point in 2D of the first UNIT of the GROUP within the mission.
GROUP:GetPositionVec3()	Returns the DCSTypes#Position3 position vectors indicating the point and direction vectors in 3D of the POSITIONABLE within the mission.
GROUP:GetRandomVec3(Radius)	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.
GROUP:GetSize()	Returns current size of the DCS Group.
GROUP:GetTaskMission()	Return the mission template of the group.
GROUP:GetTaskRoute()	Return the mission route of the group.
GROUP:GetTemplate()	Returns the group template from the DATABASE (_DATABASE object).
GROUP:GetTemplateRoutePoints()	Returns the group template route.points[] (the waypoints) from the DATABASE (_DATABASE object).
GROUP:GetTypeName()	Gets the type name of the group.
GROUP:GetUnit(UnitNumber)	Returns the UNIT wrapper class with number UnitNumber.
GROUP:GetVec2()	Returns the current point (Vec2 vector) of the first DCS Unit in the DCS Group.
GROUP:GetVec3()	Returns the current Vec3 vector of the first DCS Unit in the GROUP.
GROUP.GroupName	The name of the group.
GROUP:HandleEvent(Event, EventFunction, ...)	Subscribe to a DCS Event.
GROUP:InAir()	Returns true if the first unit of the GROUP is in the air.
GROUP:IsAir()	Returns if the group is of an air category.
GROUP:IsAirPlane()	Returns if the DCS Group contains AirPlanes.
GROUP:IsAlive()	Returns if the Group is alive.
GROUP:IsCompletelyInZone(Zone)	Returns true if all units of the group are within a Zone.
GROUP:IsGround()	Returns if the DCS Group contains Ground troops.
GROUP:IsHelicopter()	Returns if the DCS Group contains Helicopters.
GROUP:IsNotInZone(Zone)	Returns true if none of the group units of the group are within a Zone.
GROUP:IsPartlyInZone(Zone)	Returns true if some units of the group are within a Zone.
GROUP:IsShip()	Returns if the DCS Group contains Ships.
GROUP:NewTemplate(GroupTemplate, CoalitionSide, CategoryID, CountryID)	Create a new GROUP from a given GroupTemplate as a parameter.
GROUP:OnReSpawn(ReSpawnFunction)
GROUP:Register(GroupName)	Create a new GROUP from an existing Group in the Mission.
GROUP:ResetEvents()	Reset the subscriptions.
GROUP:Respawn(Template)	Respawn the GROUP using a (tweaked) template of the Group.
GROUP:RouteRTB(RTBAirbase, Speed)	(AIR) Return the Group to an Airbase#AIRBASE.
GROUP:SetAIOff()	Turns the AI Off for the GROUP.
GROUP:SetAIOn()	Turns the AI On for the GROUP.
GROUP:SetAIOnOff(AIOnOff)	Turns the AI On or Off for the GROUP.
GROUP:SetTemplateCoalition(CoalitionID, Template)	Sets the CoalitionID of the group in a Template.
GROUP:SetTemplateControlled(Controlled, Template)	Sets the controlled status in a Template.
GROUP:SetTemplateCountry(CountryID, Template)	Sets the CountryID of the group in a Template.
GROUP.Takeoff
GROUP:UnHandleEvent(Event)	UnSubscribe to a DCS event.

Type `GROUP.Takeoff`

GROUP.Takeoff.Air
GROUP.Takeoff.Cold
GROUP.Takeoff.Hot
GROUP.Takeoff.Runway

Global(s)

#GROUP GROUP

GROUP class, extends Controllable#CONTROLLABLE

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

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

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

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

GROUP.Find(): Find a GROUP instance from the _DATABASE object using a DCS Group object.
GROUP.FindByName(): Find a GROUP instance from the _DATABASE object using a DCS Group name.

GROUP task methods

A GROUP is a Controllable. See the Controllable task methods section for a description of the task methods.

Obtain the mission from group templates

Group templates contain complete mission descriptions. Sometimes you want to copy a complete mission from a group and assign it to another:

Controllable#CONTROLLABLE.TaskMission: (AIR + GROUND) Return a mission task from a mission template.

GROUP Command methods

A GROUP is a Controllable. See the Controllable command methods section for a description of the command methods.

GROUP option methods

A GROUP is a Controllable. See the Controllable option methods section for a description of the option methods.

GROUP Zone validation methods

The group can be validated whether it is completely, partly or not within a Zone. Use the following Zone validation methods on the group:

GROUP.IsCompletelyInZone: Returns true if all units of the group are within a Zone.
GROUP.IsPartlyInZone: Returns true if some units of the group are within a Zone.
GROUP.IsNotInZone: Returns true if none of the group units of the group are within a Zone.

The zone can be of any Zone class derived from Zone#ZONE_BASE. So, these methods are polymorphic to the zones tested on.

GROUP AI methods

A GROUP has AI methods to control the AI activation.

GROUP.SetAIOnOff(): Turns the GROUP AI On or Off.
GROUP.SetAIOn(): Turns the GROUP AI On.
GROUP.SetAIOff(): Turns the GROUP AI Off.

GROUPTEMPLATE

Type `Group`

Type `GROUP`

Field(s)

GROUP:Activate(): Activates a GROUP.

GROUP:AllOnGround()

Returns if all units of the group are on the ground or landed.

If all units of this group are on the ground, this function will return true, otherwise false.

Return value

#boolean: All units on the ground result.

GROUP:CalculateThreatLevelA2G(): Calculate the maxium A2G threat level of the Group.

GROUP:CopyRoute(Begin, End, Randomize, Radius)

Return the route of a group by using the Database#DATABASE class.

Parameters

#number Begin : The route point from where the copy will start. The base route point is 0.
#number End : The route point where the copy will end. The End point is the last point - the End point. The last point has base 0.
#boolean Randomize : Randomization of the route, when true.
#number Radius : When randomization is on, the randomization is within the radius.

GROUP:CountInZone(Zone)

Returns the number of UNITs that are in the Zone

Parameter

Core.Zone#ZONE_BASE Zone : The zone to test.

Return value

#number: The number of UNITs that are in the Zone

GROUP:Destroy()

Destroys the DCS Group and all of its DCS Units.

Note that this destroy method also raises a destroy event at run-time. So all event listeners will catch the destroy event of this DCS Group.

GROUP:Find(DCSGroup)

Find the GROUP wrapper class instance using the DCS Group.

Parameter

Dcs.DCSWrapper.Group#Group DCSGroup : The DCS Group.

Return value

#GROUP: The GROUP.

GROUP:FindByName(GroupName)

Find the created GROUP using the DCS Group Name.

Parameter

#string GroupName : The DCS Group Name.

Return value

#GROUP: The GROUP.

GROUP:GetCallsign()

Gets the CallSign of the first DCS Unit of the DCS Group.

Return value

#string: The CallSign of the first DCS Unit of the DCS Group.

GROUP:GetCategory()

Returns category of the DCS Group.

Return value

Dcs.DCSWrapper.Group#Group.Category: The category ID

GROUP:GetCategoryName()

Returns the category name of the #GROUP.

Return value

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

GROUP:GetCoalition()

Returns the coalition of the DCS Group.

Return value

Dcs.DCSCoalitionWrapper.Object#coalition.side: The coalition side of the DCS Group.

GROUP:GetCoordinate()

Returns a COORDINATE object indicating the point of the first UNIT of the GROUP within the mission.

Return value

Core.Point#COORDINATE: The COORDINATE of the GROUP.

GROUP:GetCountry()

Returns the country of the DCS Group.

Return values

Dcs.DCScountry#country.id: The country identifier.
#nil: The DCS Group is not existing or alive.

GROUP:GetDCSObject()

Returns the DCS Group.

Return value

Dcs.DCSWrapper.Group#Group: The DCS Group.

GROUP:GetDCSUnit(UnitNumber)

Returns the DCS Unit with number UnitNumber.

If the underlying DCS Unit does not exist, the method will return nil. .

Parameter

#number UnitNumber : The number of the DCS Unit to be returned.

Return value

Dcs.DCSWrapper.Unit#Unit: The DCS Unit.

GROUP:GetDCSUnits()

Returns the DCS Units of the DCS Group.

Return value

#table: The DCS Units.

GROUP:GetFuel()

Returns relative amount of fuel (from 0.0 to 1.0) the group 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 GROUP is not existing or alive.

GROUP:GetHeading()

Returns the mean heading of every UNIT in the GROUP in degrees

Return values

#number: mean heading of the GROUP
#nil: The first UNIT is not existing or alive.

GROUP:GetInitialSize()

Returns the initial size of the DCS Group.

If some of the DCS Units of the DCS Group are destroyed, the initial size of the DCS Group is unchanged.

Return value

#number: The DCS Group initial size.

GROUP:GetMaxHeight()

Returns the current maximum height of the group.

Each unit within the group gets evaluated, and the maximum height (= the unit which is the highest elevated) is returned.

Return value

#number: Maximum height found.

GROUP:GetMaxVelocity()

Returns the current maximum velocity of the group.

Each unit within the group gets evaluated, and the maximum velocity (= the unit which is going the fastest) is returned.

Return value

#number: Maximum velocity found.

GROUP:GetMinHeight()

Returns the current minimum height of the group.

Each unit within the group gets evaluated, and the minimum height (= the unit which is the lowest elevated) is returned.

Return value

#number: Minimum height found.

GROUP:GetPlayerName()

Gets the player name of the group.

Return value

#string: The player name of the group.

GROUP:GetPlayerNames()

Get player names

Return values

#table: The group has players, an array of player names is returned.
#nil: The group has no players

GROUP:GetPointVec2()

Returns a POINT_VEC2 object indicating the point in 2D of the first UNIT of the GROUP within the mission.

Return values

Core.Point#POINT_VEC2: The 2D point vector of the first DCS Unit of the GROUP.
#nil: The first UNIT is not existing or alive.

GROUP:GetPositionVec3()

Returns the DCSTypes#Position3 position vectors indicating the point and direction vectors in 3D of the POSITIONABLE within the mission.

Return values

Dcs.DCSTypes#Position: The 3D position vectors of the POSITIONABLE.
#nil: The POSITIONABLE is not existing or alive.

GROUP:GetRandomVec3(Radius)

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.

Parameter

#number Radius :

Return values

Dcs.DCSTypes#Vec3: The random 3D point vector around the first UNIT of the GROUP.
#nil: The GROUP is invalid or empty

Usage:


-- If Radius is ignored, returns the Dcs.DCSTypes#Vec3 of first UNIT of the GROUP

GROUP:GetSize()

Returns current size of the DCS Group.

If some of the DCS Units of the DCS Group are destroyed the size of the DCS Group is changed.

Return value

#number: The DCS Group size.

GROUP:GetTaskMission()

Return the mission template of the group.

Return value

#table: The MissionTemplate

GROUP:GetTaskRoute()

Return the mission route of the group.

Return value

#table: The mission route defined by points.

GROUP:GetTemplate()

Returns the group template from the DATABASE (_DATABASE object).

Return value

#table:

GROUP:GetTemplateRoutePoints()

Returns the group template route.points[] (the waypoints) from the DATABASE (_DATABASE object).

Return value

#table:

GROUP:GetTypeName()

Gets the type name of the group.

Return value

#string: The type name of the group.

GROUP:GetUnit(UnitNumber)

Returns the UNIT wrapper class with number UnitNumber.

If the underlying DCS Unit does not exist, the method will return nil. .

Parameter

#number UnitNumber : The number of the UNIT wrapper class to be returned.

Return value

Wrapper.Unit#UNIT: The UNIT wrapper class.

GROUP:GetVec2()

Returns the current point (Vec2 vector) of the first DCS Unit in the DCS Group.

Return value

Dcs.DCSTypes#Vec2: Current Vec2 point of the first DCS Unit of the DCS Group.

GROUP:GetVec3()

Returns the current Vec3 vector of the first DCS Unit in the GROUP.

Return value

Dcs.DCSTypes#Vec3: Current Vec3 of the first DCS Unit of the GROUP.

#string GROUP.GroupName: The name of the group.

GROUP: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 GROUP.
... :

Return value

#GROUP:

GROUP:InAir()

Returns true if the first unit of the GROUP is in the air.

Return values

#boolean: true if in the first unit of the group is in the air.
#nil: The GROUP is not existing or not alive.

GROUP:IsAir()

Returns if the group is of an air category.

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

Return value

#boolean: Air category evaluation result.

GROUP:IsAirPlane()

Returns if the DCS Group contains AirPlanes.

Return value

#boolean: true if DCS Group contains AirPlanes.

GROUP:IsAlive()

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.

Return values

#boolean: true if the Group is alive and active.
#boolean: false if the Group is alive but inactive.
#nil: if the group does not exist anymore.

GROUP:IsCompletelyInZone(Zone)

Returns true if all units of the group are within a Zone.

Parameter

Core.Zone#ZONE_BASE Zone : The zone to test.

Return value

#boolean: Returns true if the Group is completely within the Zone#ZONE_BASE

GROUP:IsGround()

Returns if the DCS Group contains Ground troops.

Return value

#boolean: true if DCS Group contains Ground troops.

GROUP:IsHelicopter()

Returns if the DCS Group contains Helicopters.

Return value

#boolean: true if DCS Group contains Helicopters.

GROUP:IsNotInZone(Zone)

Returns true if none of the group units of the group are within a Zone.

Parameter

Core.Zone#ZONE_BASE Zone : The zone to test.

Return value

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

GROUP:IsPartlyInZone(Zone)

Returns true if some units of the group are within a Zone.

Parameter

Core.Zone#ZONE_BASE Zone : The zone to test.

Return value

#boolean: Returns true if the Group is partially within the Zone#ZONE_BASE

GROUP:IsShip()

Returns if the DCS Group contains Ships.

Return value

#boolean: true if DCS Group contains Ships.

GROUP:NewTemplate(GroupTemplate, CoalitionSide, CategoryID, CountryID)

Create a new GROUP from a given GroupTemplate as a parameter.

Note that the GroupTemplate is NOT spawned into the mission. It is merely added to the Database.

Parameters

#table GroupTemplate : The GroupTemplate Structure exactly as defined within the mission editor.
Dcs.DCScoalition#coalition.side CoalitionSide : The coalition.side of the group.
Dcs.DCSGroup#Group.Category CategoryID : The Group.Category of the group.
Dcs.DCScountry#country.id CountryID : the country.id of the group.

Return value

#GROUP: self

GROUP:OnReSpawn(ReSpawnFunction)

Parameter

ReSpawnFunction :

GROUP:Register(GroupName)

Create a new GROUP from an existing Group in the Mission.

Parameter

#string GroupName : The Group name

Return value

#GROUP: self

GROUP:ResetEvents()

Reset the subscriptions.

Return value

#GROUP:

GROUP:Respawn(Template)

Respawn the GROUP using a (tweaked) template of the Group.

The template must be retrieved with the Group#GROUP.GetTemplate() function. The template contains all the definitions as declared within the mission file. To understand templates, do the following:

unpack your .miz file into a directory using 7-zip.
browse in the directory created to the file mission.
open the file and search for the country group definitions.

Your group template will contain the fields as described within the mission file.

This function will:

Get the current position and heading of the group.
When the group 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 destroy the current alive group.
And it will respawn the group using your new template definition.

Parameter

#table Template : The template of the Group retrieved with GROUP:GetTemplate()

GROUP:RouteRTB(RTBAirbase, Speed)

(AIR) Return the Group to an Airbase#AIRBASE.

The following things are to be taken into account:

The group is respawned to achieve the RTB, there may be side artefacts as a result of this. (Like weapons suddenly come back).
A group consisting out of more than one unit, may rejoin formation when respawned.
A speed can be given in km/h. If no speed is specified, the maximum speed of the first unit will be taken to return to base.
When there is no Airbase object specified, the group will return to the home base if the route of the group is pinned at take-off or at landing to a base.
When there is no Airbase object specified and the group route is not pinned to any airbase, it will return to the nearest airbase.

Parameters

Wrapper.Airbase#AIRBASE RTBAirbase : (optional) The Airbase to return to. If blank, the controllable will return to the nearest friendly airbase.
#number Speed : (optional) The Speed, if no Speed is given, the maximum Speed of the first unit is selected.

Return value

#GROUP:

GROUP:SetAIOff()

Turns the AI Off for the GROUP.

Return value

#GROUP: The GROUP.

GROUP:SetAIOn()

Turns the AI On for the GROUP.

Return value

#GROUP: The GROUP.

GROUP:SetAIOnOff(AIOnOff)

Turns the AI On or Off for the GROUP.

Parameter

#boolean AIOnOff : The value true turns the AI On, the value false turns the AI Off.

Return value

#GROUP: The GROUP.

GROUP:SetTemplateCoalition(CoalitionID, Template)

Sets the CoalitionID of the group in a Template.

Parameters

Dcs.DCSCoalitionWrapper.Object#coalition.side CoalitionID : The coalition ID.
Template :

Return value

#table:

GROUP:SetTemplateControlled(Controlled, Template)

Sets the controlled status in a Template.

Parameters

#boolean Controlled : true is controlled, false is uncontrolled.
Template :

Return value

#table:

GROUP:SetTemplateCountry(CountryID, Template)

Sets the CountryID of the group in a Template.

Parameters

Dcs.DCScountry#country.id CountryID : The country ID.
Template :

Return value

#table:

#GROUP.Takeoff GROUP.Takeoff

GROUP:UnHandleEvent(Event)

UnSubscribe to a DCS event.

Parameter

Core.Event#EVENTS Event :

Return value

#GROUP:

Type `GROUP.Takeoff`

Enumerator for location at airbases

Field(s)

#number GROUP.Takeoff.Air

#number GROUP.Takeoff.Cold

#number GROUP.Takeoff.Hot

#number GROUP.Takeoff.Runway

Modules

Module Group

Author: Sven Van de Velde (FlightControl)

Contributions:

Global(s)

GROUP class, extends Controllable#CONTROLLABLE

Type GROUP

Type GROUP.Takeoff

Global(s)

GROUP class, extends Controllable#CONTROLLABLE

GROUP task methods

Obtain the mission from group templates

GROUP Command methods

GROUP option methods

GROUP Zone validation methods

GROUP AI methods

Type Group

Type GROUP

Field(s)

Return value

Parameters

Parameter

Return value

Parameter

Return value

Parameter

Return value

Return value

Return value

Return value

Return value

Return value

Return values

Return value

Parameter

Return value

Return value

Return values

Return values

Return value

Return value

Return value

Return value

Return value

Return values

Return values

Return values

Parameter

Return values

Usage:

Return value

Return value

Return value

Return value

Return value

Return value

Parameter

Return value

Return value

Return value

Parameters

Return value

Return values

Return value

Return value

Return values

Parameter

Return value

Return value

Return value

Parameter

Return value

Parameter

Return value

Return value

Parameters

Return value

Parameter

Parameter

Return value

Module `Group`

Type `GROUP`

Type `GROUP.Takeoff`

Type `Group`

Type `GROUP`

Type `GROUP.Takeoff`