Module Task_Cargo_Dispatcher

Tasking - Creates and manages player TASK_CARGO tasks.


Author: FlightControl

Contributions:


Global(s)

TASK_CARGO_DISPATCHER

TASKCARGODISPATCHER class, extends Task_Manager#TASK_MANAGER

Banner Image

The #TASK_CARGO_DISPATCHER class implements the dynamic dispatching of cargo tasks.

Type TASK_CARGO_DISPATCHER

TASK_CARGO_DISPATCHER:AddCSARTask(CSARTaskPrefix, CSARCoordinate, CSARHeading, CSARCountry, CSARBriefing)

Add a CSAR task to retrieve a downed pilot.

TASK_CARGO_DISPATCHER:AddTransportTask(TaskName, SetCargo, Briefing)

Add a Transport task to transport cargo from fixed locations to a deployment zone.

TASK_CARGO_DISPATCHER.CSARBriefing
TASK_CARGO_DISPATCHER.CSARDeployZones
TASK_CARGO_DISPATCHER.CSARRadius
TASK_CARGO_DISPATCHER.CSARSpawned
TASK_CARGO_DISPATCHER.CSARTaskName
TASK_CARGO_DISPATCHER.CSARTasks
TASK_CARGO_DISPATCHER.DefaultDeployZones
TASK_CARGO_DISPATCHER:EvaluateCSAR(CSARUnit)

Evaluates of a CSAR task needs to be started.

TASK_CARGO_DISPATCHER:GetTransportTask(TaskName)

Add a Transport task to transport cargo from fixed locations to a deployment zone.

TASK_CARGO_DISPATCHER:ManageTasks()

Assigns tasks to the Core.Set#SET_GROUP.

TASK_CARGO_DISPATCHER.Mission
TASK_CARGO_DISPATCHER:New(Mission, SetGroup)

TASKCARGODISPATCHER constructor.

TASK_CARGO_DISPATCHER:OnAfterAssign(From, Event, To, Task, TaskUnit, PlayerName)

OnAfter Transition Handler for Event Assign.

TASK_CARGO_DISPATCHER:OnEventEjection(EventData)

Handle the event when a pilot ejects.

TASK_CARGO_DISPATCHER:SetCSARDeployZone(CSARTaskName, CSARDeployZone)

Define one deploy zone for the CSAR tasks.

TASK_CARGO_DISPATCHER:SetCSARDeployZones(CSARTaskName, CSARDeployZones)

Define the deploy zones for the CSAR tasks.

TASK_CARGO_DISPATCHER:SetCSARRadius(CSARRadius)

Define the radius to when a CSAR task will be generated for any downed pilot within range of the nearest CSAR airbase.

TASK_CARGO_DISPATCHER:SetDefaultDeployZone(DefaultDeployZone)

Define one default deploy zone for all the cargo tasks.

TASK_CARGO_DISPATCHER:SetDefaultDeployZones(DefaultDeployZones)

Define the deploy zones for all the cargo tasks.

TASK_CARGO_DISPATCHER:SetTransportDeployZone(TaskName, TransportDeployZone)

Define one deploy zone for the Transport tasks.

TASK_CARGO_DISPATCHER:SetTransportDeployZones(TaskName, TransportDeployZones)

Define the deploy zones for the Transport tasks.

TASK_CARGO_DISPATCHER:StartCSARTasks(CSARTaskName, CSARDeployZones, CSARBriefing)

Start the generation of CSAR tasks to retrieve a downed pilots.

TASK_CARGO_DISPATCHER:StopCSARTasks()

Stop the generation of CSAR tasks to retrieve a downed pilots.

TASK_CARGO_DISPATCHER.TASK_CARGO_DISPATCHER

CSAR CSAR

TASK_CARGO_DISPATCHER.TransportCount

Type TASK_CARGO_DISPATCHER.CSAR

TASK_CARGO_DISPATCHER.CSAR.PilotUnit
TASK_CARGO_DISPATCHER.CSAR.Task

Global(s)

#TASK_CARGO_DISPATCHER TASK_CARGO_DISPATCHER

TASKCARGODISPATCHER class, extends Task_Manager#TASK_MANAGER

Banner Image

The #TASK_CARGO_DISPATCHER class implements the dynamic dispatching of cargo tasks.

Banner Image

The EWR will detect units, will group them, and will dispatch Tasks to groups. Depending on the type of target detected, different tasks will be dispatched. Find a summary below describing for which situation a task type is created:

Banner Image

  • CSAR Task: Is created when a fiendly pilot has ejected from a plane, and needs to be rescued (sometimes behind enemy lines).

1. TASK_A2A_DISPATCHER constructor:

The TASK_CARGO_DISPATCHER.New() method creates a new TASK_A2A_DISPATCHER instance.

1.1. Define or set the Mission:

Tasking is executed to accomplish missions. Therefore, a MISSION object needs to be given as the first parameter.

local HQ = GROUP:FindByName( "HQ", "Bravo" )
local CommandCenter = COMMANDCENTER:New( HQ, "Lima" )
local Mission = MISSION:New( CommandCenter, "A2A Mission", "High", "Watch the air enemy units being detected.", coalition.side.RED )

Missions are governed by COMMANDCENTERS, so, ensure you have a COMMANDCENTER object installed and setup within your mission. Create the MISSION object, and hook it under the command center.

1.2. Build a set of the groups seated by human players:

Banner Image

A set or collection of the groups wherein human players can be seated, these can be clients or units that can be joined as a slot or jumping into.

local AttackGroups = SET_GROUP:New():FilterCoalitions( "red" ):FilterPrefixes( "Defender" ):FilterStart()

The set is built using the SET_GROUP class. Apply any filter criteria to identify the correct groups for your mission. Only these slots or units will be able to execute the mission and will receive tasks for this mission, once available.

1.3. Define the EWR network:

As part of the TASK_A2A_DISPATCHER constructor, an EWR network must be given as the third parameter. An EWR network, or, Early Warning Radar network, is used to early detect potential airborne targets and to understand the position of patrolling targets of the enemy.

Banner Image

Typically EWR networks are setup using 55G6 EWR, 1L13 EWR, Hawk sr and Patriot str ground based radar units. These radars have different ranges and 55G6 EWR and 1L13 EWR radars are Eastern Bloc units (eg Russia, Ukraine, Georgia) while the Hawk and Patriot radars are Western (eg US). Additionally, ANY other radar capable unit can be part of the EWR network! Also AWACS airborne units, planes, helicopters can help to detect targets, as long as they have radar. The position of these units is very important as they need to provide enough coverage to pick up enemy aircraft as they approach so that CAP and GCI flights can be tasked to intercept them.

Banner Image

Additionally in a hot war situation where the border is no longer respected the placement of radars has a big effect on how fast the war escalates. For example if they are a long way forward and can detect enemy planes on the ground and taking off they will start to vector CAP and GCI flights to attack them straight away which will immediately draw a response from the other coalition. Having the radars further back will mean a slower escalation because fewer targets will be detected and therefore less CAP and GCI flights will spawn and this will tend to make just the border area active rather than a melee over the whole map. It all depends on what the desired effect is.

EWR networks are dynamically constructed, that is, they form part of the Functional#DETECTION_BASE object that is given as the input parameter of the TASK_A2A_DISPATCHER class. By defining in a smart way the names or name prefixes of the groups with EWR capable units, these groups will be automatically added or deleted from the EWR network, increasing or decreasing the radar coverage of the Early Warning System.

See the following example to setup an EWR network containing EWR stations and AWACS.

local EWRSet = SET_GROUP:New():FilterPrefixes( "EWR" ):FilterCoalitions("red"):FilterStart()

local EWRDetection = DETECTION_AREAS:New( EWRSet, 6000 )
EWRDetection:SetFriendliesRange( 10000 )
EWRDetection:SetRefreshTimeInterval(30)

-- Setup the A2A dispatcher, and initialize it.
A2ADispatcher = TASK_CARGO_DISPATCHER:New( Mission, AttackGroups, EWRDetection )

The above example creates a SET_GROUP instance, and stores this in the variable (object) EWRSet. EWRSet is then being configured to filter all active groups with a group name starting with EWR to be included in the Set. EWRSet is then being ordered to start the dynamic filtering. Note that any destroy or new spawn of a group with the above names will be removed or added to the Set. Then a new EWRDetection object is created from the class DETECTION_AREAS. A grouping radius of 6000 is choosen, which is 6km. The EWRDetection object is then passed to the TASK_CARGO_DISPATCHER.New() method to indicate the EWR network configuration and setup the A2A tasking and detection mechanism.

2. Define the detected target grouping radius:

Banner Image

The target grouping radius is a property of the Detection object, that was passed to the AI_A2A_DISPATCHER object, but can be changed. The grouping radius should not be too small, but also depends on the types of planes and the era of the simulation. Fast planes like in the 80s, need a larger radius than WWII planes.
Typically I suggest to use 30000 for new generation planes and 10000 for older era aircraft.

Note that detected targets are constantly re-grouped, that is, when certain detected aircraft are moving further than the group radius, then these aircraft will become a separate group being detected. This may result in additional GCI being started by the dispatcher! So don't make this value too small!

3. Set the Engage radius:

Define the radius to engage any target by airborne friendlies, which are executing cap or returning from an intercept mission.

Banner Image

So, if there is a target area detected and reported, then any friendlies that are airborne near this target area, will be commanded to (re-)engage that target when available (if no other tasks were commanded). For example, if 100000 is given as a value, then any friendly that is airborne within 100km from the detected target, will be considered to receive the command to engage that target area. You need to evaluate the value of this parameter carefully. If too small, more intercept missions may be triggered upon detected target areas. If too large, any airborne cap may not be able to reach the detected target area in time, because it is too far.

4. Set Scoring and Messages:

The TASK_A2A_DISPATCHER is a state machine. It triggers the event Assign when a new player joins a Task dispatched by the TASK_A2A_DISPATCHER. An event handler can be defined to catch the Assign event, and add additional processing to set scoring and to define messages, when the player reaches certain achievements in the task.

The prototype to handle the Assign event needs to be developed as follows:

 TaskDispatcher = TASK_CARGO_DISPATCHER:New( ... )

 --- @param #TaskDispatcher self
 -- @param #string From Contains the name of the state from where the Event was triggered.
 -- @param #string Event Contains the name of the event that was triggered. In this case Assign.
 -- @param #string To Contains the name of the state that will be transitioned to.
 -- @param Tasking.Task_A2A#TASK_A2A Task The Task object, which is any derived object from TASK_A2A.
 -- @param Wrapper.Unit#UNIT TaskUnit The Unit or Client that contains the Player.
 -- @param #string PlayerName The name of the Player that joined the TaskUnit.
 function TaskDispatcher:OnAfterAssign( From, Event, To, Task, TaskUnit, PlayerName )
   Task:SetScoreOnProgress( PlayerName, 20, TaskUnit )
   Task:SetScoreOnSuccess( PlayerName, 200, TaskUnit )
   Task:SetScoreOnFail( PlayerName, -100, TaskUnit )
 end

The OnAfterAssign method (function) is added to the TaskDispatcher object. This method will be called when a new player joins a unit in the set of groups in scope of the dispatcher. So, this method will be called only ONCE when a player joins a unit in scope of the task.

The TASK class implements various methods to additional set scoring for player achievements:

  • Tasking.Task#TASK.SetScoreOnProgress() will add additional scores when a player achieves Progress while executing the task. Examples of task progress can be destroying units, arriving at zones etc.

  • Tasking.Task#TASK.SetScoreOnSuccess() will add additional scores when the task goes into Success state. This means the task has been successfully completed.

  • Tasking.Task#TASK.SetScoreOnSuccess() will add additional (negative) scores when the task goes into Failed state. This means the task has not been successfully completed, and the scores must be given with a negative value!

Type Task_Cargo_Dispatcher

Type TASK_CARGO_DISPATCHER

Extends Tasking.Task_Manager#TASK_MANAGER

TASKCARGODISPATCHER class.

Field(s)

TASK_CARGO_DISPATCHER:AddCSARTask(CSARTaskPrefix, CSARCoordinate, CSARHeading, CSARCountry, CSARBriefing)

Add a CSAR task to retrieve a downed pilot.

You need to specify a coordinate from where the pilot will be spawned to be rescued.

Parameters

  • #string CSARTaskPrefix : (optional) The prefix of the CSAR task.

  • Core.Point#COORDINATE CSARCoordinate : The coordinate where a downed pilot will be spawned.

  • #number CSARHeading : The heading of the pilot in degrees.

  • DCSCountry#Country CSARCountry : The country ID of the pilot that will be spawned.

  • #string CSARBriefing : The briefing of the CSAR task.

Return value

#string: The CSAR Task Name as a string. The Task Name is the main key and is shown in the task list of the Mission Tasking menu.

Usage:


  -- Add a CSAR task to rescue a downed pilot from within a coordinate.
  local Coordinate = PlaneUnit:GetPointVec2()
  TaskA2ADispatcher:AddCSARTask( Coordinate )
  
  -- Add a CSAR task to rescue a downed pilot from within a coordinate of country RUSSIA, which is pointing to the west (270°).
  local Coordinate = PlaneUnit:GetPointVec2()
  TaskA2ADispatcher:AddCSARTask( Coordinate, 270, Country.RUSSIA )
  
TASK_CARGO_DISPATCHER:AddTransportTask(TaskName, SetCargo, Briefing)

Add a Transport task to transport cargo from fixed locations to a deployment zone.

Parameters

  • #string TaskName : (optional) The name of the transport task.

  • Core.SetCargo#SET_CARGO SetCargo : The SetCargo to be transported.

  • #string Briefing : The briefing of the task transport to be shown to the player.

Return value

#TASK_CARGO_DISPATCHER:

Usage:


  -- Add a Transport task to transport cargo of different types to a Transport Deployment Zone.
TASK_CARGO_DISPATCHER.CSARBriefing
TASK_CARGO_DISPATCHER.CSARDeployZones
TASK_CARGO_DISPATCHER.CSARRadius
TASK_CARGO_DISPATCHER.CSARSpawned
TASK_CARGO_DISPATCHER.CSARTaskName
#boolean TASK_CARGO_DISPATCHER.CSARTasks
TASK_CARGO_DISPATCHER.DefaultDeployZones
TASK_CARGO_DISPATCHER:EvaluateCSAR(CSARUnit)

Evaluates of a CSAR task needs to be started.

Parameter

  • CSARUnit :

Return values

  1. Core.Set#SET_CARGO: The SetCargo to be rescued.

  2. #nil: If there is no CSAR task required.

TASK_CARGO_DISPATCHER:GetTransportTask(TaskName)

Add a Transport task to transport cargo from fixed locations to a deployment zone.

Parameter

  • #string TaskName : (optional) The name of the transport task.

Return value

Tasking.Task_Cargo_Transport#TASK_CARGO_TRANSPORT:

TASK_CARGO_DISPATCHER:ManageTasks()

Assigns tasks to the Core.Set#SET_GROUP.

Return value

#boolean: Return true if you want the task assigning to continue... false will cancel the loop.

TASK_CARGO_DISPATCHER.Mission
TASK_CARGO_DISPATCHER:New(Mission, SetGroup)

TASKCARGODISPATCHER constructor.

Parameters

Return value

#TASK_CARGO_DISPATCHER: self

TASK_CARGO_DISPATCHER:OnAfterAssign(From, Event, To, Task, TaskUnit, PlayerName)

OnAfter Transition Handler for Event Assign.

Parameters

TASK_CARGO_DISPATCHER:OnEventEjection(EventData)

Handle the event when a pilot ejects.

Parameter

TASK_CARGO_DISPATCHER:SetCSARDeployZone(CSARTaskName, CSARDeployZone)

Define one deploy zone for the CSAR tasks.

Parameters

  • #string CSARTaskName : (optional) The name of the CSAR task.

  • CSARDeployZone : A CSAR deploy zone.

Return value

#TASK_CARGO_DISPATCHER:

TASK_CARGO_DISPATCHER:SetCSARDeployZones(CSARTaskName, CSARDeployZones)

Define the deploy zones for the CSAR tasks.

Parameters

  • #string CSARTaskName : (optional) The name of the CSAR task.

  • CSARDeployZones : A list of the CSAR deploy zones.

Return value

#TASK_CARGO_DISPATCHER:

TASK_CARGO_DISPATCHER:SetCSARRadius(CSARRadius)

Define the radius to when a CSAR task will be generated for any downed pilot within range of the nearest CSAR airbase.

Parameter

  • #number CSARRadius : (Optional, Default = 50000) The radius in meters to decide whether a CSAR needs to be created.

Return value

#TASK_CARGO_DISPATCHER:

Usage:


  -- Set 20km as the radius to CSAR any downed pilot within range of the nearest CSAR airbase.
  TaskA2ADispatcher:SetEngageRadius( 20000 )
  
  -- Set 50km as the radius to to CSAR any downed pilot within range of the nearest CSAR airbase.
  TaskA2ADispatcher:SetEngageRadius() -- 50000 is the default value.
  
TASK_CARGO_DISPATCHER:SetDefaultDeployZone(DefaultDeployZone)

Define one default deploy zone for all the cargo tasks.

Parameter

  • DefaultDeployZone : A default deploy zone.

Return value

#TASK_CARGO_DISPATCHER:

TASK_CARGO_DISPATCHER:SetDefaultDeployZones(DefaultDeployZones)

Define the deploy zones for all the cargo tasks.

Parameter

  • DefaultDeployZones : A list of the deploy zones.

Return value

#TASK_CARGO_DISPATCHER:

TASK_CARGO_DISPATCHER:SetTransportDeployZone(TaskName, TransportDeployZone)

Define one deploy zone for the Transport tasks.

Parameters

  • #string TaskName : (optional) The name of the Transport task.

  • TransportDeployZone : A Transport deploy zone.

Return value

#TASK_CARGO_DISPATCHER:

TASK_CARGO_DISPATCHER:SetTransportDeployZones(TaskName, TransportDeployZones)

Define the deploy zones for the Transport tasks.

Parameters

  • #string TaskName : (optional) The name of the Transport task.

  • TransportDeployZones : A list of the Transport deploy zones.

Return value

#TASK_CARGO_DISPATCHER:

TASK_CARGO_DISPATCHER:StartCSARTasks(CSARTaskName, CSARDeployZones, CSARBriefing)

Start the generation of CSAR tasks to retrieve a downed pilots.

You need to specify a task briefing, a task name, default deployment zone(s). This method can only be used once!

Parameters

  • #string CSARTaskName : The CSAR task name.

  • #string CSARDeployZones : The zones to where the CSAR deployment should be directed.

  • #string CSARBriefing : The briefing of the CSAR tasks.

Return value

#TASK_CARGO_DISPATCHER:

TASK_CARGO_DISPATCHER:StopCSARTasks()

Stop the generation of CSAR tasks to retrieve a downed pilots.

Return value

#TASK_CARGO_DISPATCHER:

TASK_CARGO_DISPATCHER.TASK_CARGO_DISPATCHER

CSAR CSAR

TASK_CARGO_DISPATCHER.TransportCount

Type TASK_CARGO_DISPATCHER.CSAR

Field(s)

Wrapper.Unit#UNIT TASK_CARGO_DISPATCHER.CSAR.PilotUnit
Tasking.Task#TASK TASK_CARGO_DISPATCHER.CSAR.Task