Module `Group`

This module contains the GROUP class.

1) Group#GROUP class, extends Controllable#CONTROLLABLE

The 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 Group#GROUP.PushTask or Group#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:

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

GROUP.EnRouteTaskAWACS: (AIR) Aircraft will act as an AWACS for friendly units (will provide them with information about contacts). No parameters.
GROUP.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.
GROUP.EnRouteTaskEngageTargets: (AIR) Engaging targets of defined types.
GROUP.EnRouteTaskEWR: (AIR) Attack the Unit.
GROUP.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.
GROUP.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.
GROUP.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:

GROUP.TaskWrappedAction: Return a WrappedAction Task taking a Command.
GROUP.TaskCombo: Return a Combo Task taking an array of Tasks.
GROUP.TaskCondition: Return a condition section for a controlled task.
GROUP.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:

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

GROUP.CommandDoScript: Do Script command.
GROUP.CommandSwitchWayPoint: Perform a switch waypoint command.

1.4) GROUP Option methods

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

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

GROUP.OptionROEWeaponFreePossible
GROUP.OptionROEOpenFirePossible
GROUP.OptionROEReturnFirePossible
GROUP.OptionROEEvadeFirePossible

1.4.2) Rule on thread:

GROUP.OptionROTNoReaction
GROUP.OptionROTPassiveDefense
GROUP.OptionROTEvadeFire
GROUP.OptionROTVertical

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

GROUP.OptionROTNoReactionPossible
GROUP.OptionROTPassiveDefensePossible
GROUP.OptionROTEvadeFirePossible
GROUP.OptionROTVerticalPossible

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 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.ClassName
GROUP:CopyRoute(Begin, End, Randomize, Radius)	Return the route of a group by using the 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:GetPointVec2()	Returns the current point (Vec2 vector) of the first DCS Unit in the DCS Group.
GROUP:GetPointVec3()	Returns the current point (Vec3 vector) of the first DCS Unit in the DCS 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()
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.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:Message(Message, Duration)	Returns a message for a coalition or a client.
GROUP:MessageToAll(Message, Duration)	Send a message to all coalitions.
GROUP:MessageToBlue(Message, Duration)	Send a message to the blue coalition.
GROUP:MessageToClient(Message, Duration, Client)	Send a message to a client.
GROUP:MessageToRed(Message, Duration)	Send a message to the red coalition.
GROUP:Register(GroupName)	Create a new GROUP from a DCSGroup
GROUP:Respawn(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.

#string GROUP.ClassName

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

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

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

DCSCoalitionObject#coalition.side: The coalition side of the DCS Group.

GROUP:GetCountry()

Returns the country of the DCS Group.

Return values

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

GROUP:GetDCSObject()

Returns the DCS Group.

Return value

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

DCSUnit#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:GetPointVec2()

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

Return value

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

GROUP:GetPointVec3()

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

Return value

DCSTypes#Vec3: Current Vec3 point of the first DCS Unit of the DCS 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()

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

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.

#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

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

Zone#ZONE_BASE Zone : The zone to test.

Return value

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

GROUP:IsPartlyInZone(Zone)

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

Parameter

Zone#ZONE_BASE Zone : The zone to test.

Return value

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

GROUP:IsShip()

Returns if the DCS Group contains Ships.

Return value

#boolean: true if DCS Group contains Ships.

GROUP:Message(Message, Duration)

Returns a message for a coalition or a client.

Parameters

#string Message : The message text
DCSTypes#Duration Duration : The duration of the message.

Return value

Message#MESSAGE:

GROUP:MessageToAll(Message, Duration)

Send a message to all coalitions.

The message will appear in the message area. The message will begin with the callsign of the group and the type of the first unit sending the message.

Parameters

#string Message : The message text
DCSTypes#Duration Duration : The duration of the message.

GROUP:MessageToBlue(Message, Duration)

Send a message to the blue coalition.

The message will appear in the message area. The message will begin with the callsign of the group and the type of the first unit sending the message.

Parameters

#string Message : The message text
DCSTypes#Duration Duration : The duration of the message.

GROUP:MessageToClient(Message, Duration, Client)

Send a message to a client.

The message will appear in the message area. The message will begin with the callsign of the group and the type of the first unit sending the message.

Parameters

#string Message : The message text
DCSTypes#Duration Duration : The duration of the message.
Client#CLIENT Client : The client object receiving the message.

GROUP:MessageToRed(Message, Duration)

Send a message to the red coalition.

The message will appear in the message area. The message will begin with the callsign of the group and the type of the first unit sending the message.

Parameters

#string Message : The message text
DCSTYpes#Duration Duration : The duration of the message.

GROUP:Register(GroupName)

Create a new GROUP from a DCSGroup

Parameter

DCSGroup#Group GroupName : The DCS Group name

Return value

#GROUP: self

GROUP:Respawn(Template)

Parameter

Template :

Modules

Module Group

1) Group#GROUP class, extends 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

Return value

Parameter

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

Parameters

Return value

Parameters

Parameters

Parameters

Parameters

Parameter

Return value

Parameter

Module `Group`

Type `GROUP`

Type `Group`

Type `GROUP`