Module `Group`

This module contains the GROUP class.

1) Wrapper.Group#GROUP class, extends Wrapper.Controllable#CONTROLLABLE

The Wrapper.Group#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).

1.1) GROUP reference methods

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.

1.2) GROUP task methods

Several group task methods are available that help you to prepare tasks. These methods return a string consisting of the task description, which can then be given to either a
Wrapper.Controllable#CONTROLLABLE.PushTask or Wrapper.Controllable#CONTROLLABLE.SetTask method to assign the task to the GROUP. Tasks are specific for the category of the GROUP, more specific, for AIR, GROUND or AIR and GROUND. Each task description where applicable indicates for which group category the task is valid. There are 2 main subdivisions of tasks: Assigned tasks and EnRoute tasks.

1.2.1) Assigned task methods

Assigned task methods make the group execute the task where the location of the (possible) targets of the task are known before being detected. This is different from the EnRoute tasks, where the targets of the task need to be detected before the task can be executed.

Find below a list of the assigned task methods:

Wrapper.Controllable#CONTROLLABLE.TaskAttackGroup: (AIR) Attack a Group.
Wrapper.Controllable#CONTROLLABLE.TaskAttackMapObject: (AIR) Attacking the map object (building, structure, e.t.c).
Wrapper.Controllable#CONTROLLABLE.TaskAttackUnit: (AIR) Attack the Unit.
Wrapper.Controllable#CONTROLLABLE.TaskBombing: (Wrapper.Controllable#CONTROLLABLEDelivering weapon at the point on the ground.
Wrapper.Controllable#CONTROLLABLE.TaskBombingRunway: (AIR) Delivering weapon on the runway.
Wrapper.Controllable#CONTROLLABLE.TaskEmbarking: (AIR) Move the group to a Vec2 Point, wait for a defined duration and embark a group.
Wrapper.Controllable#CONTROLLABLE.TaskEmbarkToTransport: (GROUND) Embark to a Transport landed at a location.
Wrapper.Controllable#CONTROLLABLE.TaskEscort: (AIR) Escort another airborne group.
Wrapper.Controllable#CONTROLLABLE.TaskFAC_AttackGroup: (AIR + GROUND) The task makes the group/unit a FAC and orders the FAC to control the target (enemy ground group) destruction.
Wrapper.Controllable#CONTROLLABLE.TaskFireAtPoint: (GROUND) Fire at a VEC2 point until ammunition is finished.
Wrapper.Controllable#CONTROLLABLE.TaskFollow: (AIR) Following another airborne group.
Wrapper.Controllable#CONTROLLABLE.TaskHold: (GROUND) Hold ground group from moving.
Wrapper.Controllable#CONTROLLABLE.TaskHoldPosition: (AIR) Hold position at the current position of the first unit of the group.
Wrapper.Controllable#CONTROLLABLE.TaskLand: (AIR HELICOPTER) Landing at the ground. For helicopters only.
Wrapper.Controllable#CONTROLLABLE.TaskLandAtZone: (AIR) Land the group at a Wrapper.Controllable#CONTROLLABLE.TaskOrbitCircle: (AIR) Orbit at the current position of the first unit of the group at a specified alititude.
Wrapper.Controllable#CONTROLLABLE.TaskOrbitCircleAtVec2: (AIR) Orbit at a specified position at a specified alititude during a specified duration with a specified speed.
Wrapper.Controllable#CONTROLLABLE.TaskRefueling: (AIR) Refueling from the nearest tanker. No parameters.
Wrapper.Controllable#CONTROLLABLE.TaskRoute: (AIR + GROUND) Return a Misson task to follow a given route defined by Points.
Wrapper.Controllable#CONTROLLABLE.TaskRouteToVec2: (AIR + GROUND) Make the Group move to a given point.
Wrapper.Controllable#CONTROLLABLE.TaskRouteToVec3: (AIR + GROUND) Make the Group move to a given point.
Wrapper.Controllable#CONTROLLABLE.TaskRouteToZone: (AIR + GROUND) Route the group to a given zone.
Wrapper.Controllable#CONTROLLABLE.TaskReturnToBase: (AIR) Route the group to an airbase.

1.2.2) EnRoute task methods

EnRoute tasks require the targets of the task need to be detected by the group (using its sensors) before the task can be executed:

Wrapper.Controllable#CONTROLLABLE.EnRouteTaskAWACS: (AIR) Aircraft will act as an AWACS for friendly units (will provide them with information about contacts). No parameters.
Wrapper.Controllable#CONTROLLABLE.EnRouteTaskEngageGroup: (AIR) Engaging a group. The task does not assign the target group to the unit/group to attack now; it just allows the unit/group to engage the target group as well as other assigned targets.
Wrapper.Controllable#CONTROLLABLE.EnRouteTaskEngageTargets: (AIR) Engaging targets of defined types.
Wrapper.Controllable#CONTROLLABLE.EnRouteTaskEWR: (AIR) Attack the Unit.
Wrapper.Controllable#CONTROLLABLE.EnRouteTaskFAC: (AIR + GROUND) The task makes the group/unit a FAC and lets the FAC to choose a targets (enemy ground group) around as well as other assigned targets.
Wrapper.Controllable#CONTROLLABLE.EnRouteTaskFAC_EngageGroup: (AIR + GROUND) The task makes the group/unit a FAC and lets the FAC to choose the target (enemy ground group) as well as other assigned targets.
Wrapper.Controllable#CONTROLLABLE.EnRouteTaskTanker: (AIR) Aircraft will act as a tanker for friendly units. No parameters.

1.2.3) Preparation task methods

There are certain task methods that allow to tailor the task behaviour:

Wrapper.Controllable#CONTROLLABLE.TaskWrappedAction: Return a WrappedAction Task taking a Command.
Wrapper.Controllable#CONTROLLABLE.TaskCombo: Return a Combo Task taking an array of Tasks.
Wrapper.Controllable#CONTROLLABLE.TaskCondition: Return a condition section for a controlled task.
Wrapper.Controllable#CONTROLLABLE.TaskControlled: Return a Controlled Task taking a Task and a TaskCondition.

1.2.4) 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:

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

1.3) GROUP Command methods

Group command methods prepare the execution of commands using the Wrapper.Controllable#CONTROLLABLE.SetCommand method:

Wrapper.Controllable#CONTROLLABLE.CommandDoScript: Do Script command.
Wrapper.Controllable#CONTROLLABLE.CommandSwitchWayPoint: Perform a switch waypoint command.

1.4) GROUP Option methods

Group Option methods change the behaviour of the Group while being alive.

1.4.1) Rule of Engagement:

To check whether an ROE option is valid for a specific group, use:

1.4.2) Rule on thread:

To test whether an ROT option is valid for a specific group, use:

1.5) 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 Core.Zone#ZONE_BASE. So, these methods are polymorphic to the zones tested on.

Global(s)

GROUP

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.ClassName
GROUP:CopyRoute(Begin, End, Randomize, Radius)	Return the route of a group by using the Core.Database#DATABASE class.
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 DCS Group.
GROUP:GetCoalition()	Returns the coalition of the DCS Group.
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: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: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:GetTypeName()	Gets the type name of the group.
GROUP:GetUnit(UnitNumber)	Returns the UNIT wrapper class with number UnitNumber.
GROUP:GetUnits()	Returns the UNITs wrappers of the DCS Units of the DCS Group.
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:IsAir()	Returns if the group is of an air category.
GROUP:IsAirPlane()	Returns if the DCS Group contains AirPlanes.
GROUP:IsAlive()	Returns if the DCS 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:Register(GroupName)	Create a new GROUP from a DCSGroup
GROUP:Respawn(Template)	Respawn the GROUP using a (tweaked) template of 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.

Global(s)

#GROUP GROUP

Type `Group`

Type `GROUP`

The GROUP class

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.

#string GROUP.ClassName

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

Return the route of a group by using the Core.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: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 DCS 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: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: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: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: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:GetUnits()

Returns the UNITs wrappers of the DCS Units of the DCS Group.

Return value

#table: The UNITs wrappers.

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: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 DCS Group is alive.

When the group exists at run-time, this method will return true, otherwise false.

Return value

#boolean: true if the DCS Group is alive.

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 Core.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 completely within the Core.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 completely within the Core.Zone#ZONE_BASE

GROUP:IsShip()

Returns if the DCS Group contains Ships.

Return value

#boolean: true if DCS Group contains Ships.

GROUP:Register(GroupName)

Create a new GROUP from a DCSGroup

Parameter

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

Return value

#GROUP: self

GROUP:Respawn(Template)

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

The template must be retrieved with the Wrapper.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: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:

Modules

Module Group

1) Wrapper.Group#GROUP class, extends Wrapper.Controllable#CONTROLLABLE

1.1) GROUP reference methods

1.2) GROUP task methods

1.2.1) Assigned task methods

1.2.2) EnRoute task methods

1.2.3) Preparation task methods

1.2.4) Obtain the mission from group templates

1.3) GROUP Command methods

1.4) GROUP Option methods

1.4.1) Rule of Engagement:

1.4.2) Rule on thread:

1.5) GROUP Zone validation methods

Global(s)

Type GROUP

Global(s)

Type Group

Type GROUP

Field(s)

Return value

Parameters

Parameter

Return value

Parameter

Return value

Return value

Return value

Return value

Return value

Return values

Return value

Parameter

Return value

Return value

Return value

Return value

Return value

Return value

Return value

Return value

Return value

Return value

Return value

Parameter

Return value

Return value

Return value

Return value

Return value

Return value

Return value

Parameter

Return value

Return value

Return value

Parameter

Return value

Parameter

Return value

Return value

Parameter

Return value

Parameter

Parameters

Return value

Parameters

Return value

Parameters

Return value

Module `Group`

Type `GROUP`

Type `Group`

Type `GROUP`