diff --git a/Moose Development/Moose/AI/AI_Cargo_Dispatcher.lua b/Moose Development/Moose/AI/AI_Cargo_Dispatcher.lua index 0feea4e8e..6bce0816e 100644 --- a/Moose Development/Moose/AI/AI_Cargo_Dispatcher.lua +++ b/Moose Development/Moose/AI/AI_Cargo_Dispatcher.lua @@ -68,7 +68,6 @@ -- -- If no home zone is specified, the carriers will wait near the deploy zone for a new pickup command. -- --- -- === -- -- @field #AI_CARGO_DISPATCHER diff --git a/Moose Development/Moose/Cargo/Cargo.lua b/Moose Development/Moose/Cargo/Cargo.lua index 8add3c374..42d309c6a 100644 --- a/Moose Development/Moose/Cargo/Cargo.lua +++ b/Moose Development/Moose/Cargo/Cargo.lua @@ -2,6 +2,191 @@ -- -- === -- +-- # 1) MOOSE Cargo System. +-- +-- #### Those who have used the mission editor, know that the DCS mission editor provides cargo facilities. +-- However, these are merely static objects. Wouldn't it be nice if cargo could bring a new dynamism into your +-- simulations? Where various objects of various types could be treated also as cargo? +-- +-- This is what MOOSE brings to you, a complete new cargo object model that used the cargo capabilities of +-- DCS world, but enhances it. +-- +-- MOOSE Cargo introduces also a new concept, called a "carrier". These can be: +-- +-- - Helicopters +-- - Planes +-- - Ground Vehicles +-- - Ships +-- +-- With the MOOSE Cargo system, you can: +-- +-- - Take full control of the cargo as objects within your script (see below). +-- - Board/Unboard infantry into carriers. Also other objects can be boarded, like mortars. +-- - Load/Unload dcs world cargo objects into carriers. +-- - Load/Unload other static objects into carriers (like tires etc). +-- - Slingload cargo objects. +-- - Board units one by one... +-- +-- # 2) MOOSE Cargo Objects. +-- +-- In order to make use of the MOOSE cargo system, you need to **declare** the DCS objects as MOOSE cargo objects! +-- +-- This sounds complicated, but it is actually quite simple. +-- +-- See here an example: +-- +-- local EngineerCargoGroup = CARGO_GROUP:New( GROUP:FindByName( "Engineers" ), "Workmaterials", "Engineers", 250 ) +-- +-- The above code declares a MOOSE cargo object called `EngineerCargoGroup`. +-- It actually just refers to an infantry group created within the sim called `"Engineers"`. +-- The infantry group now becomes controlled by the MOOSE cargo object `EngineerCargoGroup`. +-- A MOOSE cargo object also has properties, like the type of cargo, the logical name, and the reporting range. +-- +-- There are 4 types of MOOSE cargo objects possible, each represented by its own class: +-- +-- - @{Cargo.CargoGroup#CARGO_GROUP}: A MOOSE cargo that is represented by a DCS world GROUP object. +-- - @{Cargo.CargoCrate#CARGO_CRATE}: A MOOSE cargo that is represented by a DCS world cargo object (static object). +-- - @{Cargo.CargoUnit#CARGO_UNIT}: A MOOSE cargo that is represented by a DCS world unit object or static object. +-- - @{Cargo.CargoSlingload#CARGO_SLINGLOAD}: A MOOSE cargo that is represented by a DCS world cargo object (static object), that can be slingloaded. +-- +-- Note that a CARGO crate is not meant to be slingloaded (it can, but it is not **meant** to be handled like that. +-- Instead, a CARGO_CRATE is able to load itself into the bays of a carrier. +-- +-- Each of these MOOSE cargo objects behave in its own way, and have methods to be handled. +-- +-- local InfantryGroup = GROUP:FindByName( "Infantry" ) +-- local InfantryCargo = CARGO_GROUP:New( InfantryGroup, "Engineers", "Infantry Engineers", 2000 ) +-- local CargoCarrier = UNIT:FindByName( "Carrier" ) +-- -- This call will make the Cargo run to the CargoCarrier. +-- -- Upon arrival at the CargoCarrier, the Cargo will be Loaded into the Carrier. +-- -- This process is now fully automated. +-- InfantryCargo:Board( CargoCarrier, 25 ) +-- +-- The above would create a MOOSE cargo object called `InfantryCargo`, and using that object, +-- you can board the cargo into the carrier `CargoCarrier`. +-- Simple, isn't it? Told you, and this is only the beginning. +-- +-- The boarding, unboarding, loading, unloading of cargo is however something that is not meant to be coded manualy by mission designers. +-- It would be too low-level and not end-user friendly to deal with cargo handling complexity. +-- Things can become really complex if you want to make cargo being handled and behave in multiple scenarios. +-- +-- # 3) Cargo Handling Classes, the main engines for mission designers! +-- +-- For this reason, the MOOSE Cargo System is heavily used by 3 important **cargo handling class hierarchies** within MOOSE, +-- that make cargo come "alive" within your mission in a full automatic manner! +-- +-- ## 3.1) AI Cargo handlers. +-- +-- - @{AI.AI_Cargo_APC} will create for you the capatility to make an APC group handle cargo. +-- - @{AI.AI_Cargo_Helicopter} will create for you the capatility to make a Helicopter group handle cargo. +-- +-- +-- ## 3.2) AI Cargo transportation dispatchers. +-- +-- There are also dispatchers that make AI work together to transport cargo automatically!!! +-- +-- - @{AI.AI_Cargo_Dispatcher_APC} derived classes will create for your dynamic cargo handlers controlled by AI ground vehicle groups (APCs) to transport cargo between sites. +-- - @{AI.AI_Cargo_Dispatcher_Helicopters} derived classes will create for your dynamic cargo handlers controlled by AI helicpter groups to transport cargo between sites. +-- +-- ## 3.3) Cargo transportation tasking. +-- +-- And there is cargo transportation tasking for human players. +-- +-- - @{Tasking.Task_CARGO} derived classes will create for you cargo transportation tasks, that allow human players to interact with MOOSE cargo objects to complete tasks. +-- +-- Please refer to the documentation reflected within these modules to understand the detailed capabilties. +-- +-- # 4) Cargo SETs. +-- +-- To make life a bit more easy, MOOSE cargo objects can be grouped into a @{Core.Set#SET_CARGO}. +-- This is a collection of MOOSE cargo objects. +-- +-- This would work as follows: +-- +-- -- Define the cargo set. +-- local CargoSetWorkmaterials = SET_CARGO:New():FilterTypes( "Workmaterials" ):FilterStart() +-- +-- -- Now add cargo the cargo set. +-- local EngineerCargoGroup = CARGO_GROUP:New( GROUP:FindByName( "Engineers" ), "Workmaterials", "Engineers", 250 ) +-- local ConcreteCargo = CARGO_SLINGLOAD:New( STATIC:FindByName( "Concrete" ), "Workmaterials", "Concrete", 150, 50 ) +-- local CrateCargo = CARGO_CRATE:New( STATIC:FindByName( "Crate" ), "Workmaterials", "Crate", 150, 50 ) +-- local EnginesCargo = CARGO_CRATE:New( STATIC:FindByName( "Engines" ), "Workmaterials", "Engines", 150, 50 ) +-- local MetalCargo = CARGO_CRATE:New( STATIC:FindByName( "Metal" ), "Workmaterials", "Metal", 150, 50 ) +-- +-- This is a very powerful concept! +-- Instead of having to deal with multiple MOOSE cargo objects yourself, the cargo set capability will group cargo objects into one set. +-- The key is the **cargo type** name given at each cargo declaration! +-- In the above example, the cargo type name is `"Workmaterials"`. Each cargo object declared is given that type name. (the 2nd parameter). +-- What happens now is that the cargo set `CargoSetWorkmaterials` will be added with each cargo object **dynamically** when the cargo object is created. +-- In other words, the cargo set `CargoSetWorkmaterials` will incorporate any `"Workmaterials"` dynamically into its set. +-- +-- The cargo sets are extremely important for the AI cargo transportation dispatchers and the cargo transporation tasking. +-- +-- # 5) Declare MOOSE cargo within the mission editor!!! +-- +-- But I am not finished! There is something more, that is even more great! +-- Imagine the mission designers having to code all these lines every time it wants to embed cargo within a mission. +-- +-- -- Now add cargo the cargo set. +-- local EngineerCargoGroup = CARGO_GROUP:New( GROUP:FindByName( "Engineers" ), "Workmaterials", "Engineers", 250 ) +-- local ConcreteCargo = CARGO_SLINGLOAD:New( STATIC:FindByName( "Concrete" ), "Workmaterials", "Concrete", 150, 50 ) +-- local CrateCargo = CARGO_CRATE:New( STATIC:FindByName( "Crate" ), "Workmaterials", "Crate", 150, 50 ) +-- local EnginesCargo = CARGO_CRATE:New( STATIC:FindByName( "Engines" ), "Workmaterials", "Engines", 150, 50 ) +-- local MetalCargo = CARGO_CRATE:New( STATIC:FindByName( "Metal" ), "Workmaterials", "Metal", 150, 50 ) +-- +-- This would be extremely tiring and a huge overload. +-- However, the MOOSE framework allows to declare MOOSE cargo objects within the mission editor!!! +-- +-- So, at mission startup, MOOSE will search for objects following a special naming convention, and will create for you dynamically +-- cargo objects at mission start!!! +-- These cargo objects can then be automatically incorporated within cargo set(s)!!! +-- In other words, your mission would be reduced to about a few lines of code, providing you with a full dynamic cargo handling mission! +-- +-- What I talk about is this: +-- +-- HQ = GROUP:FindByName( "HQ", "Bravo" ) +-- +-- CommandCenter = COMMANDCENTER +-- :New( HQ, "Lima" ) +-- +-- Mission = MISSION +-- :New( CommandCenter, "Operation Cargo Fun", "Tactical", "Transport Cargo", coalition.side.RED ) +-- +-- TransportGroups = SET_GROUP:New():FilterCoalitions( "blue" ):FilterPrefixes( "Transport" ):FilterStart() +-- +-- TaskDispatcher = TASK_CARGO_DISPATCHER:New( Mission, TransportGroups ) +-- +-- +-- -- This is the most important now. You setup a new SET_CARGO filtering the relevant type. +-- -- The actual cargo objects are now created by MOOSE in the background. +-- -- Each cargo is setup in the Mission Editor using the ~CARGO tag in the group name. +-- -- This allows a truly dynamic setup. +-- local CargoSetWorkmaterials = SET_CARGO:New():FilterTypes( "Workmaterials" ):FilterStart() +-- +-- local WorkplaceTask = TaskDispatcher:AddTransportTask( "Build a Workplace", CargoSetWorkmaterials, "Transport the workers, engineers and the equipment near the Workplace." ) +-- TaskDispatcher:SetTransportDeployZone( WorkplaceTask, ZONE:New( "Workplace" ) ) +-- +-- Helos = { SPAWN:New( "Helicopters 1" ), SPAWN:New( "Helicopters 2" ), SPAWN:New( "Helicopters 3" ), SPAWN:New( "Helicopters 4" ), SPAWN:New( "Helicopters 5" ) } +-- +-- EnemyHelos = { SPAWN:New( "Enemy Helicopters 1" ), SPAWN:New( "Enemy Helicopters 2" ), SPAWN:New( "Enemy Helicopters 3" ) } +-- +-- function WorkplaceTask:OnAfterCargoDeployed( From, Event, To, TaskUnit, Cargo, DeployZone ) +-- Helos[ math.random(1,#Helos) ]:Spawn() +-- EnemyHelos[ math.random(1,#EnemyHelos) ]:Spawn() +-- +-- end +-- +-- Here the `CargoSetWorkmaterials` is provided as a parameter to the cargo task dispatcher object WorkplaceTask`. +-- And there is NO cargo object actually declared within the script! However, if you would open the mission, there would be hundreds of cargo objects... +-- +-- HOW? => Through a naming convention introduced. Name infantry groups in a special manner, and it can behave as MOOSE cargo! +-- +-- 5.1) Name MOOSE cargo objects within the mission editor! +-- +-- +-- +-- === +-- -- ### Author: **FlightControl** -- ### Contributions: --