Banner Image

Module AI.AI_Cargo_APC

AI - Models the intelligent transportation of cargo using ground vehicles.


Author: FlightControl


Global(s)

Global AI_CARGO_APC

Brings a dynamic cargo handling capability for an AI vehicle group.

#AI_CARGO_APC AI_CARGO_APC

Brings a dynamic cargo handling capability for an AI vehicle group.

Armoured Personnel Carriers (APC), Trucks, Jeeps and other ground based carrier equipment can be mobilized to intelligently transport infantry and other cargo within the simulation.

The AI_CARGO_APC class uses the Cargo.Cargo capabilities within the MOOSE framework. Cargo.Cargo must be declared within the mission to make the AI_CARGO_APC object recognize the cargo. Please consult the Cargo.Cargo module for more information.

Cargo loading.

The module will load automatically cargo when the APCs are within boarding or loading radius. The boarding or loading radius is specified when the cargo is created in the simulation, and therefore, this radius depends on the type of cargo and the specified boarding radius.

Defending the APCs when enemies nearby.

Cargo will defend the carrier with its available arms, and to avoid cargo being lost within the battlefield.

When the APCs are approaching enemy units, something special is happening. The APCs will stop moving, and the loaded infantry will unboard and follow the APCs and will help to defend the group. The carrier will hold the route once the unboarded infantry is further than 50 meters from the APCs, to ensure that the APCs are not too far away from the following running infantry. Once all enemies are cleared, the infantry will board again automatically into the APCs. Once boarded, the APCs will follow its pre-defined route.

A combat radius needs to be specified in meters at the AI_CARGO_APC.New() method. This combat radius will trigger the unboarding of troops when enemies are within the combat radius around the APCs. During my tests, I've noticed that there is a balance between ensuring that the infantry is within sufficient hit radius (effectiveness) versus vulnerability of the infantry. It all depends on the kind of enemies that are expected to be encountered. A combat radius of 350 meters to 500 meters has been proven to be the most effective and efficient.

However, when the defense of the carrier, is not required, it must be switched off. This is done by disabling the defense of the carrier using the method AI_CARGO_APC.SetCombatRadius(), and providing a combat radius of 0 meters. It can be switched on later when required by reenabling the defense using the method and providing a combat radius larger than 0.

Infantry or cargo health.

When infantry is unboarded from the APCs, the infantry is actually respawned into the battlefield. As a result, the unboarding infantry is very healthy every time it unboards. This is due to the limitation of the DCS simulator, which is not able to specify the health of new spawned units as a parameter. However, infantry that was destroyed when unboarded and following the APCs, won't be respawned again. Destroyed is destroyed. As a result, there is some additional strength that is gained when an unboarding action happens, but in terms of simulation balance this has marginal impact on the overall battlefield simulation. Fortunately, the firing strength of infantry is limited, and thus, respacing healthy infantry every time is not so much of an issue ...

Control the APCs on the map.

It is possible also as a human ground commander to influence the path of the APCs, by pointing a new path using the DCS user interface on the map. In this case, the APCs will change the direction towards its new indicated route. However, there is a catch! Once the APCs are near the enemy, and infantry is unboarded, the APCs won't be able to hold the route until the infantry could catch up. The APCs will simply drive on and won't stop! This is a limitation in ED that prevents user actions being controlled by the scripting engine. No workaround is possible on this.

Cargo deployment.

Using the AI_CARGO_APC.Deploy() method, you are able to direct the APCs towards a point on the battlefield to unboard/unload the cargo at the specific coordinate. The APCs will follow nearby roads as much as possible, to ensure fast and clean cargo transportation between the objects and villages in the simulation environment.

Cargo pickup.

Using the AI_CARGO_APC.Pickup() method, you are able to direct the APCs towards a point on the battlefield to board/load the cargo at the specific coordinate. The APCs will follow nearby roads as much as possible, to ensure fast and clean cargo transportation between the objects and villages in the simulation environment.

Developer Note

Note while this class still works, it is no longer supported as the original author stopped active development of MOOSE Therefore, this class is considered to be deprecated

Type(s)

Fields and Methods inherited from AI_CARGO_APC Description

AI_CARGO_APC.CargoCarrier

AI_CARGO_APC.CarrierCoordinate

AI_CARGO_APC.CarrierStopped

AI_CARGO_APC.Coalition

AI_CARGO_APC.CombatRadius

AI_CARGO_APC:FindCarrier(Coordinate, Radius)

Find a free Carrier within a radius.

AI_CARGO_APC:FollowToCarrier(Me, APCUnit, Cargo, CargoGroup)

Follow Infantry to the Carrier.

AI_CARGO_APC:New(APC, CargoSet, CombatRadius)

Creates a new AI_CARGO_APC object.

AI_CARGO_APC.RouteDeploy

AI_CARGO_APC.RouteHome

AI_CARGO_APC.RoutePickup

AI_CARGO_APC:SetCarrier(CargoCarrier)

Set the Carrier.

AI_CARGO_APC:SetCombatRadius(CombatRadius)

Enable/Disable unboarding of cargo (infantry) when enemies are nearby (to help defend the carrier).

AI_CARGO_APC:SetDeployOffRoad(Offroad, Formation)

Set whether the carrier will not use roads to deploy the cargo.

AI_CARGO_APC:SetOffRoad(Offroad, Formation)

Set whether or not the carrier will use roads to pickup and deploy the cargo.

AI_CARGO_APC:SetPickupOffRoad(Offroad, Formation)

Set whether the carrier will not use roads to pickup the cargo.

AI_CARGO_APC.Zone

AI_CARGO_APC._Deploy(APC, self, Coordinate, DeployZone)

Deploy task function.

AI_CARGO_APC._Pickup(APC, sel, Coordinate, Speed, PickupZone, self)

Pickup task function.

AI_CARGO_APC.deployFormation

AI_CARGO_APC.deployOffroad

AI_CARGO_APC:onafterDeploy(APC, From, Event, To, Coordinate, Speed, Height, DeployZone)

On after Deploy event.

AI_CARGO_APC:onafterDeployed(Carrier, From, Event, To, DeployZone, APC, Defend)

On after Deployed event.

AI_CARGO_APC:onafterFollow(APC, From, Event, To)

On after Follow event.

AI_CARGO_APC:onafterHome(APC, From, Event, To, Coordinate, Speed, Height, HomeZone)

On after Home event.

AI_CARGO_APC:onafterMonitor(APC, From, Event, To)

On after Monitor event.

AI_CARGO_APC:onafterPickup(APC, From, Event, To, Coordinate, Speed, Height, PickupZone)

On after Pickup event.

AI_CARGO_APC:onafterUnloaded(Carrier, From, Event, To, Cargo, Deployed, DeployZone, CarrierUnit, Defend)

On after Unloaded event.

AI_CARGO_APC.pickupFormation

AI_CARGO_APC.pickupOffroad

Fields and Methods inherited from AI_CARGO Description

AI_CARGO_APC.CargoCarrier

AI_CARGO_APC.CargoSet

AI_CARGO_APC.Carrier_Cargo

AI_CARGO_APC:Deploy(Coordinate, Speed)

Deploy Trigger for AI_CARGO

AI_CARGO_APC:IsRelocating()

AI_CARGO_APC:IsTransporting()

AI_CARGO_APC:New(Carrier, CargoSet)

Creates a new AI_CARGO object.

AI_CARGO_APC:OnAfterDeploy(From, Event, To, Coordinate, Speed)

Deploy Handler OnAfter for AI_CARGO

AI_CARGO_APC:OnAfterDeployed(Carrier, From, Event, To, DeployZone, Defend)

On after Deployed event.

AI_CARGO_APC:OnAfterLoaded(Carrier, From, Event, To)

Loaded Handler OnAfter for AI_CARGO

AI_CARGO_APC:OnAfterPickup(From, Event, To, Coordinate, Speed)

Pickup Handler OnAfter for AI_CARGO

AI_CARGO_APC:OnAfterUnloaded(Carrier, From, Event, To)

Unloaded Handler OnAfter for AI_CARGO

AI_CARGO_APC:OnBeforeDeploy(From, Event, To, Coordinate, Speed)

Deploy Handler OnBefore for AI_CARGO

AI_CARGO_APC:OnBeforePickup(From, Event, To, Coordinate, Speed)

Pickup Handler OnBefore for AI_CARGO

AI_CARGO_APC:Pickup(Coordinate, Speed)

Pickup Trigger for AI_CARGO

AI_CARGO_APC.Relocating

AI_CARGO_APC.Transporting

AI_CARGO_APC:__Deploy(Delay, Coordinate, Speed)

Deploy Asynchronous Trigger for AI_CARGO

AI_CARGO_APC:__Pickup(Delay, Coordinate, Speed)

Pickup Asynchronous Trigger for AI_CARGO

AI_CARGO_APC:onafterBoard(Carrier, From, Event, To, Cargo, CarrierUnit, PickupZone)

On after Board event.

AI_CARGO_APC:onafterDeploy(APC, From, Event, To, Coordinate, Speed, Height, DeployZone)

On after Deploy event.

AI_CARGO_APC:onafterDeployed(Carrier, From, Event, To, DeployZone, Defend)

On after Deployed event.

AI_CARGO_APC:onafterLoaded(Carrier, From, Event, To, PickupZone, Cargo)

On after Loaded event.

AI_CARGO_APC:onafterPickedUp(Carrier, From, Event, To, PickupZone)

On after PickedUp event.

AI_CARGO_APC:onafterPickup(APC, From, Event, To, Coordinate, Speed, Height, PickupZone)

On after Pickup event.

AI_CARGO_APC:onafterUnboard(Carrier, From, Event, To, Cargo, DeployZone, CarrierUnit, Defend)

On after Unboard event.

AI_CARGO_APC:onafterUnload(Carrier, From, Event, To, DeployZone, Defend)

On after Unload event.

AI_CARGO_APC:onafterUnloaded(Carrier, From, Event, To, Cargo, Deployed, DeployZone, CarrierUnit, Defend)

On after Unloaded event.

AI_CARGO_APC:onbeforeLoad(Carrier, From, Event, To, PickupZone)

On before Load event.

AI_CARGO_APC:onbeforeReload(Carrier, From, Event, To, PickupZone)

On before Reload event.

Field(s)

Function(s)

Find a free Carrier within a radius.

Defined in:

AI_CARGO_APC

Parameters:

#number Radius

Return value:

NewCarrier

Follow Infantry to the Carrier.

Defined in:

AI_CARGO_APC

Parameters:

CargoGroup

Return value:

Creates a new AI_CARGO_APC object.

Defined in:

AI_CARGO_APC

Parameters:

The carrier APC group.

The set of cargo to be transported.

#number CombatRadius

Provide the combat radius to defend the carrier by unboarding the cargo when enemies are nearby. When the combat radius is 0, no defense will happen of the carrier.

Return value:

Set the Carrier.

Defined in:

AI_CARGO_APC

Parameter:

Wrapper.Group#GROUP CargoCarrier

Return value:

Enable/Disable unboarding of cargo (infantry) when enemies are nearby (to help defend the carrier).

This is only valid for APCs and trucks etc, thus ground vehicles.

Defined in:

AI_CARGO_APC

Parameter:

#number CombatRadius

Provide the combat radius to defend the carrier by unboarding the cargo when enemies are nearby. When the combat radius is 0, no defense will happen of the carrier. When the combat radius is not provided, no defense will happen!

Return value:

Usage:


-- Disembark the infantry when the carrier is under attack.
AICargoAPC:SetCombatRadius( true )

-- Keep the cargo in the carrier when the carrier is under attack.
AICargoAPC:SetCombatRadius( false )

Set whether the carrier will not use roads to deploy the cargo.

Defined in:

AI_CARGO_APC

Parameters:

#boolean Offroad

If true, carrier will not use roads.

#number Formation

Offroad formation used. Default is ENUMS.Formation.Vehicle.Offroad.

Return value:

Set whether or not the carrier will use roads to pickup and deploy the cargo.

Defined in:

AI_CARGO_APC

Parameters:

#boolean Offroad

If true, carrier will not use roads. If nil or false the carrier will use roads when available.

#number Formation

Offroad formation used. Default is ENUMS.Formation.Vehicle.Offroad.

Return value:

Set whether the carrier will not use roads to pickup the cargo.

Defined in:

AI_CARGO_APC

Parameters:

#boolean Offroad

If true, carrier will not use roads.

#number Formation

Offroad formation used. Default is ENUMS.Formation.Vehicle.Offroad.

Return value:

Deploy task function.

Triggers Unload event.

Defined in:

AI_CARGO_APC

Parameters:

The cargo carrier group.

AI_CARGO_APC class.

The coordinate (not used).

Core.Zone#ZONE DeployZone

Deploy zone.

Pickup task function.

Triggers Load event.

Defined in:

AI_CARGO_APC

Parameters:

The cargo carrier group.

AI_CARGO_APC class.

The coordinate (not used).

#number Speed

Speed (not used).

Core.Zone#ZONE PickupZone

Pickup zone.

self

On after Deploy event.

Defined in:

AI_CARGO_APC

Parameters:

From

Event

To

Deploy place.

#number Speed

Speed in km/h to drive to the depoly coordinate. Default is 50% of max possible speed the unit can go.

#number Height

Height in meters to move to the deploy coordinate. This parameter is ignored for APCs.

Core.Zone#ZONE DeployZone

The zone where the cargo will be deployed.

On after Deployed event.

Defined in:

AI_CARGO_APC

Parameters:

#string From

From state.

#string Event

Event.

#string To

To state.

Core.Zone#ZONE DeployZone

The zone wherein the cargo is deployed. This can be any zone type, like a ZONE, ZONE_GROUP, ZONE_AIRBASE.

APC

Defend

On after Follow event.

Defined in:

AI_CARGO_APC

Parameters:

#string From

From state.

#string Event

Event.

#string To

To state.

On after Home event.

Defined in:

AI_CARGO_APC

Parameters:

From

Event

To

Home place.

#number Speed

Speed in km/h to drive to the pickup coordinate. Default is 50% of max possible speed the unit can go.

#number Height

Height in meters to move to the home coordinate. This parameter is ignored for APCs.

HomeZone

On after Monitor event.

Defined in:

AI_CARGO_APC

Parameters:

#string From

From state.

#string Event

Event.

#string To

To state.

On after Pickup event.

Defined in:

AI_CARGO_APC

Parameters:

From

Event

To

of the pickup point.

#number Speed

Speed in km/h to drive to the pickup coordinate. Default is 50% of max possible speed the unit can go.

#number Height

Height in meters to move to the pickup coordinate. This parameter is ignored for APCs.

Core.Zone#ZONE PickupZone

(optional) The zone where the cargo will be picked up. The PickupZone can be nil, if there wasn't any PickupZoneSet provided.

On after Unloaded event.

Defined in:

AI_CARGO_APC

Parameters:

#string From

From state.

#string Event

Event.

#string To

To state.

#string Cargo

Cargo#CARGO Cargo Cargo object.

#boolean Deployed

Cargo is deployed.

Core.Zone#ZONE DeployZone

The zone wherein the cargo is deployed. This can be any zone type, like a ZONE, ZONE_GROUP, ZONE_AIRBASE.

CarrierUnit

Defend

Field(s)

Function(s)

Deploy Trigger for AI_CARGO

Defined in:

Parameters:

#number Speed

Speed in km/h. Default is 50% of max possible speed the group can do.

Creates a new AI_CARGO object.

Defined in:

Parameters:

Cargo carrier group.

Set of cargo(s) to transport.

Return value:

self

Deploy Handler OnAfter for AI_CARGO

Defined in:

Parameters:

#string From

#string Event

#string To

#number Speed

Speed in km/h. Default is 50% of max possible speed the group can do.

On after Deployed event.

Defined in:

Parameters:

#string From

From state.

#string Event

Event.

#string To

To state.

Core.Zone#ZONE DeployZone

The zone wherein the cargo is deployed. This can be any zone type, like a ZONE, ZONE_GROUP, ZONE_AIRBASE.

#boolean Defend

Defend for APCs.

Loaded Handler OnAfter for AI_CARGO

Defined in:

Parameters:

#string From

#string Event

#string To

Pickup Handler OnAfter for AI_CARGO

Defined in:

Parameters:

#string From

#string Event

#string To

#number Speed

Speed in km/h. Default is 50% of max possible speed the group can do.

Unloaded Handler OnAfter for AI_CARGO

Defined in:

Parameters:

#string From

#string Event

#string To

Deploy Handler OnBefore for AI_CARGO

Defined in:

Parameters:

#string From

#string Event

#string To

#number Speed

Speed in km/h. Default is 50% of max possible speed the group can do.

Return value:

#boolean:

Pickup Handler OnBefore for AI_CARGO

Defined in:

Parameters:

#string From

#string Event

#string To

#number Speed

Speed in km/h. Default is 50% of max possible speed the group can do.

Return value:

#boolean:

Pickup Trigger for AI_CARGO

Defined in:

Parameters:

#number Speed

Speed in km/h. Default is 50% of max possible speed the group can do.

Deploy Asynchronous Trigger for AI_CARGO

Defined in:

Parameters:

#number Delay

#number Speed

Speed in km/h. Default is 50% of max possible speed the group can do.

Pickup Asynchronous Trigger for AI_CARGO

Defined in:

Parameters:

#number Delay

Pickup place. If not given, loading starts at the current location.

#number Speed

Speed in km/h. Default is 50% of max possible speed the group can do.

On after Board event.

Defined in:

Parameters:

#string From

From state.

#string Event

Event.

#string To

To state.

Cargo object.

Wrapper.Unit#UNIT CarrierUnit

Core.Zone#ZONE PickupZone

(optional) The zone where the cargo will be picked up. The PickupZone can be nil, if there wasn't any PickupZoneSet provided.

On after Deploy event.

Defined in:

Parameters:

From

Event

To

Deploy place.

#number Speed

Speed in km/h to drive to the depoly coordinate. Default is 50% of max possible speed the unit can go.

#number Height

Height in meters to move to the deploy coordinate.

Core.Zone#ZONE DeployZone

The zone where the cargo will be deployed.

On after Deployed event.

Defined in:

Parameters:

#string From

From state.

#string Event

Event.

#string To

To state.

Core.Zone#ZONE DeployZone

The zone wherein the cargo is deployed. This can be any zone type, like a ZONE, ZONE_GROUP, ZONE_AIRBASE.

#boolean Defend

Defend for APCs.

On after Loaded event.

Defined in:

Parameters:

#string From

From state.

#string Event

Event.

#string To

To state.

Core.Zone#ZONE PickupZone

(optional) The zone where the cargo will be picked up. The PickupZone can be nil, if there wasn't any PickupZoneSet provided.

Cargo

Return value:

#boolean:

Cargo loaded.

On after PickedUp event.

Defined in:

Parameters:

#string From

From state.

#string Event

Event.

#string To

To state.

Core.Zone#ZONE PickupZone

(optional) The zone where the cargo will be picked up. The PickupZone can be nil, if there wasn't any PickupZoneSet provided.

On after Pickup event.

Defined in:

Parameters:

From

Event

To

of the pickup point.

#number Speed

Speed in km/h to drive to the pickup coordinate. Default is 50% of max possible speed the unit can go.

#number Height

Height in meters to move to the home coordinate.

Core.Zone#ZONE PickupZone

(optional) The zone where the cargo will be picked up. The PickupZone can be nil, if there wasn't any PickupZoneSet provided.

On after Unboard event.

Defined in:

Parameters:

#string From

From state.

#string Event

Event.

#string To

To state.

#string Cargo

Cargo#CARGO Cargo Cargo object.

Core.Zone#ZONE DeployZone

The zone wherein the cargo is deployed. This can be any zone type, like a ZONE, ZONE_GROUP, ZONE_AIRBASE.

CarrierUnit

Defend

On after Unload event.

Defined in:

Parameters:

#string From

From state.

#string Event

Event.

#string To

To state.

Core.Zone#ZONE DeployZone

The zone wherein the cargo is deployed. This can be any zone type, like a ZONE, ZONE_GROUP, ZONE_AIRBASE.

Defend

On after Unloaded event.

Defined in:

Parameters:

#string From

From state.

#string Event

Event.

#string To

To state.

#string Cargo

Cargo#CARGO Cargo Cargo object.

#boolean Deployed

Cargo is deployed.

Core.Zone#ZONE DeployZone

The zone wherein the cargo is deployed. This can be any zone type, like a ZONE, ZONE_GROUP, ZONE_AIRBASE.

CarrierUnit

Defend

On before Load event.

Defined in:

Parameters:

#string From

From state.

#string Event

Event.

#string To

To state.

Core.Zone#ZONE PickupZone

(optional) The zone where the cargo will be picked up. The PickupZone can be nil, if there wasn't any PickupZoneSet provided.

On before Reload event.

Defined in:

Parameters:

#string From

From state.

#string Event

Event.

#string To

To state.

Core.Zone#ZONE PickupZone

(optional) The zone where the cargo will be picked up. The PickupZone can be nil, if there wasn't any PickupZoneSet provided.