- Documentation

- Added the methods Added and Removed to the SET
- Cleanup of code.

Moose Development/Moose/AI/AI_Cargo_APC.lua

@@ -82,11 +82,11 @@ AI_CARGO_APC = {
 
 --- Creates a new AI_CARGO_APC object.
 -- @param #AI_CARGO_APC self
--- @param Wrapper.Group#GROUP CargoCarrier
+-- @param Wrapper.Group#GROUP APC
 -- @param Core.Set#SET_CARGO CargoSet
 -- @param #number CombatRadius
 -- @return #AI_CARGO_APC
-function AI_CARGO_APC:New( CargoCarrier, CargoSet, CombatRadius )
+function AI_CARGO_APC:New( APC, CargoSet, CombatRadius )
 
   local self = BASE:Inherit( self, FSM_CONTROLLABLE:New() ) -- #AI_CARGO_APC
 
@@ -189,7 +189,8 @@ function AI_CARGO_APC:New( CargoCarrier, CargoSet, CombatRadius )
 
   self:__Monitor( 1 )
 
-  self:SetCarrier( CargoCarrier )
+
+  self:SetCarrier( APC )
   self.Transporting = false
   self.Relocating = false
   

Moose Development/Moose/AI/AI_Cargo_Dispatcher.lua

@@ -9,66 +9,115 @@
 -- @module AI_Cargo_Dispatcher
 
 --- @type AI_CARGO_DISPATCHER
--- @extends Core.Fsm#FSM_CONTROLLABLE
+-- @extends Core.Fsm#FSM
 
 
---- # AI\_CARGO\_DISPATCHER class, extends @{Core.Base#BASE}
+--- # AI\_CARGO\_DISPATCHER class, extends @{Core.Fsm#FSM}
 -- 
 -- ===
 -- 
 -- AI\_CARGO\_DISPATCHER brings a dynamic cargo handling capability for AI groups.
 -- 
--- Armoured Personnel APCs (APC), Trucks, Jeeps and other carrier equipment can be mobilized to intelligently transport infantry and other cargo within the simulation.
+-- Carrier equipment can be mobilized to intelligently transport infantry and other cargo within the simulation.
--- The AI\_CARGO\_DISPATCHER module uses the @{Cargo} capabilities within the MOOSE framework.
+-- The AI\_CARGO\_DISPATCHER module uses the @{Cargo} capabilities within the MOOSE framework, to enable Carrier GROUP objects 
+-- to transport @{Cargo} towards several deploy zones.
 -- CARGO derived objects must be declared within the mission to make the AI\_CARGO\_DISPATCHER object recognize the cargo.
 -- Please consult the @{Cargo} module for more information. 
 -- 
+-- ## 1. AI\_CARGO\_DISPATCHER constructor
 --   
+--   * @{#AI_CARGO_DISPATCHER.New}(): Creates a new AI\_CARGO\_DISPATCHER object.
+-- 
+-- ## 2. AI\_CARGO\_DISPATCHER is a FSM
+-- 
+-- ![Process](..\Presentations\AI_PATROL\Dia2.JPG)
+-- 
+-- ### 2.1. AI\_CARGO\_DISPATCHER States
+-- 
+--   * **Monitoring**: The process is dispatching.
+--   * **Idle**: The process is idle.
+-- 
+-- ### 2.2. AI\_CARGO\_DISPATCHER Events
+-- 
+--   * **Monitor**: Monitor and take action.
+--   * **Start**: Start the transport process.
+--   * **Stop**: Stop the transport process.
+--   * **Pickup**: Pickup cargo.
+--   * **Load**: Load the cargo.
+--   * **Loaded**: Flag that the cargo is loaded.
+--   * **Deploy**: Deploy cargo to a location.
+--   * **Unload**: Unload the cargo.
+--   * **Unloaded**: Flag that the cargo is unloaded.
+--   * **Home**: A Carrier is going home.
+-- 
+-- ## 3. 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.
+--    
+-- ## 4. 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.
+-- 
+-- ## 5. 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.   
+-- 
+-- ===
 --   
 -- @field #AI_CARGO_DISPATCHER
 AI_CARGO_DISPATCHER = {
   ClassName = "AI_CARGO_DISPATCHER",
-  SetAPC = nil,
+  SetCarrier = nil,
   SetDeployZones = nil,
-  AI_CARGO_APC = {}
+  AI_Cargo = {},
+  PickupCargo = {}
 }
 
---- @type AI_CARGO_DISPATCHER.AI_CARGO_APC
+--- @field #AI_CARGO_DISPATCHER.AI_Cargo 
--- @map <Wrapper.Group#GROUP, AI.AI_Cargo_APC#AI_CARGO_APC>
-
---- @field #AI_CARGO_DISPATCHER.AI_CARGO_APC 
 AI_CARGO_DISPATCHER.AI_Cargo = {}
 
 --- @field #AI_CARGO_DISPATCHER.PickupCargo
 AI_CARGO_DISPATCHER.PickupCargo = {}
 
 
-
 --- Creates a new AI_CARGO_DISPATCHER object.
 -- @param #AI_CARGO_DISPATCHER self
--- @param Core.Set#SET_GROUP SetAPC
+-- @param Core.Set#SET_GROUP SetCarrier
 -- @param Core.Set#SET_CARGO SetCargo
 -- @param Core.Set#SET_ZONE SetDeployZone
 -- @return #AI_CARGO_DISPATCHER
 -- @usage
 -- 
 -- -- Create a new cargo dispatcher
--- SetAPC = SET_GROUP:New():FilterPrefixes( "APC" ):FilterStart()
+-- SetCarrier = SET_GROUP:New():FilterPrefixes( "APC" ):FilterStart()
 -- SetCargo = SET_CARGO:New():FilterTypes( "Infantry" ):FilterStart()
 -- SetDeployZone = SET_ZONE:New():FilterPrefixes( "Deploy" ):FilterStart()
--- AICargoDispatcher = AI_CARGO_DISPATCHER:New( SetAPC, SetCargo, SetDeployZone )
+-- AICargoDispatcher = AI_CARGO_DISPATCHER:New( SetCarrier, SetCargo, SetDeployZone )
 -- 
-function AI_CARGO_DISPATCHER:New( SetAPC, SetCargo, SetDeployZones )
+function AI_CARGO_DISPATCHER:New( SetCarrier, SetCargo, SetDeployZones )
 
   local self = BASE:Inherit( self, FSM:New() ) -- #AI_CARGO_DISPATCHER
 
-  self.SetAPC = SetAPC -- Core.Set#SET_GROUP
+  self.SetCarrier = SetCarrier -- Core.Set#SET_GROUP
   self.SetCargo = SetCargo -- Core.Set#SET_CARGO
   self.SetDeployZones = SetDeployZones -- Core.Set#SET_ZONE
 
-  self:SetStartState( "Dispatch" ) 
+  self:SetStartState( "Idle" ) 
+  
+  self:AddTransition( "Monitoring", "Monitor", "Monitoring" )
+
+  self:AddTransition( "Idle", "Start", "Monitoring" )
+  self:AddTransition( "Monitoring", "Stop", "Idle" )
   
-  self:AddTransition( "*", "Monitor", "*" )
 
   self:AddTransition( "*", "Pickup", "*" )
   self:AddTransition( "*", "Loading", "*" )
@@ -84,8 +133,16 @@ function AI_CARGO_DISPATCHER:New( SetAPC, SetCargo, SetDeployZones )
   self.DeployRadiusInner = 200
   self.DeployRadiusOuter = 500
   
+  self.PickupCargo = {}
   self.CarrierHome = {}
   
+  -- Put a Dead event handler on SetCarrier, to ensure that when a carrier is destroyed, that all internal parameters are reset.
+  function SetCarrier.OnAfterRemoved( SetCarrier, From, Event, To, CarrierName, Carrier )
+    self:F( { Carrier = Carrier:GetName() } )
+    self.PickupCargo[Carrier] = nil
+    self.CarrierHome[Carrier] = nil
+  end
+  
   return self
 end
 
@@ -99,7 +156,7 @@ end
 -- @usage
 -- 
 -- -- Create a new cargo dispatcher
--- AICargoDispatcher = AI_CARGO_DISPATCHER:New( SetAPC, SetCargo, SetDeployZone )
+-- AICargoDispatcher = AI_CARGO_DISPATCHER:New( SetCarrier, SetCargo, SetDeployZone )
 -- 
 -- -- Set the home coordinate
 -- local HomeZone = ZONE:New( "Home" )
@@ -132,7 +189,7 @@ end
 -- @usage
 -- 
 -- -- Create a new cargo dispatcher
--- AICargoDispatcher = AI_CARGO_DISPATCHER:New( SetAPC, SetCargo, SetDeployZone )
+-- AICargoDispatcher = AI_CARGO_DISPATCHER:New( SetCarrier, SetCargo, SetDeployZone )
 -- 
 -- -- Set the carrier to land within a band around the cargo coordinate between 500 and 300 meters!
 -- AICargoDispatcher:SetPickupRadius( 500, 300 )
@@ -157,7 +214,7 @@ end
 -- @usage
 -- 
 -- -- Create a new cargo dispatcher
--- AICargoDispatcher = AI_CARGO_DISPATCHER:New( SetAPC, SetCargo, SetDeployZone )
+-- AICargoDispatcher = AI_CARGO_DISPATCHER:New( SetCarrier, SetCargo, SetDeployZone )
 -- 
 -- -- Set the minimum pickup speed to be 100 km/h and the maximum speed to be 200 km/h.
 -- AICargoDispatcher:SetPickupSpeed( 200, 100 )
@@ -190,7 +247,7 @@ end
 -- @usage
 -- 
 -- -- Create a new cargo dispatcher
--- AICargoDispatcher = AI_CARGO_DISPATCHER:New( SetAPC, SetCargo, SetDeployZone )
+-- AICargoDispatcher = AI_CARGO_DISPATCHER:New( SetCarrier, SetCargo, SetDeployZone )
 -- 
 -- -- Set the carrier to land within a band around the cargo coordinate between 500 and 300 meters!
 -- AICargoDispatcher:SetDeployRadius( 500, 300 )
@@ -215,7 +272,7 @@ end
 -- @usage
 -- 
 -- -- Create a new cargo dispatcher
--- AICargoDispatcher = AI_CARGO_DISPATCHER:New( SetAPC, SetCargo, SetDeployZone )
+-- AICargoDispatcher = AI_CARGO_DISPATCHER:New( SetCarrier, SetCargo, SetDeployZone )
 -- 
 -- -- Set the minimum deploy speed to be 100 km/h and the maximum speed to be 200 km/h.
 -- AICargoDispatcher:SetDeploySpeed( 200, 100 )
@@ -235,65 +292,67 @@ end
 
 --- The Start trigger event, which actually takes action at the specified time interval.
 -- @param #AI_CARGO_DISPATCHER self
--- @param Wrapper.Group#GROUP APC
--- @return #AI_CARGO_DISPATCHER
 function AI_CARGO_DISPATCHER:onafterMonitor()
 
-  for APCGroupName, Carrier in pairs( self.SetAPC:GetSet() ) do
+  for CarrierGroupName, Carrier in pairs( self.SetCarrier:GetSet() ) do
     local Carrier = Carrier -- Wrapper.Group#GROUP
     local AI_Cargo = self.AI_Cargo[Carrier]
     if not AI_Cargo then
     
-      -- ok, so this APC does not have yet an AI_CARGO_APC object...
+      -- ok, so this Carrier does not have yet an AI_CARGO handling object...
       -- let's create one and also declare the Loaded and UnLoaded handlers.
       self.AI_Cargo[Carrier] = self:AICargo( Carrier, self.SetCargo, self.CombatRadius )
       AI_Cargo = self.AI_Cargo[Carrier]
       
-      function AI_Cargo.OnAfterPickup( AI_Cargo, APC, From, Event, To, Cargo )
+      function AI_Cargo.OnAfterPickup( AI_Cargo, Carrier, From, Event, To, Cargo )
-        self:Pickup( APC, Cargo )
+        self:Pickup( Carrier, Cargo )
       end
       
-      function AI_Cargo.OnAfterLoad( AI_Cargo, APC )
+      function AI_Cargo.OnAfterLoad( AI_Cargo, Carrier )
-        self:Loading( APC )
+        self:Loading( Carrier )
       end
 
-      function AI_Cargo.OnAfterLoaded( AI_Cargo, APC, From, Event, To, Cargo )
+      function AI_Cargo.OnAfterLoaded( AI_Cargo, Carrier, From, Event, To, Cargo )
-        self:Loaded( APC, Cargo )
+        self:Loaded( Carrier, Cargo )
       end
 
-      function AI_Cargo.OnAfterDeploy( AI_Cargo, APC )
+      function AI_Cargo.OnAfterDeploy( AI_Cargo, Carrier )
-        self:Deploy( APC )
+        self:Deploy( Carrier )
       end      
 
-      function AI_Cargo.OnAfterUnload( AI_Cargo, APC )
+      function AI_Cargo.OnAfterUnload( AI_Cargo, Carrier )
-        self:Unloading( APC )
+        self:Unloading( Carrier )
       end      
 
-      function AI_Cargo.OnAfterUnloaded( AI_Cargo, APC )
+      function AI_Cargo.OnAfterUnloaded( AI_Cargo, Carrier )
-        self:Unloaded( APC )
+        self:Unloaded( Carrier )
       end      
     end
 
     -- The Pickup sequence ...
-    -- Check if this APC need to go and Pickup something...
+    -- Check if this Carrier need to go and Pickup something...
     self:I( { IsTransporting = AI_Cargo:IsTransporting() } )
     if AI_Cargo:IsTransporting() == false then
-      -- ok, so there is a free APC
+      -- ok, so there is a free Carrier
       -- now find the first cargo that is Unloaded
       
       local PickupCargo = nil
       
       for CargoName, Cargo in pairs( self.SetCargo:GetSet() ) do
         local Cargo = Cargo -- Cargo.Cargo#CARGO
-        self:F( { Cargo = Cargo:GetName(), UnLoaded = Cargo:IsUnLoaded(), Deployed = Cargo:IsDeployed(), PickupCargo = self.PickupCargo[Cargo] ~= nil } )
+        self:F( { Cargo = Cargo:GetName(), UnLoaded = Cargo:IsUnLoaded(), Deployed = Cargo:IsDeployed(), PickupCargo = self.PickupCargo[Carrier] ~= nil } )
         if Cargo:IsUnLoaded() and not Cargo:IsDeployed() then
           local CargoCoordinate = Cargo:GetCoordinate()
           local CoordinateFree = true
-          for APC, Coordinate in pairs( self.PickupCargo ) do
+          for CarrierPickup, Coordinate in pairs( self.PickupCargo ) do
+            if CarrierPickup:IsAlive() == true then
               if CargoCoordinate:Get2DDistance( Coordinate ) <= 25 then
                 CoordinateFree = false
                 break
               end
+            else
+              self.PickupCargo[CarrierPickup] = nil
+            end
           end
           if CoordinateFree == true then
             self.PickupCargo[Carrier] = CargoCoordinate
@@ -319,36 +378,90 @@ function AI_CARGO_DISPATCHER:onafterMonitor()
   end
 
   self:__Monitor( self.MonitorTimeInterval )
+end
 
-  return self
+--- Start Handler OnBefore for AI_CARGO_DISPATCHER
+-- @function [parent=#AI_CARGO_DISPATCHER] OnBeforeStart
+-- @param #AI_CARGO_DISPATCHER self
+-- @param #string From
+-- @param #string Event
+-- @param #string To
+-- @return #boolean
+
+--- Start Handler OnAfter for AI_CARGO_DISPATCHER
+-- @function [parent=#AI_CARGO_DISPATCHER] OnAfterStart
+-- @param #AI_CARGO_DISPATCHER self
+-- @param #string From
+-- @param #string Event
+-- @param #string To
+
+--- Start Trigger for AI_CARGO_DISPATCHER
+-- @function [parent=#AI_CARGO_DISPATCHER] Start
+-- @param #AI_CARGO_DISPATCHER self
+
+--- Start Asynchronous Trigger for AI_CARGO_DISPATCHER
+-- @function [parent=#AI_CARGO_DISPATCHER] __Start
+-- @param #AI_CARGO_DISPATCHER self
+-- @param #number Delay
+
+function AI_CARGO_DISPATCHER:onafterStart( From, Event, To )
+  self:Monitor()
+end
+
+--- Stop Handler OnBefore for AI_CARGO_DISPATCHER
+-- @function [parent=#AI_CARGO_DISPATCHER] OnBeforeStop
+-- @param #AI_CARGO_DISPATCHER self
+-- @param #string From
+-- @param #string Event
+-- @param #string To
+-- @return #boolean
+
+--- Stop Handler OnAfter for AI_CARGO_DISPATCHER
+-- @function [parent=#AI_CARGO_DISPATCHER] OnAfterStop
+-- @param #AI_CARGO_DISPATCHER self
+-- @param #string From
+-- @param #string Event
+-- @param #string To
+
+--- Stop Trigger for AI_CARGO_DISPATCHER
+-- @function [parent=#AI_CARGO_DISPATCHER] Stop
+-- @param #AI_CARGO_DISPATCHER self
+
+--- Stop Asynchronous Trigger for AI_CARGO_DISPATCHER
+-- @function [parent=#AI_CARGO_DISPATCHER] __Stop
+-- @param #AI_CARGO_DISPATCHER self
+-- @param #number Delay
+
+
+
+--- Make a Carrier run for a cargo deploy action after the cargo Pickup trigger has been initiated, by default.
+-- @param #AI_CARGO_DISPATCHER self
+-- @param From
+-- @param Event
+-- @param To
+-- @param Wrapper.Group#GROUP Carrier
+-- @param Cargo.Cargo#CARGO Cargo
+-- @return #AI_CARGO_DISPATCHER
+function AI_CARGO_DISPATCHER:OnAfterPickup( From, Event, To, Carrier, Cargo )
 end
 
 
-
+--- Make a Carrier run for a cargo deploy action after the cargo has been loaded, by default.
---- Make a APC run for a cargo deploy action after the cargo Pickup trigger has been initiated, by default.
 -- @param #AI_CARGO_DISPATCHER self
--- @param Wrapper.Group#GROUP APC
+-- @param From
+-- @param Event
+-- @param To
+-- @param Wrapper.Group#GROUP Carrier
+-- @param Cargo.Cargo#CARGO Cargo
 -- @return #AI_CARGO_DISPATCHER
-function AI_CARGO_DISPATCHER:onafterPickup( From, Event, To, APC, Cargo )
+function AI_CARGO_DISPATCHER:OnAfterLoaded( From, Event, To, Carrier, Cargo )
-  return self
-end
 
---- Make a APC run for a cargo deploy action after the cargo has been loaded, by default.
--- @param #AI_CARGO_DISPATCHER self
--- @param Wrapper.Group#GROUP APC
--- @return #AI_CARGO_DISPATCHER
-function AI_CARGO_DISPATCHER:OnAfterLoaded( From, Event, To, APC, Cargo )
-
-  self:I( { "Loaded Dispatcher", APC } )
   local DeployZone = self.SetDeployZones:GetRandomZone()
-  self:I( { RandomZone = DeployZone } )
   
   local DeployCoordinate = DeployZone:GetCoordinate():GetRandomCoordinateInRadius( self.DeployOuterRadius, self.DeployInnerRadius )
-  self.AI_Cargo[APC]:Deploy( DeployCoordinate, math.random( self.DeployMinSpeed, self.DeployMaxSpeed ) )
+  self.AI_Cargo[Carrier]:Deploy( DeployCoordinate, math.random( self.DeployMinSpeed, self.DeployMaxSpeed ) )
   
-  self.PickupCargo[APC] = nil
+  self.PickupCargo[Carrier] = nil
-  
-  return self
 end
 
 

Moose Development/Moose/AI/AI_Cargo_Dispatcher_APC.lua

@@ -14,6 +14,8 @@
 
 --- # AI\_CARGO\_DISPATCHER\_APC class, extends @{Core.Base#BASE}
 -- 
+-- ![Banner Image](..\Presentations\AI_CARGO_DISPATCHER_APC\Dia1.JPG)
+-- 
 -- ===
 -- 
 -- AI\_CARGO\_DISPATCHER\_APC brings a dynamic cargo handling capability for AI groups.
@@ -23,7 +25,54 @@
 -- CARGO derived objects must be declared within the mission to make the AI\_CARGO\_DISPATCHER\_APC object recognize the cargo.
 -- Please consult the @{Cargo} module for more information. 
 -- 
+-- ## 1. AI\_CARGO\_DISPATCHER\_APC constructor
 --   
+--   * @{#AI_CARGO_DISPATCHER\_APC.New}(): Creates a new AI\_CARGO\_DISPATCHER\_APC object.
+-- 
+-- ## 2. AI\_CARGO\_DISPATCHER\_APC is a FSM
+-- 
+-- ![Process](..\Presentations\AI_CARGO_DISPATCHER_APC\Dia3.JPG)
+-- 
+-- ### 2.1. AI\_CARGO\_DISPATCHER\_APC States
+-- 
+--   * **Monitoring**: The process is dispatching.
+--   * **Idle**: The process is idle.
+-- 
+-- ### 2.2. AI\_CARGO\_DISPATCHER\_APC Events
+-- 
+--   * **Monitor**: Monitor and take action.
+--   * **Start**: Start the transport process.
+--   * **Stop**: Stop the transport process.
+--   * **Pickup**: Pickup cargo.
+--   * **Load**: Load the cargo.
+--   * **Loaded**: Flag that the cargo is loaded.
+--   * **Deploy**: Deploy cargo to a location.
+--   * **Unload**: Unload the cargo.
+--   * **Unloaded**: Flag that the cargo is unloaded.
+--   * **Home**: A APC is going home.
+-- 
+-- ## 3. Set the pickup parameters.
+-- 
+-- Several parameters can be set to pickup cargo:
+-- 
+--    * @{#AI_CARGO_DISPATCHER\_APC.SetPickupRadius}(): Sets or randomizes the pickup location for the APC around the cargo coordinate in a radius defined an outer and optional inner radius. 
+--    * @{#AI_CARGO_DISPATCHER\_APC.SetPickupSpeed}(): Set the speed or randomizes the speed in km/h to pickup the cargo.
+--    
+-- ## 4. Set the deploy parameters.
+-- 
+-- Several parameters can be set to deploy cargo:
+-- 
+--    * @{#AI_CARGO_DISPATCHER\_APC.SetDeployRadius}(): Sets or randomizes the deploy location for the APC around the cargo coordinate in a radius defined an outer and an optional inner radius. 
+--    * @{#AI_CARGO_DISPATCHER\_APC.SetDeploySpeed}(): Set the speed or randomizes the speed in km/h to deploy the cargo.
+-- 
+-- ## 5. Set the home zone when there isn't any more cargo to pickup.
+-- 
+-- A home zone can be specified to where the APCs will move when there isn't any cargo left for pickup.
+-- Use @{#AI_CARGO_DISPATCHER\_APC.SetHomeZone}() to specify the home zone.
+-- 
+-- If no home zone is specified, the APCs will wait near the deploy zone for a new pickup command.   
+-- 
+-- ===
 -- 
 -- @field #AI_CARGO_DISPATCHER_APC
 AI_CARGO_DISPATCHER_APC = {
@@ -32,31 +81,30 @@ AI_CARGO_DISPATCHER_APC = {
 
 --- Creates a new AI_CARGO_DISPATCHER_APC object.
 -- @param #AI_CARGO_DISPATCHER_APC self
--- @param Core.Set#SET_GROUP SetAPC
+-- @param Core.Set#SET_GROUP SetAPC The collection of APC @{Group}s.
--- @param Core.Set#SET_CARGO SetCargo
+-- @param Core.Set#SET_CARGO SetCargo The collection of @{Cargo} derived objects.
--- @param Core.Set#SET_ZONE SetDeployZone
+-- @param Core.Set#SET_ZONE SetDeployZone The collection of deploy @{Zone}s, which are used to where the cargo will be deployed by the APCs. 
+-- @param #number CombatRadius The cargo will be unloaded from the APC and engage the enemy if the enemy is within CombatRadius range. The radius is in meters, the default value is 500 meters.
 -- @return #AI_CARGO_DISPATCHER_APC
 -- @usage
 -- 
--- -- Create a new cargo dispatcher
+-- -- Create a new cargo dispatcher for the set of APCs, with a combatradius of 500.
 -- SetAPC = SET_GROUP:New():FilterPrefixes( "APC" ):FilterStart()
 -- SetCargo = SET_CARGO:New():FilterTypes( "Infantry" ):FilterStart()
 -- SetDeployZone = SET_ZONE:New():FilterPrefixes( "Deploy" ):FilterStart()
--- AICargoDispatcher = AI_CARGO_DISPATCHER_APC:New( SetAPC, SetCargo )
+-- AICargoDispatcher = AI_CARGO_DISPATCHER_APC:New( SetAPC, SetCargo, SetDeployZone, 500 )
 -- 
-function AI_CARGO_DISPATCHER_APC:New( SetAPC, SetCargo, SetDeployZones )
+function AI_CARGO_DISPATCHER_APC:New( SetAPC, SetCargo, SetDeployZones, CombatRadius )
 
   local self = BASE:Inherit( self, AI_CARGO_DISPATCHER:New( SetAPC, SetCargo, SetDeployZones ) ) -- #AI_CARGO_DISPATCHER_APC
 
-  self.CombatRadius = 500
+  self.CombatRadius = CombatRadius or 500
 
   self:SetDeploySpeed( 70, 120 )
   self:SetPickupSpeed( 70, 120 )
   self:SetPickupRadius( 0, 0 )
   self:SetDeployRadius( 0, 0 )
 
-  self:Monitor( 1 )
-
   return self
 end
 

Moose Development/Moose/AI/AI_Cargo_Dispatcher_Helicopter.lua

@@ -1,5 +1,7 @@
 --- **AI** -- (R2.4) - Models the intelligent transportation of infantry and other cargo using Helicopters.
 --
+-- The @{#AI_CARGO_DISPATCHER_HELICOPTER} classes implements the dynamic dispatching of cargo transportation tasks for helicopters.
+--
 -- ===
 -- 
 -- ### Author: **FlightControl**
@@ -12,18 +14,77 @@
 -- @extends AI.AI_Cargo_Dispatcher#AI_CARGO_DISPATCHER
 
 
---- # AI\_CARGO\_DISPATCHER\_HELICOPTER class, extends @{Core.Base#BASE}
+--- # AI\_CARGO\_DISPATCHER\_HELICOPTER class, extends @{AI.AI_Cargo_Dispatcher#AI_CARGO_DISPATCHER}
+-- 
+-- ![Banner Image](..\Presentations\AI_CARGO_DISPATCHER_HELICOPTER\Dia1.JPG)
 -- 
 -- ===
 -- 
--- AI\_CARGO\_DISPATCHER\_HELICOPTER brings a dynamic cargo handling capability for AI groups.
+-- AI\_CARGO\_DISPATCHER\_HELICOPTER brings a dynamic cargo handling capability for AI helicopter groups.
 -- 
 -- Helicopters can be mobilized to intelligently transport infantry and other cargo within the simulation.
 -- The AI\_CARGO\_DISPATCHER\_HELICOPTER module uses the @{Cargo} capabilities within the MOOSE framework.
 -- CARGO derived objects must be declared within the mission to make the AI\_CARGO\_DISPATCHER\_HELICOPTER object recognize the cargo.
 -- Please consult the @{Cargo} module for more information. 
 -- 
+-- ---
 -- 
+-- ## 1. AI\_CARGO\_DISPATCHER\_HELICOPTER constructor
+--   
+--   * @{#AI_CARGO_DISPATCHER\_HELICOPTER.New}(): Creates a new AI\_CARGO\_DISPATCHER\_HELICOPTER object.
+-- 
+-- ---
+-- 
+-- ## 2. AI\_CARGO\_DISPATCHER\_HELICOPTER is a FSM
+-- 
+-- ![Process](..\Presentations\AI_CARGO_DISPATCHER_HELICOPTER\Dia3.JPG)
+-- 
+-- ### 2.1. AI\_CARGO\_DISPATCHER\_HELICOPTER States
+-- 
+--   * **Monitoring**: The process is dispatching.
+--   * **Idle**: The process is idle.
+-- 
+-- ### 2.2. AI\_CARGO\_DISPATCHER\_HELICOPTER Events
+-- 
+--   * **Monitor**: Monitor and take action.
+--   * **Start**: Start the transport process.
+--   * **Stop**: Stop the transport process.
+--   * **Pickup**: Pickup cargo.
+--   * **Load**: Load the cargo.
+--   * **Loaded**: Flag that the cargo is loaded.
+--   * **Deploy**: Deploy cargo to a location.
+--   * **Unload**: Unload the cargo.
+--   * **Unloaded**: Flag that the cargo is unloaded.
+--   * **Home**: A Helicopter is going home.
+-- 
+-- ---
+-- 
+-- ## 3. Set the pickup parameters.
+-- 
+-- Several parameters can be set to pickup cargo:
+-- 
+--    * @{#AI_CARGO_DISPATCHER\_HELICOPTER.SetPickupRadius}(): Sets or randomizes the pickup location for the helicopter around the cargo coordinate in a radius defined an outer and optional inner radius. 
+--    * @{#AI_CARGO_DISPATCHER\_HELICOPTER.SetPickupSpeed}(): Set the speed or randomizes the speed in km/h to pickup the cargo.
+-- 
+-- ---   
+--    
+-- ## 4. Set the deploy parameters.
+-- 
+-- Several parameters can be set to deploy cargo:
+-- 
+--    * @{#AI_CARGO_DISPATCHER\_HELICOPTER.SetDeployRadius}(): Sets or randomizes the deploy location for the helicopter around the cargo coordinate in a radius defined an outer and an optional inner radius. 
+--    * @{#AI_CARGO_DISPATCHER\_HELICOPTER.SetDeploySpeed}(): Set the speed or randomizes the speed in km/h to deploy the cargo.
+-- 
+-- ---
+-- 
+-- ## 5. Set the home zone when there isn't any more cargo to pickup.
+-- 
+-- A home zone can be specified to where the Helicopters will move when there isn't any cargo left for pickup.
+-- Use @{#AI_CARGO_DISPATCHER\_HELICOPTER.SetHomeZone}() to specify the home zone.
+-- 
+-- If no home zone is specified, the helicopters will wait near the deploy zone for a new pickup command.   
+-- 
+-- ===
 -- 
 -- @field #AI_CARGO_DISPATCHER_HELICOPTER
 AI_CARGO_DISPATCHER_HELICOPTER = {
@@ -32,9 +93,9 @@ AI_CARGO_DISPATCHER_HELICOPTER = {
 
 --- Creates a new AI_CARGO_DISPATCHER_HELICOPTER object.
 -- @param #AI_CARGO_DISPATCHER_HELICOPTER self
--- @param Core.Set#SET_GROUP SetHelicopter
+-- @param Core.Set#SET_GROUP SetHelicopter The collection of Helicopter @{Group}s.
--- @param Core.Set#SET_CARGO SetCargo
+-- @param Core.Set#SET_CARGO SetCargo The collection of @{Cargo} derived objects.
--- @param Core.Set#SET_ZONE SetDeployZone
+-- @param Core.Set#SET_ZONE SetDeployZone The collection of deploy @{Zone}s, which are used to where the cargo will be deployed by the Helicopters. 
 -- @return #AI_CARGO_DISPATCHER_HELICOPTER
 -- @usage
 -- 
@@ -53,7 +114,7 @@ function AI_CARGO_DISPATCHER_HELICOPTER:New( SetHelicopter, SetCargo, SetDeployZ
   self:SetPickupRadius( 0, 0 )
   self:SetDeployRadius( 0, 0 )
   
-  self:Monitor( 1 )
+  self:__Start( 1 )
 
   return self
 end

Moose Development/Moose/AI/AI_Cargo_Helicopter.lua

@@ -114,6 +114,14 @@ function AI_CARGO_HELICOPTER:New( Helicopter, CargoSet )
   -- @param #number Delay
 
 
+  -- We need to capture the Crash events for the helicopters.
+  -- The helicopter reference is used in the semaphore AI_CARGO_QUEUEU.
+  -- So, we need to unlock this when the helo is not anymore ...
+  Helicopter:HandleEvent( EVENTS.Crash,
+    function( Helicopter, EventData )
+      AI_CARGO_QUEUE[Helicopter] = nil
+    end
+  )
 
   self:SetCarrier( Helicopter )
   
@@ -225,7 +233,7 @@ function AI_CARGO_HELICOPTER:onafterQueue( Helicopter, From, Event, To, Coordina
 
   local HelicopterInZone = false
 
-  if Helicopter and Helicopter:IsAlive() then
+  if Helicopter and Helicopter:IsAlive() == true then
     
     local Distance = Coordinate:DistanceFromPointVec2( Helicopter:GetCoordinate() )
     
@@ -283,6 +291,8 @@ function AI_CARGO_HELICOPTER:onafterQueue( Helicopter, From, Event, To, Coordina
         self:__Queue( -10, Coordinate )
       end
     end
+  else
+    AI_CARGO_QUEUE[Helicopter] = nil
   end
 end
 

Moose Development/Moose/Core/Set.lua

@@ -76,10 +76,35 @@ SET_BASE = {
 function SET_BASE:New( Database )
 
   -- Inherits from BASE
-  local self = BASE:Inherit( self, BASE:New() ) -- Core.Set#SET_BASE
+  local self = BASE:Inherit( self, FSM:New() ) -- Core.Set#SET_BASE
   
   self.Database = Database
 
+  self:SetStartState( "Started" )
+  
+  --- Added Handler OnAfter for SET_BASE
+  -- @function [parent=#SET_BASE] OnAfterAdded
+  -- @param #SET_BASE self
+  -- @param #string From
+  -- @param #string Event
+  -- @param #string To
+  -- @param #string ObjectName The name of the object.
+  -- @param Object The object.
+  
+  
+  self:AddTransition( "*",  "Added", "*" )
+  
+  --- Removed Handler OnAfter for SET_BASE
+  -- @function [parent=#SET_BASE] OnAfterRemoved
+  -- @param #SET_BASE self
+  -- @param #string From
+  -- @param #string Event
+  -- @param #string To
+  -- @param #string ObjectName The name of the object.
+  -- @param Object The object.
+  
+  self:AddTransition( "*",  "Removed", "*" )
+
   self.YieldInterval = 10
   self.TimeInterval = 0.001
 
@@ -148,7 +173,8 @@ end
 --- Removes a @{Base#BASE} object from the @{Set#SET_BASE} and derived classes, based on the Object Name.
 -- @param #SET_BASE self
 -- @param #string ObjectName
-function SET_BASE:Remove( ObjectName )
+-- @param NoTriggerEvent (optional) When `true`, the :Remove() method will not trigger a **Removed** event.
+function SET_BASE:Remove( ObjectName, NoTriggerEvent )
   self:F2( { ObjectName = ObjectName } )
 
   local Object = self.Set[ObjectName]
@@ -161,9 +187,11 @@ function SET_BASE:Remove( ObjectName )
         break
       end
     end
-    
+    -- When NoTriggerEvent is true, then no Removed event will be triggered.
+    if not NoTriggerEvent then
+      self:Removed( ObjectName, Object )
+    end
   end
-  
 end
 
 
@@ -177,10 +205,12 @@ function SET_BASE:Add( ObjectName, Object )
 
   -- Ensure that the existing element is removed from the Set before a new one is inserted to the Set
   if self.Set[ObjectName] then
-    self:Remove( ObjectName )
+    self:Remove( ObjectName, true )
   end
   self.Set[ObjectName] = Object
   table.insert( self.Index, ObjectName )
+  
+  self:Added( ObjectName, Object )
 end
 
 --- Adds a @{Base#BASE} object in the @{Set#SET_BASE}, using the Object Name as the index.
@@ -425,7 +455,7 @@ end
 -- @param #SET_BASE self
 -- @param Core.Event#EVENTDATA Event
 function SET_BASE:_EventOnDeadOrCrash( Event )
-  self:F3( { Event } )
+  self:F( { Event } )
 
   if Event.IniDCSUnit then
     local ObjectName, Object = self:FindInDatabase( Event )
@@ -675,6 +705,52 @@ end
 --   * @{#SET_GROUP.ForEachGroupPartlyInZone}: Iterate the SET_GROUP and call an iterator function for each **alive** GROUP presence partly in a @{Zone}, providing the GROUP and optional parameters to the called function.
 --   * @{#SET_GROUP.ForEachGroupNotInZone}: Iterate the SET_GROUP and call an iterator function for each **alive** GROUP presence not in a @{Zone}, providing the GROUP and optional parameters to the called function.
 --
+--
+-- ## 5. SET_GROUP trigger events on the GROUP objects.
+-- 
+-- The SET is derived from the FSM class, which provides extra capabilities to track the contents of the GROUP objects in the SET_GROUP.
+-- 
+-- ### 5.1. When a GROUP object crashes or is dead, the SET_GROUP will trigger a **Dead** event.
+-- 
+-- You can handle the event using the OnBefore and OnAfter event handlers. 
+-- The event handlers need to have the paramters From, Event, To, GroupObject.
+-- The GroupObject is the GROUP object that is dead and within the SET_GROUP, and is passed as a parameter to the event handler.
+-- See the following example:
+-- 
+--        -- Create the SetCarrier SET_GROUP collection.
+--
+--        local SetHelicopter = SET_GROUP:New():FilterPrefixes( "Helicopter" ):FilterStart()
+-- 
+--        -- Put a Dead event handler on SetCarrier, to ensure that when a carrier is destroyed, that all internal parameters are reset.
+--
+--        function SetHelicopter:OnAfterDead( From, Event, To, GroupObject )
+--          self:F( { GroupObject = GroupObject:GetName() } )
+--        end
+-- 
+-- While this is a good example, there is a catch.
+-- Imageine you want to execute the code above, the the self would need to be from the object declared outside (above) the OnAfterDead method.
+-- So, the self would need to contain another object. Fortunately, this can be done, but you must use then the **`.`** notation for the method.
+-- See the modified example:
+-- 
+--        -- Now we have a constructor of the class AI_CARGO_DISPATCHER, that receives the SetHelicopter as a parameter.
+--        -- Within that constructor, we want to set an enclosed event handler OnAfterDead for SetHelicopter.
+--        -- But within the OnAfterDead method, we want to refer to the self variable of the AI_CARGO_DISPATCHER.
+-- 
+--        function AI_CARGO_DISPATCHER:New( SetCarrier, SetCargo, SetDeployZones )
+--         
+--          local self = BASE:Inherit( self, FSM:New() ) -- #AI_CARGO_DISPATCHER
+-- 
+--          -- Put a Dead event handler on SetCarrier, to ensure that when a carrier is destroyed, that all internal parameters are reset.
+--          -- Note the "." notation, and the explicit declaration of SetHelicopter, which would be using the ":" notation the implicit self variable declaration.
+--
+--          function SetHelicopter.OnAfterDead( SetHelicopter, From, Event, To, GroupObject )
+--            SetHelicopter:F( { GroupObject = GroupObject:GetName() } )
+--            self.PickupCargo[GroupObject] = nil  -- So here I clear the PickupCargo table entry of the self object AI_CARGO_DISPATCHER.
+--            self.CarrierHome[GroupObject] = nil
+--          end
+--        
+--        end
+-- 
 -- ===
 -- @field #SET_GROUP SET_GROUP 
 SET_GROUP = {
@@ -946,7 +1022,7 @@ end
 -- @param #SET_GROUP self
 -- @param Core.Event#EVENTDATA Event
 function SET_GROUP:_EventOnDeadOrCrash( Event )
-  self:F3( { Event } )
+  self:F( { Event } )
 
   if Event.IniDCSUnit then
     local ObjectName, Object = self:FindInDatabase( Event )
@@ -1409,6 +1485,59 @@ do -- SET_UNIT
   -- 
   --   * @{#SET_UNIT.GetTypeNames}(): Retrieve the type names of the @{Unit}s in the SET, delimited by a comma.
   -- 
+  -- ## 4. SET_UNIT iterators
+  -- 
+  -- Once the filters have been defined and the SET_UNIT has been built, you can iterate the SET_UNIT with the available iterator methods.
+  -- The iterator methods will walk the SET_UNIT set, and call for each element within the set a function that you provide.
+  -- The following iterator methods are currently available within the SET_UNIT:
+  -- 
+  --   * @{#SET_UNIT.ForEachUnit}: Calls a function for each alive group it finds within the SET_UNIT.
+  --   * @{#SET_UNIT.ForEachUnitInZone}: Iterate the SET_UNIT and call an iterator function for each **alive** UNIT object presence completely in a @{Zone}, providing the UNIT object and optional parameters to the called function.
+  --   * @{#SET_UNIT.ForEachUnitNotInZone}: Iterate the SET_UNIT and call an iterator function for each **alive** UNIT object presence not in a @{Zone}, providing the UNIT object and optional parameters to the called function.
+  --
+  -- ## 5. SET_UNIT trigger events on the UNIT objects.
+  -- 
+  -- The SET is derived from the FSM class, which provides extra capabilities to track the contents of the UNIT objects in the SET_UNIT.
+  -- 
+  -- ### 5.1. When a UNIT object crashes or is dead, the SET_UNIT will trigger a **Dead** event.
+  -- 
+  -- You can handle the event using the OnBefore and OnAfter event handlers. 
+  -- The event handlers need to have the paramters From, Event, To, GroupObject.
+  -- The GroupObject is the UNIT object that is dead and within the SET_UNIT, and is passed as a parameter to the event handler.
+  -- See the following example:
+  -- 
+  --        -- Create the SetCarrier SET_UNIT collection.
+  --
+  --        local SetHelicopter = SET_UNIT:New():FilterPrefixes( "Helicopter" ):FilterStart()
+  -- 
+  --        -- Put a Dead event handler on SetCarrier, to ensure that when a carrier unit is destroyed, that all internal parameters are reset.
+  --
+  --        function SetHelicopter:OnAfterDead( From, Event, To, UnitObject )
+  --          self:F( { UnitObject = UnitObject:GetName() } )
+  --        end
+  -- 
+  -- While this is a good example, there is a catch.
+  -- Imageine you want to execute the code above, the the self would need to be from the object declared outside (above) the OnAfterDead method.
+  -- So, the self would need to contain another object. Fortunately, this can be done, but you must use then the **`.`** notation for the method.
+  -- See the modified example:
+  -- 
+  --        -- Now we have a constructor of the class AI_CARGO_DISPATCHER, that receives the SetHelicopter as a parameter.
+  --        -- Within that constructor, we want to set an enclosed event handler OnAfterDead for SetHelicopter.
+  --        -- But within the OnAfterDead method, we want to refer to the self variable of the AI_CARGO_DISPATCHER.
+  -- 
+  --        function ACLASS:New( SetCarrier, SetCargo, SetDeployZones )
+  --         
+  --          local self = BASE:Inherit( self, FSM:New() ) -- #AI_CARGO_DISPATCHER
+  -- 
+  --          -- Put a Dead event handler on SetCarrier, to ensure that when a carrier is destroyed, that all internal parameters are reset.
+  --          -- Note the "." notation, and the explicit declaration of SetHelicopter, which would be using the ":" notation the implicit self variable declaration.
+  --
+  --          function SetHelicopter.OnAfterDead( SetHelicopter, From, Event, To, UnitObject )
+  --            SetHelicopter:F( { UnitObject = UnitObject:GetName() } )
+  --            self.array[UnitObject] = nil  -- So here I clear the array table entry of the self object ACLASS.
+  --          end
+  --        
+  --        end
   -- ===
   -- @field #SET_UNIT SET_UNIT
   SET_UNIT = {
@@ -1650,6 +1779,8 @@ do -- SET_UNIT
     return self
   end
 
+  
+  
   --- Handles the Database to check on an event (birth) that the Object was added in the Database.
   -- This is required, because sometimes the _DATABASE birth event gets called later than the SET_BASE birth event!
   -- @param #SET_UNIT self