A dynamic cargo handling capability for AI groups.

Carrier equipment can be mobilized to intelligently transport infantry and other cargo within the simulation. The AI_CARGO_DISPATCHER module uses the Cargo.Cargo capabilities within the MOOSE framework, to enable Carrier GROUP objects to transport Cargo.Cargo towards several deploy zones. Cargo.Cargo must be declared within the mission to make the AI_CARGO_DISPATCHER object recognize the cargo. Please consult the Cargo.Cargo module for more information.

1) AI_CARGO_DISPATCHER constructor.

• AI_CARGO_DISPATCHER.New(): Creates a new AI_CARGO_DISPATCHER object.

Find below some examples of AI cargo dispatcher objects created.

An AI dispatcher object for a helicopter squadron, moving infantry from pickup zones to deploy zones.

   local SetCargoInfantry = SET_CARGO:New():FilterTypes( "Infantry" ):FilterStart()
   local SetHelicopter = SET_GROUP:New():FilterPrefixes( "Helicopter" ):FilterStart()
   local SetPickupZones = SET_ZONE:New():FilterPrefixes( "Pickup" ):FilterStart()
   local SetDeployZones = SET_ZONE:New():FilterPrefixes( "Deploy" ):FilterStart()

   AICargoDispatcherHelicopter = AI_CARGO_DISPATCHER_HELICOPTER:New( SetHelicopter, SetCargoInfantry, SetPickupZones, SetDeployZones ) 
   AICargoDispatcherHelicopter:SetHomeZone( ZONE:FindByName( "Home" ) )

An AI dispatcher object for a vehicle squadron, moving infantry from pickup zones to deploy zones.

   local SetCargoInfantry = SET_CARGO:New():FilterTypes( "Infantry" ):FilterStart()
   local SetAPC = SET_GROUP:New():FilterPrefixes( "APC" ):FilterStart()
   local SetDeployZones = SET_ZONE:New():FilterPrefixes( "Deploy" ):FilterStart()

   AICargoDispatcherAPC = AI_CARGO_DISPATCHER_APC:New( SetAPC, SetCargoInfantry, nil, SetDeployZones ) 
   AICargoDispatcherAPC:Start()

An AI dispatcher object for an airplane squadron, moving infantry and vehicles from pickup airbases to deploy airbases.

   local CargoInfantrySet = SET_CARGO:New():FilterTypes( "Infantry" ):FilterStart()
   local AirplanesSet = SET_GROUP:New():FilterPrefixes( "Airplane" ):FilterStart()
   local PickupZoneSet = SET_ZONE:New()
   local DeployZoneSet = SET_ZONE:New()

   PickupZoneSet:AddZone( ZONE_AIRBASE:New( AIRBASE.Caucasus.Gudauta ) )
   DeployZoneSet:AddZone( ZONE_AIRBASE:New( AIRBASE.Caucasus.Sochi_Adler ) )
   DeployZoneSet:AddZone( ZONE_AIRBASE:New( AIRBASE.Caucasus.Maykop_Khanskaya ) )
   DeployZoneSet:AddZone( ZONE_AIRBASE:New( AIRBASE.Caucasus.Mineralnye_Vody ) )
   DeployZoneSet:AddZone( ZONE_AIRBASE:New( AIRBASE.Caucasus.Vaziani ) )

   AICargoDispatcherAirplanes = AI_CARGO_DISPATCHER_AIRPLANE:New( AirplanesSet, CargoInfantrySet, PickupZoneSet, DeployZoneSet ) 
   AICargoDispatcherAirplanes:SetHomeZone( ZONE_AIRBASE:New( AIRBASE.Caucasus.Kobuleti ) )

2) AI_CARGO_DISPATCHER is a Finite State Machine.

This section must be read as follows. Each of the rows indicate a state transition, triggered through an event, and with an ending state of the event was executed. The first column is the From state, the second column the Event, and the third column the To state.

So, each of the rows have the following structure.

• From => Event => To

Important to know is that an event can only be executed if the current state is the From state. This, when an Event that is being triggered has a From state that is equal to the Current state of the state machine, the event will be executed, and the resulting state will be the To state.

These are the different possible state transitions of this state machine implementation:

• Idle => Start => Monitoring

• Monitoring => Monitor => Monitoring

• Monitoring => Stop => Idle

• Monitoring => Pickup => Monitoring

• Monitoring => Load => Monitoring

• Monitoring => Loading => Monitoring

• Monitoring => Loaded => Monitoring

• Monitoring => PickedUp => Monitoring

• Monitoring => Deploy => Monitoring

• Monitoring => Unload => Monitoring

• Monitoring => Unloaded => Monitoring

• Monitoring => Deployed => Monitoring

• Monitoring => Home => Monitoring

2.1) AI_CARGO_DISPATCHER States.

• Monitoring: The process is dispatching.
• Idle: The process is idle.

2.2) AI_CARGO_DISPATCHER Events.

• Start: Start the transport process.

• Stop: Stop the transport process.

• Monitor: Monitor and take action.

• Pickup: Pickup cargo.

• Load: Load the cargo.

• Loading: The dispatcher is coordinating the loading of a cargo.

• Loaded: Flag that the cargo is loaded.

• PickedUp: The dispatcher has loaded all requested cargo into the CarrierGroup.

• Deploy: Deploy cargo to a location.

• Unload: Unload the cargo.

• Unloaded: Flag that the cargo is unloaded.

• Deployed: All cargo is unloaded from the carriers in the group.

• Home: A Carrier is going home.

3) Enhance your mission scripts with Tailored Event Handling!

Use these methods to capture the events and tailor the events with your own code! All classes derived from AI_CARGO_DISPATCHER can capture these events, and you can write your own code.

In order to properly capture the events, it is mandatory that you execute the following actions using your script:

• Copy / Paste the code section into your script.
• Change the CLASS literal to the 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!

Mission AID-CGO-140, AID-CGO-240 and AID-CGO-340 contain examples how these events can be tailored.

For those who don't have the time to check the test missions, find the underlying example of a Deployed event that is tailored.

 --- Deployed Handler OnAfter for AI_CARGO_DISPATCHER.
 -- Use this event handler to tailor the event when a carrier has deployed all cargo objects from the CarrierGroup.
 -- You can use this event handler to post messages to players, or provide status updates etc.
 -- @function OnAfterDeployed
 -- @param #AICargoDispatcherHelicopter self
 -- @param #string From A string that contains the "*from state name*" when the event was fired.
 -- @param #string Event A string that contains the "*event name*" when the event was fired.
 -- @param #string To A string that contains the "*to state name*" when the event was fired.
 -- @param Wrapper.Group#GROUP CarrierGroup The group object that contains the CarrierUnits.
 -- @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 AICargoDispatcherHelicopter:OnAfterDeployed( From, Event, To, CarrierGroup, DeployZone )

   MESSAGE:NewType( "Group " .. CarrierGroup:GetName() .. " deployed all cargo in zone " .. DeployZone:GetName(), MESSAGE.Type.Information ):ToAll()

 end 

3.1) Tailor the Pickup event

Use this event handler to tailor the event when a CarrierGroup is routed towards a new pickup Coordinate and a specified Speed. You can use this event handler to post messages to players, or provide status updates etc.

 --- Pickup event handler OnAfter for CLASS.
 -- Use this event handler to tailor the event when a CarrierGroup is routed towards a new pickup Coordinate and a specified Speed.
 -- You can use this event handler to post messages to players, or provide status updates etc.
 -- @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 Wrapper.Group#GROUP CarrierGroup The group object that contains the CarrierUnits.
 -- @param Core.Point#COORDINATE Coordinate The coordinate of the pickup location.
 -- @param #number Speed The velocity in meters per second on which the CarrierGroup is routed towards the pickup Coordinate.
 -- @param #number Height Height in meters to move to the pickup coordinate.
 -- @param Core.Zone#ZONE_AIRBASE PickupZone (optional) The zone from where the cargo is picked up. Note that the zone is optional and may not be provided, but for AI_CARGO_DISPATCHER_AIRBASE there will always be a PickupZone, as the pickup location is an airbase zone.
 function CLASS:OnAfterPickup( From, Event, To, CarrierGroup, Coordinate, Speed, Height, PickupZone )

   -- Write here your own code.

 end

3.2) Tailor the Load event

Use this event handler to tailor the event when a CarrierGroup has initiated the loading or boarding of cargo within reporting or near range. You can use this event handler to post messages to players, or provide status updates etc.

 --- Load event handler OnAfter for CLASS.
 -- Use this event handler to tailor the event when a CarrierGroup has initiated the loading or boarding of cargo within reporting or near range.
 -- You can use this event handler to post messages to players, or provide status updates etc.
 -- @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 Wrapper.Group#GROUP CarrierGroup The group object that contains the CarrierUnits.
 -- @param Core.Zone#ZONE_AIRBASE PickupZone (optional) The zone from where the cargo is picked up. Note that the zone is optional and may not be provided, but for AI_CARGO_DISPATCHER_AIRBASE there will always be a PickupZone, as the pickup location is an airbase zone.
 function CLASS:OnAfterLoad( From, Event, To, CarrierGroup, PickupZone )

   -- Write here your own code.

 end

3.3) Tailor the Loading event

Use this event handler to tailor the event when a CarrierUnit of a CarrierGroup is in the process of loading or boarding of a cargo object. You can use this event handler to post messages to players, or provide status updates etc.

 --- Loading event handler OnAfter for CLASS.
 -- Use this event handler to tailor the event when a CarrierUnit of a CarrierGroup is in the process of loading or boarding of a cargo object.
 -- You can use this event handler to post messages to players, or provide status updates etc.
 -- Note that this event is triggered repeatedly until all cargo (units) have been boarded into the carrier.
 -- @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 Wrapper.Group#GROUP CarrierGroup The group object that contains the CarrierUnits.
 -- @param Cargo.Cargo#CARGO Cargo The cargo object.
 -- @param Wrapper.Unit#UNIT CarrierUnit The carrier unit that is executing the cargo loading operation.
 -- @param Core.Zone#ZONE_AIRBASE PickupZone (optional) The zone from where the cargo is picked up. Note that the zone is optional and may not be provided, but for AI_CARGO_DISPATCHER_AIRBASE there will always be a PickupZone, as the pickup location is an airbase zone.
 function CLASS:OnAfterLoading( From, Event, To, CarrierGroup, Cargo, CarrierUnit, PickupZone )

   -- Write here your own code.

 end

3.4) Tailor the Loaded event

Use this event handler to tailor the event when a CarrierUnit of a CarrierGroup has loaded a cargo object. You can use this event handler to post messages to players, or provide status updates etc. Note that if more cargo objects were loading or boarding into the CarrierUnit, then this event can be triggered multiple times for each different Cargo/CarrierUnit.

The function provides the CarrierGroup, which is the main group that was loading the Cargo into the CarrierUnit. A CarrierUnit is part of the larger CarrierGroup.

 --- Loaded event handler OnAfter for CLASS.
 -- Use this event handler to tailor the event when a CarrierUnit of a CarrierGroup has loaded a cargo object.
 -- You can use this event handler to post messages to players, or provide status updates etc.
 -- Note that if more cargo objects were loading or boarding into the CarrierUnit, then this event can be triggered multiple times for each different Cargo/CarrierUnit.
 -- A CarrierUnit can be part of the larger CarrierGroup.
 -- @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 Wrapper.Group#GROUP CarrierGroup The group object that contains the CarrierUnits.
 -- @param Cargo.Cargo#CARGO Cargo The cargo object.
 -- @param Wrapper.Unit#UNIT CarrierUnit The carrier unit that is executing the cargo loading operation.
 -- @param Core.Zone#ZONE_AIRBASE PickupZone (optional) The zone from where the cargo is picked up. Note that the zone is optional and may not be provided, but for AI_CARGO_DISPATCHER_AIRBASE there will always be a PickupZone, as the pickup location is an airbase zone.
 function CLASS:OnAfterLoaded( From, Event, To, CarrierGroup, Cargo, CarrierUnit, PickupZone )

   -- Write here your own code.

 end

3.5) Tailor the PickedUp event

Use this event handler to tailor the event when a carrier has picked up all cargo objects into the CarrierGroup. You can use this event handler to post messages to players, or provide status updates etc.

 --- PickedUp event handler OnAfter for CLASS.
 -- Use this event handler to tailor the event when a carrier has picked up all cargo objects into the CarrierGroup.
 -- You can use this event handler to post messages to players, or provide status updates etc.
 -- @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 Wrapper.Group#GROUP CarrierGroup The group object that contains the CarrierUnits.
 -- @param Core.Zone#ZONE_AIRBASE PickupZone (optional) The zone from where the cargo is picked up. Note that the zone is optional and may not be provided, but for AI_CARGO_DISPATCHER_AIRBASE there will always be a PickupZone, as the pickup location is an airbase zone.
 function CLASS:OnAfterPickedUp( From, Event, To, CarrierGroup, PickupZone )

   -- Write here your own code.

 end

3.6) Tailor the Deploy event

Use this event handler to tailor the event when a CarrierGroup is routed to a deploy coordinate, to Unload all cargo objects in each CarrierUnit. You can use this event handler to post messages to players, or provide status updates etc.

 --- Deploy event handler OnAfter for CLASS.
 -- Use this event handler to tailor the event when a CarrierGroup is routed to a deploy coordinate, to Unload all cargo objects in each CarrierUnit.
 -- You can use this event handler to post messages to players, or provide status updates etc.
 -- @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 Wrapper.Group#GROUP CarrierGroup The group object that contains the CarrierUnits.
 -- @param Core.Point#COORDINATE Coordinate The deploy coordinate.
 -- @param #number Speed The velocity in meters per second on which the CarrierGroup is routed towards the deploy Coordinate.
 -- @param #number Height Height in meters to move to the deploy coordinate.
 -- @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:OnAfterDeploy( From, Event, To, CarrierGroup, Coordinate, Speed, Height, DeployZone )

   -- Write here your own code.

 end

3.7) Tailor the Unload event

Use this event handler to tailor the event when a CarrierGroup has initiated the unloading or unboarding of cargo. You can use this event handler to post messages to players, or provide status updates etc.

 --- Unload event handler OnAfter for CLASS.
 -- Use this event handler to tailor the event when a CarrierGroup has initiated the unloading or unboarding of cargo.
 -- You can use this event handler to post messages to players, or provide status updates etc.
 -- @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 Wrapper.Group#GROUP CarrierGroup The group object that contains the CarrierUnits.
 -- @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:OnAfterUnload( From, Event, To, CarrierGroup, DeployZone )

   -- Write here your own code.

 end

3.8) Tailor the Unloading event

 --- UnLoading event handler OnAfter for CLASS.
 -- Use this event handler to tailor the event when a CarrierUnit of a CarrierGroup is in the process of unloading or unboarding of a cargo object.
 -- You can use this event handler to post messages to players, or provide status updates etc.
 -- Note that this event is triggered repeatedly until all cargo (units) have been unboarded from the CarrierUnit.
 -- @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 Wrapper.Group#GROUP CarrierGroup The group object that contains the CarrierUnits.
 -- @param Cargo.Cargo#CARGO Cargo The cargo object.
 -- @param Wrapper.Unit#UNIT CarrierUnit The carrier unit that is executing the cargo unloading operation.
 -- @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:OnAfterUnload( From, Event, To, CarrierGroup, Cargo, CarrierUnit, DeployZone )

   -- Write here your own code.

 end

3.9) Tailor the Unloaded event

Use this event handler to tailor the event when a CarrierUnit of a CarrierGroup has unloaded a cargo object. You can use this event handler to post messages to players, or provide status updates etc.

 --- Unloaded event handler OnAfter for CLASS.
 -- Use this event handler to tailor the event when a CarrierUnit of a CarrierGroup has unloaded a cargo object.
 -- You can use this event handler to post messages to players, or provide status updates etc.
 -- Note that if more cargo objects were unloading or unboarding from the CarrierUnit, then this event can be triggered multiple times for each different Cargo/CarrierUnit.
 -- A CarrierUnit can be part of the larger CarrierGroup.
 -- @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 Wrapper.Group#GROUP CarrierGroup The group object that contains the CarrierUnits.
 -- @param Cargo.Cargo#CARGO Cargo The cargo object.
 -- @param Wrapper.Unit#UNIT CarrierUnit The carrier unit that is executing the cargo unloading operation.
 -- @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:OnAfterUnloaded( From, Event, To, CarrierGroup, Cargo, CarrierUnit, DeployZone )

   -- Write here your own code.

 end

3.10) Tailor the Deployed event

Use this event handler to tailor the event when a carrier has deployed all cargo objects from the CarrierGroup. You can use this event handler to post messages to players, or provide status updates etc.

 --- Deployed event handler OnAfter for CLASS.
 -- Use this event handler to tailor the event when a carrier has deployed all cargo objects from the CarrierGroup.
 -- You can use this event handler to post messages to players, or provide status updates etc.
 -- @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 Wrapper.Group#GROUP CarrierGroup The group object that contains the CarrierUnits.
 -- @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:OnAfterDeployed( From, Event, To, CarrierGroup, DeployZone )

   -- Write here your own code.

 end

3.11) Tailor the Home event

Use this event handler to tailor the event when a CarrierGroup is returning to the HomeZone, after it has deployed all cargo objects from the CarrierGroup. You can use this event handler to post messages to players, or provide status updates etc.

 --- Home event handler OnAfter for CLASS.
 -- Use this event handler to tailor the event when a CarrierGroup is returning to the HomeZone, after it has deployed all cargo objects from the CarrierGroup.
 -- You can use this event handler to post messages to players, or provide status updates etc.
 -- If there is no HomeZone is specified, the CarrierGroup will stay at the current location after having deployed all cargo and this event won't be triggered.
 -- @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 Wrapper.Group#GROUP CarrierGroup The group object that contains the CarrierUnits.
 -- @param Core.Point#COORDINATE Coordinate The home coordinate the Carrier will arrive and stop it's activities.
 -- @param #number Speed The velocity in meters per second on which the CarrierGroup is routed towards the home Coordinate.
 -- @param #number Height Height in meters to move to the home coordinate.
 -- @param Core.Zone#ZONE HomeZone The zone wherein the carrier will return when all cargo has been transported. This can be any zone type, like a ZONE, ZONE_GROUP, ZONE_AIRBASE.
 function CLASS:OnAfterHome( From, Event, To, CarrierGroup, Coordinate, Speed, Height, HomeZone )

   -- Write here your own code.

 end      

4) Set the pickup parameters.

Several parameters can be set to pickup cargo:

• AI_CARGO_DISPATCHER.SetPickupRadius(): Sets or randomizes the pickup location for the carrier around the cargo coordinate in a radius defined an outer and optional inner radius.
• AI_CARGO_DISPATCHER.SetPickupSpeed(): Set the speed or randomizes the speed in km/h to pickup the cargo.
• AI_CARGO_DISPATCHER.SetPickupHeight(): Set the height or randomizes the height in meters to pickup the cargo.

5) Set the deploy parameters.

Several parameters can be set to deploy cargo:

• AI_CARGO_DISPATCHER.SetDeployRadius(): Sets or randomizes the deploy location for the carrier around the cargo coordinate in a radius defined an outer and an optional inner radius.
• AI_CARGO_DISPATCHER.SetDeploySpeed(): Set the speed or randomizes the speed in km/h to deploy the cargo.
• AI_CARGO_DISPATCHER.SetDeployHeight(): Set the height or randomizes the height in meters to deploy the cargo.

6) Set the home zone when there isn't any more cargo to pickup.

A home zone can be specified to where the Carriers will move when there isn't any cargo left for pickup. Use AI_CARGO_DISPATCHER.SetHomeZone() to specify the home zone.

If no home zone is specified, the carriers will wait near the deploy zone for a new pickup command.