Module Arty

  • Functional - (R2.4) Control artillery units.

Banner Image


The ARTY class can be used to easily assign and manage targets for artillery units.

Features:

  • Multiple targets can be assigned. No restriction on number of targets.
  • Targets can be given a priority. Engagement of targets is executed a according to their priority.
  • Engagements can be scheduled, i.e. will be executed at a certain time of the day.
  • Special weapon types can be selected for each attack, e.g. cruise missiles for Naval units.
  • Automatic rearming once the artillery is out of ammo.
  • New targets can be added during the mission, e.g. when they are detected by recon units.
  • Finite state machine implementation. Mission designer can interact when certain events occur.

Demo Missions

MOOSE - ALL Demo Missions


YouTube Channel

MOOSE YouTube Channel


Author: funkyfranky

Contributions: FlightControl


Global(s)

ARTY

ARTY class, extends Core.Fsm#FSM_CONTROLLABLE

The ARTY class enables mission designers easily to assign targets for artillery units.

Type ARTY

ARTY:AssignMoveCoord(coord, time, speed, onroad, cancel, name)

Assign coordinate to where the ARTY group should move.

ARTY:AssignTargetCoord(coord, prio, radius, nshells, maxengage, time, weapontype, name, unique)

Assign target coordinates to the ARTY group.

ARTY.ClassName

Name of the class.

ARTY.DCSdesc

DCS descriptors of the ARTY group.

ARTY.Debug

Write Debug messages to DCS log file and send Debug messages to all players.

ARTY.DisplayName

Extended type name of the ARTY group.

ARTY.FullAmmo

Full amount of all ammunition taking the number of alive units into account.

ARTY:GetAmmo(display)

Get the number of shells a unit or group currently has.

ARTY.IniGroupStrength

Inital number of units in the ARTY group.

ARTY.InitialCoord

Initial coordinates of the ARTY group.

ARTY.IsArtillery

If true, ARTY group has attribute "Artillery".

ARTY.Nammo0

Initial amount total ammunition (shells+rockets+missiles) of the whole group.

ARTY:New(group)

Creates a new ARTY object.

ARTY.Nmissiles0

Initial amount of missiles of the whole group.

ARTY.Nrockets0

Initial amount of rockets of the whole group.

ARTY.Nshells0

Initial amount of shells of the whole group.

ARTY.Nshots

Number of shots fired on current target.

ARTY.RearmingArtyOnRoad

If true, ARTY group will move to rearming place using mainly roads. Default false.

ARTY.RearmingDistance

Safe distance in meters between ARTY group and rearming group or place at which rearming is possible. Default 100 m.

ARTY.RearmingGroup

Unit designated to rearm the ARTY group.

ARTY.RearmingGroupCoord

Initial coordinates of the rearming unit. After rearming complete, the unit will return to this position.

ARTY.RearmingGroupOnRoad

If true, rearming group will move to ARTY group or rearming place using mainly roads. Default false.

ARTY.RearmingGroupSpeed

Speed in km/h the rearming unit moves at. Default 50 km/h.

ARTY.RearmingPlaceCoord

Coordinates of the rearming place. If the place is more than 100 m away from the ARTY group, the group will go there.

ARTY:RemoveAllTargets()

Delete ALL targets from current target list.

ARTY:RemoveMove(name)

Delete a move from move list.

ARTY:RemoveTarget(name)

Delete a target from target list.

ARTY:SetDebugOFF()

Turn debug mode off.

ARTY:SetDebugON()

Turn debug mode on.

ARTY:SetMaxFiringRange(range)

Set maximum firing range.

ARTY:SetMinFiringRange(range)

Set minimum firing range.

ARTY:SetMissileTypes(tableofnames)

Define missile types that are counted to determine the ammo amount the ARTY group has.

ARTY:SetRearmingArtyOnRoad(onroad)

Define if ARTY group uses mainly roads to drive to the rearming place.

ARTY:SetRearmingDistance(distance)

Define the safe distance between ARTY group and rearming unit or rearming place at which rearming process is possible.

ARTY:SetRearmingGroup(group)

Assign a group, which is responsible for rearming the ARTY group.

ARTY:SetRearmingGroupOnRoad(onroad)

Define if rearming group uses mainly roads to drive to the ARTY group or rearming place.

ARTY:SetRearmingGroupSpeed(speed)

Set the speed the rearming group moves at towards the ARTY group or the rearming place.

ARTY:SetRearmingPlace(coord)

Defines the rearming place of the ARTY group.

ARTY:SetReportOFF()

Report messages of ARTY group turned off.

ARTY:SetReportON()

Report messages of ARTY group turned on.

ARTY:SetRocketTypes(tableofnames)

Define rocket types that are counted to determine the ammo amount the ARTY group has.

ARTY:SetShellTypes(tableofnames)

Define shell types that are counted to determine the ammo amount the ARTY group has.

ARTY:SetStatusInterval(interval)

Set time interval between status updates.

ARTY:SetWaitForShotTime(waittime)

Set time how it is waited a unit the first shot event happens.

ARTY.Speed

Default speed in km/h the ARTY group moves at. Maximum speed possible is 80% of maximum speed the group can do.

ARTY.SpeedMax

Maximum speed of ARTY group in km/h. This is determined from the DCS descriptor table.

ARTY.StatusInterval

Update interval in seconds between status updates. Default 10 seconds.

ARTY.Type

Type of the ARTY group.

ARTY.WaitForShotTime

Max time in seconds to wait until fist shot event occurs after target is assigned. If time is passed without shot, the target is deleted. Default is 300 seconds.

ARTY.WeaponType

Weapong type ID.

ARTY:_CheckMoves()

Check all moves and return the one which should be executed next.

ARTY:_CheckName(givennames, name, makeunique)

Check if a name is unique.

ARTY:_CheckNormalTargets()

Check all normal (untimed) targets and return the target with the highest priority which has been engaged the fewest times.

ARTY:_CheckRearmed()

Check if ARTY group is rearmed, i.e.

ARTY:_CheckShootingStarted()

Check whether shooting started within a certain time (~5 min).

ARTY:_CheckTimedTargets()

Check all timed targets and return the target which should be attacked next.

ARTY:_ClockToSeconds(clock)

Convert clock time from hours, minutes and seconds to seconds.

ARTY:_EventFromTo(BA, Event, From, To)

Print event-from-to string to DCS log file.

ARTY:_FireAtCoord(coord, radius, nshells, weapontype)

Set task for firing at a coordinate.

ARTY:_GetMoveIndexByName(name)

Get the index of a move by its name.

ARTY:_GetTargetIndexByName(name)

Get the index of a target by its name.

ARTY:_Move(group, ToCoord, Speed, OnRoad)

Route group to a certain point.

ARTY:_MoveInfo(move)

Returns a formatted string with information about all move parameters.

ARTY:_OnEventDead(EventData)

Event handler for event Dead.

ARTY:_OnEventShot(EventData)

Eventhandler for shot event.

ARTY._PassingWaypoint(group, arty, i, final)

Function called when group is passing a waypoint.

ARTY:_SecondsToClock(seconds)

Convert time in seconds to hours, minutes and seconds.

ARTY:_SortQueueTime(queue)

Sort array with respect to time.

ARTY:_SortTargetQueuePrio()

Sort targets with respect to priority and number of times it was already engaged.

ARTY:_StatusReport()

After "Start" event.

ARTY:_TargetInRange(target)

Check if target is in range.

ARTY:_TargetInfo(target)

Returns the target parameters as formatted string.

ARTY:_VicinityCoord(coord, rmin, rmax)

Find a random coordinate in the vicinity of another coordinate.

ARTY:_WeaponTypeName(tnumber)

Get the weapon type name, which should be used to attack the target.

ARTY:_split(str, sep)

Split string.

ARTY.ammomissiles

Table holding names of the missile types which are included when counting the ammo. Default is {"weapons.missiles"} which includes some guided missiles.

ARTY.ammorockets

Table holding names of the rocket types which are included when counting the ammo. Default is {"weapons.nurs"} which includes most unguided rockets.

ARTY.ammoshells

Table holding names of the shell types which are included when counting the ammo. Default is {"weapons.shells"} which include most shells.

ARTY.currentMove

Holds the current commanded move, if there is one assigned.

ARTY.currentTarget

Holds the current target, if there is one assigned.

ARTY.id

Some ID to identify who we are in output of the DCS.log file.

ARTY.maxrange

Maximum firing range in kilometers. Targets further away than this distance are not engaged. Default 10000 km.

ARTY.minrange

Minimum firing range in kilometers. Targets closer than this distance are not engaged. Default 0.5 km.

ARTY.moves

All moves assigned.

ARTY:onafterArrived(Controllable, From, Event, To)

After "Arrived" event.

ARTY:onafterCeaseFire(Controllable, From, Event, To, target)

After "CeaseFire" event.

ARTY:onafterDead(Controllable, From, Event, To)

After "Dead" event, when a unit has died.

ARTY:onafterMove(Controllable, From, Event, To, ToCoord, Speed, OnRoad)

After "Move" event.

ARTY:onafterNewMove(Controllable, From, Event, To, move)

After "NewMove" event.

ARTY:onafterNewTarget(Controllable, From, Event, To, target)

After "NewTarget" event.

ARTY:onafterOpenFire(Controllable, From, Event, To, target)

After "OpenFire" event.

ARTY:onafterRearm(Controllable, From, Event, To)

After "Rearm" event.

ARTY:onafterRearmed(Controllable, From, Event, To)

After "Rearmed" event.

ARTY:onafterStart(Controllable, From, Event, To)

After "Start" event.

ARTY:onafterStatus(Controllable, From, Event, To)

After "Status" event.

ARTY:onafterStop(Controllable, From, Event, To)

After "Stop" event.

ARTY:onafterWinchester(Controllable, From, Event, To)

After "Winchester" event.

ARTY:onbeforeMove(Controllable, From, Event, To, ToCoord, OnRoad)

Before "Move" event.

ARTY:onbeforeOpenFire(Controllable, From, Event, To, target)

Before "OpenFire" event.

ARTY:onbeforeRearm(Controllable, From, Event, To)

Before "Rearm" event.

ARTY:onenterCombatReady(Controllable, From, Event, To)

Enter "CombatReady" state.

ARTY.report

Arty group sends messages about their current state or target to its coaliton.

ARTY.targets

All targets assigned.

ARTY.version

Arty script version.

Global(s)

#ARTY ARTY

ARTY class, extends Core.Fsm#FSM_CONTROLLABLE

The ARTY class enables mission designers easily to assign targets for artillery units.

Since the implementation is based on a Finite State Model (FSM), the mission designer can interact with the process at certain events or states.

A new ARTY object can be created with the ARTY.New(group) contructor. The parameter group has to be a MOOSE Group object and defines ARTY group.

The ARTY FSM process can be started by the ARTY.Start() command.

The ARTY Process

Process

Blue Branch

After the FMS process is started the ARTY group will be in the state CombatReady. Once a target is assigned the OpenFire event will be triggered and the group starts firing. At this point the group in in the state Firing. When the defined number of shots has been fired on the current target the event CeaseFire is triggered. The group will stop firing and go back to the state CombatReady. If another target is defined (or multiple engagements of the same target), the cycle starts anew.

Violet Branch

When the ARTY group runs out of ammunition, the event Winchester is triggered and the group enters the state OutOfAmmo. In this state, the group is unable to engage further targets.

Red Branch

With the ARTY.SetRearmingGroup(group) command, a special group can be defined to rearm the ARTY group. If this unit has been assigned and the group has entered the state OutOfAmmo the event Rearm is triggered followed by a transition to the state Rearming. If the rearming group is less than 100 meters away from the ARTY group, the rearming process starts. If the rearming group is more than 100 meters away from the ARTY unit, the rearming group is routed to a point 20 to 100 m from the ARTY group.

Once the rearming is complete, the Rearmed event is triggered and the group enters the state CombatReady. At this point targeted can be engaged again.

Green Branch

The ARTY group can be ordered to change its position via the ARTY.AssignMoveCoord() function as described below. When the group receives the command to move the event Move is triggered and the state changes to Moving. When the unit arrives to its destination the event Arrived is triggered and the group becomes CombatReady again.

Note, that the ARTY group will not open fire while it is in state Moving. This property differentiates artillery from tanks.

Yellow Branch

When a new target is assigned via the ARTY.AssignTargetCoord() function (see below), the NewTarget event is triggered.

Assigning Targets

Assigning targets is a central point of the ARTY class. Multiple targets can be assigned simultanioulsly and are put into a queue. Of course, targets can be added at any time during the mission. For example, once they are detected by a reconnaissance unit.

In order to add a target, the function ARTY.AssignTargetCoord(coord, prio, radius, nshells, maxengage, time, weapontype, name) has to be used. Only the first parameter coord is mandatory while all remaining parameters are all optional.

Parameters:

  • coord: Coordinates of the target, given as Point#COORDINATE object.
  • prio: Priority of the target. This a number between 1 (high prio) and 100 (low prio). Targets with higher priority are engaged before targets with lower priority.
  • radius: Radius in meters which defines the area the ARTY group will attempt to be hitting. Default is 100 meters.
  • nshells: Number of shots (shells, rockets, missiles) fired by the group at each engagement of a target. Default is 5.
  • maxengage: Number of times a target is engaged.
  • time: Time of day the engagement is schedule in the format "hh:mm:ss" for hh=hours, mm=minutes, ss=seconds. For example "10:15:35". In the case the attack will be executed at a quarter past ten in the morning at the day the mission started. If the engagement should start on the following day the format can be specified as "10:15:35+1", where the +1 denots the following day. This is useful for longer running missions or if the mission starts at 23:00 hours and the attack should be scheduled at 01:00 hours on the following day. Of course, later days are also possible by appending "+2", "+3", etc. Note that the time has to be given as a string. So the enclosing quotation marks "" are important.
  • weapontype: Specified the weapon type that should be used for this attack if the ARTY group has multiple weapons to engage the target. For example, this is useful for naval units which carry a bigger arsenal (cannons and missiles). Default is Auto, i.e. DCS logic selects the appropriate weapon type. name: A special name can be defined for this target. Default name are the coordinates of the target in LL DMS format. If a name is already given for another target or the same target should be attacked two or more times with different parameters a suffix "#01", "#02", "#03" is automatically appended to the specified name.

Target Queue

In case multiple targets have been defined, it is important to understand how the target queue works.

Here, the essential parameters are the priority prio, the number of engagements maxengage and the scheduled time as described above.

For example, we have assigned two targets one with prio=10 and the other with prio=50 and both targets should be engaged three times (maxengage=3). Let's first consider the case that none of the targets is scheduled to be executed at a certain time (time=nil). The ARTY group will first engage the target with higher priority (prio=10). After the engagement is finished, the target with lower priority is attacked. This is because the target with lower prio has been attacked one time less. After the attack on the lower priority task is finished and both targets have been engaged equally often, the target with the higher priority is engaged again. This coninues until a target has engaged three times. Once the maximum number of engagements is reached, the target is deleted from the queue.

In other words, the queue is first sorted with respect to the number of engagements and targets with the same number of engagements are sorted with respect to their priority.

Timed Engagements

As mentioned above, targets can be engaged at a specific time of the day via the time parameter.

If the time parameter is specified for a target, the first engagement of that target will happen at that time of the day and not before. This also applies when multiple engagements are requested via the maxengage parameter. The first attack will not happen before the specifed time. When that timed attack is finished, the time parameter is deleted and the remaining engagements are carried out in the same manner as for untimed targets (described above).

Of course, it can happen that a scheduled task should be executed at a time, when another target is already under attack. If the priority of the target is higher than the priority of the current target, then the current attack is cancelled and the engagement of the target with the higher priority is started.

By contrast, if the current target has a higher priority than the target scheduled at that time, the current attack is finished before the scheduled attack is started.

Determining the Amount of Ammo

In order to determin when a unit is out of ammo and possible initiate the rearming process it is necessary to know which types of weapons have to be counted. For most artillery unit types, this is simple because they only have one type of weapon and hence ammunition.

However, there are more complex scenarios. For example, naval units carry a big arsenal of different ammunition types ranging from various cannon shell types over surface-to-air missiles to cruise missiles. Obviously, not all of these ammo types can be employed for artillery tasks.

Unfortunately, there is no easy way to count only those ammo types useable as artillery. Therefore, to keep the implementation general the user can specify the names of the ammo types by the following functions:

  • ARTY.SetShellTypes(tableofnames): Defines the ammo types for unguided cannons. Default is tableofnames={"weapons.shells"}, i.e. all types of shells are counted.
  • ARTY.SetRocketTypes(tableofnames): Defines the ammo types of unguided rockets. Default is tableofnames={"weapons.nurs"}, i.e. all types of rockets are counted.
  • ARTY.SetMissileTypes(tableofnames): Defines the ammo types of guided missiles. Default is tableofnames={"weapons.missiles"}, i.e. all types of missiles are counted.

Note that the default parameters "weapons.shells", "weapons.nurs", "weapons.missiles" should in priciple capture all the corresponding ammo types. However, the logic searches for the string "weapon.missies" in the ammo type. Especially for missiles, this string is often not contained in the ammo type descriptor.

One way to determin which types of ammo the unit carries, one can use the debug mode of the arty class via ARTY.SetDebugON(). In debug mode, the all ammo types of the group are printed to the monitor as message and can be found in the DCS.log file.

Empoying Selected Weapons

If an ARTY group carries multiple weapons, which can be used for artillery task, a certain weapon type can be selected to attack the target. This is done via the weapontype parameter of the ARTY.AssignTargetCoord(..., weapontype, ...) function.

The enumerator ARTY.WeaponType has been defined to select a certain weapon type. Supported values are:

Assigning Moves

The ARTY group can be commanded to move. This is done by the ARTY.AssignMoveCoord(*coord,time,speed,onroad,cancel,name*) function. With this multiple timed moves of the group can be scheduled easily. By default, these moves will only be executed if the group is state CombatReady.

Parameters

  • coord: Coordinates where the group should move to given as Point#COORDINATE object.
  • time: The time when the move should be executed. This has to be given as a string in the format "hh:mm:ss" (hh=hours, mm=minutes, ss=seconds).
  • speed: Speed of the group in km/h.
  • onroad: If this parameter is set to true, the group uses mainly roads to get to the commanded coordinates.
  • cancel: If set to true, any current engagement of targets is cancelled at the time the move should be executed.
  • name: Can be used to set a user defined name of the move. By default the name is created from the LL DMS coordinates.

Automatic Rearming

If an ARTY group runs out of ammunition, it can be rearmed automatically.

Rearming Group

The first way to activate the automatic rearming is to define a rearming group with the function ARTY.SetRearmingGroup(group). For the blue side, this could be a M181 transport truck and for the red side an Ural-375 truck.

Once the ARTY group is out of ammo and the Rearm event is triggered, the defined rearming truck will drive to the ARTY group. So the rearming truck does not have to be placed nearby the artillery group. When the rearming is complete, the rearming truck will drive back to its original position.

Rearming Place

The second alternative is to define a rearming place, e.g. a FRAP, airport or any other warehouse. This is done with the function ARTY.SetRearmingPlace(coord). The parameter coord specifies the coordinate of the rearming place which should not be further away then 100 meters from the warehouse.

When the Rearm event is triggered, the ARTY group will move to the rearming place. Of course, the group must be mobil. So for a mortar this rearming procedure would not work.

After the rearming is complete, the ARTY group will move back to its original position and resume normal operations.

Rearming Group and Rearming Place

If both a rearming group and a rearming place are specified like described above, both the ARTY group and the rearming truck will move to the rearming place and meet there.

After the rearming is complete, both groups will move back to their original positions.

Fine Tuning

The mission designer has a few options to tailor the ARTY object according to his needs.

  • ARTY.RemoveAllTargets() removes all targets from the target queue.
  • ARTY.RemoveTarget(name) deletes the target with name from the target queue.
  • ARTY.SetMaxFiringRange(range) defines the maximum firing range. Targets further away than this distance are not engaged.
  • ARTY.SetMinFiringRange(range) defines the minimum firing range. Targets closer than this distance are not engaged.
  • ARTY.SetRearmingGroup(group) sets the group resposible for rearming of the ARTY group once it is out of ammo.
  • ARTY.SetReportON() and ARTY.SetReportOFF() can be used to enable/disable status reports of the ARTY group send to all coalition members.
  • ARTY.SetWaitForShotTime(waittime) sets the time after which a target is deleted from the queue if no shooting event occured after the target engagement started. Default is 300 seconds. Note that this can for example happen, when the assigned target is out of range.
  • ARTY.SetDebugON() and ARTY.SetDebugOFF() can be used to enable/disable the debug mode.

Examples

Assigning Multiple Targets

This basic example illustrates how to assign multiple targets and defining a rearming group.

-- Creat a new ARTY object from a Paladin group.
paladin=ARTY:New(GROUP:FindByName("Blue Paladin"))

-- Define a rearming group. This is a Transport M818 truck.
paladin:SetRearmingGroup(GROUP:FindByName("Blue Ammo Truck"))

-- Set the max firing range. A Paladin unit has a range of 20 km.
paladin:SetMaxFiringRange(20)

-- Low priorty (90) target, will be engage last. Target is engaged two times. At each engagement five shots are fired.
paladin:AssignTargetCoord(GROUP:FindByName("Red Targets 3"):GetCoordinate(),  90, nil,  5, 2)
-- Medium priorty (nil=50) target, will be engage second. Target is engaged two times. At each engagement ten shots are fired.
paladin:AssignTargetCoord(GROUP:FindByName("Red Targets 1"):GetCoordinate(), nil, nil, 10, 2)
-- High priorty (10) target, will be engage first. Target is engaged three times. At each engagement twenty shots are fired.
paladin:AssignTargetCoord(GROUP:FindByName("Red Targets 2"):GetCoordinate(),  10, nil, 20, 3)

-- Start ARTY process.
paladin:Start()

Note

  • If a parameter should be set to its default value, it has to be set to nil if other non-default parameters follow. Parameters at the end can simply be skiped.
  • In this example, the target coordinates are taken from groups placed in the mission edit using the COORDINATE:GetCoordinate() function.

Scheduled Engagements

-- Mission starts at 8 o'clock.
-- Assign two scheduled targets.

-- Create ARTY object from Paladin group.
paladin=ARTY:New(GROUP:FindByName("Blue Paladin"))

-- Assign target coordinates. Priority=50 (medium), radius=100 m, use 5 shells per engagement, engage 1 time at two past 8 o'clock.
paladin:AssignTargetCoord(GROUP:FindByName("Red Targets 1"):GetCoordinate(), 50, 100,  5, 1, "08:02:00", ARTY.WeaponType.Auto, "Target 1")

-- Assign target coordinates. Priority=10 (high), radius=300 m, use 10 shells per engagement, engage 1 time at seven past 8 o'clock.
paladin:AssignTargetCoord(GROUP:FindByName("Red Targets 2"):GetCoordinate(), 10, 300, 10, 1, "08:07:00", ARTY.WeaponType.Auto, "Target 2")

-- Start ARTY process.
paladin:Start()

Specific Weapons

This example demonstrates how to use specific weapons during an engagement.

-- Define the Normandy as ARTY object.
normandy=ARTY:New(GROUP:FindByName("Normandy"))

-- Add target: prio=50, radius=300 m, number of missiles=20, number of engagements=1, start time=08:05 hours, only use cruise missiles for this attack.
normandy:AssignTargetCoord(GROUP:FindByName("Red Targets 1"):GetCoordinate(),  20, 300,  50, 1, "08:01:00", ARTY.WeaponType.CruiseMissile)

-- Add target: prio=50, radius=300 m, number of shells=100, number of engagements=1, start time=08:15 hours, only use cannons during this attack.
normandy:AssignTargetCoord(GROUP:FindByName("Red Targets 1"):GetCoordinate(),  50, 300, 100, 1, "08:15:00", ARTY.WeaponType.Cannon)

-- Define shells that are counted to check whether the ship is out of ammo.
-- Note that this is necessary because the Normandy has a lot of other shell type weapons which cannot be used to engage ground targets in an artillery style manner.
normandy:SetShellTypes({"MK45_127"})

-- Define missile types that are counted.
normandy:SetMissileTypes({"BGM"})

-- Start ARTY process.
normandy:Start()

Type Arty

Type ARTY

Extends Core.Fsm#FSM_CONTROLLABLE

  • ARTY class

Field(s)

ARTY:AssignMoveCoord(coord, time, speed, onroad, cancel, name)

Assign coordinate to where the ARTY group should move.

Parameters

  • Wrapper.Point#COORDINATE coord : Coordinates of the target.

  • #string time : (Optional) Day time at which the group should start moving. Passed as a string in format "08:13:45".

  • #number speed : (Optinal) Speed in km/h the group should move at. Default 50 km/h.

  • #boolean onroad : (Optional) If true, group will mainly use roads. Default off, i.e. go directly towards the specified coordinate.

  • #boolean cancel : (Optional) If true, cancel any running attack when move should begin. Default is false.

  • #string name : (Optional) Name of the coordinate. Default is LL DMS string of the coordinate. If the name was already given, the numbering "#01", "#02",... is appended automatically.

Return value

#string: Name of the move. Can be used for further reference, e.g. deleting the move from the list.

ARTY:AssignTargetCoord(coord, prio, radius, nshells, maxengage, time, weapontype, name, unique)

Assign target coordinates to the ARTY group.

Only the first parameter, i.e. the coordinate of the target is mandatory. The remaining parameters are optional and can be used to fine tune the engagement.

Parameters

  • Wrapper.Point#COORDINATE coord : Coordinates of the target.

  • #number prio : (Optional) Priority of target. Number between 1 (high) and 100 (low). Default 50.

  • #number radius : (Optional) Radius. Default is 100 m.

  • #number nshells : (Optional) How many shells (or rockets) are fired on target per engagement. Default 5.

  • #number maxengage : (Optional) How many times a target is engaged. Default 1.

  • #string time : (Optional) Day time at which the target should be engaged. Passed as a string in format "08:13:45". Current task will be canceled.

  • #number weapontype : (Optional) Type of weapon to be used to attack this target. Default ARTY.WeaponType.Auto, i.e. the DCS logic automatically determins the appropriate weapon.

  • #string name : (Optional) Name of the target. Default is LL DMS coordinate of the target. If the name was already given, the numbering "#01", "#02",... is appended automatically.

  • #boolean unique : (Optional) Target is unique. If the target name is already known, the target is rejected. Default false.

Return value

#string: Name of the target. Can be used for further reference, e.g. deleting the target from the list.

Usage:

paladin=ARTY:New(GROUP:FindByName("Blue Paladin"))
paladin:AssignTargetCoord(GROUP:FindByName("Red Targets 1"):GetCoordinate(), 10, 300, 10, 1, "08:02:00", ARTY.WeaponType.Auto, "Target 1")
paladin:Start()
#string ARTY.ClassName

Name of the class.

#table ARTY.DCSdesc

DCS descriptors of the ARTY group.

#boolean ARTY.Debug

Write Debug messages to DCS log file and send Debug messages to all players.

#string ARTY.DisplayName

Extended type name of the ARTY group.

#number ARTY.FullAmmo

Full amount of all ammunition taking the number of alive units into account.

ARTY:GetAmmo(display)

Get the number of shells a unit or group currently has.

For a group the ammo count of all units is summed up.

Parameter

  • #boolean display : Display ammo table as message to all. Default false.

Return values

  1. #number: Total amount of ammo the whole group has left.

  2. #number: Number of shells the group has left.

  3. #number: Number of rockets the group has left.

  4. #number: Number of missiles the group has left.

#number ARTY.IniGroupStrength

Inital number of units in the ARTY group.

Core.Point#COORDINATE ARTY.InitialCoord

Initial coordinates of the ARTY group.

#boolean ARTY.IsArtillery

If true, ARTY group has attribute "Artillery".

#number ARTY.Nammo0

Initial amount total ammunition (shells+rockets+missiles) of the whole group.

ARTY:New(group)

Creates a new ARTY object.

Parameter

Return values

  1. #ARTY: ARTY object.

  2. nil If group does not exist or is not a ground or naval group.

#number ARTY.Nmissiles0

Initial amount of missiles of the whole group.

#number ARTY.Nrockets0

Initial amount of rockets of the whole group.

#number ARTY.Nshells0

Initial amount of shells of the whole group.

#number ARTY.Nshots

Number of shots fired on current target.

#boolean ARTY.RearmingArtyOnRoad

If true, ARTY group will move to rearming place using mainly roads. Default false.

#number ARTY.RearmingDistance

Safe distance in meters between ARTY group and rearming group or place at which rearming is possible. Default 100 m.

Wrapper.Group#GROUP ARTY.RearmingGroup

Unit designated to rearm the ARTY group.

Core.Point#COORDINATE ARTY.RearmingGroupCoord

Initial coordinates of the rearming unit. After rearming complete, the unit will return to this position.

#boolean ARTY.RearmingGroupOnRoad

If true, rearming group will move to ARTY group or rearming place using mainly roads. Default false.

#number ARTY.RearmingGroupSpeed

Speed in km/h the rearming unit moves at. Default 50 km/h.

Core.Point#COORDINATE ARTY.RearmingPlaceCoord

Coordinates of the rearming place. If the place is more than 100 m away from the ARTY group, the group will go there.

ARTY:RemoveAllTargets()

Delete ALL targets from current target list.

ARTY:RemoveMove(name)

Delete a move from move list.

Parameter

  • #string name : Name of the target.

ARTY:RemoveTarget(name)

Delete a target from target list.

Parameter

  • #string name : Name of the target.

ARTY:SetDebugOFF()

Turn debug mode off.

This is the default setting.

ARTY:SetDebugON()

Turn debug mode on.

Information is printed to screen.

ARTY:SetMaxFiringRange(range)

Set maximum firing range.

Targets further away than this distance are not engaged.

Parameter

  • #number range : Max range in kilometers. Default is 1000 km.

ARTY:SetMinFiringRange(range)

Set minimum firing range.

Targets closer than this distance are not engaged.

Parameter

  • #number range : Min range in kilometers. Default is 0.5 km.

ARTY:SetMissileTypes(tableofnames)

Define missile types that are counted to determine the ammo amount the ARTY group has.

Parameter

  • #table tableofnames : Table of rocket type names.

ARTY:SetRearmingArtyOnRoad(onroad)

Define if ARTY group uses mainly roads to drive to the rearming place.

Parameter

  • #boolean onroad : If true, ARTY group uses mainly roads. If false, it drives directly to the rearming place.

ARTY:SetRearmingDistance(distance)

Define the safe distance between ARTY group and rearming unit or rearming place at which rearming process is possible.

Parameter

  • #number distance : Safe distance in meters. Default is 100 m.

ARTY:SetRearmingGroup(group)

Assign a group, which is responsible for rearming the ARTY group.

If the group is too far away from the ARTY group it will be guided towards the ARTY group.

Parameter

ARTY:SetRearmingGroupOnRoad(onroad)

Define if rearming group uses mainly roads to drive to the ARTY group or rearming place.

Parameter

  • #boolean onroad : If true, rearming group uses mainly roads. If false, it drives directly to the ARTY group or rearming place.

ARTY:SetRearmingGroupSpeed(speed)

Set the speed the rearming group moves at towards the ARTY group or the rearming place.

Parameter

  • #number speed : Speed in km/h. Default 50 km/h.

ARTY:SetRearmingPlace(coord)

Defines the rearming place of the ARTY group.

If the place is too far away from the ARTY group it will be routed to the place.

Parameter

ARTY:SetReportOFF()

Report messages of ARTY group turned off.

Default is on.

ARTY:SetReportON()

Report messages of ARTY group turned on.

This is the default.

ARTY:SetRocketTypes(tableofnames)

Define rocket types that are counted to determine the ammo amount the ARTY group has.

Parameter

  • #table tableofnames : Table of rocket type names.

ARTY:SetShellTypes(tableofnames)

Define shell types that are counted to determine the ammo amount the ARTY group has.

Parameter

  • #table tableofnames : Table of shell type names.

ARTY:SetStatusInterval(interval)

Set time interval between status updates.

During the status check, new events are triggered.

Parameter

  • #number interval : Time interval in seconds. Default 10 seconds.

ARTY:SetWaitForShotTime(waittime)

Set time how it is waited a unit the first shot event happens.

If no shot is fired after this time, the task to fire is aborted and the target removed.

Parameter

  • #number waittime : Time in seconds. Default 300 seconds.

#number ARTY.Speed

Default speed in km/h the ARTY group moves at. Maximum speed possible is 80% of maximum speed the group can do.

#number ARTY.SpeedMax

Maximum speed of ARTY group in km/h. This is determined from the DCS descriptor table.

#number ARTY.StatusInterval

Update interval in seconds between status updates. Default 10 seconds.

#string ARTY.Type

Type of the ARTY group.

#number ARTY.WaitForShotTime

Max time in seconds to wait until fist shot event occurs after target is assigned. If time is passed without shot, the target is deleted. Default is 300 seconds.

#table ARTY.WeaponType

Weapong type ID.

http://wiki.hoggit.us/view/DCSenumweapon_flag

ARTY:_CheckMoves()

Check all moves and return the one which should be executed next.

Return value

#table: Move which is due.

ARTY:_CheckName(givennames, name, makeunique)

Check if a name is unique.

If not, a new unique name can be created by adding a running index #01, #02, ...

Parameters

  • #table givennames : Table with entries of already given names. Must contain a .name item.

  • #string name : Name to check if it already exists in givennames table.

  • #boolean makeunique : If true, a new unique name is returned by appending the running index.

Return value

#string: Unique name, which is not already given for another target.

ARTY:_CheckNormalTargets()

Check all normal (untimed) targets and return the target with the highest priority which has been engaged the fewest times.

Return value

#table: Target which is due to be attacked now or nil if no target could be found.

ARTY:_CheckRearmed()

Check if ARTY group is rearmed, i.e.

has its full amount of ammo.

Return value

#boolean: True if rearming is complete, false otherwise.

ARTY:_CheckShootingStarted()

Check whether shooting started within a certain time (~5 min).

If not, the current target is considered invalid and removed from the target list.

ARTY:_CheckTimedTargets()

Check all timed targets and return the target which should be attacked next.

Return value

#table: Target which is due to be attacked now.

ARTY:_ClockToSeconds(clock)

Convert clock time from hours, minutes and seconds to seconds.

Parameter

  • #string clock : String of clock time. E.g., "06:12:35".

ARTY:_EventFromTo(BA, Event, From, To)

Print event-from-to string to DCS log file.

Parameters

  • #string BA : Before/after info.

  • #string Event : Event.

  • #string From : From state.

  • #string To : To state.

ARTY:_FireAtCoord(coord, radius, nshells, weapontype)

Set task for firing at a coordinate.

Parameters

  • Core.Point#COORDINATE coord : Coordinates to fire upon.

  • #number radius : Radius around coordinate.

  • #number nshells : Number of shells to fire.

  • #number weapontype : Type of weapon to use.

ARTY:_GetMoveIndexByName(name)

Get the index of a move by its name.

Parameter

  • #string name : Name of move.

Return value

#number: Arrayindex of move.

ARTY:_GetTargetIndexByName(name)

Get the index of a target by its name.

Parameter

  • #string name : Name of target.

Return value

#number: Arrayindex of target.

ARTY:_Move(group, ToCoord, Speed, OnRoad)

Route group to a certain point.

Parameters

ARTY:_MoveInfo(move)

Returns a formatted string with information about all move parameters.

Parameter

  • #table move : Move table item.

Return value

#string: Info string.

ARTY:_OnEventDead(EventData)

Event handler for event Dead.

Parameter

ARTY:_OnEventShot(EventData)

Eventhandler for shot event.

Parameter

ARTY._PassingWaypoint(group, arty, i, final)

Function called when group is passing a waypoint.

Parameters

  • Wrapper.Group#GROUP group : Group for which waypoint passing should be monitored.

  • #ARTY arty : ARTY object.

  • #number i : Waypoint number that has been reached.

  • #boolean final : True if it is the final waypoint.

ARTY:_SecondsToClock(seconds)

Convert time in seconds to hours, minutes and seconds.

Parameter

  • #number seconds : Time in seconds.

Return value

#string: Time in format Hours:minutes:seconds.

ARTY:_SortQueueTime(queue)

Sort array with respect to time.

Array elements must have a .time entry.

Parameter

  • #table queue : Array to sort. Should have elemnt .time.

ARTY:_SortTargetQueuePrio()

Sort targets with respect to priority and number of times it was already engaged.

ARTY:_StatusReport()

After "Start" event.

Initialized ROE and alarm state. Starts the event handler.

ARTY:_TargetInRange(target)

Check if target is in range.

Parameter

  • #table target : Target table.

Return value

#boolean: True if target is in range, false otherwise.

ARTY:_TargetInfo(target)

Returns the target parameters as formatted string.

Parameter

  • target :

Return value

#string: name, prio, radius, nshells, engaged, maxengage, time, weapontype

ARTY:_VicinityCoord(coord, rmin, rmax)

Find a random coordinate in the vicinity of another coordinate.

Parameters

  • Core.Point#COORDINATE coord : Center coordinate.

  • #number rmin : (Optional) Minimum distance in meters from center coordinate. Default 20 m.

  • #number rmax : (Optional) Maximum distance in meters from center coordinate. Default 80 m.

Return value

Core.Point#COORDINATE: Random coordinate in a certain distance from center coordinate.

ARTY:_WeaponTypeName(tnumber)

Get the weapon type name, which should be used to attack the target.

Parameter

  • #number tnumber : Number of weapon type ARTY.WeaponType.XXX

Return value

#number: tnumber of weapon type.

ARTY:_split(str, sep)

Split string.

C.f. http://stackoverflow.com/questions/1426954/split-string-in-lua

Parameters

  • #string str : Sting to split.

  • #string sep : Speparator for split.

Return value

#table: Split text.

#table ARTY.ammomissiles

Table holding names of the missile types which are included when counting the ammo. Default is {"weapons.missiles"} which includes some guided missiles.

#table ARTY.ammorockets

Table holding names of the rocket types which are included when counting the ammo. Default is {"weapons.nurs"} which includes most unguided rockets.

#table ARTY.ammoshells

Table holding names of the shell types which are included when counting the ammo. Default is {"weapons.shells"} which include most shells.

#table ARTY.currentMove

Holds the current commanded move, if there is one assigned.

#table ARTY.currentTarget

Holds the current target, if there is one assigned.

#string ARTY.id

Some ID to identify who we are in output of the DCS.log file.

#number ARTY.maxrange

Maximum firing range in kilometers. Targets further away than this distance are not engaged. Default 10000 km.

#number ARTY.minrange

Minimum firing range in kilometers. Targets closer than this distance are not engaged. Default 0.5 km.

#table ARTY.moves

All moves assigned.

ARTY:onafterArrived(Controllable, From, Event, To)

After "Arrived" event.

Group has reached its destination.

Parameters

ARTY:onafterCeaseFire(Controllable, From, Event, To, target)

After "CeaseFire" event.

Clears task of the group and removes the target if max engagement was reached.

Parameters

  • Wrapper.Controllable#CONTROLLABLE Controllable : Controllable of the group.

  • #string From : From state.

  • #string Event : Event.

  • #string To : To state.

  • #table target : Array holding the target info.

ARTY:onafterDead(Controllable, From, Event, To)

After "Dead" event, when a unit has died.

When all units of a group are dead trigger "Stop" event.

Parameters

ARTY:onafterMove(Controllable, From, Event, To, ToCoord, Speed, OnRoad)

After "Move" event.

Route group to given coordinate.

Parameters

  • Wrapper.Controllable#CONTROLLABLE Controllable : Controllable of the group.

  • #string From : From state.

  • #string Event : Event.

  • #string To : To state.

  • Core.Point#COORDINATE ToCoord : Coordinate to which the ARTY group should move.

  • #number Speed : Speed in km/h at which the grou p should move.

  • #boolean OnRoad : If true group should move on road mainly.

ARTY:onafterNewMove(Controllable, From, Event, To, move)

After "NewMove" event.

Parameters

  • Wrapper.Controllable#CONTROLLABLE Controllable : Controllable of the group.

  • #string From : From state.

  • #string Event : Event.

  • #string To : To state.

  • #table move : Array holding the move parameters.

Return value

#boolean: If true, proceed to onafterOpenfire.

ARTY:onafterNewTarget(Controllable, From, Event, To, target)

After "NewTarget" event.

Parameters

  • Wrapper.Controllable#CONTROLLABLE Controllable : Controllable of the group.

  • #string From : From state.

  • #string Event : Event.

  • #string To : To state.

  • #table target : Array holding the target parameters.

Return value

#boolean: If true, proceed to onafterOpenfire.

ARTY:onafterOpenFire(Controllable, From, Event, To, target)

After "OpenFire" event.

Sets the current target and starts the fire at point task.

Parameters

  • Wrapper.Controllable#CONTROLLABLE Controllable : Controllable of the group.

  • #string From : From state.

  • #string Event : Event.

  • #string To : To state.

  • #table target : Array holding the target info.

ARTY:onafterRearm(Controllable, From, Event, To)

After "Rearm" event.

Send message if reporting is on. Route rearming unit to ARTY group.

Parameters

ARTY:onafterRearmed(Controllable, From, Event, To)

After "Rearmed" event.

Send ARTY and rearming group back to their inital positions.

Parameters

ARTY:onafterStart(Controllable, From, Event, To)

After "Start" event.

Initialized ROE and alarm state. Starts the event handler.

Parameters

ARTY:onafterStatus(Controllable, From, Event, To)

After "Status" event.

Report status of group.

Parameters

ARTY:onafterStop(Controllable, From, Event, To)

After "Stop" event.

Unhandle events and cease fire on current target.

Parameters

ARTY:onafterWinchester(Controllable, From, Event, To)

After "Winchester" event.

Group is out of ammo. Trigger "Rearm" event.

Parameters

ARTY:onbeforeMove(Controllable, From, Event, To, ToCoord, OnRoad)

Before "Move" event.

Check if a unit to rearm the ARTY group has been defined.

Parameters

  • Wrapper.Controllable#CONTROLLABLE Controllable : Controllable of the group.

  • #string From : From state.

  • #string Event : Event.

  • #string To : To state.

  • Wrapper.Point#COORDINATE ToCoord : Coordinate to which the ARTY group should move.

  • #boolean OnRoad : If true group should move on road mainly.

Return value

#boolean: If true, proceed to onafterMove.

ARTY:onbeforeOpenFire(Controllable, From, Event, To, target)

Before "OpenFire" event.

Checks if group already has a target. Checks for valid min/max range and removes the target if necessary.

Parameters

  • Wrapper.Controllable#CONTROLLABLE Controllable : Controllable of the group.

  • #string From : From state.

  • #string Event : Event.

  • #string To : To state.

  • #table target : Array holding the target info.

Return value

#boolean: If true, proceed to onafterOpenfire.

ARTY:onbeforeRearm(Controllable, From, Event, To)

Before "Rearm" event.

Check if a unit to rearm the ARTY group has been defined.

Parameters

Return value

#boolean: If true, proceed to onafterRearm.

ARTY:onenterCombatReady(Controllable, From, Event, To)

Enter "CombatReady" state.

Route the group back if necessary.

Parameters

#boolean ARTY.report

Arty group sends messages about their current state or target to its coaliton.

#table ARTY.targets

All targets assigned.

#string ARTY.version

Arty script version.