Implements the dynamic dispatching of cargo tasks.

The TASK_CARGO_DISPATCHER allows you to setup various tasks for let human players transport cargo as part of a task.

There are currently two types of tasks that can be constructed:

• A normal cargo transport task, which tasks humans to transport cargo from a location towards a deploy zone.
• A CSAR cargo transport task. CSAR tasks are automatically generated when a friendly (AI) plane is downed and the friendly pilot ejects... You as a player (the helo pilot) can go out in the battlefield, fly behind enemy lines, and rescue the pilot (back to a deploy zone).

Let's explore step by step how to setup the task cargo dispatcher.

1. Setup a mission environment.

It is easy, as it works just like any other task setup, so setup a command center and a mission.

1.1. Create a command center.

First you need to create a command center using the Tasking.CommandCenter#COMMANDCENTER.New() constructor.

local CommandCenter = COMMANDCENTER
   :New( HQ, "Lima" ) -- Create the CommandCenter.

1.2. Create a mission.

Tasks work in a mission, which groups these tasks to achieve a joint mission goal. A command center can govern multiple missions. Create a new mission, using the Tasking.Mission#MISSION.New() constructor.

-- Declare the Mission for the Command Center.
local Mission = MISSION
  :New( CommandCenter, 
        "Overlord", 
        "High", 
        "Transport the cargo.", 
        coalition.side.RED 
      ) 

2. Dispatch a transport cargo task.

So, now that we have a command center and a mission, we now create the transport task. We create the transport task using the TASK_CARGO_DISPATCHER.AddTransportTask() constructor.

2.1. Create the cargo in the mission.

Because a transport task will not generate the cargo itself, you'll need to create it first.

-- Here we define the "cargo set", which is a collection of cargo objects.
-- The cargo set will be the input for the cargo transportation task.
-- So a transportation object is handling a cargo set, which is automatically updated when new cargo is added/deleted.
local WorkmaterialsCargoSet = SET_CARGO:New():FilterTypes( "Workmaterials" ):FilterStart()

-- Now we add cargo into the battle scene.
local PilotGroup = GROUP:FindByName( "Engineers" )

-- CARGO_GROUP can be used to setup cargo with a GROUP object underneath.
-- We name the type of this group "Workmaterials", so that this cargo group will be included within the WorkmaterialsCargoSet.
-- Note that the name of the cargo is "Engineer Team 1".
local CargoGroup = CARGO_GROUP:New( PilotGroup, "Workmaterials", "Engineer Team 1", 500 )

What is also needed, is to have a set of Wrapper.Groups defined that contains the clients of the players.

-- Allocate the Transport, which are the helicopters to retrieve the pilot, that can be manned by players.
-- The name of these helicopter groups containing one client begins with "Transport", as modelled within the mission editor.
local PilotGroupSet = SET_GROUP:New():FilterPrefixes( "Transport" ):FilterStart()

2.2. Setup the cargo transport task.

First, we need to create a TASK_CARGO_DISPATCHER object.

TaskDispatcher = TASK_CARGO_DISPATCHER:New( Mission, PilotGroupSet )

So, the variable TaskDispatcher will contain the object of class TASK_CARGO_DISPATCHER, which will allow you to dispatch cargo transport tasks:

• for mission Mission.
• for the group set PilotGroupSet.

Now that we have TaskDispatcher object, we can now create the TransportTask, using the TASK_CARGO_DISPATCHER.AddTransportTask() method!

local TransportTask = TaskDispatcher:AddTransportTask( 
  "Transport workmaterials", 
  WorkmaterialsCargoSet, 
  "Transport the workers, engineers and the equipment near the Workplace." )

As a result of this code, the TransportTask (returned) variable will contain an object of #TASK_CARGO_TRANSPORT! We pass to the method the title of the task, and the WorkmaterialsCargoSet, which is the set of cargo groups to be transported! This object can also be used to setup additional things, or to control this specific task with special actions.

And you're done! As you can see, it is a bit of work, but the reward is great. And, because all this is done using program interfaces, you can build a mission with a dynamic cargo transport task mechanism yourself! Based on events happening within your mission, you can use the above methods to create new cargo, and setup a new task for cargo transportation to a group of players!

3. Dispatch CSAR tasks.

CSAR tasks can be dynamically created when a friendly pilot ejects, or can be created manually. We'll explore both options.

3.1. CSAR task dynamic creation.

Because there is an "event" in a running simulation that creates CSAR tasks, the method TASK_CARGO_DISPATCHER.StartCSARTasks() will create automatically:

1. a new downed pilot at the location where the plane was shot
2. declare that pilot as cargo
3. creates a CSAR task automatically to retrieve that pilot
4. requires deploy zones to be specified where to transport the downed pilot to, in order to complete that task.

You create a CSAR task dynamically in a very easy way:

TaskDispatcher:StartCSARTasks( 
  "CSAR", 
  { ZONE_UNIT:New( "Hospital", STATIC:FindByName( "Hospital" ), 100 ) }, 
  "One of our pilots has ejected. Go out to Search and Rescue our pilot!\n" .. 
  "Use the radio menu to let the command center assist you with the CSAR tasking."
)

The method TASK_CARGO_DISPATCHER.StopCSARTasks() will automatically stop with the creation of CSAR tasks when friendly pilots eject.

Remarks:

• the ZONE_UNIT can also be a ZONE, or a ZONE_POLYGON object, or any other ZONE_ object!
• you can declare the array of zones in another variable, or course!

3.2. CSAR task manual creation.

We create the CSAR task using the TASK_CARGO_DISPATCHER.AddCSARTask() constructor.

The method will create a new CSAR task, and will generate the pilots cargo itself, at the specified coordinate.

What is first needed, is to have a set of Wrapper.Groups defined that contains the clients of the players.

-- Allocate the Transport, which are the helicopter to retrieve the pilot, that can be manned by players.
local GroupSet = SET_GROUP:New():FilterPrefixes( "Transport" ):FilterStart()

We need to create a TASK_CARGO_DISPATCHER object.

TaskDispatcher = TASK_CARGO_DISPATCHER:New( Mission, GroupSet )

So, the variable TaskDispatcher will contain the object of class TASK_CARGO_DISPATCHER, which will allow you to dispatch cargo CSAR tasks:

• for mission Mission.
• for the group of players (pilots) captured within the GroupSet (those groups with a name starting with "Transport").

Now that we have a PilotsCargoSet and a GroupSet, we can now create the CSAR task manually.

-- Declare the CSAR task.
local CSARTask = TaskDispatcher:AddCSARTask( 
  "CSAR Task",
  Coordinate,
  270,
  "Bring the pilot back!"
)

As a result of this code, the CSARTask (returned) variable will contain an object of #TASK_CARGO_CSAR! We pass to the method the title of the task, and the WorkmaterialsCargoSet, which is the set of cargo groups to be transported! This object can also be used to setup additional things, or to control this specific task with special actions. Note that when you declare a CSAR task manually, you'll still need to specify a deployment zone!

4. Setup the deploy zone(s).

The task cargo dispatcher also foresees methods to setup the deployment zones to where the cargo needs to be transported!

There are two levels on which deployment zones can be configured:

• Default deploy zones: The TASK_CARGO_DISPATCHER object can have default deployment zones, which will apply over all tasks active in the task dispatcher.
• Task specific deploy zones: The TASK_CARGO_DISPATCHER object can have specific deployment zones which apply to a specific task only!

Note that for Task specific deployment zones, there are separate deployment zone creation methods per task type!

4.1. Setup default deploy zones.

Use the TASK_CARGO_DISPATCHER.SetDefaultDeployZone() to setup one deployment zone, and TASK_CARGO_DISPATCHER.SetDefaultDeployZones() to setup multiple default deployment zones in one call.

4.2. Setup task specific deploy zones for a transport task.

Use the TASK_CARGO_DISPATCHER.SetTransportDeployZone() to setup one deployment zone, and TASK_CARGO_DISPATCHER.SetTransportDeployZones() to setup multiple default deployment zones in one call.

4.3. Setup task specific deploy zones for a CSAR task.

Use the TASK_CARGO_DISPATCHER.SetCSARDeployZone() to setup one deployment zone, and TASK_CARGO_DISPATCHER.SetCSARDeployZones() to setup multiple default deployment zones in one call.

4.4. CSAR ejection zones.

Setup a set of zones where the pilots will only eject and a task is created for CSAR. When such a set of zones is given, any ejection outside those zones will not result in a pilot created for CSAR!

Use the TASK_CARGO_DISPATCHER.SetCSARZones() to setup the set of zones.

4.5. CSAR ejection maximum.

Setup how many pilots will eject the maximum. This to avoid an overload of CSAR tasks being created :-) The default is endless CSAR tasks.

Use the TASK_CARGO_DISPATCHER.SetMaxCSAR() to setup the maximum of pilots that will eject for CSAR.

5) Handle cargo task events.

When a player is picking up and deploying cargo using his carrier, events are generated by the dispatcher. These events can be captured and tailored with your own code.

In order to properly capture the events and avoid mistakes using the documentation, it is advised that you execute the following actions:

• Copy / Paste the code section into your script.
• Change the CLASS literal to the task object name you have in your script.
• Within the function, you can now write your own code!
• IntelliSense will recognize the type of the variables provided by the function. Note: the From, Event and To variables can be safely ignored, but you need to declare them as they are automatically provided by the event handling system of MOOSE.

You can send messages or fire off any other events within the code section. The sky is the limit!

First, we need to create a TASK_CARGO_DISPATCHER object.

 TaskDispatcher = TASK_CARGO_DISPATCHER:New( Mission, PilotGroupSet )

Second, we create a new cargo transport task for the transportation of workmaterials.

 TaskDispatcher:AddTransportTask( 
   "Transport workmaterials", 
   WorkmaterialsCargoSet, 
   "Transport the workers, engineers and the equipment near the Workplace." )

Note that we don't really need to keep the resulting task, it is kept internally also in the dispatcher.

Using the TaskDispatcher object, we can now cpature the CargoPickedUp and CargoDeployed events.

5.1) Handle the CargoPickedUp event.

Find below an example how to tailor the CargoPickedUp event, generated by the TaskDispatcher:

 function TaskDispatcher:OnAfterCargoPickedUp( From, Event, To, Task, TaskPrefix, TaskUnit, Cargo )

   MESSAGE:NewType( "Unit " .. TaskUnit:GetName().. " has picked up cargo for task " .. Task:GetName() .. ".", MESSAGE.Type.Information ):ToAll()

 end

If you want to code your own event handler, use this code fragment to tailor the event when a player carrier has picked up a cargo object in the CarrierGroup. You can use this event handler to post messages to players, or provide status updates etc.

 --- CargoPickedUp event handler OnAfter for CLASS.
 -- @param #CLASS self
 -- @param #string From A string that contains the "*from state name*" when the event was triggered.
 -- @param #string Event A string that contains the "*event name*" when the event was triggered.
 -- @param #string To A string that contains the "*to state name*" when the event was triggered.
 -- @param Tasking.Task_Cargo#TASK_CARGO Task The cargo task for which the cargo has been picked up. Note that this will be a derived TAKS_CARGO object!
 -- @param #string TaskPrefix The prefix of the task that was provided when the task was created.
 -- @param Wrapper.Unit#UNIT TaskUnit The unit (client) of the player that has picked up the cargo.
 -- @param Cargo.Cargo#CARGO Cargo The cargo object that has been picked up. Note that this can be a CARGO_GROUP, CARGO_CRATE or CARGO_SLINGLOAD object!
 function CLASS:OnAfterCargoPickedUp( From, Event, To, Task, TaskPrefix, TaskUnit, Cargo )

   -- Write here your own code.

 end

5.2) Handle the CargoDeployed event.

Find below an example how to tailor the CargoDeployed event, generated by the TaskDispatcher:

  function WorkplaceTask:OnAfterCargoDeployed( From, Event, To, Task, TaskPrefix, TaskUnit, Cargo, DeployZone )

    MESSAGE:NewType( "Unit " .. TaskUnit:GetName().. " has deployed cargo at zone " .. DeployZone:GetName() .. " for task " .. Task:GetName() .. ".", MESSAGE.Type.Information ):ToAll()

    Helos[ math.random(1,#Helos) ]:Spawn()
    EnemyHelos[ math.random(1,#EnemyHelos) ]:Spawn()
  end

If you want to code your own event handler, use this code fragment to tailor the event when a player carrier has deployed a cargo object from the CarrierGroup. You can use this event handler to post messages to players, or provide status updates etc.

 --- CargoDeployed event handler OnAfter for CLASS.
 -- @param #CLASS self
 -- @param #string From A string that contains the "*from state name*" when the event was triggered.
 -- @param #string Event A string that contains the "*event name*" when the event was triggered.
 -- @param #string To A string that contains the "*to state name*" when the event was triggered.
 -- @param Tasking.Task_Cargo#TASK_CARGO Task The cargo task for which the cargo has been deployed. Note that this will be a derived TAKS_CARGO object!
 -- @param #string TaskPrefix The prefix of the task that was provided when the task was created.
 -- @param Wrapper.Unit#UNIT TaskUnit The unit (client) of the player that has deployed the cargo.
 -- @param Cargo.Cargo#CARGO Cargo The cargo object that has been deployed. Note that this can be a CARGO_GROUP, CARGO_CRATE or CARGO_SLINGLOAD object!
 -- @param Core.Zone#ZONE DeployZone The zone wherein the cargo is deployed. This can be any zone type, like a ZONE, ZONE_GROUP, ZONE_AIRBASE.
 function CLASS:OnAfterCargoDeployed( From, Event, To, Task, TaskPrefix, TaskUnit, Cargo, DeployZone )

   -- Write here your own code.

 end