Merge branch 'develop'

Warehouse v0.6.1

Moose Development/Moose/AI/AI_A2A.lua

@@ -400,7 +400,6 @@ end
 -- @param #string Event The Event string.
 -- @param #string To The To State string.
 function AI_A2A:onafterStart( Controllable, From, Event, To )
-  self:F2()
 
   self:__Status( 10 ) -- Check status status every 30 seconds.
   
@@ -423,8 +422,6 @@ end
 --- @param #AI_A2A self
 function AI_A2A:onafterStatus()
 
-  self:F( " Checking Status" )
-
   if self.Controllable and self.Controllable:IsAlive() then
   
     local RTB = false
@@ -452,7 +449,7 @@ function AI_A2A:onafterStatus()
 
     if not self:Is( "Fuel" ) and not self:Is( "Home" ) then
       local Fuel = self.Controllable:GetFuelMin()
-      self:F({Fuel=Fuel})
+      self:F({Fuel=Fuel, PatrolFuelThresholdPercentage=self.PatrolFuelThresholdPercentage})
       if Fuel < self.PatrolFuelThresholdPercentage then
         if self.TankerName then
           self:E( self.Controllable:GetName() .. " is out of fuel: " .. Fuel .. " ... Refuelling at Tanker!" )

Moose Development/Moose/AI/AI_A2A_Cap.lua

@@ -282,13 +282,14 @@ function AI_A2A_CAP:New( AICap, PatrolZone, PatrolFloorAltitude, PatrolCeilingAl
 end
 
 --- onafter State Transition for Event Patrol.
--- @param #AI_A2A_GCI self
+-- @param #AI_A2A_CAP self
 -- @param Wrapper.Group#GROUP AICap The AI Group managed by the FSM.
 -- @param #string From The From State string.
 -- @param #string Event The Event string.
 -- @param #string To The To State string.
 function AI_A2A_CAP:onafterStart( AICap, From, Event, To )
 
+  self:GetParent( self ).onafterStart( self, AICap, From, Event, To )
   AICap:HandleEvent( EVENTS.Takeoff, nil, self )
 
 end

Moose Development/Moose/AI/AI_A2A_Dispatcher.lua

@@ -993,6 +993,7 @@ do -- AI_A2A_DISPATCHER
     
     self:HandleEvent( EVENTS.Crash, self.OnEventCrashOrDead )
     self:HandleEvent( EVENTS.Dead, self.OnEventCrashOrDead )
+    --self:HandleEvent( EVENTS.RemoveUnit, self.OnEventCrashOrDead )
     
     self:HandleEvent( EVENTS.Land )
     self:HandleEvent( EVENTS.EngineShutdown )
@@ -2364,7 +2365,7 @@ do -- AI_A2A_DISPATCHER
   --   A2ADispatcher = AI_A2A_DISPATCHER:New( Detection )  
   --   
   --   -- Now Setup the default fuel treshold.
-  --   A2ADispatcher:SetDefaultRefuelThreshold( 0.30 ) -- Go RTB when only 30% of fuel remaining in the tank.
+  --   A2ADispatcher:SetDefaultFuelThreshold( 0.30 ) -- Go RTB when only 30% of fuel remaining in the tank.
   --   
   function AI_A2A_DISPATCHER:SetDefaultFuelThreshold( FuelThreshold )
     
@@ -2406,7 +2407,7 @@ do -- AI_A2A_DISPATCHER
   --   A2ADispatcher = AI_A2A_DISPATCHER:New( Detection )  
   --   
   --   -- Now Setup the default fuel treshold.
-  --   A2ADispatcher:SetDefaultRefuelThreshold( 0.30 ) -- Go RTB when only 30% of fuel remaining in the tank.
+  --   A2ADispatcher:SetDefaultFuelThreshold( 0.30 ) -- Go RTB when only 30% of fuel remaining in the tank.
   --   
   --   -- Now Setup the default tanker.
   --   A2ADispatcher:SetDefaultTanker( "Tanker" ) -- The group name of the tanker is "Tanker" in the Mission Editor.
@@ -2548,8 +2549,12 @@ do -- AI_A2A_DISPATCHER
         local SquadronOverhead = Squadron.Overhead or self.DefenderDefault.Overhead
         
         local DefenderSize = Defender:GetInitialSize()
-        DefenderCount = DefenderCount + DefenderSize / SquadronOverhead
-        self:F( "Defender Group Name: " .. Defender:GetName() .. ", Size: " .. DefenderSize )
+        if DefenderSize then
+          DefenderCount = DefenderCount + DefenderSize / SquadronOverhead
+          self:F( "Defender Group Name: " .. Defender:GetName() .. ", Size: " .. DefenderSize )
+        else
+          DefenderCount = 0
+        end
       end
     end
 
@@ -2991,6 +2996,8 @@ do -- AI_A2A_DISPATCHER
 
     local Report = REPORT:New( "\nTactical Overview" )
 
+    local DefenderGroupCount = 0
+
     -- Now that all obsolete tasks are removed, loop through the detected targets.
     for DetectedItemID, DetectedItem in pairs( Detection:GetDetectedItems() ) do
     
@@ -3028,16 +3035,19 @@ do -- AI_A2A_DISPATCHER
         for Defender, DefenderTask in pairs( self:GetDefenderTasks() ) do
           local Defender = Defender -- Wrapper.Group#GROUP
            if DefenderTask.Target and DefenderTask.Target.Index == DetectedItem.Index then
-             local Fuel = Defender:GetFuelMin() * 100
-             local Damage = Defender:GetLife() / Defender:GetLife0() * 100
-             Report:Add( string.format( "   - %s ( %s - %s ): ( #%d ) F: %3d, D:%3d - %s", 
-                                        Defender:GetName(), 
-                                        DefenderTask.Type, 
-                                        DefenderTask.Fsm:GetState(), 
-                                        Defender:GetSize(), 
-                                        Fuel,
-                                        Damage, 
-                                        Defender:HasTask() == true and "Executing" or "Idle" ) )
+             if Defender:IsAlive() then
+               DefenderGroupCount = DefenderGroupCount + 1
+               local Fuel = Defender:GetFuelMin() * 100
+               local Damage = Defender:GetLife() / Defender:GetLife0() * 100
+               Report:Add( string.format( "   - %s ( %s - %s ): ( #%d ) F: %3d, D:%3d - %s", 
+                                          Defender:GetName(), 
+                                          DefenderTask.Type, 
+                                          DefenderTask.Fsm:GetState(), 
+                                          Defender:GetSize(), 
+                                          Fuel,
+                                          Damage, 
+                                          Defender:HasTask() == true and "Executing" or "Idle" ) )
+             end
            end
         end
       end
@@ -3050,20 +3060,23 @@ do -- AI_A2A_DISPATCHER
         TaskCount = TaskCount + 1
         local Defender = Defender -- Wrapper.Group#GROUP
         if not DefenderTask.Target then
-          local DefenderHasTask = Defender:HasTask()
-          local Fuel = Defender:GetFuelMin() * 100
-          local Damage = Defender:GetLife() / Defender:GetLife0() * 100
-          Report:Add( string.format( "   - %s ( %s - %s ): ( #%d ) F: %3d, D:%3d - %s", 
-                                     Defender:GetName(), 
-                                     DefenderTask.Type, 
-                                     DefenderTask.Fsm:GetState(), 
-                                     Defender:GetSize(),
-                                     Fuel,
-                                     Damage, 
-                                     Defender:HasTask() == true and "Executing" or "Idle" ) )
+          if Defender:IsAlive() then
+            local DefenderHasTask = Defender:HasTask()
+            local Fuel = Defender:GetFuelMin() * 100
+            local Damage = Defender:GetLife() / Defender:GetLife0() * 100
+            DefenderGroupCount = DefenderGroupCount + 1
+            Report:Add( string.format( "   - %s ( %s - %s ): ( #%d ) F: %3d, D:%3d - %s", 
+                                       Defender:GetName(), 
+                                       DefenderTask.Type, 
+                                       DefenderTask.Fsm:GetState(), 
+                                       Defender:GetSize(),
+                                       Fuel,
+                                       Damage, 
+                                       Defender:HasTask() == true and "Executing" or "Idle" ) )
+          end
         end
       end
-      Report:Add( string.format( "\n - %d Tasks", TaskCount ) )
+      Report:Add( string.format( "\n - %d Tasks - %d Defender Groups", TaskCount, DefenderGroupCount ) )
   
       self:F( Report:Text( "\n" ) )
       trigger.action.outText( Report:Text( "\n" ), 25 )
@@ -3556,23 +3569,23 @@ do
 
     -- Setup squadrons
     
-    self:F( { Airbases = AirbaseNames  } )
+    self:I( { Airbases = AirbaseNames  } )
 
-    self:F( "Defining Templates for Airbases ..." )    
+    self:I( "Defining Templates for Airbases ..." )    
     for AirbaseID, AirbaseName in pairs( AirbaseNames ) do
       local Airbase = _DATABASE:FindAirbase( AirbaseName ) -- Wrapper.Airbase#AIRBASE
       local AirbaseName = Airbase:GetName()
       local AirbaseCoord = Airbase:GetCoordinate()
       local AirbaseZone = ZONE_RADIUS:New( "Airbase", AirbaseCoord:GetVec2(), 3000 )
       local Templates = nil
-      self:F( { Airbase = AirbaseName } )    
+      self:I( { Airbase = AirbaseName } )    
       for TemplateID, Template in pairs( self.Templates:GetSet() ) do
         local Template = Template -- Wrapper.Group#GROUP
         local TemplateCoord = Template:GetCoordinate()
         if AirbaseZone:IsVec2InZone( TemplateCoord:GetVec2() ) then
           Templates = Templates or {}
           table.insert( Templates, Template:GetName() )
-          self:F( { Template = Template:GetName() } )
+          self:I( { Template = Template:GetName() } )
         end
       end
       if Templates then
@@ -3588,13 +3601,13 @@ do
     self.CAPTemplates:FilterPrefixes( CapPrefixes )
     self.CAPTemplates:FilterOnce()
     
-    self:F( "Setting up CAP ..." )    
+    self:I( "Setting up CAP ..." )    
     for CAPID, CAPTemplate in pairs( self.CAPTemplates:GetSet() ) do
       local CAPZone = ZONE_POLYGON:New( CAPTemplate:GetName(), CAPTemplate )
       -- Now find the closest airbase from the ZONE (start or center)
       local AirbaseDistance = 99999999
       local AirbaseClosest = nil -- Wrapper.Airbase#AIRBASE
-      self:F( { CAPZoneGroup = CAPID } )    
+      self:I( { CAPZoneGroup = CAPID } )    
       for AirbaseID, AirbaseName in pairs( AirbaseNames ) do
         local Airbase = _DATABASE:FindAirbase( AirbaseName ) -- Wrapper.Airbase#AIRBASE
         local AirbaseName = Airbase:GetName()
@@ -3602,7 +3615,7 @@ do
         local Squadron = self.DefenderSquadrons[AirbaseName]
         if Squadron then
           local Distance = AirbaseCoord:Get2DDistance( CAPZone:GetCoordinate() )
-          self:F( { AirbaseDistance = Distance } )    
+          self:I( { AirbaseDistance = Distance } )    
           if Distance < AirbaseDistance then
             AirbaseDistance = Distance
             AirbaseClosest = Airbase
@@ -3610,7 +3623,7 @@ do
         end
       end
       if AirbaseClosest then
-        self:F( { CAPAirbase = AirbaseClosest:GetName() } )    
+        self:I( { CAPAirbase = AirbaseClosest:GetName() } )    
         self:SetSquadronCap( AirbaseClosest:GetName(), CAPZone, 6000, 10000, 500, 800, 800, 1200, "RADIO" )
         self:SetSquadronCapInterval( AirbaseClosest:GetName(), CapLimit, 300, 600, 1 )
       end          
@@ -3618,14 +3631,14 @@ do
 
     -- Setup GCI.
     -- GCI is setup for all Squadrons.
-    self:F( "Setting up GCI ..." )    
+    self:I( "Setting up GCI ..." )    
     for AirbaseID, AirbaseName in pairs( AirbaseNames ) do
       local Airbase = _DATABASE:FindAirbase( AirbaseName ) -- Wrapper.Airbase#AIRBASE
       local AirbaseName = Airbase:GetName()
       local Squadron = self.DefenderSquadrons[AirbaseName]
       self:F( { Airbase = AirbaseName } )    
       if Squadron then
-        self:F( { GCIAirbase = AirbaseName } )    
+        self:I( { GCIAirbase = AirbaseName } )    
         self:SetSquadronGci( AirbaseName, 800, 1200 )
       end
     end
@@ -3634,6 +3647,7 @@ do
     
     self:HandleEvent( EVENTS.Crash, self.OnEventCrashOrDead )
     self:HandleEvent( EVENTS.Dead, self.OnEventCrashOrDead )
+    --self:HandleEvent( EVENTS.RemoveUnit, self.OnEventCrashOrDead )
     
     self:HandleEvent( EVENTS.Land )
     self:HandleEvent( EVENTS.EngineShutdown )

Moose Development/Moose/AI/AI_A2A_Gci.lua

@@ -290,6 +290,7 @@ end
 -- @param #string To The To State string.
 function AI_A2A_GCI:onafterStart( AIIntercept, From, Event, To )
 
+  self:GetParent( self ).onafterStart( self, AIIntercept, From, Event, To )
   AIIntercept:HandleEvent( EVENTS.Takeoff, nil, self )
 
 end

Moose Development/Moose/AI/AI_Cargo.lua

@@ -0,0 +1,486 @@
+--- **AI** -- (R2.4) - Models the intelligent transportation of infantry and other cargo.
+--
+-- ===
+-- 
+-- ### Author: **FlightControl**
+-- 
+-- ===       
+--
+-- @module AI.AI_Cargo
+-- @image Cargo.JPG
+
+--- @type AI_CARGO
+-- @extends Core.Fsm#FSM_CONTROLLABLE
+
+
+--- Base class for the dynamic cargo handling capability for AI groups.
+-- 
+-- Carriers can be mobilized to intelligently transport infantry and other cargo within the simulation.
+-- The AI_CARGO module uses the @{Cargo.Cargo} capabilities within the MOOSE framework.
+-- CARGO derived objects must be declared within the mission to make the AI_CARGO object recognize the cargo.
+-- Please consult the @{Cargo.Cargo} module for more information. 
+-- 
+-- The derived classes from this module are:
+-- 
+--    * @{AI.AI_Cargo_APC} - Cargo transportation using APCs and other vehicles between zones.
+--    * @{AI.AI_Cargo_Helicopter} - Cargo transportation using helicopters between zones.
+--    * @{AI.AI_Cargo_Airplane} - Cargo transportation using airplanes to and from airbases.
+--    
+-- @field #AI_CARGO
+AI_CARGO = {
+  ClassName = "AI_CARGO",
+  Coordinate = nil, -- Core.Point#COORDINATE,
+  Carrier_Cargo = {},
+}
+
+--- Creates a new AI_CARGO object.
+-- @param #AI_CARGO self
+-- @param Wrapper.Group#GROUP Carrier
+-- @param Core.Set#SET_CARGO CargoSet
+-- @param #number CombatRadius
+-- @return #AI_CARGO
+function AI_CARGO:New( Carrier, CargoSet )
+
+  local self = BASE:Inherit( self, FSM_CONTROLLABLE:New( Carrier ) ) -- #AI_CARGO
+
+  self.CargoSet = CargoSet -- Core.Set#SET_CARGO
+  self.CargoCarrier = Carrier -- Wrapper.Group#GROUP
+
+  self:SetStartState( "Unloaded" )
+  
+  self:AddTransition( "Unloaded", "Pickup", "*" )
+  self:AddTransition( "Loaded", "Deploy", "*" )
+  
+  self:AddTransition( "*", "Load", "Boarding" )
+  self:AddTransition( { "Boarding", "Loaded" }, "Board", "Boarding" )
+  self:AddTransition( "Boarding", "Loaded", "Boarding" )
+  self:AddTransition( "Boarding", "PickedUp", "Loaded" )
+  
+  self:AddTransition( "Loaded", "Unload", "Unboarding" )
+  self:AddTransition( "Unboarding", "Unboard", "Unboarding" )
+  self:AddTransition( "Unboarding", "Unloaded", "Unboarding" )
+  self:AddTransition( "Unboarding", "Deployed", "Unloaded" )
+  
+  --- Pickup Handler OnBefore for AI_CARGO
+  -- @function [parent=#AI_CARGO] OnBeforePickup
+  -- @param #AI_CARGO self
+  -- @param #string From
+  -- @param #string Event
+  -- @param #string To
+  -- @param Core.Point#COORDINATE Coordinate
+  -- @param #number Speed Speed in km/h. Default is 50% of max possible speed the group can do. 
+  -- @return #boolean
+  
+  --- Pickup Handler OnAfter for AI_CARGO
+  -- @function [parent=#AI_CARGO] OnAfterPickup
+  -- @param #AI_CARGO self
+  -- @param #string From
+  -- @param #string Event
+  -- @param #string To
+  -- @param Core.Point#COORDINATE Coordinate
+  -- @param #number Speed Speed in km/h. Default is 50% of max possible speed the group can do.
+  
+  --- Pickup Trigger for AI_CARGO
+  -- @function [parent=#AI_CARGO] Pickup
+  -- @param #AI_CARGO self
+  -- @param Core.Point#COORDINATE Coordinate
+  -- @param #number Speed Speed in km/h. Default is 50% of max possible speed the group can do.
+  
+  --- Pickup Asynchronous Trigger for AI_CARGO
+  -- @function [parent=#AI_CARGO] __Pickup
+  -- @param #AI_CARGO self
+  -- @param #number Delay
+  -- @param Core.Point#COORDINATE Coordinate Pickup place. If not given, loading starts at the current location.
+  -- @param #number Speed Speed in km/h. Default is 50% of max possible speed the group can do.
+  
+  --- Deploy Handler OnBefore for AI_CARGO
+  -- @function [parent=#AI_CARGO] OnBeforeDeploy
+  -- @param #AI_CARGO self
+  -- @param #string From
+  -- @param #string Event
+  -- @param #string To
+  -- @param Core.Point#COORDINATE Coordinate
+  -- @param #number Speed Speed in km/h. Default is 50% of max possible speed the group can do.
+  -- @return #boolean
+  
+  --- Deploy Handler OnAfter for AI_CARGO
+  -- @function [parent=#AI_CARGO] OnAfterDeploy
+  -- @param #AI_CARGO self
+  -- @param #string From
+  -- @param #string Event
+  -- @param #string To
+  -- @param Core.Point#COORDINATE Coordinate
+  -- @param #number Speed Speed in km/h. Default is 50% of max possible speed the group can do.
+  
+  --- Deploy Trigger for AI_CARGO
+  -- @function [parent=#AI_CARGO] Deploy
+  -- @param #AI_CARGO self
+  -- @param Core.Point#COORDINATE Coordinate
+  -- @param #number Speed Speed in km/h. Default is 50% of max possible speed the group can do.
+  
+  --- Deploy Asynchronous Trigger for AI_CARGO
+  -- @function [parent=#AI_CARGO] __Deploy
+  -- @param #AI_CARGO self
+  -- @param #number Delay
+  -- @param Core.Point#COORDINATE Coordinate
+  -- @param #number Speed Speed in km/h. Default is 50% of max possible speed the group can do.
+
+  
+  --- Loaded Handler OnAfter for AI_CARGO
+  -- @function [parent=#AI_CARGO] OnAfterLoaded
+  -- @param #AI_CARGO self
+  -- @param Wrapper.Group#GROUP Carrier
+  -- @param #string From
+  -- @param #string Event
+  -- @param #string To
+  
+  --- Unloaded Handler OnAfter for AI_CARGO
+  -- @function [parent=#AI_CARGO] OnAfterUnloaded
+  -- @param #AI_CARGO self
+  -- @param Wrapper.Group#GROUP Carrier
+  -- @param #string From
+  -- @param #string Event
+  -- @param #string To
+  
+  for _, CarrierUnit in pairs( Carrier:GetUnits() ) do
+    local CarrierUnit = CarrierUnit -- Wrapper.Unit#UNIT
+    CarrierUnit:SetCargoBayWeightLimit()
+  end
+  
+  self.Transporting = false
+  self.Relocating = false
+  
+  return self
+end
+
+
+
+function AI_CARGO:IsTransporting()
+
+  return self.Transporting == true
+end
+
+function AI_CARGO:IsRelocating()
+
+  return self.Relocating == true
+end
+
+
+--- On after Pickup event.
+-- @param #AI_CARGO self
+-- @param Wrapper.Group#GROUP APC
+-- @param From
+-- @param Event
+-- @param To
+-- @param Core.Point#COORDINATE Coordinate of the pickup point.
+-- @param #number Speed Speed in km/h to drive to the pickup coordinate. Default is 50% of max possible speed the unit can go.
+-- @param #number Height Height in meters to move to the home coordinate.
+-- @param 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.
+function AI_CARGO:onafterPickup( APC, From, Event, To, Coordinate, Speed, Height, PickupZone )
+
+  self.Transporting = false
+  self.Relocating = true
+  
+end
+
+
+--- On after Deploy event.
+-- @param #AI_CARGO self
+-- @param Wrapper.Group#GROUP APC
+-- @param From
+-- @param Event
+-- @param To
+-- @param Core.Point#COORDINATE Coordinate Deploy place.
+-- @param #number Speed Speed in km/h to drive to the depoly coordinate. Default is 50% of max possible speed the unit can go.
+-- @param #number Height Height in meters to move to the deploy coordinate.
+-- @param Core.Zone#ZONE DeployZone The zone where the cargo will be deployed.
+function AI_CARGO:onafterDeploy( APC, From, Event, To, Coordinate, Speed, Height, DeployZone )
+
+  self.Relocating = false
+  self.Transporting = true
+  
+end
+
+--- On before Load event.
+-- @param #AI_CARGO self
+-- @param Wrapper.Group#GROUP Carrier
+-- @param #string From From state.
+-- @param #string Event Event.
+-- @param #string To To state.
+-- @param 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.
+function AI_CARGO:onbeforeLoad( Carrier, From, Event, To, PickupZone )
+  self:F( { Carrier, From, Event, To } )
+
+  local Boarding = false
+
+  local LoadInterval = 5
+  local LoadDelay = 0
+  local Carrier_List = {}
+  local Carrier_Weight = {}
+
+  if Carrier and Carrier:IsAlive() then
+    self.Carrier_Cargo = {}
+    for _, CarrierUnit in pairs( Carrier:GetUnits() ) do
+      local CarrierUnit = CarrierUnit -- Wrapper.Unit#UNIT
+      
+      local CargoBayFreeWeight = CarrierUnit:GetCargoBayFreeWeight()
+      self:F({CargoBayFreeWeight=CargoBayFreeWeight})
+      
+      Carrier_List[#Carrier_List+1] = CarrierUnit
+      Carrier_Weight[CarrierUnit] = CargoBayFreeWeight
+    end
+
+    local Carrier_Count = #Carrier_List
+    local Carrier_Index = 1
+      
+    local Loaded = false
+
+    for _, Cargo in UTILS.spairs( self.CargoSet:GetSet(), function( t, a, b ) return t[a]:GetWeight() > t[b]:GetWeight() end ) do
+      local Cargo = Cargo -- Cargo.Cargo#CARGO
+
+      self:F( { IsUnLoaded = Cargo:IsUnLoaded(), IsDeployed = Cargo:IsDeployed(), Cargo:GetName(), Carrier:GetName() } )
+
+      -- Try all Carriers, but start from the one according the Carrier_Index
+      for Carrier_Loop = 1, #Carrier_List do
+
+        local CarrierUnit = Carrier_List[Carrier_Index] -- Wrapper.Unit#UNIT
+
+        -- This counters loop through the available Carriers.
+        Carrier_Index = Carrier_Index + 1
+        if Carrier_Index > Carrier_Count then
+          Carrier_Index = 1
+        end
+        
+        if Cargo:IsUnLoaded() and not Cargo:IsDeployed() then
+          if Cargo:IsInLoadRadius( CarrierUnit:GetCoordinate() ) then
+            self:F( { "In radius", CarrierUnit:GetName() } )
+            
+            local CargoWeight = Cargo:GetWeight()
+  
+            -- Only when there is space within the bay to load the next cargo item!
+            if Carrier_Weight[CarrierUnit] > CargoWeight then --and CargoBayFreeVolume > CargoVolume then
+              Carrier:RouteStop()
+              --Cargo:Ungroup()
+              Cargo:__Board( -LoadDelay, CarrierUnit )
+              LoadDelay = LoadDelay + Cargo:GetCount() * LoadInterval
+              self:__Board( LoadDelay, Cargo, CarrierUnit, PickupZone )
+  
+              -- So now this CarrierUnit has Cargo that is being loaded.
+              -- This will be used further in the logic to follow and to check cargo status.
+              self.Carrier_Cargo[Cargo] = CarrierUnit
+              Boarding = true
+              Carrier_Weight[CarrierUnit] = Carrier_Weight[CarrierUnit] - CargoWeight
+              Loaded = true
+              
+              -- Ok, we loaded a cargo, now we can stop the loop.
+              break
+            end
+          end
+        end
+        
+      end
+      
+      
+    end
+    
+    if not Loaded == true then
+      -- No loading happened, so we need to pickup something else.
+      self.Relocating = false
+    end
+  end
+
+  return Boarding
+  
+end
+
+--- On after Board event.
+-- @param #AI_CARGO self
+-- @param Wrapper.Group#GROUP Carrier
+-- @param #string From From state.
+-- @param #string Event Event.
+-- @param #string To To state.
+-- @param Cargo.Cargo#CARGO Cargo Cargo object.
+-- @param Wrapper.Unit#UNIT CarrierUnit
+-- @param 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.
+function AI_CARGO:onafterBoard( Carrier, From, Event, To, Cargo, CarrierUnit, PickupZone )
+  self:F( { Carrier, From, Event, To, Cargo, CarrierUnit:GetName() } )
+
+  if Carrier and Carrier:IsAlive() then
+    self:F({ IsLoaded = Cargo:IsLoaded(), Cargo:GetName(), Carrier:GetName() } )
+    if not Cargo:IsLoaded() then
+      self:__Board( -10, Cargo, CarrierUnit, PickupZone )
+      return
+    end
+  end
+
+  self:__Loaded( 0.1, Cargo, CarrierUnit, PickupZone )
+  
+end
+
+--- On after Loaded event.
+-- @param #AI_CARGO self
+-- @param Wrapper.Group#GROUP Carrier
+-- @param #string From From state.
+-- @param #string Event Event.
+-- @param #string To To state.
+-- @return #boolean Cargo loaded.
+-- @param 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.
+function AI_CARGO:onafterLoaded( Carrier, From, Event, To, Cargo, PickupZone )
+  self:F( { Carrier, From, Event, To } )
+
+  local Loaded = true
+
+  if Carrier and Carrier:IsAlive() then
+    for Cargo, CarrierUnit in pairs( self.Carrier_Cargo ) do
+      local Cargo = Cargo -- Cargo.Cargo#CARGO
+      self:F( { IsLoaded = Cargo:IsLoaded(), IsDestroyed = Cargo:IsDestroyed(), Cargo:GetName(), Carrier:GetName() } )
+      if not Cargo:IsLoaded() and not Cargo:IsDestroyed() then
+        Loaded = false
+      end
+    end
+  end
+  
+  if Loaded then
+    self:__PickedUp( 0.1, PickupZone )
+  end
+  
+end
+
+--- On after PickedUp event.
+-- @param #AI_CARGO self
+-- @param Wrapper.Group#GROUP Carrier
+-- @param #string From From state.
+-- @param #string Event Event.
+-- @param #string To To state.
+-- @param 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.
+function AI_CARGO:onafterPickedUp( Carrier, From, Event, To, PickupZone )
+  self:F( { Carrier, From, Event, To } )
+
+  Carrier:RouteResume()
+
+  local HasCargo = false
+  if Carrier and Carrier :IsAlive() then
+    for Cargo, CarrierUnit in pairs( self.Carrier_Cargo ) do
+      HasCargo = true
+      break
+    end
+  end
+
+  self.Relocating = false
+  if HasCargo then
+    self.Transporting = true
+  end
+  
+end
+
+
+
+
+--- On after Unload event.
+-- @param #AI_CARGO self
+-- @param Wrapper.Group#GROUP Carrier
+-- @param #string From From state.
+-- @param #string Event Event.
+-- @param #string To To state.
+-- @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 AI_CARGO:onafterUnload( Carrier, From, Event, To, DeployZone )
+  self:F( { Carrier, From, Event, To, DeployZone } )
+
+  local UnboardInterval = 10
+  local UnboardDelay = 10
+
+  if Carrier and Carrier:IsAlive() then
+    for _, CarrierUnit in pairs( Carrier:GetUnits() ) do
+      local CarrierUnit = CarrierUnit -- Wrapper.Unit#UNIT
+      Carrier:RouteStop()
+      for _, Cargo in pairs( CarrierUnit:GetCargo() ) do
+        self:F( { Cargo = Cargo:GetName(), Isloaded = Cargo:IsLoaded() } )
+        if Cargo:IsLoaded() then
+          Cargo:__UnBoard( UnboardDelay )
+          UnboardDelay = UnboardDelay + Cargo:GetCount() * UnboardInterval
+          Cargo:SetDeployed( true )
+          self:__Unboard( UnboardDelay, Cargo, CarrierUnit, DeployZone )
+        end 
+      end
+    end
+  end
+  
+end
+
+--- On after Unboard event.
+-- @param #AI_CARGO self
+-- @param Wrapper.Group#GROUP Carrier
+-- @param #string From From state.
+-- @param #string Event Event.
+-- @param #string To To state.
+-- @param #string Cargo.Cargo#CARGO Cargo Cargo object.
+-- @param Core.Zone#ZONE DeployZone The zone wherein the cargo is deployed. This can be any zone type, like a ZONE, ZONE_GROUP, ZONE_AIRBASE.
+function AI_CARGO:onafterUnboard( Carrier, From, Event, To, Cargo, CarrierUnit, DeployZone )
+  self:F( { Carrier, From, Event, To, Cargo:GetName() } )
+
+  if Carrier and Carrier:IsAlive() then
+    if not Cargo:IsUnLoaded() then
+      self:__Unboard( 10, Cargo, CarrierUnit, DeployZone ) 
+      return
+    end
+  end
+
+  self:Unloaded( Cargo, CarrierUnit, DeployZone )
+  
+end
+
+--- On after Unloaded event.
+-- @param #AI_CARGO self
+-- @param Wrapper.Group#GROUP Carrier
+-- @param #string From From state.
+-- @param #string Event Event.
+-- @param #string To To state.
+-- @param #string Cargo.Cargo#CARGO Cargo Cargo object.
+-- @param #boolean Deployed Cargo is deployed.
+-- @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 AI_CARGO:onafterUnloaded( Carrier, From, Event, To, Cargo, CarrierUnit, DeployZone )
+  self:F( { Carrier, From, Event, To, Cargo:GetName(), DeployZone = DeployZone } )
+
+  local AllUnloaded = true
+
+  --Cargo:Regroup()
+
+  if Carrier and Carrier:IsAlive() then
+    for _, CarrierUnit in pairs( Carrier:GetUnits() ) do
+      local CarrierUnit = CarrierUnit -- Wrapper.Unit#UNIT
+      local IsEmpty = CarrierUnit:IsCargoEmpty()
+      self:I({ IsEmpty = IsEmpty })
+      if not IsEmpty then
+        AllUnloaded = false
+        break
+      end
+    end
+    
+    if AllUnloaded == true then
+      if DeployZone == true then
+        self.Carrier_Cargo = {}
+      end
+      self.CargoCarrier = Carrier
+    end
+  end
+
+  if AllUnloaded == true then
+    self:__Deployed( 5, DeployZone )
+  end
+  
+end
+
+--- On after Deployed event.
+-- @param #AI_CARGO self
+-- @param Wrapper.Group#GROUP Carrier
+-- @param #string From From state.
+-- @param #string Event Event.
+-- @param #string To To state.
+-- @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 AI_CARGO:onafterDeployed( Carrier, From, Event, To, DeployZone )
+  self:F( { Carrier, From, Event, To, DeployZone = DeployZone } )
+
+    self.Transporting = false
+
+end
+

Moose Development/Moose/AI/AI_Cargo_APC.lua

@@ -1,4 +1,4 @@
---- **AI** -- (R2.3) - Models the intelligent transportation of infantry and other cargo.
+--- **AI** -- (R2.4) - Models the intelligent transportation of infantry and other cargo.
 --
 -- ===
 -- 
@@ -10,23 +10,26 @@
 -- @image AI_Cargo_Dispatching_For_APC.JPG
 
 --- @type AI_CARGO_APC
--- @extends Core.Fsm#FSM_CONTROLLABLE
+-- @extends AI.AI_Cargo#AI_CARGO
 
 
---- Brings a dynamic cargo handling capability for AI groups.
+--- 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 module uses the @{Cargo} capabilities within the MOOSE framework.
--- CARGO derived objects must be declared within the mission to make the AI\_CARGO\APC object recognize the cargo.
--- Please consult the @{Cargo} module for more information. 
+-- 
+-- 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 range.
--- The boarding or loading range is specified when the cargo is created in the simulation, and therefore, this range depends on the type of cargo
--- and the specified boarding range.
+-- 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.
 -- 
--- ## Enemies nearby.
+-- ## **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.
@@ -34,13 +37,17 @@
 -- 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 range needs to be specified in meters at the @{#AI_CARGO_APC.New}() method. 
--- This combat range will trigger the unboarding of troops when enemies are within the combat range around the APCs.
--- During my tests, I've noticed that there is a balance between ensuring that the infantry is within sufficient hit range (effectiveness) versus
+-- 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 range of 350 meters to 500 meters has been proven to be the most effective and efficient.
+-- A combat radius of 350 meters to 500 meters has been proven to be the most effective and efficient.
 -- 
--- ## Infantry health.
+-- 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.
@@ -74,34 +81,18 @@
 AI_CARGO_APC = {
   ClassName = "AI_CARGO_APC",
   Coordinate = nil, -- Core.Point#COORDINATE,
-  APC_Cargo = {},
 }
 
 --- Creates a new AI_CARGO_APC object.
 -- @param #AI_CARGO_APC self
--- @param Wrapper.Group#GROUP APC
--- @param Core.Set#SET_CARGO CargoSet
--- @param #number CombatRadius
+-- @param Wrapper.Group#GROUP APC The carrier APC group.
+-- @param Core.Set#SET_CARGO CargoSet The set of cargo to be transported.
+-- @param #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 #AI_CARGO_APC
 function AI_CARGO_APC:New( APC, CargoSet, CombatRadius )
 
-  local self = BASE:Inherit( self, FSM_CONTROLLABLE:New() ) -- #AI_CARGO_APC
+  local self = BASE:Inherit( self, AI_CARGO:New( APC, CargoSet ) ) -- #AI_CARGO_APC
 
-  self.CargoSet = CargoSet -- Core.Set#SET_CARGO
-  self.CombatRadius = CombatRadius
-
-  self:SetStartState( "Unloaded" ) 
-  
-  self:AddTransition( "Unloaded", "Pickup", "*" )
-  self:AddTransition( "Loaded", "Deploy", "*" )
-  
-  self:AddTransition( "*", "Load", "Boarding" )
-  self:AddTransition( "Boarding", "Board", "Boarding" )
-  self:AddTransition( "Boarding", "Loaded", "Loaded" )
-  self:AddTransition( "Loaded", "Unload", "Unboarding" )
-  self:AddTransition( "Unboarding", "Unboard", "Unboarding" )
-  self:AddTransition( { "Unboarding", "Unloaded" }, "Unloaded", "Unloaded" )
-  
   self:AddTransition( "*", "Monitor", "*" )
   self:AddTransition( "*", "Follow", "Following" )
   self:AddTransition( "*", "Guard", "Unloaded" )
@@ -109,87 +100,9 @@ function AI_CARGO_APC:New( APC, CargoSet, CombatRadius )
   
   self:AddTransition( "*", "Destroyed", "Destroyed" )
 
-
-  --- Pickup Handler OnBefore for AI_CARGO_APC
-  -- @function [parent=#AI_CARGO_APC] OnBeforePickup
-  -- @param #AI_CARGO_APC self
-  -- @param #string From
-  -- @param #string Event
-  -- @param #string To
-  -- @param Core.Point#COORDINATE Coordinate
-  -- @return #boolean
-  
-  --- Pickup Handler OnAfter for AI_CARGO_APC
-  -- @function [parent=#AI_CARGO_APC] OnAfterPickup
-  -- @param #AI_CARGO_APC self
-  -- @param #string From
-  -- @param #string Event
-  -- @param #string To
-  -- @param Core.Point#COORDINATE Coordinate
-  
-  --- Pickup Trigger for AI_CARGO_APC
-  -- @function [parent=#AI_CARGO_APC] Pickup
-  -- @param #AI_CARGO_APC self
-  -- @param Core.Point#COORDINATE Coordinate
-  
-  --- Pickup Asynchronous Trigger for AI_CARGO_APC
-  -- @function [parent=#AI_CARGO_APC] __Pickup
-  -- @param #AI_CARGO_APC self
-  -- @param #number Delay
-  -- @param Core.Point#COORDINATE Coordinate
-  
-  --- Deploy Handler OnBefore for AI_CARGO_APC
-  -- @function [parent=#AI_CARGO_APC] OnBeforeDeploy
-  -- @param #AI_CARGO_APC self
-  -- @param #string From
-  -- @param #string Event
-  -- @param #string To
-  -- @param Core.Point#COORDINATE Coordinate
-  -- @return #boolean
-  
-  --- Deploy Handler OnAfter for AI_CARGO_APC
-  -- @function [parent=#AI_CARGO_APC] OnAfterDeploy
-  -- @param #AI_CARGO_APC self
-  -- @param #string From
-  -- @param #string Event
-  -- @param #string To
-  -- @param Core.Point#COORDINATE Coordinate
-  
-  --- Deploy Trigger for AI_CARGO_APC
-  -- @function [parent=#AI_CARGO_APC] Deploy
-  -- @param #AI_CARGO_APC self
-  -- @param Core.Point#COORDINATE Coordinate
-  
-  --- Deploy Asynchronous Trigger for AI_CARGO_APC
-  -- @function [parent=#AI_CARGO_APC] __Deploy
-  -- @param #AI_CARGO_APC self
-  -- @param Core.Point#COORDINATE Coordinate
-  -- @param #number Delay
-
-  
-  --- Loaded Handler OnAfter for AI_CARGO_APC
-  -- @function [parent=#AI_CARGO_APC] OnAfterLoaded
-  -- @param #AI_CARGO_APC self
-  -- @param Wrapper.Group#GROUP APC
-  -- @param #string From
-  -- @param #string Event
-  -- @param #string To
-  
-  --- Unloaded Handler OnAfter for AI_CARGO_APC
-  -- @function [parent=#AI_CARGO_APC] OnAfterUnloaded
-  -- @param #AI_CARGO_APC self
-  -- @param Wrapper.Group#GROUP APC
-  -- @param #string From
-  -- @param #string Event
-  -- @param #string To
-  
-
-  self:__Monitor( 1 )
-
+  self:SetCombatRadius( CombatRadius )
 
   self:SetCarrier( APC )
-  self.Transporting = false
-  self.Relocating = false
   
   return self
 end
@@ -214,7 +127,7 @@ function AI_CARGO_APC:SetCarrier( CargoCarrier )
     if AICargoTroops then
       self:F({})
       if not AICargoTroops:Is( "Loaded" ) then
-        -- There are enemies within combat range. Unload the CargoCarrier.
+        -- There are enemies within combat radius. Unload the CargoCarrier.
         AICargoTroops:Destroyed()
       end
     end
@@ -226,7 +139,7 @@ function AI_CARGO_APC:SetCarrier( CargoCarrier )
     if AICargoTroops then
       self:F( { OnHitLoaded = AICargoTroops:Is( "Loaded" ) } )
       if AICargoTroops:Is( "Loaded" ) or AICargoTroops:Is( "Boarding" ) then
-        -- There are enemies within combat range. Unload the CargoCarrier.
+        -- There are enemies within combat radius. Unload the CargoCarrier.
         AICargoTroops:Unload( false )
       end
     end
@@ -243,17 +156,7 @@ function AI_CARGO_APC:SetCarrier( CargoCarrier )
 end
 
 
-function AI_CARGO_APC:IsTransporting()
-
-  return self.Transporting == true
-end
-
-function AI_CARGO_APC:IsRelocating()
-
-  return self.Relocating == true
-end
-
---- Find a free Carrier within a range.
+--- Find a free Carrier within a radius.
 -- @param #AI_CARGO_APC self
 -- @param Core.Point#COORDINATE Coordinate
 -- @param #number Radius
@@ -278,6 +181,30 @@ function AI_CARGO_APC:FindCarrier( Coordinate, Radius )
 
 end
 
+--- 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.
+-- @param #AI_CARGO_APC self
+-- @param #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 #AI_CARGO_APC
+-- @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 )
+function AI_CARGO_APC:SetCombatRadius( CombatRadius )
+
+  self.CombatRadius = CombatRadius or 0
+
+  if self.CombatRadius > 0 then
+    self:__Monitor( -5 )
+  end
+
+  return self
+end
 
 
 --- Follow Infantry to the Carrier.
@@ -335,41 +262,49 @@ function AI_CARGO_APC:FollowToCarrier( Me, APCUnit, CargoGroup )
 end
 
 
---- @param #AI_CARGO_APC self
+--- On after Monitor event.
+-- @param #AI_CARGO_APC self
 -- @param Wrapper.Group#GROUP APC
+-- @param #string From From state.
+-- @param #string Event Event.
+-- @param #string To To state.
 function AI_CARGO_APC:onafterMonitor( APC, From, Event, To )
-  self:F( { APC, From, Event, To } )
+  self:F( { APC, From, Event, To, IsTransporting = self:IsTransporting() } )
 
-  if APC and APC:IsAlive() then
-    if self.CarrierCoordinate then
-      if self:IsRelocating() == true then
-        local Coordinate = APC:GetCoordinate()
-        self.Zone:Scan( { Object.Category.UNIT } )
-        if self.Zone:IsAllInZoneOfCoalition( self.Coalition ) then
-          if self:Is( "Unloaded" ) or self:Is( "Following" ) then
-            -- There are no enemies within combat range. Load the CargoCarrier.
-            self:Load()
-          end
-        else
-          if self:Is( "Loaded" ) then
-            -- There are enemies within combat range. Unload the CargoCarrier.
-            self:__Unload( 1, false )
-          else
-            if self:Is( "Unloaded" ) then
-              self:Follow()
+  if self.CombatRadius > 0 then
+    if APC and APC:IsAlive() then
+      if self.CarrierCoordinate then
+        if self:IsTransporting() == true then
+          local Coordinate = APC:GetCoordinate()
+          self.Zone:Scan( { Object.Category.UNIT } )
+          if self.Zone:IsAllInZoneOfCoalition( self.Coalition ) then
+            if self:Is( "Unloaded" ) or self:Is( "Following" ) then
+              -- There are no enemies within combat radius. Load the CargoCarrier.
+              self:Load()
             end
-            if self:Is( "Following" ) then
-              for APCUnit, Cargo in pairs( self.APC_Cargo ) do
-                local Cargo = Cargo -- Cargo.Cargo#CARGO
-                if Cargo:IsAlive() then
-                  if not Cargo:IsNear( APCUnit, 40 ) then
-                    APCUnit:RouteStop()
-                    self.CarrierStopped = true
-                  else
-                    if self.CarrierStopped then
-                      if Cargo:IsNear( APCUnit, 25 ) then
-                        APCUnit:RouteResume()
-                        self.CarrierStopped = nil
+          else
+            if self:Is( "Loaded" ) then
+              -- There are enemies within combat radius. Unload the CargoCarrier.
+              self:__Unload( 1 )
+            else
+              if self:Is( "Unloaded" ) then
+                self:Follow()
+              end
+              self:F( "I am here" .. self:GetCurrentState() )
+              if self:Is( "Following" ) then
+                for Cargo, APCUnit in pairs( self.Carrier_Cargo ) do
+                  local Cargo = Cargo -- Cargo.Cargo#CARGO
+                  local APCUnit = APCUnit -- Wrapper.Unit#UNIT
+                  if Cargo:IsAlive() then
+                    if not Cargo:IsNear( APCUnit, 40 ) then
+                      APCUnit:RouteStop()
+                      self.CarrierStopped = true
+                    else
+                      if self.CarrierStopped then
+                        if Cargo:IsNear( APCUnit, 25 ) then
+                          APCUnit:RouteResume()
+                          self.CarrierStopped = nil
+                        end
                       end
                     end
                   end
@@ -378,180 +313,29 @@ function AI_CARGO_APC:onafterMonitor( APC, From, Event, To )
             end
           end
         end
+        
       end
-      
+      self.CarrierCoordinate = APC:GetCoordinate()
     end
-    self.CarrierCoordinate = APC:GetCoordinate()
-  end
   
-  self:__Monitor( -5 )
-
-end
-
-
---- @param #AI_CARGO_APC self
--- @param Wrapper.Group#GROUP APC
-function AI_CARGO_APC:onbeforeLoad( APC, From, Event, To )
-  self:F( { APC, From, Event, To } )
-
-  local Boarding = false
-  self.BoardingCount = 0
-
-  if APC and APC:IsAlive() then
-    self.APC_Cargo = {}
-    for _, APCUnit in pairs( APC:GetUnits() ) do
-      local APCUnit = APCUnit -- Wrapper.Unit#UNIT
-      for _, Cargo in pairs( self.CargoSet:GetSet() ) do
-        local Cargo = Cargo -- Cargo.Cargo#CARGO
-        self:F( { IsUnLoaded = Cargo:IsUnLoaded(), IsDeployed = Cargo:IsDeployed(), Cargo:GetName(), APC:GetName() } )
-        if Cargo:IsUnLoaded() and not Cargo:IsDeployed() then
-          if Cargo:IsInLoadRadius( APCUnit:GetCoordinate() ) then
-            self:F( { "In radius", APCUnit:GetName() } )
-            APC:RouteStop()
-            --Cargo:Ungroup()
-            Cargo:Board( APCUnit, 25 )
-            self:__Board( 1, Cargo )
-            Boarding = true
-            
-            -- So now this APCUnit has Cargo that is being loaded.
-            -- This will be used further in the logic to follow and to check cargo status.
-            self.APC_Cargo[APCUnit] = Cargo
-            break
-          end
-        end
-      end
-    end
-  end
-
-  return Boarding
-  
-end
-
---- @param #AI_CARGO_APC self
--- @param Wrapper.Group#GROUP APC
-function AI_CARGO_APC:onafterBoard( APC, From, Event, To, Cargo )
-  self:F( { APC, From, Event, To, Cargo } )
-
-  if APC and APC:IsAlive() then
-    self:F({ IsLoaded = Cargo:IsLoaded(), Cargo:GetName(), APC:GetName() } )
-    if not Cargo:IsLoaded() then
-      self:__Board( 10, Cargo )
-    else
-      self:__Loaded( 1 )
-    end
+    self:__Monitor( -5 )
   end
   
 end
 
---- @param #AI_CARGO_APC self
--- @param Wrapper.Group#GROUP APC
-function AI_CARGO_APC:onbeforeLoaded( APC, From, Event, To )
-  self:F( { APC, From, Event, To } )
-
-  local Loaded = true
-
-  if APC and APC:IsAlive() then
-    for APCUnit, Cargo in pairs( self.APC_Cargo ) do
-      local Cargo = Cargo -- Cargo.Cargo#CARGO
-      self:F( { IsLoaded = Cargo:IsLoaded(), IsDestroyed = Cargo:IsDestroyed(), Cargo:GetName(), APC:GetName() } )
-      if not Cargo:IsLoaded() and not Cargo:IsDestroyed() then
-        Loaded = false
-      end
-    end
-    
-  end
-  
-  if Loaded == true then
-    APC:RouteResume()
-  end
-  
-  return Loaded
-  
-end
-
-
---- @param #AI_CARGO_APC self
--- @param Wrapper.Group#GROUP APC
-function AI_CARGO_APC:onafterUnload( APC, From, Event, To, Deployed )
-  self:F( { APC, From, Event, To, Deployed } )
-
-  if APC and APC:IsAlive() then
-    for _, APCUnit in pairs( APC:GetUnits() ) do
-      local APCUnit = APCUnit -- Wrapper.Unit#UNIT
-      APC:RouteStop()
-      for _, Cargo in pairs( APCUnit:GetCargo() ) do
-        Cargo:UnBoard()
-        self:__Unboard( 10, Cargo, Deployed )
-      end 
-    end
-  end
-  
-end
-
---- @param #AI_CARGO_APC self
--- @param Wrapper.Group#GROUP APC
-function AI_CARGO_APC:onafterUnboard( APC, From, Event, To, Cargo, Deployed )
-  self:F( { APC, From, Event, To, Cargo:GetName() } )
-
-  if APC and APC:IsAlive() then
-    if not Cargo:IsUnLoaded() then
-      self:__Unboard( 10, Cargo, Deployed ) 
-    else
-      self:__Unloaded( 1, Cargo, Deployed )
-    end
-  end
-  
-end
-
---- @param #AI_CARGO_APC self
--- @param Wrapper.Group#GROUP APC
-function AI_CARGO_APC:onbeforeUnloaded( APC, From, Event, To, Cargo, Deployed )
-  self:F( { APC, From, Event, To, Cargo:GetName(), Deployed = Deployed } )
-
-  local AllUnloaded = true
-
-  --Cargo:Regroup()
-
-  if APC and APC:IsAlive() then
-    for _, APCUnit in pairs( APC:GetUnits() ) do
-      local APCUnit = APCUnit -- Wrapper.Unit#UNIT
-      local CargoCheck = self.APC_Cargo[APCUnit]
-      if CargoCheck then
-        self:F( { CargoCheck:GetName(), IsUnLoaded = CargoCheck:IsUnLoaded() } )
-        if CargoCheck:IsUnLoaded() == false then
-          AllUnloaded = false
-          break
-        end
-      end
-    end
-    
-    if AllUnloaded == true then
-      if Deployed == true then
-        for APCUnit, Cargo in pairs( self.APC_Cargo ) do
-          local Cargo = Cargo -- Cargo.Cargo#CARGO
-          Cargo:SetDeployed( true )
-        end
-        self.APC_Cargo = {}
-      end
-      self:Guard()
-      self.CargoCarrier = APC
-    end
-  end
-  
-  self:F( { AllUnloaded = AllUnloaded } )
-  return AllUnloaded
-  
-end
-
-
---- @param #AI_CARGO_APC self
+
+--- On after Follow event.
+-- @param #AI_CARGO_APC self
 -- @param Wrapper.Group#GROUP APC
+-- @param #string From From state.
+-- @param #string Event Event.
+-- @param #string To To state.
 function AI_CARGO_APC:onafterFollow( APC, From, Event, To )
   self:F( { APC, From, Event, To } )
 
   self:F( "Follow" )
   if APC and APC:IsAlive() then
-    for APCUnit, Cargo in pairs( self.APC_Cargo ) do
+    for Cargo, APCUnit in pairs( self.Carrier_Cargo ) do
       local Cargo = Cargo -- Cargo.Cargo#CARGO
       if Cargo:IsUnLoaded() then
         self:FollowToCarrier( self, APCUnit, Cargo )
@@ -565,40 +349,38 @@ end
 
 --- @param #AI_CARGO_APC 
 -- @param Wrapper.Group#GROUP APC
-function AI_CARGO_APC._Pickup( APC, self )
+function AI_CARGO_APC._Pickup( APC, self, Coordinate, Speed, PickupZone )
 
   APC:F( { "AI_CARGO_APC._Pickup:", APC:GetName() } )
 
   if APC:IsAlive() then
-    self:Load()
-    self.Relocating = true
+    self:Load( PickupZone )
   end
 end
 
 
---- @param #AI_CARGO_APC 
--- @param Wrapper.Group#GROUP APC
-function AI_CARGO_APC._Deploy( APC, self )
+function AI_CARGO_APC._Deploy( APC, self, Coordinate, DeployZone )
 
   APC:F( { "AI_CARGO_APC._Deploy:", APC } )
 
   if APC:IsAlive() then
-    self:Unload( true )
-    self.Transporting = false
-    self.Relocating = false
+    self:Unload( DeployZone )
   end
 end
 
 
 
---- @param #AI_CARGO_APC self
+--- On after Pickup event.
+-- @param #AI_CARGO_APC self
 -- @param Wrapper.Group#GROUP APC
 -- @param From
 -- @param Event
 -- @param To
 -- @param Core.Point#COORDINATE Coordinate of the pickup point.
 -- @param #number Speed Speed in km/h to drive to the pickup coordinate. Default is 50% of max possible speed the unit can go.
-function AI_CARGO_APC:onafterPickup( APC, From, Event, To, Coordinate, Speed )
+-- @param #number Height Height in meters to move to the pickup coordinate. This parameter is ignored for APCs.
+-- @param 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.
+function AI_CARGO_APC:onafterPickup( APC, From, Event, To, Coordinate, Speed, Height, PickupZone )
 
   if APC and APC:IsAlive() then
 
@@ -609,7 +391,7 @@ function AI_CARGO_APC:onafterPickup( APC, From, Event, To, Coordinate, Speed )
       
       local Waypoints = APC:TaskGroundOnRoad( Coordinate, _speed, "Line abreast", true )
   
-      local TaskFunction = APC:TaskFunction( "AI_CARGO_APC._Pickup", self )
+      local TaskFunction = APC:TaskFunction( "AI_CARGO_APC._Pickup", self, Coordinate, Speed, PickupZone )
       
       self:F({Waypoints = Waypoints})
       local Waypoint = Waypoints[#Waypoints]
@@ -617,23 +399,26 @@ function AI_CARGO_APC:onafterPickup( APC, From, Event, To, Coordinate, Speed )
     
       APC:Route( Waypoints, 1 ) -- Move after a random seconds to the Route. See the Route method for details.
     else
-      AI_CARGO_APC._Pickup( APC, self )
+      AI_CARGO_APC._Pickup( APC, self, Coordinate, Speed, PickupZone )
     end
-    
-    self.Transporting = true
+
+    self:GetParent( self, AI_CARGO_APC ).onafterPickup( self, APC, From, Event, To, Coordinate, Speed, Height, PickupZone )
   end
   
 end
 
 
---- @param #AI_CARGO_APC self
+--- On after Deploy event.
+-- @param #AI_CARGO_APC self
 -- @param Wrapper.Group#GROUP APC
 -- @param From
 -- @param Event
 -- @param To
--- @param Core.Point#COORDINATE Coordinate
--- @param #number Speed Speed in km/h to drive to the pickup coordinate. Default is 50% of max possible speed the unit can go.
-function AI_CARGO_APC:onafterDeploy( APC, From, Event, To, Coordinate, Speed )
+-- @param Core.Point#COORDINATE Coordinate Deploy place.
+-- @param #number Speed Speed in km/h to drive to the depoly coordinate. Default is 50% of max possible speed the unit can go.
+-- @param #number Height Height in meters to move to the deploy coordinate. This parameter is ignored for APCs.
+-- @param Core.Zone#ZONE DeployZone The zone where the cargo will be deployed.
+function AI_CARGO_APC:onafterDeploy( APC, From, Event, To, Coordinate, Speed, Height, DeployZone )
 
   if APC and APC:IsAlive() then
 
@@ -643,34 +428,55 @@ function AI_CARGO_APC:onafterDeploy( APC, From, Event, To, Coordinate, Speed )
      
     local Waypoints = APC:TaskGroundOnRoad( Coordinate, _speed, "Line abreast", true )
 
-    local TaskFunction = APC:TaskFunction( "AI_CARGO_APC._Deploy", self )
+    local TaskFunction = APC:TaskFunction( "AI_CARGO_APC._Deploy", self, Coordinate, DeployZone )
     
     self:F({Waypoints = Waypoints})
     local Waypoint = Waypoints[#Waypoints]
     APC:SetTaskWaypoint( Waypoint, TaskFunction ) -- Set for the given Route at Waypoint 2 the TaskRouteToZone.
   
     APC:Route( Waypoints, 1 ) -- Move after a random seconds to the Route. See the Route method for details.
+
+    self:GetParent( self, AI_CARGO_APC ).onafterDeploy( self, APC, From, Event, To, Coordinate, Speed, Height, DeployZone )
+
   end
   
 end
 
+--- On after Deployed event.
+-- @param #AI_CARGO_APC self
+-- @param Wrapper.Group#GROUP Carrier
+-- @param #string From From state.
+-- @param #string Event Event.
+-- @param #string To To state.
+-- @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 AI_CARGO_APC:onafterDeployed( APC, From, Event, To, DeployZone )
+  self:F( { APC, From, Event, To, DeployZone = DeployZone } )
 
---- @param #AI_CARGO_APC self
+  self:__Guard( 0.1 )
+
+  self:GetParent( self, AI_CARGO_APC ).onafterDeployed( self, APC, From, Event, To, DeployZone )
+
+end
+
+
+--- On after Home event.
+-- @param #AI_CARGO_APC self
 -- @param Wrapper.Group#GROUP APC
 -- @param From
 -- @param Event
 -- @param To
--- @param Core.Point#COORDINATE Coordinate
+-- @param Core.Point#COORDINATE Coordinate Home place.
 -- @param #number Speed Speed in km/h to drive to the pickup coordinate. Default is 50% of max possible speed the unit can go.
-function AI_CARGO_APC:onafterHome( APC, From, Event, To, Coordinate, Speed )
+-- @param #number Height Height in meters to move to the home coordinate. This parameter is ignored for APCs.
+function AI_CARGO_APC:onafterHome( APC, From, Event, To, Coordinate, Speed, Height, HomeZone )
 
   if APC and APC:IsAlive() ~= nil then
 
     self.RouteHome = true
     
-    local _speed=Speed or APC:GetSpeedMax()*0.5
+    Speed = Speed or APC:GetSpeedMax()*0.5
     
-    local Waypoints = APC:TaskGroundOnRoad( Coordinate, _speed, "Line abreast", true )
+    local Waypoints = APC:TaskGroundOnRoad( Coordinate, Speed, "Line abreast", true )
 
     self:F({Waypoints = Waypoints})
     local Waypoint = Waypoints[#Waypoints]

Moose Development/Moose/AI/AI_Cargo_Airplane.lua

@@ -1,4 +1,4 @@
---- **AI** -- (R2.3) - Models the intelligent transportation of infantry (cargo).
+--- **AI** -- (R2.4) - Models the intelligent transportation of infantry (cargo).
 --
 -- ===
 -- 
@@ -13,108 +13,142 @@
 -- @extends Core.Fsm#FSM_CONTROLLABLE
 
 
---- Implements the transportation of cargo by airplanes.
+--- Brings a dynamic cargo handling capability for an AI airplane group.
+--  
+-- Airplane carrier equipment can be mobilized to intelligently transport infantry and other cargo within the simulation between airbases.
+-- 
+-- The AI_CARGO_AIRPLANE module uses the @{Cargo.Cargo} capabilities within the MOOSE framework.
+-- @{Cargo.Cargo} must be declared within the mission to make AI_CARGO_AIRPLANE recognize the cargo.
+-- Please consult the @{Cargo.Cargo} module for more information. 
+-- 
+-- ## Cargo pickup.
+--  
+-- Using the @{#AI_CARGO_AIRPLANE.Pickup}() method, you are able to direct the helicopters towards a point on the battlefield to board/load the cargo at the specific coordinate. 
+-- Ensure that the landing zone is horizontally flat, and that trees cannot be found in the landing vicinity, or the helicopters won't land or will even crash!
+-- 
+-- ## Cargo deployment.
+--  
+-- Using the @{#AI_CARGO_AIRPLANE.Deploy}() method, you are able to direct the helicopters towards a point on the battlefield to unboard/unload the cargo at the specific coordinate. 
+-- Ensure that the landing zone is horizontally flat, and that trees cannot be found in the landing vicinity, or the helicopters won't land or will even crash!
+-- 
+-- ## Infantry 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, 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 ... 
+-- 
 -- 
 -- @field #AI_CARGO_AIRPLANE
 AI_CARGO_AIRPLANE = {
   ClassName = "AI_CARGO_AIRPLANE",
-  Coordinate = nil -- Core.Point#COORDINATE,
+  Coordinate = nil, -- Core.Point#COORDINATE
 }
 
 --- Creates a new AI_CARGO_AIRPLANE object.
 -- @param #AI_CARGO_AIRPLANE self
--- @param Wrapper.Group#GROUP Airplane
--- @param Core.Set#SET_CARGO CargoSet
+-- @param Wrapper.Group#GROUP Airplane Plane used for transportation of cargo.
+-- @param Core.Set#SET_CARGO CargoSet Cargo set to be transported.
 -- @return #AI_CARGO_AIRPLANE
 function AI_CARGO_AIRPLANE:New( Airplane, CargoSet )
 
-  local self = BASE:Inherit( self, FSM_CONTROLLABLE:New() ) -- #AI_CARGO_AIRPLANE
-
-  self.CargoSet = CargoSet -- Cargo.CargoGroup#CARGO_GROUP
-
-  self:SetStartState( "Unloaded" ) 
-  
-  self:AddTransition( "Unloaded", "Pickup", "*" )
-  self:AddTransition( "Loaded", "Deploy", "*" )
-  
-  self:AddTransition( "Unloaded", "Load", "Boarding" )
-  self:AddTransition( "Boarding", "Board", "Boarding" )
-  self:AddTransition( "Boarding", "Loaded", "Loaded" )
-  self:AddTransition( "Loaded", "Unload", "Unboarding" )
-  self:AddTransition( "Unboarding", "Unboard", "Unboarding" )
-  self:AddTransition( "Unboarding", "Unloaded", "Unloaded" )
+  local self = BASE:Inherit( self, AI_CARGO:New( Airplane, CargoSet ) ) -- #AI_CARGO_AIRPLANE
 
   self:AddTransition( "*", "Landed", "*" )
+  self:AddTransition( "*", "Home" ,  "*" ) 
   
   self:AddTransition( "*", "Destroyed", "Destroyed" )
 
   --- Pickup Handler OnBefore for AI_CARGO_AIRPLANE
   -- @function [parent=#AI_CARGO_AIRPLANE] OnBeforePickup
   -- @param #AI_CARGO_AIRPLANE self
-  -- @param #string From
-  -- @param #string Event
-  -- @param #string To
-  -- @param Wrapper.Airbase#AIRBASE Airbase
+  -- @param Wrapper.Group#GROUP Airplane Cargo transport plane.
+  -- @param #string From From state.
+  -- @param #string Event Event.
+  -- @param #string To To state.
+  -- @param Wrapper.Airbase#AIRBASE Airbase Airbase where troops are picked up.
+  -- @param #number Speed in km/h for travelling to pickup base.
   -- @return #boolean
   
   --- Pickup Handler OnAfter for AI_CARGO_AIRPLANE
   -- @function [parent=#AI_CARGO_AIRPLANE] OnAfterPickup
   -- @param #AI_CARGO_AIRPLANE self
+  -- @param Wrapper.Group#GROUP Airplane Cargo plane.
   -- @param #string From
   -- @param #string Event
   -- @param #string To
-  -- @param Wrapper.Airbase#AIRBASE Airbase
+  -- @param Wrapper.Airbase#AIRBASE Airbase Airbase where troops are picked up.
+  -- @param #number Speed in km/h for travelling to pickup base.
   
   --- Pickup Trigger for AI_CARGO_AIRPLANE
   -- @function [parent=#AI_CARGO_AIRPLANE] Pickup
   -- @param #AI_CARGO_AIRPLANE self
-  -- @param Wrapper.Airbase#AIRBASE Airbase
+  -- @param Wrapper.Airbase#AIRBASE Airbase Airbase where troops are picked up.
+  -- @param #number Speed in km/h for travelling to pickup base.
   
   --- Pickup Asynchronous Trigger for AI_CARGO_AIRPLANE
   -- @function [parent=#AI_CARGO_AIRPLANE] __Pickup
   -- @param #AI_CARGO_AIRPLANE self
-  -- @param #number Delay
-  -- @param Wrapper.Airbase#AIRBASE Airbase
+  -- @param #number Delay Delay in seconds.
+  -- @param Wrapper.Airbase#AIRBASE Airbase Airbase where troops are picked up.
+  -- @param #number Speed in km/h for travelling to pickup base.
   
   --- Deploy Handler OnBefore for AI_CARGO_AIRPLANE
   -- @function [parent=#AI_CARGO_AIRPLANE] OnBeforeDeploy
   -- @param #AI_CARGO_AIRPLANE self
+  -- @param Wrapper.Group#GROUP Airplane Cargo plane.
   -- @param #string From
   -- @param #string Event
   -- @param #string To
-  -- @param Wrapper.Airbase#AIRBASE Airbase
+  -- @param Wrapper.Airbase#AIRBASE Airbase Destination airbase where troops are deployed.
+  -- @param #number Speed Speed in km/h for travelling to deploy base.
   -- @return #boolean
   
   --- Deploy Handler OnAfter for AI_CARGO_AIRPLANE
   -- @function [parent=#AI_CARGO_AIRPLANE] OnAfterDeploy
   -- @param #AI_CARGO_AIRPLANE self
+  -- @param Wrapper.Group#GROUP Airplane Cargo plane.
   -- @param #string From
   -- @param #string Event
   -- @param #string To
-  -- @param Wrapper.Airbase#AIRBASE Airbase
+  -- @param Wrapper.Airbase#AIRBASE Airbase Destination airbase where troops are deployed.
+  -- @param #number Speed Speed in km/h for travelling to deploy base.
   
   --- Deploy Trigger for AI_CARGO_AIRPLANE
   -- @function [parent=#AI_CARGO_AIRPLANE] Deploy
   -- @param #AI_CARGO_AIRPLANE self
-  -- @param Wrapper.Airbase#AIRBASE Airbase
+  -- @param Wrapper.Airbase#AIRBASE Airbase Destination airbase where troops are deployed.
+  -- @param #number Speed Speed in km/h for travelling to deploy base.
   
   --- Deploy Asynchronous Trigger for AI_CARGO_AIRPLANE
   -- @function [parent=#AI_CARGO_AIRPLANE] __Deploy
   -- @param #AI_CARGO_AIRPLANE self
-  -- @param Wrapper.Airbase#AIRBASE Airbase
-  -- @param #number Delay
-
+  -- @param #number Delay Delay in seconds.
+  -- @param Wrapper.Airbase#AIRBASE Airbase Destination airbase where troops are deployed.
+  -- @param #number Speed Speed in km/h for travelling to deploy base.
 
+  --- On after Loaded event, i.e. triggered when the cargo is inside the carrier.
+  -- @function [parent=#AI_CARGO_AIRPLANE] OnAfterLoaded
+  -- @param #AI_CARGO_AIRPLANE self
+  -- @param Wrapper.Group#GROUP Airplane Cargo plane.
+  -- @param From
+  -- @param Event
+  -- @param To
+  
+  -- Set carrier. 
   self:SetCarrier( Airplane )
   
   return self
 end
 
 
---- Set the Carrier.
+--- Set the Carrier (controllable). Also initializes events for carrier and defines the coalition.
 -- @param #AI_CARGO_AIRPLANE self
--- @param Wrapper.Group#GROUP Airplane
--- @return #AI_CARGO_AIRPLANE
+-- @param Wrapper.Group#GROUP Airplane Transport plane.
+-- @return #AI_CARGO_AIRPLANE self
 function AI_CARGO_AIRPLANE:SetCarrier( Airplane )
 
   local AICargo = self
@@ -155,7 +189,8 @@ function AI_CARGO_AIRPLANE:SetCarrier( Airplane )
   
   
   function Airplane:OnEventEngineShutdown( EventData )
-    AICargo:Landed()
+    AICargo.Relocating = false
+    AICargo:Landed( self.Airplane )
   end
   
   self.Coalition = self.Airplane:GetCoalition()
@@ -168,7 +203,7 @@ end
 
 --- Find a free Carrier within a range.
 -- @param #AI_CARGO_AIRPLANE self
-  -- @param Wrapper.Airbase#AIRBASE Airbase
+-- @param Wrapper.Airbase#AIRBASE Airbase
 -- @param #number Radius
 -- @return Wrapper.Group#GROUP NewCarrier
 function AI_CARGO_AIRPLANE:FindCarrier( Coordinate, Radius )
@@ -190,22 +225,24 @@ function AI_CARGO_AIRPLANE:FindCarrier( Coordinate, Radius )
 
 end
 
---- @param #AI_CARGO_AIRPLANE self
--- @param Wrapper.Group#GROUP Airplane
+--- On after "Landed" event. Called on engine shutdown and initiates the pickup mission or unloading event.
+-- @param #AI_CARGO_AIRPLANE self
+-- @param Wrapper.Group#GROUP Airplane Cargo transport plane.
 -- @param From
 -- @param Event
 -- @param To
-  -- @param Wrapper.Airbase#AIRBASE Airbase
--- @param #number Speed
 function AI_CARGO_AIRPLANE:onafterLanded( Airplane, From, Event, To )
 
-  if Airplane and Airplane:IsAlive() then
+  self:F({Airplane, From, Event, To})
 
+  if Airplane and Airplane:IsAlive()~=nil then
+
+    -- Aircraft was sent to this airbase to pickup troops. Initiate loadling.
     if self.RoutePickup == true then
-      self:Load( Airplane:GetPointVec2() )
-      self.RoutePickup = false
+      self:Load( self.PickupZone )
     end
     
+    -- Aircraft was send to this airbase to deploy troops. Initiate unloading.
     if self.RouteDeploy == true then
       self:Unload()
       self.RouteDeploy = false
@@ -216,231 +253,232 @@ function AI_CARGO_AIRPLANE:onafterLanded( Airplane, From, Event, To )
 end
 
 
-
---- @param #AI_CARGO_AIRPLANE self
--- @param Wrapper.Group#GROUP Airplane
--- @param From
--- @param Event
--- @param To
--- @param Wrapper.Airbase#AIRBASE Airbase
--- @param #number Speed
-function AI_CARGO_AIRPLANE:onafterPickup( Airplane, From, Event, To, Airbase, Speed )
+--- On after "Pickup" event. Routes transport to pickup airbase.
+-- @param #AI_CARGO_AIRPLANE self
+-- @param Wrapper.Group#GROUP Airplane Cargo transport plane.
+-- @param #string From From state.
+-- @param #string Event Event.
+-- @param #string To To state.
+-- @param Core.Point#COORDINATE Coordinate
+-- @param #number Speed in km/h for travelling to pickup base.
+-- @param #number Height Height in meters to move to the pickup coordinate.
+-- @param Core.Zone#ZONE_AIRBASE (optional) PickupZone The zone where the cargo will be picked up.
+function AI_CARGO_AIRPLANE:onafterPickup( Airplane, From, Event, To, Coordinate, Speed, Height, PickupZone )
 
   if Airplane and Airplane:IsAlive() then
-    self:Route( Airplane, Airbase, Speed )
-    self.RoutePickup = true
-    self.Airbase = Airbase
+    
+    self.PickupZone = PickupZone
+  
+    -- Get closest airbase of current position.
+    local ClosestAirbase, DistToAirbase=Airplane:GetCoordinate():GetClosestAirbase()
+  
+    -- Two cases. Aircraft spawned in air or at an airbase.
+    if Airplane:InAir() then
+      self.Airbase=nil  --> route will start in air
+    else      
+      self.Airbase=ClosestAirbase
+    end
+    
+    -- Set pickup airbase.
+    local Airbase = PickupZone:GetAirbase()
+    
+    -- Distance from closest to pickup airbase ==> we need to know if we are already at the pickup airbase. 
+    local Dist = Airbase:GetCoordinate():Get2DDistance(ClosestAirbase:GetCoordinate())
+    --env.info("Distance closest to pickup airbase = "..Dist)
+    
+    if Airplane:InAir() or Dist>500 then
+    
+      -- Route aircraft to pickup airbase.
+      self:Route( Airplane, Airbase, Speed, Height ) 
+          
+      -- Set airbase as starting point in the next Route() call.
+      self.Airbase = Airbase
+      
+      -- Aircraft is on a pickup mission.
+      self.RoutePickup = true
+      
+    else
+    
+      -- We are already at the right airbase ==> Landed ==> triggers loading of troops. Is usually called at engine shutdown event.
+      self.RoutePickup=true
+      self:Landed()
+      
+    end
+
+    self:GetParent( self, AI_CARGO_AIRPLANE ).onafterPickup( self, Airplane, From, Event, To, Coordinate, Speed, Height, PickupZone )
+    
   end
+
   
 end
 
+--- On after Depoly event. Routes plane to the airbase where the troops are deployed.
+-- @param #AI_CARGO_AIRPLANE self
+-- @param Wrapper.Group#GROUP Airplane Cargo transport plane.
+-- @param #string From From state.
+-- @param #string Event Event.
+-- @param #string To To state.
+-- @param Core.Point#COORDINATE Coordinate
+-- @param #number Speed in km/h for travelling to pickup base.
+-- @param #number Height Height in meters to move to the home coordinate.
+-- @param Core.Zone#ZONE_AIRBASE DeployZone The zone where the cargo will be deployed.
+function AI_CARGO_AIRPLANE:onafterDeploy( Airplane, From, Event, To, Coordinate, Speed, Height, DeployZone )
 
---- @param #AI_CARGO_AIRPLANE self
--- @param Wrapper.Group#GROUP Airplane
--- @param From
--- @param Event
--- @param To
--- @param Wrapper.Airbase#AIRBASE Airbase
--- @param #number Speed
-function AI_CARGO_AIRPLANE:onafterDeploy( Airplane, From, Event, To, Airbase, Speed )
-
-  if Airplane and Airplane:IsAlive() then
-    self:Route( Airplane, Airbase, Speed )
+  if Airplane and Airplane:IsAlive()~=nil then
+    
+    local Airbase = DeployZone:GetAirbase()
+    
+    -- Activate uncontrolled airplane.
+    if Airplane:IsAlive()==false then
+      Airplane:SetCommand({id = 'Start', params = {}})
+    end
+    
+    -- Route to destination airbase.
+    self:Route( Airplane, Airbase, Speed, Height )
+    
+    -- Aircraft is on a depoly mission.
     self.RouteDeploy = true
+    
+    -- Set destination airbase for next :Route() command.
     self.Airbase = Airbase
+    
+    self:GetParent( self, AI_CARGO_AIRPLANE ).onafterDeploy( self, Airplane, From, Event, To, Coordinate, Speed, Height, DeployZone )
   end
   
 end
 
 
---- @param #AI_CARGO_AIRPLANE self
--- @param Wrapper.Group#GROUP Airplane
-function AI_CARGO_AIRPLANE:onafterLoad( Airplane, From, Event, To, Coordinate )
+--- On after Unload event. Cargo is beeing unloaded, i.e. the unboarding process is started.
+-- @param #AI_CARGO_AIRPLANE self
+-- @param Wrapper.Group#GROUP Airplane Cargo transport plane.
+-- @param #string From From state.
+-- @param #string Event Event.
+-- @param #string To To state.
+function AI_CARGO_AIRPLANE:onafterUnload( Airplane, From, Event, To, DeployZone )
+
+  local UnboardInterval = 10
+  local UnboardDelay = 10
 
   if Airplane and Airplane:IsAlive() then
-  
-    for _, Cargo in pairs( self.CargoSet:GetSet() ) do
-      if Cargo:IsInLoadRadius( Coordinate ) then
-        self:__Board( 5 )
-        Cargo:Board( Airplane, 25 )
-        self.Cargo = Cargo
-        break
+    for _, AirplaneUnit in pairs( Airplane:GetUnits() ) do
+      local Cargos = AirplaneUnit:GetCargo()
+      for CargoID, Cargo in pairs( Cargos ) do
+      
+        local Angle = 180
+        local CargoCarrierHeading = Airplane:GetHeading() -- Get Heading of object in degrees.
+        local CargoDeployHeading = ( ( CargoCarrierHeading + Angle ) >= 360 ) and ( CargoCarrierHeading + Angle - 360 ) or ( CargoCarrierHeading + Angle )
+        self:T( { CargoCarrierHeading, CargoDeployHeading } )
+        local CargoDeployCoordinate = Airplane:GetPointVec2():Translate( 150, CargoDeployHeading )
+      
+         Cargo:__UnBoard( UnboardDelay, CargoDeployCoordinate )
+         UnboardDelay = UnboardDelay + UnboardInterval
+         Cargo:SetDeployed( true )
+         self:__Unboard( UnboardDelay, Cargo, AirplaneUnit, DeployZone ) 
       end
     end
   end
   
 end
 
---- @param #AI_CARGO_AIRPLANE self
--- @param Wrapper.Group#GROUP Airplane
-function AI_CARGO_AIRPLANE:onafterBoard( Airplane, From, Event, To )
-
-  if Airplane and Airplane:IsAlive() then
-    self:F({ IsLoaded = self.Cargo:IsLoaded() } )
-    if not self.Cargo:IsLoaded() then
-      self:__Board( 10 )
-    else
-      self:__Loaded( 1 )
-    end
-  end
-  
-end
-
---- @param #AI_CARGO_AIRPLANE self
--- @param Wrapper.Group#GROUP Airplane
-function AI_CARGO_AIRPLANE:onafterLoaded( Airplane, From, Event, To )
-
-  if Airplane and Airplane:IsAlive() then
-  end
-  
-end
 
 
---- @param #AI_CARGO_AIRPLANE self
--- @param Wrapper.Group#GROUP Airplane
-function AI_CARGO_AIRPLANE:onafterUnload( Airplane, From, Event, To )
 
-  if Airplane and Airplane:IsAlive() then
-    self.Cargo:UnBoard()
-    self:__Unboard( 10 ) 
-  end
-  
-end
-
---- @param #AI_CARGO_AIRPLANE self
--- @param Wrapper.Group#GROUP Airplane
-function AI_CARGO_AIRPLANE:onafterUnboard( Airplane, From, Event, To )
-
-  if Airplane and Airplane:IsAlive() then
-    if not self.Cargo:IsUnLoaded() then
-      self:__Unboard( 10 ) 
-    else
-      self:__Unloaded( 1 )
-    end
-  end
-  
-end
-
---- @param #AI_CARGO_AIRPLANE self
--- @param Wrapper.Group#GROUP Airplane
-function AI_CARGO_AIRPLANE:onafterUnloaded( Airplane, From, Event, To )
-
-  if Airplane and Airplane:IsAlive() then
-    self.Airplane = Airplane
-  end
-  
-end
-
-
---- @param #AI_CARGO_AIRPLANE self
--- @param Wrapper.Group#GROUP Airplane
--- @param Wrapper.Airbase#AIRBASE Airbase
--- @param #number Speed
-function AI_CARGO_AIRPLANE:Route( Airplane, Airbase, Speed )
+--- Route the airplane from one airport or it's current position to another airbase.
+-- @param #AI_CARGO_AIRPLANE self
+-- @param Wrapper.Group#GROUP Airplane Airplane group to be routed.
+-- @param Wrapper.Airbase#AIRBASE Airbase Destination airbase.
+-- @param #number Speed Speed in km/h. Default is 80% of max possible speed the group can do.
+-- @param #number Height Height in meters to move to the Airbase.
+-- @param #boolean Uncontrolled If true, spawn group in uncontrolled state.
+function AI_CARGO_AIRPLANE:Route( Airplane, Airbase, Speed, Height, Uncontrolled )
 
   if Airplane and Airplane:IsAlive() then
 
-    local PointVec3 = Airplane:GetPointVec3()
-  
-    local Takeoff = SPAWN.Takeoff.Hot
+    -- Set takeoff type.
+    local Takeoff = SPAWN.Takeoff.Cold
     
+    -- Get template of group.
     local Template = Airplane:GetTemplate()
-  
-    if Template then
+    
+    -- Nil check
+    if Template==nil then
+      return
+    end
 
-      local Points = {}
-      
-      if self.Airbase then
-  
-        local FromWaypoint = Template.route.points[1] 
+    -- Waypoints of the route.
+    local Points={}
     
-        -- These are only for ships.
-        FromWaypoint.linkUnit = nil
-        FromWaypoint.helipadId = nil
-        FromWaypoint.airdromeId = nil
+    -- To point.
+    local AirbasePointVec2 = Airbase:GetPointVec2()
+    local ToWaypoint = AirbasePointVec2:WaypointAir(
+      POINT_VEC3.RoutePointAltType.BARO,
+      "Land",
+      "Landing", 
+      Speed or Airplane:GetSpeedMax()*0.8
+    )    
+    ToWaypoint["airdromeId"]   = Airbase:GetID()
+    ToWaypoint["speed_locked"] = true
     
-        local AirbaseID = self.Airbase:GetID()
-        local AirbaseCategory = self.Airbase:GetDesc().category
-        
-        FromWaypoint.airdromeId = AirbaseID
-    
-        FromWaypoint.alt = 0
-                
-        FromWaypoint.type = GROUPTEMPLATE.Takeoff[Takeoff][1] -- type
-        FromWaypoint.action = GROUPTEMPLATE.Takeoff[Takeoff][2] -- action
-        
-    
-        -- Translate the position of the Group Template to the Vec3.
-        for UnitID = 1, #Template.units do
-          self:T( 'Before Translation SpawnTemplate.units['..UnitID..'].x = ' .. Template.units[UnitID].x .. ', SpawnTemplate.units['..UnitID..'].y = ' .. Template.units[UnitID].y )
-    
-          -- These cause a lot of confusion.
-          local UnitTemplate = Template.units[UnitID]
-    
-          UnitTemplate.parking = 15
-          UnitTemplate.parking_id = "1"
-          UnitTemplate.alt = 0
-    
-          local SX = UnitTemplate.x
-          local SY = UnitTemplate.y 
-          local BX = FromWaypoint.x
-          local BY = FromWaypoint.y
-          local TX = PointVec3.x + ( SX - BX )
-          local TY = PointVec3.z + ( SY - BY )
-          
-          UnitTemplate.x = TX
-          UnitTemplate.y = TY
-          
-          self:T( 'After Translation SpawnTemplate.units['..UnitID..'].x = ' .. UnitTemplate.x .. ', SpawnTemplate.units['..UnitID..'].y = ' .. UnitTemplate.y )
-        end
-        
-        FromWaypoint.x = PointVec3.x
-        FromWaypoint.y = PointVec3.z
 
-        Points[#Points+1] = FromWaypoint
-      else
-        
-        local GroupPoint = Airplane:GetVec2()
-        local GroupVelocity = Airplane:GetUnit(1):GetDesc().speedMax
+    -- If self.Airbase~=nil then group is currently at an airbase, where it should be respawned.        
+    if self.Airbase then
     
-        local FromWaypoint = {}
-        FromWaypoint.x = GroupPoint.x
-        FromWaypoint.y = GroupPoint.y
-        FromWaypoint.type = "Turning Point"
-        FromWaypoint.action = "Turning Point"
-        FromWaypoint.speed = GroupVelocity
+      -- Second point of the route. First point is done in RespawnAtCurrentAirbase() routine.
+      Template.route.points[2] = ToWaypoint
+    
+      -- Respawn group at the current airbase.
+      Airplane:RespawnAtCurrentAirbase(Template, Takeoff, Uncontrolled)
+      
+    else
+  
+      -- From point.
+      local GroupPoint = Airplane:GetVec2()
+      local FromWaypoint = {}
+      FromWaypoint.x      = GroupPoint.x
+      FromWaypoint.y      = GroupPoint.y
+      FromWaypoint.type   = "Turning Point"
+      FromWaypoint.action = "Turning Point"
+      FromWaypoint.speed  = Airplane:GetSpeedMax()*0.8
+ 
+      -- The two route points. 
+      Points[1] = FromWaypoint
+      Points[2] = ToWaypoint
 
-        Points[#Points+1] = FromWaypoint
-      end
-      
-      local AirbasePointVec2 = Airbase:GetPointVec2()
-      local ToWaypoint = AirbasePointVec2:WaypointAir(
-        POINT_VEC3.RoutePointAltType.BARO,
-        "Land",
-        "Landing", 
-        Speed or Airplane:GetUnit(1):GetDesc().speedMax
-      )
-      
-      ToWaypoint["airdromeId"] = Airbase:GetID()
-      ToWaypoint["speed_locked"] = true,
-  
-      self:F( ToWaypoint )
-      
-      Points[#Points+1] = ToWaypoint
-  
+      local PointVec3 = Airplane:GetPointVec3()
       Template.x = PointVec3.x
       Template.y = PointVec3.z
-      
-      self:T3( Points )
+ 
       Template.route.points = Points
-
-      --self:Respawn( Template )
-
-      local GroupSpawned = Airplane:Respawn( Template )
-      
-      return GroupSpawned
+            
+      local GroupSpawned = Airplane:Respawn(Template)
+    
     end
+  end
+end
 
+--- On after Home event. Aircraft will be routed to their home base.
+-- @param #AI_CARGO_AIRPLANE self
+-- @param Wrapper.Group#GROUP Airplane The cargo plane.
+-- @param From From state.
+-- @param Event Event.
+-- @param To To State.
+-- @param Core.Point#COORDINATE Coordinate Home place (not used).
+-- @param #number Speed Speed in km/h to fly to the home airbase (zone). Default is 80% of max possible speed the unit can go.
+-- @param #number Height Height in meters to move to the home coordinate.
+-- @param Core.Zone#ZONE_AIRBASE HomeZone The home airbase (zone) where the plane should return to.
+function AI_CARGO_AIRPLANE:onafterHome(Airplane, From, Event, To, Coordinate, Speed, Height, HomeZone )
+  if Airplane and Airplane:IsAlive() then
+
+    -- We are going home!
+    self.RouteHome = true
+       
+    -- Home Base.
+    local HomeBase=HomeZone:GetAirbase()
+    self.Airbase=HomeBase
+    
+    -- Now route the airplane home
+   self:Route( Airplane, HomeBase, Speed, Height )
+    
   end
   
 end

Moose Development/Moose/AI/AI_Cargo_Dispatcher_APC.lua

@@ -1,6 +1,6 @@
---- **AI** -- Models the intelligent transportation of infantry and other cargo using APCs.
+--- **AI** -- (2.4) - Models the intelligent transportation of infantry and other cargo using APCs.
 --
--- **Features:**
+-- ## Features:
 -- 
 --   * Quickly transport cargo to various deploy zones using ground vehicles (APCs, trucks ...).
 --   * Various @{Cargo.Cargo#CARGO} types can be transported. These are infantry groups and crates.
@@ -14,6 +14,15 @@
 --  
 -- ===
 -- 
+-- ## Test Missions:
+-- 
+-- Test missions can be located on the main GITHUB site.
+-- 
+-- [FlightControl-Master/MOOSE_MISSIONS/AID - AI Dispatching/AID-CGO - AI Cargo Dispatching/]  
+-- (https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/develop/AID%20-%20AI%20Dispatching/AID-CGO%20-%20AI%20Cargo%20Dispatching)
+-- 
+-- ===
+-- 
 -- ### Author: **FlightControl**
 -- 
 -- ===       
@@ -28,54 +37,104 @@
 --- A dynamic cargo transportation 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.
--- The AI\_CARGO\_DISPATCHER\_APC module uses the @{Cargo} capabilities within the MOOSE framework.
--- 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
+-- The AI_CARGO_DISPATCHER_APC module is derived from the AI_CARGO_DISPATCHER module.
+-- 
+-- ## Note! In order to fully understand the mechanisms of the AI_CARGO_DISPATCHER_APC class, it is recommended that you first consult and READ the documentation of the @{AI.AI_Cargo_Dispatcher} module!!!
+-- 
+-- Especially to learn how to **Tailor the different cargo handling events**, this will be very useful!
+-- 
+-- On top, the AI_CARGO_DISPATCHER_APC class uses the @{Cargo.Cargo} capabilities within the MOOSE framework.
+-- Also ensure that you fully understand how to declare and setup Cargo objects within the MOOSE framework before using this class.
+-- CARGO derived objects must be declared within the mission to make the AI_CARGO_DISPATCHER_HELICOPTER object recognize the cargo.
+-- 
+-- 
+-- # 1) AI_CARGO_DISPATCHER_APC constructor.
 --   
---   * @{#AI_CARGO_DISPATCHER\_APC.New}(): Creates a new AI\_CARGO\_DISPATCHER\_APC object.
+--   * @{#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) AI_CARGO_DISPATCHER_APC is a Finite State Machine.
 -- 
--- ### 2.1. AI\_CARGO\_DISPATCHER\_APC States
+-- 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\_APC Events
+-- ## 2.2) AI_CARGO_DISPATCHER Events.
 -- 
---   * **Monitor**: Monitor and take action.
 --   * **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.
---   * **Home**: A APC is going home.
+--   * **Deployed**: All cargo is unloaded from the carriers in the group.
+--   * **Home**: A Carrier is going home.
 -- 
--- ## 3. Set the pickup parameters.
+-- ## 2.3) Enhance your mission scripts with **Tailored** Event Handling!
+-- 
+-- Within your mission, you can capture these events when triggered, and tailor the events with your own code!
+-- Check out the @{AI.AI_Cargo_Dispatcher#AI_CARGO_DISPATCHER} class at chapter 3 for details on the different event handlers that are available and how to use them.
+-- 
+-- **There are a lot of templates available that allows you to quickly setup an event handler for a specific event type!**
+-- 
+-- ---
+-- 
+-- # 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.
+--    * @{#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.
+-- # 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.
+--    * @{#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.
+-- # 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.
+-- 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.   
 -- 
@@ -88,35 +147,63 @@ AI_CARGO_DISPATCHER_APC = {
 
 --- Creates a new AI_CARGO_DISPATCHER_APC object.
 -- @param #AI_CARGO_DISPATCHER_APC self
--- @param Core.Set#SET_GROUP SetAPC The collection of APC @{Wrapper.Group}s.
--- @param Core.Set#SET_CARGO SetCargo The collection of @{Cargo} derived objects.
--- @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 Core.Set#SET_GROUP APCSet The set of @{Wrapper.Group#GROUP} objects of vehicles, trucks, APCs that will transport the cargo.
+-- @param Core.Set#SET_CARGO CargoSet The set of @{Cargo.Cargo#CARGO} objects, which can be CARGO_GROUP, CARGO_CRATE, CARGO_SLINGLOAD objects.
+-- @param Core.Set#SET_ZONE PickupZoneSet (optional) The set of pickup zones, which are used to where the cargo can be picked up by the APCs. If nil, then cargo can be picked up everywhere. 
+-- @param Core.Set#SET_ZONE DeployZoneSet The set of deploy zones, which are used to where the cargo will be deployed by the APCs. 
 -- @param DCS#Distance 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 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, SetDeployZone, 500 )
+--      -- An AI dispatcher object for a vehicle squadron, moving infantry from pickup zones to deploy zones.
 -- 
-function AI_CARGO_DISPATCHER_APC:New( SetAPC, SetCargo, SetDeployZone, CombatRadius )
+--      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()
+-- 
+function AI_CARGO_DISPATCHER_APC:New( APCSet, CargoSet, PickupZoneSet, DeployZoneSet, CombatRadius )
 
-  local self = BASE:Inherit( self, AI_CARGO_DISPATCHER:New( SetAPC, SetCargo, SetDeployZone ) ) -- #AI_CARGO_DISPATCHER_APC
+  local self = BASE:Inherit( self, AI_CARGO_DISPATCHER:New( APCSet, CargoSet, PickupZoneSet, DeployZoneSet ) ) -- #AI_CARGO_DISPATCHER_APC
 
-  self.CombatRadius = CombatRadius or 500
-
-  self:SetDeploySpeed( 70, 120 )
-  self:SetPickupSpeed( 70, 120 )
+  self:SetDeploySpeed( 120, 70 )
+  self:SetPickupSpeed( 120, 70 )
   self:SetPickupRadius( 0, 0 )
   self:SetDeployRadius( 0, 0 )
+  
+  self:SetPickupHeight()
+  self:SetDeployHeight()
+  
+  self:SetCombatRadius( CombatRadius )
 
   return self
 end
 
+function AI_CARGO_DISPATCHER_APC:AICargo( APC, CargoSet )
 
-function AI_CARGO_DISPATCHER_APC:AICargo( APC, SetCargo )
-
-  return AI_CARGO_APC:New( APC, SetCargo, self.CombatRadius )
+  return AI_CARGO_APC:New( APC, CargoSet, self.CombatRadius )
 end
+
+--- 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.
+-- @param #AI_CARGO_DISPATCHER_APC self
+-- @param #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 #AI_CARGO_DISPATCHER_APC
+-- @usage
+-- 
+-- -- Disembark the infantry when the carrier is under attack.
+-- AICargoDispatcher:SetCombatRadius( true )
+-- 
+-- -- Keep the cargo in the carrier when the carrier is under attack.
+-- AICargoDispatcher:SetCombatRadius( false )
+function AI_CARGO_DISPATCHER_APC:SetCombatRadius( CombatRadius )
+
+  self.CombatRadius = CombatRadius or 0
+
+  return self
+end
+

Moose Development/Moose/AI/AI_Cargo_Dispatcher_Airplane.lua

@@ -1,5 +1,19 @@
 --- **AI** -- (R2.4) - Models the intelligent transportation of infantry and other cargo using Planes.
 --
+-- ## Features:
+--
+--   * The airplanes will fly towards the pickup airbases to pickup the cargo.
+--   * The airplanes will fly towards the deploy airbases to deploy the cargo.
+--   
+-- ===
+-- 
+-- ## Test Missions:
+-- 
+-- Test missions can be located on the main GITHUB site.
+-- 
+-- [FlightControl-Master/MOOSE_MISSIONS/AID - AI Dispatching/AID-CGO - AI Cargo Dispatching/]  
+-- (https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/develop/AID%20-%20AI%20Dispatching/AID-CGO%20-%20AI%20Cargo%20Dispatching)
+-- 
 -- ===
 -- 
 -- ### Author: **FlightControl**
@@ -8,7 +22,8 @@
 --
 -- @module AI.AI_Cargo_Dispatcher_Airplane
 -- @image AI_Cargo_Dispatching_For_Airplanes.JPG
--- 
+
+
 --- @type AI_CARGO_DISPATCHER_AIRPLANE
 -- @extends AI.AI_Cargo_Dispatcher#AI_CARGO_DISPATCHER
 
@@ -16,9 +31,82 @@
 --- Brings a dynamic cargo handling capability for AI groups.
 -- 
 -- Airplanes can be mobilized to intelligently transport infantry and other cargo within the simulation.
--- The AI\_CARGO\_DISPATCHER\_AIRPLANE module uses the @{Cargo} capabilities within the MOOSE framework.
--- CARGO derived objects must be declared within the mission to make the AI\_CARGO\_DISPATCHER\_AIRPLANE object recognize the cargo.
--- Please consult the @{Cargo} module for more information. 
+-- 
+-- The AI_CARGO_DISPATCHER_AIRPLANE module is derived from the AI_CARGO_DISPATCHER module.
+-- 
+-- ## Note! In order to fully understand the mechanisms of the AI_CARGO_DISPATCHER_AIRPLANE class, it is recommended that you first consult and READ the documentation of the @{AI.AI_Cargo_Dispatcher} module!!!**
+-- 
+-- Especially to learn how to **Tailor the different cargo handling events**, this will be very useful!
+-- 
+-- On top, the AI_CARGO_DISPATCHER_AIRPLANE class uses the @{Cargo.Cargo} capabilities within the MOOSE framework.
+-- Also ensure that you fully understand how to declare and setup Cargo objects within the MOOSE framework before using this class.
+-- CARGO derived objects must be declared within the mission to make the AI_CARGO_DISPATCHER_HELICOPTER object recognize the cargo.
+-- 
+-- # 1) AI_CARGO_DISPATCHER_AIRPLANE constructor.
+--   
+--   * @{#AI_CARGO_DISPATCHER_AIRPLANE.New}(): Creates a new AI_CARGO_DISPATCHER_AIRPLANE object.
+-- 
+-- ---
+-- 
+-- # 2) AI_CARGO_DISPATCHER_AIRPLANE 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.
+-- 
+-- ## 2.3) Enhance your mission scripts with **Tailored** Event Handling!
+-- 
+-- Within your mission, you can capture these events when triggered, and tailor the events with your own code!
+-- Check out the @{AI.AI_Cargo_Dispatcher#AI_CARGO_DISPATCHER} class at chapter 3 for details on the different event handlers that are available and how to use them.
+-- 
+-- **There are a lot of templates available that allows you to quickly setup an event handler for a specific event type!**
 -- 
 -- 
 -- 
@@ -29,23 +117,48 @@ AI_CARGO_DISPATCHER_AIRPLANE = {
 
 --- Creates a new AI_CARGO_DISPATCHER_AIRPLANE object.
 -- @param #AI_CARGO_DISPATCHER_AIRPLANE self
--- @param Core.Set#SET_GROUP SetAirplane
--- @param Core.Set#SET_CARGO SetCargo
--- @param Core.Set#SET_ZONE SetDeployZone
--- @return #AI_CARGO_DISPATCHER_AIRPLANE
+-- @param Core.Set#SET_GROUP AirplaneSet The set of @{Wrapper.Group#GROUP} objects of airplanes that will transport the cargo.
+-- @param Core.Set#SET_CARGO CargoSet The set of @{Cargo.Cargo#CARGO} objects, which can be CARGO_GROUP, CARGO_CRATE, CARGO_SLINGLOAD objects.
+-- @param Core.Zone#SET_ZONE PickupZoneSet The set of zone airbases where the cargo has to be picked up.
+-- @param Core.Zone#SET_ZONE DeployZoneSet The set of zone airbases where the cargo is deployed. Choice for each cargo is random.
+-- @return #AI_CARGO_DISPATCHER_AIRPLANE self
 -- @usage
 -- 
--- -- Create a new cargo dispatcher
--- SetAirplane = SET_GROUP:New():FilterPrefixes( "Airplane" ):FilterStart()
--- SetCargo = SET_CARGO:New():FilterTypes( "Infantry" ):FilterStart()
--- SetDeployZone = SET_ZONE:New():FilterPrefixes( "Deploy" ):FilterStart()
--- AICargoDispatcher = AI_CARGO_DISPATCHER_AIRPLANE:New( SetAirplane, SetCargo )
+--      -- 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:Start()
 -- 
-function AI_CARGO_DISPATCHER_AIRPLANE:New( SetAirplane, SetCargo, SetDeployZones )
+function AI_CARGO_DISPATCHER_AIRPLANE:New( AirplaneSet, CargoSet, PickupZoneSet, DeployZoneSet )
 
-  local self = BASE:Inherit( self, AI_CARGO_DISPATCHER:New( SetAirplane, SetCargo, SetDeployZones ) ) -- #AI_CARGO_DISPATCHER_AIRPLANE
+  local self = BASE:Inherit( self, AI_CARGO_DISPATCHER:New( AirplaneSet, CargoSet, PickupZoneSet, DeployZoneSet ) ) -- #AI_CARGO_DISPATCHER_AIRPLANE
+
+  self:SetPickupSpeed( 1200, 600 )
+  self:SetDeploySpeed( 1200, 600 )
+  
+  self:SetPickupRadius( 0, 0 )
+  self:SetDeployRadius( 0, 0 )
+
+  self:SetPickupHeight( 8000, 6000 )  
+  self:SetDeployHeight( 8000, 6000 )
+    
+  self:SetMonitorTimeInterval( 600 )
 
   return self
 end
 
+function AI_CARGO_DISPATCHER_AIRPLANE:AICargo( Airplane, CargoSet )
 
+  return AI_CARGO_AIRPLANE:New( Airplane, CargoSet )
+end

Moose Development/Moose/AI/AI_Cargo_Dispatcher_Helicopter.lua

@@ -1,7 +1,21 @@
---- **AI** -- 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.
+--- **AI** -- (2.4) - Models the intelligent transportation of infantry and other cargo using Helicopters.
 --
+-- ## Features:
+-- 
+--   * The helicopters will fly towards the pickup locations to pickup the cargo.
+--   * The helicopters will fly towards the deploy zones to deploy the cargo.
+--   * Precision deployment as well as randomized deployment within the deploy zones are possible.
+--   * Helicopters will orbit the deploy zones when there is no space for landing until the deploy zone is free.
+--   
+-- ===
+-- 
+-- ## Test Missions:
+-- 
+-- Test missions can be located on the main GITHUB site.
+-- 
+-- [FlightControl-Master/MOOSE_MISSIONS/AID - AI Dispatching/AID-CGO - AI Cargo Dispatching/]  
+-- (https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/develop/AID%20-%20AI%20Dispatching/AID-CGO%20-%20AI%20Cargo%20Dispatching)
+-- 
 -- ===
 -- 
 -- ### Author: **FlightControl**
@@ -18,39 +32,85 @@
 --- 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. 
+-- 
+-- 
+-- The AI_CARGO_DISPATCHER_HELICOPTER module is derived from the AI_CARGO_DISPATCHER module.
+-- 
+-- ## Note! In order to fully understand the mechanisms of the AI_CARGO_DISPATCHER_HELICOPTER class, it is recommended that you first consult and READ the documentation of the @{AI.AI_Cargo_Dispatcher} module!!!**
+-- 
+-- Especially to learn how to **Tailor the different cargo handling events**, this will be very useful!
+-- 
+-- On top, the AI_CARGO_DISPATCHER_HELICOPTER class uses the @{Cargo.Cargo} capabilities within the MOOSE framework.
+-- Also ensure that you fully understand how to declare and setup Cargo objects within the MOOSE framework before using this class.
+-- CARGO derived objects must be declared within the mission to make the AI_CARGO_DISPATCHER_HELICOPTER object recognize the cargo.
 -- 
 -- ---
 -- 
--- ## 1. AI\_CARGO\_DISPATCHER\_HELICOPTER constructor
+-- # 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
+-- # 2. AI\_CARGO\_DISPATCHER\_HELICOPTER is a Finite State Machine.
 -- 
--- ![Process](..\Presentations\AI_CARGO_DISPATCHER_HELICOPTER\Dia3.JPG)
+-- 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.
 -- 
--- ### 2.1. AI\_CARGO\_DISPATCHER\_HELICOPTER States
+-- 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\_HELICOPTER Events
+-- ## 2.2) AI_CARGO_DISPATCHER Events.
 -- 
---   * **Monitor**: Monitor and take action.
 --   * **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.
---   * **Home**: A Helicopter is going home.
+--   * **Deployed**: All cargo is unloaded from the carriers in the group.
+--   * **Home**: A Carrier is going home.
+-- 
+-- ## 2.3) Enhance your mission scripts with **Tailored** Event Handling!
+-- 
+-- Within your mission, you can capture these events when triggered, and tailor the events with your own code!
+-- Check out the @{AI.AI_Cargo_Dispatcher#AI_CARGO_DISPATCHER} class at chapter 3 for details on the different event handlers that are available and how to use them.
+-- 
+-- **There are a lot of templates available that allows you to quickly setup an event handler for a specific event type!**
 -- 
 -- ---
 -- 
@@ -58,8 +118,9 @@
 -- 
 -- 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.
+--    * @{#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.
+--    * @{#AI_CARGO_DISPATCHER_HELICOPTER.SetPickupHeight}(): Set the height or randomizes the height in meters to pickup the cargo.
 -- 
 -- ---   
 --    
@@ -67,15 +128,16 @@
 -- 
 -- 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.
+--    * @{#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.
+--    * @{#AI_CARGO_DISPATCHER_HELICOPTER.SetDeployHeight}(): Set the height or randomizes the height in meters 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.
+-- 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.   
 -- 
@@ -88,32 +150,42 @@ AI_CARGO_DISPATCHER_HELICOPTER = {
 
 --- Creates a new AI_CARGO_DISPATCHER_HELICOPTER object.
 -- @param #AI_CARGO_DISPATCHER_HELICOPTER self
--- @param Core.Set#SET_GROUP SetHelicopter The collection of Helicopter @{Wrapper.Group}s.
--- @param Core.Set#SET_CARGO SetCargo The collection of @{Cargo} derived objects.
--- @param Core.Set#SET_ZONE SetDeployZones The collection of deploy @{Zone}s, which are used to where the cargo will be deployed by the Helicopters. 
+-- @param Core.Set#SET_GROUP HelicopterSet The set of @{Wrapper.Group#GROUP} objects of helicopters that will transport the cargo.
+-- @param Core.Set#SET_CARGO CargoSet The set of @{Cargo.Cargo#CARGO} objects, which can be CARGO_GROUP, CARGO_CRATE, CARGO_SLINGLOAD objects.
+-- @param Core.Set#SET_ZONE PickupZoneSet (optional) The set of pickup zones, which are used to where the cargo can be picked up by the APCs. If nil, then cargo can be picked up everywhere. 
+-- @param Core.Set#SET_ZONE DeployZoneSet The set of deploy zones, which are used to where the cargo will be deployed by the Helicopters. 
 -- @return #AI_CARGO_DISPATCHER_HELICOPTER
 -- @usage
 -- 
--- -- Create a new cargo dispatcher
--- SetHelicopter = SET_GROUP:New():FilterPrefixes( "Helicopter" ):FilterStart()
--- SetCargo = SET_CARGO:New():FilterTypes( "Infantry" ):FilterStart()
--- SetDeployZone = SET_ZONE:New():FilterPrefixes( "Deploy" ):FilterStart()
--- AICargoDispatcher = AI_CARGO_DISPATCHER_HELICOPTER:New( SetHelicopter, SetCargo )
+--      -- An AI dispatcher object for a helicopter squadron, moving infantry from pickup zones to deploy zones.
 -- 
-function AI_CARGO_DISPATCHER_HELICOPTER:New( SetHelicopter, SetCargo, SetDeployZones )
+--      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:Start()
+-- 
+function AI_CARGO_DISPATCHER_HELICOPTER:New( HelicopterSet, CargoSet, PickupZoneSet, DeployZoneSet )
 
-  local self = BASE:Inherit( self, AI_CARGO_DISPATCHER:New( SetHelicopter, SetCargo, SetDeployZones ) ) -- #AI_CARGO_DISPATCHER_HELICOPTER
+  local self = BASE:Inherit( self, AI_CARGO_DISPATCHER:New( HelicopterSet, CargoSet, PickupZoneSet, DeployZoneSet ) ) -- #AI_CARGO_DISPATCHER_HELICOPTER
+
+  self:SetPickupSpeed( 350, 150 )
+  self:SetDeploySpeed( 350, 150 )
 
-  self:SetDeploySpeed( 200, 150 )
-  self:SetPickupSpeed( 200, 150 )
   self:SetPickupRadius( 0, 0 )
   self:SetDeployRadius( 0, 0 )
   
+  self:SetPickupHeight( 500, 200 )
+  self:SetDeployHeight( 500, 200 )
+  
   return self
 end
 
-function AI_CARGO_DISPATCHER_HELICOPTER:AICargo( Helicopter, SetCargo )
 
-  return AI_CARGO_HELICOPTER:New( Helicopter, SetCargo )
+function AI_CARGO_DISPATCHER_HELICOPTER:AICargo( Helicopter, CargoSet )
+
+  return AI_CARGO_HELICOPTER:New( Helicopter, CargoSet )
 end
 

Moose Development/Moose/AI/AI_Cargo_Helicopter.lua

@@ -1,4 +1,4 @@
---- **AI** -- (R2.3) - Models the intelligent transportation of infantry (cargo).
+--- **AI** -- (R2.4) - Models the intelligent transportation of infantry (cargo).
 --
 -- ===
 -- 
@@ -13,14 +13,41 @@
 -- @extends Core.Fsm#FSM_CONTROLLABLE
 
 
---- # AI\_CARGO\_TROOPS class, extends @{Core.Fsm#FSM_CONTROLLABLE}
+--- Brings a dynamic cargo handling capability for an AI helicopter group.
+--  
+-- Helicopter carriers can be mobilized to intelligently transport infantry and other cargo within the simulation.
+-- 
+-- The AI_CARGO_HELICOPTER class uses the @{Cargo.Cargo} capabilities within the MOOSE framework.
+-- @{Cargo.Cargo} must be declared within the mission to make the AI_CARGO_HELICOPTER object recognize the cargo.
+-- Please consult the @{Cargo.Cargo} module for more information. 
+-- 
+-- ## Cargo pickup.
+--  
+-- Using the @{#AI_CARGO_HELICOPTER.Pickup}() method, you are able to direct the helicopters towards a point on the battlefield to board/load the cargo at the specific coordinate. 
+-- Ensure that the landing zone is horizontally flat, and that trees cannot be found in the landing vicinity, or the helicopters won't land or will even crash!
+-- 
+-- ## Cargo deployment.
+--  
+-- Using the @{#AI_CARGO_HELICOPTER.Deploy}() method, you are able to direct the helicopters towards a point on the battlefield to unboard/unload the cargo at the specific coordinate. 
+-- Ensure that the landing zone is horizontally flat, and that trees cannot be found in the landing vicinity, or the helicopters won't land or will even crash!
+-- 
+-- ## Infantry 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, 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 ... 
+-- 
 -- 
 -- ===
 -- 
 -- @field #AI_CARGO_HELICOPTER
 AI_CARGO_HELICOPTER = {
   ClassName = "AI_CARGO_HELICOPTER",
-  Coordinate = nil -- Core.Point#COORDINATE,
+  Coordinate = nil, -- Core.Point#COORDINATE,
 }
 
 AI_CARGO_QUEUE = {}
@@ -32,10 +59,8 @@ AI_CARGO_QUEUE = {}
 -- @return #AI_CARGO_HELICOPTER
 function AI_CARGO_HELICOPTER:New( Helicopter, CargoSet )
 
-  local self = BASE:Inherit( self, FSM_CONTROLLABLE:New() ) -- #AI_CARGO_HELICOPTER
+  local self = BASE:Inherit( self, AI_CARGO:New( Helicopter, CargoSet ) ) -- #AI_CARGO_HELICOPTER
 
-  self.CargoSet = CargoSet -- Cargo.CargoGroup#CARGO_GROUP
-  
   self.Zone = ZONE_GROUP:New( Helicopter:GetName(), Helicopter, 300 )
 
   self:SetStartState( "Unloaded" ) 
@@ -43,12 +68,14 @@ function AI_CARGO_HELICOPTER:New( Helicopter, CargoSet )
   self:AddTransition( "Unloaded", "Pickup", "*" )
   self:AddTransition( "Loaded", "Deploy", "*" )
   
-  self:AddTransition( "Unloaded", "Load", "Boarding" )
+  self:AddTransition( { "Unloaded", "Loading" }, "Load", "Boarding" )
   self:AddTransition( "Boarding", "Board", "Boarding" )
-  self:AddTransition( "Boarding", "Loaded", "Loaded" )
+  self:AddTransition( "Boarding", "Loaded", "Boarding" )
+  self:AddTransition( "Boarding", "PickedUp", "Loaded" )
   self:AddTransition( "Loaded", "Unload", "Unboarding" )
   self:AddTransition( "Unboarding", "Unboard", "Unboarding" )
-  self:AddTransition( "Unboarding", "Unloaded", "Unloaded" )
+  self:AddTransition( "Unboarding", "Unloaded", "Unboarding" )
+  self:AddTransition( "Unboarding", "Deployed", "Unloaded" )
 
   self:AddTransition( "*", "Landed", "*" )
   self:AddTransition( "*", "Queue", "*" )
@@ -73,17 +100,20 @@ function AI_CARGO_HELICOPTER:New( Helicopter, CargoSet )
   -- @param #string Event
   -- @param #string To
   -- @param Core.Point#COORDINATE Coordinate
+  -- @param #number Speed Speed in km/h to drive to the pickup coordinate. Default is 50% of max possible speed the unit can go.
   
   --- Pickup Trigger for AI_CARGO_HELICOPTER
   -- @function [parent=#AI_CARGO_HELICOPTER] Pickup
   -- @param #AI_CARGO_HELICOPTER self
   -- @param Core.Point#COORDINATE Coordinate
+  -- @param #number Speed Speed in km/h to drive to the pickup coordinate. Default is 50% of max possible speed the unit can go.
   
   --- Pickup Asynchronous Trigger for AI_CARGO_HELICOPTER
   -- @function [parent=#AI_CARGO_HELICOPTER] __Pickup
   -- @param #AI_CARGO_HELICOPTER self
-  -- @param #number Delay
+  -- @param #number Delay Delay in seconds.
   -- @param Core.Point#COORDINATE Coordinate
+  -- @param #number Speed Speed in km/h to go to the pickup coordinate. Default is 50% of max possible speed the unit can go.
   
   --- Deploy Handler OnBefore for AI_CARGO_HELICOPTER
   -- @function [parent=#AI_CARGO_HELICOPTER] OnBeforeDeploy
@@ -91,7 +121,8 @@ function AI_CARGO_HELICOPTER:New( Helicopter, CargoSet )
   -- @param #string From
   -- @param #string Event
   -- @param #string To
-  -- @param Core.Point#COORDINATE Coordinate
+  -- @param Core.Point#COORDINATE Coordinate Place at which cargo is deployed.
+  -- @param #number Speed Speed in km/h to drive to the pickup coordinate. Default is 50% of max possible speed the unit can go.
   -- @return #boolean
   
   --- Deploy Handler OnAfter for AI_CARGO_HELICOPTER
@@ -101,18 +132,21 @@ function AI_CARGO_HELICOPTER:New( Helicopter, CargoSet )
   -- @param #string Event
   -- @param #string To
   -- @param Core.Point#COORDINATE Coordinate
+  -- @param #number Speed Speed in km/h to drive to the pickup coordinate. Default is 50% of max possible speed the unit can go.
   
   --- Deploy Trigger for AI_CARGO_HELICOPTER
   -- @function [parent=#AI_CARGO_HELICOPTER] Deploy
   -- @param #AI_CARGO_HELICOPTER self
-  -- @param Core.Point#COORDINATE Coordinate
+  -- @param Core.Point#COORDINATE Coordinate Place at which the cargo is deployed.
+  -- @param #number Speed Speed in km/h to drive to the pickup coordinate. Default is 50% of max possible speed the unit can go.
   
   --- Deploy Asynchronous Trigger for AI_CARGO_HELICOPTER
   -- @function [parent=#AI_CARGO_HELICOPTER] __Deploy
+  -- @param #number Delay Delay in seconds.
   -- @param #AI_CARGO_HELICOPTER self
-  -- @param Core.Point#COORDINATE Coordinate
-  -- @param #number Delay
-
+  -- @param Core.Point#COORDINATE Coordinate Place at which the cargo is deployed.
+  -- @param #number Speed Speed in km/h to drive to the pickup coordinate. Default is 50% of max possible speed the unit can go.
+  
 
   -- We need to capture the Crash events for the helicopters.
   -- The helicopter reference is used in the semaphore AI_CARGO_QUEUE.
@@ -142,15 +176,8 @@ function AI_CARGO_HELICOPTER:New( Helicopter, CargoSet )
   return self
 end
 
-function AI_CARGO_HELICOPTER:IsTransporting()
 
-  return self.Transporting == true
-end
 
-function AI_CARGO_HELICOPTER:IsRelocating()
-
-  return self.Relocating == true
-end
 
 
 --- Set the Carrier.
@@ -200,8 +227,6 @@ end
 -- @param From
 -- @param Event
 -- @param To
--- @param Core.Point#COORDINATE Coordinate
--- @param #number Speed
 function AI_CARGO_HELICOPTER:onafterLanded( Helicopter, From, Event, To )
 
   Helicopter:F( { Name = Helicopter:GetName() } )
@@ -219,18 +244,16 @@ function AI_CARGO_HELICOPTER:onafterLanded( Helicopter, From, Event, To )
 
     if self.RoutePickup == true then
       if Helicopter:GetHeight( true ) <= 5 and Helicopter:GetVelocityKMH() < 10 then
-        self:Load( Helicopter:GetPointVec2() )
+        --self:Load( Helicopter:GetPointVec2() )
+        self:Load( self.PickupZone )
         self.RoutePickup = false
-        self.Relocating = true
       end
     end
     
     if self.RouteDeploy == true then
       if Helicopter:GetHeight( true ) <= 5 and Helicopter:GetVelocityKMH() < 10 then
-        self:Unload( true )
+        self:Unload( self.DeployZone )
         self.RouteDeploy = false
-        self.Transporting = false
-        self.Relocating = false
       end
     end
      
@@ -245,7 +268,7 @@ end
 -- @param To
 -- @param Core.Point#COORDINATE Coordinate
 -- @param #number Speed
-function AI_CARGO_HELICOPTER:onafterQueue( Helicopter, From, Event, To, Coordinate )
+function AI_CARGO_HELICOPTER:onafterQueue( Helicopter, From, Event, To, Coordinate, Speed, DeployZone )
 
   local HelicopterInZone = false
 
@@ -254,7 +277,7 @@ function AI_CARGO_HELICOPTER:onafterQueue( Helicopter, From, Event, To, Coordina
     local Distance = Coordinate:DistanceFromPointVec2( Helicopter:GetCoordinate() )
     
     if Distance > 2000 then
-      self:__Queue( -10, Coordinate )
+      self:__Queue( -10, Coordinate, Speed, DeployZone )
     else
     
       local ZoneFree = true
@@ -303,8 +326,12 @@ function AI_CARGO_HELICOPTER:onafterQueue( Helicopter, From, Event, To, Coordina
     
         -- Now route the helicopter
         Helicopter:Route( Route, 0 )
+        
+        -- Keep the DeployZone, because when the helo has landed, we want to provide the DeployZone to the mission designer as part of the Unloaded event.
+        self.DeployZone = DeployZone
+        
       else
-        self:__Queue( -10, Coordinate )
+        self:__Queue( -10, Coordinate, Speed, DeployZone )
       end
     end
   else
@@ -324,193 +351,51 @@ function AI_CARGO_HELICOPTER:onafterOrbit( Helicopter, From, Event, To, Coordina
 
   if Helicopter and Helicopter:IsAlive() then
     
-    if not self:IsTransporting() then
-      local Route = {}
-      
-  --          local CoordinateFrom = Helicopter:GetCoordinate()
-  --          local WaypointFrom = CoordinateFrom:WaypointAir( 
-  --            "RADIO", 
-  --            POINT_VEC3.RoutePointType.TurningPoint, 
-  --            POINT_VEC3.RoutePointAction.TurningPoint, 
-  --            Speed, 
-  --            true 
-  --          )
-  --          Route[#Route+1] = WaypointFrom
-      local CoordinateTo   = Coordinate
-      local WaypointTo = CoordinateTo:WaypointAir( 
-        "RADIO", 
-        POINT_VEC3.RoutePointType.TurningPoint, 
-        POINT_VEC3.RoutePointAction.TurningPoint, 
-        50, 
-        true 
-      )
-      Route[#Route+1] = WaypointTo
-      
-      local Tasks = {}
-      Tasks[#Tasks+1] = Helicopter:TaskOrbitCircle( math.random( 30, 80 ), 150, CoordinateTo:GetRandomCoordinateInRadius( 800, 500 ) )
-      Route[#Route].task = Helicopter:TaskCombo( Tasks )
-  
-      Route[#Route+1] = WaypointTo
-  
-      -- Now route the helicopter
-      Helicopter:Route( Route, 0 )
-    end
-  end
-end
-
-
-
---- @param #AI_CARGO_HELICOPTER self
--- @param Wrapper.Group#GROUP Helicopter
-function AI_CARGO_HELICOPTER:onbeforeLoad( Helicopter, From, Event, To, Coordinate )
-
-  local Boarding = false
-
-  if Helicopter and Helicopter:IsAlive() then
-  
-    self.BoardingCount = 0
-  
-    if Helicopter and Helicopter:IsAlive() then
-      self.Helicopter_Cargo = {}
-      for _, HelicopterUnit in pairs( Helicopter:GetUnits() ) do
-        local HelicopterUnit = HelicopterUnit -- Wrapper.Unit#UNIT
-        for _, Cargo in pairs( self.CargoSet:GetSet() ) do
-          local Cargo = Cargo -- Cargo.Cargo#CARGO
-          self:F( { IsUnLoaded = Cargo:IsUnLoaded() } )
-          if Cargo:IsUnLoaded() then
-            if Cargo:IsInLoadRadius( HelicopterUnit:GetCoordinate() ) then
-              self:F( { "In radius", HelicopterUnit:GetName() } )
-              --Cargo:Ungroup()
-              Cargo:Board( HelicopterUnit, 25 )
-              self:__Board( 1, Cargo )
-              Boarding = true
-              
-              -- So now this APCUnit has Cargo that is being loaded.
-              -- This will be used further in the logic to follow and to check cargo status.
-              self.Helicopter_Cargo[HelicopterUnit] = Cargo
-              break
-            end
-          end
-        end
-      end
-    end
-  end
-
-  return Boarding
-  
-end
-
---- @param #AI_CARGO_HELICOPTER self
--- @param Wrapper.Group#GROUP Helicopter
-function AI_CARGO_HELICOPTER:onafterBoard( Helicopter, From, Event, To, Cargo )
-  self:F( { APC, From, Event, To, Cargo } )
-
-  if Helicopter and Helicopter:IsAlive() then
-    self:F({ IsLoaded = Cargo:IsLoaded() } )
-    if not Cargo:IsLoaded() then
-      self:__Board( 10, Cargo )
-    else
-      self:__Loaded( 1, Cargo )
-    end
-  end
-  
-end
-
---- @param #AI_CARGO_HELICOPTER self
--- @param Wrapper.Group#GROUP Helicopter
-function AI_CARGO_HELICOPTER:onbeforeLoaded( Helicopter, From, Event, To, Cargo )
-  self:F( { APC, From, Event, To } )
-  
-  local Loaded = true
-
-  if Helicopter and Helicopter:IsAlive() then
-    for HelicopterUnit, Cargo in pairs( self.Helicopter_Cargo ) do
-      local Cargo = Cargo -- Cargo.Cargo#CARGO
-      self:F( { IsLoaded = Cargo:IsLoaded(), IsDestroyed = Cargo:IsDestroyed() } )
-      if not Cargo:IsLoaded() and not Cargo:IsDestroyed() then
-        Loaded = false
-      end
-    end
+    local Route = {}
     
-  end
-  
-  return Loaded
-
-end
-
-
---- @param #AI_CARGO_HELICOPTER self
--- @param Wrapper.Group#GROUP Helicopter
-function AI_CARGO_HELICOPTER:onafterUnload( Helicopter, From, Event, To, Deployed )
-
-  if Helicopter and Helicopter:IsAlive() then
-    for _, HelicopterUnit in pairs( Helicopter:GetUnits() ) do
-      local HelicopterUnit = HelicopterUnit -- Wrapper.Unit#UNIT
-      for _, Cargo in pairs( HelicopterUnit:GetCargo() ) do
-        Cargo:UnBoard()
-        Cargo:SetDeployed( true )
-        self:__Unboard( 10, Cargo, Deployed )
-      end 
-    end
-  end
-
-  
-end
-
---- @param #AI_CARGO_HELICOPTER self
--- @param Wrapper.Group#GROUP Helicopter
-function AI_CARGO_HELICOPTER:onafterUnboard( Helicopter, From, Event, To, Cargo, Deployed )
-
-  if Helicopter and Helicopter:IsAlive() then
-    if not Cargo:IsUnLoaded() then
-      self:__Unboard( 10, Cargo, Deployed ) 
-    else
-      self:__Unloaded( 1, Cargo, Deployed )
-    end
-  end
-  
-end
-
---- @param #AI_CARGO_HELICOPTER self
--- @param Wrapper.Group#GROUP Helicopter
-function AI_CARGO_HELICOPTER:onbeforeUnloaded( Helicopter, From, Event, To, Cargo, Deployed )
-  self:F( { APC, From, Event, To, Cargo:GetName(), Deployed = Deployed } )
-
-  local AllUnloaded = true
-
-  --Cargo:Regroup()
-
-  if Helicopter and Helicopter:IsAlive() then
-    for _, HelicopterUnit in pairs( Helicopter:GetUnits() ) do
-      local CargoCheck = self.Helicopter_Cargo[HelicopterUnit] -- Cargo.Cargo#CARGO
-      if CargoCheck then
-        self:F( { CargoCheck:GetName(), IsUnLoaded = CargoCheck:IsUnLoaded() } )
-        if CargoCheck:IsUnLoaded() == false then
-          AllUnloaded = false
-          break
-        end
-      end
-    end
+--          local CoordinateFrom = Helicopter:GetCoordinate()
+--          local WaypointFrom = CoordinateFrom:WaypointAir( 
+--            "RADIO", 
+--            POINT_VEC3.RoutePointType.TurningPoint, 
+--            POINT_VEC3.RoutePointAction.TurningPoint, 
+--            Speed, 
+--            true 
+--          )
+--          Route[#Route+1] = WaypointFrom
+    local CoordinateTo   = Coordinate
+    local WaypointTo = CoordinateTo:WaypointAir( 
+      "RADIO", 
+      POINT_VEC3.RoutePointType.TurningPoint, 
+      POINT_VEC3.RoutePointAction.TurningPoint, 
+      50, 
+      true 
+    )
+    Route[#Route+1] = WaypointTo
     
-    if AllUnloaded == true then
-      if Deployed == true then
-        for HelicopterUnit, Cargo in pairs( self.Helicopter_Cargo ) do
-          local Cargo = Cargo -- Cargo.Cargo#CARGO
-        end
-        self.Helicopter_Cargo = {}
-      end
-      self.Helicopter = Helicopter
-    end
+    local Tasks = {}
+    Tasks[#Tasks+1] = Helicopter:TaskOrbitCircle( math.random( 30, 80 ), 150, CoordinateTo:GetRandomCoordinateInRadius( 800, 500 ) )
+    Route[#Route].task = Helicopter:TaskCombo( Tasks )
+
+    Route[#Route+1] = WaypointTo
+
+    -- Now route the helicopter
+    Helicopter:Route( Route, 0 )
   end
-  
-  self:F( { AllUnloaded = AllUnloaded } )
-  return AllUnloaded
-  
 end
 
---- @param #AI_CARGO_HELICOPTER self
+
+
+--- On after Deployed event.
+-- @param #AI_CARGO_HELICOPTER self
 -- @param Wrapper.Group#GROUP Helicopter
-function AI_CARGO_HELICOPTER:onafterUnloaded( Helicopter, From, Event, To, Cargo, Deployed )
+-- @param #string From From state.
+-- @param #string Event Event.
+-- @param #string To To state.
+-- @param Cargo.Cargo#CARGO Cargo Cargo object.
+-- @param #boolean Deployed Cargo is deployed.
+-- @return #boolean True if all cargo has been unloaded.
+function AI_CARGO_HELICOPTER:onafterDeployed( Helicopter, From, Event, To, DeployZone )
+  self:F( { Helicopter, From, Event, To, DeployZone = DeployZone } )
 
   self:Orbit( Helicopter:GetCoordinate(), 50 )
 
@@ -520,24 +405,30 @@ function AI_CARGO_HELICOPTER:onafterUnloaded( Helicopter, From, Event, To, Cargo
       AI_CARGO_QUEUE[Helicopter] = nil
     end, Helicopter
   )
-
+  
+  self:GetParent( self, AI_CARGO_HELICOPTER ).onafterDeployed( self, Helicopter, From, Event, To, DeployZone )
+  
+  
 end
 
---- @param #AI_CARGO_HELICOPTER self
+--- On after Pickup event.
+-- @param #AI_CARGO_HELICOPTER self
 -- @param Wrapper.Group#GROUP Helicopter
 -- @param From
 -- @param Event
 -- @param To
--- @param Core.Point#COORDINATE Coordinate
+-- @param Core.Point#COORDINATE Coordinate Pickup place.
 -- @param #number Speed Speed in km/h to drive to the pickup coordinate. Default is 50% of max possible speed the unit can go.
-function AI_CARGO_HELICOPTER:onafterPickup( Helicopter, From, Event, To, Coordinate, Speed )
+-- @param #number Height Height in meters to move to the pickup coordinate. This parameter is ignored for APCs.
+-- @param 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.
+function AI_CARGO_HELICOPTER:onafterPickup( Helicopter, From, Event, To, Coordinate, Speed, Height, PickupZone )
 
   if Helicopter and Helicopter:IsAlive() ~= nil then
 
     Helicopter:Activate()
 
     self.RoutePickup = true
-    Coordinate.y = math.random( 50, 200 )
+    Coordinate.y = Height
     
     local _speed=Speed or Helicopter:GetSpeedMax()*0.5        
      
@@ -580,25 +471,33 @@ function AI_CARGO_HELICOPTER:onafterPickup( Helicopter, From, Event, To, Coordin
 
     -- Now route the helicopter
     Helicopter:Route( Route, 1 )
+    
+    self.PickupZone = PickupZone
+
+    self:GetParent( self, AI_CARGO_HELICOPTER ).onafterPickup( self, Helicopter, From, Event, To, Coordinate, Speed, Height, PickupZone )
 
-    self.Transporting = true
   end
   
 end
 
-
-function AI_CARGO_HELICOPTER:_Deploy( AICargoHelicopter, Coordinate )
-  AICargoHelicopter:__Queue( -10, Coordinate, 100 )
+--- Depoloy function and queue.
+-- @param #AI_CARGO_HELICOPTER self
+-- @param Wrapper.Group#GROUP AICargoHelicopter
+-- @param Core.Point#COORDINATE Coordinate Coordinate
+function AI_CARGO_HELICOPTER:_Deploy( AICargoHelicopter, Coordinate, DeployZone )
+  AICargoHelicopter:__Queue( -10, Coordinate, 100, DeployZone )
 end
 
---- @param #AI_CARGO_HELICOPTER self
--- @param Wrapper.Group#GROUP Helicopter
+--- On after Deploy event.
+-- @param #AI_CARGO_HELICOPTER self
+-- @param Wrapper.Group#GROUP Helicopter Transport helicopter.
 -- @param From
 -- @param Event
 -- @param To
--- @param Core.Point#COORDINATE Coordinate
+-- @param Core.Point#COORDINATE Coordinate Place at which the cargo is deployed.
 -- @param #number Speed Speed in km/h to drive to the pickup coordinate. Default is 50% of max possible speed the unit can go.
-function AI_CARGO_HELICOPTER:onafterDeploy( Helicopter, From, Event, To, Coordinate, Speed )
+-- @param #number Height Height in meters to move to the deploy coordinate.
+function AI_CARGO_HELICOPTER:onafterDeploy( Helicopter, From, Event, To, Coordinate, Speed, Height, DeployZone )
 
   if Helicopter and Helicopter:IsAlive() ~= nil then
 
@@ -609,7 +508,7 @@ function AI_CARGO_HELICOPTER:onafterDeploy( Helicopter, From, Event, To, Coordin
     
     --- Calculate the target route point.
 
-    Coordinate.y = math.random( 50, 200 )  
+    Coordinate.y = Height
     
     local _speed=Speed or Helicopter:GetSpeedMax()*0.5      
 
@@ -643,7 +542,7 @@ function AI_CARGO_HELICOPTER:onafterDeploy( Helicopter, From, Event, To, Coordin
   
     local Tasks = {}
     
-    Tasks[#Tasks+1] = Helicopter:TaskFunction( "AI_CARGO_HELICOPTER._Deploy", self, Coordinate )
+    Tasks[#Tasks+1] = Helicopter:TaskFunction( "AI_CARGO_HELICOPTER._Deploy", self, Coordinate, DeployZone )
     Tasks[#Tasks+1] = Helicopter:TaskOrbitCircle( math.random( 30, 100 ), _speed, CoordinateTo:GetRandomCoordinateInRadius( 800, 500 ) )
     
     --Tasks[#Tasks+1] = Helicopter:TaskLandAtVec2( CoordinateTo:GetVec2() )
@@ -653,20 +552,24 @@ function AI_CARGO_HELICOPTER:onafterDeploy( Helicopter, From, Event, To, Coordin
 
     -- Now route the helicopter
     Helicopter:Route( Route, 0 )
-    
+
+    self:GetParent( self, AI_CARGO_HELICOPTER ).onafterDeploy( self, Helicopter, From, Event, To, Coordinate, Speed, Height, DeployZone )
   end
   
 end
 
 
---- @param #AI_CARGO_HELICOPTER self
+--- On after Home event.
+-- @param #AI_CARGO_HELICOPTER self
 -- @param Wrapper.Group#GROUP Helicopter
 -- @param From
 -- @param Event
 -- @param To
--- @param Core.Point#COORDINATE Coordinate
+-- @param Core.Point#COORDINATE Coordinate Home place.
 -- @param #number Speed Speed in km/h to drive to the pickup coordinate. Default is 50% of max possible speed the unit can go.
-function AI_CARGO_HELICOPTER:onafterHome( Helicopter, From, Event, To, Coordinate, Speed )
+-- @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 AI_CARGO_HELICOPTER:onafterHome( Helicopter, From, Event, To, Coordinate, Speed, Height, HomeZone )
 
   if Helicopter and Helicopter:IsAlive() ~= nil then
 
@@ -676,9 +579,9 @@ function AI_CARGO_HELICOPTER:onafterHome( Helicopter, From, Event, To, Coordinat
     
     --- Calculate the target route point.
 
-    Coordinate.y = math.random( 50, 200 )    
+    Coordinate.y = Height
     
-    local _speed=Speed or Helicopter:GetSpeedMax()*0.5          
+    Speed = Speed or Helicopter:GetSpeedMax()*0.5          
 
     --- Create a route point of type air.
     local CoordinateFrom = Helicopter:GetCoordinate()
@@ -686,7 +589,7 @@ function AI_CARGO_HELICOPTER:onafterHome( Helicopter, From, Event, To, Coordinat
       "RADIO", 
       POINT_VEC3.RoutePointType.TurningPoint, 
       POINT_VEC3.RoutePointAction.TurningPoint, 
-      _speed, 
+      Speed , 
       true 
     )
     Route[#Route+1] = WaypointFrom
@@ -697,7 +600,7 @@ function AI_CARGO_HELICOPTER:onafterHome( Helicopter, From, Event, To, Coordinat
       "RADIO", 
       POINT_VEC3.RoutePointType.TurningPoint, 
       POINT_VEC3.RoutePointAction.TurningPoint, 
-      _speed, 
+      Speed , 
       true 
     )
 

Moose Development/Moose/AI/AI_Formation.lua

@@ -650,7 +650,7 @@ function AI_FORMATION:onafterFormationLine( FollowGroupSet, From , Event , To, X
   
   local FollowSet = FollowGroupSet:GetSet()
   
-  local i = 0
+  local i = 1  --FF i=0 caused first unit to have no XSpace! Probably needs further adjustments. This is just a quick work around.
   
   for FollowID, FollowGroup in pairs( FollowSet ) do
   

Moose Development/Moose/Actions/Act_Route.lua

@@ -362,7 +362,7 @@ do -- ACT_ROUTE_POINT
       local Distance = self.Coordinate:Get2DDistance( ProcessUnit:GetCoordinate() )
       
       if Distance <= self.Range then
-        local RouteText = "You have arrived."
+        local RouteText = "Task \"" .. self:GetTask():GetName() .. "\", you have arrived."
         self:GetCommandCenter():MessageTypeToGroup( RouteText, ProcessUnit:GetGroup(), MESSAGE.Type.Information )
         return true
       end
@@ -381,7 +381,7 @@ do -- ACT_ROUTE_POINT
   -- @param #string To
   function ACT_ROUTE_POINT:onafterReport( ProcessUnit, From, Event, To )
   
-    local RouteText = self:GetRouteText( ProcessUnit )
+    local RouteText = "Task \"" .. self:GetTask():GetName() .. "\", " .. self:GetRouteText( ProcessUnit )
     
     self:GetCommandCenter():MessageTypeToGroup( RouteText, ProcessUnit:GetGroup(), MESSAGE.Type.Update )
   end
@@ -453,7 +453,7 @@ do -- ACT_ROUTE_ZONE
   function ACT_ROUTE_ZONE:onfuncHasArrived( ProcessUnit )
 
     if ProcessUnit:IsInZone( self.Zone ) then
-      local RouteText = "You have arrived within the zone."
+      local RouteText = "Task \"" .. self:GetTask():GetName() .. "\", you have arrived within the zone."
       self:GetCommandCenter():MessageTypeToGroup( RouteText, ProcessUnit:GetGroup(), MESSAGE.Type.Information )
     end
 
@@ -471,7 +471,7 @@ do -- ACT_ROUTE_ZONE
   function ACT_ROUTE_ZONE:onafterReport( ProcessUnit, From, Event, To )
     self:F( { ProcessUnit = ProcessUnit } )
   
-    local RouteText = self:GetRouteText( ProcessUnit )
+    local RouteText = "Task \"" .. self:GetTask():GetName() .. "\", " .. self:GetRouteText( ProcessUnit )
     self:GetCommandCenter():MessageTypeToGroup( RouteText, ProcessUnit:GetGroup(), MESSAGE.Type.Update )
   end
 

Moose Development/Moose/Cargo/Cargo.lua

@@ -122,7 +122,7 @@
 -- 
 -- 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!!!
+-- # 5) Declare cargo directly in 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.
@@ -137,13 +137,23 @@
 -- 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!
+-- 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 will be reduced to about a few lines of code, providing you with a full dynamic cargo handling mission!
+-- 
+-- ## 5.1) Use \#CARGO tags in the mission editor:
+-- 
+-- MOOSE can create automatically cargo objects, if the name of the cargo contains the **\#CARGO** tag.
+-- When a mission starts, MOOSE will scan all group and static objects it found for the presence of the \#CARGO tag.
+-- When found, MOOSE will declare the object as cargo (create in the background a CARGO_ object, like CARGO_GROUP, CARGO_CRATE or CARGO_SLINGLOAD.
+-- The creation of these CARGO_ objects will allow to be filtered and automatically added in SET_CARGO objects.
+-- In other words, with very minimal code as explained in the above code section, you are able to create vast amounts of cargo objects just from within the editor.
 -- 
 -- What I talk about is this:
 -- 
+--      -- BEFORE THIS SCRIPT STARTS, MOOSE WILL ALREADY HAVE SCANNED FOR OBJECTS WITH THE #CARGO TAG IN THE NAME.
+--      -- FOR EACH OF THESE OBJECT, MOOSE WILL HAVE CREATED CARGO_ OBJECTS LIKE CARGO_GROUP, CARGO_CRATE AND CARGO_SLINGLOAD.
+-- 
 --      HQ = GROUP:FindByName( "HQ", "Bravo" )
 --      
 --      CommandCenter = COMMANDCENTER
@@ -156,34 +166,71 @@
 --      
 --      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.
+--      -- 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`.
+-- The above code example has the `CargoSetWorkmaterials`, which is a SET_CARGO collection and will include the CARGO_ objects of the type "Workmaterials".    
 -- 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!
+-- The \#CARGO tag even allows for several options to be specified, which are important to learn.
 -- 
--- 5.1) Name MOOSE cargo objects within the mission editor!
+-- ## 5.2) The \#CARGO tag to create CARGO_GROUP objects:
 -- 
+-- You can also use the \#CARGO tag on **group** objects of the mission editor.
 -- 
+-- For example, the following #CARGO naming in the **group name** of the object, will create a CARGO_GROUP object when the mission starts.
+-- 
+--   `Infantry #CARGO(T=Workmaterials,RR=500,NR=25)`
+-- 
+-- This will create a CARGO_GROUP object:
+-- 
+--    * with the group name `Infantry #CARGO`
+--    * is of type `Workmaterials`
+--    * will report when a carrier is within 500 meters
+--    * will board to carriers when the carrier is within 500 meters from the cargo object
+--    * will dissapear when the cargo is within 25 meters from the carrier during boarding
+-- 
+-- So the overall syntax of the #CARGO naming tag and arguments are:
+-- 
+--   `GroupName #CARGO(T=CargoTypeName,RR=Range,NR=Range)`
+-- 
+--    * **T=** Provide a text that contains the type name of the cargo object. This type name can be used to filter cargo within a SET_CARGO object.
+--    * **RR=** Provide the minimal range in meters when the report to the carrier, and board to the carrier.
+--      Note that this option is optional, so can be omitted. The default value of the RR is 250 meters.
+--    * **NR=** Provide the maximum range in meters when the cargo units will be boarded within the carrier during boarding.
+--      Note that this option is optional, so can be omitted. The default value of the RR is 10 meters.
+-- 
+-- ## 5.2) The \#CARGO tag to create CARGO_CRATE objects:
+-- 
+-- You can also use the \#CARGO tag on **static** objects, including **static cargo** objects of the mission editor.
+-- 
+-- For example, the following #CARGO naming in the **static name** of the object, will create a CARGO_CRATE object when the mission starts.
+-- 
+--   `Static #CARGO(T=Workmaterials,RR=500,NR=25)`
+-- 
+-- This will create a CARGO_CRATE object:
+-- 
+--    * with the group name `Static #CARGO`
+--    * is of type `Workmaterials`
+--    * will report when a carrier is within 500 meters
+--    * will board to carriers when the carrier is within 500 meters from the cargo object
+--    * will dissapear when the cargo is within 25 meters from the carrier during boarding
+-- 
+-- So the overall syntax of the #CARGO naming tag and arguments are:
+-- 
+--   `StaticName #CARGO(T=CargoTypeName,RR=Range,NR=Range)`
+-- 
+--    * **T=** Provide a text that contains the type name of the cargo object. This type name can be used to filter cargo within a SET_CARGO object.
+--    * **RR=** Provide the minimal range in meters when the report to the carrier, and board to the carrier.
+--      Note that this option is optional, so can be omitted. The default value of the RR is 250 meters.
+--    * **NR=** Provide the maximum range in meters when the cargo units will be boarded within the carrier during boarding.
+--      Note that this option is optional, so can be omitted. The default value of the RR is 10 meters.
 -- 
 -- ===
 -- 
@@ -424,7 +471,7 @@ do -- CARGO
     self.CargoLimit = 0
     
     self.LoadRadius = LoadRadius or 500
-    self.NearRadius = NearRadius or 25
+    --self.NearRadius = NearRadius or 25
     
     self:SetDeployed( false )
   
@@ -516,7 +563,7 @@ do -- CARGO
   -- @param #CARGO self
   function CARGO:Destroy()
     if self.CargoObject then
-      self.CargoObject:Destroy( false )
+      self.CargoObject:Destroy()
     end
     self:Destroyed()
   end
@@ -779,7 +826,8 @@ do -- CARGO
   
     local Distance = 0
     if self:IsUnLoaded() then
-      Distance = Coordinate:Get2DDistance( self.CargoObject:GetCoordinate() )
+      local CargoCoordinate = self.CargoObject:GetCoordinate()
+      Distance = Coordinate:Get2DDistance( CargoCoordinate )
       self:T( Distance )
       if Distance <= self.LoadRadius then
         return true
@@ -810,7 +858,7 @@ do -- CARGO
   end
 
 
-  --- Check if CargoCarrier is near the Cargo to be Loaded.
+  --- Check if CargoCarrier is near the coordinate within NearRadius.
   -- @param #CARGO self
   -- @param Core.Point#COORDINATE Coordinate
   -- @param #number NearRadius The radius when the cargo will board the Carrier (to avoid collision).
@@ -824,7 +872,7 @@ do -- CARGO
       --self:F( { CargoObjectVec2 = self.CargoObject:GetVec2() } )
       --self:F( { PointVec2 = PointVec2:GetVec2() } )
       local Distance = Coordinate:Get2DDistance( self.CargoObject:GetCoordinate() )
-      --self:F( Distance )
+      --self:F( { Distance = Distance, NearRadius = NearRadius or "nil" }  )
       
       if Distance <= NearRadius then
         --self:F( { PointVec2 = PointVec2, NearRadius = NearRadius, IsNear = true } )
@@ -875,6 +923,13 @@ do -- CARGO
     return self.CargoObject:GetCoordinate()
   end
   
+  --- Get the weight of the cargo.
+  -- @param #CARGO self
+  -- @return #number Weight The weight in kg.
+  function CARGO:GetWeight()
+    return self.Weight 
+  end
+  
   --- Set the weight of the cargo.
   -- @param #CARGO self
   -- @param #number Weight The weight in kg.
@@ -884,6 +939,22 @@ do -- CARGO
     return self
   end
   
+  --- Get the volume of the cargo.
+  -- @param #CARGO self
+  -- @return #number Volume The volume in kg.
+  function CARGO:GetVolume()
+    return self.Volume 
+  end
+  
+  --- Set the volume of the cargo.
+  -- @param #CARGO self
+  -- @param #number Volume The volume in kg.
+  -- @return #CARGO
+  function CARGO:SetVolume( Volume )
+    self.Volume = Volume
+    return self
+  end
+  
   --- Send a CC message to a @{Wrapper.Group}.
   -- @param #CARGO self
   -- @param #string Message
@@ -997,13 +1068,31 @@ do -- CARGO_REPRESENTABLE
   -- @param #CARGO_REPRESENTABLE self
   -- @param #string Type
   -- @param #string Name
-  -- @param #number Weight
   -- @param #number LoadRadius (optional)
   -- @param #number NearRadius (optional)
   -- @return #CARGO_REPRESENTABLE
-  function CARGO_REPRESENTABLE:New( CargoObject, Type, Name, Weight, LoadRadius, NearRadius )
-    local self = BASE:Inherit( self, CARGO:New( Type, Name, Weight, LoadRadius, NearRadius ) ) -- #CARGO_REPRESENTABLE
-    self:F( { Type, Name, Weight, LoadRadius, NearRadius } )
+  function CARGO_REPRESENTABLE:New( CargoObject, Type, Name, LoadRadius, NearRadius )
+    local self = BASE:Inherit( self, CARGO:New( Type, Name, 0, LoadRadius, NearRadius ) ) -- #CARGO_REPRESENTABLE
+    self:F( { Type, Name, LoadRadius, NearRadius } )
+
+    local Desc = CargoObject:GetDesc()
+    self:I( { Desc = Desc } )
+    local Weight = math.random( 80, 120 )
+    if Desc then
+      if Desc.typeName == "2B11 mortar" then
+        Weight = 210
+      else
+        Weight = Desc.massEmpty
+      end
+    end
+
+    self:SetWeight( Weight )      
+
+--      local Box = CargoUnit:GetBoundingBox()
+--      local VolumeUnit = ( Box.max.x - Box.min.x ) * ( Box.max.y - Box.min.y ) * ( Box.max.z - Box.min.z ) 
+--      self:I( { VolumeUnit = VolumeUnit, WeightUnit = WeightUnit } )
+    --self:SetVolume( VolumeUnit )
+
     
     return self
   end
@@ -1203,6 +1292,10 @@ end
 -- @param #string From
 -- @param #string To
 -- @param Wrapper.Unit#UNIT CargoCarrier
+-- @param #number Speed
+-- @param #number BoardDistance
+-- @param #number LoadDistance
+-- @param #number Angle
 function CARGO_PACKAGE:onafterOnBoarded( From, Event, To, CargoCarrier, Speed, BoardDistance, LoadDistance, Angle )
   self:F()
 
@@ -1218,6 +1311,7 @@ end
 -- @param #string Event
 -- @param #string From
 -- @param #string To
+-- @param Wrapper.Unit#UNIT CargoCarrier
 -- @param #number Speed
 -- @param #number UnLoadDistance
 -- @param #number UnBoardDistance
@@ -1261,6 +1355,7 @@ end
 -- @param #string From
 -- @param #string To
 -- @param Wrapper.Unit#UNIT CargoCarrier
+-- @param #number Speed
 function CARGO_PACKAGE:onafterUnBoarded( From, Event, To, CargoCarrier, Speed )
   self:F()
 
@@ -1304,6 +1399,8 @@ end
 -- @param #string Event
 -- @param #string From
 -- @param #string To
+-- @param Wrapper.Unit#UNIT CargoCarrier
+-- @param #number Speed
 -- @param #number Distance
 -- @param #number Angle
 function CARGO_PACKAGE:onafterUnLoad( From, Event, To, CargoCarrier, Speed, Distance, Angle )

Moose Development/Moose/Cargo/CargoCrate.lua

@@ -25,6 +25,18 @@ do -- CARGO_CRATE
   --- Defines a cargo that is represented by a UNIT object within the simulator, and can be transported by a carrier.
   -- Use the event functions as described above to Load, UnLoad, Board, UnBoard the CARGO\_CRATE objects to and from carriers.
   -- 
+  -- The above cargo classes are used by the following AI_CARGO_ classes to allow AI groups to transport cargo:
+  -- 
+  --   * AI Armoured Personnel Carriers to transport cargo and engage in battles, using the @{AI.AI_Cargo_APC} module.
+  --   * AI Helicopters to transport cargo, using the @{AI.AI_Cargo_Helicopter} module.
+  --   * AI Planes to transport cargo, using the @{AI.AI_Cargo_Airplane} module.
+  --   * AI Ships is planned.
+  -- 
+  -- The above cargo classes are also used by the TASK_CARGO_ classes to allow human players to transport cargo as part of a tasking:
+  -- 
+  --   * @{Tasking.Task_Cargo_Transport#TASK_CARGO_TRANSPORT} to transport cargo by human players.
+  --   * @{Tasking.Task_Cargo_Transport#TASK_CARGO_CSAR} to transport downed pilots by human players.
+  -- 
   -- ===
   -- 
   -- @field #CARGO_CRATE
@@ -51,9 +63,12 @@ do -- CARGO_CRATE
     
     self:HandleEvent( EVENTS.Dead, self.OnEventCargoDead )
     self:HandleEvent( EVENTS.Crash, self.OnEventCargoDead )
+    --self:HandleEvent( EVENTS.RemoveUnit, self.OnEventCargoDead )
     self:HandleEvent( EVENTS.PlayerLeaveUnit, self.OnEventCargoDead )
     
     self:SetEventPriority( 4 )
+    
+    self.NearRadius = NearRadius or 25
   
     return self
   end
@@ -141,7 +156,7 @@ do -- CARGO_CRATE
     if self.CargoObject then
       self:T("Destroying")
       self.NoDestroy = true
-      self.CargoObject:Destroy()
+      self.CargoObject:Destroy( false ) -- Do not generate a remove unit event, because we want to keep the template for later respawn in the database.
       --local Coordinate = self.CargoObject:GetCoordinate():GetRandomCoordinateInRadius( 50, 20 )
       --self.CargoObject:ReSpawnAt( Coordinate, 0 )
     end
@@ -159,6 +174,12 @@ do -- CARGO_CRATE
     return false
   end
 
+  --- Check if the cargo can be sling loaded.
+  -- @param #CARGO_CRATE self
+  function CARGO_CRATE:CanSlingload()
+    return false
+  end
+
   --- Check if Cargo Crate is in the radius for the Cargo to be reported.
   -- @param #CARGO_CRATE self
   -- @param Core.Point#COORDINATE Coordinate

Moose Development/Moose/Cargo/CargoGroup.lua

@@ -1,10 +1,6 @@
 --- **Cargo** -- Management of grouped cargo logistics, which are based on a @{Wrapper.Group} object.
 --
 -- ===
---
--- ![Banner Image](..\Presentations\CARGO\Dia1.JPG)
---
--- ===
 -- 
 -- ### [Demo Missions]()
 -- 
@@ -31,20 +27,18 @@ do -- CARGO_GROUP
   --- Defines a cargo that is represented by a @{Wrapper.Group} object within the simulator.
   -- The cargo can be Loaded, UnLoaded, Boarded, UnBoarded to and from Carriers.
   -- 
-  -- The above cargo classes are used by the AI\_CARGO\_ classes to allow AI groups to transport cargo:
+  -- The above cargo classes are used by the following AI_CARGO_ classes to allow AI groups to transport cargo:
   -- 
-  --   * AI Armoured Personnel Carriers to transport cargo and engage in battles, using the @{AI.AI_Cargo_APC#AI_CARGO_APC} class.
-  --   * AI Helicopters to transport cargo, using the @{AI.AI_Cargo_Helicopter#AI_CARGO_HELICOPTER} class.
-  --   * AI Planes to transport cargo, using the @{AI.AI_Cargo_Plane#AI_CARGO_PLANE} class.
+  --   * AI Armoured Personnel Carriers to transport cargo and engage in battles, using the @{AI.AI_Cargo_APC} module.
+  --   * AI Helicopters to transport cargo, using the @{AI.AI_Cargo_Helicopter} module.
+  --   * AI Planes to transport cargo, using the @{AI.AI_Cargo_Airplane} module.
   --   * AI Ships is planned.
   -- 
-  -- The above cargo classes are also used by the TASK\_CARGO\_ classes to allow human players to transport cargo as part of a tasking:
+  -- The above cargo classes are also used by the TASK_CARGO_ classes to allow human players to transport cargo as part of a tasking:
   -- 
   --   * @{Tasking.Task_Cargo_Transport#TASK_CARGO_TRANSPORT} to transport cargo by human players.
   --   * @{Tasking.Task_Cargo_Transport#TASK_CARGO_CSAR} to transport downed pilots by human players.
   -- 
-  -- The
-  --
   -- @field #CARGO_GROUP CARGO_GROUP
   -- 
   CARGO_GROUP = {
@@ -55,14 +49,14 @@ do -- CARGO_GROUP
   -- This make a new CARGO_GROUP from a @{Wrapper.Group} object.
   -- It will "ungroup" the group object within the sim, and will create a @{Set} of individual Unit objects.
   -- @param #CARGO_GROUP self
-  -- @param Wrapper.Group#GROUP CargoGroup
-  -- @param #string Type
-  -- @param #string Name
-  -- @param #number LoadRadius (optional)
-  -- @param #number NearRadius (optional)
-  -- @return #CARGO_GROUP
-  function CARGO_GROUP:New( CargoGroup, Type, Name, LoadRadius )
-    local self = BASE:Inherit( self, CARGO_REPORTABLE:New( Type, Name, 0, LoadRadius ) ) -- #CARGO_GROUP
+  -- @param Wrapper.Group#GROUP CargoGroup Group to be transported as cargo.
+  -- @param #string Type Cargo type, e.g. "Infantry". This is the type used in SET_CARGO:New():FilterTypes("Infantry") to define the valid cargo groups of the set.
+  -- @param #string Name A user defined name of the cargo group. This name CAN be the same as the group object but can also have a different name. This name MUST be unique!
+  -- @param #number LoadRadius (optional) Distance in meters until which a cargo is loaded into the carrier. Cargo outside this radius has to be routed by other means to within the radius to be loaded.
+  -- @param #number NearRadius (optional) Once the units are within this radius of the carrier, they are actually loaded, i.e. disappear from the scene.
+  -- @return #CARGO_GROUP Cargo group object.
+  function CARGO_GROUP:New( CargoGroup, Type, Name, LoadRadius, NearRadius )
+    local self = BASE:Inherit( self, CARGO_REPORTABLE:New( Type, Name, 0, LoadRadius, NearRadius ) ) -- #CARGO_GROUP
     self:F( { Type, Name, LoadRadius } )
   
     self.CargoSet = SET_CARGO:New()
@@ -70,46 +64,57 @@ do -- CARGO_GROUP
     self.Grouped = true
     self.CargoUnitTemplate = {}
     
+    self.NearRadius = NearRadius
+    
     self:SetDeployed( false )
     
     local WeightGroup = 0
+    local VolumeGroup = 0
     
-    self.CargoGroup:Destroy()
+    self.CargoGroup:Destroy() -- destroy and generate a unit removal event, so that the database gets cleaned, and the linked sets get properly cleaned.
 
     local GroupName = CargoGroup:GetName()
     self.CargoName = Name
     self.CargoTemplate = UTILS.DeepCopy( _DATABASE:GetGroupTemplate( GroupName ) )
 
-    local GroupTemplate = UTILS.DeepCopy( self.CargoTemplate )
-    GroupTemplate.name = self.CargoName .. "#CARGO"
-    GroupTemplate.groupId = nil
+    self.GroupTemplate = UTILS.DeepCopy( self.CargoTemplate )
+    self.GroupTemplate.name = self.CargoName .. "#CARGO"
+    self.GroupTemplate.groupId = nil
     
-    GroupTemplate.units = {}
+    self.GroupTemplate.units = {}
     
     for UnitID, UnitTemplate in pairs( self.CargoTemplate.units ) do
       UnitTemplate.name = UnitTemplate.name .. "#CARGO"
-      local CargoUnitName = UnitTemplate.name 
+      local CargoUnitName = UnitTemplate.name
       self.CargoUnitTemplate[CargoUnitName] = UnitTemplate      
 
-       GroupTemplate.units[#GroupTemplate.units+1] = self.CargoUnitTemplate[CargoUnitName]
-       GroupTemplate.units[#GroupTemplate.units].unitId = nil
+       self.GroupTemplate.units[#self.GroupTemplate.units+1] = self.CargoUnitTemplate[CargoUnitName]
+       self.GroupTemplate.units[#self.GroupTemplate.units].unitId = nil
       
       -- And we register the spawned unit as part of the CargoSet.
       local Unit = UNIT:Register( CargoUnitName )
-      --local WeightUnit = Unit:GetDesc().massEmpty
-      --WeightGroup = WeightGroup + WeightUnit
-      local CargoUnit = CARGO_UNIT:New( Unit, Type, CargoUnitName, 10 )
-      self.CargoSet:Add( CargoUnitName, CargoUnit )
+      
     end
 
     -- Then we register the new group in the database
-    self.CargoGroup = GROUP:NewTemplate( GroupTemplate, GroupTemplate.CoalitionID, GroupTemplate.CategoryID, GroupTemplate.CountryID)
+    self.CargoGroup = GROUP:NewTemplate( self.GroupTemplate, self.GroupTemplate.CoalitionID, self.GroupTemplate.CategoryID, self.GroupTemplate.CountryID )
     
     -- Now we spawn the new group based on the template created.
-    self.CargoObject = _DATABASE:Spawn( GroupTemplate )
+    self.CargoObject = _DATABASE:Spawn( self.GroupTemplate )
+    
+    for CargoUnitID, CargoUnit in pairs( self.CargoObject:GetUnits() ) do
+      
+
+      local CargoUnitName = CargoUnit:GetName()
+
+      local Cargo = CARGO_UNIT:New( CargoUnit, Type, CargoUnitName, LoadRadius, NearRadius )
+      self.CargoSet:Add( CargoUnitName, Cargo )
+
+      WeightGroup = WeightGroup + Cargo:GetWeight()
+
+    end
   
     self:SetWeight( WeightGroup )
-    self.CargoLimit = 10
     
     self:T( { "Weight Cargo", WeightGroup } )
   
@@ -118,6 +123,7 @@ do -- CARGO_GROUP
     
     self:HandleEvent( EVENTS.Dead, self.OnEventCargoDead )
     self:HandleEvent( EVENTS.Crash, self.OnEventCargoDead )
+    --self:HandleEvent( EVENTS.RemoveUnit, self.OnEventCargoDead )
     self:HandleEvent( EVENTS.PlayerLeaveUnit, self.OnEventCargoDead )
     
     self:SetEventPriority( 4 )
@@ -125,6 +131,35 @@ do -- CARGO_GROUP
     return self
   end
 
+
+  --- Respawn the CargoGroup.
+  -- @param #CARGO_GROUP self
+  function CARGO_GROUP:Respawn()
+
+    self:F( { "Respawning" } )
+
+    for CargoID, CargoData in pairs( self.CargoSet:GetSet() ) do
+      local Cargo = CargoData -- Cargo.Cargo#CARGO
+      Cargo:Destroy() -- Destroy the cargo and generate a remove unit event to update the sets.
+      Cargo:SetStartState( "UnLoaded" )
+    end
+
+    -- Now we spawn the new group based on the template created.
+    _DATABASE:Spawn( self.GroupTemplate )
+      
+    for CargoUnitID, CargoUnit in pairs( self.CargoObject:GetUnits() ) do
+
+      local CargoUnitName = CargoUnit:GetName()
+
+      local Cargo = CARGO_UNIT:New( CargoUnit, self.Type, CargoUnitName, self.LoadRadius )
+      self.CargoSet:Add( CargoUnitName, Cargo )
+
+    end
+  
+    self:SetDeployed( false )
+    self:SetStartState( "UnLoaded" )
+    
+  end
   
   --- Ungroup the cargo group into individual groups with one unit.
   -- This is required because by default a group will move in formation and this is really an issue for group control.
@@ -225,7 +260,8 @@ do -- CARGO_GROUP
   --- @param #CARGO_GROUP self
   -- @param Core.Event#EVENTDATA EventData 
   function CARGO_GROUP:OnEventCargoDead( EventData )
-    self:I( EventData )
+  
+    self:E(EventData)
 
     local Destroyed = false
   
@@ -257,14 +293,15 @@ do -- CARGO_GROUP
 
   --- Enter Boarding State.
   -- @param #CARGO_GROUP self
-  -- @param Wrapper.Unit#UNIT CargoCarrier
   -- @param #string Event
   -- @param #string From
   -- @param #string To
+  -- @param Wrapper.Unit#UNIT CargoCarrier
+  -- @param #number NearRadius If distance is smaller than this number, cargo is loaded into the carrier.
   function CARGO_GROUP:onenterBoarding( From, Event, To, CargoCarrier, NearRadius, ... )
-    --self:F( { CargoCarrier.UnitName, From, Event, To } )
+    self:F( { CargoCarrier.UnitName, From, Event, To, NearRadius = NearRadius } )
     
-    local NearRadius = NearRadius or 25
+    NearRadius = NearRadius or self.NearRadius
     
     if From == "UnLoaded" then
   
@@ -303,16 +340,15 @@ do -- CARGO_GROUP
   end
 
   --- Leave Boarding State.
-  -- @param #CARGO_GROUP self
-  -- @param Wrapper.Unit#UNIT CargoCarrier
+  -- @param #CARGO_GROUP self  
   -- @param #string Event
   -- @param #string From
   -- @param #string To
+  -- @param Wrapper.Unit#UNIT CargoCarrier
+  -- @param #number NearRadius If distance is smaller than this number, cargo is loaded into the carrier.
   function CARGO_GROUP:onafterBoarding( From, Event, To, CargoCarrier, NearRadius, ... )
     --self:F( { CargoCarrier.UnitName, From, Event, To } )
   
-    local NearRadius = NearRadius or 100
-  
     local Boarded = true
     local Cancelled = false
     local Dead = true
@@ -321,7 +357,7 @@ do -- CARGO_GROUP
   
     -- For each Cargo object within the CARGO_GROUP, route each object to the CargoLoadPointVec2
     for CargoID, Cargo in pairs( self.CargoSet:GetSet() ) do
-      self:T( { Cargo:GetName(), Cargo.current } )
+      --self:T( { Cargo:GetName(), Cargo.current } )
       
       
       if not Cargo:is( "Loaded" ) 
@@ -343,7 +379,7 @@ do -- CARGO_GROUP
   
       if not Cancelled then
         if not Boarded then
-          self:__Boarding( 1, CargoCarrier, NearRadius, ... )
+          self:__Boarding( -5, CargoCarrier, NearRadius, ... )
         else
           self:F("Group Cargo is loaded")
           self:__Load( 1, CargoCarrier, ... )
@@ -359,10 +395,11 @@ do -- CARGO_GROUP
 
   --- Enter UnBoarding State.
   -- @param #CARGO_GROUP self
-  -- @param Core.Point#POINT_VEC2 ToPointVec2
   -- @param #string Event
   -- @param #string From
   -- @param #string To
+  -- @param Core.Point#POINT_VEC2 ToPointVec2
+  -- @param #number NearRadius If distance is smaller than this number, cargo is loaded into the carrier.
   function CARGO_GROUP:onenterUnBoarding( From, Event, To, ToPointVec2, NearRadius, ... )
     self:F( {From, Event, To, ToPointVec2, NearRadius } )
   
@@ -388,7 +425,7 @@ do -- CARGO_GROUP
               ToVec=ToPointVec2
             end
             Cargo:__UnBoard( Timer, ToVec, NearRadius )
-            Timer = Timer + 3
+            Timer = Timer + 1
           end
         end, { NearRadius }
       )
@@ -401,10 +438,11 @@ do -- CARGO_GROUP
 
   --- Leave UnBoarding State.
   -- @param #CARGO_GROUP self
-  -- @param Core.Point#POINT_VEC2 ToPointVec2
   -- @param #string Event
   -- @param #string From
   -- @param #string To
+  -- @param Core.Point#POINT_VEC2 ToPointVec2
+  -- @param #number NearRadius If distance is smaller than this number, cargo is loaded into the carrier.
   function CARGO_GROUP:onleaveUnBoarding( From, Event, To, ToPointVec2, NearRadius, ... )
     --self:F( { From, Event, To, ToPointVec2, NearRadius } )
   
@@ -438,10 +476,11 @@ do -- CARGO_GROUP
 
   --- UnBoard Event.
   -- @param #CARGO_GROUP self
-  -- @param Core.Point#POINT_VEC2 ToPointVec2
   -- @param #string Event
   -- @param #string From
   -- @param #string To
+  -- @param Core.Point#POINT_VEC2 ToPointVec2
+  -- @param #number NearRadius If distance is smaller than this number, cargo is loaded into the carrier.
   function CARGO_GROUP:onafterUnBoarding( From, Event, To, ToPointVec2, NearRadius, ... )
     --self:F( { From, Event, To, ToPointVec2, NearRadius } )
   
@@ -454,10 +493,10 @@ do -- CARGO_GROUP
 
   --- Enter UnLoaded State.
   -- @param #CARGO_GROUP self
-  -- @param Core.Point#POINT_VEC2
   -- @param #string Event
   -- @param #string From
   -- @param #string To
+  -- @param Core.Point#POINT_VEC2
   function CARGO_GROUP:onenterUnLoaded( From, Event, To, ToPointVec2, ... )
     --self:F( { From, Event, To, ToPointVec2 } )
   
@@ -467,7 +506,7 @@ do -- CARGO_GROUP
       self.CargoSet:ForEach(
         function( Cargo )
           --Cargo:UnLoad( ToPointVec2 )
-          local RandomVec2=ToPointVec2:GetRandomPointVec2InRadius(10)
+          local RandomVec2=ToPointVec2:GetRandomPointVec2InRadius(20, 10)
           Cargo:UnLoad( RandomVec2 )
         end
       )
@@ -485,8 +524,6 @@ do -- CARGO_GROUP
   -- @return Core.Point#COORDINATE The current Coordinate of the first Cargo of the CargoGroup.
   -- @return #nil There is no valid Cargo in the CargoGroup.
   function CARGO_GROUP:GetCoordinate()
-    self:F()
-
     local Cargo = self:GetFirstAlive() -- Cargo.Cargo#CARGO
     
     if Cargo then
@@ -592,8 +629,7 @@ do -- CARGO_GROUP
   -- @param #CARGO_GROUP self
   -- @param Wrapper.Group#GROUP CargoCarrier
   -- @param #number NearRadius
-  -- @return #boolean The Cargo is near to the Carrier.
-  -- @return #nil The Cargo is not near to the Carrier.
+  -- @return #boolean The Cargo is near to the Carrier or #nil if the Cargo is not near to the Carrier.
   function CARGO_GROUP:IsNear( CargoCarrier, NearRadius )
     self:F( {NearRadius = NearRadius } )
     
@@ -621,10 +657,18 @@ do -- CARGO_GROUP
 
     if Cargo then
       local Distance = 0
+      local CargoCoordinate
       if Cargo:IsLoaded() then
-        Distance = Coordinate:Get2DDistance( Cargo.CargoCarrier:GetCoordinate() )
+        CargoCoordinate = Cargo.CargoCarrier:GetCoordinate()
       else
-        Distance = Coordinate:Get2DDistance( Cargo.CargoObject:GetCoordinate() )
+        CargoCoordinate = Cargo.CargoObject:GetCoordinate()
+      end
+
+      -- FF check if coordinate could be obtained. This was commented out for some (unknown) reason. But the check seems valid!      
+      if CargoCoordinate then
+        Distance = Coordinate:Get2DDistance( CargoCoordinate )
+      else
+        return false
       end
       
       self:F( { Distance = Distance, LoadRadius = self.LoadRadius } )
@@ -665,53 +709,6 @@ do -- CARGO_GROUP
   
   end
 
-  --- Respawn the CargoGroup.
-  -- @param #CARGO_GROUP self
-  function CARGO_GROUP:Respawn()
-
-    self:F( { "Respawning" } )
-
-    for CargoID, CargoData in pairs( self.CargoSet:GetSet() ) do
-      local Cargo = CargoData -- Cargo.Cargo#CARGO
-      Cargo:Destroy()
-      Cargo:SetStartState( "UnLoaded" )
-    end
-
-    
-    -- We iterate through the group template and for each unit in the template, we create a new group with one unit.
-    for UnitID, UnitTemplate in pairs( self.CargoTemplate.units ) do
-      
-      local GroupTemplate = UTILS.DeepCopy( self.CargoTemplate )
-      local GroupName = env.getValueDictByKey( GroupTemplate.name )
-      
-      -- We create a new group object with one unit...
-      -- First we prepare the template...
-      GroupTemplate.name = GroupName .. "#CARGO#" .. UnitID
-      GroupTemplate.groupId = nil
-      GroupTemplate.units = {}
-      GroupTemplate.units[1] = UnitTemplate
-      local UnitName = UnitTemplate.name .. "#CARGO"
-      GroupTemplate.units[1].name = UnitTemplate.name .. "#CARGO"
-  
-  
-      -- Then we register the new group in the database
-      local CargoGroup = GROUP:NewTemplate( GroupTemplate, GroupTemplate.CoalitionID, GroupTemplate.CategoryID, GroupTemplate.CountryID)
-      
-      -- Now we spawn the new group based on the template created.
-      _DATABASE:Spawn( GroupTemplate )
-      
-      -- And we register the spawned unit as part of the CargoSet.
-      local Unit = UNIT:FindByName( UnitName )
-      --local WeightUnit = Unit:GetDesc().massEmpty
-      --WeightGroup = WeightGroup + WeightUnit
-      local CargoUnit = CARGO_UNIT:New( Unit, Type, UnitName, 10 )
-      self.CargoSet:Add( UnitName, CargoUnit )
-    end
-
-    self:SetDeployed( false )
-    self:SetStartState( "UnLoaded" )
-    
-  end
 
   --- Signal a flare at the position of the CargoGroup.
   -- @param #CARGO_GROUP self

Moose Development/Moose/Cargo/CargoSlingload.lua

@@ -25,6 +25,11 @@ do -- CARGO_SLINGLOAD
   
   --- Defines a cargo that is represented by a UNIT object within the simulator, and can be transported by a carrier.
   -- 
+  -- The above cargo classes are also used by the TASK_CARGO_ classes to allow human players to transport cargo as part of a tasking:
+  -- 
+  --   * @{Tasking.Task_Cargo_Transport#TASK_CARGO_TRANSPORT} to transport cargo by human players.
+  --   * @{Tasking.Task_Cargo_Transport#TASK_CARGO_CSAR} to transport downed pilots by human players.
+  -- 
   -- ===
   -- 
   -- @field #CARGO_SLINGLOAD
@@ -51,9 +56,12 @@ do -- CARGO_SLINGLOAD
     
     self:HandleEvent( EVENTS.Dead, self.OnEventCargoDead )
     self:HandleEvent( EVENTS.Crash, self.OnEventCargoDead )
+    --self:HandleEvent( EVENTS.RemoveUnit, self.OnEventCargoDead )
     self:HandleEvent( EVENTS.PlayerLeaveUnit, self.OnEventCargoDead )
     
     self:SetEventPriority( 4 )
+    
+    self.NearRadius = NearRadius or 25
   
     return self
   end

Moose Development/Moose/Cargo/CargoUnit.lua

@@ -23,7 +23,10 @@ do -- CARGO_UNIT
   -- @extends Cargo.Cargo#CARGO_REPRESENTABLE
   
   --- Defines a cargo that is represented by a UNIT object within the simulator, and can be transported by a carrier.
-  -- Use the event functions as described above to Load, UnLoad, Board, UnBoard the CARGO\_UNIT objects to and from carriers.
+  -- Use the event functions as described above to Load, UnLoad, Board, UnBoard the CARGO_UNIT objects to and from carriers.
+  -- Note that ground forces behave in a group, and thus, act in formation, regardless if one unit is commanded to move.
+  -- 
+  -- This class is used in CARGO_GROUP, and is not meant to be used by mission designers individually.
   -- 
   -- ===
   -- 
@@ -42,9 +45,9 @@ do -- CARGO_UNIT
   -- @param #number LoadRadius (optional)
   -- @param #number NearRadius (optional)
   -- @return #CARGO_UNIT
-  function CARGO_UNIT:New( CargoUnit, Type, Name, Weight, NearRadius )
-    local self = BASE:Inherit( self, CARGO_REPRESENTABLE:New( CargoUnit, Type, Name, Weight, NearRadius ) ) -- #CARGO_UNIT
-    self:I( { Type, Name, Weight, NearRadius } )
+  function CARGO_UNIT:New( CargoUnit, Type, Name, LoadRadius, NearRadius )
+    local self = BASE:Inherit( self, CARGO_REPRESENTABLE:New( CargoUnit, Type, Name, LoadRadius, NearRadius ) ) -- #CARGO_UNIT
+    self:I( { Type, Name, LoadRadius, NearRadius } )
   
     self:T( CargoUnit )
     self.CargoObject = CargoUnit
@@ -62,11 +65,10 @@ do -- CARGO_UNIT
   -- @param #string From
   -- @param #string To
   -- @param Core.Point#POINT_VEC2 ToPointVec2
+  -- @param #number NearRadius (optional) Defaut 25 m.
   function CARGO_UNIT:onenterUnBoarding( From, Event, To, ToPointVec2, NearRadius )
     self:F( { From, Event, To, ToPointVec2, NearRadius } )
   
-    NearRadius = NearRadius or 25
-  
     local Angle = 180
     local Speed = 60
     local DeployDistance = 9
@@ -131,11 +133,10 @@ do -- CARGO_UNIT
   -- @param #string From
   -- @param #string To
   -- @param Core.Point#POINT_VEC2 ToPointVec2
+  -- @param #number NearRadius (optional) Defaut 100 m.
   function CARGO_UNIT:onleaveUnBoarding( From, Event, To, ToPointVec2, NearRadius )
     self:F( { From, Event, To, ToPointVec2, NearRadius } )
   
-    NearRadius = NearRadius or 100
-  
     local Angle = 180
     local Speed = 10
     local Distance = 5
@@ -158,11 +159,10 @@ do -- CARGO_UNIT
   -- @param #string From
   -- @param #string To
   -- @param Core.Point#POINT_VEC2 ToPointVec2
+  -- @param #number NearRadius (optional) Defaut 100 m.
   function CARGO_UNIT:onafterUnBoarding( From, Event, To, ToPointVec2, NearRadius )
     self:F( { From, Event, To, ToPointVec2, NearRadius } )
   
-    NearRadius = NearRadius or 100
-  
     self.CargoInAir = self.CargoObject:InAir()
   
     self:T( self.CargoInAir )
@@ -220,11 +220,11 @@ do -- CARGO_UNIT
   -- @param #string Event
   -- @param #string From
   -- @param #string To
+  -- @param Wrapper.Group#GROUP CargoCarrier
+  -- @param #number NearRadius
   function CARGO_UNIT:onafterBoard( From, Event, To, CargoCarrier, NearRadius, ... )
-    self:F( { From, Event, To, CargoCarrier, NearRadius } )
+    self:F( { From, Event, To, CargoCarrier, NearRadius = NearRadius } )
   
-    local NearRadius = NearRadius or 25
-    
     self.CargoInAir = self.CargoObject:InAir()
     
     local Desc = self.CargoObject:GetDesc()
@@ -236,6 +236,9 @@ do -- CARGO_UNIT
     -- Only move the group to the carrier when the cargo is not in the air
     -- (eg. cargo can be on a oil derrick, moving the cargo on the oil derrick will drop the cargo on the sea).
     if not self.CargoInAir then
+      -- If NearRadius is given, then use the given NearRadius, otherwise calculate the NearRadius 
+      -- based upon the Carrier bounding radius, which is calculated from the bounding rectangle on the Y axis.
+      local NearRadius = NearRadius or CargoCarrier:GetBoundingRadius() + 5
       if self:IsNear( CargoCarrier:GetPointVec2(), NearRadius ) then
         self:Load( CargoCarrier, NearRadius, ... )
       else
@@ -245,10 +248,8 @@ do -- CARGO_UNIT
           
           local Speed = 90
           local Angle = 180
-          local Distance = 5
+          local Distance = 0
           
-          NearRadius = NearRadius or 25
-        
           local CargoCarrierPointVec2 = CargoCarrier:GetPointVec2()
           local CargoCarrierHeading = CargoCarrier:GetHeading() -- Get Heading of object in degrees.
           local CargoDeployHeading = ( ( CargoCarrierHeading + Angle ) >= 360 ) and ( CargoCarrierHeading + Angle - 360 ) or ( CargoCarrierHeading + Angle )
@@ -266,7 +267,7 @@ do -- CARGO_UNIT
           
           local TaskRoute = self.CargoObject:TaskRoute( Points )
           self.CargoObject:SetTask( TaskRoute, 2 )
-          self:__Boarding( -1, CargoCarrier, NearRadius )
+          self:__Boarding( -5, CargoCarrier, NearRadius, ... )
           self.RunCount = 0
         end
       end
@@ -281,26 +282,30 @@ do -- CARGO_UNIT
   -- @param #string From
   -- @param #string To
   -- @param Wrapper.Client#CLIENT CargoCarrier
-  -- @param #number NearRadius
+  -- @param #number NearRadius Default 25 m.
   function CARGO_UNIT:onafterBoarding( From, Event, To, CargoCarrier, NearRadius, ... )
-    --self:F( { From, Event, To, CargoCarrier.UnitName, NearRadius } )
+    self:F( { From, Event, To, CargoCarrier:GetName(), NearRadius = NearRadius } )
     
     
     if CargoCarrier and CargoCarrier:IsAlive() and self.CargoObject and self.CargoObject:IsAlive() then 
-      if CargoCarrier:InAir() == false then
+      if (CargoCarrier:IsAir() and not CargoCarrier:InAir()) or true then
+        local NearRadius = NearRadius or CargoCarrier:GetBoundingRadius( NearRadius ) + 5
         if self:IsNear( CargoCarrier:GetPointVec2(), NearRadius ) then
           self:__Load( 1, CargoCarrier, ... )
         else
-          self:__Boarding( -1, CargoCarrier, NearRadius, ... )
-          self.RunCount = self.RunCount + 1
+          if self:IsNear( CargoCarrier:GetPointVec2(), 20 ) then
+            self:__Boarding( -1, CargoCarrier, NearRadius, ... )
+            self.RunCount = self.RunCount + 1
+          else
+            self:__Boarding( -2, CargoCarrier, NearRadius, ... )
+            self.RunCount = self.RunCount + 2
+          end
           if self.RunCount >= 40 then
             self.RunCount = 0
             local Speed = 90
             local Angle = 180
-            local Distance = 5
+            local Distance = 0
             
-            NearRadius = NearRadius or 25
-          
             local CargoCarrierPointVec2 = CargoCarrier:GetPointVec2()
             local CargoCarrierHeading = CargoCarrier:GetHeading() -- Get Heading of object in degrees.
             local CargoDeployHeading = ( ( CargoCarrierHeading + Angle ) >= 360 ) and ( CargoCarrierHeading + Angle - 360 ) or ( CargoCarrierHeading + Angle )
@@ -338,6 +343,7 @@ do -- CARGO_UNIT
   -- @param #string From
   -- @param #string To
   -- @param Wrapper.Unit#UNIT CargoCarrier
+  -- @param #number NearRadius Default 25 m.
   function CARGO_UNIT:onenterBoarding( From, Event, To, CargoCarrier, NearRadius, ... )
     --self:F( { From, Event, To, CargoCarrier.UnitName, NearRadius } )
     
@@ -345,8 +351,6 @@ do -- CARGO_UNIT
     local Angle = 180
     local Distance = 5
     
-    local NearRadius = NearRadius or 25
-  
     if From == "UnLoaded" or From == "Boarding" then
     
     end

Moose Development/Moose/Core/Base.lua

@@ -1,4 +1,22 @@
---- **Core** -- BASE forms **the basis of the MOOSE framework**. Each class within the MOOSE framework derives from BASE.
+--- **Core** - The base class within the framework.
+-- 
+-- ===
+-- 
+-- ## Features:
+-- 
+--   * The construction and inheritance of MOOSE classes.
+--   * The class naming and numbering system.
+--   * The class hierarchy search system.
+--   * The tracing of information or objects during mission execution for debuggin purposes.
+--   * The subscription to DCS events for event handling in MOOSE objects.
+--   * Object inspection.
+-- 
+-- ===
+-- 
+-- All classes within the MOOSE framework are derived from the BASE class.
+-- Note: The BASE class is an abstract class and is not meant to be used directly.
+-- 
+-- ===
 -- 
 -- ### Author: **FlightControl**
 -- ### Contributions: 
@@ -23,24 +41,14 @@ local _ClassID = 0
 -- @field ClassID The ID number of the class.
 -- @field ClassNameAndID The name of the class concatenated with the ID number of the class.
 
---- All classes within the MOOSE framework are derived from the BASE class. 
---  
--- BASE provides facilities for :
--- 
---   * The construction and inheritance of MOOSE classes.
---   * The class naming and numbering system.
---   * The class hierarchy search system.
---   * The tracing of information or objects during mission execution for debuggin purposes.
---   * The subscription to DCS events for event handling in MOOSE objects.
--- 
--- Note: The BASE class is an abstract class and is not meant to be used directly.
--- 
--- ## 1.1) BASE constructor
+--- BASE class
+--
+-- # 1. BASE constructor.
 -- 
 -- Any class derived from BASE, will use the @{Core.Base#BASE.New} constructor embedded in the @{Core.Base#BASE.Inherit} method. 
 -- See an example at the @{Core.Base#BASE.New} method how this is done.
 -- 
--- ## 1.2) Trace information for debugging
+-- # 2. Trace information for debugging.
 -- 
 -- The BASE class contains trace methods to trace progress within a mission execution of a certain object.
 -- These trace methods are inherited by each MOOSE class interiting BASE, soeach object created from derived class from BASE can use the tracing methods to trace its execution.
@@ -71,7 +79,7 @@ local _ClassID = 0
 -- 
 -- Below a more detailed explanation of the different method types for tracing.
 -- 
--- ### 1.2.1) Tracing methods categories
+-- ## 2.1. Tracing methods categories.
 --
 -- There are basically 3 types of tracing methods available:
 -- 
@@ -79,9 +87,9 @@ local _ClassID = 0
 --   * @{#BASE.T}: Used to trace further logic within a function giving optional variables or parameters. A T is indicated at column 44 in the DCS.log file.
 --   * @{#BASE.E}: Used to always trace information giving optional variables or parameters. An E is indicated at column 44 in the DCS.log file.
 -- 
--- ### 1.2.2) Tracing levels
+-- ## 2.2 Tracing levels.
 --
--- There are 3 tracing levels within MOOSE.  
+-- There are 3 tracing levels within MOOSE.    
 -- These tracing levels were defined to avoid bulks of tracing to be generated by lots of objects.
 -- 
 -- As such, the F and T methods have additional variants to trace level 2 and 3 respectively:
@@ -91,7 +99,7 @@ local _ClassID = 0
 --   * @{#BASE.T2}: Trace further logic within a function giving optional variables or parameters with tracing level 2.
 --   * @{#BASE.T3}: Trace further logic within a function giving optional variables or parameters with tracing level 3.
 -- 
--- ### 1.2.3) Trace activation.
+-- ## 2.3. Trace activation.
 -- 
 -- Tracing can be activated in several ways:
 -- 
@@ -101,16 +109,17 @@ local _ClassID = 0
 --   * Activate only the tracing of a certain method of a certain class through the @{#BASE.TraceClassMethod}() method.
 --   * Activate only the tracing of a certain level through the @{#BASE.TraceLevel}() method.
 -- 
--- ### 1.2.4) Check if tracing is on.
+-- ## 2.4. Check if tracing is on.
 -- 
 -- The method @{#BASE.IsTrace}() will validate if tracing is activated or not.
 -- 
--- ## 1.3 DCS simulator Event Handling
+-- 
+-- # 3. DCS simulator Event Handling.
 -- 
 -- The BASE class provides methods to catch DCS Events. These are events that are triggered from within the DCS simulator, 
 -- and handled through lua scripting. MOOSE provides an encapsulation to handle these events more efficiently.
 -- 
--- ### 1.3.1 Subscribe / Unsubscribe to DCS Events
+-- ## 3.1. Subscribe / Unsubscribe to DCS Events.
 -- 
 -- At first, the mission designer will need to **Subscribe** to a specific DCS event for the class.
 -- So, when the DCS event occurs, the class will be notified of that event.
@@ -119,7 +128,7 @@ local _ClassID = 0
 --   * @{#BASE.HandleEvent}(): Subscribe to a DCS Event.
 --   * @{#BASE.UnHandleEvent}(): Unsubscribe from a DCS Event.
 -- 
--- ### 1.3.2 Event Handling of DCS Events
+-- ## 3.2. Event Handling of DCS Events.
 -- 
 -- Once the class is subscribed to the event, an **Event Handling** method on the object or class needs to be written that will be called
 -- when the DCS event occurs. The Event Handling method receives an @{Core.Event#EVENTDATA} structure, which contains a lot of information
@@ -154,7 +163,7 @@ local _ClassID = 0
 -- 
 -- See the @{Event} module for more information about event handling.
 -- 
--- ## 1.4) Class identification methods
+-- # 4. Class identification methods.
 -- 
 -- BASE provides methods to get more information of each object:
 -- 
@@ -162,7 +171,7 @@ local _ClassID = 0
 --   * @{#BASE.GetClassName}(): Gets the name of the object, which is the name of the class the object was instantiated from.
 --   * @{#BASE.GetClassNameAndID}(): Gets the name and ID of the object.
 -- 
--- ## 1.5) All objects derived from BASE can have "States"
+-- # 5. All objects derived from BASE can have "States".
 -- 
 -- A mechanism is in place in MOOSE, that allows to let the objects administer **states**.  
 -- States are essentially properties of objects, which are identified by a **Key** and a **Value**.  
@@ -177,7 +186,7 @@ local _ClassID = 0
 -- Thus, if the state is to be set for the same object as the object for which the method is used, then provide the same
 -- object name to the method.
 -- 
--- ## 1.10) Inheritance
+-- # 6. Inheritance.
 -- 
 -- The following methods are available to implement inheritance
 -- 
@@ -186,8 +195,7 @@ local _ClassID = 0
 -- 
 -- ===
 -- 
--- @field #BASE BASE
--- 
+-- @field #BASE
 BASE = {
   ClassName = "BASE",
   ClassID = 0,
@@ -656,6 +664,22 @@ function BASE:CreateEventDead( EventTime, Initiator )
   world.onEvent( Event )
 end
 
+--- Creation of a Remove Unit Event.
+-- @param #BASE self
+-- @param DCS#Time EventTime The time stamp of the event.
+-- @param DCS#Object Initiator The initiating object of the event.
+function BASE:CreateEventRemoveUnit( EventTime, Initiator )
+  self:F( { EventTime, Initiator } )
+
+  local Event = {
+    id = EVENTS.RemoveUnit,
+    time = EventTime,
+    initiator = Initiator,
+    }
+
+  world.onEvent( Event )
+end
+
 --- Creation of a Takeoff Event.
 -- @param #BASE self
 -- @param DCS#Time EventTime The time stamp of the event.
@@ -798,8 +822,7 @@ end
 -- @param Object The object that will hold the Value set by the Key.
 -- @param Key The key that is used as a reference of the value. Note that the key can be a #string, but it can also be any other type!
 -- @param Value The value to is stored in the object.
--- @return The Value set.
--- @return #nil The Key was not found and thus the Value could not be retrieved.
+-- @return The Value set. 
 function BASE:SetState( Object, Key, Value )
 
   local ClassNameAndID = Object:GetClassNameAndID()
@@ -816,7 +839,7 @@ end
 -- @param #BASE self
 -- @param Object The object that holds the Value set by the Key.
 -- @param Key The key that is used to retrieve the value. Note that the key can be a #string, but it can also be any other type!
--- @return The Value retrieved.
+-- @return The Value retrieved or nil if the Key was not found and thus the Value could not be retrieved.
 function BASE:GetState( Object, Key )
 
   local ClassNameAndID = Object:GetClassNameAndID()
@@ -829,6 +852,10 @@ function BASE:GetState( Object, Key )
   return nil
 end
 
+--- Clear the state of an object.
+-- @param #BASE self
+-- @param Object The object that holds the Value set by the Key.
+-- @param StateName The key that is should be cleared.
 function BASE:ClearState( Object, StateName )
 
   local ClassNameAndID = Object:GetClassNameAndID()

Moose Development/Moose/Core/Database.lua

@@ -1,4 +1,25 @@
---- **Core** -- DATABASE manages the database of mission objects. 
+--- **Core** - Manages several databases containing templates, mission objects, and mission information. 
+-- 
+-- ===
+-- 
+-- ## Features:
+-- 
+--   * During mission startup, scan the mission environment, and create / instantiate intelligently the different objects as defined within the mission.
+--   * Manage database of DCS Group templates (as modelled using the mission editor).
+--     - Group templates.
+--     - Unit templates.
+--     - Statics templates.
+--   * Manage database of @{Wrapper.Group#GROUP} objects alive in the mission.
+--   * Manage database of @{Wrapper.Unit#UNIT} objects alive in the mission.
+--   * Manage database of @{Wrapper.Static#STATIC} objects alive in the mission.
+--   * Manage database of players.
+--   * Manage database of client slots defined using the mission editor.
+--   * Manage database of airbases on the map, and from FARPs and ships as defined using the mission editor.
+--   * Manage database of countries.
+--   * Manage database of zone names.
+--   * Manage database of hits to units and statics.
+--   * Manage database of destroys of units and statics.
+--   * Manage database of @{Core.Zone#ZONE_BASE} objects.
 -- 
 -- ===
 -- 
@@ -95,6 +116,7 @@ function DATABASE:New()
   self:HandleEvent( EVENTS.Birth, self._EventOnBirth )
   self:HandleEvent( EVENTS.Dead, self._EventOnDeadOrCrash )
   self:HandleEvent( EVENTS.Crash, self._EventOnDeadOrCrash )
+  self:HandleEvent( EVENTS.RemoveUnit, self._EventOnDeadOrCrash )
   self:HandleEvent( EVENTS.Hit, self.AccountHits )
   self:HandleEvent( EVENTS.NewCargo )
   self:HandleEvent( EVENTS.DeleteCargo )
@@ -187,7 +209,10 @@ function DATABASE:AddStatic( DCSStaticName )
 
   if not self.STATICS[DCSStaticName] then
     self.STATICS[DCSStaticName] = STATIC:Register( DCSStaticName )
+    return self.STATICS[DCSStaticName]
   end
+  
+  return nil
 end
 
 
@@ -306,9 +331,9 @@ do -- Zones
     end
   
     for ZoneGroupName, ZoneGroup in pairs( self.GROUPS ) do
-      if ZoneGroupName:match("~ZONE_POLYGON") then
-        local ZoneName1 = ZoneGroupName:match("(.*)~ZONE_POLYGON")
-        local ZoneName2 = ZoneGroupName:match(".*~ZONE_POLYGON(.*)")
+      if ZoneGroupName:match("#ZONE_POLYGON") then
+        local ZoneName1 = ZoneGroupName:match("(.*)#ZONE_POLYGON")
+        local ZoneName2 = ZoneGroupName:match(".*#ZONE_POLYGON(.*)")
         local ZoneName = ZoneName1 .. ( ZoneName2 or "" )
         
         self:I( { "Register ZONE_POLYGON:", Name = ZoneName } )
@@ -355,7 +380,7 @@ do -- cargo
     return CargoFound
   end
   
-  --- Checks if the Template name has a ~CARGO tag.
+  --- Checks if the Template name has a #CARGO tag.
   -- If yes, the group is a cargo.
   -- @param #DATABASE self
   -- @param #string TemplateName
@@ -364,7 +389,7 @@ do -- cargo
 
     TemplateName = env.getValueDictByKey( TemplateName )
   
-    local Cargo = TemplateName:match( "~(CARGO)" )
+    local Cargo = TemplateName:match( "#(CARGO)" )
 
     return Cargo and Cargo == "CARGO"    
   end
@@ -374,14 +399,15 @@ do -- cargo
   -- @return #DATABASE self
   function DATABASE:_RegisterCargos()
 
+    local Groups = UTILS.DeepCopy( self.GROUPS ) -- This is a very important statement. CARGO_GROUP:New creates a new _DATABASE.GROUP entry, which will confuse the loop. I searched 4 hours on this to find the bug!
   
-    for CargoGroupName, CargoGroup in pairs( self.GROUPS ) do
+    for CargoGroupName, CargoGroup in pairs( Groups ) do
+      self:I( { Cargo = CargoGroupName } )
       if self:IsCargo( CargoGroupName ) then
-        local CargoInfo = CargoGroupName:match("~CARGO(.*)")
+        local CargoInfo = CargoGroupName:match("#CARGO(.*)")
         local CargoParam = CargoInfo and CargoInfo:match( "%((.*)%)")
-        local CargoName1 = CargoGroupName:match("(.*)~CARGO%(.*%)")
-        local CargoName2 = CargoGroupName:match(".*~CARGO%(.*%)(.*)")
-        self:E({CargoName1 = CargoName1, CargoName2 = CargoName2 })
+        local CargoName1 = CargoGroupName:match("(.*)#CARGO%(.*%)")
+        local CargoName2 = CargoGroupName:match(".*#CARGO%(.*%)(.*)")
         local CargoName = CargoName1 .. ( CargoName2 or "" )
         local Type = CargoParam and CargoParam:match( "T=([%a%d ]+),?")
         local Name = CargoParam and CargoParam:match( "N=([%a%d]+),?") or CargoName
@@ -395,9 +421,9 @@ do -- cargo
     
     for CargoStaticName, CargoStatic in pairs( self.STATICS ) do
       if self:IsCargo( CargoStaticName ) then
-        local CargoInfo = CargoStaticName:match("~CARGO(.*)")
+        local CargoInfo = CargoStaticName:match("#CARGO(.*)")
         local CargoParam = CargoInfo and CargoInfo:match( "%((.*)%)")
-        local CargoName = CargoStaticName:match("(.*)~CARGO")
+        local CargoName = CargoStaticName:match("(.*)#CARGO")
         local Type = CargoParam and CargoParam:match( "T=([%a%d ]+),?")
         local Category = CargoParam and CargoParam:match( "C=([%a%d ]+),?")
         local Name = CargoParam and CargoParam:match( "N=([%a%d]+),?") or CargoName
@@ -459,7 +485,7 @@ end
 function DATABASE:AddGroup( GroupName )
 
   if not self.GROUPS[GroupName] then
-    self:E( { "Add GROUP:", GroupName } )
+    self:I( { "Add GROUP:", GroupName } )
     self.GROUPS[GroupName] = GROUP:Register( GroupName )
   end  
   
@@ -471,7 +497,7 @@ end
 function DATABASE:AddPlayer( UnitName, PlayerName )
 
   if PlayerName then
-    self:E( { "Add player for unit:", UnitName, PlayerName } )
+    self:I( { "Add player for unit:", UnitName, PlayerName } )
     self.PLAYERS[PlayerName] = UnitName
     self.PLAYERUNITS[PlayerName] = self:FindUnit( UnitName )
     self.PLAYERSJOINED[PlayerName] = PlayerName
@@ -483,7 +509,7 @@ end
 function DATABASE:DeletePlayer( UnitName, PlayerName )
 
   if PlayerName then
-    self:E( { "Clean player:", PlayerName } )
+    self:I( { "Clean player:", PlayerName } )
     self.PLAYERS[PlayerName] = nil
     self.PLAYERUNITS[PlayerName] = nil
   end
@@ -533,8 +559,8 @@ end
 -- SpawnCountryID, SpawnCategoryID
 -- This method is used by the SPAWN class.
 -- @param #DATABASE self
--- @param #table SpawnTemplate
--- @return #DATABASE self
+-- @param #table SpawnTemplate Template of the group to spawn.
+-- @return Wrapper.Group#GROUP Spawned group.
 function DATABASE:Spawn( SpawnTemplate )
   self:F( SpawnTemplate.name )
 
@@ -667,10 +693,12 @@ end
 
 --- Private method that registers new Static Templates within the DATABASE Object.
 -- @param #DATABASE self
--- @param #table GroupTemplate
+-- @param #table StaticTemplate
 -- @return #DATABASE self
 function DATABASE:_RegisterStaticTemplate( StaticTemplate, CoalitionID, CategoryID, CountryID )
 
+  local StaticTemplate = UTILS.DeepCopy( StaticTemplate )
+
   local StaticTemplateName = env.getValueDictByKey(StaticTemplate.name)
   
   self.Templates.Statics[StaticTemplateName] = self.Templates.Statics[StaticTemplateName] or {}
@@ -699,11 +727,17 @@ end
 
 
 --- @param #DATABASE self
-function DATABASE:GetStaticUnitTemplate( StaticName )
-  local StaticTemplate = self.Templates.Statics[StaticName].UnitTemplate
+function DATABASE:GetStaticGroupTemplate( StaticName )
+  local StaticTemplate = self.Templates.Statics[StaticName].GroupTemplate
   return StaticTemplate, self.Templates.Statics[StaticName].CoalitionID, self.Templates.Statics[StaticName].CategoryID, self.Templates.Statics[StaticName].CountryID
 end
 
+--- @param #DATABASE self
+function DATABASE:GetStaticUnitTemplate( StaticName )
+  local UnitTemplate = self.Templates.Statics[StaticName].UnitTemplate
+  return UnitTemplate, self.Templates.Statics[StaticName].CoalitionID, self.Templates.Statics[StaticName].CategoryID, self.Templates.Statics[StaticName].CountryID
+end
+
 
 function DATABASE:GetGroupNameFromUnitName( UnitName )
   return self.Templates.Units[UnitName].GroupName
@@ -750,7 +784,7 @@ function DATABASE:_RegisterPlayers()
         local UnitName = UnitData:getName()
         local PlayerName = UnitData:getPlayerName()
         if not self.PLAYERS[PlayerName] then
-          self:E( { "Add player for unit:", UnitName, PlayerName } )
+          self:I( { "Add player for unit:", UnitName, PlayerName } )
           self:AddPlayer( UnitName, PlayerName )
         end
       end
@@ -773,13 +807,13 @@ function DATABASE:_RegisterGroupsAndUnits()
       if DCSGroup:isExist() then
         local DCSGroupName = DCSGroup:getName()
   
-        self:E( { "Register Group:", DCSGroupName } )
+        self:I( { "Register Group:", DCSGroupName } )
         self:AddGroup( DCSGroupName )
 
         for DCSUnitId, DCSUnit in pairs( DCSGroup:getUnits() ) do
   
           local DCSUnitName = DCSUnit:getName()
-          self:E( { "Register Unit:", DCSUnitName } )
+          self:I( { "Register Unit:", DCSUnitName } )
           self:AddUnit( DCSUnitName )
         end
       else
@@ -788,6 +822,11 @@ function DATABASE:_RegisterGroupsAndUnits()
       
     end
   end
+  
+  self:I("Groups:")
+  for GroupName, Group in pairs( self.GROUPS ) do
+    self:I( { "Group:", GroupName } )
+  end
 
   return self
 end
@@ -798,7 +837,7 @@ end
 function DATABASE:_RegisterClients()
 
   for ClientName, ClientTemplate in pairs( self.Templates.ClientsByName ) do
-    self:E( { "Register Client:", ClientName } )
+    self:I( { "Register Client:", ClientName } )
     self:AddClient( ClientName )
   end
   
@@ -809,14 +848,14 @@ end
 function DATABASE:_RegisterStatics()
 
   local CoalitionsData = { GroupsRed = coalition.getStaticObjects( coalition.side.RED ), GroupsBlue = coalition.getStaticObjects( coalition.side.BLUE ) }
-  self:E( { Statics = CoalitionsData } )
+  self:I( { Statics = CoalitionsData } )
   for CoalitionId, CoalitionData in pairs( CoalitionsData ) do
     for DCSStaticId, DCSStatic in pairs( CoalitionData ) do
 
       if DCSStatic:isExist() then
         local DCSStaticName = DCSStatic:getName()
   
-        self:E( { "Register Static:", DCSStaticName } )
+        self:I( { "Register Static:", DCSStaticName } )
         self:AddStatic( DCSStaticName )
       else
         self:E( { "Static does not exist: ",  DCSStatic } )
@@ -836,7 +875,7 @@ function DATABASE:_RegisterAirbases()
 
       local DCSAirbaseName = DCSAirbase:getName()
 
-      self:E( { "Register Airbase:", DCSAirbaseName, DCSAirbase:getID() } )
+      self:I( { "Register Airbase:", DCSAirbaseName, DCSAirbase:getID() } )
       self:AddAirbase( DCSAirbaseName )
     end
   end
@@ -866,9 +905,8 @@ function DATABASE:_EventOnBirth( Event )
       Event.IniUnit = self:FindUnit( Event.IniDCSUnitName )
       Event.IniGroup = self:FindGroup( Event.IniDCSGroupName )
       local PlayerName = Event.IniUnit:GetPlayerName()
-      self:E( { "PlayerName:", PlayerName } )
       if PlayerName then
-        self:E( { "Player Joined:", PlayerName } )
+        self:I( { "Player Joined:", PlayerName } )
         if not self.PLAYERS[PlayerName] then
           self:AddPlayer( Event.IniUnitName, PlayerName )
         end
@@ -937,7 +975,7 @@ function DATABASE:_EventOnPlayerLeaveUnit( Event )
     if Event.IniObjectCategory == 1 then
       local PlayerName = Event.IniUnit:GetPlayerName()
       if PlayerName and self.PLAYERS[PlayerName] then
-        self:E( { "Player Left:", PlayerName } )
+        self:I( { "Player Left:", PlayerName } )
         local Settings = SETTINGS:Set( PlayerName )
         Settings:RemovePlayerMenu( Event.IniUnit )
         self:DeletePlayer( Event.IniUnit, PlayerName )
@@ -1342,18 +1380,12 @@ end
       self:T( { TargetUnitName, TargetGroupName, TargetPlayerName, TargetCoalition, TargetCategory, TargetType } )
     end
   
-    self:T( "Something got destroyed" )
-
     local Destroyed = false
 
     -- What is the player destroying?
     if self.HITS[Event.IniUnitName] then -- Was there a hit for this unit for this player before registered???
-      
-
       self.DESTROYS[Event.IniUnitName] = self.DESTROYS[Event.IniUnitName] or {}
-      
       self.DESTROYS[Event.IniUnitName] = true
-
     end
   end
 

Moose Development/Moose/Core/Event.lua

@@ -1,8 +1,15 @@
---- **Core** -- EVENT models DCS **event dispatching** using a **publish-subscribe** model.
+--- **Core** - Models DCS event dispatching using a publish-subscribe model.
 -- 
 -- ===
 -- 
--- # 1) Event Handling Overview
+-- ## Features:
+-- 
+--   * Capture DCS events and dispatch them to the subscribed objects.
+--   * Generate DCS events to the subscribed objects from within the code.
+-- 
+-- ===
+-- 
+-- # Event Handling Overview
 -- 
 -- ![Objects](..\Presentations\EVENT\Dia2.JPG)
 -- 
@@ -14,7 +21,7 @@
 -- Objects can subscribe to different events. The Event dispatcher will publish the received DCS events to the subscribed MOOSE objects, in a specified order.
 -- In this way, the subscribed MOOSE objects are kept in sync with your evolving running mission.
 -- 
--- ## 1.1) Event Dispatching
+-- ## 1. Event Dispatching
 -- 
 -- ![Objects](..\Presentations\EVENT\Dia4.JPG)
 -- 
@@ -41,7 +48,7 @@
 -- 
 -- But for some DCS events, the publishing order is reversed. This is due to the fact that objects need to be **erased** instead of added.
 -- 
--- ## 1.2) Event Handling
+-- # 2. Event Handling
 -- 
 -- ![Objects](..\Presentations\EVENT\Dia8.JPG)
 -- 
@@ -53,7 +60,7 @@
 -- The BASE class provides methods to catch DCS Events. These are events that are triggered from within the DCS simulator, 
 -- and handled through lua scripting. MOOSE provides an encapsulation to handle these events more efficiently.
 -- 
--- ### 1.2.1 Subscribe / Unsubscribe to DCS Events
+-- ## 2.1. Subscribe to / Unsubscribe from DCS Events.
 -- 
 -- At first, the mission designer will need to **Subscribe** to a specific DCS event for the class.
 -- So, when the DCS event occurs, the class will be notified of that event.
@@ -69,7 +76,7 @@
 -- So if a UNIT within the mission has the subscribed event for that object, 
 -- then the object event handler will receive the event for that UNIT!
 -- 
--- ### 1.3.2 Event Handling of DCS Events
+-- ## 2.2 Event Handling of DCS Events
 -- 
 -- Once the class is subscribed to the event, an **Event Handling** method on the object or class needs to be written that will be called
 -- when the DCS event occurs. The Event Handling method receives an @{Core.Event#EVENTDATA} structure, which contains a lot of information
@@ -100,19 +107,19 @@
 --        self:SmokeBlue()
 --      end
 -- 
--- ### 1.3.3 Event Handling methods that are automatically called upon subscribed DCS events
+-- ## 2.3 Event Handling methods that are automatically called upon subscribed DCS events.
 -- 
 -- ![Objects](..\Presentations\EVENT\Dia10.JPG)
 -- 
 -- The following list outlines which EVENTS item in the structure corresponds to which Event Handling method.
 -- Always ensure that your event handling methods align with the events being subscribed to, or nothing will be executed.
 -- 
--- # 2) EVENTS type
+-- # 3. EVENTS type
 -- 
 -- The EVENTS structure contains names for all the different DCS events that objects can subscribe to using the 
 -- @{Core.Base#BASE.HandleEvent}() method.
 -- 
--- # 3) EVENTDATA type
+-- # 4. EVENTDATA type
 -- 
 -- The @{Core.Event#EVENTDATA} structure contains all the fields that are populated with event information before 
 -- an Event Handler method is being called by the event dispatcher.
@@ -166,11 +173,12 @@
 -- @image Core_Event.JPG
 
 
---- The EVENT structure
--- 
--- @type EVENT
+--- @type EVENT
 -- @field #EVENT.Events Events
 -- @extends Core.Base#BASE
+
+--- The EVENT class
+-- @field #EVENT
 EVENT = {
   ClassName = "EVENT",
   ClassID = 0,
@@ -181,6 +189,8 @@ world.event.S_EVENT_NEW_CARGO = world.event.S_EVENT_MAX + 1000
 world.event.S_EVENT_DELETE_CARGO = world.event.S_EVENT_MAX + 1001
 world.event.S_EVENT_NEW_ZONE = world.event.S_EVENT_MAX + 1002
 world.event.S_EVENT_DELETE_ZONE = world.event.S_EVENT_MAX + 1003
+world.event.S_EVENT_REMOVE_UNIT = world.event.S_EVENT_MAX + 1004
+
 
 --- The different types of events supported by MOOSE.
 -- Use this structure to subscribe to events using the @{Core.Base#BASE.HandleEvent}() method.
@@ -216,6 +226,7 @@ EVENTS = {
   DeleteCargo =       world.event.S_EVENT_DELETE_CARGO,
   NewZone =           world.event.S_EVENT_NEW_ZONE,
   DeleteZone =        world.event.S_EVENT_DELETE_ZONE,
+  RemoveUnit =        world.event.S_EVENT_REMOVE_UNIT,
 }
 
 --- The Event structure
@@ -257,6 +268,10 @@ EVENTS = {
 -- @field DCS#Unit.Category TgtCategory (UNIT) The category of the target.
 -- @field #string TgtTypeName (UNIT) The type name of the target.
 -- 
+-- @field DCS#Airbase place The @{DCS#Airbase}
+-- @field Wrapper.Airbase#AIRBASE Place The MOOSE airbase object.
+-- @field #string PlaceName The name of the airbase.
+-- 
 -- @field weapon The weapon used during the event.
 -- @field Weapon
 -- @field WeaponName
@@ -441,6 +456,11 @@ local _EVENTMETA = {
      Event = "OnEventDeleteZone",
      Text = "S_EVENT_DELETE_ZONE" 
    },
+   [EVENTS.RemoveUnit] = {
+     Order = -1,
+     Event = "OnEventRemoveUnit",
+     Text = "S_EVENT_REMOVE_UNIT" 
+   },
 }
 
 
@@ -495,7 +515,6 @@ function EVENT:RemoveEvent( EventClass, EventID  )
   self.Events = self.Events or {}
   self.Events[EventID] = self.Events[EventID] or {}
   self.Events[EventID][EventPriority] = self.Events[EventID][EventPriority] or {}  
-  self.Events[EventID][EventPriority][EventClass] = self.Events[EventID][EventPriority][EventClass]
     
   self.Events[EventID][EventPriority][EventClass] = nil
   
@@ -719,7 +738,7 @@ do -- Event Creation
   -- @param #EVENT self
   -- @param AI.AI_Cargo#AI_CARGO Cargo The Cargo created.
   function EVENT:CreateEventNewCargo( Cargo )
-    self:F( { Cargo } )
+    self:I( { Cargo } )
   
     local Event = {
       id = EVENTS.NewCargo,
@@ -933,6 +952,12 @@ function EVENT:onEvent( Event )
       Event.WeaponTypeName = Event.WeaponUNIT and Event.Weapon:getTypeName()
       --Event.WeaponTgtDCSUnit = Event.Weapon:getTarget()
     end
+    
+    -- Place should be given for takeoff and landing events as well as base captured. It should be a DCS airbase. 
+    if Event.place then      
+      Event.Place=AIRBASE:Find(Event.place)
+      Event.PlaceName=Event.Place:GetName()
+    end
 
 --  @FC: something like this should be added.
 --[[    
@@ -961,7 +986,7 @@ function EVENT:onEvent( Event )
     local PriorityEnd = PriorityOrder == -1 and 1 or 5
 
     if Event.IniObjectCategory ~= Object.Category.STATIC then
-      self:E( { EventMeta.Text, Event, Event.IniDCSUnitName, Event.TgtDCSUnitName, PriorityOrder } )
+      self:T( { EventMeta.Text, Event, Event.IniDCSUnitName, Event.TgtDCSUnitName, PriorityOrder } )
     end
     
     for EventPriority = PriorityBegin, PriorityEnd, PriorityOrder do
@@ -985,7 +1010,8 @@ function EVENT:onEvent( Event )
             if EventClass:IsAlive() or
                Event.id == EVENTS.PlayerEnterUnit or 
                Event.id == EVENTS.Crash or 
-               Event.id == EVENTS.Dead then
+               Event.id == EVENTS.Dead or 
+               Event.id == EVENTS.RemoveUnit then
             
               local UnitName = EventClass:GetName()
 
@@ -1035,7 +1061,8 @@ function EVENT:onEvent( Event )
               if EventClass:IsAlive() or
                  Event.id == EVENTS.PlayerEnterUnit or
                  Event.id == EVENTS.Crash or
-                 Event.id == EVENTS.Dead then
+                 Event.id == EVENTS.Dead or
+                 Event.id == EVENTS.RemoveUnit then
 
                 -- We can get the name of the EventClass, which is now always a GROUP object.
                 local GroupName = EventClass:GetName()

Moose Development/Moose/Core/Fsm.lua

@@ -1,5 +1,18 @@
---- **Core** -- The **FSM** (**F**inite **S**tate **M**achine) class and derived **FSM\_** classes 
--- are design patterns allowing efficient (long-lasting) processes and workflows.
+--- **Core** - FSM (Finite State Machine) are objects that model and control long lasting business processes and workflow.
+-- 
+-- ===
+-- 
+-- ## Features:
+-- 
+--   * Provide a base class to model your own state machines.
+--   * Trigger events synchronously.
+--   * Trigger events asynchronously.
+--   * Handle events before or after the event was triggered.
+--   * Handle state transitions as a result of event before and after the state change.
+--   * For internal moose purposes, further state machines have been designed:
+--     - to handle controllables (groups and units).
+--     - to handle tasks.
+--     - to handle processes.
 -- 
 -- ===
 -- 
@@ -325,7 +338,7 @@ do -- FSM
   --
   -- ===
   -- 
-  -- @field #FSM FSM
+  -- @field #FSM
   -- 
   FSM = {
     ClassName = "FSM",
@@ -805,8 +818,7 @@ do -- FSM_CONTROLLABLE
   -- 
   -- ===
   -- 
-  -- @field #FSM_CONTROLLABLE FSM_CONTROLLABLE
-  -- 
+  -- @field #FSM_CONTROLLABLE
   FSM_CONTROLLABLE = {
     ClassName = "FSM_CONTROLLABLE",
   }
@@ -981,8 +993,9 @@ do -- FSM_PROCESS
         self:T( "*** FSM ***    " .. step .. " *** " .. params[1] .. " --> " .. params[2] .. " --> " .. params[3] .. " *** Task: " .. self.Task:GetName() .. ", TaskUnit: " .. self.Controllable:GetName() )
       end
       self._EventSchedules[EventName] = nil
+      local Result, Value
       if self.Controllable and self.Controllable:IsAlive() == true then
-        local Result, Value = xpcall( function() return self[handler]( self, self.Controllable, self.Task, unpack( params ) ) end, ErrorHandler )
+        Result, Value = xpcall( function() return self[handler]( self, self.Controllable, self.Task, unpack( params ) ) end, ErrorHandler )
       end
       return Value
       --return self[handler]( self, self.Controllable, unpack( params ) )
@@ -1204,10 +1217,22 @@ do -- FSM_TASK
   function FSM_TASK:_call_handler( step, trigger, params, EventName )
     local handler = step .. trigger
     
+    local ErrorHandler = function( errmsg )
+  
+      env.info( "Error in SCHEDULER function:" .. errmsg )
+      if BASE.Debug ~= nil then
+        env.info( BASE.Debug.traceback() )
+      end
+      
+      return errmsg
+    end
+
     if self[handler] then
       self:T( "*** FSM ***    " .. step .. " *** " .. params[1] .. " --> " .. params[2] .. " --> " .. params[3] .. " *** Task: " .. self.TaskName )
       self._EventSchedules[EventName] = nil
-      return self[handler]( self, unpack( params ) )
+      --return self[handler]( self, unpack( params ) )
+      local Result, Value = xpcall( function() return self[handler]( self, unpack( params ) ) end, ErrorHandler )
+      return Value
     end
   end
 

Moose Development/Moose/Core/Goal.lua

@@ -1,8 +1,16 @@
---- **Core (WIP)** -- Base class to allow the modeling of processes to achieve Goals.
+--- **Core** - Models the process to achieve goal(s).
 --
 -- ===
 -- 
--- GOAL models processes that have an objective with a defined achievement. Derived classes implement the ways how the achievements can be realized.
+-- ## Features:
+-- 
+--   * Define the goal.
+--   * Monitor the goal achievement.
+--   * Manage goal contribution by players.
+-- 
+-- ===
+-- 
+-- Classes that implement a goal achievement, will derive from GOAL to implement the ways how the achievements can be realized.
 -- 
 -- ===
 -- 
@@ -13,6 +21,7 @@
 -- @module Core.Goal
 -- @image Core_Goal.JPG
 
+
 do -- Goal
 
   --- @type GOAL
@@ -21,21 +30,43 @@ do -- Goal
 
   --- Models processes that have an objective with a defined achievement. Derived classes implement the ways how the achievements can be realized.
   -- 
-  -- ## 1. GOAL constructor
+  -- # 1. GOAL constructor
   --   
   --   * @{#GOAL.New}(): Creates a new GOAL object.
   -- 
-  -- ## 2. GOAL is a finite state machine (FSM).
+  -- # 2. GOAL is a finite state machine (FSM).
   -- 
-  -- ### 2.1 GOAL States
+  -- ## 2.1. GOAL States
   -- 
   --   * **Pending**: The goal object is in progress.
   --   * **Achieved**: The goal objective is Achieved.
   -- 
-  -- ### 2.2 GOAL Events
+  -- ## 2.2. GOAL Events
   -- 
   --   * **Achieved**: Set the goal objective to Achieved.
   -- 
+  -- # 3. Player contributions.
+  -- 
+  -- Goals are most of the time achieved by players. These player achievements can be registered as part of the goal achievement.
+  -- Use @{#GOAL.AddPlayerContribution}() to add a player contribution to the goal.
+  -- The player contributions are based on a points system, an internal counter per player.
+  -- So once the goal has been achieved, the player contributions can be queried using @{#GOAL.GetPlayerContributions}(), 
+  -- that retrieves all contributions done by the players. For one player, the contribution can be queried using @{#GOAL.GetPlayerContribution}().
+  -- The total amount of player contributions can be queried using @{#GOAL.GetTotalContributions}().
+  -- 
+  -- # 4. Goal achievement.
+  -- 
+  -- Once the goal is achieved, the mission designer will need to trigger the goal achievement using the **Achieved** event.
+  -- The underlying 2 examples will achieve the goals for the `Goal` object:
+  -- 
+  --       Goal:Achieved() -- Achieve the goal immediately.
+  --       Goal:__Achieved( 30 ) -- Achieve the goal within 30 seconds.
+  -- 
+  -- # 5. Check goal achievement.
+  -- 
+  -- The method @{#GOAL.IsAchieved}() will return true if the goal is achieved (the trigger **Achieved** was executed).
+  -- You can use this method to check asynchronously if a goal has been achieved, for example using a scheduler.
+  -- 
   -- @field #GOAL
   GOAL = {
     ClassName = "GOAL",
@@ -107,8 +138,9 @@ do -- Goal
   end
   
   
-  --- @param #GOAL self
-  -- @param #string PlayerName
+  --- Add a new contribution by a player.
+  -- @param #GOAL self
+  -- @param #string PlayerName The name of the player.
   function GOAL:AddPlayerContribution( PlayerName )
     self.Players[PlayerName] = self.Players[PlayerName] or 0
     self.Players[PlayerName] = self.Players[PlayerName] + 1
@@ -123,21 +155,28 @@ do -- Goal
   end
 
   
-  --- @param #GOAL self
+  --- Get the players who contributed to achieve the goal.
+  -- The result is a list of players, sorted by the name of the players.
+  -- @param #GOAL self
+  -- @return #list The list of players, indexed by the player name.
   function GOAL:GetPlayerContributions()
     return self.Players or {}
   end
 
   
-  --- @param #GOAL self
+  --- Gets the total contributions that happened to achieve the goal.
+  -- The result is a number.
+  -- @param #GOAL self
+  -- @return #number The total number of contributions. 0 is returned if there were no contributions (yet).
   function GOAL:GetTotalContributions()
     return self.TotalContributions or 0
   end
   
   
   
-  --- @param #GOAL self
-  -- @return #boolean true if the goal is Achieved
+  --- Validates if the goal is achieved.
+  -- @param #GOAL self
+  -- @return #boolean true if the goal is achieved.
   function GOAL:IsAchieved()
     return self:Is( "Achieved" )
   end

Moose Development/Moose/Core/Menu.lua

@@ -1,7 +1,27 @@
---- **Core** -- MENU_ classes model the definition of **hierarchical menu structures** and **commands for players** within a mission.
+--- **Core** - Manage hierarchical menu structures and commands for players within a mission.
 -- 
 -- ===
 -- 
+-- ### Features:
+-- 
+--   * Setup mission sub menus.
+--   * Setup mission command menus.
+--   * Setup coalition sub menus.
+--   * Setup coalition command menus.
+--   * Setup group sub menus.
+--   * Setup group command menus.
+--   * Manage menu creation intelligently, avoid double menu creation.
+--   * Only create or delete menus when required, and keep existing menus persistent.
+--   * Update menu structures.
+--   * Refresh menu structures intelligently, based on a time stamp of updates.
+--     - Delete obscolete menus.
+--     - Create new one where required.
+--     - Don't touch the existing ones.
+--   * Provide a variable amount of parameters to menus.
+--   * Update the parameters and the receiving methods, without updating the menu within DCS!
+--   * Provide a great performance boost in menu management.
+--   * Provide a great tool to manage menus in your code.
+-- 
 -- DCS Menus can be managed using the MENU classes. 
 -- The advantage of using MENU classes is that it hides the complexity of dealing with menu management in more advanced scanerios where you need to 
 -- set menus and later remove them, and later set them again. You'll find while using use normal DCS scripting functions, that setting and removing
@@ -89,11 +109,14 @@ function MENU_INDEX:PrepareCoalition( CoalitionSide )
     self.Coalition[CoalitionSide].Menus = self.Coalition[CoalitionSide].Menus or {}
 end
 
-
+---
+-- @param Wrapper.Group#GROUP Group
 function MENU_INDEX:PrepareGroup( Group )
+  if Group and Group:IsAlive() ~= nil  then -- something was changed here!
     local GroupName = Group:GetName()
     self.Group[GroupName] = self.Group[GroupName] or {}
     self.Group[GroupName].Menus = self.Group[GroupName].Menus or {}
+  end
 end
 
 
@@ -133,14 +156,17 @@ end
 
 
 function MENU_INDEX:HasGroupMenu( Group, Path )
-
-  local MenuGroupName = Group:GetName()
-  return self.Group[MenuGroupName].Menus[Path]
+  if Group and Group:IsAlive() then
+    local MenuGroupName = Group:GetName()
+    return self.Group[MenuGroupName].Menus[Path]
+  end
+  return nil
 end
 
 function MENU_INDEX:SetGroupMenu( Group, Path, Menu )
 
   local MenuGroupName = Group:GetName()
+  Group:F({MenuGroupName=MenuGroupName,Path=Path})
   self.Group[MenuGroupName].Menus[Path] = Menu
 end
 

Moose Development/Moose/Core/Message.lua

@@ -1,4 +1,15 @@
---- **Core** -- MESSAGE class takes are of the **real-time notifications** and **messages to players** during a simulation.
+--- **Core** - Informs the players using messages during a simulation.
+-- 
+-- ===
+-- 
+-- ## Features:
+-- 
+--   * A more advanced messaging system using the DCS message system.
+--   * Time messages.
+--   * Send messages based on a message type, which has a pre-defined duration that can be tweaked in SETTINGS.
+--   * Send message to all players.
+--   * Send messages to a coalition.
+--   * Send messages to a specific group.
 -- 
 -- ===
 -- 
@@ -161,6 +172,7 @@ end
 --- Sends a MESSAGE to a Client Group. Note that the Group needs to be defined within the ME with the skillset "Client" or "Player".
 -- @param #MESSAGE self
 -- @param Wrapper.Client#CLIENT Client is the Group of the Client.
+-- @param Core.Settings#SETTINGS Settings Settings used to display the message.
 -- @return #MESSAGE
 -- @usage
 -- -- Send the 2 messages created with the @{New} method to the Client Group.
@@ -200,8 +212,8 @@ end
 
 --- Sends a MESSAGE to a Group. 
 -- @param #MESSAGE self
--- @param Wrapper.Group#GROUP Group is the Group.
--- @return #MESSAGE
+-- @param Wrapper.Group#GROUP Group to which the message is displayed.
+-- @return #MESSAGE Message object.
 function MESSAGE:ToGroup( Group, Settings )
   self:F( Group.GroupName )
 
@@ -261,8 +273,9 @@ end
 
 --- Sends a MESSAGE to a Coalition. 
 -- @param #MESSAGE self
--- @param CoalitionSide needs to be filled out by the defined structure of the standard scripting engine @{coalition.side}. 
--- @return #MESSAGE
+-- @param #DCS.coalition.side CoalitionSide @{#DCS.coalition.side} to which the message is displayed.
+-- @param Core.Settings#SETTINGS Settings (Optional) Settings for message display.
+-- @return #MESSAGE Message object.
 -- @usage
 -- -- Send a message created with the @{New} method to the RED coalition.
 -- MessageRED = MESSAGE:New( "To the RED Players: You receive a penalty because you've killed one of your own units", "Penalty", 25, "Score" ):ToCoalition( coalition.side.RED )
@@ -292,8 +305,9 @@ end
 
 --- Sends a MESSAGE to a Coalition if the given Condition is true. 
 -- @param #MESSAGE self
--- @param CoalitionSide needs to be filled out by the defined structure of the standard scripting engine @{coalition.side}. 
--- @return #MESSAGE
+-- @param CoalitionSide needs to be filled out by the defined structure of the standard scripting engine @{coalition.side}.
+-- @param #boolean Condition Sends the message only if the condition is true. 
+-- @return #MESSAGE self
 function MESSAGE:ToCoalitionIf( CoalitionSide, Condition )
   self:F( CoalitionSide )
 
@@ -306,6 +320,7 @@ end
 
 --- Sends a MESSAGE to all players. 
 -- @param #MESSAGE self
+-- @param Core.Settings#Settings Settings (Optional) Settings for message display.
 -- @return #MESSAGE
 -- @usage
 -- -- Send a message created to all players.
@@ -315,7 +330,7 @@ end
 -- or
 -- MessageAll = MESSAGE:New( "To all Players: BLUE has won! Each player of BLUE wins 50 points!", "End of Mission", 25, "Win" )
 -- MessageAll:ToAll()
-function MESSAGE:ToAll()
+function MESSAGE:ToAll(Settings)
   self:F()
 
   if self.MessageType then

Moose Development/Moose/Core/Point.lua

@@ -1,6 +1,6 @@
---- **Core** -- Defines an **extensive API** to **manage 3D points** in the DCS World 3D simulation space.
+--- **Core** - Defines an extensive API to manage 3D points in the DCS World 3D simulation space.
 --
--- **Features:**
+-- ## Features:
 -- 
 --   * Provides a COORDINATE class, which allows to manage points in 3D space and perform various operations on it.
 --   * Provides a POINT\_VEC2 class, which is derived from COORDINATE, and allows to manage points in 3D space, but from a Lat/Lon and Altitude perspective.
@@ -397,7 +397,7 @@ do -- COORDINATE
     local gotunits=false
     local gotscenery=false
     
-    local function EvaluateZone( ZoneObject )
+    local function EvaluateZone(ZoneObject)
     
       if ZoneObject then
       
@@ -408,7 +408,7 @@ do -- COORDINATE
         --if (ObjectCategory == Object.Category.UNIT and ZoneObject:isExist() and ZoneObject:isActive()) then
         if (ObjectCategory == Object.Category.UNIT and ZoneObject:isExist()) then
         
-          table.insert(Units, ZoneObject)
+          table.insert(Units, UNIT:Find(ZoneObject))
           gotunits=true
           
         elseif (ObjectCategory == Object.Category.STATIC and ZoneObject:isExist()) then
@@ -432,7 +432,7 @@ do -- COORDINATE
     world.searchObjects(scanobjects, SphereSearch, EvaluateZone)
     
     for _,unit in pairs(Units) do
-      self:T(string.format("Scan found unit %s", unit:getName()))
+      self:T(string.format("Scan found unit %s", unit:GetName()))
     end
     for _,static in pairs(Statics) do
       self:T(string.format("Scan found static %s", static:getName()))
@@ -729,6 +729,20 @@ do -- COORDINATE
     return nil
   end
   
+  --- Returns the heading from this to another coordinate.
+  -- @param #COORDINATE self
+  -- @param #COORDINATE ToCoordinate
+  -- @return #number Heading in degrees. 
+  function COORDINATE:HeadingTo(ToCoordinate)
+    local dz=ToCoordinate.z-self.z
+    local dx=ToCoordinate.x-self.x
+    local heading=math.deg(math.atan2(dz, dx))
+    if heading < 0 then
+      heading = 360 + heading
+    end
+    return heading
+  end
+  
   --- Returns the wind direction (from) and strength.
   -- @param #COORDINATE self
   -- @param height (Optional) parameter specifying the height ASL. The minimum height will be always be the land height since the wind is zero below the ground.
@@ -924,6 +938,21 @@ do -- COORDINATE
   end
 
 
+  --- Set altitude.
+  -- @param #COORDINATE self
+  -- @param #number altitude New altitude in meters.
+  -- @param #boolean asl Altitude above sea level. Default is above ground level.
+  -- @return #COORDINATE The COORDINATE with adjusted altitude.
+  function COORDINATE:SetAltitude(altitude, asl)
+    local alt=altitude
+    if asl then
+      alt=altitude
+    else
+      alt=self:GetLandHeight()+altitude
+    end
+    self.y=alt
+    return self
+  end
 
   --- Add a Distance in meters from the COORDINATE horizontal plane, with the given angle, and calculate the new COORDINATE.
   -- @param #COORDINATE self
@@ -949,21 +978,53 @@ do -- COORDINATE
   -- @param #COORDINATE.WaypointAction Action The route point action.
   -- @param DCS#Speed Speed Airspeed in km/h. Default is 500 km/h.
   -- @param #boolean SpeedLocked true means the speed is locked.
+  -- @param Wrapper.Airbase#AIRBASE airbase The airbase for takeoff and landing points.
+  -- @param #table DCSTasks A table of @{DCS#Task} items which are executed at the waypoint.
+  -- @param #string description A text description of the waypoint, which will be shown on the F10 map.
   -- @return #table The route point.
-  function COORDINATE:WaypointAir( AltType, Type, Action, Speed, SpeedLocked )
+  function COORDINATE:WaypointAir( AltType, Type, Action, Speed, SpeedLocked, airbase, DCSTasks, description )
     self:F2( { AltType, Type, Action, Speed, SpeedLocked } )
-
+    
+    -- Defaults
+    AltType=AltType or "RADIO"
+    if SpeedLocked==nil then
+      SpeedLocked=true
+    end
+    Speed=Speed or 500
+    
+    -- Waypoint array.
     local RoutePoint = {}
+    
+    -- Coordinates.
     RoutePoint.x = self.x
     RoutePoint.y = self.z
+    -- Altitude.
     RoutePoint.alt = self.y
-    RoutePoint.alt_type = AltType or "RADIO"
-
+    RoutePoint.alt_type = AltType
+    -- Waypoint type.
     RoutePoint.type = Type or nil
     RoutePoint.action = Action or nil
-
-    RoutePoint.speed = ( Speed and Speed / 3.6 ) or ( 500 / 3.6 )
-    RoutePoint.speed_locked = true
+    -- Set speed/ETA.
+    RoutePoint.speed = Speed/3.6
+    RoutePoint.speed_locked = SpeedLocked
+    RoutePoint.ETA=nil
+    RoutePoint.ETA_locked = false    
+    -- Waypoint description.
+    RoutePoint.name=description
+    -- Airbase parameters for takeoff and landing points.
+    if airbase then
+      local AirbaseID = airbase:GetID()
+      local AirbaseCategory = airbase:GetDesc().category
+      if AirbaseCategory == Airbase.Category.SHIP or AirbaseCategory == Airbase.Category.HELIPAD then
+        RoutePoint.linkUnit = AirbaseID
+        RoutePoint.helipadId = AirbaseID
+      elseif AirbaseCategory == Airbase.Category.AIRDROME then
+        RoutePoint.airdromeId = AirbaseID       
+      else
+        self:T("ERROR: Unknown airbase category in COORDINATE:WaypointAir()!")
+      end  
+    end        
+    
 
     --  ["task"] =
     --  {
@@ -976,13 +1037,13 @@ do -- COORDINATE
     --      }, -- end of ["params"]
     --  }, -- end of ["task"]
 
-
+    -- Waypoint tasks.
     RoutePoint.task = {}
     RoutePoint.task.id = "ComboTask"
     RoutePoint.task.params = {}
-    RoutePoint.task.params.tasks = {}
-
+    RoutePoint.task.params.tasks = DCSTasks or {}
 
+    self:T({RoutePoint=RoutePoint})
     return RoutePoint
   end
 
@@ -991,9 +1052,11 @@ do -- COORDINATE
   -- @param #COORDINATE self
   -- @param #COORDINATE.WaypointAltType AltType The altitude type.
   -- @param DCS#Speed Speed Airspeed in km/h.
+  -- @param #table DCSTasks (Optional) A table of @{DCS#Task} items which are executed at the waypoint.
+  -- @param #string description (Optional) A text description of the waypoint, which will be shown on the F10 map.
   -- @return #table The route point.
-  function COORDINATE:WaypointAirTurningPoint( AltType, Speed )
-    return self:WaypointAir( AltType, COORDINATE.WaypointType.TurningPoint, COORDINATE.WaypointAction.TurningPoint, Speed )
+  function COORDINATE:WaypointAirTurningPoint( AltType, Speed, DCSTasks, description )
+    return self:WaypointAir( AltType, COORDINATE.WaypointType.TurningPoint, COORDINATE.WaypointAction.TurningPoint, Speed, true, nil, DCSTasks, description )
   end
 
   
@@ -1095,6 +1158,40 @@ do -- COORDINATE
 
     return RoutePoint
   end
+
+  --- Gets the nearest airbase with respect to the current coordinates.
+  -- @param #COORDINATE self
+  -- @param #number Category (Optional) Category of the airbase. Enumerator of @{Wrapper.Airbase#AIRBASE.Category}.
+  -- @param #number Coalition (Optional) Coalition of the airbase.
+  -- @return Wrapper.Airbase#AIRBASE Closest Airbase to the given coordinate.
+  -- @return #number Distance to the closest airbase in meters.
+  function COORDINATE:GetClosestAirbase(Category, Coalition)
+  
+    -- Get all airbases of the map.
+    local airbases=AIRBASE.GetAllAirbases(Coalition)
+    
+    local closest=nil
+    local distmin=nil
+    -- Loop over all airbases.
+    for _,_airbase in pairs(airbases) do
+      local airbase=_airbase --Wrapper.Airbase#AIRBASE
+      local category=airbase:GetDesc().category
+      if Category and Category==category or Category==nil then
+        local dist=self:Get2DDistance(airbase:GetCoordinate())
+        if closest==nil then
+          distmin=dist
+          closest=airbase
+        else
+          if dist<distmin then
+            distmin=dist
+            closest=airbase
+          end 
+        end
+      end
+    end
+    
+    return closest,distmin
+  end
   
   --- Gets the nearest parking spot.
   -- @param #COORDINATE self
@@ -1174,27 +1271,43 @@ do -- COORDINATE
     return self:GetClosestParkingSpot(airbase, terminaltype, false)
   end
     
-  --- Gets the nearest coordinate to a road.
+  --- Gets the nearest coordinate to a road (or railroad).
   -- @param #COORDINATE self
+  -- @param #boolean Railroad (Optional) If true, closest point to railroad is returned rather than closest point to conventional road. Default false. 
   -- @return #COORDINATE Coordinate of the nearest road.
-  function COORDINATE:GetClosestPointToRoad()
-   local x,y = land.getClosestPointOnRoads("roads", self.x, self.z)
-   local vec2={ x = x, y = y }
-   return COORDINATE:NewFromVec2(vec2)
+  function COORDINATE:GetClosestPointToRoad(Railroad)
+    local roadtype="roads"
+    if Railroad==true then
+      roadtype="railroads"
+    end
+    local x,y = land.getClosestPointOnRoads(roadtype, self.x, self.z)
+    local vec2={ x = x, y = y }
+    return COORDINATE:NewFromVec2(vec2)
   end
+  
 
-  --- Returns a table of coordinates to a destination using only roads.
+  --- Returns a table of coordinates to a destination using only roads or railroads.
   -- The first point is the closest point on road of the given coordinate.
   -- By default, the last point is the closest point on road of the ToCoord. Hence, the coordinate itself and the final ToCoord are not necessarily included in the path.
   -- @param #COORDINATE self
   -- @param #COORDINATE ToCoord Coordinate of destination.
   -- @param #boolean IncludeEndpoints (Optional) Include the coordinate itself and the ToCoordinate in the path.
+  -- @param #boolean Railroad (Optional) If true, path on railroad is returned. Default false.
+  -- @param #boolean MarkPath (Optional) If true, place markers on F10 map along the path.
+  -- @param #boolean SmokePath (Optional) If true, put (green) smoke along the  
   -- @return #table Table of coordinates on road. If no path on road can be found, nil is returned or just the endpoints.
-  -- @return #number The length of the total path.
-  function COORDINATE:GetPathOnRoad(ToCoord, IncludeEndpoints)
-
+  -- @return #number Tonal length of path.
+  -- @return #boolean If true a valid path on road/rail was found. If false, only the direct way is possible. 
+  function COORDINATE:GetPathOnRoad(ToCoord, IncludeEndpoints, Railroad, MarkPath, SmokePath)
+  
+    -- Set road type.
+    local RoadType="roads"
+    if Railroad==true then
+      RoadType="railroads"
+    end
+    
     -- DCS API function returning a table of vec2.
-    local path = land.findPathOnRoads("roads", self.x, self.z, ToCoord.x, ToCoord.z)
+    local path = land.findPathOnRoads(RoadType, self.x, self.z, ToCoord.x, ToCoord.z)
     
     -- Array holding the path coordinates.
     local Path={}
@@ -1204,18 +1317,43 @@ do -- COORDINATE
     if IncludeEndpoints then
       Path[1]=self
     end
+    
+    -- Assume we could get a valid path.
+    local GotPath=true
         
     -- Check that DCS routine actually returned a path. There are situations where this is not the case.
     if path then
     
       -- Include all points on road.      
-      for _,_vec2 in ipairs(path) do
-        Path[#Path+1]=COORDINATE:NewFromVec2(_vec2)
-        --COORDINATE:NewFromVec2(_vec2):SmokeGreen()
+      for _i,_vec2 in ipairs(path) do
+      
+        local coord=COORDINATE:NewFromVec2(_vec2)
+        
+        Path[#Path+1]=coord
+        
+        if MarkPath then
+          coord:MarkToAll(string.format("Path segment %d.", _i))
+        end
+        if SmokePath then
+          coord:SmokeGreen()
+        end
+      end
+            
+      -- Mark/smoke endpoints
+      if IncludeEndpoints then
+        if MarkPath then
+          COORDINATE:NewFromVec2(path[1]):MarkToAll("Path Initinal Point")
+          COORDINATE:NewFromVec2(path[1]):MarkToAll("Path Final Point")        
+        end
+        if SmokePath then
+          COORDINATE:NewFromVec2(path[1]):SmokeBlue()
+          COORDINATE:NewFromVec2(path[#path]):SmokeBlue()
+        end
       end
             
     else
       self:E("Path is nil. No valid path on road could be found.")
+      GotPath=false
     end
  
     -- Include end point, which might not be on road.
@@ -1233,7 +1371,7 @@ do -- COORDINATE
       return nil,nil
     end 
         
-    return Path, Way
+    return Path, Way, GotPath
   end
 
   --- Gets the surface type at the coordinate.
@@ -1245,9 +1383,53 @@ do -- COORDINATE
     return surface
   end
 
+  --- Checks if the surface type is on land.
+  -- @param #COORDINATE self
+  -- @return #boolean If true, the surface type at the coordinate is land.
+  function COORDINATE:IsSurfaceTypeLand()
+    return self:GetSurfaceType()==land.SurfaceType.LAND
+  end
+
+  --- Checks if the surface type is road.
+  -- @param #COORDINATE self
+  -- @return #boolean If true, the surface type at the coordinate is land.
+  function COORDINATE:IsSurfaceTypeLand()
+    return self:GetSurfaceType()==land.SurfaceType.LAND
+  end
+
+
+  --- Checks if the surface type is road.
+  -- @param #COORDINATE self
+  -- @return #boolean If true, the surface type at the coordinate is a road.
+  function COORDINATE:IsSurfaceTypeRoad()
+    return self:GetSurfaceType()==land.SurfaceType.ROAD
+  end
+
+  --- Checks if the surface type is runway.
+  -- @param #COORDINATE self
+  -- @return #boolean If true, the surface type at the coordinate is a runway or taxi way.
+  function COORDINATE:IsSurfaceTypeRunway()
+    return self:GetSurfaceType()==land.SurfaceType.RUNWAY
+  end
+
+  --- Checks if the surface type is shallow water.
+  -- @param #COORDINATE self
+  -- @return #boolean If true, the surface type at the coordinate is a shallow water.
+  function COORDINATE:IsSurfaceTypeShallowWater()
+    return self:GetSurfaceType()==land.SurfaceType.SHALLOW_WATER
+  end
+
+  --- Checks if the surface type is water.
+  -- @param #COORDINATE self
+  -- @return #boolean If true, the surface type at the coordinate is a deep water.
+  function COORDINATE:IsSurfaceTypeWater()
+    return self:GetSurfaceType()==land.SurfaceType.WATER
+  end
+
+
   --- Creates an explosion at the point of a certain intensity.
   -- @param #COORDINATE self
-  -- @param #number ExplosionIntensity
+  -- @param #number ExplosionIntensity Intensity of the explosion in kg TNT.
   function COORDINATE:Explosion( ExplosionIntensity )
     self:F2( { ExplosionIntensity } )
     trigger.action.explosion( self:GetVec3(), ExplosionIntensity )
@@ -1390,7 +1572,7 @@ do -- COORDINATE
   --- Flares the point in a color.
   -- @param #COORDINATE self
   -- @param Utilities.Utils#FLARECOLOR FlareColor
-  -- @param DCS#Azimuth (optional) Azimuth The azimuth of the flare direction. The default azimuth is 0.
+  -- @param DCS#Azimuth Azimuth (optional) The azimuth of the flare direction. The default azimuth is 0.
   function COORDINATE:Flare( FlareColor, Azimuth )
     self:F2( { FlareColor } )
     trigger.action.signalFlare( self:GetVec3(), FlareColor, Azimuth and Azimuth or 0 )
@@ -1398,7 +1580,7 @@ do -- COORDINATE
 
   --- Flare the COORDINATE White.
   -- @param #COORDINATE self
-  -- @param DCS#Azimuth (optional) Azimuth The azimuth of the flare direction. The default azimuth is 0.
+  -- @param DCS#Azimuth Azimuth (optional) The azimuth of the flare direction. The default azimuth is 0.
   function COORDINATE:FlareWhite( Azimuth )
     self:F2( Azimuth )
     self:Flare( FLARECOLOR.White, Azimuth )
@@ -1406,7 +1588,7 @@ do -- COORDINATE
 
   --- Flare the COORDINATE Yellow.
   -- @param #COORDINATE self
-  -- @param DCS#Azimuth (optional) Azimuth The azimuth of the flare direction. The default azimuth is 0.
+  -- @param DCS#Azimuth Azimuth (optional) The azimuth of the flare direction. The default azimuth is 0.
   function COORDINATE:FlareYellow( Azimuth )
     self:F2( Azimuth )
     self:Flare( FLARECOLOR.Yellow, Azimuth )
@@ -1414,7 +1596,7 @@ do -- COORDINATE
 
   --- Flare the COORDINATE Green.
   -- @param #COORDINATE self
-  -- @param DCS#Azimuth (optional) Azimuth The azimuth of the flare direction. The default azimuth is 0.
+  -- @param DCS#Azimuth Azimuth (optional) The azimuth of the flare direction. The default azimuth is 0.
   function COORDINATE:FlareGreen( Azimuth )
     self:F2( Azimuth )
     self:Flare( FLARECOLOR.Green, Azimuth )
@@ -1791,17 +1973,20 @@ do -- COORDINATE
   -- @param Core.Settings#SETTINGS Settings
   -- @param Tasking.Task#TASK Task The task for which coordinates need to be calculated.
   -- @return #string The coordinate Text in the configured coordinate system.
-  function COORDINATE:ToString( Controllable, Settings, Task ) -- R2.2
+  function COORDINATE:ToString( Controllable, Settings, Task )
   
     self:F2( { Controllable = Controllable and Controllable:GetName() } )
 
     local Settings = Settings or ( Controllable and _DATABASE:GetPlayerSettings( Controllable:GetPlayerName() ) ) or _SETTINGS
 
     local ModeA2A = false
+    self:E('A2A false')
     
     if Task then
+      self:E('Task ' .. Task.ClassName )
       if Task:IsInstanceOf( TASK_A2A ) then
         ModeA2A = true
+        self:E('A2A true')
       else
         if Task:IsInstanceOf( TASK_A2G ) then
           ModeA2A = false
@@ -1895,7 +2080,7 @@ do -- POINT_VEC3
   -- @field #POINT_VEC3.RoutePointAltType RoutePointAltType
   -- @field #POINT_VEC3.RoutePointType RoutePointType
   -- @field #POINT_VEC3.RoutePointAction RoutePointAction
-  -- @extends Core.Point#COORDINATE
+  -- @extends #COORDINATE
   
   
   --- Defines a 3D point in the simulator and with its methods, you can use or manipulate the point in 3D space.

Moose Development/Moose/Core/Radio.lua

@@ -1,6 +1,11 @@
---- **Core** -- The RADIO Module is responsible for everything that is related to radio transmission and you can hear in DCS, be it TACAN beacons, Radio transmissions...
+--- **Core** - Is responsible for everything that is related to radio transmission and you can hear in DCS, be it TACAN beacons, Radio transmissions.
 -- 
 -- ===
+-- 
+-- ## Features:
+-- 
+--   * Provide radio functionality to broadcast radio transmissions.
+--   * Provide beacon functionality to assist pilots.
 --
 -- The Radio contains 2 classes : RADIO and BEACON
 --  

Moose Development/Moose/Core/Report.lua

@@ -1,20 +1,26 @@
---- **Core** -- **REPORT** class provides a handy means to create messages and reports.
+--- **Core** - Provides a handy means to create messages and reports.
 --
 -- ===
+-- 
+-- ## Features:
+-- 
+--   * Create text blocks that are formatted.
+--   * Create automatic indents.
+--   * Variate the delimiters between reporting lines.
+-- 
+-- ===
 --
--- ### Authors:
---
---   * FlightControl : Design & Programming
---
--- ### Contributions:
+-- ### Authors: FlightControl : Design & Programming
 --
 -- @module Core.Report
 -- @image Core_Report.JPG
 
 
---- The REPORT class
--- @type REPORT
+--- @type REPORT
 -- @extends Core.Base#BASE
+
+--- Provides a handy means to create messages and reports.
+-- @field #REPORT
 REPORT = {
   ClassName = "REPORT",
   Title = "",

Moose Development/Moose/Core/Scheduler.lua

@@ -1,13 +1,14 @@
---- **Core** -- SCHEDULER prepares and handles the **execution of functions over scheduled time (intervals)**.
+--- **Core** - Prepares and handles the execution of functions over scheduled time (intervals).
 --
 -- ===
 -- 
--- SCHEDULER manages the **scheduling of functions**:
+-- ## Features:
 -- 
---    * optionally in an optional specified time interval, 
---    * optionally **repeating** with a specified time repeat interval, 
---    * optionally **randomizing** with a specified time interval randomization factor, 
---    * optionally **stop** the repeating after a specified time interval. 
+--   * Schedule functions over time,
+--   * optionally in an optional specified time interval, 
+--   * optionally **repeating** with a specified time repeat interval, 
+--   * optionally **randomizing** with a specified time interval randomization factor, 
+--   * optionally **stop** the repeating after a specified time interval. 
 --
 -- ===
 -- 

Moose Development/Moose/Core/Settings.lua

@@ -1,7 +1,19 @@
---- **Core** -- Manages various settings for MOOSE classes.
+--- **Core** - Manages various settings for running missions, consumed by moose classes and provides a menu system for players to tweak settings in running missions.
 --
 -- ===
 -- 
+-- ## Features:
+-- 
+--   * Provide a settings menu system to the players.
+--   * Provide a player settings menu and an overall mission settings menu.
+--   * Mission settings provide default settings, while player settings override mission settings.
+--   * Provide a menu to select between different coordinate formats for A2G coordinates.
+--   * Provide a menu to select between different coordinate formats for A2A coordinates.
+--   * Provide a menu to select between different message time duration options.
+--   * Provide a menu to select between different metric systems.
+-- 
+-- ===
+-- 
 -- The documentation of the SETTINGS class can be found further in this document.
 -- 
 -- ===
@@ -364,7 +376,6 @@ do -- SETTINGS
   -- @param #SETTINGS self
   -- @return #boolean true if BRA
   function SETTINGS:IsA2A_BRAA()
-    self:E( { BRA = ( self.A2ASystem and self.A2ASystem == "BRAA" ) or ( not self.A2ASystem and _SETTINGS:IsA2A_BRAA() ) } )
     return ( self.A2ASystem and self.A2ASystem == "BRAA" ) or ( not self.A2ASystem and _SETTINGS:IsA2A_BRAA() )
   end
 

Moose Development/Moose/Core/Spawn.lua

@@ -1,8 +1,32 @@
---- **Core** -- SPAWN class dynamically spawns new groups of units in your missions.
+--- **Core** - Spawn dynamically new groups of units in running missions.
 --  
 -- ===
 -- 
--- The documentation of the SPAWN class can be found further in this document.
+-- ## Features:
+-- 
+--   * Spawn new groups in running missions.
+--   * Schedule spawning of new groups.
+--   * Put limits on the amount of groups that can be spawned, and the amount of units that can be alive at the same time.
+--   * Randomize the spawning location between different zones.
+--   * Randomize the intial positions within the zones.
+--   * Spawn in array formation.
+--   * Spawn uncontrolled (for planes or helos only).
+--   * Clean up inactive helicopters that "crashed".
+--   * Place a hook to capture a spawn event, and tailor with customer code.
+--   * Spawn late activated.
+--   * Spawn with or without an initial delay.
+--   * Respawn after landing, on the runway or at the ramp after engine shutdown.
+--   * Spawn with custom heading.
+--   * Spawn with different skills.
+--   * Spawn with different liveries.
+--   * Spawn with an inner and outer radius to set the initial position.
+--   * Spawn with a randomize route.
+--   * Spawn with a randomized template.
+--   * Spawn with a randomized start points on a route.
+--   * Spawn with an alternative name.
+--   * Spawn and keep the unit names.
+--   * Spawn with a different coalition and country.
+--   * Enquiry methods to check on spawn status.
 -- 
 -- ===
 -- 
@@ -496,7 +520,12 @@ end
 
 --- Sets the coalition of the spawned group. Note that it might be necessary to also set the country explicitly!
 -- @param #SPAWN self 
--- @param #DCS.coalition Coaliton Coaliton of the group as number of enumerator, i.e. 0=coaliton.side.NEUTRAL, 1=coaliton.side.RED, 2=coalition.side.BLUE.
+-- @param DCS#coalition.side Coalition Coalition of the group as number of enumerator:
+-- 
+--   * @{DCS#coaliton.side.NEUTRAL}
+--   * @{DCS#coaliton.side.RED}
+--   * @{DCS#coalition.side.BLUE}
+--   
 -- @return #SPAWN self
 function SPAWN:InitCoalition( Coalition )
   self:F({coalition=Coalition})
@@ -507,9 +536,12 @@ function SPAWN:InitCoalition( Coalition )
 end
 
 --- Sets the country of the spawn group. Note that the country determins the coalition of the group depending on which country is defined to be on which side for each specific mission!
--- See https://wiki.hoggitworld.com/view/DCS_enum_country for country enumerators.
 -- @param #SPAWN self 
--- @param #DCS.country Country Country id as number or enumerator, e.g. country.id.RUSSIA=0, county.id.USA=2 etc.
+-- @param #DCS.country Country Country id as number or enumerator:
+-- 
+--   * @{DCS#country.id.RUSSIA}
+--   * @{DCS#county.id.USA}
+--   
 -- @return #SPAWN self
 function SPAWN:InitCountry( Country )
   self:F( )
@@ -757,14 +789,20 @@ end
 
 
 
---TODO: Add example.
 --- This method provides the functionality to randomize the spawning of the Groups at a given list of zones of different types.
 -- @param #SPAWN self
 -- @param #table SpawnZoneTable A table with @{Zone} objects. If this table is given, then each spawn will be executed within the given list of @{Zone}s objects. 
 -- @return #SPAWN
 -- @usage
--- -- NATO Tank Platoons invading Gori.
--- -- Choose between 3 different zones for each new SPAWN the Group to be executed, regardless of the zone type. 
+--  -- Create a zone table of the 2 zones.
+--  ZoneTable = { ZONE:New( "Zone1" ), ZONE:New( "Zone2" ) }
+--  
+--  Spawn_Vehicle_1 = SPAWN:New( "Spawn Vehicle 1" )
+--    :InitLimit( 10, 10 )
+--    :InitRandomizeRoute( 1, 1, 200 ) 
+--    :InitRandomizeZones( ZoneTable )
+--    :SpawnScheduled( 5, .5 )
+--    
 function SPAWN:InitRandomizeZones( SpawnZoneTable )
   self:F( { self.SpawnTemplatePrefix, SpawnZoneTable } )
 
@@ -883,10 +921,10 @@ end
 --- Makes the groups visible before start (like a batallion).
 -- The method will take the position of the group as the first position in the array.
 -- @param #SPAWN self
--- @param #number SpawnAngle         The angle in degrees how the groups and each unit of the group will be positioned.
--- @param #number SpawnWidth		     The amount of Groups that will be positioned on the X axis.
--- @param #number SpawnDeltaX        The space between each Group on the X-axis.
--- @param #number SpawnDeltaY		     The space between each Group on the Y-axis.
+-- @param #number SpawnAngle The angle in degrees how the groups and each unit of the group will be positioned.
+-- @param #number SpawnWidth The amount of Groups that will be positioned on the X axis.
+-- @param #number SpawnDeltaX The space between each Group on the X-axis.
+-- @param #number SpawnDeltaY The space between each Group on the Y-axis.
 -- @return #SPAWN self
 -- @usage
 -- -- Define an array of Groups.
@@ -932,6 +970,7 @@ function SPAWN:InitArray( SpawnAngle, SpawnWidth, SpawnDeltaX, SpawnDeltaY )
     self:HandleEvent( EVENTS.Birth, self._OnBirth )
     self:HandleEvent( EVENTS.Dead, self._OnDeadOrCrash )
     self:HandleEvent( EVENTS.Crash, self._OnDeadOrCrash )
+    self:HandleEvent( EVENTS.RemoveUnit, self._OnDeadOrCrash )
     if self.Repeat then
       self:HandleEvent( EVENTS.Takeoff, self._OnTakeOff )
       self:HandleEvent( EVENTS.Land, self._OnLand )
@@ -1151,6 +1190,7 @@ function SPAWN:SpawnWithIndex( SpawnIndex )
       self:HandleEvent( EVENTS.Birth, self._OnBirth )
       self:HandleEvent( EVENTS.Dead, self._OnDeadOrCrash )
       self:HandleEvent( EVENTS.Crash, self._OnDeadOrCrash )
+      self:HandleEvent( EVENTS.RemoveUnit, self._OnDeadOrCrash )
       if self.Repeat then
         self:HandleEvent( EVENTS.Takeoff, self._OnTakeOff )
         self:HandleEvent( EVENTS.Land, self._OnLand )
@@ -1251,16 +1291,17 @@ end
 -- @param SpawnFunctionArguments A random amount of arguments to be provided to the function when the group spawns.
 -- @return #SPAWN
 -- @usage
--- -- Declare SpawnObject and call a function when a new Group is spawned.
--- local SpawnObject = SPAWN
---   :New( "SpawnObject" )
---   :InitLimit( 2, 10 )
---   :OnSpawnGroup(
---     function( SpawnGroup )
---       SpawnGroup:E( "I am spawned" )
---     end 
---     )
---   :SpawnScheduled( 300, 0.3 )
+--  -- Declare SpawnObject and call a function when a new Group is spawned.
+--  local SpawnObject = SPAWN
+--    :New( "SpawnObject" )
+--    :InitLimit( 2, 10 )
+--    :OnSpawnGroup(
+--      function( SpawnGroup )
+--        SpawnGroup:E( "I am spawned" )
+--      end 
+--      )
+--    :SpawnScheduled( 300, 0.3 )
+--    
 function SPAWN:OnSpawnGroup( SpawnCallBackFunction, ... )
   self:F( "OnSpawnGroup" )
 
@@ -1299,6 +1340,7 @@ end
 -- @param #number TakeoffAltitude (optional) The altitude above the ground.
 -- @param Wrapper.Airbase#AIRBASE.TerminalType TerminalType (optional) The terminal type the aircraft should be spawned at. See @{Wrapper.Airbase#AIRBASE.TerminalType}.
 -- @param #boolean EmergencyAirSpawn (optional) If true (default), groups are spawned in air if there is no parking spot at the airbase. If false, nothing is spawned if no parking spot is available.
+-- @param #table Parkingdata (optional) Table holding the coordinates and terminal ids for all units of the group. Spawning will be forced to happen at exactily these spots!
 -- @return Wrapper.Group#GROUP that was spawned or nil when nothing was spawned.
 -- @usage
 --   Spawn_Plane = SPAWN:New( "Plane" )
@@ -1319,7 +1361,7 @@ end
 --   
 --   Spawn_Plane:SpawnAtAirbase( AIRBASE:FindByName( AIRBASE.Caucasus.Krymsk ), SPAWN.Takeoff.Cold, nil, AIRBASE.TerminalType.OpenBig )
 -- 
-function SPAWN:SpawnAtAirbase( SpawnAirbase, Takeoff, TakeoffAltitude, TerminalType, EmergencyAirSpawn ) -- R2.2, R2.4
+function SPAWN:SpawnAtAirbase( SpawnAirbase, Takeoff, TakeoffAltitude, TerminalType, EmergencyAirSpawn, Parkingdata ) -- R2.2, R2.4
   self:F( { self.SpawnTemplatePrefix, SpawnAirbase, Takeoff, TakeoffAltitude, TerminalType } )
 
   -- Get position of airbase.
@@ -1434,6 +1476,10 @@ function SPAWN:SpawnAtAirbase( SpawnAirbase, Takeoff, TakeoffAltitude, TerminalT
           self:T(string.format("Group %s is spawned on farp/ship/runway %s.", self.SpawnTemplatePrefix, SpawnAirbase:GetName()))
           nfree=SpawnAirbase:GetFreeParkingSpotsNumber(termtype, true)
           spots=SpawnAirbase:GetFreeParkingSpotsTable(termtype, true)
+        elseif Parkingdata~=nil then
+          -- Parking data explicitly set by user as input parameter.
+          nfree=#Parkingdata
+          spots=Parkingdata
         else
           if ishelo then
             if termtype==nil then
@@ -1511,7 +1557,7 @@ function SPAWN:SpawnAtAirbase( SpawnAirbase, Takeoff, TakeoffAltitude, TerminalT
             PointVec3=spots[1].Coordinate
             
           else
-            -- If there is absolutely not spot ==> air start!
+            -- If there is absolutely no spot ==> air start!
             _notenough=true
           end
         
@@ -1615,6 +1661,7 @@ function SPAWN:SpawnAtAirbase( SpawnAirbase, Takeoff, TakeoffAltitude, TerminalT
             SpawnTemplate.units[UnitID].y   = parkingspots[UnitID].z
             SpawnTemplate.units[UnitID].alt = parkingspots[UnitID].y
             
+            --parkingspots[UnitID]:MarkToAll(string.format("Group %s spawning at airbase %s on parking spot id %d", self.SpawnTemplatePrefix, SpawnAirbase:GetName(), parkingindex[UnitID]))
           end
                  
         else

Moose Development/Moose/Core/SpawnStatic.lua

@@ -1,8 +1,14 @@
---- **Core** -- Spawn dynamically new STATICs in your missions.
+--- **Core** - Spawn new statics in your running missions.
 --  
 -- ===
 -- 
--- SPAWNSTATIC spawns static structures in your missions dynamically. See below the SPAWNSTATIC class documentation.
+-- ## Features:
+-- 
+--   * Spawn new statics from a static already defined using the mission editor.
+--   * Spawn new statics from a given template.
+--   * Spawn new statics from a given type.
+--   * Spawn with a custom heading and location.
+--   * Spawn within a zone.
 -- 
 -- ===
 -- 
@@ -77,20 +83,22 @@ SPAWNSTATIC = {
 --- Creates the main object to spawn a @{Static} defined in the ME.
 -- @param #SPAWNSTATIC self
 -- @param #string SpawnTemplatePrefix is the name of the Group in the ME that defines the Template.  Each new group will have the name starting with SpawnTemplatePrefix.
+-- @param DCS#country.id SpawnCountryID The ID of the country.
+-- @param DCS#coalition.side SpawnCoalitionID The ID of the coalition.
 -- @return #SPAWNSTATIC
-function SPAWNSTATIC:NewFromStatic( SpawnTemplatePrefix, SpawnCountryID ) --R2.1
+function SPAWNSTATIC:NewFromStatic( SpawnTemplatePrefix, SpawnCountryID, SpawnCoalitionID )
 	local self = BASE:Inherit( self, BASE:New() ) -- #SPAWNSTATIC
 	self:F( { SpawnTemplatePrefix } )
   
-	local TemplateStatic, CoalitionID, CategoryID, CountryID = _DATABASE:GetStaticUnitTemplate( SpawnTemplatePrefix )
+	local TemplateStatic, CoalitionID, CategoryID, CountryID = _DATABASE:GetStaticGroupTemplate( SpawnTemplatePrefix )
 	if TemplateStatic then
 		self.SpawnTemplatePrefix = SpawnTemplatePrefix
 		self.CountryID = SpawnCountryID or CountryID
 		self.CategoryID = CategoryID
-		self.CoalitionID = CoalitionID
+		self.CoalitionID = SpawnCoalitionID or CoalitionID
 		self.SpawnIndex = 0
 	else
-		error( "SPAWNSTATIC:New: There is no group declared in the mission editor with SpawnTemplatePrefix = '" .. SpawnTemplatePrefix .. "'" )
+		error( "SPAWNSTATIC:New: There is no static declared in the mission editor with SpawnTemplatePrefix = '" .. SpawnTemplatePrefix .. "'" )
 	end
 
   self:SetEventPriority( 5 )
@@ -102,12 +110,13 @@ end
 -- @param #SPAWNSTATIC self
 -- @param #string SpawnTypeName is the name of the type.
 -- @return #SPAWNSTATIC
-function SPAWNSTATIC:NewFromType( SpawnTypeName, SpawnShapeName, SpawnCategory, CountryID ) --R2.1
+function SPAWNSTATIC:NewFromType( SpawnTypeName, SpawnShapeName, SpawnCategory, SpawnCountryID, SpawnCoalitionID ) 
   local self = BASE:Inherit( self, BASE:New() ) -- #SPAWNSTATIC
   self:F( { SpawnTypeName } )
   
   self.SpawnTypeName = SpawnTypeName
-  self.CountryID = CountryID
+  self.CountryID = SpawnCountryID
+  self.CoalitionID = SpawnCoalitionID
   self.SpawnIndex = 0
 
   self:SetEventPriority( 5 )
@@ -124,32 +133,28 @@ end
 function SPAWNSTATIC:Spawn( Heading, NewName ) --R2.3
   self:F( { Heading, NewName  } )
   
-  local StaticTemplate = _DATABASE:GetStaticUnitTemplate( self.SpawnTemplatePrefix )
+  local StaticTemplate, CoalitionID, CategoryID, CountryID = _DATABASE:GetStaticGroupTemplate( self.SpawnTemplatePrefix )
   
   if StaticTemplate then
   
-    local CountryID = self.CountryID
-    local CountryName = _DATABASE.COUNTRY_NAME[CountryID]
+    local StaticUnitTemplate = StaticTemplate.units[1]
   
     StaticTemplate.name = NewName or string.format("%s#%05d", self.SpawnTemplatePrefix, self.SpawnIndex )
     StaticTemplate.heading = ( Heading / 180 ) * math.pi
     
-    StaticTemplate.CountryID = nil
-    StaticTemplate.CoalitionID = nil
-    StaticTemplate.CategoryID = nil
-    
-    local Static = coalition.addStaticObject( CountryID, StaticTemplate )
+    _DATABASE:_RegisterStaticTemplate( StaticTemplate, CoalitionID, CategoryID, CountryID )
+
+    local Static = coalition.addStaticObject( self.CountryID or CountryID, StaticTemplate.units[1] )
     
     self.SpawnIndex = self.SpawnIndex + 1
   
-    return Static
+    return _DATABASE:FindStatic(Static:getName())
   end
   
   return nil
 end
 
 
-
 --- Creates a new @{Static} from a POINT_VEC2.
 -- @param #SPAWNSTATIC self
 -- @param Core.Point#POINT_VEC2 PointVec2 The 2D coordinate where to spawn the static.
@@ -159,64 +164,53 @@ end
 function SPAWNSTATIC:SpawnFromPointVec2( PointVec2, Heading, NewName ) --R2.1
   self:F( { PointVec2, Heading, NewName  } )
   
-  local StaticTemplate = _DATABASE:GetStaticUnitTemplate( self.SpawnTemplatePrefix )
+  local StaticTemplate, CoalitionID, CategoryID, CountryID = _DATABASE:GetStaticGroupTemplate( self.SpawnTemplatePrefix )
   
   if StaticTemplate then
-
-    local CountryID = self.CountryID
-    local CountryName = _DATABASE.COUNTRY_NAME[CountryID]
-    
-    StaticTemplate.x = PointVec2.x
-    StaticTemplate.y = PointVec2.z
   
-    StaticTemplate.units = nil
+    local StaticUnitTemplate = StaticTemplate.units[1]
+  
+    StaticUnitTemplate.x = PointVec2.x
+    StaticUnitTemplate.y = PointVec2.z
+  
     StaticTemplate.route = nil
     StaticTemplate.groupId = nil
     
     StaticTemplate.name = NewName or string.format("%s#%05d", self.SpawnTemplatePrefix, self.SpawnIndex )
-    StaticTemplate.heading = ( Heading / 180 ) * math.pi
+    StaticUnitTemplate.name = StaticTemplate.name
+    StaticUnitTemplate.heading = ( Heading / 180 ) * math.pi
     
-    StaticTemplate.CountryID = nil
-    StaticTemplate.CoalitionID = nil
-    StaticTemplate.CategoryID = nil
+    _DATABASE:_RegisterStaticTemplate( StaticTemplate, CoalitionID, CategoryID, CountryID)
     
-    local Static = coalition.addStaticObject( CountryID, StaticTemplate )
+    self:F({StaticTemplate = StaticTemplate})
+
+    local Static = coalition.addStaticObject( self.CountryID or CountryID, StaticTemplate.units[1] )
     
     self.SpawnIndex = self.SpawnIndex + 1
-  
-    return Static
+    
+    return _DATABASE:FindStatic(Static:getName())
   end
   
   return nil
 end
 
 
---- Creates the original @{Static} at a POINT_VEC2.
+--- Respawns the original @{Static}.
 -- @param #SPAWNSTATIC self
--- @param Core.Point#POINT_VEC2 PointVec2 The 2D coordinate where to spawn the static.
--- @param #number Heading The heading of the static, which is a number in degrees from 0 to 360.
--- @param #string (optional) The name of the new static.
 -- @return #SPAWNSTATIC
 function SPAWNSTATIC:ReSpawn()
   
-  local StaticTemplate = _DATABASE:GetStaticUnitTemplate( self.SpawnTemplatePrefix )
+  local StaticTemplate, CoalitionID, CategoryID, CountryID = _DATABASE:GetStaticGroupTemplate( self.SpawnTemplatePrefix )
   
   if StaticTemplate then
 
-    local CountryID = self.CountryID
-    local CountryName = _DATABASE.COUNTRY_NAME[CountryID]
-    
-    StaticTemplate.units = nil
+    local StaticUnitTemplate = StaticTemplate.units[1]
     StaticTemplate.route = nil
     StaticTemplate.groupId = nil
     
-    StaticTemplate.CountryID = nil
-    StaticTemplate.CoalitionID = nil
-    StaticTemplate.CategoryID = nil
+    local Static = coalition.addStaticObject( self.CountryID or CountryID, StaticTemplate.units[1] )
     
-    local Static = coalition.addStaticObject( CountryID, StaticTemplate )
-    
-    return Static
+    return _DATABASE:FindStatic(Static:getName())
   end
   
   return nil
@@ -230,24 +224,20 @@ end
 -- @return #SPAWNSTATIC
 function SPAWNSTATIC:ReSpawnAt( Coordinate, Heading )
   
-  local StaticTemplate = _DATABASE:GetStaticUnitTemplate( self.SpawnTemplatePrefix )
+  local StaticTemplate, CoalitionID, CategoryID, CountryID = _DATABASE:GetStaticGroupTemplate( self.SpawnTemplatePrefix )
   
   if StaticTemplate then
 
-    local CountryID = self.CountryID
-    
-    StaticTemplate.x = Coordinate.x
-    StaticTemplate.y = Coordinate.z
+    local StaticUnitTemplate = StaticTemplate.units[1]
+  
+    StaticUnitTemplate.x = Coordinate.x
+    StaticUnitTemplate.y = Coordinate.z
 
-    StaticTemplate.heading = Heading and ( ( Heading / 180 ) * math.pi ) or StaticTemplate.heading
-
-    StaticTemplate.CountryID = nil
-    StaticTemplate.CoalitionID = nil
-    StaticTemplate.CategoryID = nil
+    StaticUnitTemplate.heading = Heading and ( ( Heading / 180 ) * math.pi ) or StaticTemplate.heading
     
-    local Static = coalition.addStaticObject( CountryID, StaticTemplate )
+    local Static = coalition.addStaticObject( self.CountryID or CountryID, StaticTemplate.units[1] )
     
-    return Static
+    return _DATABASE:FindStatic(Static:getName())
   end
   
   return nil

Moose Development/Moose/Core/Spot.lua

@@ -1,11 +1,12 @@
---- **Core** -- Management of SPOT logistics, that can be transported from and to transportation carriers.
+--- **Core** - Management of spotting logistics, that can be activated and deactivated upon command.
 --
 -- ===
 -- 
 -- SPOT implements the DCS Spot class functionality, but adds additional luxury to be able to:
 -- 
 --   * Spot for a defined duration.
---   * wiggle the spot at the target.
+--   * Updates of laer spot position every 0.2 seconds for moving targets.
+--   * Wiggle the spot at the target.
 --   * Provide a @{Wrapper.Unit} as a target, instead of a point.
 --   * Implement a status machine, LaseOn, LaseOff.
 --
@@ -49,7 +50,8 @@ do
   --- Implements the target spotting or marking functionality, but adds additional luxury to be able to:
   -- 
   --   * Mark targets for a defined duration.
-  --   * wiggle the spot at the target.
+  --   * Updates of laer spot position every 0.2 seconds for moving targets.
+  --   * Wiggle the spot at the target.
   --   * Provide a @{Wrapper.Unit} as a target, instead of a point.
   --   * Implement a status machine, LaseOn, LaseOff.
   -- 
@@ -85,9 +87,7 @@ do
   
   --- SPOT Constructor.
   -- @param #SPOT self
-  -- @param Wrapper.Unit#UNIT Recce
-  -- @param #number LaserCode
-  -- @param #number Duration
+  -- @param Wrapper.Unit#UNIT Recce Unit that is lasing
   -- @return #SPOT
   function SPOT:New( Recce )
   
@@ -115,12 +115,17 @@ do
     --- LaseOn Trigger for SPOT
     -- @function [parent=#SPOT] LaseOn
     -- @param #SPOT self
+    -- @param Wrapper.Positionable#POSITIONABLE Target
+    -- @param #number LaserCode Laser code.
+    -- @param #number Duration Duration of lasing in seconds.
     
     --- LaseOn Asynchronous Trigger for SPOT
     -- @function [parent=#SPOT] __LaseOn
     -- @param #SPOT self
     -- @param #number Delay
-    
+    -- @param Wrapper.Positionable#POSITIONABLE Target
+    -- @param #number LaserCode Laser code.
+    -- @param #number Duration Duration of lasing in seconds.
     
     
     self:AddTransition( "On",  "Lasing", "On" )
@@ -193,9 +198,9 @@ do
   -- @param From
   -- @param Event
   -- @param To
-  -- @param Wrapper.Positionable#POSITIONABLE Target
-  -- @param #number LaserCode
-  -- @param #number Duration
+  -- @param Wrapper.Positionable#POSITIONABLE Target Unit that is being lased.
+  -- @param #number LaserCode Laser code.
+  -- @param #number Duration Duration of lasing in seconds.
   function SPOT:onafterLaseOn( From, Event, To, Target, LaserCode, Duration )
     self:F( { "LaseOn", Target, LaserCode, Duration } )
 

Moose Development/Moose/Core/UserFlag.lua

@@ -1,8 +1,10 @@
---- **Core (WIP)** -- Manage user flags.
+--- **Core** - Manage user flags to interact with the mission editor trigger system and server side scripts.
 --
 -- ===
 -- 
--- Management of DCS User Flags.
+-- ## Features:
+-- 
+--   * Set or get DCS user flags within running missions.
 -- 
 -- ===
 -- 
@@ -22,7 +24,7 @@ do -- UserFlag
 
   --- Management of DCS User Flags.
   -- 
-  -- ## USERFLAG constructor
+  -- # 1. USERFLAG constructor
   --   
   --   * @{#USERFLAG.New}(): Creates a new USERFLAG object.
   -- 

Moose Development/Moose/Core/UserSound.lua

@@ -1,7 +1,13 @@
---- **Core (WIP)** -- Manage user sound.
+--- **Core** - Manage user sound.
 --
 -- ===
 -- 
+-- ## Features:
+-- 
+--   * Play sounds wihtin running missions.
+-- 
+-- ===
+-- 
 -- Management of DCS User Sound.
 -- 
 -- ===

Moose Development/Moose/Core/Velocity.lua

@@ -1,7 +1,15 @@
---- **Core** -- VELOCITY models a speed, which can be expressed in various formats according the Settings.
+--- **Core** - Models a velocity or speed, which can be expressed in various formats according the settings.
 -- 
 -- ===
 -- 
+-- ## Features:
+-- 
+--   * Convert velocity in various metric systems.
+--   * Set the velocity.
+--   * Create a text in a specific format of a velocity.
+--   
+-- ===
+-- 
 -- ### Author: **FlightControl**
 -- ### Contributions: 
 -- 

Moose Development/Moose/Core/Zone.lua

@@ -1,7 +1,24 @@
---- **Core** -- ZONE classes define **zones** within your mission of **various forms**, with **various capabilities**.
+--- **Core** - Define zones within your mission of various forms, with various capabilities.
 -- 
 -- ===
 -- 
+-- ## Features:
+-- 
+--   * Create radius zones.
+--   * Create trigger zones.
+--   * Create polygon zones.
+--   * Create moving zones around a unit.
+--   * Create moving zones around a group.
+--   * Provide the zone behaviour. Some zones are static, while others are moveable.
+--   * Enquiry if a coordinate is within a zone.
+--   * Smoke zones.
+--   * Set a zone probability to control zone selection.
+--   * Get zone coordinates.
+--   * Get zone properties.
+--   * Get zone bounding box.
+--   * Set/get zone name.
+--   
+-- 
 -- There are essentially two core functions that zones accomodate:
 -- 
 --   * Test if an object is within the zone boundaries.
@@ -312,12 +329,13 @@ end
 -- @param Utilities.Utils#SMOKECOLOR SmokeColor The smoke color.
 function ZONE_BASE:SmokeZone( SmokeColor )
   self:F2( SmokeColor )
-
+  
 end
 
 --- Set the randomization probability of a zone to be selected.
 -- @param #ZONE_BASE self
--- @param ZoneProbability A value between 0 and 1. 0 = 0% and 1 = 100% probability.
+-- @param #number ZoneProbability A value between 0 and 1. 0 = 0% and 1 = 100% probability.
+-- @return #ZONE_BASE self
 function ZONE_BASE:SetZoneProbability( ZoneProbability )
   self:F( { self:GetName(), ZoneProbability = ZoneProbability } )
   
@@ -329,7 +347,7 @@ end
 -- @param #ZONE_BASE self
 -- @return #number A value between 0 and 1. 0 = 0% and 1 = 100% probability.
 function ZONE_BASE:GetZoneProbability()
-  self:F2()
+  self:F2()  
   
   return self.ZoneProbability
 end
@@ -644,14 +662,14 @@ function ZONE_RADIUS:Scan( ObjectCategories )
         local CoalitionDCSUnit = ZoneObject:getCoalition()
         self.ScanData.Coalitions[CoalitionDCSUnit] = true
         self.ScanData.Units[ZoneObject] = ZoneObject
-        self:F( { Name = ZoneObject:getName(), Coalition = CoalitionDCSUnit } )
+        self:F2( { Name = ZoneObject:getName(), Coalition = CoalitionDCSUnit } )
       end
       if ObjectCategory == Object.Category.SCENERY then
         local SceneryType = ZoneObject:getTypeName()
         local SceneryName = ZoneObject:getName()
         self.ScanData.Scenery[SceneryType] = self.ScanData.Scenery[SceneryType] or {}
         self.ScanData.Scenery[SceneryType][SceneryName] = SCENERY:Register( SceneryName, ZoneObject )
-        self:F( { SCENERY =  self.ScanData.Scenery[SceneryType][SceneryName] } )
+        self:F2( { SCENERY =  self.ScanData.Scenery[SceneryType][SceneryName] } )
       end
     end
     return true
@@ -934,7 +952,7 @@ end
 function ZONE_RADIUS:GetRandomCoordinate( inner, outer )
   self:F( self.ZoneName, inner, outer )
 
-  local Coordinate = COORDINATE:NewFromVec2( self:GetRandomVec2() )
+  local Coordinate = COORDINATE:NewFromVec2( self:GetRandomVec2(inner, outer) )
 
   self:T3( { Coordinate = Coordinate } )
   
@@ -1079,6 +1097,7 @@ function ZONE_UNIT:GetVec2()
   local ZoneVec2 = self.ZoneUNIT:GetVec2()
   if ZoneVec2 then
   
+    local heading
     if self.relative_to_unit then
         heading = ( self.ZoneUNIT:GetHeading() or 0.0 ) * math.pi / 180.0
       else
@@ -1118,7 +1137,8 @@ function ZONE_UNIT:GetRandomVec2()
   self:F( self.ZoneName )
 
   local RandomVec2 = {}
-  local Vec2 = self.ZoneUNIT:GetVec2()
+  --local Vec2 = self.ZoneUNIT:GetVec2()  -- FF: This does not take care of the new offset feature!
+  local Vec2 = self:GetVec2()
   
   if not Vec2 then
     Vec2 = self.LastVec2
@@ -1174,6 +1194,7 @@ function ZONE_GROUP:New( ZoneName, ZoneGROUP, Radius )
   self:F( { ZoneName, ZoneGROUP:GetVec2(), Radius } )
 
   self._.ZoneGROUP = ZoneGROUP
+  self._.ZoneVec2Cache = self._.ZoneGROUP:GetVec2()
 
   -- Zone objects are added to the _DATABASE and SET_ZONE objects.
   _EVENTDISPATCHER:CreateEventNewZone( self )
@@ -1188,7 +1209,14 @@ end
 function ZONE_GROUP:GetVec2()
   self:F( self.ZoneName )
   
-  local ZoneVec2 = self._.ZoneGROUP:GetVec2()
+  local ZoneVec2 = nil
+  
+  if self._.ZoneGROUP:IsAlive() then
+    ZoneVec2 = self._.ZoneGROUP:GetVec2()
+    self._.ZoneVec2Cache = ZoneVec2
+  else
+    ZoneVec2 = self._.ZoneVec2Cache
+  end
 
   self:T( { ZoneVec2 } )
   
@@ -1550,6 +1578,9 @@ function ZONE_POLYGON:New( ZoneName, ZoneGroup )
   local self = BASE:Inherit( self, ZONE_POLYGON_BASE:New( ZoneName, GroupPoints ) )
   self:F( { ZoneName, ZoneGroup, self._.Polygon } )
 
+  -- Zone objects are added to the _DATABASE and SET_ZONE objects.
+  _EVENTDISPATCHER:CreateEventNewZone( self )
+
   return self
 end
 
@@ -1557,7 +1588,6 @@ end
 --- Constructor to create a ZONE_POLYGON instance, taking the zone name and the **name** of the @{Wrapper.Group#GROUP} defined within the Mission Editor.
 -- The @{Wrapper.Group#GROUP} waypoints define the polygon corners. The first and the last point are automatically connected by ZONE_POLYGON.
 -- @param #ZONE_POLYGON self
--- @param #string ZoneName Name of the zone.
 -- @param #string GroupName The group name of the GROUP defining the waypoints within the Mission Editor to define the polygon shape.
 -- @return #ZONE_POLYGON self
 function ZONE_POLYGON:NewFromGroupName( GroupName )
@@ -1569,6 +1599,9 @@ function ZONE_POLYGON:NewFromGroupName( GroupName )
   local self = BASE:Inherit( self, ZONE_POLYGON_BASE:New( GroupName, GroupPoints ) )
   self:F( { GroupName, ZoneGroup, self._.Polygon } )
 
+  -- Zone objects are added to the _DATABASE and SET_ZONE objects.
+  _EVENTDISPATCHER:CreateEventNewZone( self )
+
   return self
 end
 
@@ -1583,4 +1616,103 @@ function ZONE_POLYGON:FindByName( ZoneName )
   return ZoneFound
 end
 
+do -- ZONE_AIRBASE
 
+  --- @type ZONE_AIRBASE
+  -- @extends #ZONE_RADIUS
+  
+  
+  --- The ZONE_AIRBASE class defines by a zone around a @{Wrapper.Airbase#AIRBASE} with a radius.
+  -- This class implements the inherited functions from @{Core.Zone#ZONE_RADIUS} taking into account the own zone format and properties.
+  -- 
+  -- @field #ZONE_AIRBASE
+  ZONE_AIRBASE = {
+    ClassName="ZONE_AIRBASE",
+    }
+    
+    
+    
+  --- Constructor to create a ZONE_AIRBASE instance, taking the zone name, a zone @{Wrapper.Airbase#AIRBASE} and a radius.
+  -- @param #ZONE_AIRBASE self
+  -- @param #string AirbaseName Name of the airbase.
+  -- @param DCS#Distance Radius (Optional)The radius of the zone in meters. Default 4000 meters.
+  -- @return #ZONE_AIRBASE self
+  function ZONE_AIRBASE:New( AirbaseName, Radius )
+  
+    Radius=Radius or 4000
+  
+    local Airbase = AIRBASE:FindByName( AirbaseName )
+  
+    local self = BASE:Inherit( self, ZONE_RADIUS:New( AirbaseName, Airbase:GetVec2(), Radius ) )
+  
+    self._.ZoneAirbase = Airbase
+    self._.ZoneVec2Cache = self._.ZoneAirbase:GetVec2()
+  
+    -- Zone objects are added to the _DATABASE and SET_ZONE objects.
+    _EVENTDISPATCHER:CreateEventNewZone( self )
+    
+    return self
+  end
+  
+  --- Get the airbase as part of the ZONE_AIRBASE object.
+  -- @param #ZONE_AIRBASE self
+  -- @return Wrapper.Airbase#AIRBASE The airbase.
+  function ZONE_AIRBASE:GetAirbase()
+    return self._.ZoneAirbase
+  end  
+  
+  --- Returns the current location of the @{Wrapper.Group}.
+  -- @param #ZONE_AIRBASE self
+  -- @return DCS#Vec2 The location of the zone based on the @{Wrapper.Group} location.
+  function ZONE_AIRBASE:GetVec2()
+    self:F( self.ZoneName )
+    
+    local ZoneVec2 = nil
+    
+    if self._.ZoneAirbase:IsAlive() then
+      ZoneVec2 = self._.ZoneAirbase:GetVec2()
+      self._.ZoneVec2Cache = ZoneVec2
+    else
+      ZoneVec2 = self._.ZoneVec2Cache
+    end
+  
+    self:T( { ZoneVec2 } )
+    
+    return ZoneVec2
+  end
+  
+  --- Returns a random location within the zone of the @{Wrapper.Group}.
+  -- @param #ZONE_AIRBASE self
+  -- @return DCS#Vec2 The random location of the zone based on the @{Wrapper.Group} location.
+  function ZONE_AIRBASE:GetRandomVec2()
+    self:F( self.ZoneName )
+  
+    local Point = {}
+    local Vec2 = self._.ZoneAirbase:GetVec2()
+  
+    local angle = math.random() * math.pi*2;
+    Point.x = Vec2.x + math.cos( angle ) * math.random() * self:GetRadius();
+    Point.y = Vec2.y + math.sin( angle ) * math.random() * self:GetRadius();
+    
+    self:T( { Point } )
+    
+    return Point
+  end
+  
+  --- Returns a @{Core.Point#POINT_VEC2} object reflecting a random 2D location within the zone.
+  -- @param #ZONE_AIRBASE self
+  -- @param #number inner (optional) Minimal distance from the center of the zone. Default is 0.
+  -- @param #number outer (optional) Maximal distance from the outer edge of the zone. Default is the radius of the zone.
+  -- @return Core.Point#POINT_VEC2 The @{Core.Point#POINT_VEC2} object reflecting the random 3D location within the zone.
+  function ZONE_AIRBASE:GetRandomPointVec2( inner, outer )
+    self:F( self.ZoneName, inner, outer )
+  
+    local PointVec2 = POINT_VEC2:NewFromVec2( self:GetRandomVec2() )
+  
+    self:T3( { PointVec2 } )
+    
+    return PointVec2
+  end
+
+
+end

Moose Development/Moose/DCS.lua

@@ -1,76 +1,133 @@
 --- DCS API prototypes
+-- See [https://wiki.hoggitworld.com/view/Simulator_Scripting_Engine_Documentation](https://wiki.hoggitworld.com/view/Simulator_Scripting_Engine_Documentation) 
+-- for further explanation and examples.
 -- @module DCS
 -- @image MOOSE.JPG
 
 do -- world
 
-  --- @type world
-  -- @field #world.event event
+  --- [DCS Enum world](https://wiki.hoggitworld.com/view/DCS_enum_world)
+  -- @type world
+  -- @field #world.event event [https://wiki.hoggitworld.com/view/DCS_enum_world](https://wiki.hoggitworld.com/view/DCS_enum_world)
+  -- @field #world.BirthPlace BirthPlace The birthplace enumerator is used to define where an aircraft or helicopter has spawned in association with birth events.
+  -- @field #world.VolumeType VolumeType The volumeType enumerator defines the types of 3d geometery used within the [world.searchObjects](https://wiki.hoggitworld.com/view/DCS_func_searchObjects) function.
+
+  --- The world singleton contains functions centered around two different but extremely useful functions.
+  -- * Events and event handlers are all governed within world.
+  -- * A number of functions to get information about the game world.
+  -- 
+  -- See [https://wiki.hoggitworld.com/view/DCS_singleton_world](https://wiki.hoggitworld.com/view/DCS_singleton_world)
+  -- @field #world world
+  world = {}
   
-  --- @type world.event
-  -- @field S_EVENT_INVALID
-  -- @field S_EVENT_SHOT
-  -- @field S_EVENT_HIT
-  -- @field S_EVENT_TAKEOFF
-  -- @field S_EVENT_LAND
-  -- @field S_EVENT_CRASH
-  -- @field S_EVENT_EJECTION
-  -- @field S_EVENT_REFUELING
-  -- @field S_EVENT_DEAD
-  -- @field S_EVENT_PILOT_DEAD
-  -- @field S_EVENT_BASE_CAPTURED
-  -- @field S_EVENT_MISSION_START
-  -- @field S_EVENT_MISSION_END
-  -- @field S_EVENT_TOOK_CONTROL
-  -- @field S_EVENT_REFUELING_STOP
-  -- @field S_EVENT_BIRTH
-  -- @field S_EVENT_HUMAN_FAILURE
-  -- @field S_EVENT_ENGINE_STARTUP
-  -- @field S_EVENT_ENGINE_SHUTDOWN
-  -- @field S_EVENT_PLAYER_ENTER_UNIT
-  -- @field S_EVENT_PLAYER_LEAVE_UNIT
-  -- @field S_EVENT_PLAYER_COMMENT
-  -- @field S_EVENT_SHOOTING_START
-  -- @field S_EVENT_SHOOTING_END
+  --- [https://wiki.hoggitworld.com/view/DCS_enum_world](https://wiki.hoggitworld.com/view/DCS_enum_world)
+  -- @type world.event
+  -- @field S_EVENT_INVALID 
+  -- @field S_EVENT_SHOT [https://wiki.hoggitworld.com/view/DCS_event_shot](https://wiki.hoggitworld.com/view/DCS_event_shot)
+  -- @field S_EVENT_HIT [https://wiki.hoggitworld.com/view/DCS_event_hit](https://wiki.hoggitworld.com/view/DCS_event_hit)
+  -- @field S_EVENT_TAKEOFF [https://wiki.hoggitworld.com/view/DCS_event_takeoff](https://wiki.hoggitworld.com/view/DCS_event_takeoff)
+  -- @field S_EVENT_LAND [https://wiki.hoggitworld.com/view/DCS_event_land](https://wiki.hoggitworld.com/view/DCS_event_land)
+  -- @field S_EVENT_CRASH [https://wiki.hoggitworld.com/view/DCS_event_crash](https://wiki.hoggitworld.com/view/DCS_event_crash)
+  -- @field S_EVENT_EJECTION [https://wiki.hoggitworld.com/view/DCS_event_ejection](https://wiki.hoggitworld.com/view/DCS_event_ejection)
+  -- @field S_EVENT_REFUELING [https://wiki.hoggitworld.com/view/DCS_event_refueling](https://wiki.hoggitworld.com/view/DCS_event_refueling)
+  -- @field S_EVENT_DEAD [https://wiki.hoggitworld.com/view/DCS_event_dead](https://wiki.hoggitworld.com/view/DCS_event_dead)
+  -- @field S_EVENT_PILOT_DEAD [https://wiki.hoggitworld.com/view/DCS_event_pilot_dead](https://wiki.hoggitworld.com/view/DCS_event_pilot_dead)
+  -- @field S_EVENT_BASE_CAPTURED [https://wiki.hoggitworld.com/view/DCS_event_base_captured](https://wiki.hoggitworld.com/view/DCS_event_base_captured)
+  -- @field S_EVENT_MISSION_START [https://wiki.hoggitworld.com/view/DCS_event_mission_start](https://wiki.hoggitworld.com/view/DCS_event_mission_start)
+  -- @field S_EVENT_MISSION_END [https://wiki.hoggitworld.com/view/DCS_event_mission_end](https://wiki.hoggitworld.com/view/DCS_event_mission_end)
+  -- @field S_EVENT_TOOK_CONTROL 
+  -- @field S_EVENT_REFUELING_STOP [https://wiki.hoggitworld.com/view/DCS_event_refueling_stop](https://wiki.hoggitworld.com/view/DCS_event_refueling_stop)
+  -- @field S_EVENT_BIRTH [https://wiki.hoggitworld.com/view/DCS_event_birth](https://wiki.hoggitworld.com/view/DCS_event_birth)
+  -- @field S_EVENT_HUMAN_FAILURE [https://wiki.hoggitworld.com/view/DCS_event_human_failure](https://wiki.hoggitworld.com/view/DCS_event_human_failure)
+  -- @field S_EVENT_ENGINE_STARTUP [https://wiki.hoggitworld.com/view/DCS_event_engine_startup](https://wiki.hoggitworld.com/view/DCS_event_engine_startup)
+  -- @field S_EVENT_ENGINE_SHUTDOWN [https://wiki.hoggitworld.com/view/DCS_event_engine_shutdown](https://wiki.hoggitworld.com/view/DCS_event_engine_shutdown)
+  -- @field S_EVENT_PLAYER_ENTER_UNIT [https://wiki.hoggitworld.com/view/DCS_event_player_enter_unit](https://wiki.hoggitworld.com/view/DCS_event_player_enter_unit)
+  -- @field S_EVENT_PLAYER_LEAVE_UNIT [https://wiki.hoggitworld.com/view/DCS_event_player_leave_unit](https://wiki.hoggitworld.com/view/DCS_event_player_leave_unit)
+  -- @field S_EVENT_PLAYER_COMMENT 
+  -- @field S_EVENT_SHOOTING_START [https://wiki.hoggitworld.com/view/DCS_event_shooting_start](https://wiki.hoggitworld.com/view/DCS_event_shooting_start)
+  -- @field S_EVENT_SHOOTING_END [https://wiki.hoggitworld.com/view/DCS_event_shooting_end](https://wiki.hoggitworld.com/view/DCS_event_shooting_end)
+  -- @field S_EVENT_MARK ADDED [https://wiki.hoggitworld.com/view/DCS_event_mark_added](https://wiki.hoggitworld.com/view/DCS_event_mark_added)
+  -- @field S_EVENT_MARK CHANGE [https://wiki.hoggitworld.com/view/DCS_event_mark_change](https://wiki.hoggitworld.com/view/DCS_event_mark_change)
+  -- @field S_EVENT_MARK REMOVE [https://wiki.hoggitworld.com/view/DCS_event_mark_remove](https://wiki.hoggitworld.com/view/DCS_event_mark_remove)
   -- @field S_EVENT_MAX
   
-  world = {} --#world
+  --- The birthplace enumerator is used to define where an aircraft or helicopter has spawned in association with birth events.
+  -- @type world.BirthPlace
+  -- @field wsBirthPlace_Air
+  -- @field wsBirthPlace_RunWay
+  -- @field wsBirthPlace_Park
+  -- @field wsBirthPlace_Heliport_Hot
+  -- @field wsBirthPlace_Heliport_Cold
+
+  --- The volumeType enumerator defines the types of 3d geometery used within the #world.searchObjects function.
+  -- @type world.VolumeType
+  -- @field SEGMENT
+  -- @field BOX
+  -- @field SPHERE
+  -- @field PYRAMID
+
+  --- Adds a function as an event handler that executes whenever a simulator event occurs. See [hoggit](https://wiki.hoggitworld.com/view/DCS_func_addEventHandler).
+  -- @function [parent=#world] addEventHandler
+  -- @param #table handler Event handler table.
   
+  --- Removes the specified event handler from handling events.
+  -- @function [parent=#world] removeEventHandler
+  -- @param #table handler Event handler table.
+  
+  --- Returns a table of the single unit object in the game who's skill level is set as "Player". See [hoggit](https://wiki.hoggitworld.com/view/DCS_func_getPlayer).
+  -- There is only a single player unit in a mission and in single player the user will always spawn into this unit automatically unless other client or Combined Arms slots are available.
+  -- @function [parent=#world] getPlayer
+  -- @return DCS#Unit  
+  
+  --- Searches a defined volume of 3d space for the specified objects within it and then can run function on each returned object. See [hoggit](https://wiki.hoggitworld.com/view/DCS_func_searchObjects).
+  -- @function [parent=#world] searchObjects
+  -- @param DCS#Object.Category objectcategory Category (can be a table) of objects to search.
+  -- @param DCS#word.VolumeType volume Shape of the search area/volume.
+  -- @param ObjectSeachHandler handler A function that handles the search.
+  -- @param #table any Additional data.
+  -- @return DCS#Unit  
+  
+  --- Returns a table of mark panels indexed numerically that are present within the mission. See [hoggit](https://wiki.hoggitworld.com/view/DCS_func_getMarkPanels)
+  -- @function [parent=#world] getMarkPanels
+  -- @return #table Table of marks.
+ 
 end -- world
 
 
 do -- env
 
-  --- @type env
-  
+  --- [DCS Singleton env](https://wiki.hoggitworld.com/view/DCS_singleton_env)
+  -- @type env
+
   --- Add message to simulator log with caption "INFO". Message box is optional.
   -- @function [parent=#env] info
-  -- @field #string message message string to add to log.
-  -- @field #boolean showMessageBox If the parameter is true Message Box will appear. Optional.
+  -- @param #string message message string to add to log.
+  -- @param #boolean showMessageBox If the parameter is true Message Box will appear. Optional.
   
   --- Add message to simulator log with caption "WARNING". Message box is optional. 
   -- @function [parent=#env] warning
-  -- @field #string message message string to add to log.
-  -- @field #boolean showMessageBox If the parameter is true Message Box will appear. Optional.
+  -- @param #string message message string to add to log.
+  -- @param #boolean showMessageBox If the parameter is true Message Box will appear. Optional.
   
   --- Add message to simulator log with caption "ERROR". Message box is optional.
   -- @function [parent=#env] error
-  -- @field #string message message string to add to log.
-  -- @field #boolean showMessageBox If the parameter is true Message Box will appear. Optional.
+  -- @param #string message message string to add to log.
+  -- @param #boolean showMessageBox If the parameter is true Message Box will appear. Optional.
   
   --- Enables/disables appearance of message box each time lua error occurs.
   -- @function [parent=#env] setErrorMessageBoxEnabled
-  -- @field #boolean on if true message box appearance is enabled.
-  
-  env = {} --#env
+  -- @param #boolean on if true message box appearance is enabled.
+
+  --- [DCS Singleton env](https://wiki.hoggitworld.com/view/DCS_singleton_env)
+  env = {} --#env 
   
 end -- env
 
 
 do -- timer
 
-  --- @type timer
-  
+  --- [DCS Singleton timer](https://wiki.hoggitworld.com/view/DCS_singleton_timer)
+  -- @type timer
   
   --- Returns model time in seconds.
   -- @function [parent=#timer] getTime
@@ -110,6 +167,7 @@ do -- timer
   -- @function [parent=#timer] removeFunction
   -- @param functionId Function identifier to remove from schedule 
   
+  --- [DCS Singleton timer](https://wiki.hoggitworld.com/view/DCS_singleton_timer)
   timer = {} --#timer
 
 end 
@@ -117,11 +175,12 @@ end
 
 do -- land
 
-  --- @type land
+  --- [DCS Singleton land](https://wiki.hoggitworld.com/view/DCS_singleton_land)
+  -- @type land
   -- @field #land.SurfaceType SurfaceType
   
-  
-  --- @type land.SurfaceType
+  --- [Type of surface enumerator](https://wiki.hoggitworld.com/view/DCS_singleton_land)
+  -- @type land.SurfaceType
   -- @field LAND
   -- @field SHALLOW_WATER
   -- @field WATER
@@ -138,16 +197,20 @@ do -- land
   -- @param #Vec2 point Point on the land. 
   -- @return #land.SurfaceType
   
+  --- [DCS Singleton land](https://wiki.hoggitworld.com/view/DCS_singleton_land)
   land = {} --#land
 
 end -- land
 
 do -- country
 
-  --- @type country
-  -- @field #country.id id
+  --- [DCS Enum country](https://wiki.hoggitworld.com/view/DCS_enum_country)
+  -- @type country
+  -- @field #country.id id 
   
-  --- @type country.id
+  
+  --- [DCS enumerator country](https://wiki.hoggitworld.com/view/DCS_enum_country)
+  -- @type country.id
   -- @field RUSSIA
   -- @field UKRAINE
   -- @field USA
@@ -223,10 +286,11 @@ do -- country
   -- @field OMAN
   -- @field UNITED_ARAB_EMIRATES
 
-  country = {} -- #country
+  country = {} --#country
 
 end -- country
 
+
 do -- Command
 
   --- @type Command
@@ -239,10 +303,12 @@ end -- Command
 
 do -- coalition
 
-  --- @type coalition
+  --- [DCS Enum coalition](https://wiki.hoggitworld.com/view/DCS_enum_coalition)
+  -- @type coalition
   -- @field #coalition.side side
   
-  --- @type coalition.side
+  --- [DCS Enum coalition.side](https://wiki.hoggitworld.com/view/DCS_enum_coalition)
+  -- @type coalition.side
   -- @field NEUTRAL
   -- @field RED
   -- @field BLUE
@@ -349,7 +415,8 @@ do -- Types
   --- @type Time
   -- @extends #number
   
-  --- A task descriptor (internal structure for DCS World)
+  --- A task descriptor (internal structure for DCS World). See [https://wiki.hoggitworld.com/view/Category:Tasks](https://wiki.hoggitworld.com/view/Category:Tasks).
+  -- In MOOSE, these tasks can be accessed via @{Wrapper.Controllable#CONTROLLABLE}.
   -- @type Task
   -- @field #string id
   -- @field #Task.param param
@@ -365,11 +432,13 @@ end --
 
 do -- Object
 
-  --- @type Object
+  --- [DCS Class Object](https://wiki.hoggitworld.com/view/DCS_Class_Object)
+  -- @type Object
   -- @field #Object.Category Category
   -- @field #Object.Desc Desc
   
-  --- @type Object.Category
+  --- [DCS Enum Object.Category](https://wiki.hoggitworld.com/view/DCS_Class_Object)
+  -- @type Object.Category
   -- @field UNIT
   -- @field WEAPON
   -- @field STATIC
@@ -439,10 +508,10 @@ end -- Object
 
 do -- CoalitionObject
 
-  --- @type CoalitionObject
+  --- [DCS Class CoalitionObject](https://wiki.hoggitworld.com/view/DCS_Class_Coalition_Object)
+  -- @type CoalitionObject
   -- @extends #Object
   
-  
   --- Returns coalition of the object.
   -- @function [parent=#CoalitionObject] getCoalition
   -- @param #CoalitionObject self
@@ -453,14 +522,15 @@ do -- CoalitionObject
   -- @param #CoalitionObject self
   -- @return #country.id
 
-CoalitionObject = {} --#CoalitionObject
+  CoalitionObject = {} --#CoalitionObject
 
 end -- CoalitionObject
 
 
 do -- Airbase
 
-  --- Represents airbases: airdromes, helipads and ships with flying decks or landing pads.  
+  --- [DCS Class Airbase](https://wiki.hoggitworld.com/view/DCS_Class_Airbase)
+  -- Represents airbases: airdromes, helipads and ships with flying decks or landing pads.  
   -- @type Airbase
   -- @extends #CoalitionObject
   -- @field #Airbase.ID ID Identifier of an airbase. It assigned to an airbase by the Mission Editor automatically. This identifier is used in AI tasks to refer an airbase that exists (spawned and not dead) or not. 
@@ -888,6 +958,7 @@ do -- Group
   -- @field HELICOPTER
   -- @field GROUND
   -- @field SHIP
+  -- @field TRAIN
   
   -- Static Functions
   
@@ -912,8 +983,6 @@ do -- Group
   -- @param #Group self 
   -- @return #Group.Category
   
-  --TODO check coalition.side
-  
   --- Returns the coalition of the group.
   -- @function [parent=#Group] getCoalition
   -- @param #Group self 
@@ -962,12 +1031,14 @@ end -- Group
 
 do -- AI
 
-  --- @type AI
+  --- [https://wiki.hoggitworld.com/view/DCS_enum_AI](https://wiki.hoggitworld.com/view/DCS_enum_AI)
+  -- @type AI
   -- @field #AI.Skill Skill
   -- @field #AI.Task Task
   -- @field #AI.Option Option
   
-  --- @type AI.Skill
+  --- [https://wiki.hoggitworld.com/view/DCS_enum_AI](https://wiki.hoggitworld.com/view/DCS_enum_AI)
+  -- @type AI.Skill
   -- @field AVERAGE
   -- @field GOOD
   -- @field HIGH
@@ -975,7 +1046,8 @@ do -- AI
   -- @field PLAYER
   -- @field CLIENT
   
-  --- @type AI.Task
+  --- [https://wiki.hoggitworld.com/view/DCS_enum_AI](https://wiki.hoggitworld.com/view/DCS_enum_AI)
+  -- @type AI.Task
   -- @field #AI.Task.WeaponExpend WeaponExpend
   -- @field #AI.Task.OrbitPattern OrbitPattern
   -- @field #AI.Task.Designation Designation
@@ -984,7 +1056,8 @@ do -- AI
   -- @field #AI.Task.AltitudeType AltitudeType
   -- @field #AI.Task.VehicleFormation VehicleFormation
   
-  --- @type AI.Task.WeaponExpend
+  --- [https://wiki.hoggitworld.com/view/DCS_enum_AI](https://wiki.hoggitworld.com/view/DCS_enum_AI)
+  -- @type AI.Task.WeaponExpend
   -- @field ONE
   -- @field TWO
   -- @field FOUR
@@ -992,11 +1065,13 @@ do -- AI
   -- @field HALF
   -- @field ALL
   
-  --- @type AI.Task.OrbitPattern
+  --- [https://wiki.hoggitworld.com/view/DCS_enum_AI](https://wiki.hoggitworld.com/view/DCS_enum_AI)
+  -- @type AI.Task.OrbitPattern
   -- @field CIRCLE
   -- @field RACE_TRACK
   
-  --- @type AI.Task.Designation
+  --- [https://wiki.hoggitworld.com/view/DCS_enum_AI](https://wiki.hoggitworld.com/view/DCS_enum_AI)
+  -- @type AI.Task.Designation
   -- @field NO
   -- @field AUTO
   -- @field WP

Moose Development/Moose/Functional/ATC_Ground.lua

@@ -1,10 +1,20 @@
---- **Functional** -- The ATC\_GROUND classes monitor airbase traffic and regulate speed while taxiing.
+--- **Functional** -- Monitor airbase traffic and regulate speed while taxiing.
 --
 -- ===
+--
+-- ## Features:
 -- 
--- ![Banner Image](..\Presentations\ATC_GROUND\Dia1.JPG)
+--   * Monitor speed of the airplanes of players during taxi.
+--   * Communicate ATC ground operations.
+--   * Kick speeding players during taxi.
 -- 
 -- ===
+-- 
+-- ## Missions:
+-- 
+-- [ABP - Airbase Police](https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/master/ABP%20-%20Airbase%20Police)
+--
+-- ===
 --
 -- ### Contributions: Dutch Baron - Concept & Testing
 -- ### Author: FlightControl - Framework Design &  Programming

Moose Development/Moose/Functional/Artillery.lua

@@ -1,4 +1,4 @@
---- **Functional** - (R2.4) Control artillery units.
+--- **Functional** - Control artillery units.
 -- 
 -- ===
 -- 
@@ -6,30 +6,22 @@
 -- 
 -- ## Features:
 -- 
--- * Multiple targets can be assigned. No restriction on number of targets.
--- * Targets can be given a priority. Engagement of targets is executed a according to their priority.
--- * Engagements can be scheduled, i.e. will be executed at a certain time of the day.
--- * Multiple relocations of the group can be assigned and scheduled via queueing system. 
--- * Special weapon types can be selected for each attack, e.g. cruise missiles for Naval units.
--- * Automatic rearming once the artillery is out of ammo (optional).
--- * Automatic relocation after each firing engagement to prevent counter strikes (optional).
--- * Automatic relocation movements to get the battery within firing range (optional).
--- * Simulation of tactical nuclear shells as well as illumination and smoke shells.
--- * New targets can be added during the mission, e.g. when they are detected by recon units.
--- * Targets and relocations can be assigned by placing markers on the F10 map.
--- * Finite state machine implementation. Mission designer can interact when certain events occur.
+--   * Multiple targets can be assigned. No restriction on number of targets.
+--   * Targets can be given a priority. Engagement of targets is executed a according to their priority.
+--   * Engagements can be scheduled, i.e. will be executed at a certain time of the day.
+--   * Multiple relocations of the group can be assigned and scheduled via queueing system. 
+--   * Special weapon types can be selected for each attack, e.g. cruise missiles for Naval units.
+--   * Automatic rearming once the artillery is out of ammo (optional).
+--   * Automatic relocation after each firing engagement to prevent counter strikes (optional).
+--   * Automatic relocation movements to get the battery within firing range (optional).
+--   * Simulation of tactical nuclear shells as well as illumination and smoke shells.
+--   * New targets can be added during the mission, e.g. when they are detected by recon units.
+--   * Targets and relocations can be assigned by placing markers on the F10 map.
+--   * Finite state machine implementation. Mission designer can interact when certain events occur.
 -- 
 -- ====
 -- 
--- # Demo Missions
---
--- ### [MOOSE - ALL Demo Missions](https://github.com/FlightControl-Master/MOOSE_MISSIONS)
--- 
--- ====
--- 
--- # YouTube Channel
--- 
--- ### [MOOSE YouTube Channel](https://www.youtube.com/channel/UCjrA9j5LQoWsG4SpS8i79Qg)
+-- ## [MOOSE YouTube Channel](https://www.youtube.com/channel/UCjrA9j5LQoWsG4SpS8i79Qg)
 -- 
 -- ===
 -- 
@@ -65,6 +57,8 @@
 -- @field #number IniGroupStrength Inital number of units in the ARTY group.
 -- @field #boolean IsArtillery If true, ARTY group has attribute "Artillery". This is automatically derived from the DCS descriptor table.
 -- @field #boolean ismobile If true, ARTY group can move.
+-- @field #boolean iscargo If true, ARTY group is defined as possible cargo. If it is immobile, targets out of range are not deleted from the queue.
+-- @field Cargo.CargoGroup#CARGO_GROUP cargogroup Cargo group object if ARTY group is a cargo that will be transported to another place.
 -- @field #string groupname Name of the ARTY group as defined in the mission editor.
 -- @field #string alias Name of the ARTY group.
 -- @field #table clusters Table of names of clusters the group belongs to. Can be used to address all groups within the cluster simultaniously.
@@ -417,7 +411,15 @@
 -- 
 -- Setting the rearming group is independent of the position of the mark. Just create one anywhere on the map and type
 --      arty set, battery "Mortar Bravo", rearming group "Ammo Truck M818"
--- Note that the name of the rearming group has to be given in quotation marks and spellt exactly as the group name defined in the mission editor.   
+-- Note that the name of the rearming group has to be given in quotation marks and spellt exactly as the group name defined in the mission editor.
+-- 
+-- ## Transporting
+-- 
+-- ARTY groups can be transported to another location as @{Cargo.Cargo} by means of classes such as @{AI.AI_Cargo_APC}, @{AI.AI_Cargo_Dispatcher_APC}, 
+-- @{AI.AI_Cargo_Helicopter}, @{AI.AI_Cargo_Dispatcher_Helicopter} or @{AI.AI_Cargo_Airplane}.
+-- 
+-- In order to do this, one needs to define an ARTY object via the @{#ARTY.NewFromCargoGroup}(*cargogroup*, *alias*) function.
+-- The first argument *cargogroup* has to be a @{Cargo.CargoGroup#CARGO_GROUP} object. The second argument *alias* is a string which can be freely chosen by the user.
 -- 
 -- ## Fine Tuning
 -- 
@@ -503,7 +505,25 @@
 --     -- Start ARTY process.
 --     normandy:Start()
 --
--- 
+-- ### Transportation as Cargo
+-- This example demonstates how an ARTY group can be transported to another location as cargo.
+--      -- Define a group as CARGO_GROUP
+--      CargoGroupMortars=CARGO_GROUP:New(GROUP:FindByName("Mortars"), "Mortars", "Mortar Platoon Alpha", 100 , 10)
+--      
+--      -- Define the mortar CARGO GROUP as ARTY object
+--      mortars=ARTY:NewFromCargoGroup(CargoGroupMortars, "Mortar Platoon Alpha")
+--      
+--      -- Start ARTY process
+--      mortars:Start()
+--      
+--      -- Setup AI cargo dispatcher for e.g. helos
+--      SetHeloCarriers = SET_GROUP:New():FilterPrefixes("CH-47D"):FilterStart()
+--      SetCargoMortars = SET_CARGO:New():FilterTypes("Mortars"):FilterStart()
+--      SetZoneDepoly   = SET_ZONE:New():FilterPrefixes("Deploy"):FilterStart()
+--      CargoHelo=AI_CARGO_DISPATCHER_HELICOPTER:New(SetHeloCarriers, SetCargoMortars, SetZoneDepoly)
+--      CargoHelo:Start()
+-- The ARTY group will be transported and resume its normal operation after it has been deployed. New targets can be assigned at any time also during the transportation process.
+--
 -- @field #ARTY
 ARTY={
   ClassName="ARTY",
@@ -528,6 +548,8 @@ ARTY={
   alias=nil,
   clusters={},
   ismobile=true,
+  iscargo=false,
+  cargogroup=nil,
   IniGroupStrength=0,
   IsArtillery=nil,
   RearmingDistance=100,
@@ -567,8 +589,15 @@ ARTY={
   autorelocateonroad=false,
 }
 
---- Weapong type ID. http://wiki.hoggit.us/view/DCS_enum_weapon_flag
--- @list WeaponType
+--- Weapong type ID. See [here](http://wiki.hoggit.us/view/DCS_enum_weapon_flag).
+-- @type ARTY.WeaponType
+-- @field #number Auto Automatic selection of weapon type.
+-- @field #number Cannon Cannons using conventional shells.
+-- @field #number Rockets Unguided rockets.
+-- @field #number CruiseMissile Cruise missiles.
+-- @field #number TacticalNukes Tactical nuclear shells (simulated).
+-- @field #number IlluminationShells Illumination shells (simulated).
+-- @field #number SmokeShells Smoke shells (simulated).
 ARTY.WeaponType={
   Auto=1073741822,
   Cannon=805306368,
@@ -580,7 +609,7 @@ ARTY.WeaponType={
 }
 
 --- Database of common artillery unit properties.
--- @list db
+-- @type ARTY.db
 ARTY.db={
   ["2B11 mortar"] = {  -- type "2B11 mortar"
     minrange   = 500,  -- correct?
@@ -645,7 +674,7 @@ ARTY.id="ARTY | "
 
 --- Arty script version.
 -- @field #string version
-ARTY.version="1.0.4"
+ARTY.version="1.0.6"
 
 -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 
@@ -677,13 +706,43 @@ ARTY.version="1.0.4"
 
 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 
---- Creates a new ARTY object.
+--- Creates a new ARTY object from a MOOSE CARGO_GROUP object.
+-- @param #ARTY self
+-- @param Cargo.CargoGroup#CARGO_GROUP cargogroup The CARGO GROUP object for which artillery tasks should be assigned.
+-- @param alias (Optional) Alias name the group will be calling itself when sending messages. Default is the group name.
+-- @return #ARTY ARTY object or nil if group does not exist or is not a ground or naval group.
+function ARTY:NewFromCargoGroup(cargogroup, alias)
+  BASE:F2({cargogroup=cargogroup, alias=alias})
+  
+  if cargogroup then
+    BASE:T(ARTY.id..string.format("ARTY script version %s. Added CARGO group %s.", ARTY.version, cargogroup:GetName()))
+  else
+    BASE:E(ARTY.id.."ERROR: Requested ARTY CARGO GROUP does not exist! (Has to be a MOOSE CARGO(!) group.)")
+    return nil
+  end
+
+  -- Get group belonging to the cargo group.
+  local group=cargogroup:GetObject()
+  
+  -- Create ARTY object.
+  local arty=ARTY:New(group,alias)
+  
+  -- Set iscargo flag.
+  arty.iscargo=true
+
+  -- Set cargo group object.
+  arty.cargogroup=cargogroup
+
+  return arty
+end
+
+--- Creates a new ARTY object from a MOOSE group object.
 -- @param #ARTY self
 -- @param Wrapper.Group#GROUP group The GROUP object for which artillery tasks should be assigned.
 -- @param alias (Optional) Alias name the group will be calling itself when sending messages. Default is the group name.
 -- @return #ARTY ARTY object or nil if group does not exist or is not a ground or naval group.
 function ARTY:New(group, alias)
-  BASE:F2(group)
+  BASE:F2({group=group, alias=alias})
 
   -- Inherits from FSM_CONTROLLABLE
   local self=BASE:Inherit(self, FSM_CONTROLLABLE:New()) -- #ARTY
@@ -697,7 +756,7 @@ function ARTY:New(group, alias)
   end
   
   -- Check that we actually have a GROUND group.
-  if group:IsGround()==false and group:IsShip()==false then
+  if not (group:IsGround() or group:IsShip()) then
     self:E(ARTY.id..string.format("ERROR: ARTY group %s has to be a GROUND or SHIP group!", group:GetName()))
     return nil
   end
@@ -785,6 +844,10 @@ function ARTY:New(group, alias)
   self:AddTransition("*",           "NewMove",     "*")
   self:AddTransition("*",           "Dead",        "*")
   
+  -- Transport as cargo (not in diagram).
+  self:AddTransition("*",           "Loaded",      "InTransit")
+  self:AddTransition("InTransit",   "UnLoaded",    "CombatReady")
+  
   -- Unknown transitons. To be checked if adding these causes problems.
   self:AddTransition("Rearming",    "Arrived",     "Rearming")
   self:AddTransition("Rearming",    "Move",        "Rearming")
@@ -1125,7 +1188,14 @@ function ARTY:AssignTargetCoord(coord, prio, radius, nshells, maxengage, time, w
   end
   
   -- Time in seconds.
-  local _time=self:_ClockToSeconds(time)
+  local _time
+  if type(time)=="string" then
+    _time=self:_ClockToSeconds(time)
+  elseif type(time)=="number" then
+    _time=timer.getAbsTime()+time
+  else
+    _time=timer.getAbsTime()
+  end
   
   -- Prepare target array.
   local _target={name=_name, coord=coord, radius=radius, nshells=nshells, engaged=0, underfire=false, prio=prio, maxengage=maxengage, time=_time, weapontype=weapontype}
@@ -1176,9 +1246,6 @@ function ARTY:AssignMoveCoord(coord, time, speed, onroad, cancel, name, unique)
     return nil
   end
       
-  -- Default is current time if no time was specified.
-  time=time or self:_SecondsToClock(timer.getAbsTime())
-    
   -- Set speed.
   if speed then
     -- Make sure, given speed is less than max physiaclly possible speed of group.
@@ -1200,7 +1267,14 @@ function ARTY:AssignMoveCoord(coord, time, speed, onroad, cancel, name, unique)
   end
   
   -- Time in seconds.
-  local _time=self:_ClockToSeconds(time)
+  local _time
+  if type(time)=="string" then
+    _time=self:_ClockToSeconds(time)
+  elseif type(time)=="number" then
+    _time=timer.getAbsTime()+time
+  else
+    _time=timer.getAbsTime()
+  end
   
   -- Prepare move array.
   local _move={name=_name, coord=coord, time=_time, speed=speed, onroad=onroad, cancel=cancel}
@@ -1667,6 +1741,7 @@ function ARTY:onafterStart(Controllable, From, Event, To)
   text=text..string.format("Speed max           = %d km/h\n", self.SpeedMax)
   text=text..string.format("Speed default       = %d km/h\n", self.Speed)
   text=text..string.format("Is mobile           = %s\n", tostring(self.ismobile))
+  text=text..string.format("Is cargo            = %s\n", tostring(self.iscargo))
   text=text..string.format("Min range           = %.1f km\n", self.minrange/1000)
   text=text..string.format("Max range           = %.1f km\n", self.maxrange/1000)
   text=text..string.format("Total ammo count    = %d\n", self.Nammo0)
@@ -2458,10 +2533,29 @@ end
 function ARTY:onafterStatus(Controllable, From, Event, To)
   self:_EventFromTo("onafterStatus", Event, From, To)
   
+  -- We have a cargo group ==> check if group was loaded into a carrier.
+  if self.cargogroup then
+    if self.cargogroup:IsLoaded() and not self:is("InTransit")  then
+      -- Group is now InTransit state. Current target is canceled.
+      self:T(ARTY.id..string.format("Group %s has been loaded into a carrier and is now transported.", self.alias))
+      self:Loaded()
+    elseif self.cargogroup:IsUnLoaded() then
+      -- Group has been unloaded and is combat ready again.
+      self:T(ARTY.id..string.format("Group %s has been unloaded from the carrier.", self.alias))      
+      self:UnLoaded()
+    end
+  end
+
   -- Debug current status info.
   if self.Debug then
     self:_StatusReport()
   end
+
+  -- Group is being transported as cargo ==> skip everything and check again in 5 seconds.  
+  if self:is("InTransit") then
+    self:__Status(-5)
+    return
+  end
   
   -- Group on the move.
   if self:is("Moving") then
@@ -2582,6 +2676,34 @@ end
 
 -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 
+--- Before "Loaded" event. Checks if group is currently firing and removes the target by calling CeaseFire.
+-- @param #ARTY self
+-- @param Wrapper.Controllable#CONTROLLABLE Controllable Controllable of the group.
+-- @param #string From From state.
+-- @param #string Event Event.
+-- @param #string To To state.
+-- @return #boolean If true, proceed to onafterLoaded.
+function ARTY:onbeforeLoaded(Controllable, From, Event, To)
+  if self.currentTarget then
+    self:CeaseFire(self.currentTarget)
+  end
+  
+  return true
+end
+
+--- After "UnLoaded" event. Group is combat ready again.
+-- @param #ARTY self
+-- @param Wrapper.Controllable#CONTROLLABLE Controllable Controllable of the group.
+-- @param #string From From state.
+-- @param #string Event Event.
+-- @param #string To To state.
+-- @return #boolean If true, proceed to onafterLoaded.
+function ARTY:onafterUnLoaded(Controllable, From, Event, To)
+  self:CombatReady()
+end
+
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
 --- Enter "CombatReady" state. Route the group back if necessary.
 -- @param #ARTY self
 -- @param Wrapper.Controllable#CONTROLLABLE Controllable Controllable of the group.
@@ -2840,7 +2962,7 @@ function ARTY:onafterRearm(Controllable, From, Event, To)
       self.RearmingGroupCoord=coordRARM
     end
     
-    if self.RearmingGroup and self.RearmingPlaceCoord and self.SpeedMax>0 then
+    if self.RearmingGroup and self.RearmingPlaceCoord and self.ismobile then
     
       -- CASE 1: Rearming unit and ARTY group meet at rearming place.
       
@@ -4615,6 +4737,7 @@ function ARTY:_TargetInRange(target, message)
   end
 
   -- Distance between ARTY group and target.
+  self:E({controllable=self.Controllable, targetcoord=target.coord})
   local _dist=self.Controllable:GetCoordinate():Get2DDistance(target.coord)
   
   -- Assume we are in range.
@@ -4639,8 +4762,8 @@ function ARTY:_TargetInRange(target, message)
     MESSAGE:New(text, 5):ToCoalitionIf(self.Controllable:GetCoalition(), (self.report and message) or (self.Debug and message))
   end
     
-  -- Remove target if ARTY group cannot move, e.g. Mortas. No chance to be ever in range.
-  if not self.ismobile and _inrange==false then
+  -- Remove target if ARTY group cannot move, e.g. Mortas. No chance to be ever in range - unless they are cargo.
+  if not (self.ismobile or self.iscargo) and _inrange==false then
     self:RemoveTarget(target.name)
   end
 

Moose Development/Moose/Functional/CleanUp.lua

@@ -1,23 +1,22 @@
---- **Functional** -- The CLEANUP_AIRBASE class keeps an area clean of crashing or colliding airplanes. It also prevents airplanes from firing within this area.
+--- **Functional** -- Keep airbases clean of crashing or colliding airplanes, and kill missiles when being fired at airbases.
 -- 
 -- ===
 -- 
--- ### Author: **FlightControl**
--- ### Contributions: 
+-- ## Features:
+-- 
+-- 
+--  * Try to keep the airbase clean and operational.
+--  * Prevent airplanes from crashing.
+--  * Clean up obstructing airplanes from the runway that are standing still for a period of time.
+--  * Prevent airplanes firing missiles within the airbase zone.
 -- 
 -- ===
 -- 
--- @module Functional.CleanUp
--- @image CleanUp_Airbases.JPG
-
---- @type CLEANUP_AIRBASE.__ Methods which are not intended for mission designers, but which are used interally by the moose designer :-)
--- @field #map<#string,Wrapper.Airbase#AIRBASE> Airbases Map of Airbases.
--- @extends Core.Base#BASE
-
---- @type CLEANUP_AIRBASE
--- @extends #CLEANUP_AIRBASE.__
-
---- Keeps airbases clean, and tries to guarantee continuous airbase operations, even under combat.
+-- ## Missions:
+-- 
+-- [CLA - CleanUp Airbase](https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/master/CLA%20-%20CleanUp%20Airbase)
+-- 
+-- ===
 -- 
 -- Specific airbases need to be provided that need to be guarded. Each airbase registered, will be guarded within a zone of 8 km around the airbase.
 -- Any unit that fires a missile, or shoots within the zone of an airbase, will be monitored by CLEANUP_AIRBASE.
@@ -43,7 +42,26 @@
 --     
 -- By following the above guidelines, you can add airbase cleanup with acceptable CPU overhead.
 -- 
--- ## 1. CLEANUP_AIRBASE Constructor
+-- ===
+-- 
+-- ### Author: **FlightControl**
+-- ### Contributions: 
+-- 
+-- ===
+-- 
+-- @module Functional.CleanUp
+-- @image CleanUp_Airbases.JPG
+
+--- @type CLEANUP_AIRBASE.__ Methods which are not intended for mission designers, but which are used interally by the moose designer :-)
+-- @field #map<#string,Wrapper.Airbase#AIRBASE> Airbases Map of Airbases.
+-- @extends Core.Base#BASE
+
+--- @type CLEANUP_AIRBASE
+-- @extends #CLEANUP_AIRBASE.__
+
+--- Keeps airbases clean, and tries to guarantee continuous airbase operations, even under combat.
+-- 
+-- # 1. CLEANUP_AIRBASE Constructor
 -- 
 -- Creates the main object which is preventing the airbase to get polluted with debris on the runway, which halts the airbase.
 -- 
@@ -54,12 +72,12 @@
 --      CleanUpTbilisi = CLEANUP_AIRBASE:New( AIRBASE.Caucasus.Tbilisi )
 --      CleanUpKutaisi = CLEANUP_AIRBASE:New( AIRBASE.Caucasus.Kutaisi )
 -- 
--- ## 2. Add or Remove airbases
+-- # 2. Add or Remove airbases
 -- 
 -- The method @{#CLEANUP_AIRBASE.AddAirbase}() to add an airbase to the cleanup validation process.
 -- The method @{#CLEANUP_AIRBASE.RemoveAirbase}() removes an airbase from the cleanup validation process.
 -- 
--- ## 3. Clean missiles and bombs within the airbase zone.
+-- # 3. Clean missiles and bombs within the airbase zone.
 -- 
 -- When missiles or bombs hit the runway, the airbase operations stop.
 -- Use the method @{#CLEANUP_AIRBASE.SetCleanMissiles}() to control the cleaning of missiles, which will prevent airbases to stop.
@@ -112,6 +130,20 @@ function CLEANUP_AIRBASE:New( AirbaseNames )
   self:HandleEvent( EVENTS.PilotDead, self.__.OnEventCrash )
   self:HandleEvent( EVENTS.Dead, self.__.OnEventCrash )
   self:HandleEvent( EVENTS.Crash, self.__.OnEventCrash )
+  
+  for UnitName, Unit in pairs( _DATABASE.UNITS ) do
+    local Unit = Unit -- Wrapper.Unit#UNIT
+    if Unit:IsAlive() ~= nil then
+      if self:IsInAirbase( Unit:GetVec2() ) then
+        self:F( { UnitName = UnitName } )
+        self.CleanUpList[UnitName] = {}
+        self.CleanUpList[UnitName].CleanUpUnit = Unit
+        self.CleanUpList[UnitName].CleanUpGroup = Unit:GetGroup()
+        self.CleanUpList[UnitName].CleanUpGroupName = Unit:GetGroup():GetName()
+        self.CleanUpList[UnitName].CleanUpUnitName = Unit:GetName()
+      end
+    end
+  end
 	
 	return self
 end
@@ -180,7 +212,7 @@ function CLEANUP_AIRBASE.__:DestroyUnit( CleanUpUnit )
 	if CleanUpUnit then
 	  local CleanUpUnitName = CleanUpUnit:GetName()
 		local CleanUpGroup = CleanUpUnit:GetGroup()
-    -- TODO Client bug in 1.5.3
+    -- TODO DCS BUG - Client bug in 1.5.3
 		if CleanUpGroup:IsAlive() then
 			local CleanUpGroupUnits = CleanUpGroup:GetUnits()
 			if #CleanUpGroupUnits == 1 then
@@ -213,11 +245,15 @@ end
 function CLEANUP_AIRBASE.__:OnEventBirth( EventData )
   self:F( { EventData } )
   
-  self.CleanUpList[EventData.IniDCSUnitName] = {}
-  self.CleanUpList[EventData.IniDCSUnitName].CleanUpUnit = EventData.IniUnit
-  self.CleanUpList[EventData.IniDCSUnitName].CleanUpGroup = EventData.IniGroup
-  self.CleanUpList[EventData.IniDCSUnitName].CleanUpGroupName = EventData.IniDCSGroupName
-  self.CleanUpList[EventData.IniDCSUnitName].CleanUpUnitName = EventData.IniDCSUnitName
+  if EventData.IniUnit:IsAlive() ~= nil then
+    if self:IsInAirbase( EventData.IniUnit:GetVec2() ) then
+      self.CleanUpList[EventData.IniDCSUnitName] = {}
+      self.CleanUpList[EventData.IniDCSUnitName].CleanUpUnit = EventData.IniUnit
+      self.CleanUpList[EventData.IniDCSUnitName].CleanUpGroup = EventData.IniGroup
+      self.CleanUpList[EventData.IniDCSUnitName].CleanUpGroupName = EventData.IniDCSGroupName
+      self.CleanUpList[EventData.IniDCSUnitName].CleanUpUnitName = EventData.IniDCSUnitName
+    end
+  end
 
 end
 
@@ -229,7 +265,7 @@ end
 function CLEANUP_AIRBASE.__:OnEventCrash( Event )
 	self:F( { Event } )
 
-  --TODO: This stuff is not working due to a DCS bug. Burning units cannot be destroyed.
+  --TODO: DCS BUG - This stuff is not working due to a DCS bug. Burning units cannot be destroyed.
 	-- self:T("before getGroup")
 	-- local _grp = Unit.getGroup(event.initiator)-- Identify the group that fired 
 	-- self:T("after getGroup")
@@ -349,45 +385,50 @@ function CLEANUP_AIRBASE.__:CleanUpSchedule()
 		local CleanUpGroupName = CleanUpListData.CleanUpGroupName
 
 		if CleanUpUnit:IsAlive() ~= nil then
+		
+		  if self:IsInAirbase( CleanUpUnit:GetVec2() ) then
 
-			if _DATABASE:GetStatusGroup( CleanUpGroupName ) ~= "ReSpawn" then
-
-				local CleanUpCoordinate = CleanUpUnit:GetCoordinate()
-
-        self:T( { "CleanUp Scheduler", CleanUpUnitName } )
-        if CleanUpUnit:GetLife() <= CleanUpUnit:GetLife0() * 0.95 then
-					if CleanUpUnit:IsAboveRunway() then
-						if CleanUpUnit:InAir() then
-
-							local CleanUpLandHeight = CleanUpCoordinate:GetLandHeight()
-							local CleanUpUnitHeight = CleanUpCoordinate.y - CleanUpLandHeight
-							
-							if CleanUpUnitHeight < 100 then
-								self:T( { "CleanUp Scheduler", "Destroy " .. CleanUpUnitName .. " because below safe height and damaged." } )
-								self:DestroyUnit( CleanUpUnit )
-							end
-						else
-							self:T( { "CleanUp Scheduler", "Destroy " .. CleanUpUnitName .. " because on runway and damaged." } )
-							self:DestroyUnit( CleanUpUnit )
-						end
-					end
-				end
-				-- Clean Units which are waiting for a very long time in the CleanUpZone.
-				if CleanUpUnit then
-					local CleanUpUnitVelocity = CleanUpUnit:GetVelocityKMH()
-					if CleanUpUnitVelocity < 1 then
-						if CleanUpListData.CleanUpMoved then
-							if CleanUpListData.CleanUpTime + 180 <= timer.getTime() then
-								self:T( { "CleanUp Scheduler", "Destroy due to not moving anymore " .. CleanUpUnitName } )
-								self:DestroyUnit( CleanUpUnit )
-							end
-						end
-					else
-						CleanUpListData.CleanUpTime = timer.getTime()
-						CleanUpListData.CleanUpMoved = true
-					end
-				end
-				
+  			if _DATABASE:GetStatusGroup( CleanUpGroupName ) ~= "ReSpawn" then
+  
+  				local CleanUpCoordinate = CleanUpUnit:GetCoordinate()
+  
+          self:T( { "CleanUp Scheduler", CleanUpUnitName } )
+          if CleanUpUnit:GetLife() <= CleanUpUnit:GetLife0() * 0.95 then
+  					if CleanUpUnit:IsAboveRunway() then
+  						if CleanUpUnit:InAir() then
+  
+  							local CleanUpLandHeight = CleanUpCoordinate:GetLandHeight()
+  							local CleanUpUnitHeight = CleanUpCoordinate.y - CleanUpLandHeight
+  							
+  							if CleanUpUnitHeight < 100 then
+  								self:T( { "CleanUp Scheduler", "Destroy " .. CleanUpUnitName .. " because below safe height and damaged." } )
+  								self:DestroyUnit( CleanUpUnit )
+  							end
+  						else
+  							self:T( { "CleanUp Scheduler", "Destroy " .. CleanUpUnitName .. " because on runway and damaged." } )
+  							self:DestroyUnit( CleanUpUnit )
+  						end
+  					end
+  				end
+  				-- Clean Units which are waiting for a very long time in the CleanUpZone.
+  				if CleanUpUnit and not CleanUpUnit:GetPlayerName() then
+  					local CleanUpUnitVelocity = CleanUpUnit:GetVelocityKMH()
+  					if CleanUpUnitVelocity < 1 then
+  						if CleanUpListData.CleanUpMoved then
+  							if CleanUpListData.CleanUpTime + 180 <= timer.getTime() then
+  								self:T( { "CleanUp Scheduler", "Destroy due to not moving anymore " .. CleanUpUnitName } )
+  								self:DestroyUnit( CleanUpUnit )
+  							end
+  						end
+  					else
+  						CleanUpListData.CleanUpTime = timer.getTime()
+  						CleanUpListData.CleanUpMoved = true
+  					end
+  				end
+        else
+          -- not anymore in an airbase zone, remove from cleanup list.
+          self.CleanUpList[CleanUpUnitName] = nil
+        end
 			else
 				-- Do nothing ...
 				self.CleanUpList[CleanUpUnitName] = nil

Moose Development/Moose/Functional/Designate.lua

@@ -2,32 +2,181 @@
 --
 -- ===
 --
--- Orchestrate the designation of potential targets executed by a Recce group, 
--- and communicates these to a dedicated attacking group of players, 
--- so that following a dynamically generated menu system, 
--- each detected set of potential targets can be lased or smoked...
+-- ## Features:
 -- 
--- Targets can be:
+--   * Faciliate the communication of detected targets to players.
+--   * Designate targets using lasers, through a menu system.
+--   * Designate targets using smoking, through a menu system.
+--   * Designate targets using illumination, through a menu system.
+--   * Auto lase targets.
+--   * Refresh detection upon specified time intervals.
+--   * Prioritization on threat levels.
+--   * Reporting system of threats.
+--  
+-- ===
+-- 
+-- ## Missions:
+-- 
+-- [DES - Designation](https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/master/DES%20-%20Designation)
+-- 
+-- ===
+--
+-- Targets detected by recce will be communicated to a group of attacking players.  
+-- A menu system is made available that allows to: 
 -- 
 --   * **Lased** for a period of time.
 --   * **Smoked**. Artillery or airplanes with Illuminatino ordonance need to be present. (WIP, but early demo ready.)
 --   * **Illuminated** through an illumination bomb. Artillery or airplanes with Illuminatino ordonance need to be present. (WIP, but early demo ready.
 -- 
--- ===
+-- The following terminology is being used throughout this document:
 -- 
--- # **AUTHORS and CONTRIBUTIONS**
+--   * The **DesignateObject** is the object of the DESIGNATE class, which is this class explained in the document.
+--   * The **DetectionObject** is the object of a DETECTION_ class (DETECTION_TYPES, DETECTION_AREAS, DETECTION_UNITS), which is executing the detection and grouping of Targets into _DetectionItems_.
+--   * **TargetGroups** is the list of detected target groupings by the _DetectionObject_. Each _TargetGroup_ contains a _TargetSet_.
+--   * **TargetGroup** is one element of the __TargetGroups__ list, and contains a _TargetSet_.
+--   * The **TargetSet** is a SET_UNITS collection of _Targets_, that have been detected by the _DetectionObject_.
+--   * A **Target** is a detected UNIT object by the _DetectionObject_.
+--   * A **Threat Level** is a number from 0 to 10 that is calculated based on the threat of the Target in an Air to Ground battle scenario.
+--   * The **RecceSet** is a SET_GROUP collection that contains the **RecceGroups**.
+--   * A **RecceGroup** is a GROUP object containing the **Recces**.
+--   * A **Recce** is a UNIT object executing the reconnaissance as part the _DetectionObject_. A Recce can be of any UNIT type.
+--   * An **AttackGroup** is a GROUP object that contain _Players_.
+--   * A **Player** is an active CLIENT object containing a human player.
+--   * A **Designate Menu** is the menu that is dynamically created during the designation process for each _AttackGroup_.
+-- 
+-- # Player Manual
+-- 
+-- ![Banner Image](..\Presentations\DESIGNATE\Dia3.JPG)
+-- 
+-- A typical mission setup would require Recce (a @{Set} of Recce) to be detecting potential targets.
+-- The DetectionObject will group the detected targets based on the detection method being used.
+-- Possible detection methods could be by Area, by Type or by Unit.
+-- Each grouping will result in a **TargetGroup**, for terminology and clarity we will use this term throughout the document.
+-- 
+-- **Recce** require to have Line of Sight (LOS) towards the targets.
+-- The **Recce** will report any detected targets to the Players (on the picture Observers).
+-- When targets are detected, a menu will be made available that allows those **TargetGroups** to be designated.
+-- Designation can be done by Lasing, Smoking and Illumination.
+-- Smoking is useful during the day, while illumination is recommended to be used during the night.
+-- Smoking can designate specific targets, but not very precise, while lasing is very accurate and allows to
+-- players to attack the targets using laser guided bombs or rockets.
+-- Illumination will lighten up the Target Area.
+-- 
+-- **Recce** can be ground based or airborne. Airborne **Recce** (AFAC) can be really useful to designate a large amount of targets
+-- in a wide open area, as airborne **Recce** has a large LOS.
+-- However, ground based **Recce** are very useful to smoke or illuminate targets, as they can be much closer
+-- to the Target Area.
+-- 
+-- It is recommended to make the **Recce** invisible and immortal using the Mission Editor in DCS World.
+-- This will ensure that the detection process won't be interrupted and that targets can be designated.
+-- However, you don't have to, so to simulate a more real-word situation or simulation, **Recce can also be destroyed**!
+--  
+-- ## 1. Player View (Observer)
+-- 
+-- ![Banner Image](..\Presentations\DESIGNATE\Dia4.JPG)
+-- 
+-- The RecceSet is continuously detecting for potential Targets, 
+-- executing its task as part of the DetectionObject.
+-- Once Targets have been detected, the DesignateObject will trigger the **Detect Event**.
+-- 
+-- In order to prevent an overflow in the DesignateObject of detected targets, 
+-- there is a maximum amount of TargetGroups 
+-- that can be put in **scope** of the DesignateObject.
+-- We call this the **MaximumDesignations** term.
+-- 
+-- ## 2. Designate Menu
+-- 
+-- ![Banner Image](..\Presentations\DESIGNATE\Dia5.JPG)
+-- 
+-- For each detected TargetGroup, there is:
+-- 
+--   * A **Designate Menu** are created and continuously refreshed, containing the **DesignationID** and the **Designation Status**.
+--   * The RecceGroups are reporting to each AttackGroup, sending **Messages** containing the Threat Level and the TargetSet composition.
+-- 
+-- A Player can then select an action from the **Designate Menu**. 
+-- The Designation Status is shown between the (   ).
+-- 
+-- It indicates for each TargetGroup the current active designation action applied:
+-- 
+--   * An "I" for Illumnation designation.
+--   * An "S" for Smoking designation.
+--   * An "L" for Lasing designation.
+--
+-- Note that multiple designation methods can be active at the same time!
+-- Note the **Auto Lase** option. When switched on, the available **Recce** will lase 
+-- Targets when detected.
+-- 
+-- Targets are designated per **Threat Level**. 
+-- The most threatening targets from an Air to Ground perspective, are designated first!
+-- This is for all designation methods.
+-- 
+-- ![Banner Image](..\Presentations\DESIGNATE\Dia6.JPG)
+-- 
+-- Each Designate Menu has a sub menu structure, which allows specific actions to be triggered:
+-- 
+--   * Lase Targets using a specific laser code.
+--   * Smoke Targets using a specific smoke color.
+--   * Illuminate areas.
+-- 
+-- ## 3. Lasing Targets
+-- 
+-- ![Banner Image](..\Presentations\DESIGNATE\Dia7.JPG)
+-- 
+-- Lasing targets is done as expected. Each available Recce can lase only ONE target through!
+-- 
+-- ![Banner Image](..\Presentations\DESIGNATE\Dia8.JPG)
+-- 
+-- Lasing can be done for specific laser codes. The Su-25T requires laser code 1113, while the A-10A requires laser code 1680.
+-- For those, specific menu options can be made available for players to lase with these codes.
+-- Auto Lase (as explained above), will ensure continuous lasing of available targets.
+-- The status report shows which targets are being designated.
+-- 
+-- The following logic is executed when a TargetGroup is selected to be *lased* from the Designation Menu:
+-- 
+--   * The RecceSet is searched for any Recce that is within *designation distance* from a Target in the TargetGroup that is currently not being designated.
+--   * If there is a Recce found that is currently no designating a target, and is within designation distance from the Target, then that Target will be designated.
+--   * During designation, any Recce that does not have Line of Sight (LOS) and is not within disignation distance from the Target, will stop designating the Target, and a report is given.
+--   * When a Recce is designating a Target, and that Target is destroyed, then the Recce will stop designating the Target, and will report the event.
+--   * When a Recce is designating a Target, and that Recce is destroyed, then the Recce will be removed from the RecceSet and designation will stop without reporting.
+--   * When all RecceGroups are destroyed from the RecceSet, then the DesignationObject will stop functioning, and nothing will be reported.
+--   
+-- In this way, DESIGNATE assists players to designate ground targets for a coordinated attack!
+-- 
+-- ## 4. Illuminating Targets
+-- 
+-- ![Banner Image](..\Presentations\DESIGNATE\Dia9.JPG)
+-- 
+-- Illumination bombs are fired between 500 and 700 meters altitude and will burn about 2 minutes, while slowly decending.
+-- Each available recce within range will fire an illumination bomb.
+-- Illumination bombs can be fired in while lasing targets.
+-- When illumination bombs are fired, it will take about 2 minutes until a sequent bomb run can be requested using the menus.
+-- 
+-- ## 5. Smoking Targets
+-- 
+-- ![Banner Image](..\Presentations\DESIGNATE\Dia10.JPG)
+-- 
+-- Smoke will fire for 5 minutes.
+-- Each available recce within range will smoke a target.
+-- Smoking can be requested while lasing targets.
+-- Smoke will appear "around" the targets, because of accuracy limitations.
+-- 
+-- 
+-- Have FUN!
+-- 
+-- ===
 -- 
 -- ### Contributions: 
 -- 
 --   * [**Ciribob**](https://forums.eagle.ru/member.php?u=112175): Showing the way how to lase targets + how laser codes work!!! Explained the autolase script.
 --   * [**EasyEB**](https://forums.eagle.ru/member.php?u=112055): Ideas and Beta Testing
 --   * [**Wingthor**](https://forums.eagle.ru/member.php?u=123698): Beta Testing
---   
 -- 
 -- ### Authors: 
 -- 
 --   * **FlightControl**: Design & Programming
 -- 
+-- ===
+-- 
 -- @module Functional.Designate
 -- @image Designation.JPG
 
@@ -38,161 +187,20 @@ do -- DESIGNATE
 
   --- Manage the designation of detected targets.
   -- 
-  -- Targets detected by recce will be communicated to a group of attacking players.  
-  -- A menu system is made available that allows to: 
   -- 
-  --   * **Lased** for a period of time.
-  --   * **Smoked**. Artillery or airplanes with Illuminatino ordonance need to be present. (WIP, but early demo ready.)
-  --   * **Illuminated** through an illumination bomb. Artillery or airplanes with Illuminatino ordonance need to be present. (WIP, but early demo ready.
-  -- 
-  -- The following terminology is being used throughout this document:
-  -- 
-  --   * The **DesignateObject** is the object of the DESIGNATE class, which is this class explained in the document.
-  --   * The **DetectionObject** is the object of a DETECTION_ class (DETECTION_TYPES, DETECTION_AREAS, DETECTION_UNITS), which is executing the detection and grouping of Targets into _DetectionItems_.
-  --   * **TargetGroups** is the list of detected target groupings by the _DetectionObject_. Each _TargetGroup_ contains a _TargetSet_.
-  --   * **TargetGroup** is one element of the __TargetGroups__ list, and contains a _TargetSet_.
-  --   * The **TargetSet** is a SET_UNITS collection of _Targets_, that have been detected by the _DetectionObject_.
-  --   * A **Target** is a detected UNIT object by the _DetectionObject_.
-  --   * A **Threat Level** is a number from 0 to 10 that is calculated based on the threat of the Target in an Air to Ground battle scenario.
-  --   * The **RecceSet** is a SET_GROUP collection that contains the **RecceGroups**.
-  --   * A **RecceGroup** is a GROUP object containing the **Recces**.
-  --   * A **Recce** is a UNIT object executing the reconnaissance as part the _DetectionObject_. A Recce can be of any UNIT type.
-  --   * An **AttackGroup** is a GROUP object that contain _Players_.
-  --   * A **Player** is an active CLIENT object containing a human player.
-  --   * A **Designate Menu** is the menu that is dynamically created during the designation process for each _AttackGroup_.
-  -- 
-  -- ## 0. Player Manual
-  -- 
-  -- ![Banner Image](..\Presentations\DESIGNATE\Dia3.JPG)
-  -- 
-  -- A typical mission setup would require Recce (a @{Set} of Recce) to be detecting potential targets.
-  -- The DetectionObject will group the detected targets based on the detection method being used.
-  -- Possible detection methods could be by Area, by Type or by Unit.
-  -- Each grouping will result in a **TargetGroup**, for terminology and clarity we will use this term throughout the document.
-  -- 
-  -- **Recce** require to have Line of Sight (LOS) towards the targets.
-  -- The **Recce** will report any detected targets to the Players (on the picture Observers).
-  -- When targets are detected, a menu will be made available that allows those **TargetGroups** to be designated.
-  -- Designation can be done by Lasing, Smoking and Illumination.
-  -- Smoking is useful during the day, while illumination is recommended to be used during the night.
-  -- Smoking can designate specific targets, but not very precise, while lasing is very accurate and allows to
-  -- players to attack the targets using laser guided bombs or rockets.
-  -- Illumination will lighten up the Target Area.
-  -- 
-  -- **Recce** can be ground based or airborne. Airborne **Recce** (AFAC) can be really useful to designate a large amount of targets
-  -- in a wide open area, as airborne **Recce** has a large LOS.
-  -- However, ground based **Recce** are very useful to smoke or illuminate targets, as they can be much closer
-  -- to the Target Area.
-  -- 
-  -- It is recommended to make the **Recce** invisible and immortal using the Mission Editor in DCS World.
-  -- This will ensure that the detection process won't be interrupted and that targets can be designated.
-  -- However, you don't have to, so to simulate a more real-word situation or simulation, **Recce can also be destroyed**!
-  --  
-  -- ### 0.1. Player View (Observer)
-  -- 
-  -- ![Banner Image](..\Presentations\DESIGNATE\Dia4.JPG)
-  -- 
-  -- The RecceSet is continuously detecting for potential Targets, 
-  -- executing its task as part of the DetectionObject.
-  -- Once Targets have been detected, the DesignateObject will trigger the **Detect Event**.
-  -- 
-  -- In order to prevent an overflow in the DesignateObject of detected targets, 
-  -- there is a maximum amount of TargetGroups 
-  -- that can be put in **scope** of the DesignateObject.
-  -- We call this the **MaximumDesignations** term.
-  -- 
-  -- ### 0.2. Designate Menu
-  -- 
-  -- ![Banner Image](..\Presentations\DESIGNATE\Dia5.JPG)
-  -- 
-  -- For each detected TargetGroup, there is:
-  -- 
-  --   * A **Designate Menu** are created and continuously refreshed, containing the **DesignationID** and the **Designation Status**.
-  --   * The RecceGroups are reporting to each AttackGroup, sending **Messages** containing the Threat Level and the TargetSet composition.
-  -- 
-  -- A Player can then select an action from the **Designate Menu**. 
-  -- The Designation Status is shown between the (   ).
-  -- 
-  -- It indicates for each TargetGroup the current active designation action applied:
-  -- 
-  --   * An "I" for Illumnation designation.
-  --   * An "S" for Smoking designation.
-  --   * An "L" for Lasing designation.
-  --
-  -- Note that multiple designation methods can be active at the same time!
-  -- Note the **Auto Lase** option. When switched on, the available **Recce** will lase 
-  -- Targets when detected.
-  -- 
-  -- Targets are designated per **Threat Level**. 
-  -- The most threatening targets from an Air to Ground perspective, are designated first!
-  -- This is for all designation methods.
-  -- 
-  -- ![Banner Image](..\Presentations\DESIGNATE\Dia6.JPG)
-  -- 
-  -- Each Designate Menu has a sub menu structure, which allows specific actions to be triggered:
-  -- 
-  --   * Lase Targets using a specific laser code.
-  --   * Smoke Targets using a specific smoke color.
-  --   * Illuminate areas.
-  -- 
-  -- ### 0.3. Lasing Targets
-  -- 
-  -- ![Banner Image](..\Presentations\DESIGNATE\Dia7.JPG)
-  -- 
-  -- Lasing targets is done as expected. Each available Recce can lase only ONE target through!
-  -- 
-  -- ![Banner Image](..\Presentations\DESIGNATE\Dia8.JPG)
-  -- 
-  -- Lasing can be done for specific laser codes. The Su-25T requires laser code 1113, while the A-10A requires laser code 1680.
-  -- For those, specific menu options can be made available for players to lase with these codes.
-  -- Auto Lase (as explained above), will ensure continuous lasing of available targets.
-  -- The status report shows which targets are being designated.
-  -- 
-  -- The following logic is executed when a TargetGroup is selected to be *lased* from the Designation Menu:
-  -- 
-  --   * The RecceSet is searched for any Recce that is within *designation distance* from a Target in the TargetGroup that is currently not being designated.
-  --   * If there is a Recce found that is currently no designating a target, and is within designation distance from the Target, then that Target will be designated.
-  --   * During designation, any Recce that does not have Line of Sight (LOS) and is not within disignation distance from the Target, will stop designating the Target, and a report is given.
-  --   * When a Recce is designating a Target, and that Target is destroyed, then the Recce will stop designating the Target, and will report the event.
-  --   * When a Recce is designating a Target, and that Recce is destroyed, then the Recce will be removed from the RecceSet and designation will stop without reporting.
-  --   * When all RecceGroups are destroyed from the RecceSet, then the DesignationObject will stop functioning, and nothing will be reported.
-  --   
-  -- In this way, DESIGNATE assists players to designate ground targets for a coordinated attack!
-  -- 
-  -- ### 0.4. Illuminating Targets
-  -- 
-  -- ![Banner Image](..\Presentations\DESIGNATE\Dia9.JPG)
-  -- 
-  -- Illumination bombs are fired between 500 and 700 meters altitude and will burn about 2 minutes, while slowly decending.
-  -- Each available recce within range will fire an illumination bomb.
-  -- Illumination bombs can be fired in while lasing targets.
-  -- When illumination bombs are fired, it will take about 2 minutes until a sequent bomb run can be requested using the menus.
-  -- 
-  -- ### 0.5. Smoking Targets
-  -- 
-  -- ![Banner Image](..\Presentations\DESIGNATE\Dia10.JPG)
-  -- 
-  -- Smoke will fire for 5 minutes.
-  -- Each available recce within range will smoke a target.
-  -- Smoking can be requested while lasing targets.
-  -- Smoke will appear “around” the targets, because of accuracy limitations.
-  -- 
-  -- 
-  -- Have FUN!
-  -- 
-  -- ## 1. DESIGNATE constructor
+  -- # 1. DESIGNATE constructor
   --   
   --   * @{#DESIGNATE.New}(): Creates a new DESIGNATE object.
   -- 
-  -- ## 2. DESIGNATE is a FSM
+  -- # 2. DESIGNATE is a FSM
   -- 
   -- Designate is a finite state machine, which allows for controlled transitions of states.
   -- 
-  -- ### 2.1 DESIGNATE States
+  -- ## 2.1 DESIGNATE States
   -- 
   --   * **Designating** ( Group ): The designation process.
   -- 
-  -- ### 2.2 DESIGNATE Events
+  -- ## 2.2 DESIGNATE Events
   -- 
   --   * **@{#DESIGNATE.Detect}**: Detect targets.
   --   * **@{#DESIGNATE.LaseOn}**: Lase the targets with the specified Index.
@@ -200,7 +208,7 @@ do -- DESIGNATE
   --   * **@{#DESIGNATE.Smoke}**: Smoke the targets with the specified Index.
   --   * **@{#DESIGNATE.Status}**: Report designation status.
   -- 
-  -- ## 3. Maximum Designations
+  -- # 3. Maximum Designations
   -- 
   -- In order to prevent an overflow of designations due to many Detected Targets, there is a 
   -- Maximum Designations scope that is set in the DesignationObject.
@@ -208,9 +216,9 @@ do -- DESIGNATE
   -- The method @{#DESIGNATE.SetMaximumDesignations}() will put a limit on the amount of designations put in scope of the DesignationObject.
   -- Using the menu system, the player can "forget" a designation, so that gradually a new designation can be put in scope when detected.
   -- 
-  -- ## 4. Laser codes
+  -- # 4. Laser codes
   -- 
-  -- ### 4.1. Set possible laser codes
+  -- ## 4.1. Set possible laser codes
   -- 
   -- An array of laser codes can be provided, that will be used by the DESIGNATE when lasing.
   -- The laser code is communicated by the Recce when it is lasing a larget.
@@ -228,11 +236,11 @@ do -- DESIGNATE
   --     
   -- The above sets a collection of possible laser codes that can be assigned. **Note the { } notation!**
   -- 
-  -- ### 4.2. Auto generate laser codes
+  -- ## 4.2. Auto generate laser codes
   -- 
   -- Use the method @{#DESIGNATE.GenerateLaserCodes}() to generate all possible laser codes. Logic implemented and advised by Ciribob!
   -- 
-  -- ### 4.3. Add specific lase codes to the lase menu
+  -- ## 4.3. Add specific lase codes to the lase menu
   -- 
   -- Certain plane types can only drop laser guided ordonnance when targets are lased with specific laser codes.
   -- The SU-25T needs targets to be lased using laser code 1113.
@@ -241,7 +249,7 @@ do -- DESIGNATE
   -- The method @{#DESIGNATE.AddMenuLaserCode}() to allow a player to lase a target using a specific laser code.
   -- Remove such a lase menu option using @{#DESIGNATE.RemoveMenuLaserCode}().
   -- 
-  -- ## 5. Autolase to automatically lase detected targets.
+  -- # 5. Autolase to automatically lase detected targets.
   -- 
   -- DetectionItems can be auto lased once detected by Recces. As such, there is almost no action required from the Players using the Designate Menu.
   -- The **auto lase** function can be activated through the Designation Menu.
@@ -252,7 +260,7 @@ do -- DESIGNATE
   -- 
   -- Activate the auto lasing.
   -- 
-  -- ## 6. Target prioritization on threat level
+  -- # 6. Target prioritization on threat level
   -- 
   -- Targets can be detected of different types in one DetectionItem. Depending on the type of the Target, a different threat level applies in an Air to Ground combat context.
   -- SAMs are of a higher threat than normal tanks. So, if the Target type was recognized, the Recces will select those targets that form the biggest threat first,
@@ -265,12 +273,12 @@ do -- DESIGNATE
   --     
   -- The example will activate the threat level prioritization for this the Designate object. Threats will be marked based on the threat level of the Target.
   -- 
-  -- ## 6. Designate Menu Location for a Mission
+  -- # 7. Designate Menu Location for a Mission
   -- 
   -- You can make DESIGNATE work for a @{Tasking.Mission#MISSION} object. In this way, the designate menu will not appear in the root of the radio menu, but in the menu of the Mission.
   -- Use the method @{#DESIGNATE.SetMission}() to set the @{Mission} object for the designate function.
   -- 
-  -- ## 7. Status Report
+  -- # 8. Status Report
   -- 
   -- A status report is available that displays the current Targets detected, grouped per DetectionItem, and a list of which Targets are currently being marked.
   -- 
@@ -936,89 +944,112 @@ do -- DESIGNATE
     return self
   end
 
-  --- Sets the Designate Menu.
+
+  --- Sets the Designate Menu for one attack groups.
+  -- @param #DESIGNATE self
+  -- @return #DESIGNATE
+  function DESIGNATE:SetMenu( AttackGroup )
+
+    self.MenuDesignate = self.MenuDesignate or {}
+    
+    local MissionMenu = nil
+    
+    if self.Mission then
+      --MissionMenu = self.Mission:GetRootMenu( AttackGroup )
+      MissionMenu = self.Mission:GetMenu( AttackGroup )
+    end
+    
+    local MenuTime = timer.getTime()
+    
+    self.MenuDesignate[AttackGroup] = MENU_GROUP_DELAYED:New( AttackGroup, self.DesignateName, MissionMenu ):SetTime( MenuTime ):SetTag( self.DesignateName ) 
+    local MenuDesignate = self.MenuDesignate[AttackGroup] -- Core.Menu#MENU_GROUP_DELAYED
+
+    -- Set Menu option for auto lase
+
+    if self.AutoLase then        
+      MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Auto Lase Off", MenuDesignate, self.MenuAutoLase, self, false ):SetTime( MenuTime ):SetTag( self.DesignateName )
+    else
+      MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Auto Lase On", MenuDesignate, self.MenuAutoLase, self, true ):SetTime( MenuTime ):SetTag( self.DesignateName )
+    end        
+
+    local StatusMenu = MENU_GROUP_DELAYED:New( AttackGroup, "Status", MenuDesignate ):SetTime( MenuTime ):SetTag( self.DesignateName )
+    MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Report Status", StatusMenu, self.MenuStatus, self, AttackGroup ):SetTime( MenuTime ):SetTag( self.DesignateName )
+    
+    if self.FlashStatusMenu[AttackGroup] then
+      MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Flash Status Report Off", StatusMenu, self.MenuFlashStatus, self, AttackGroup, false ):SetTime( MenuTime ):SetTag( self.DesignateName )
+    else
+       MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Flash Status Report On", StatusMenu, self.MenuFlashStatus, self, AttackGroup, true ):SetTime( MenuTime ):SetTag( self.DesignateName )
+    end        
+  
+    local DesignateCount = 0
+  
+    for DesignateIndex, Designating in pairs( self.Designating ) do
+
+      local DetectedItem = self.Detection:GetDetectedItemByIndex( DesignateIndex )
+
+      if DetectedItem then
+      
+        local Coord = self.Detection:GetDetectedItemCoordinate( DetectedItem )
+        local ID = self.Detection:GetDetectedItemID( DetectedItem )
+        local MenuText = ID --.. ", " .. Coord:ToStringA2G( AttackGroup )
+        
+        MenuText = string.format( "(%3s) %s", Designating, MenuText )
+        local DetectedMenu = MENU_GROUP_DELAYED:New( AttackGroup, MenuText, MenuDesignate ):SetTime( MenuTime ):SetTag( self.DesignateName )
+        
+        -- Build the Lasing menu.
+        if string.find( Designating, "L", 1, true ) == nil then
+          MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Search other target", DetectedMenu, self.MenuForget, self, DesignateIndex ):SetTime( MenuTime ):SetTag( self.DesignateName )
+          for LaserCode, MenuText in pairs( self.MenuLaserCodes ) do
+            MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, string.format( MenuText, LaserCode ), DetectedMenu, self.MenuLaseCode, self, DesignateIndex, 60, LaserCode ):SetTime( MenuTime ):SetTag( self.DesignateName )
+          end
+          MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Lase with random laser code(s)", DetectedMenu, self.MenuLaseOn, self, DesignateIndex, 60 ):SetTime( MenuTime ):SetTag( self.DesignateName )
+        else
+          MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Stop lasing", DetectedMenu, self.MenuLaseOff, self, DesignateIndex ):SetTime( MenuTime ):SetTag( self.DesignateName )
+        end
+        
+        -- Build the Smoking menu.
+        if string.find( Designating, "S", 1, true ) == nil then
+          MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Smoke red", DetectedMenu, self.MenuSmoke, self, DesignateIndex, SMOKECOLOR.Red ):SetTime( MenuTime ):SetTag( self.DesignateName )
+          MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Smoke blue", DetectedMenu, self.MenuSmoke, self, DesignateIndex, SMOKECOLOR.Blue ):SetTime( MenuTime ):SetTag( self.DesignateName )
+          MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Smoke green", DetectedMenu, self.MenuSmoke, self, DesignateIndex, SMOKECOLOR.Green ):SetTime( MenuTime ):SetTag( self.DesignateName )
+          MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Smoke white", DetectedMenu, self.MenuSmoke, self, DesignateIndex, SMOKECOLOR.White ):SetTime( MenuTime ):SetTag( self.DesignateName )
+          MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Smoke orange", DetectedMenu, self.MenuSmoke, self, DesignateIndex, SMOKECOLOR.Orange ):SetTime( MenuTime ):SetTag( self.DesignateName )
+        end            
+
+        -- Build the Illuminate menu.
+        if string.find( Designating, "I", 1, true ) == nil then
+          MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Illuminate", DetectedMenu, self.MenuIlluminate, self, DesignateIndex ):SetTime( MenuTime ):SetTag( self.DesignateName )
+        end
+      end
+      
+      DesignateCount = DesignateCount + 1
+      if DesignateCount > 10 then
+        break
+      end
+    end
+    MenuDesignate:Remove( MenuTime, self.DesignateName )
+    MenuDesignate:Set()
+  end
+
+
+  --- Sets the Designate Menu for all the attack groups.
   -- @param #DESIGNATE self
   -- @return #DESIGNATE
   function DESIGNATE:SetDesignateMenu()
 
     self.AttackSet:Flush( self )
+    
+    local Delay = 1
 
     self.AttackSet:ForEachGroupAlive(
     
       --- @param Wrapper.Group#GROUP GroupReport
       function( AttackGroup )
-        self.MenuDesignate = self.MenuDesignate or {}
-        
-        local MissionMenu = nil
-        
-        if self.Mission then
-          MissionMenu = self.Mission:GetRootMenu( AttackGroup )
-        end
-        
-        local MenuTime = timer.getTime()
-        
-        self.MenuDesignate[AttackGroup] = MENU_GROUP_DELAYED:New( AttackGroup, self.DesignateName, MissionMenu ):SetTime( MenuTime ):SetTag( self.DesignateName ) 
-        local MenuDesignate = self.MenuDesignate[AttackGroup] -- Core.Menu#MENU_GROUP_DELAYED
-
-        -- Set Menu option for auto lase
-
-        if self.AutoLase then        
-          MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Auto Lase Off", MenuDesignate, self.MenuAutoLase, self, false ):SetTime( MenuTime ):SetTag( self.DesignateName )
-        else
-          MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Auto Lase On", MenuDesignate, self.MenuAutoLase, self, true ):SetTime( MenuTime ):SetTag( self.DesignateName )
-        end        
-
-        local StatusMenu = MENU_GROUP_DELAYED:New( AttackGroup, "Status", MenuDesignate ):SetTime( MenuTime ):SetTag( self.DesignateName )
-        MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Report Status", StatusMenu, self.MenuStatus, self, AttackGroup ):SetTime( MenuTime ):SetTag( self.DesignateName )
-        
-        if self.FlashStatusMenu[AttackGroup] then
-          MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Flash Status Report Off", StatusMenu, self.MenuFlashStatus, self, AttackGroup, false ):SetTime( MenuTime ):SetTag( self.DesignateName )
-        else
-           MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Flash Status Report On", StatusMenu, self.MenuFlashStatus, self, AttackGroup, true ):SetTime( MenuTime ):SetTag( self.DesignateName )
-        end        
       
-        for DesignateIndex, Designating in pairs( self.Designating ) do
-
-          local DetectedItem = self.Detection:GetDetectedItemByIndex( DesignateIndex )
-
-          if DetectedItem then
-          
-            local Coord = self.Detection:GetDetectedItemCoordinate( DetectedItem )
-            local ID = self.Detection:GetDetectedItemID( DetectedItem )
-            local MenuText = ID --.. ", " .. Coord:ToStringA2G( AttackGroup )
-            
-            MenuText = string.format( "(%3s) %s", Designating, MenuText )
-            local DetectedMenu = MENU_GROUP_DELAYED:New( AttackGroup, MenuText, MenuDesignate ):SetTime( MenuTime ):SetTag( self.DesignateName )
-            
-            -- Build the Lasing menu.
-            if string.find( Designating, "L", 1, true ) == nil then
-              MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Search other target", DetectedMenu, self.MenuForget, self, DesignateIndex ):SetTime( MenuTime ):SetTag( self.DesignateName )
-              for LaserCode, MenuText in pairs( self.MenuLaserCodes ) do
-                MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, string.format( MenuText, LaserCode ), DetectedMenu, self.MenuLaseCode, self, DesignateIndex, 60, LaserCode ):SetTime( MenuTime ):SetTag( self.DesignateName )
-              end
-              MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Lase with random laser code(s)", DetectedMenu, self.MenuLaseOn, self, DesignateIndex, 60 ):SetTime( MenuTime ):SetTag( self.DesignateName )
-            else
-              MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Stop lasing", DetectedMenu, self.MenuLaseOff, self, DesignateIndex ):SetTime( MenuTime ):SetTag( self.DesignateName )
-            end
-            
-            -- Build the Smoking menu.
-            if string.find( Designating, "S", 1, true ) == nil then
-              MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Smoke red", DetectedMenu, self.MenuSmoke, self, DesignateIndex, SMOKECOLOR.Red ):SetTime( MenuTime ):SetTag( self.DesignateName )
-              MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Smoke blue", DetectedMenu, self.MenuSmoke, self, DesignateIndex, SMOKECOLOR.Blue ):SetTime( MenuTime ):SetTag( self.DesignateName )
-              MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Smoke green", DetectedMenu, self.MenuSmoke, self, DesignateIndex, SMOKECOLOR.Green ):SetTime( MenuTime ):SetTag( self.DesignateName )
-              MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Smoke white", DetectedMenu, self.MenuSmoke, self, DesignateIndex, SMOKECOLOR.White ):SetTime( MenuTime ):SetTag( self.DesignateName )
-              MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Smoke orange", DetectedMenu, self.MenuSmoke, self, DesignateIndex, SMOKECOLOR.Orange ):SetTime( MenuTime ):SetTag( self.DesignateName )
-            end            
-
-            -- Build the Illuminate menu.
-            if string.find( Designating, "I", 1, true ) == nil then
-              MENU_GROUP_COMMAND_DELAYED:New( AttackGroup, "Illuminate", DetectedMenu, self.MenuIlluminate, self, DesignateIndex ):SetTime( MenuTime ):SetTag( self.DesignateName )
-            end
-          end
-        end
-        MenuDesignate:Remove( MenuTime, self.DesignateName )
-        MenuDesignate:Set()
-      end
+        self:ScheduleOnce( Delay, self.SetMenu, self, AttackGroup )
+        Delay = Delay + 1
+      end  
+        
     )
     
     return self

Moose Development/Moose/Functional/Detection.lua

@@ -2,18 +2,25 @@
 -- 
 -- ===
 -- 
+-- ## Features:
+-- 
+--   * Detection of targets by recce units.
+--   * Group detected targets per unit, type or area (zone).
+--   * Keep persistency of detected targets, if when detection is lost.
+--   * Provide an indication of detected targets.
+--   * Report detected targets.
+--   * Refresh detection upon specified time intervals.
+-- 
+-- ===
+-- 
+-- ## Missions:
+-- 
+-- [DET - Detection](https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/master/DET%20-%20Detection)
+-- 
+-- ===
+-- 
 -- Facilitate the detection of enemy units within the battle zone executed by FACs (Forward Air Controllers) or RECCEs (Reconnassance Units).
--- DETECTION uses the in-built detection capabilities of DCS World, but adds new functionalities.
--- 
--- Find the DETECTION classes documentation further in this document in the globals section.
--- 
--- ===
--- 
--- ### [Demo Missions](https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/master/DET%20-%20Detection)
--- 
--- ===
--- 
--- ### [YouTube Playlist](https://www.youtube.com/playlist?list=PL7ZUrU4zZUl3Cf5jpI6BS0sBOVWK__tji)
+-- It uses the in-built detection capabilities of DCS World, but adds new functionalities.
 -- 
 -- ===
 -- 
@@ -25,13 +32,11 @@
 -- 
 --   * FlightControl : Analysis, Design, Programming, Testing
 -- 
+-- ===
+-- 
 -- @module Functional.Detection
 -- @image Detection.JPG
 
-----BASE:TraceClass("DETECTION_BASE")
-----BASE:TraceClass("DETECTION_AREAS")
-----BASE:TraceClass("DETECTION_UNITS")
-----BASE:TraceClass("DETECTION_TYPES")
 
 do -- DETECTION_BASE
 
@@ -287,6 +292,7 @@ do -- DETECTION_BASE
   -- @list <#DETECTION_BASE.DetectedItem>
   
   --- @type DETECTION_BASE.DetectedItem
+  -- @field #boolean IsDetected Indicates if the DetectedItem has been detected or not.
   -- @field Core.Set#SET_UNIT Set
   -- @field Core.Set#SET_UNIT Set -- The Set of Units in the detected area.
   -- @field Core.Zone#ZONE_UNIT Zone -- The Zone of the detected area.
@@ -445,7 +451,16 @@ do -- DETECTION_BASE
     -- @param #DETECTION_BASE self
     -- @param #number Delay The delay in seconds.
     
+    self:AddTransition( "Detecting", "DetectedItem", "Detecting" )
     
+    --- OnAfter Transition Handler for Event DetectedItem.
+    -- @function [parent=#DETECTION_BASE] OnAfterDetectedItem
+    -- @param #DETECTION_BASE self
+    -- @param #string From The From State string.
+    -- @param #string Event The Event string.
+    -- @param #string To The To State string.
+    -- @param #table DetectedItem The DetectedItem.
+      
     self:AddTransition( "*", "Stop", "Stopped" )
     
     --- OnBefore Transition Handler for Event Stop.
@@ -513,8 +528,21 @@ do -- DETECTION_BASE
       
       local DetectionTimeStamp = timer.getTime()
       
+      -- Reset detection cache for the next detection run.
+      for DetectionObjectName, DetectedObjectData in pairs( self.DetectedObjects ) do
+        
+        self.DetectedObjects[DetectionObjectName].IsDetected = false
+        self.DetectedObjects[DetectionObjectName].IsVisible = false
+        self.DetectedObjects[DetectionObjectName].KnowDistance = nil
+        self.DetectedObjects[DetectionObjectName].LastTime = nil
+        self.DetectedObjects[DetectionObjectName].LastPos = nil
+        self.DetectedObjects[DetectionObjectName].LastVelocity = nil
+        self.DetectedObjects[DetectionObjectName].Distance = 10000000
+      
+      end
       for DetectionGroupID, DetectionGroupData in pairs( self.DetectionSetGroup:GetSet() ) do
         --self:F( { DetectionGroupData } )
+        self:F( { DetectionGroup = DetectionGroupData:GetName() } )
         self:__DetectionGroup( DetectDelay, DetectionGroupData, DetectionTimeStamp ) -- Process each detection asynchronously.
         self.DetectionCount = self.DetectionCount + 1
         DetectDelay = DetectDelay + 1
@@ -526,8 +554,11 @@ do -- DETECTION_BASE
     -- @param #string Event The Event string.
     -- @param #string To The To State string.
     -- @param Wrapper.Group#GROUP DetectionGroup The Group detecting.
+    -- @param #number DetectionTimeStamp Time stamp of detection event.
     function DETECTION_BASE:onafterDetectionGroup( From, Event, To, DetectionGroup, DetectionTimeStamp  )
       
+      --self:F( { DetectedObjects = self.DetectedObjects } )
+      
       self.DetectionRun = self.DetectionRun + 1
       
       local HasDetectedObjects = false
@@ -550,13 +581,27 @@ do -- DETECTION_BASE
           self.DetectDLINK
         )
         
-        --self:F( DetectedTargets )
+        self:F( { DetectedTargets = DetectedTargets } )
         
         for DetectionObjectID, Detection in pairs( DetectedTargets ) do
           local DetectedObject = Detection.object -- DCS#Object
           
           if DetectedObject and DetectedObject:isExist() and DetectedObject.id_ < 50000000 then -- and ( DetectedObject:getCategory() == Object.Category.UNIT or DetectedObject:getCategory() == Object.Category.STATIC ) then
-    
+            local DetectedObjectName = DetectedObject:getName()
+            if not self.DetectedObjects[DetectedObjectName] then
+              self.DetectedObjects[DetectedObjectName] = self.DetectedObjects[DetectedObjectName] or {} 
+              self.DetectedObjects[DetectedObjectName].Name = DetectedObjectName
+              self.DetectedObjects[DetectedObjectName].Object = DetectedObject
+            end
+          end
+        end
+        
+        for DetectionObjectName, DetectedObjectData in pairs( self.DetectedObjects ) do
+        
+          local DetectedObject = DetectedObjectData.Object
+          
+          if DetectedObject:isExist() then
+  
             local TargetIsDetected, TargetIsVisible, TargetLastTime, TargetKnowType, TargetKnowDistance, TargetLastPos, TargetLastVelocity = DetectionUnit:IsTargetDetected( 
               DetectedObject,
               self.DetectVisual,
@@ -568,7 +613,7 @@ do -- DETECTION_BASE
             )
             
             --self:T2( { TargetIsDetected = TargetIsDetected, TargetIsVisible = TargetIsVisible, TargetLastTime = TargetLastTime, TargetKnowType = TargetKnowType, TargetKnowDistance = TargetKnowDistance, TargetLastPos = TargetLastPos, TargetLastVelocity = TargetLastVelocity } )
-
+  
             -- Only process if the target is visible. Detection also returns invisible units.
             --if Detection.visible == true then
             
@@ -631,7 +676,7 @@ do -- DETECTION_BASE
               
               -- Calculate additional probabilities
               
-              if not self.DetectedObjects[DetectedObjectName] and Detection.visible and self.DistanceProbability then
+              if not self.DetectedObjects[DetectedObjectName] and TargetIsVisible and self.DistanceProbability then
                 local DistanceFactor = Distance / 4
                 local DistanceProbabilityReversed = ( 1 - self.DistanceProbability ) * DistanceFactor
                 local DistanceProbability = 1 - DistanceProbabilityReversed
@@ -643,7 +688,7 @@ do -- DETECTION_BASE
                 end
               end
               
-              if not self.DetectedObjects[DetectedObjectName] and Detection.visible and self.AlphaAngleProbability then
+              if not self.DetectedObjects[DetectedObjectName] and TargetIsVisible and self.AlphaAngleProbability then
                 local NormalVec2 = { x = DetectedObjectVec2.x - DetectionGroupVec2.x, y = DetectedObjectVec2.y - DetectionGroupVec2.y }
                 local AlphaAngle = math.atan2( NormalVec2.y, NormalVec2.x )
                 local Sinus = math.sin( AlphaAngle )
@@ -660,7 +705,7 @@ do -- DETECTION_BASE
                  
               end
               
-              if not self.DetectedObjects[DetectedObjectName] and Detection.visible and self.ZoneProbability then
+              if not self.DetectedObjects[DetectedObjectName] and TargetIsVisible and self.ZoneProbability then
               
                 for ZoneDataID, ZoneData in pairs( self.ZoneProbability ) do
                   self:F({ZoneData})
@@ -683,33 +728,50 @@ do -- DETECTION_BASE
                 
                 HasDetectedObjects = true
       
-                self.DetectedObjects[DetectedObjectName] = self.DetectedObjects[DetectedObjectName] or {} 
+                self.DetectedObjects[DetectedObjectName] = self.DetectedObjects[DetectedObjectName] or {}
                 self.DetectedObjects[DetectedObjectName].Name = DetectedObjectName
-                self.DetectedObjects[DetectedObjectName].IsDetected = TargetIsDetected
-                self.DetectedObjects[DetectedObjectName].IsVisible = TargetIsVisible 
-                self.DetectedObjects[DetectedObjectName].LastTime = TargetLastTime
-                self.DetectedObjects[DetectedObjectName].LastPos = TargetLastPos
-                self.DetectedObjects[DetectedObjectName].LastVelocity = TargetLastVelocity
-                self.DetectedObjects[DetectedObjectName].KnowType = TargetKnowType
-                self.DetectedObjects[DetectedObjectName].KnowDistance = Detection.distance   -- TargetKnowDistance
-                self.DetectedObjects[DetectedObjectName].Distance = Distance
+  
+                if TargetIsDetected and TargetIsDetected == true then
+                  self.DetectedObjects[DetectedObjectName].IsDetected = TargetIsDetected
+                end
+                
+                if TargetIsDetected and TargetIsVisible and TargetIsVisible == true then
+                  self.DetectedObjects[DetectedObjectName].IsVisible = TargetIsDetected and TargetIsVisible
+                end
+                
+                if TargetIsDetected and not self.DetectedObjects[DetectedObjectName].KnowType then
+                  self.DetectedObjects[DetectedObjectName].KnowType = TargetIsDetected and TargetKnowType
+                end
+                self.DetectedObjects[DetectedObjectName].KnowDistance = TargetKnowDistance -- Detection.distance   -- TargetKnowDistance
+                self.DetectedObjects[DetectedObjectName].LastTime = ( TargetIsDetected and TargetIsVisible == false )  and TargetLastTime
+                self.DetectedObjects[DetectedObjectName].LastPos = ( TargetIsDetected and TargetIsVisible == false )  and TargetLastPos
+                self.DetectedObjects[DetectedObjectName].LastVelocity = ( TargetIsDetected and TargetIsVisible == false )  and TargetLastVelocity
+                
+                if not self.DetectedObjects[DetectedObjectName].Distance or ( Distance and self.DetectedObjects[DetectedObjectName].Distance > Distance ) then
+                  self.DetectedObjects[DetectedObjectName].Distance = Distance
+                end
+  
                 self.DetectedObjects[DetectedObjectName].DetectionTimeStamp = DetectionTimeStamp
                 
-                --self:F( { DetectedObject = self.DetectedObjects[DetectedObjectName] } )
+                self:F( { DetectedObject = self.DetectedObjects[DetectedObjectName] } )
                 
                 local DetectedUnit = UNIT:FindByName( DetectedObjectName )
                 
                 DetectedUnits[DetectedObjectName] = DetectedUnit
               else
                 -- if beyond the DetectionRange then nullify...
+                self:F( { DetectedObject = "No more detection for " .. DetectedObjectName } )
                 if self.DetectedObjects[DetectedObjectName] then
                   self.DetectedObjects[DetectedObjectName] = nil
                 end
               end
-            --end
+            
+            --self:T2( self.DetectedObjects )
+          else
+            -- The previously detected object does not exist anymore, delete from the cache.
+            self:F( "Removing from DetectedObjects: " .. DetectionObjectName )
+            self.DetectedObjects[DetectionObjectName] = nil
           end
-          
-          --self:T2( self.DetectedObjects )
         end
         
         if HasDetectedObjects then
@@ -735,6 +797,9 @@ do -- DETECTION_BASE
         for DetectedItemID, DetectedItem in pairs( self.DetectedItems ) do
           self:UpdateDetectedItemDetection( DetectedItem )
           self:CleanDetectionItem( DetectedItem, DetectedItemID ) -- Any DetectionItem that has a Set with zero elements in it, must be removed from the DetectionItems list.
+          if DetectedItem then
+            self:__DetectedItem( 0.1, DetectedItem )
+          end
         end
  
         self:__Detect( self.RefreshTimeInterval )
@@ -1396,16 +1461,18 @@ do -- DETECTION_BASE
   -- @param #string ObjectName
   -- @return #DETECTION_BASE.DetectedObject
   function DETECTION_BASE:GetDetectedObject( ObjectName )
-  	--self:F2( ObjectName )
+  	self:F2( { ObjectName = ObjectName } )
     
     if ObjectName then
       local DetectedObject = self.DetectedObjects[ObjectName]
       
       if DetectedObject then
+        --self:F( { DetectedObjects = self.DetectedObjects } )
         -- Only return detected objects that are alive!
         local DetectedUnit = UNIT:FindByName( ObjectName )
         if DetectedUnit and DetectedUnit:IsAlive() then
           if self:IsDetectedObjectIdentified( DetectedObject ) == false then
+            --self:F( { DetectedObject = DetectedObject } )
             return DetectedObject
           end
         end
@@ -1604,7 +1671,7 @@ do -- DETECTION_BASE
     return nil
   end
   
-  --- Set IsDetected flag for all DetectedItems.
+  --- Set IsDetected flag for the DetectedItem, which can have more units.
   -- @param #DETECTION_BASE self
   -- @return #DETECTION_BASE.DetectedItem DetectedItem
   -- @return #boolean true if at least one UNIT is detected from the DetectedSet, false if no UNIT was detected from the DetectedSet.
@@ -1802,14 +1869,16 @@ end
 
 do -- DETECTION_UNITS
 
+  --- @type DETECTION_UNITS
+  -- @field DCS#Distance DetectionRange The range till which targets are detected.
+  -- @extends Functional.Detection#DETECTION_BASE
+
   --- Will detect units within the battle zone.
   -- 
   -- It will build a DetectedItems list filled with DetectedItems. Each DetectedItem will contain a field Set, which contains a @{Core.Set#SET_UNIT} containing ONE @{UNIT} object reference.
   -- Beware that when the amount of units detected is large, the DetectedItems list will be large also. 
   -- 
-  -- @type DETECTION_UNITS
-  -- @field DCS#Distance DetectionRange The range till which targets are detected.
-  -- @extends #DETECTION_BASE
+  -- @field #DETECTION_UNITS
   DETECTION_UNITS = {
     ClassName = "DETECTION_UNITS",
     DetectionRange = nil,
@@ -1835,7 +1904,7 @@ do -- DETECTION_UNITS
 
   --- Make text documenting the changes of the detected zone.
   -- @param #DETECTION_UNITS self
-  -- @param #DETECTION_UNITS.DetectedItem DetectedItem
+  -- @param #DETECTION_BASE.DetectedItem DetectedItem
   -- @return #string The Changes text
   function DETECTION_UNITS:GetChangeText( DetectedItem )
     self:F( DetectedItem )
@@ -1876,7 +1945,6 @@ do -- DETECTION_UNITS
   -- @param #DETECTION_UNITS self
   -- @return #DETECTION_UNITS self
   function DETECTION_UNITS:CreateDetectionItems()
-  
     -- Loop the current detected items, and check if each object still exists and is detected.
     
     for DetectedItemKey, DetectedItem in pairs( self.DetectedItems ) do
@@ -1897,6 +1965,7 @@ do -- DETECTION_UNITS
           -- Yes, the DetectedUnit is still detected or exists. Flag as identified.
           self:IdentifyDetectedObject( DetectedObject )
           
+          self:F( { "**DETECTED**", IsVisible = DetectedObject.IsVisible } )
           -- Update the detection with the new data provided.
           DetectedItem.TypeName = DetectedUnit:GetTypeName()            
           DetectedItem.CategoryName = DetectedUnit:GetCategoryName()            
@@ -2021,6 +2090,9 @@ do -- DETECTION_UNITS
       Report:Add(DetectedItemID .. ", " .. DetectedItemCoordText)
       Report:Add( string.format( "Threat: [%s]", string.rep(  "■", ThreatLevelA2G ), string.rep(  "□", 10-ThreatLevelA2G ) ) )
       Report:Add( string.format("Type: %s%s", UnitCategoryText, UnitDistanceText ) )
+      Report:Add( string.format("Visible: %s", DetectedItem.IsVisible and "yes" or "no" ) )
+      Report:Add( string.format("Detected: %s", DetectedItem.IsDetected and "yes" or "no" ) )
+      Report:Add( string.format("Distance: %s", DetectedItem.KnowDistance and "yes" or "no" ) )
       return Report
     end
     return nil
@@ -2051,13 +2123,15 @@ end
 
 do -- DETECTION_TYPES
 
+  --- @type DETECTION_TYPES
+  -- @extends Functional.Detection#DETECTION_BASE
+
   --- Will detect units within the battle zone.
   -- It will build a DetectedItems[] list filled with DetectedItems, grouped by the type of units detected. 
   -- Each DetectedItem will contain a field Set, which contains a @{Core.Set#SET_UNIT} containing ONE @{UNIT} object reference.
   -- Beware that when the amount of different types detected is large, the DetectedItems[] list will be large also. 
   -- 
-  -- @type DETECTION_TYPES
-  -- @extends #DETECTION_BASE
+  -- @field #DETECTION_TYPES
   DETECTION_TYPES = {
     ClassName = "DETECTION_TYPES",
     DetectionRange = nil,
@@ -2083,7 +2157,7 @@ do -- DETECTION_TYPES
 
   --- Make text documenting the changes of the detected zone.
   -- @param #DETECTION_TYPES self
-  -- @param #DETECTION_TYPES.DetectedItem DetectedItem
+  -- @param Functional.Detection#DETECTION_BASE.DetectedItem DetectedItem
   -- @return #string The Changes text
   function DETECTION_TYPES:GetChangeText( DetectedItem )
     self:F( DetectedItem )
@@ -2258,6 +2332,11 @@ end
 
 do -- DETECTION_AREAS
 
+  --- @type DETECTION_AREAS
+  -- @field DCS#Distance DetectionZoneRange The range till which targets are grouped upon the first detected target.
+  -- @field #DETECTION_BASE.DetectedItems DetectedItems A list of areas containing the set of @{Wrapper.Unit}s, @{Zone}s, the center @{Wrapper.Unit} within the zone, and ID of each area that was detected within a DetectionZoneRange.
+  -- @extends Functional.Detection#DETECTION_BASE
+
   --- Detect units within the battle zone for a list of @{Wrapper.Group}s detecting targets following (a) detection method(s), 
   -- and will build a list (table) of @{Core.Set#SET_UNIT}s containing the @{Wrapper.Unit#UNIT}s detected.
   -- The class is group the detected units within zones given a DetectedZoneRange parameter.
@@ -2288,10 +2367,7 @@ do -- DETECTION_AREAS
   --   
   -- the detected zones when a new detection has taken place.
   -- 
-  -- @type DETECTION_AREAS
-  -- @field DCS#Distance DetectionZoneRange The range till which targets are grouped upon the first detected target.
-  -- @field #DETECTION_BASE.DetectedItems DetectedItems A list of areas containing the set of @{Wrapper.Unit}s, @{Zone}s, the center @{Wrapper.Unit} within the zone, and ID of each area that was detected within a DetectionZoneRange.
-  -- @extends #DETECTION_BASE
+  -- @field #DETECTION_AREAS
   DETECTION_AREAS = {
     ClassName = "DETECTION_AREAS",
     DetectionZoneRange = nil,
@@ -2347,6 +2423,7 @@ do -- DETECTION_AREAS
       Report:Add(DetectedItemID .. ", " .. DetectedItemCoordText)
       Report:Add( string.format( "Threat: [%s]", string.rep(  "■", ThreatLevelA2G ), string.rep(  "□", 10-ThreatLevelA2G ) ) )
       Report:Add( string.format("Type: %2d of %s", DetectedItemsCount, DetectedItemsTypes ) )
+      Report:Add( string.format("Detected: %s", DetectedItem.IsDetected and "yes" or "no" ) )
       
       return Report
     end
@@ -2511,7 +2588,9 @@ do -- DETECTION_AREAS
   function DETECTION_AREAS:CreateDetectionItems()
   
   
-    self:T2( "Checking Detected Items for new Detected Units ..." )
+    self:F( "Checking Detected Items for new Detected Units ..." )
+    --self:F( { DetectedObjects = self.DetectedObjects } )
+    
     -- First go through all detected sets, and check if there are new detected units, match all existing detected units and identify undetected units.
     -- Regroup when needed, split groups when needed.
     for DetectedItemID, DetectedItemData in pairs( self.DetectedItems ) do

Moose Development/Moose/Functional/Escort.lua

@@ -2,6 +2,27 @@
 -- 
 -- ===
 -- 
+-- ## Features:
+-- 
+--   * Escort navigation commands.
+--   * Escort hold at position commands.
+--   * Escorts reporting detected targets.
+--   * Escorts scanning targets in advance.
+--   * Escorts attacking specific targets.
+--   * Request assistance from other groups for attack.
+--   * Manage rule of engagement of escorts.
+--   * Manage the allowed evasion techniques of escorts.
+--   * Make escort to execute a defined mission or path.
+--   * Escort tactical situation reporting.
+-- 
+-- ===
+-- 
+-- ## Missions:
+-- 
+-- [ESC - Escorting](https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/master/ESC%20-%20Escorting)
+-- 
+-- ===
+-- 
 -- Allows you to interact with escorting AI on your flight and take the lead.
 -- 
 -- Each escorting group can be commanded with a whole set of radio commands (radio menu in your flight, and then F10).
@@ -77,47 +98,18 @@
 -- Escort groups can have their own mission. This menu item will allow the escort group to resume their Mission from a given waypoint.
 -- Note that this is really fantastic, as you now have the dynamic of taking control of the escort groups, and allowing them to resume their path or mission.
 --
--- # ESCORT construction methods.
+-- ===
 -- 
--- Create a new SPAWN object with the @{#ESCORT.New} method:
---
---  * @{#ESCORT.New}: Creates a new ESCORT object from a @{Wrapper.Group#GROUP} for a @{Wrapper.Client#CLIENT}, with an optional briefing text.
---
--- # ESCORT initialization methods.
+-- ### Authors: **FlightControl** 
 -- 
--- The following menus are created within the RADIO MENU (F10) of an active unit hosted by a player:
---
--- * @{#ESCORT.MenuFollowAt}: Creates a menu to make the escort follow the client.
--- * @{#ESCORT.MenuHoldAtEscortPosition}: Creates a menu to hold the escort at its current position.
--- * @{#ESCORT.MenuHoldAtLeaderPosition}: Creates a menu to hold the escort at the client position.
--- * @{#ESCORT.MenuScanForTargets}: Creates a menu so that the escort scans targets.
--- * @{#ESCORT.MenuFlare}: Creates a menu to disperse flares.
--- * @{#ESCORT.MenuSmoke}: Creates a menu to disparse smoke.
--- * @{#ESCORT.MenuReportTargets}: Creates a menu so that the escort reports targets.
--- * @{#ESCORT.MenuReportPosition}: Creates a menu so that the escort reports its current position from bullseye.
--- * @{#ESCORT.MenuAssistedAttack: Creates a menu so that the escort supportes assisted attack from other escorts with the client.
--- * @{#ESCORT.MenuROE: Creates a menu structure to set the rules of engagement of the escort.
--- * @{#ESCORT.MenuEvasion: Creates a menu structure to set the evasion techniques when the escort is under threat.
--- * @{#ESCORT.MenuResumeMission}: Creates a menu structure so that the escort can resume from a waypoint.
--- 
--- 
--- @usage
--- -- Declare a new EscortPlanes object as follows:
--- 
--- -- First find the GROUP object and the CLIENT object.
--- local EscortClient = CLIENT:FindByName( "Unit Name" ) -- The Unit Name is the name of the unit flagged with the skill Client in the mission editor.
--- local EscortGroup = GROUP:FindByName( "Group Name" ) -- The Group Name is the name of the group that will escort the Escort Client.
--- 
--- -- Now use these 2 objects to construct the new EscortPlanes object.
--- EscortPlanes = ESCORT:New( EscortClient, EscortGroup, "Desert", "Welcome to the mission. You are escorted by a plane with code name 'Desert', which can be instructed through the F10 radio menu." )
--- 
---
+-- ===
 --
 -- @module Functional.Escort
 -- @image Escorting.JPG
 
---- ESCORT class
--- @type ESCORT
+
+
+--- @type ESCORT
 -- @extends Core.Base#BASE
 -- @field Wrapper.Client#CLIENT EscortClient
 -- @field Wrapper.Group#GROUP EscortGroup
@@ -129,6 +121,26 @@
 -- @Field DCS#AI.Option.Air.val.ROE OptionROE Which ROE is set to the EscortGroup.
 -- @field DCS#AI.Option.Air.val.REACTION_ON_THREAT OptionReactionOnThreat Which REACTION_ON_THREAT is set to the EscortGroup.
 -- @field FunctionalMENU_GROUPDETECTION_BASE Detection
+
+--- ESCORT class
+-- 
+-- # ESCORT construction methods.
+-- 
+-- Create a new SPAWN object with the @{#ESCORT.New} method:
+--
+--  * @{#ESCORT.New}: Creates a new ESCORT object from a @{Wrapper.Group#GROUP} for a @{Wrapper.Client#CLIENT}, with an optional briefing text.
+--
+-- @usage
+-- -- Declare a new EscortPlanes object as follows:
+-- 
+-- -- First find the GROUP object and the CLIENT object.
+-- local EscortClient = CLIENT:FindByName( "Unit Name" ) -- The Unit Name is the name of the unit flagged with the skill Client in the mission editor.
+-- local EscortGroup = GROUP:FindByName( "Group Name" ) -- The Group Name is the name of the group that will escort the Escort Client.
+-- 
+-- -- Now use these 2 objects to construct the new EscortPlanes object.
+-- EscortPlanes = ESCORT:New( EscortClient, EscortGroup, "Desert", "Welcome to the mission. You are escorted by a plane with code name 'Desert', which can be instructed through the F10 radio menu." )
+--
+-- @field #ESCORT
 ESCORT = {
   ClassName = "ESCORT",
   EscortName = nil, -- The Escort Name

Moose Development/Moose/Functional/MissileTrainer.lua

@@ -1,18 +1,27 @@
---- **Functional** -- MISSILETRAINER helps you to train missile avoidance.
+--- **Functional** -- Train missile defence and deflection.
 -- 
 -- ===
 --
--- The @{#MISSILETRAINER} class uses the DCS world messaging system to be alerted of any missiles fired, and when a missile would hit your aircraft,
+-- ## Features:
+-- 
+--   * Track the missiles fired at you and other players, providing bearing and range information of the missiles towards the airplanes.
+--   * Provide alerts of missile launches, including detailed information of the units launching, including bearing, range <20>
+--   * Provide alerts when a missile would have killed your aircraft.
+--   * Provide alerts when the missile self destructs.
+--   * Enable / Disable and Configure the Missile Trainer using the various menu options.
+-- 
+-- ===
+-- 
+-- ## Missions:
+-- 
+-- [MIT - Missile Trainer](https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/master/MIT%20-%20Missile%20Trainer)
+-- 
+-- ===
+-- 
+-- Uses the MOOSE messaging system to be alerted of any missiles fired, and when a missile would hit your aircraft,
 -- the class will destroy the missile within a certain range, to avoid damage to your aircraft.
--- It suports the following functionality:
---
---  * Track the missiles fired at you and other players, providing bearing and range information of the missiles towards the airplanes.
---  * Provide alerts of missile launches, including detailed information of the units launching, including bearing, range <20>
---  * Provide alerts when a missile would have killed your aircraft.
---  * Provide alerts when the missile self destructs.
---  * Enable / Disable and Configure the Missile Trainer using the various menu options.
 --  
---  When running a mission where MISSILETRAINER is used, the following radio menu structure ( 'Radio Menu' -> 'Other (F10)' -> 'MissileTrainer' ) options are available for the players:
+-- When running a mission where the missile trainer is used, the following radio menu structure ( 'Radio Menu' -> 'Other (F10)' -> 'MissileTrainer' ) options are available for the players:
 --  
 --  * **Messages**: Menu to configure all messages.
 --     * **Messages On**: Show all messages.
@@ -42,17 +51,40 @@
 --     * **150 meter**: Destroys the missile when the distance to the aircraft is below or equal to 150 meter.
 --     * **200 meter**: Destroys the missile when the distance to the aircraft is below or equal to 200 meter.
 --   
+-- ===
+-- 
+-- ### Authors: **FlightControl**
+-- 
+-- ### Contributions:
+-- 
+--    * **Stuka (Danny)**: Who you can search on the Eagle Dynamics Forums. Working together with Danny has resulted in the MISSILETRAINER class.  
+--      Danny has shared his ideas and together we made a design. 
+--      Together with the **476 virtual team**, we tested the MISSILETRAINER class, and got much positive feedback!
+--    * **132nd Squadron**: Testing and optimizing the logic.
+-- 
+-- ===
 --
--- 1.1) MISSILETRAINER construction methods:
--- -----------------------------------------
+-- @module Functional.MissileTrainer
+-- @image Missile_Trainer.JPG
+
+
+--- @type MISSILETRAINER
+-- @field Core.Set#SET_CLIENT DBClients
+-- @extends Core.Base#BASE
+
+
+---
+--
+-- # Constructor:
+-- 
 -- Create a new MISSILETRAINER object with the @{#MISSILETRAINER.New} method:
 --
 --   * @{#MISSILETRAINER.New}: Creates a new MISSILETRAINER object taking the maximum distance to your aircraft to evaluate when a missile needs to be destroyed.
 --
 -- MISSILETRAINER will collect each unit declared in the mission with a skill level "Client" and "Player", and will monitor the missiles shot at those.
 --
--- 1.2) MISSILETRAINER initialization methods:
--- -------------------------------------------
+-- # Initialization:
+-- 
 -- A MISSILETRAINER object will behave differently based on the usage of initialization methods:
 --
 --  * @{#MISSILETRAINER.InitMessagesOnOff}: Sets by default the display of any message to be ON or OFF.
@@ -65,24 +97,8 @@
 --  * @{#MISSILETRAINER.InitRangeOnOff}: Sets by default the display of range information of missiles ON of OFF.
 --  * @{#MISSILETRAINER.InitBearingOnOff}: Sets by default the display of bearing information of missiles ON of OFF.
 --  * @{#MISSILETRAINER.InitMenusOnOff}: Allows to configure the options through the radio menu.
---
--- ===
 -- 
--- CREDITS
--- ===
--- **Stuka (Danny)** Who you can search on the Eagle Dynamics Forums.
--- Working together with Danny has resulted in the MISSILETRAINER class. 
--- Danny has shared his ideas and together we made a design. 
--- Together with the **476 virtual team**, we tested the MISSILETRAINER class, and got much positive feedback!
--- 
--- @module Functional.MissileTrainer
--- @image Missile_Trainer.JPG
-
-
---- The MISSILETRAINER class
--- @type MISSILETRAINER
--- @field Core.Set#SET_CLIENT DBClients
--- @extends Core.Base#BASE
+-- @field #MISSILETRAINER 
 MISSILETRAINER = {
   ClassName = "MISSILETRAINER",
   TrackingMissiles = {},

Moose Development/Moose/Functional/Movement.lua

@@ -1,4 +1,4 @@
---- **Functional** -- Limit the MOVEMENT of simulaneous moving ground vehicles.
+--- **Functional** -- Limit the movement of simulaneous moving ground vehicles.
 -- 
 -- ===
 --  
@@ -10,9 +10,11 @@
 -- @module Functional.Movement
 -- @image MOOSE.JPG
 
---- the MOVEMENT class
--- @type MOVEMENT
+--- @type MOVEMENT
 -- @extends Core.Base#BASE
+
+---
+--@field #MOVEMENT
 MOVEMENT = {
 	ClassName = "MOVEMENT",
 }

Moose Development/Moose/Functional/PseudoATC.lua

@@ -1,4 +1,4 @@
---- **Functional** - (R2.4) Rudimentary ATC.
+--- **Functional** - Rudimentary ATC.
 --  
 -- ![Banner Image](..\Presentations\PSEUDOATC\PSEUDOATC_Main.jpg)
 -- 
@@ -8,7 +8,7 @@
 -- 
 -- In particular, a menu entry "Pseudo ATC" is created in the "F10 Other..." radiomenu.
 -- 
--- ## Features
+-- ## Features:
 -- 
 -- * Weather report at nearby airbases and mission waypoints.
 -- * Report absolute bearing and range to nearest airports and mission waypoints.
@@ -20,12 +20,6 @@
 --  
 -- ====
 -- 
--- # Demo Missions
---
--- ### [MOOSE - ALL Demo Missions](https://github.com/FlightControl-Master/MOOSE_MISSIONS)
--- 
--- ====
--- 
 -- # YouTube Channel
 -- 
 -- ### [MOOSE YouTube Channel](https://www.youtube.com/channel/UCjrA9j5LQoWsG4SpS8i79Qg)

Moose Development/Moose/Functional/RAT.lua

@@ -1,33 +1,31 @@
---- **Functional** - (R2.2) - Create random airtraffic in your missions.
+--- **Functional** - Create random airtraffic in your missions.
 -- 
 -- ===
 -- 
--- The aim of the RAT class is to fill the empty DCS world with randomized air traffic and bring more life to your airports.
--- 
--- In particular, it is designed to spawn AI air units at random airports. These units will be assigned a random flight path to another random airport on the map.
--- 
+-- The aim of the RAT class is to fill the empty DCS world with randomized air traffic and bring more life to your airports.  
+-- In particular, it is designed to spawn AI air units at random airports. These units will be assigned a random flight path to another random airport on the map.  
 -- Even the mission designer will not know where aircraft will be spawned and which route they follow.
 -- 
--- ## Features
+-- ## Features:
 -- 
---  * Very simple interface. Just one unit and two lines of Lua code needed to fill your map.
---  * High degree of randomization. Aircraft will spawn at random airports, have random routes and random destinations.
---  * Specific departure and/or destination airports can be chosen.
---  * Departure and destination airports can be restricted by coalition.
---  * Planes and helicopters supported. Helicopters can also be send to FARPs and ships.
---  * Units can also be spawned in air within pre-defined zones of the map.
---  * Aircraft will be removed when they arrive at their destination (or get stuck on the ground).
---  * When a unit is removed a new unit with a different flight plan is respawned.
---  * Aircraft can report their status during the route.
---  * All of the above can be customized by the user if necessary.
---  * All current (Caucasus, Nevada, Normandy, Persian Gulf) and future maps are supported.
+--   * Very simple interface. Just one unit and two lines of Lua code needed to fill your map.
+--   * High degree of randomization. Aircraft will spawn at random airports, have random routes and random destinations.
+--   * Specific departure and/or destination airports can be chosen.
+--   * Departure and destination airports can be restricted by coalition.
+--   * Planes and helicopters supported. Helicopters can also be send to FARPs and ships.
+--   * Units can also be spawned in air within pre-defined zones of the map.
+--   * Aircraft will be removed when they arrive at their destination (or get stuck on the ground).
+--   * When a unit is removed a new unit with a different flight plan is respawned.
+--   * Aircraft can report their status during the route.
+--   * All of the above can be customized by the user if necessary.
+--   * All current (Caucasus, Nevada, Normandy, Persian Gulf) and future maps are supported.
 --  
---  The RAT class creates an entry in the F10 radio menu which allows to
+-- The RAT class creates an entry in the F10 radio menu which allows to:
 --  
---  * Create new groups on-the-fly, i.e. at run time within the mission,
---  * Destroy specific groups (e.g. if they get stuck or damaged and block a runway),
---  * Request the status of all RAT aircraft or individual groups,
---  * Place markers at waypoints on the F10 map for each group.
+--   * Create new groups on-the-fly, i.e. at run time within the mission,
+--   * Destroy specific groups (e.g. if they get stuck or damaged and block a runway),
+--   * Request the status of all RAT aircraft or individual groups,
+--   * Place markers at waypoints on the F10 map for each group.
 -- 
 -- Note that by its very nature, this class is suited best for civil or transport aircraft. However, it also works perfectly fine for military aircraft of any kind.
 -- 
@@ -35,10 +33,9 @@
 -- 
 -- ===
 -- 
--- # Demo Missions
+-- ## Missions:
 --
--- ### [MOOSE - ALL Demo Missions](https://github.com/FlightControl-Master/MOOSE_MISSIONS)
--- ### [MOOSE - RAT Demo Missions](https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/master/RAT%20-%20Random%20Air%20Traffic)
+-- ### [RAT - Random Air Traffic](https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/master/RAT%20-%20Random%20Air%20Traffic)
 -- 
 -- ===
 -- 
@@ -219,6 +216,44 @@
 -- Hence, the default flight plan for a RAT aircraft will be: Fly from airport A to B, get respawned at C and fly to D, get respawned at E and fly to F, ...
 -- This ensures that you always have a constant number of AI aircraft on your map.
 -- 
+-- ## Parking Problems
+-- 
+-- One big issue in DCS is that not all aircraft can be spawned on every airport or airbase. In particular, bigger aircraft might not have a valid parking spot at smaller airports and 
+-- airstripes. This can lead to multiple problems in DCS.
+-- 
+-- * Landing: When an aircraft tries to land at an airport where it does not have a valid parking spot, it is immidiately despawned the moment its wheels touch the runway, i.e.
+-- when a landing event is triggered. This leads to the loss of the RAT aircraft. On possible way to circumvent the this problem is to let another RAT aircraft spawn at landing
+-- and not when it shuts down its engines. See the @{RAT.RespawnAfterLanding}() function.
+-- * Spawning: When a big aircraft is dynamically spawned on a small airbase a few things can go wrong. For example, it could be spawned at a parking spot with a shelter.
+-- Or it could be damaged by a scenery object when it is taxiing out to the runway, or it could overlap with other aircraft on parking spots near by.
+-- 
+-- You can check yourself if an aircraft has a valid parking spot at an airbase by dragging its group on the airport in the mission editor and set it to start from ramp.
+-- If it stays at the airport, it has a valid parking spot, if it jumps to another airport, it does not have a valid parking spot on that airbase.
+-- 
+-- ### Setting the Terminal Type
+-- Each parking spot has a specific type depending on its size or if a helicopter spot or a shelter etc. The classification is not perfect but it is the best we have.
+-- If you encounter problems described above, you can request a specific terminal type for the RAT aircraft. This can be done by the @{#RAT.SetTerminalType}(*terminaltype*)
+-- function. The parameter *terminaltype* can be set as follows
+-- 
+-- * AIRBASE.TerminalType.HelicopterOnly: Special spots for Helicopers.
+-- * AIRBASE.TerminalType.Shelter: Hardened Air Shelter. Currently only on Caucaus map.
+-- * AIRBASE.TerminalType.OpenMed: Open/Shelter air airplane only.
+-- * AIRBASE.TerminalType.OpenBig: Open air spawn points. Generally larger but does not guarantee large aircraft are capable of spawning there.
+-- * AIRBASE.TerminalType.OpenMedOrBig: Combines OpenMed and OpenBig spots.
+-- * AIRBASE.TerminalType.HelicopterUnsable: Combines HelicopterOnly, OpenMed and OpenBig.
+-- * AIRBASE.TerminalType.FighterAircraft: Combines Shelter, OpenMed and OpenBig spots. So effectively all spots usable by fixed wing aircraft.
+-- 
+-- So for example
+--      c17=RAT:New("C-17")
+--      c17:SetTerminalType(AIRBASE.TerminalType.OpenBig)
+--      c17:Spawn(5)
+--      
+-- This would randomly spawn five C-17s but only on airports which have big open air parking spots. Note that also only destination airports are allowed
+-- which do have this type of parking spot. This should ensure that the aircraft is able to land at the destination without beeing despawned immidiately.
+-- 
+-- Also, the aircraft are spawned only on the requested parking spot types and not on any other type. If no parking spot of this type is availabe at the
+-- moment of spawning, the group is automatically spawned in air above the selected airport.
+-- 
 -- ## Examples
 -- 
 -- Here are a few examples, how you can modify the default settings of RAT class objects.
@@ -511,7 +546,7 @@ RAT.id="RAT | "
 --- RAT version.
 -- @list version
 RAT.version={
-  version = "2.3.2",
+  version = "2.3.4",
   print = true,
 }
 
@@ -983,11 +1018,11 @@ function RAT:SetCoalitionAircraft(color)
 end
 
 --- Set country of RAT group.
--- See https://wiki.hoggitworld.com/view/DCS_enum_country
+-- See [DCS_enum_country](https://wiki.hoggitworld.com/view/DCS_enum_country).
 -- 
 -- This overrules the coalition settings. So if you want your group to be of a specific coalition, you have to set a country that is part of that coalition.
 -- @param #RAT self
--- @param #DCS.country.id id DCS country enumerator ID. For example country.id.USA or country.id.RUSSIA.
+-- @param DCS#country.id id DCS country enumerator ID. For example country.id.USA or country.id.RUSSIA.
 -- @return #RAT RAT self object.
 function RAT:SetCountry(id)
   self:F2(id)
@@ -995,10 +1030,17 @@ function RAT:SetCountry(id)
   return self
 end
 
---- Set the terminal type the aircraft use when spawning at an airbase. Cf. https://wiki.hoggitworld.com/view/DCS_func_getParking
+--- Set the terminal type the aircraft use when spawning at an airbase. See [DCS_func_getParking](https://wiki.hoggitworld.com/view/DCS_func_getParking).
+-- Note that some additional terminal types have been introduced. Check @{Wrapper.Airbase#AIRBASE} class for details.
+-- Also note that only airports which have this kind of terminal are possible departures and/or destinations.
 -- @param #RAT self
 -- @param Wrapper.Airbase#AIRBASE.TerminalType termtype Type of terminal. Use enumerator AIRBASE.TerminalType.XXX.
 -- @return #RAT RAT self object.
+-- 
+-- @usage
+-- c17=RAT:New("C-17 BIG Plane")
+-- c17:SetTerminalType(AIRBASE.TerminalType.OpenBig) -- Only very big parking spots are used.
+-- c17:Spawn(5)
 function RAT:SetTerminalType(termtype)
   self:F2(termtype)
   self.termtype=termtype
@@ -2019,8 +2061,9 @@ end
 -- @param #table _waypoint First waypoint to be used (for continue journey, commute, etc).
 -- @param Core.Point#COORDINATE _lastpos (Optional) Position where the aircraft will be spawned.
 -- @param #number _nrespawn Number of already performed respawn attempts (e.g. spawning on runway bug).
+-- @param #table parkingdata Explicitly specify the parking spots when spawning at an airport.
 -- @return #number Spawn index.
-function RAT:_SpawnWithRoute(_departure, _destination, _takeoff, _landing, _livery, _waypoint, _lastpos, _nrespawn)
+function RAT:_SpawnWithRoute(_departure, _destination, _takeoff, _landing, _livery, _waypoint, _lastpos, _nrespawn, parkingdata)
   self:F({rat=RAT.id, departure=_departure, destination=_destination, takeoff=_takeoff, landing=_landing, livery=_livery, waypoint=_waypoint, lastpos=_lastpos, nrespawn=_nrespawn})
 
   -- Set takeoff type.
@@ -2070,7 +2113,7 @@ function RAT:_SpawnWithRoute(_departure, _destination, _takeoff, _landing, _live
   end
   
   -- Modify the spawn template to follow the flight plan.
-  local successful=self:_ModifySpawnTemplate(waypoints, livery, _lastpos, departure, takeoff)
+  local successful=self:_ModifySpawnTemplate(waypoints, livery, _lastpos, departure, takeoff, parkingdata)
   if not successful then
     return nil
   end
@@ -2413,7 +2456,7 @@ function RAT:_SetRoute(takeoff, landing, _departure, _destination, _waypoint)
   local VxCruiseMin = math.min(VxCruiseMax*0.70, 166)
   
   -- Cruise speed (randomized). Expectation value at midpoint between min and max.
-  local VxCruise = self:_Random_Gaussian((VxCruiseMax-VxCruiseMin)/2+VxCruiseMin, (VxCruiseMax-VxCruiseMax)/4, VxCruiseMin, VxCruiseMax)
+  local VxCruise = UTILS.RandomGaussian((VxCruiseMax-VxCruiseMin)/2+VxCruiseMin, (VxCruiseMax-VxCruiseMax)/4, VxCruiseMin, VxCruiseMax)
   
   -- Climb speed 90% ov Vmax but max 720 km/h.
   local VxClimb = math.min(self.aircraft.Vmax*0.90, 200)
@@ -2771,7 +2814,7 @@ function RAT:_SetRoute(takeoff, landing, _departure, _destination, _waypoint)
   end
     
   -- Set cruise altitude. Selected from Gaussian distribution but limited to FLmin and FLmax.
-  local FLcruise=self:_Random_Gaussian(FLcruise_expect, math.abs(FLmax-FLmin)/4, FLmin, FLmax)
+  local FLcruise=UTILS.RandomGaussian(FLcruise_expect, math.abs(FLmax-FLmin)/4, FLmin, FLmax)
     
   -- Overrule setting if user specified a flight level explicitly.
   if self.FLuser then
@@ -3010,14 +3053,27 @@ function RAT:_PickDeparture(takeoff)
   if self.random_departure then
   
     -- Airports of friendly coalitions.
-    for _,airport in pairs(self.airports) do
+    for _,_airport in pairs(self.airports) do
     
+      local airport=_airport --Wrapper.Airbase#AIRBASE
+      
       local name=airport:GetName()
       if not self:_Excluded(name) then
         if takeoff==RAT.wp.air then
+        
           table.insert(departures, airport:GetZone())  -- insert zone object.
+          
         else
-          table.insert(departures, airport)            -- insert airport object.
+        
+          -- Check if airbase has the right terminals.
+          local nspots=1
+          if self.termtype~=nil then
+            nspots=airport:GetParkingSpotsNumber(self.termtype)
+          end
+          
+          if nspots>0 then
+            table.insert(departures, airport)            -- insert airport object.
+          end
         end
       end
       
@@ -3034,6 +3090,14 @@ function RAT:_PickDeparture(takeoff)
           dep=AIRBASE:FindByName(name):GetZone()
         else
           dep=AIRBASE:FindByName(name)
+          -- Check if the airport has a valid parking spot
+          if self.termtype~=nil and dep~=nil then
+            local _dep=dep --Wrapper.Airbase#AIRBASE
+            local nspots=_dep:GetParkingSpotsNumber(self.termtype)
+            if nspots==0 then
+              dep=nil
+            end
+          end
         end
       elseif self:_ZoneExists(name) then
         if takeoff==RAT.wp.air then
@@ -3098,7 +3162,8 @@ function RAT:_PickDestination(departure, q, minrange, maxrange, random, landing)
   if random then
   
     -- Airports of friendly coalitions.
-    for _,airport in pairs(self.airports) do
+    for _,_airport in pairs(self.airports) do
+      local airport=_airport --Wrapper.Airbase#AIRBASE
       local name=airport:GetName()
       if self:_IsFriendly(name) and not self:_Excluded(name) and name~=departure:GetName() then
       
@@ -3110,7 +3175,14 @@ function RAT:_PickDestination(departure, q, minrange, maxrange, random, landing)
           if landing==RAT.wp.air then
             table.insert(destinations, airport:GetZone())  -- insert zone object.
           else
-            table.insert(destinations, airport)            -- insert airport object.
+            -- Check if the requested terminal type is available.
+            local nspot=1
+            if self.termtype then
+              nspot=airport:GetParkingSpotsNumber(self.termtype)
+            end
+            if nspot>0 then
+              table.insert(destinations, airport)            -- insert airport object.
+            end
           end
         end
       end
@@ -3130,6 +3202,14 @@ function RAT:_PickDestination(departure, q, minrange, maxrange, random, landing)
             dest=AIRBASE:FindByName(name):GetZone()
           else
             dest=AIRBASE:FindByName(name)
+            -- Check if the requested terminal type is available.
+            local nspot=1
+            if self.termtype then
+              nspot=dest:GetParkingSpotsNumber(self.termtype)
+            end
+            if nspot==0 then
+              dest=nil
+            end
           end
         elseif self:_ZoneExists(name) then
           if landing==RAT.wp.air then
@@ -3287,16 +3367,31 @@ function RAT:_GetAirportsOfMap()
   end
 end
 
---- Get all "friendly" airports of the current map.
+--- Get all "friendly" airports of the current map. Fills the self.airports{} table.
 -- @param #RAT self
 function RAT:_GetAirportsOfCoalition()
   for _,coalition in pairs(self.ctable) do
-    for _,airport in pairs(self.airports_map) do
+    for _,_airport in pairs(self.airports_map) do
+      local airport=_airport --Wrapper.Airbase#AIRBASE
+      local category=airport:GetDesc().category
       if airport:GetCoalition()==coalition then
         -- Planes cannot land on FARPs.
-        local condition1=self.category==RAT.cat.plane and airport:GetTypeName()=="FARP"
+        --local condition1=self.category==RAT.cat.plane and airport:GetTypeName()=="FARP"
+        local condition1=self.category==RAT.cat.plane and category==Airbase.Category.HELIPAD
         -- Planes cannot land on ships.
-        local condition2=self.category==RAT.cat.plane and airport:GetCategory()==1
+        --local condition2=self.category==RAT.cat.plane and airport:GetCategory()==1
+        local condition2=self.category==RAT.cat.plane and category==Airbase.Category.SHIP
+        
+        -- Check that airport has the requested terminal types.
+        -- NOT good here because we would also not allow any airport zones!
+        --[[
+        local nspots=1
+        if self.termtype then
+          nspots=airport:GetParkingSpotsNumber(self.termtype)
+        end
+        local condition3 = nspots==0
+        ]]
+        
         if not (condition1 or condition2) then
           table.insert(self.airports, airport)
         end
@@ -3305,8 +3400,8 @@ function RAT:_GetAirportsOfCoalition()
   end
     
   if #self.airports==0 then
-    local text="ERROR! No possible departure/destination airports found."
-    MESSAGE:New(text, 30):ToAll()
+    local text=string.format("No possible departure/destination airports found for RAT %s.", tostring(self.alias))
+    MESSAGE:New(text, 10):ToAll()
     self:E(RAT.id..text)
   end
 end
@@ -4916,38 +5011,6 @@ function RAT:_Randomize(value, fac, lower, upper)
   return r
 end
 
---- Generate Gaussian pseudo-random numbers.
--- @param #number x0 Expectation value of distribution.
--- @param #number sigma (Optional) Standard deviation. Default 10.
--- @param #number xmin (Optional) Lower cut-off value.
--- @param #number xmax (Optional) Upper cut-off value.
--- @return #number Gaussian random number.
-function RAT:_Random_Gaussian(x0, sigma, xmin, xmax)
-
-  -- Standard deviation. Default 10 if not given.
-  sigma=sigma or 10
-    
-  local r
-  local gotit=false
-  local i=0
-  while not gotit do
-  
-    -- Uniform numbers in [0,1). We need two.
-    local x1=math.random()
-    local x2=math.random()
-  
-    -- Transform to Gaussian exp(-(x-x0)²/(2*sigma²).
-    r = math.sqrt(-2*sigma*sigma * math.log(x1)) * math.cos(2*math.pi * x2) + x0
-    
-    i=i+1
-    if (r>=xmin and r<=xmax) or i>100 then
-      gotit=true
-    end
-  end
-  
-  return r
-
-end
 
 --- Place markers of the waypoints. Note we assume a very specific number and type of waypoints here.
 -- @param #RAT self
@@ -5006,9 +5069,10 @@ end
 -- @param Core.Point#COORDINATE spawnplace (Optional) Place where spawning should happen. If not present, first waypoint is taken.
 -- @param Wrapper.Airbase#AIRBASE departure Departure airbase or zone.
 -- @param #number takeoff Takeoff type.
+-- @param #table parkingdata Parking data, i.e. parking spot coordinates and terminal ids for all units of the group.
 -- @return #boolean True if modification was successful or nil if not, e.g. when no parking space was found and spawn in air is disabled.
-function RAT:_ModifySpawnTemplate(waypoints, livery, spawnplace, departure, takeoff)
-  self:F2({waypoints=waypoints, livery=livery, spawnplace=spawnplace, departure=departure, takeoff=takeoff})
+function RAT:_ModifySpawnTemplate(waypoints, livery, spawnplace, departure, takeoff, parkingdata)
+  self:F2({waypoints=waypoints, livery=livery, spawnplace=spawnplace, departure=departure, takeoff=takeoff, parking=parkingdata})
 
   -- The 3D vector of the first waypoint, i.e. where we actually spawn the template group.
   local PointVec3 = COORDINATE:New(waypoints[1].x, waypoints[1].alt, waypoints[1].y)
@@ -5096,6 +5160,10 @@ function RAT:_ModifySpawnTemplate(waypoints, livery, spawnplace, departure, take
           self:T(RAT.id..string.format("Group %s is spawned on farp/ship/runway %s.", self.alias, departure:GetName()))
           nfree=departure:GetFreeParkingSpotsNumber(termtype, true)
           spots=departure:GetFreeParkingSpotsTable(termtype, true)
+        elseif parkingdata~=nil then
+          -- Parking data explicitly set by user as input parameter.
+          nfree=#parkingdata
+          spots=parkingdata
         else
           -- Helo is spawned.
           if self.category==RAT.cat.heli then
@@ -5254,7 +5322,7 @@ function RAT:_ModifySpawnTemplate(waypoints, livery, spawnplace, departure, take
                
         if spawnonground then
           
-          -- Shíps and FARPS seem to have a build in queue.
+          -- Sh<EFBFBD>ps and FARPS seem to have a build in queue.
           if spawnonship or spawnonfarp or spawnonrunway or automatic then
             self:T(RAT.id..string.format("RAT group %s spawning at farp, ship or runway %s.", self.alias, departure:GetName()))
 

Moose Development/Moose/Functional/Range.lua

@@ -1,4 +1,4 @@
---- **Functional** - (R2.3) - Range Practice.
+--- **Functional** - Range Practice.
 --  
 -- ===
 -- 
@@ -9,30 +9,22 @@
 -- 
 -- [476th - Air Weapons Range Objects mod](http://www.476vfightergroup.com/downloads.php?do=file&id=287) is highly recommended for this class.
 -- 
--- ## Features
+-- ## Features:
 --
--- * Impact points of bombs, rockets and missils are recorded and distance to closest range target is measured and reported to the player.
--- * Number of hits on strafing passes are counted and reported. Also the percentage of hits w.r.t fired shots is evaluated. 
--- * Results of all bombing and strafing runs are stored and top 10 results can be displayed. 
--- * Range targets can be marked by smoke.
--- * Range can be illuminated by illumination bombs for night practices.
--- * Bomb, rocket and missile impact points can be marked by smoke.
--- * Direct hits on targets can trigger flares.
--- * Smoke and flare colors can be adjusted for each player via radio menu.
--- * Range information and weather report at the range can be reported via radio menu.
+--   * Impact points of bombs, rockets and missils are recorded and distance to closest range target is measured and reported to the player.
+--   * Number of hits on strafing passes are counted and reported. Also the percentage of hits w.r.t fired shots is evaluated. 
+--   * Results of all bombing and strafing runs are stored and top 10 results can be displayed. 
+--   * Range targets can be marked by smoke.
+--   * Range can be illuminated by illumination bombs for night practices.
+--   * Bomb, rocket and missile impact points can be marked by smoke.
+--   * Direct hits on targets can trigger flares.
+--   * Smoke and flare colors can be adjusted for each player via radio menu.
+--   * Range information and weather report at the range can be reported via radio menu.
 -- 
 -- More information and examples can be found below.
 -- 
 -- ===
 -- 
--- # Demo Missions
---
--- ### [MOOSE - ALL Demo Missions](https://github.com/FlightControl-Master/MOOSE_MISSIONS)
--- 
--- ===
--- 
--- # YouTube Channel
---
 -- ### [MOOSE YouTube Channel](https://www.youtube.com/channel/UCjrA9j5LQoWsG4SpS8i79Qg) 
 -- ### [MOOSE - On the Range - Demonstration Video](https://www.youtube.com/watch?v=kIXcxNB9_3M)
 -- 
@@ -68,6 +60,8 @@
 -- @field #number dtBombtrack Time step [sec] used for tracking released bomb/rocket positions. Default 0.005 seconds.
 -- @field #number BombtrackThreshold Bombs/rockets/missiles are only tracked if player-range distance is smaller than this threashold [m]. Default 25000 m.
 -- @field #number Tmsg Time [sec] messages to players are displayed. Default 30 sec.
+-- @field #string examinergroupname Name of the examiner group which should get all messages.
+-- @field #boolean examinerexclusive If true, only the examiner gets messages. If false, clients and examiner get messages.
 -- @field #number strafemaxalt Maximum altitude above ground for registering for a strafe run. Default is 914 m = 3000 ft. 
 -- @field #number ndisplayresult Number of (player) results that a displayed. Default is 10.
 -- @field Utilities.Utils#SMOKECOLOR BombSmokeColor Color id used for smoking bomb targets.
@@ -102,7 +96,7 @@
 -- ## Strafe Pits
 -- Each strafe pit can consist of multiple targets. Often one findes two or three strafe targets next to each other.
 -- 
--- A strafe pit can be added to the range by the @{#RANGE.AddStrafepit}(*targetnames, boxlength, boxwidth, heading, inverseheading, goodpass, foulline*) function.
+-- A strafe pit can be added to the range by the @{#RANGE.AddStrafePit}(*targetnames, boxlength, boxwidth, heading, inverseheading, goodpass, foulline*) function.
 -- 
 -- * The first parameter *targetnames* defines the target or targets. This has to be given as a lua table which contains the names of @{Wrapper.Unit} or @{Static} objects defined in the mission editor. 
 -- * In order to perform a valid pass on the strafe pit, the pilot has to begin his run from the correct direction. Therefore, an "approach box" is defined in front
@@ -234,6 +228,8 @@ RANGE={
   dtBombtrack=0.005,
   BombtrackThreshold=25000,
   Tmsg=30,
+  examinergroupname=nil,
+  examinerexclusive=nil,
   strafemaxalt=914,
   ndisplayresult=10,
   BombSmokeColor=SMOKECOLOR.Red,
@@ -279,8 +275,8 @@ RANGE.MenuF10={}
 RANGE.id="RANGE | "
 
 --- Range script version.
--- @field #number version
-RANGE.version="1.2.0"
+-- @field #string version
+RANGE.version="1.2.1"
 
 --TODO list:
 --TODO: Add custom weapons, which can be specified by the user.
@@ -434,6 +430,15 @@ function RANGE:SetMessageTimeDuration(time)
   self.Tmsg=time or RANGE.Defaults.Tmsg
 end
 
+--- Set messages to examiner. The examiner will receive messages from all clients.
+-- @param #RANGE self
+-- @param #string examinergroupname Name of the group of the examiner.
+-- @param #boolean exclusively If true, messages are send exclusively to the examiner, i.e. not to the clients.
+function RANGE:SetMessageToExaminer(examinergroupname, exclusively)
+  self.examinergroupname=examinergroupname
+  self.examinerexclusive=exclusively
+end
+
 --- Set max number of player results that are displayed.
 -- @param #RANGE self
 -- @param #number nmax Number of results. Default is 10.
@@ -2119,13 +2124,24 @@ function RANGE:_DisplayMessageToGroup(_unit, _text, _time, _clear)
   -- Group ID.
   local _gid=_unit:GetGroup():GetID()
   
-  if _gid then
+  if _gid and not self.examinerexclusive then
     if _clear == true then
       trigger.action.outTextForGroup(_gid, _text, _time, _clear)
     else
       trigger.action.outTextForGroup(_gid, _text, _time)
     end
   end
+
+  if self.examinergroupname~=nil then
+    local _examinerid=GROUP:FindByName(self.examinergroupname):GetID()
+    if _examinerid then
+      if _clear == true then
+        trigger.action.outTextForGroup(_examinerid, _text, _time, _clear)
+      else
+        trigger.action.outTextForGroup(_examinerid, _text, _time)
+      end
+    end  
+  end
   
 end
 

Moose Development/Moose/Functional/Scoring.lua

@@ -1,4 +1,25 @@
---- **Functional** -- (R2.0) - Administer the scoring of player achievements, and create a CSV file logging the scoring events for use at team or squadron websites.
+--- **Functional** - Administer the scoring of player achievements, and create a CSV file logging the scoring events for use at team or squadron websites.
+-- 
+-- ===
+-- 
+-- ## Features:
+-- 
+--   * Set the scoring scales based on threat level.
+--   * Positive scores and negative scores.
+--   * A contribution model to score achievements.
+--   * Score goals.
+--   * Score specific achievements.
+--   * Score the hits and destroys of units.
+--   * Score the hits and destroys of statics.
+--   * Score the hits and destroys of scenery.
+--   * Log scores into a CSV file.
+--   * Connect to a remote server using JSON and IP.
+--   
+-- ===
+-- 
+-- ## Missions:
+-- 
+-- [SCO - Scoring](https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/master/SCO%20-%20Scoring)
 -- 
 -- ===
 -- 
@@ -52,9 +73,34 @@
 -- Use the radio menu F10 to consult the scores while running the mission. 
 -- Scores can be reported for your user, or an overall score can be reported of all players currently active in the mission.
 -- 
--- # 1) @{Functional.Scoring#SCORING} class, extends @{Core.Base#BASE}
+-- ===
 -- 
--- ## 1.1) Set the destroy score or penalty scale
+-- ### Authors: **FlightControl**
+-- 
+-- ### Contributions:
+-- 
+--   * **Wingthor (TAW)**: Testing & Advice.
+--   * **Dutch-Baron (TAW)**: Testing & Advice.
+--   * **[Whisper](http://forums.eagle.ru/member.php?u=3829): Testing and Advice.
+-- 
+-- ===       
+-- 
+-- @module Functional.Scoring
+-- @image Scoring.JPG
+
+
+--- @type SCORING
+-- @field Players A collection of the current players that have joined the game.
+-- @extends Core.Base#BASE
+
+--- SCORING class
+-- 
+-- # Constructor:
+-- 
+--      local Scoring = SCORING:New( "Scoring File" )
+--       
+-- 
+-- # Set the destroy score or penalty scale:
 -- 
 -- Score scales can be set for scores granted when enemies or friendlies are destroyed.
 -- Use the method @{#SCORING.SetScaleDestroyScore}() to set the scale of enemy destroys (positive destroys). 
@@ -67,7 +113,7 @@
 -- The above sets the scale for valid scores to 10. So scores will be given in a scale from 0 to 10.
 -- The penalties will be given in a scale from 0 to 40.
 -- 
--- ## 1.2) Define special targets that will give extra scores.
+-- # Define special targets that will give extra scores:
 -- 
 -- Special targets can be set that will give extra scores to the players when these are destroyed.
 -- Use the methods @{#SCORING.AddUnitScore}() and @{#SCORING.RemoveUnitScore}() to specify a special additional score for a specific @{Wrapper.Unit}s.  
@@ -84,7 +130,7 @@
 -- 
 --      Scoring:RemoveUnitScore( UNIT:FindByName( "Unit #001" ) )
 -- 
--- ## 1.3) Define destruction zones that will give extra scores.
+-- # Define destruction zones that will give extra scores:
 -- 
 -- Define zones of destruction. Any object destroyed within the zone of the given category will give extra points.
 -- Use the method @{#SCORING.AddZoneScore}() to add a @{Zone} for additional scoring.  
@@ -94,12 +140,12 @@
 -- The other implementation could be to designate a scenery target (a building) in the mission editor surrounded by a @{Zone}, 
 -- just large enough around that building.
 -- 
--- ## 1.4) Add extra Goal scores upon an event or a condition.
+-- # Add extra Goal scores upon an event or a condition:
 -- 
 -- A mission has goals and achievements. The scoring system provides an API to set additional scores when a goal or achievement event happens.
 -- Use the method @{#SCORING.AddGoalScore}() to add a score for a Player at any time in your mission.
 -- 
--- ## 1.5) (Decommissioned) Configure fratricide level.
+-- # (Decommissioned) Configure fratricide level.
 -- 
 -- **This functionality is decomissioned until the DCS bug concerning Unit:destroy() not being functional in multi player for player units has been fixed by ED**.
 -- 
@@ -107,13 +153,13 @@
 -- Use the method @{#SCORING.SetFratricide}() to define the level when a player gets kicked.  
 -- By default, the fratricide level is the default penalty mutiplier * 2 for the penalty score.
 -- 
--- ## 1.6) Penalty score when a player changes the coalition.
+-- # Penalty score when a player changes the coalition.
 -- 
 -- When a player changes the coalition, he can receive a penalty score.
 -- Use the method @{#SCORING.SetCoalitionChangePenalty}() to define the penalty when a player changes coalition.
 -- By default, the penalty for changing coalition is the default penalty scale.  
 -- 
--- ## 1.8) Define output CSV files.
+-- # Define output CSV files.
 -- 
 -- The CSV file is given the name of the string given in the @{#SCORING.New}{} constructor, followed by the .csv extension.
 -- The file is incrementally saved in the **<User>\\Saved Games\\DCS\\Logs** folder, and has a time stamp indicating each mission run.
@@ -150,7 +196,7 @@
 -- The MOOSE designer cannot take any responsibility of any damage inflicted as a result of the de-sanitization.
 -- That being said, I hope that the SCORING class provides you with a great add-on to score your squad mates achievements.
 -- 
--- ## 1.9) Configure messages.
+-- # Configure messages.
 -- 
 -- When players hit or destroy targets, messages are sent.
 -- Various methods exist to configure:
@@ -158,7 +204,7 @@
 --   * Which messages are sent upon the event.
 --   * Which audience receives the message.
 -- 
--- ### 1.9.1) Configure the messages sent upon the event.
+-- ## Configure the messages sent upon the event.
 -- 
 -- Use the following methods to configure when to send messages. By default, all messages are sent.
 -- 
@@ -167,49 +213,16 @@
 --   * @{#SCORING.SetMessagesAddon}(): Configure to send messages for additional score, after a target has been destroyed.
 --   * @{#SCORING.SetMessagesZone}(): Configure to send messages for additional score, after a target has been destroyed within a given zone.
 --   
--- ### 1.9.2) Configure the audience of the messages.
+-- ## Configure the audience of the messages.
 -- 
 -- Use the following methods to configure the audience of the messages. By default, the messages are sent to all players in the mission.
 -- 
 --   * @{#SCORING.SetMessagesToAll}(): Configure to send messages to all players.
 --   * @{#SCORING.SetMessagesToCoalition}(): Configure to send messages to only those players within the same coalition as the player.
--- 
---   
--- ===
---
--- # **API CHANGE HISTORY**
---
--- The underlying change log documents the API changes. Please read this carefully. The following notation is used:
---
---   * **Added** parts are expressed in bold type face.
---   * _Removed_ parts are expressed in italic type face.
---
--- Hereby the change log:
---
--- 2017-02-26: Initial class and API.
 --
 -- ===
---
--- # **AUTHORS and CONTRIBUTIONS**
---
--- ### Contributions:
---
---   * **Wingthor (TAW)**: Testing & Advice.
---   * **Dutch-Baron (TAW)**: Testing & Advice.
---   * **[Whisper](http://forums.eagle.ru/member.php?u=3829): Testing and Advice.
---        
--- ### Authors:
---
---   * **FlightControl**: Concept, Design & Programming.
 -- 
--- @module Functional.Scoring
--- @image Scoring.JPG
-
-
---- The Scoring class
--- @type SCORING
--- @field Players A collection of the current players that have joined the game.
--- @extends Core.Base#BASE
+-- @field #SCORING
 SCORING = {
   ClassName = "SCORING",
   ClassID = 0,
@@ -236,8 +249,10 @@ local _SCORINGCategory =
 -- @param #string GameName The name of the game. This name is also logged in the CSV score file.
 -- @return #SCORING self
 -- @usage
+-- 
 -- -- Define a new scoring object for the mission Gori Valley.
 -- ScoringObject = SCORING:New( "Gori Valley" )
+-- 
 function SCORING:New( GameName )
 
   -- Inherits from BASE

Moose Development/Moose/Functional/Sead.lua

@@ -1,13 +1,41 @@
---- **Functional** -- Provides defensive behaviour to a set of SAM sites within a running Mission.
+--- **Functional** -- Make SAM sites execute evasive and defensive behaviour when being fired upon.
+-- 
+-- ===
+-- 
+-- ## Features:
+-- 
+--   * When SAM sites are being fired upon, the SAMs will take evasive action will reposition themselves when possible.
+--   * When SAM sites are being fired upon, the SAMs will take defensive action by shutting down their radars.
+-- 
+-- ===
+-- 
+-- ## Missions:
+-- 
+-- [SEV - SEAD Evasion](https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/master/SEV%20-%20SEAD%20Evasion)
+-- 
+-- ===
+-- 
+-- ### Authors: **FlightControl**
 -- 
 -- ===
 -- 
 -- @module Functional.Sead
 -- @image SEAD.JPG
 
---- The SEAD class
--- @type SEAD
+--- @type SEAD
 -- @extends Core.Base#BASE
+
+--- Make SAM sites execute evasive and defensive behaviour when being fired upon.
+-- 
+-- This class is very easy to use. Just setup a SEAD object by using @{#SEAD.New}() and SAMs will evade and take defensive action when being fired upon.
+-- 
+-- # Constructor:
+-- 
+-- Use the @{#SEAD.New}() constructor to create a new SEAD object.
+-- 
+--       SEAD_RU_SAM_Defenses = SEAD:New( { 'RU SA-6 Kub', 'RU SA-6 Defenses', 'RU MI-26 Troops', 'RU Attack Gori' } )
+-- 
+-- @field #SEAD
 SEAD = {
 	ClassName = "SEAD", 
 	TargetSkill = {

Moose Development/Moose/Functional/Suppression.lua

@@ -1,7 +1,18 @@
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
---- **Functional** - (R2.4) Suppress fire of ground units when they get hit.
+--- **Functional** - Suppress fire of ground units when they get hit.
 -- 
--- ====
+-- ===
+-- 
+-- ## Features:
+-- 
+--   * Hold fire of attacked units when being fired upon.
+--
+-- ===
+-- 
+-- ## Missions:
+--
+-- ## [MOOSE - ALL Demo Missions](https://github.com/FlightControl-Master/MOOSE_MISSIONS)
+-- 
+-- === 
 -- 
 -- When ground units get hit by (suppressive) enemy fire, they will not be able to shoot back for a certain amount of time.
 -- 
@@ -12,12 +23,6 @@
 -- 
 -- ====
 -- 
--- # Demo Missions
---
--- ### [MOOSE - ALL Demo Missions](https://github.com/FlightControl-Master/MOOSE_MISSIONS)
--- 
--- ====
--- 
 -- # YouTube Channel
 -- 
 -- ### [MOOSE YouTube Channel](https://www.youtube.com/channel/UCjrA9j5LQoWsG4SpS8i79Qg)
@@ -28,7 +33,8 @@
 -- 
 -- ### Contributions: [FlightControl](https://forums.eagle.ru/member.php?u=89536)
 -- 
--- ====
+-- ===
+-- 
 -- @module Functional.Suppression
 -- @image Suppression.JPG
 

Moose Development/Moose/Functional/ZoneCaptureCoalition.lua

@@ -1,14 +1,40 @@
---- **Functional** -- (R2.3) Models the process to zone guarding and capturing.
+--- **Functional** -- Models the process to zone guarding and capturing.
 --
 -- ===
 -- 
--- ### [Demo Missions](https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/master/CAZ - Capture Zones)
+-- ## Features:
 -- 
---   - CAZ-000 - Capture Zone: Demonstrates the basic concept of capturing a zone.
+--   * Models the possible state transitions between the Guarded, Attacked, Empty and Captured states.
+--   * A zone has an owning coalition, that means that at a specific point in time, a zone can be owned by the red or blue coalition.
+--   * Provide event handlers to tailor the actions when a zone changes coalition or state.
 -- 
 -- ===
 -- 
--- ### [YouTube Playlist](https://www.youtube.com/watch?v=0m6K6Yxa-os&list=PL7ZUrU4zZUl0qqJsfa8DPvZWDY-OyDumE)
+-- ## Missions:
+-- 
+-- [CAZ - Capture Zones](https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/master/CAZ%20-%20Capture%20Zones)
+-- 
+-- ===
+-- 
+-- # Player Experience
+-- 
+-- ![States](..\Presentations\ZONE_CAPTURE_COALITION\Dia3.JPG)
+--  
+-- The above models the possible state transitions between the **Guarded**, **Attacked**, **Empty** and **Captured** states.  
+-- A zone has an __owning coalition__, that means that at a specific point in time, a zone can be owned by the red or blue coalition.
+--
+-- The Zone can be in the state **Guarded** by the __owning coalition__, which is the coalition that initially occupies the zone with units of its coalition.  
+-- Once units of an other coalition are entering the Zone, the state will change to **Attacked**. As long as these units remain in the zone, the state keeps set to Attacked.  
+-- When all units are destroyed in the Zone, the state will change to **Empty**, which expresses that the Zone is empty, and can be captured.  
+-- When units of the other coalition are in the Zone, and no other units of the owning coalition is in the Zone, the Zone is captured, and its state will change to **Captured**.  
+-- 
+-- The zone needs to be monitored regularly for the presence of units to interprete the correct state transition required.  
+-- This monitoring process MUST be started using the @{#ZONE_CAPTURE_COALITION.Start}() method.  
+-- Otherwise no monitoring will be active and the zone will stay in the current state forever.  
+-- 
+-- ===
+-- 
+-- ## [YouTube Playlist](https://www.youtube.com/watch?v=0m6K6Yxa-os&list=PL7ZUrU4zZUl0qqJsfa8DPvZWDY-OyDumE)
 -- 
 -- ===
 -- 
@@ -29,65 +55,76 @@ do -- ZONE_CAPTURE_COALITION
   --- Models the process to capture a Zone for a Coalition, which is guarded by another Coalition.
   -- This is a powerful concept that allows to create very dynamic missions based on the different state transitions of various zones.
   -- 
-  -- ---
-  --
-  -- ![Banner Image](..\Presentations\ZONE_CAPTURE_COALITION\Dia1.JPG)
-  --
-  -- ---
+  -- ===
   -- 
-  -- # 0. Player Experience
+  -- In order to use ZONE_CAPTURE_COALITION, you need to:
   -- 
-  -- ![States](..\Presentations\ZONE_CAPTURE_COALITION\Dia3.JPG)
-  --  
-  -- The above models the possible state transitions between the **Guarded**, **Attacked**, **Empty** and **Captured** states.
-  -- A zone has an __owning coalition__, that means that at a specific point in time, a zone can be owned by the red or blue coalition.
-  --
-  -- The Zone can be in the state **Guarded** by the __owning coalition__, which is the coalition that initially occupies the zone with units of its coalition.
-  -- Once units of an other coalition are entering the Zone, the state will change to **Attacked**. As long as these units remain in the zone, the state keeps set to Attacked.
-  -- When all units are destroyed in the Zone, the state will change to **Empty**, which expresses that the Zone is empty, and can be captured.
-  -- When units of the other coalition are in the Zone, and no other units of the owning coalition is in the Zone, the Zone is captured, and its state will change to **Captured**.
-  -- 
-  -- The zone needs to be monitored regularly for the presence of units to interprete the correct state transition required.
-  -- This monitoring process MUST be started using the @{#ZONE_CAPTURE_COALITION.Start}() method.
-  -- Otherwise no monitoring will be active and the zone will stay in the current state forever.
-  -- See further in chapter 3.3 for more information about this.
-  -- 
-  -- ## 1. ZONE\_CAPTURE\_COALITION constructor
-  --   
-  --   * @{#ZONE_CAPTURE_COALITION.New}(): Creates a new ZONE\_CAPTURE\_COALITION object.
-  --   
-  -- In order to use ZONE\_CAPTURE\_COALITION, you need to:
-  -- 
-  --   - Create a @{Zone} object from one of the ZONE\_ classes. Note that ZONE\_POLYGON\_ classes are not yet functional. The only functional ZONE\_ classses are those derived from a ZONE\_RADIUS.
+  --   * Create a @{Zone} object from one of the ZONE_ classes.  
+  --     Note that ZONE_POLYGON_ classes are not yet functional.  
+  --     The only functional ZONE_ classses are those derived from a ZONE_RADIUS.
+  --   * Set the state of the zone. Most of the time, Guarded would be the initial state.
+  --   * Start the zone capturing **monitoring process**.  
+  --     This will check the presence of friendly and/or enemy units within the zone and will transition the state of the zone when the tactical situation changed.
+  --     The frequency of the monitoring must not be real-time, a 30 second interval to execute the checks is sufficient. 
   -- 
   -- ![New](..\Presentations\ZONE_CAPTURE_COALITION\Dia5.JPG)
   -- 
-  -- Ensure that during the life cycle of the ZONE\_CAPTURE\_COALITION object, the object keeps alive.
-  -- It is best to declare the object globally within your script.
+  -- ### Important:
   -- 
-  -- ## 2. ZONE\_CAPTURE\_COALITION is a finite state machine (FSM).
+  -- You must start the monitoring process within your code, or there won't be any state transition checks executed.  
+  -- See further the start/stop monitoring process.
+  -- 
+  -- ### Important:
+  -- 
+  -- Ensure that the object containing the ZONE_CAPTURE_COALITION object is persistent.
+  -- Otherwise the garbage collector of lua will remove the object and the monitoring process will stop.
+  -- This will result in your object to be destroyed (removed) from internal memory and there won't be any zone state transitions anymore detected!
+  -- So use the `local` keyword in lua with thought! Most of the time, you can declare your object gobally.
+  -- 
+  -- 
+  -- 
+  -- # Example:
+  -- 
+  --       -- Define a new ZONE object, which is based on the trigger zone `CaptureZone`, which is defined within the mission editor.
+  --       CaptureZone = ZONE:New( "CaptureZone" )
+  --       
+  --       -- Here we create a new ZONE_CAPTURE_COALITION object, using the :New constructor.
+  --       ZoneCaptureCoalition = ZONE_CAPTURE_COALITION:New( CaptureZone, coalition.side.RED )
+  --       
+  --       -- Set the zone to Guarding state.
+  --       ZoneCaptureCoalition:__Guard( 1 )
+  --       
+  --       -- Start the zone monitoring process in 30 seconds and check every 30 seconds.
+  --       ZoneCaptureCoalition:Start( 30, 30 ) 
+  --   
+  -- 
+  -- # Constructor:
+  --   
+  -- Use the @{#ZONE_CAPTURE_COALITION.New}() constructor to create a new ZONE_CAPTURE_COALITION object.
+  -- 
+  -- # ZONE_CAPTURE_COALITION is a finite state machine (FSM).
   -- 
   -- ![States](..\Presentations\ZONE_CAPTURE_COALITION\Dia4.JPG)
   -- 
-  -- ### 2.1 ZONE\_CAPTURE\_COALITION States
+  -- ## ZONE_CAPTURE_COALITION States
   -- 
   --   * **Captured**: The Zone has been captured by an other coalition.
   --   * **Attacked**: The Zone is currently intruded by an other coalition. There are units of the owning coalition and an other coalition in the Zone.
   --   * **Guarded**: The Zone is guarded by the owning coalition. There is no other unit of an other coalition in the Zone.
   --   * **Empty**: The Zone is empty. There is not valid unit in the Zone.
   --   
-  -- ### 2.2 ZONE\_CAPTURE\_COALITION Events
+  -- ## 2.2 ZONE_CAPTURE_COALITION Events
   -- 
   --   * **Capture**: The Zone has been captured by an other coalition.
   --   * **Attack**: The Zone is currently intruded by an other coalition. There are units of the owning coalition and an other coalition in the Zone.
   --   * **Guard**: The Zone is guarded by the owning coalition. There is no other unit of an other coalition in the Zone.
   --   * **Empty**: The Zone is empty. There is not valid unit in the Zone.
   -- 
-  -- ## 3. "Script It"
+  -- # "Script It"
   -- 
-  -- ZONE\_CAPTURE\_COALITION allows to take action on the various state transitions and add your custom code and logic.
+  -- ZONE_CAPTURE_COALITION allows to take action on the various state transitions and add your custom code and logic.
   -- 
-  -- ### 3.1. Take action using state- and event handlers.
+  -- ## Take action using state- and event handlers.
   -- 
   -- ![States](..\Presentations\ZONE_CAPTURE_COALITION\Dia6.JPG)
   -- 
@@ -104,8 +141,6 @@ do -- ZONE_CAPTURE_COALITION
   --   - On Before the event is triggered. Return false to cancel the transition.
   --   - On After the event is triggered.
   -- 
-  -- 
-  -- 
   -- ![States](..\Presentations\ZONE_CAPTURE_COALITION\Dia7.JPG)
   -- 
   -- Each handler can receive optionally 3 parameters:
@@ -126,7 +161,7 @@ do -- ZONE_CAPTURE_COALITION
   -- 
   -- This code checks that when the __Guarded__ state has been reached, that if the **From** state was __Empty__, then display a message.
   -- 
-  -- ### 3.2. Example Event Handler.
+  -- ## Example Event Handler.
   -- 
   --     --- @param Functional.ZoneCaptureCoalition#ZONE_CAPTURE_COALITION self
   --     function ZoneCaptureCoalition:OnEnterGuarded( From, Event, To )
@@ -145,7 +180,7 @@ do -- ZONE_CAPTURE_COALITION
   --       end
   --     end
   --     
-  -- ### 3.3. Stop and Start the zone monitoring process.
+  -- ## Stop and Start the zone monitoring process.
   -- 
   -- At regular intervals, the state of the zone needs to be monitored.
   -- The zone needs to be scanned for the presence of units within the zone boundaries.
@@ -157,8 +192,8 @@ do -- ZONE_CAPTURE_COALITION
   -- 
   -- Therefore, the mission designer is given 2 methods that allow to take control of the CPU utilization efficiency:
   -- 
-  --   - @{#ZONE_CAPTURE_COALITION.Start()}(): This starts the monitoring process.
-  --   - @{#ZONE_CAPTURE_COALITION.Stop()}(): This stops the monitoring process.
+  --   * @{#ZONE_CAPTURE_COALITION.Start}(): This starts the monitoring process.
+  --   * @{#ZONE_CAPTURE_COALITION.Stop}(): This stops the monitoring process.
   --   
   -- ### IMPORTANT
   -- 
@@ -166,9 +201,9 @@ do -- ZONE_CAPTURE_COALITION
   -- The monitoring process is NOT started by default!!!**
   --   
   -- 
-  -- ## 4. Full Example
+  -- # Full Example
   -- 
-  -- The following annotated code shows a real example of how ZONE\_CAPTURE\_COALITION can be applied.
+  -- The following annotated code shows a real example of how ZONE_CAPTURE_COALITION can be applied.
   -- 
   -- The concept is simple.
   -- 
@@ -329,7 +364,7 @@ do -- ZONE_CAPTURE_COALITION
 
     do 
     
-      --- Captured State Handler OnLeave for ZONE\_CAPTURE\_COALITION
+      --- Captured State Handler OnLeave for ZONE_CAPTURE_COALITION
       -- @function [parent=#ZONE_CAPTURE_COALITION] OnLeaveCaptured
       -- @param #ZONE_CAPTURE_COALITION self
       -- @param #string From
@@ -337,7 +372,7 @@ do -- ZONE_CAPTURE_COALITION
       -- @param #string To
       -- @return #boolean
   
-      --- Captured State Handler OnEnter for ZONE\_CAPTURE\_COALITION
+      --- Captured State Handler OnEnter for ZONE_CAPTURE_COALITION
       -- @function [parent=#ZONE_CAPTURE_COALITION] OnEnterCaptured
       -- @param #ZONE_CAPTURE_COALITION self
       -- @param #string From
@@ -349,7 +384,7 @@ do -- ZONE_CAPTURE_COALITION
   
     do 
     
-      --- Attacked State Handler OnLeave for ZONE\_CAPTURE\_COALITION
+      --- Attacked State Handler OnLeave for ZONE_CAPTURE_COALITION
       -- @function [parent=#ZONE_CAPTURE_COALITION] OnLeaveAttacked
       -- @param #ZONE_CAPTURE_COALITION self
       -- @param #string From
@@ -357,7 +392,7 @@ do -- ZONE_CAPTURE_COALITION
       -- @param #string To
       -- @return #boolean
   
-      --- Attacked State Handler OnEnter for ZONE\_CAPTURE\_COALITION
+      --- Attacked State Handler OnEnter for ZONE_CAPTURE_COALITION
       -- @function [parent=#ZONE_CAPTURE_COALITION] OnEnterAttacked
       -- @param #ZONE_CAPTURE_COALITION self
       -- @param #string From
@@ -368,7 +403,7 @@ do -- ZONE_CAPTURE_COALITION
 
     do 
     
-      --- Guarded State Handler OnLeave for ZONE\_CAPTURE\_COALITION
+      --- Guarded State Handler OnLeave for ZONE_CAPTURE_COALITION
       -- @function [parent=#ZONE_CAPTURE_COALITION] OnLeaveGuarded
       -- @param #ZONE_CAPTURE_COALITION self
       -- @param #string From
@@ -376,7 +411,7 @@ do -- ZONE_CAPTURE_COALITION
       -- @param #string To
       -- @return #boolean
   
-      --- Guarded State Handler OnEnter for ZONE\_CAPTURE\_COALITION
+      --- Guarded State Handler OnEnter for ZONE_CAPTURE_COALITION
       -- @function [parent=#ZONE_CAPTURE_COALITION] OnEnterGuarded
       -- @param #ZONE_CAPTURE_COALITION self
       -- @param #string From
@@ -388,7 +423,7 @@ do -- ZONE_CAPTURE_COALITION
 
     do 
     
-      --- Empty State Handler OnLeave for ZONE\_CAPTURE\_COALITION
+      --- Empty State Handler OnLeave for ZONE_CAPTURE_COALITION
       -- @function [parent=#ZONE_CAPTURE_COALITION] OnLeaveEmpty
       -- @param #ZONE_CAPTURE_COALITION self
       -- @param #string From
@@ -396,7 +431,7 @@ do -- ZONE_CAPTURE_COALITION
       -- @param #string To
       -- @return #boolean
   
-      --- Empty State Handler OnEnter for ZONE\_CAPTURE\_COALITION
+      --- Empty State Handler OnEnter for ZONE_CAPTURE_COALITION
       -- @function [parent=#ZONE_CAPTURE_COALITION] OnEnterEmpty
       -- @param #ZONE_CAPTURE_COALITION self
       -- @param #string From
@@ -407,7 +442,7 @@ do -- ZONE_CAPTURE_COALITION
   
     self:AddTransition( "*", "Guard", "Guarded" )
     
-    --- Guard Handler OnBefore for ZONE\_CAPTURE\_COALITION
+    --- Guard Handler OnBefore for ZONE_CAPTURE_COALITION
     -- @function [parent=#ZONE_CAPTURE_COALITION] OnBeforeGuard
     -- @param #ZONE_CAPTURE_COALITION self
     -- @param #string From
@@ -415,25 +450,25 @@ do -- ZONE_CAPTURE_COALITION
     -- @param #string To
     -- @return #boolean
     
-    --- Guard Handler OnAfter for ZONE\_CAPTURE\_COALITION
+    --- Guard Handler OnAfter for ZONE_CAPTURE_COALITION
     -- @function [parent=#ZONE_CAPTURE_COALITION] OnAfterGuard
     -- @param #ZONE_CAPTURE_COALITION self
     -- @param #string From
     -- @param #string Event
     -- @param #string To
     
-    --- Guard Trigger for ZONE\_CAPTURE\_COALITION
+    --- Guard Trigger for ZONE_CAPTURE_COALITION
     -- @function [parent=#ZONE_CAPTURE_COALITION] Guard
     -- @param #ZONE_CAPTURE_COALITION self
     
-    --- Guard Asynchronous Trigger for ZONE\_CAPTURE\_COALITION
+    --- Guard Asynchronous Trigger for ZONE_CAPTURE_COALITION
     -- @function [parent=#ZONE_CAPTURE_COALITION] __Guard
     -- @param #ZONE_CAPTURE_COALITION self
     -- @param #number Delay
     
     self:AddTransition( "*", "Empty", "Empty" )
     
-    --- Empty Handler OnBefore for ZONE\_CAPTURE\_COALITION
+    --- Empty Handler OnBefore for ZONE_CAPTURE_COALITION
     -- @function [parent=#ZONE_CAPTURE_COALITION] OnBeforeEmpty
     -- @param #ZONE_CAPTURE_COALITION self
     -- @param #string From
@@ -441,18 +476,18 @@ do -- ZONE_CAPTURE_COALITION
     -- @param #string To
     -- @return #boolean
     
-    --- Empty Handler OnAfter for ZONE\_CAPTURE\_COALITION
+    --- Empty Handler OnAfter for ZONE_CAPTURE_COALITION
     -- @function [parent=#ZONE_CAPTURE_COALITION] OnAfterEmpty
     -- @param #ZONE_CAPTURE_COALITION self
     -- @param #string From
     -- @param #string Event
     -- @param #string To
     
-    --- Empty Trigger for ZONE\_CAPTURE\_COALITION
+    --- Empty Trigger for ZONE_CAPTURE_COALITION
     -- @function [parent=#ZONE_CAPTURE_COALITION] Empty
     -- @param #ZONE_CAPTURE_COALITION self
     
-    --- Empty Asynchronous Trigger for ZONE\_CAPTURE\_COALITION
+    --- Empty Asynchronous Trigger for ZONE_CAPTURE_COALITION
     -- @function [parent=#ZONE_CAPTURE_COALITION] __Empty
     -- @param #ZONE_CAPTURE_COALITION self
     -- @param #number Delay
@@ -460,7 +495,7 @@ do -- ZONE_CAPTURE_COALITION
     
     self:AddTransition( {  "Guarded", "Empty" }, "Attack", "Attacked" )
   
-    --- Attack Handler OnBefore for ZONE\_CAPTURE\_COALITION
+    --- Attack Handler OnBefore for ZONE_CAPTURE_COALITION
     -- @function [parent=#ZONE_CAPTURE_COALITION] OnBeforeAttack
     -- @param #ZONE_CAPTURE_COALITION self
     -- @param #string From
@@ -468,25 +503,25 @@ do -- ZONE_CAPTURE_COALITION
     -- @param #string To
     -- @return #boolean
     
-    --- Attack Handler OnAfter for ZONE\_CAPTURE\_COALITION
+    --- Attack Handler OnAfter for ZONE_CAPTURE_COALITION
     -- @function [parent=#ZONE_CAPTURE_COALITION] OnAfterAttack
     -- @param #ZONE_CAPTURE_COALITION self
     -- @param #string From
     -- @param #string Event
     -- @param #string To
     
-    --- Attack Trigger for ZONE\_CAPTURE\_COALITION
+    --- Attack Trigger for ZONE_CAPTURE_COALITION
     -- @function [parent=#ZONE_CAPTURE_COALITION] Attack
     -- @param #ZONE_CAPTURE_COALITION self
     
-    --- Attack Asynchronous Trigger for ZONE\_CAPTURE\_COALITION
+    --- Attack Asynchronous Trigger for ZONE_CAPTURE_COALITION
     -- @function [parent=#ZONE_CAPTURE_COALITION] __Attack
     -- @param #ZONE_CAPTURE_COALITION self
     -- @param #number Delay
     
     self:AddTransition( { "Guarded", "Attacked", "Empty" }, "Capture", "Captured" )
    
-    --- Capture Handler OnBefore for ZONE\_CAPTURE\_COALITION
+    --- Capture Handler OnBefore for ZONE_CAPTURE_COALITION
     -- @function [parent=#ZONE_CAPTURE_COALITION] OnBeforeCapture
     -- @param #ZONE_CAPTURE_COALITION self
     -- @param #string From
@@ -494,18 +529,18 @@ do -- ZONE_CAPTURE_COALITION
     -- @param #string To
     -- @return #boolean
     
-    --- Capture Handler OnAfter for ZONE\_CAPTURE\_COALITION
+    --- Capture Handler OnAfter for ZONE_CAPTURE_COALITION
     -- @function [parent=#ZONE_CAPTURE_COALITION] OnAfterCapture
     -- @param #ZONE_CAPTURE_COALITION self
     -- @param #string From
     -- @param #string Event
     -- @param #string To
     
-    --- Capture Trigger for ZONE\_CAPTURE\_COALITION
+    --- Capture Trigger for ZONE_CAPTURE_COALITION
     -- @function [parent=#ZONE_CAPTURE_COALITION] Capture
     -- @param #ZONE_CAPTURE_COALITION self
     
-    --- Capture Asynchronous Trigger for ZONE\_CAPTURE\_COALITION
+    --- Capture Asynchronous Trigger for ZONE_CAPTURE_COALITION
     -- @function [parent=#ZONE_CAPTURE_COALITION] __Capture
     -- @param #ZONE_CAPTURE_COALITION self
     -- @param #number Delay

Moose Development/Moose/Tasking/CommandCenter.lua

@@ -270,6 +270,8 @@ function COMMANDCENTER:New( CommandCenterPositionable, CommandCenterName )
   self:SetMenu()
   
   _SETTINGS:SetSystemMenu( CommandCenterPositionable )
+  
+  self:SetCommandMenu()
 	
 	return self
 end
@@ -426,6 +428,7 @@ end
 
 --- Gets the commandcenter menu structure governed by the HQ command center.
 -- @param #COMMANDCENTER self
+-- @param Wrapper.Group#Group TaskGroup Task Group.
 -- @return Core.Menu#MENU_COALITION
 function COMMANDCENTER:GetMenu( TaskGroup )
 
@@ -439,10 +442,7 @@ function COMMANDCENTER:GetMenu( TaskGroup )
   self.CommandCenterMenus[TaskGroup] = CommandCenterMenu
 
   if self.AutoAssignTasks == false then
-    local AutoAssignTaskMenu = MENU_GROUP_COMMAND:New( TaskGroup, "Assign Task On", CommandCenterMenu, self.SetAutoAssignTasks, self, true ):SetTime(MenuTime):SetTag("AutoTask")
     local AssignTaskMenu = MENU_GROUP_COMMAND:New( TaskGroup, "Assign Task", CommandCenterMenu, self.AssignRandomTask, self, TaskGroup ):SetTime(MenuTime):SetTag("AutoTask")
-  else
-    local AutoAssignTaskMenu = MENU_GROUP_COMMAND:New( TaskGroup, "Assign Task Off", CommandCenterMenu, self.SetAutoAssignTasks, self, false ):SetTime(MenuTime):SetTag("AutoTask")
   end
   CommandCenterMenu:Remove( MenuTime, "AutoTask" )
     
@@ -474,10 +474,32 @@ function COMMANDCENTER:AssignRandomTask( TaskGroup )
 end
 
 
+--- Sets the menu of the command center.
+-- This command is called within the :New() method.
+-- @param #COMMANDCENTER self
+function COMMANDCENTER:SetCommandMenu()
+
+  local MenuTime = timer.getTime()
+  
+  if self.CommandCenterPositionable and self.CommandCenterPositionable:IsInstanceOf(GROUP) then
+    local CommandCenterText = self:GetText()
+    local CommandCenterMenu = MENU_GROUP:New( self.CommandCenterPositionable, CommandCenterText ):SetTime(MenuTime)
+  
+    if self.AutoAssignTasks == false then
+      local AutoAssignTaskMenu = MENU_GROUP_COMMAND:New( self.CommandCenterPositionable, "Assign Task On", CommandCenterMenu, self.SetAutoAssignTasks, self, true ):SetTime(MenuTime):SetTag("AutoTask")
+    else
+      local AutoAssignTaskMenu = MENU_GROUP_COMMAND:New( self.CommandCenterPositionable, "Assign Task Off", CommandCenterMenu, self.SetAutoAssignTasks, self, false ):SetTime(MenuTime):SetTag("AutoTask")
+    end
+    CommandCenterMenu:Remove( MenuTime, "AutoTask" )
+  end
+
+end
+
+
+
 --- Automatically assigns tasks to all TaskGroups.
 -- @param #COMMANDCENTER self
 -- @param #boolean AutoAssign true for ON and false or nil for OFF.
--- @return #COMMANDCENTER
 function COMMANDCENTER:SetAutoAssignTasks( AutoAssign )
 
   self.AutoAssignTasks = AutoAssign or false
@@ -494,6 +516,8 @@ function COMMANDCENTER:SetAutoAssignTasks( AutoAssign )
   else
     self:ScheduleStop( self.AssignTasks )
   end
+  
+  self:SetCommandCenterMenu()
 
 end
 
@@ -516,12 +540,13 @@ function COMMANDCENTER:AssignTasks()
       end
     end
   end
+
 end
 
 
 --- Get all the Groups active within the command center.
 -- @param #COMMANDCENTER self
--- @return Core.Set#SET_GROUP
+-- @return Core.Set#SET_GROUP The set of groups active within the command center.
 function COMMANDCENTER:AddGroups()
 
   local GroupSet = SET_GROUP:New()
@@ -537,7 +562,7 @@ end
 
 --- Checks of the TaskGroup has a Task.
 -- @param #COMMANDCENTER self
--- @return #boolean
+-- @return #boolean When true, the TaskGroup has a Task, otherwise the returned value will be false.
 function COMMANDCENTER:IsGroupAssigned( TaskGroup )
 
   local Assigned = false
@@ -554,9 +579,9 @@ function COMMANDCENTER:IsGroupAssigned( TaskGroup )
 end
 
 
---- Checks of the COMMANDCENTER has a GROUP.
+--- Checks of the command center has the given MissionGroup.
 -- @param #COMMANDCENTER self
--- @param Wrapper.Group#GROUP
+-- @param Wrapper.Group#GROUP MissionGroup The group active within one of the missions governed by the command center.
 -- @return #boolean
 function COMMANDCENTER:HasGroup( MissionGroup )
 
@@ -573,37 +598,39 @@ function COMMANDCENTER:HasGroup( MissionGroup )
   return Has
 end
 
---- Send a CC message to the coalition of the CC.
+--- Let the command center send a Message to all players.
 -- @param #COMMANDCENTER self
+-- @param #string Message The message text.
 function COMMANDCENTER:MessageToAll( Message )
 
     self:GetPositionable():MessageToAll( Message, 20, self:GetName() )
 
 end
 
---- Send a CC message to a GROUP.
+--- Let the command center send a message to the MessageGroup.
 -- @param #COMMANDCENTER self
--- @param #string Message
--- @param Wrapper.Group#GROUP TaskGroup
-function COMMANDCENTER:MessageToGroup( Message, TaskGroup )
+-- @param #string Message The message text.
+-- @param Wrapper.Group#GROUP MessageGroup The group to receive the message.
+function COMMANDCENTER:MessageToGroup( Message, MessageGroup )
 
-  self:GetPositionable():MessageToGroup( Message, 15, TaskGroup, self:GetShortText() )
+  self:GetPositionable():MessageToGroup( Message, 15, MessageGroup, self:GetShortText() )
 
 end
 
---- Send a CC message of a specified type to a GROUP.
+--- Let the command center send a message to the MessageGroup.
 -- @param #COMMANDCENTER self
--- @param #string Message
--- @param Wrapper.Group#GROUP TaskGroup
+-- @param #string Message The message text.
+-- @param Wrapper.Group#GROUP MessageGroup The group to receive the message.
 -- @param Core.Message#MESSAGE.MessageType MessageType The type of the message, resulting in automatic time duration and prefix of the message.
-function COMMANDCENTER:MessageTypeToGroup( Message, TaskGroup, MessageType )
+function COMMANDCENTER:MessageTypeToGroup( Message, MessageGroup, MessageType )
 
-  self:GetPositionable():MessageTypeToGroup( Message, MessageType, TaskGroup, self:GetShortText() )
+  self:GetPositionable():MessageTypeToGroup( Message, MessageType, MessageGroup, self:GetShortText() )
 
 end
 
---- Send a CC message to the coalition of the CC.
+--- Let the command center send a message to the coalition of the command center.
 -- @param #COMMANDCENTER self
+-- @param #string Message The message text.
 function COMMANDCENTER:MessageToCoalition( Message )
 
   local CCCoalition = self:GetPositionable():GetCoalition()
@@ -614,9 +641,9 @@ function COMMANDCENTER:MessageToCoalition( Message )
 end
 
 
---- Send a CC message of a specified type to the coalition of the CC.
+--- Let the command center send a message of a specified type to the coalition of the command center.
 -- @param #COMMANDCENTER self
--- @param #string Message The message.
+-- @param #string Message The message text.
 -- @param Core.Message#MESSAGE.MessageType MessageType The type of the message, resulting in automatic time duration and prefix of the message.
 function COMMANDCENTER:MessageTypeToCoalition( Message, MessageType )
 
@@ -628,9 +655,10 @@ function COMMANDCENTER:MessageTypeToCoalition( Message, MessageType )
 end
 
 
---- Report the status of all MISSIONs to a GROUP.
+--- Let the command center send a report of the status of all missions to a group.
 -- Each Mission is listed, with an indication how many Tasks are still to be completed.
 -- @param #COMMANDCENTER self
+-- @param Wrapper.Group#GROUP ReportGroup The group to receive the report.
 function COMMANDCENTER:ReportSummary( ReportGroup )
   self:F( ReportGroup )
 
@@ -642,15 +670,16 @@ function COMMANDCENTER:ReportSummary( ReportGroup )
   
   for MissionID, Mission in pairs( self.Missions ) do
     local Mission = Mission -- Tasking.Mission#MISSION
-    Report:Add( " - " .. Mission:ReportSummary() )
+    Report:Add( " - " .. Mission:ReportSummary( ReportGroup ) )
   end
   
   self:MessageToGroup( Report:Text(), ReportGroup )
 end
 
---- Report the players of all MISSIONs to a GROUP.
+--- Let the command center send a report of the players of all missions to a group.
 -- Each Mission is listed, with an indication how many Tasks are still to be completed.
 -- @param #COMMANDCENTER self
+-- @param Wrapper.Group#GROUP ReportGroup The group to receive the report.
 function COMMANDCENTER:ReportMissionsPlayers( ReportGroup )
   self:F( ReportGroup )
 
@@ -666,9 +695,11 @@ function COMMANDCENTER:ReportMissionsPlayers( ReportGroup )
   self:MessageToGroup( Report:Text(), ReportGroup )
 end
 
---- Report the status of a Task to a Group.
+--- Let the command center send a report of the status of a task to a group.
 -- Report the details of a Mission, listing the Mission, and all the Task details.
 -- @param #COMMANDCENTER self
+-- @param Wrapper.Group#GROUP ReportGroup The group to receive the report.
+-- @param Tasking.Task#TASK Task The task to be reported.
 function COMMANDCENTER:ReportDetails( ReportGroup, Task )
   self:F( ReportGroup )
 

Moose Development/Moose/Tasking/DetectionManager.lua

@@ -43,11 +43,13 @@
 
 do -- DETECTION MANAGER
   
-  --- DETECTION_MANAGER class.
-  -- @type DETECTION_MANAGER
+  --- @type DETECTION_MANAGER
   -- @field Core.Set#SET_GROUP SetGroup The groups to which the FAC will report to.
   -- @field Functional.Detection#DETECTION_BASE Detection The DETECTION_BASE object that is used to report the detected objects.
   -- @extends Core.Fsm#FSM
+
+  --- DETECTION_MANAGER class.
+  -- @field #DETECTION_MANAGER
   DETECTION_MANAGER = {
     ClassName = "DETECTION_MANAGER",
     SetGroup = nil,

Moose Development/Moose/Tasking/Mission.lua

@@ -129,10 +129,10 @@ MISSION = {
 --- This is the main MISSION declaration method. Each Mission is like the master or a Mission orchestration between, Clients, Tasks, Stages etc.
 -- @param #MISSION self
 -- @param Tasking.CommandCenter#COMMANDCENTER CommandCenter
--- @param #string MissionName is the name of the mission. This name will be used to reference the status of each mission by the players.
--- @param #string MissionPriority is a string indicating the "priority" of the Mission. f.e. "Primary", "Secondary" or "First", "Second". It is free format and up to the Mission designer to choose. There are no rules behind this field.
--- @param #string MissionBriefing is a string indicating the mission briefing to be shown when a player joins a @{CLIENT}.
--- @param #string MissionCoalition is a string indicating the coalition or party to which this mission belongs to. It is free format and can be chosen freely by the mission designer. Note that this field is not to be confused with the coalition concept of the ME. Examples of a Mission Coalition could be "NATO", "CCCP", "Intruders", "Terrorists"...
+-- @param #string MissionName Name of the mission. This name will be used to reference the status of each mission by the players.
+-- @param #string MissionPriority String indicating the "priority" of the Mission. e.g. "Primary", "Secondary". It is free format and up to the Mission designer to choose. There are no rules behind this field.
+-- @param #string MissionBriefing String indicating the mission briefing to be shown when a player joins a @{CLIENT}.
+-- @param DCS#coaliton.side MissionCoalition Side of the coalition, i.e. and enumerator @{#DCS.coalition.side} corresponding to RED, BLUE or NEUTRAL.
 -- @return #MISSION self
 function MISSION:New( CommandCenter, MissionName, MissionPriority, MissionBriefing, MissionCoalition )
 
@@ -611,13 +611,14 @@ function MISSION:RemoveTaskMenu( Task )
 end
 
 
---- Gets the root mission menu for the TaskGroup.
+--- Gets the root mission menu for the TaskGroup. Obsolete?! Originally no reference to TaskGroup parameter!
 -- @param #MISSION self
+-- @param Wrapper.Group#GROUP TaskGroup Task group.
 -- @return Core.Menu#MENU_COALITION self
 function MISSION:GetRootMenu( TaskGroup ) -- R2.2
 
   local CommandCenter = self:GetCommandCenter()
-  local CommandCenterMenu = CommandCenter:GetMenu()
+  local CommandCenterMenu = CommandCenter:GetMenu( TaskGroup )
 
   local MissionName = self:GetText()
   --local MissionMenu = CommandCenterMenu:GetMenu( MissionName )
@@ -629,6 +630,7 @@ end
 
 --- Gets the mission menu for the TaskGroup.
 -- @param #MISSION self
+-- @param Wrapper.Group#GROUP TaskGroup Task group.
 -- @return Core.Menu#MENU_COALITION self
 function MISSION:GetMenu( TaskGroup ) -- R2.1 -- Changed Menu Structure
 

Moose Development/Moose/Tasking/Task.lua

@@ -1200,15 +1200,27 @@ function TASK:MenuMarkToGroup( TaskGroup )
 
   self:UpdateTaskInfo( self.DetectedItem )
   
-  local Report = REPORT:New():SetIndent( 0 )
-
-  self.TaskInfo:Report( Report, "M", TaskGroup )
-
-  local TargetCoordinate = self.TaskInfo:GetData( "Coordinate" ) -- Core.Point#COORDINATE
-  local MarkText = Report:Text( ", " ) 
-  self:F( { Coordinate = TargetCoordinate, MarkText = MarkText } )
-  TargetCoordinate:MarkToGroup( MarkText, TaskGroup )
-  --Coordinate:MarkToAll( Briefing )
+  local TargetCoordinates = self.TaskInfo:GetData( "Coordinates" ) -- Core.Point#COORDINATE
+  if TargetCoordinates then
+    for TargetCoordinateID, TargetCoordinate in pairs( TargetCoordinates ) do
+      local Report = REPORT:New():SetIndent( 0 )
+      self.TaskInfo:Report( Report, "M", TaskGroup, self )
+      local MarkText = Report:Text( ", " ) 
+      self:F( { Coordinate = TargetCoordinate, MarkText = MarkText } )
+      TargetCoordinate:MarkToGroup( MarkText, TaskGroup )
+      --Coordinate:MarkToAll( Briefing )
+    end
+  else
+    local TargetCoordinate = self.TaskInfo:GetData( "Coordinate" ) -- Core.Point#COORDINATE
+    if TargetCoordinate then
+      local Report = REPORT:New():SetIndent( 0 )
+      self.TaskInfo:Report( Report, "M", TaskGroup, self )
+      local MarkText = Report:Text( ", " ) 
+      self:F( { Coordinate = TargetCoordinate, MarkText = MarkText } )
+      TargetCoordinate:MarkToGroup( MarkText, TaskGroup )
+    end
+  end
+  
 end
 
 --- Report the task status.
@@ -1739,7 +1751,7 @@ function TASK:ReportSummary( ReportGroup )
   -- Determine the status of the Task.
   Report:Add( "State: <" .. self:GetState() .. ">" )
   
-  self.TaskInfo:Report( Report, "S", ReportGroup )
+  self.TaskInfo:Report( Report, "S", ReportGroup, self )
   
   return Report:Text( ', ' )
 end
@@ -1756,7 +1768,7 @@ function TASK:ReportOverview( ReportGroup )
   local TaskName = self:GetName()
   local Report = REPORT:New()
   
-  self.TaskInfo:Report( Report, "O", ReportGroup )
+  self.TaskInfo:Report( Report, "O", ReportGroup, self )
   
   return Report:Text()
 end
@@ -1840,7 +1852,7 @@ function TASK:ReportDetails( ReportGroup )
     Report:AddIndent( Players )
   end
   
-  self.TaskInfo:Report( Report, "D", ReportGroup )
+  self.TaskInfo:Report( Report, "D", ReportGroup, self )
   
   return Report:Text()
 end

Moose Development/Moose/Tasking/TaskInfo.lua

@@ -85,7 +85,7 @@ end
 -- @return Data The data of the info.
 function TASKINFO:GetData( Key )
   local Object = self.Info:Get( Key )
-  return Object.Data
+  return Object and Object.Data
 end
 
 
@@ -130,6 +130,19 @@ function TASKINFO:AddCoordinate( Coordinate, Order, Detail, Keep )
 end
 
 
+--- Add Coordinates. 
+-- @param #TASKINFO self
+-- @param #list<Core.Point#COORDINATE> Coordinates
+-- @param #number Order The display order, which is a number from 0 to 100.
+-- @param #TASKINFO.Detail Detail The detail Level.
+-- @param #boolean Keep (optional) If true, this would indicate that the planned taskinfo would be persistent when the task is completed, so that the original planned task info is used at the completed reports.
+-- @return #TASKINFO self
+function TASKINFO:AddCoordinates( Coordinates, Order, Detail, Keep )
+  self:AddInfo( "Coordinates", Coordinates, Order, Detail, Keep )
+  return self
+end
+
+
 
 --- Add Threat. 
 -- @param #TASKINFO self
@@ -259,6 +272,7 @@ function TASKINFO:AddCargoSet( SetCargo, Order, Detail, Keep )
   )
 
   self:AddInfo( "Cargo", CargoReport:Text(), Order, Detail, Keep )
+  
 
   return self
 end
@@ -270,8 +284,9 @@ end
 -- @param Core.Report#REPORT Report
 -- @param #TASKINFO.Detail Detail The detail Level.
 -- @param Wrapper.Group#GROUP ReportGroup
+-- @param Tasking.Task#TASK Task
 -- @return #TASKINFO self
-function TASKINFO:Report( Report, Detail, ReportGroup )
+function TASKINFO:Report( Report, Detail, ReportGroup, Task )
 
   local Line = 0
   local LineReport = REPORT:New()
@@ -292,7 +307,7 @@ function TASKINFO:Report( Report, Detail, ReportGroup )
       end
       if Key == "Coordinate" then
         local Coordinate = Data.Data -- Core.Point#COORDINATE
-        Text = Coordinate:ToString( ReportGroup:GetUnit(1), nil, self )
+        Text = Coordinate:ToString( ReportGroup:GetUnit(1), nil, Task )
       end
       if Key == "Threat" then
         local DataText = Data.Data -- #string
@@ -308,15 +323,15 @@ function TASKINFO:Report( Report, Detail, ReportGroup )
       end
       if Key == "QFE" then
         local Coordinate = Data.Data -- Core.Point#COORDINATE
-        Text = Coordinate:ToStringPressure( ReportGroup:GetUnit(1), nil, self )
+        Text = Coordinate:ToStringPressure( ReportGroup:GetUnit(1), nil, Task )
       end
       if Key == "Temperature" then
         local Coordinate = Data.Data -- Core.Point#COORDINATE
-        Text = Coordinate:ToStringTemperature( ReportGroup:GetUnit(1), nil, self )
+        Text = Coordinate:ToStringTemperature( ReportGroup:GetUnit(1), nil, Task )
       end
       if Key == "Wind" then
         local Coordinate = Data.Data -- Core.Point#COORDINATE
-        Text = Coordinate:ToStringWind( ReportGroup:GetUnit(1), nil, self )
+        Text = Coordinate:ToStringWind( ReportGroup:GetUnit(1), nil, Task )
       end
       if Key == "Cargo" then
         local DataText = Data.Data -- #string

Moose Development/Moose/Tasking/Task_A2A_Dispatcher.lua

@@ -574,15 +574,15 @@ do -- TASK_A2A_DISPATCHER
               self:Success( Task )
             end
 
-            function Task.onenterCancelled( Task, From, Event, To )
+            function Task.OnEnterCancelled( Task, From, Event, To )
               self:Cancelled( Task )
             end
             
-            function Task.onenterFailed( Task, From, Event, To )
+            function Task.OnEnterFailed( Task, From, Event, To )
               self:Failed( Task )
             end
 
-            function Task.onenterAborted( Task, From, Event, To )
+            function Task.OnEnterAborted( Task, From, Event, To )
               self:Aborted( Task )
             end
             

Moose Development/Moose/Tasking/Task_A2G_Dispatcher.lua

@@ -775,15 +775,15 @@ do -- TASK_A2G_DISPATCHER
               self:Success( Task )
             end
 
-            function Task.onenterCancelled( Task, From, Event, To )
+            function Task.OnEnterCancelled( Task, From, Event, To )
               self:Cancelled( Task )
             end
             
-            function Task.onenterFailed( Task, From, Event, To )
+            function Task.OnEnterFailed( Task, From, Event, To )
               self:Failed( Task )
             end
 
-            function Task.onenterAborted( Task, From, Event, To )
+            function Task.OnEnterAborted( Task, From, Event, To )
               self:Aborted( Task )
             end
             

Moose Development/Moose/Tasking/Task_CARGO.lua

@@ -1,19 +1,35 @@
 --- **Tasking** -- Base class to model tasks for players to transport cargo.
 -- 
+-- ## Features:
+-- 
+--   * TASK_CARGO is the **base class** for:
+--   
+--     * @{Tasking.Task_Cargo_Transport#TASK_CARGO_TRANSPORT}
+--     * @{Tasking.Task_Cargo_CSAR#TASK_CARGO_CSAR}
+-- 
+-- 
+-- ===
+-- 
+-- ## Test Missions:
+-- 
+-- Test missions can be located on the main GITHUB site.
+-- 
+-- [FlightControl-Master/MOOSE_MISSIONS/TAD - Task Dispatching/CGO - Cargo Dispatching/](https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/develop/TAD%20-%20Task%20Dispatching/CGO%20-%20Cargo%20Dispatching)
+-- 
 -- ===
 --
--- # 1) Tasking system.
+-- ## Tasking system.
 -- 
--- #### If you are not yet aware what the MOOSE tasking system is about, read FIRST the explanation on tasking **@{Tasking.Task}**.
+-- #### If you are not yet aware what the MOOSE tasking system is about, read FIRST the explanation on the @{Tasking.Task} module.
 -- 
 -- ===
 -- 
--- # 2) Context of cargo tasking.
+-- ## Context of cargo tasking.
 -- 
 -- The Moose framework provides various CARGO classes that allow DCS physical or logical objects to be transported or sling loaded by Carriers.
 -- The CARGO_ classes, as part of the MOOSE core, are able to Board, Load, UnBoard and UnLoad cargo between Carrier units.
 -- 
--- The TASK\_CARGO class is not meant to use within your missions as a mission designer. It is a base class, and other classes are derived from it.
+-- The TASK_CARGO class is not meant to use within your missions as a mission designer. It is a base class, and other classes are derived from it.
 -- 
 -- The following TASK_CARGO_ classes are important, as they implement the CONCRETE tasks:
 -- 
@@ -25,7 +41,7 @@
 -- 
 -- ===
 -- 
--- # 3) Cargo tasking from a player perspective.
+-- ## Cargo tasking from a player perspective.
 -- 
 -- A human player can join the battle field in a client airborne slot or a ground vehicle within the CA module (ALT-J).
 -- The player needs to accept the task from the task overview list within the mission, using the menus.
@@ -46,19 +62,19 @@
 -- In the menu, you'll find for each CARGO, that is part of the scope of the task, various actions that can be completed.
 -- Depending on the location of your Carrier unit, the menu options will vary.
 -- 
--- ## 3.1) Joining a Cargo Transport Task
+-- ### Joining a Cargo Transport Task
 -- 
 -- Once you've joined a task, using the **Join Planned Task Menu**, 
 -- you can Pickup cargo from a pickup location and Deploy cargo in deployment zones, using the **Task Action Menu**.
 --  
--- ## 3.2) Task Action Menu.
+-- ### Task Action Menu.
 -- 
 -- When a player has joined a **`CARGO`** task (type), for that player only, 
 -- it's **Task Action Menu** will show an additional menu options.
 -- 
 -- From within this menu, you will be able to route to a cargo location, deploy zone, and load/unload cargo.
 -- 
--- ## 3.3) Pickup cargo by Boarding, Loading and Sling Loading.
+-- ### Pickup cargo by Boarding, Loading and Sling Loading.
 -- 
 -- There are three different ways how cargo can be picked up:
 -- 
@@ -99,7 +115,7 @@
 -- This is done to ensure that **different teams** have a **defined scope** for defined cargo, and that **multiple teams** can join
 -- **multiple tasks**, transporting cargo **simultaneously** in a **cooperation**.
 -- 
--- In this example, there is a menu option to **Route to pickup cargo...".
+-- In this example, there is a menu option to **Route to pickup cargo...**.
 -- Use this menu to route towards cargo locations for pickup into your carrier.
 -- 
 -- ![Task_Types](../Tasking/Task_Cargo_Types_Menu.JPG)
@@ -140,7 +156,7 @@
 -- These routing options will only be shown, when your carrier bays have cargo loaded.
 -- So, only when there is something to be deployed from your carrier, the deploy options will be shown.
 --     
--- ### 3.3.1) Pickup Cargo.
+-- #### Pickup Cargo.
 -- 
 -- In order to pickup cargo, use the **task action menu** to **route to a specific cargo**.
 -- When a cargo route is selected, the HQ will send you routing messages indicating the location of the cargo.
@@ -155,51 +171,78 @@
 -- It takes a bit of skill to land a helicopter near a cargo to be loaded, but that is part of the game, isn't it?
 -- Expecially when you are landing in a "hot" zone, so when cargo is under immediate threat of fire.
 -- 
--- ### 3.3.2) Board Cargo (infantry).
+-- #### Board Cargo (infantry).
 -- 
--- ![Task_Types](../Tasking/Boarding_Ready.JPG)  
+-- ![](../Tasking/Boarding_Ready.png)  
 -- 
 -- If your Carrier is within the **Reporting Range of the cargo**, and the cargo is **moveable**, the **cargo can be boarded**!
 -- This type of cargo will be most of the time be infantry.
 -- 
--- ![Boarding](../Tasking/Boarding_Menu.JPG)  
+-- ![](../Tasking/Boarding_Menu.png)  
 -- 
--- A board menu has appeared, because your carrier is in boarding range of the cargo (infantry).
+-- A **Board cargo...** sub menu has appeared, because your carrier is in boarding range of the cargo (infantry).
+-- Select the **Board cargo...** menu.
 -- 
--- ![Boarding](../Tasking/Boarding_Started.JPG)  
+-- ![](../Tasking/Boarding_Menu_Engineers.png)  
 -- 
+-- Any cargo that can be boarded (thus movable cargo), within boarding range of the carrier, will be listed here!
+-- In this example, the cargo **Engineers** can be boarded, by selecting the menu option.
 -- 
--- Select the option from the action menu, then select the cargo to be boarded, and the cargo will start moving towards your carrier.
--- Note that a message is displayed by the infantry cargo that boarding has started.
+-- ![](../Tasking/Boarding_Started.png)  
 -- 
--- ![Boarding](../Tasking/Boarding_Ongoing.JPG)  
+-- After the menu option to board the cargo has been selected, the boarding process is started.
+-- A message from the cargo is communicated to the pilot, that boarding is started.
+-- 
+-- ![](../Tasking/Boarding_Ongoing.png)  
+-- 
+-- **The pilot must wait at the exact position until all cargo has been boarded!**  
 -- 
 -- The moveable cargo will run in formation to your carrier, and will board one by one, depending on the near range set by the mission designer.
 -- The near range as added because carriers can be large or small, depending on the object size of the carrier.
 -- 
--- ![Boarding](../Tasking/Boarding_Almost_Done.JPG)  
+-- ![](../Tasking/Boarding_In_Progress.png)  
+-- 
+-- ![](../Tasking/Boarding_Almost_Done.png)  
 -- 
 -- Note that multiple units may need to board your Carrier, so it is required to await the full boarding process.
 -- 
--- ![Boarding](../Tasking/Boarding_Done.JPG)  
+-- ![](../Tasking/Boarding_Done.png)  
 -- 
 -- Once the cargo is fully boarded within your Carrier, you will be notified of this.
 -- 
--- Note that for airborne Carriers, it is required to land first before the Boarding process can be initiated.
--- If during boarding the Carrier gets airborne, the boarding process will be cancelled.
+-- **Remarks:**
 -- 
--- ### 3.3.3) Load Cargo.
+--   * For airborne Carriers, it is required to land first before the Boarding process can be initiated.
+--     If during boarding the Carrier gets airborne, the boarding process will be cancelled.
+--   * The carrier must remain stationary when the boarding sequence has started until further notified.
 -- 
--- If your Carrier is within the **Loading Range of the cargo**, and the cargo is **stationary**, the **cargo can be loaded**, but not boarded!
+-- #### Load Cargo.
+-- 
+-- Cargo can be loaded into vehicles or helicopters or airplanes, as long as the carrier is sufficiently near to the cargo object.
+-- 
+-- ![](../Tasking/Loading_Ready.png)  
+-- 
+-- If your Carrier is within the **Loading Range of the cargo**, thus, sufficiently near to the cargo, and the cargo is **stationary**, the **cargo can be loaded**, but not boarded!
+-- 
+-- ![](../Tasking/Loading_Menu.png)  
+-- 
+-- Select the task action menu and now a **Load cargo...** sub menu will be listed.
+-- Select the **Load cargo...** sub menu, and a further detailed menu will be shown.
+-- 
+-- ![](../Tasking/Loading_Menu_Crate.png)  
+-- 
+-- For each non-moveable cargo object (crates etc), **within loading range of the carrier**, the cargo will be listed and can be loaded into the carrier!
+-- 
+-- ![](../Tasking/Loading_Cargo_Loaded.png)  
 -- 
--- Select the task action menu and now a **Load option** will be listed with the cargo name next to it!
--- Select the option from the action menu, and the cargo will loaded into your carrier.
 -- Once the cargo is loaded within your Carrier, you will be notified of this.
 -- 
--- Note that for airborne Carriers, it is required to land first right near the cargo, before the loading process can be initiated.
+-- **Remarks:**
+--  
+--   * For airborne Carriers, it is required to **land first right near the cargo**, before the loading process can be initiated.
 -- As stated, this requires some pilot skills :-)
 -- 
--- ### 3.3.4) Sling Load Cargo (helicopters only).
+-- #### Sling Load Cargo (helicopters only).
 -- 
 -- If your Carrier is within the **Loading Range of the cargo**, and the cargo is **stationary**, the **cargo can also be sling loaded**!
 -- Note that this is only possible for helicopters.
@@ -211,7 +254,9 @@
 -- As stated, this requires some pilot skills :-)
 -- 
 -- 
--- ## 3.4) Deploy cargo by Unboarding, Unloading and Sling Deploying.
+-- ### Deploy cargo by Unboarding, Unloading and Sling Deploying.
+-- 
+-- #### **Deploying the relevant cargo within deploy zones, will make you achieve cargo transportation tasks!!!**
 -- 
 -- There are two different ways how cargo can be deployed:
 -- 
@@ -231,61 +276,122 @@
 -- Fortunately, the HQ can help to route you to the locations of deploy zone.
 -- Use the task action menu to receive HQ help for this.
 -- 
--- ![Task_Types](../Tasking/Task_Cargo_Actions.JPG)
+-- ![](../Tasking/Routing_Deploy_Zone_Menu.png)
 --  
 -- Depending on the location within the battlefield, the task action menu will contain **Route options** that can be selected
 -- to start the HQ sending you routing messages. Also, if the carrier cargo bays contain cargo, 
 -- then beside **Route options** there will also be **Deploy options** listed.
 -- These **Deploy options** are meant to route you to the deploy zone locations.
 -- 
+-- ![](../Tasking/Routing_Deploy_Zone_Menu_Workplace.png)
+-- 
+-- Depending on the task that you have selected, the deploy zones will be listed.
+-- **There may be multiple deploy zones within the mission, but only the deploy zones relevant for your task will be available in the menu!**
+--  
+-- ![](../Tasking/Routing_Deploy_Zone_Message.png)
+-- 
+-- When a routing option is selected, you are sent routing messages in a selected coordinate format.
 -- Possible routing coordinate formats are: Bearing Range (BR), Lattitude Longitude (LL) or Military Grid System (MGRS).
--- Note that for LL, there are two sub formats.
+-- Note that for LL, there are two sub formats. (See pickup).
+-- 
+-- ![](../Tasking/Routing_Deploy_Zone_Arrived.png)
+-- 
+-- When you are within the range of the deploy zone (can be also a polygon!), a message is communicated by HQ that you have arrived within the zone!
 -- 
 -- The routing messages are formulated in the coordinate format that is currently active as configured in your settings profile.  
 -- ![Task_Types](../Tasking/Task_Cargo_Settings.JPG)  
 -- Use the **Settings Menu** to select the coordinate format that you would like to use for location determination.
 -- 
--- ## 3.4) Deploy Cargo.
+-- #### Unboard Cargo.
 -- 
--- Various Deployment Zones can be foreseen in the scope of the Cargo transportation. Each deployment zone can be of varying @{Zone} type.
--- The Cargo menu provides with menu options to execute an action to steer your Carrier to a specific Zone.
+-- If your carrier contains cargo, and the cargo is **moveable**, the **cargo can be unboarded**!
+-- You can only unload cargo if there is cargo within your cargo bays within the carrier.
 -- 
--- In order to deploy cargo, use the task action menu to select a cargo to route to.
--- When selected, the HQ will send you routing messages indicating the location of the deploy zone.
---  
--- Upon arrival at the deploy zone, the HQ will contact you and further instructions will be given.
+-- ![](../Tasking/Unboarding_Menu.png)
 -- 
--- ### 3.4.1) Unboard Cargo.
+-- Select the task action menu and now an **Unboard cargo...** sub menu will be listed!
+-- Again, this option will only be listed if there is a non moveable cargo within your cargo bays.
 -- 
--- If your Carrier is within the **deploy zone**, and the cargo is **moveable**, the **cargo can be unboarded**!
+-- ![](../Tasking/Unboarding_Menu_Engineers.png)
 -- 
--- Select the task action menu and now an **Unboard option** will be listed with the cargo name next to it!
--- Select the option from the action menu, and the cargo will step out of your carrier and will move towards a grouping point.
+-- Now you will see a menu option to unload the non-moveable cargo.
+-- In this example, you can unload the **Engineers** that was loaded within your carrier cargo bays.
+-- Depending on the cargo loaded within your cargo bays, you will see other options here!
+-- Select the relevant menu option from the cargo unload menu, and the cargo will unloaded from your carrier.
+-- 
+-- ![](../Tasking/Unboarding_Started.png)
+-- 
+-- **The cargo will step out of your carrier and will move towards a grouping point.**
+-- When the unboarding process has started, you will be notified by a message to your carrier.
+-- 
+-- ![](../Tasking/Unboarding_In_Progress.png)
 -- 
 -- The moveable cargo will unboard one by one, so note that multiple units may need to unboard your Carrier, 
 -- so it is required to await the full completion of the unboarding process.
--- Once the cargo is fully unboarded from your Carrier, you will be notified of this.
 -- 
--- Note that for airborne Carriers, it is required to land first before the unboarding process can be initiated.
--- If during unboarding the Carrier gets airborne, the unboarding process will be cancelled.
+-- ![](../Tasking/Unboarding_Done.png)
 -- 
--- ### 3.4.2) Unload Cargo.
+-- Once the cargo is fully unboarded from your carrier, you will be notified of this.
+--
+-- **Remarks:**
 -- 
--- If your Carrier is within the **deploy zone**, and the cargo is **stationary**, the **cargo can be unloaded**, but not unboarded!
+--   * For airborne carriers, it is required to land first before the unboarding process can be initiated.
+--     If during unboarding the Carrier gets airborne, the unboarding process will be cancelled.
+--   * Once the moveable cargo is unboarded, they will start moving towards a specified gathering point.
+--   * The moveable cargo will send a message to your carrier with unboarding status updates.
 -- 
--- Select the task action menu and now an **Unload option** will be listed with the cargo name next to it!
--- Select the option from the action menu, and the cargo will unloaded from your carrier.
--- Once the cargo is unloaded fom your Carrier, you will be notified of this.
+-- **Deploying a cargo within a deployment zone, may complete a deployment task! So ensure that you deploy the right cargo at the right deployment zone!**
 -- 
--- Note that for airborne Carriers, it is required to land first at the deploy zone, before the unloading process can be initiated.
+-- #### Unload Cargo.
 -- 
--- ### 3.4.3) Sling Deploy Cargo (helicopters only).
+-- If your carrier contains cargo, and the cargo is **stationary**, the **cargo can be unloaded**, but not unboarded!
+-- You can only unload cargo if there is cargo within your cargo bays within the carrier.
+-- 
+-- ![](../Tasking/Unloading_Menu.png)
+-- 
+-- Select the task action menu and now an **Unload cargo...** sub menu will be listed! 
+-- Again, this option will only be listed if there is a non moveable cargo within your cargo bays.
+-- 
+-- ![](../Tasking/Unloading_Menu_Crate.png)
+-- 
+-- Now you will see a menu option to unload the non-moveable cargo.
+-- In this example, you can unload the **Crate** that was loaded within your carrier cargo bays.
+-- Depending on the cargo loaded within your cargo bays, you will see other options here!
+-- Select the relevant menu option from the cargo unload menu, and the cargo will unloaded from your carrier.
+-- 
+-- ![](../Tasking/Unloading_Done.png)
+-- 
+-- Once the cargo is unloaded fom your Carrier, you may be notified of this, when there is a truck near to the cargo.
+-- If there is no truck near to the unload area, no message will be sent to your carrier!
+-- 
+-- **Remarks:**
+-- 
+--   * For airborne Carriers, it is required to land first, before the unloading process can be initiated.
+--   * A truck must be near the unload area to get messages to your carrier of the unload event!
+--   * Unloading is only for non-moveable cargo.
+--   * The non-moveable cargo must be within your cargo bays, or no unload option will be available.
+--   
+-- **Deploying a cargo within a deployment zone, may complete a deployment task! So ensure that you deploy the right cargo at the right deployment zone!**
+-- 
+-- 
+-- #### Sling Deploy Cargo (helicopters only).
 -- 
 -- If your Carrier is within the **deploy zone**, and the cargo is **stationary**, the **cargo can also be sling deploying**!
 -- Note that this is only possible for helicopters.
 -- 
 -- To sling deploy cargo, there is no task action menu required. Just follow the normal sling deploying procedure.
 -- 
+-- **Deploying a cargo within a deployment zone, may complete a deployment task! So ensure that you deploy the right cargo at the right deployment zone!**
+-- 
+-- ## Cargo tasking from a mission designer perspective.
+-- 
+-- Please consult the documentation how to implement the derived classes of SET_CARGO in:
+-- 
+--   - @{Tasking.Task_Cargo#TASK_CARGO}: Documents the main methods how to handle the cargo tasking from a mission designer perspective.
+--   - @{Tasking.Task_Cargo#TASK_CARGO_TRANSPORT}: Documents the specific methods how to handle the cargo transportation tasking from a mission designer perspective.
+--   - @{Tasking.Task_Cargo#TASK_CARGO_CSAR}: Documents the specific methods how to handle the cargo CSAR tasking from a mission designer perspective.
+--   
+-- 
 -- ===
 -- 
 -- ### Author: **FlightControl**
@@ -364,6 +470,8 @@ do -- TASK_CARGO
   --   * **Success**: The cargo task is successfully completed.
   --   * **Failed**: The cargo task has failed. This will happen if the player exists the task early, without communicating a possible cancellation to HQ.
   -- 
+  -- 
+  -- 
   -- ===
   -- 
   -- @field #TASK_CARGO
@@ -508,7 +616,6 @@ do -- TASK_CARGO
     Fsm:AddTransition( "Rejected", "Reject", "Aborted" )
     Fsm:AddTransition( "Failed", "Fail", "Failed" )
 
-
     ---- @param #FSM_PROCESS self
     -- @param Wrapper.Unit#UNIT TaskUnit
     -- @param #TASK_CARGO Task
@@ -529,7 +636,6 @@ do -- TASK_CARGO
       local TaskUnitName = TaskUnit:GetName()
       local MenuTime = Task:InitTaskControlMenu( TaskUnit )
       local MenuControl = Task:GetTaskControlMenu( TaskUnit )
-      local CargoItemCount = TaskUnit:CargoItemCount()
       
       Task.SetCargo:ForEachCargo(
         
@@ -554,7 +660,13 @@ do -- TASK_CARGO
             local TaskGroup = TaskUnit:GetGroup()
             
             if Cargo:IsUnLoaded() then
-              if CargoItemCount < 1 then 
+              local CargoBayFreeWeight = TaskUnit:GetCargoBayFreeWeight()
+              local CargoWeight = Cargo:GetWeight()
+              
+              self:F({CargoBayFreeWeight=CargoBayFreeWeight})
+  
+              -- Only when there is space within the bay to load the next cargo item!
+              if CargoBayFreeWeight > CargoWeight then 
                 if Cargo:IsInReportRadius( TaskUnit:GetPointVec2() ) then
                   local NotInDeployZones = true
                   for DeployZoneName, DeployZone in pairs( Task.DeployZones ) do
@@ -582,9 +694,12 @@ do -- TASK_CARGO
                             Cargo:Report( "Load at " .. Cargo:GetCoordinate():ToString( TaskUnit:GetGroup() ) .. " within " .. Cargo.NearRadius .. ".", "reporting", TaskUnit:GetGroup() )
                           end
                         else
+                          --local Cargo = Cargo -- Cargo.CargoSlingload#CARGO_SLINGLOAD
                           if Cargo:CanSlingload() == true then
                             if Cargo:IsInLoadRadius( TaskUnit:GetPointVec2() ) then
-                              Cargo:Report( "Ready for slingloading.", "slingload", TaskUnit:GetGroup() )
+                              Cargo:Report( "Ready for sling loading.", "slingload", TaskUnit:GetGroup() )
+                              local SlingloadMenu = MENU_GROUP:New( TaskGroup, "Slingload cargo", MenuControl ):SetTime( MenuTime ):SetTag( "Cargo" )
+                              MENU_GROUP_COMMAND:New( TaskUnit:GetGroup(), Cargo.Name, SlingloadMenu, self.MenuLoadCargo, self, Cargo ):SetTime(MenuTime):SetTag("Cargo"):SetRemoveParent()
                             else
                               Cargo:Report( "Slingload at " .. Cargo:GetCoordinate():ToString( TaskUnit:GetGroup() ) .. ".", "reporting", TaskUnit:GetGroup() )
                             end
@@ -598,8 +713,29 @@ do -- TASK_CARGO
                 else
                   if not Cargo:IsDeployed() == true then
                     local RouteToPickupMenu = MENU_GROUP:New( TaskGroup, "Route to pickup cargo", MenuControl ):SetTime( MenuTime ):SetTag( "Cargo" )
-                    MENU_GROUP_COMMAND:New( TaskUnit:GetGroup(), Cargo.Name, RouteToPickupMenu, self.MenuRouteToPickup, self, Cargo ):SetTime(MenuTime):SetTag("Cargo"):SetRemoveParent()
+                    --MENU_GROUP_COMMAND:New( TaskUnit:GetGroup(), Cargo.Name, RouteToPickupMenu, self.MenuRouteToPickup, self, Cargo ):SetTime(MenuTime):SetTag("Cargo"):SetRemoveParent()
                     Cargo:ReportResetAll( TaskUnit:GetGroup() )
+                    if Cargo:CanBoard() == true then
+                      if not Cargo:IsInLoadRadius( TaskUnit:GetPointVec2() ) then
+                        local BoardMenu = MENU_GROUP:New( TaskGroup, "Board cargo", RouteToPickupMenu ):SetTime( MenuTime ):SetTag( "Cargo" )
+                        MENU_GROUP_COMMAND:New( TaskUnit:GetGroup(), Cargo.Name, BoardMenu, self.MenuRouteToPickup, self, Cargo ):SetTime(MenuTime):SetTag("Cargo"):SetRemoveParent()
+                      end
+                    else
+                      if Cargo:CanLoad() == true then
+                        if not Cargo:IsInLoadRadius( TaskUnit:GetPointVec2() ) then
+                          local LoadMenu = MENU_GROUP:New( TaskGroup, "Load cargo", RouteToPickupMenu ):SetTime( MenuTime ):SetTag( "Cargo" )
+                          MENU_GROUP_COMMAND:New( TaskUnit:GetGroup(), Cargo.Name, LoadMenu, self.MenuRouteToPickup, self, Cargo ):SetTime(MenuTime):SetTag("Cargo"):SetRemoveParent()
+                        end
+                      else
+                        --local Cargo = Cargo -- Cargo.CargoSlingload#CARGO_SLINGLOAD
+                        if Cargo:CanSlingload() == true then
+                          if not Cargo:IsInLoadRadius( TaskUnit:GetPointVec2() ) then
+                            local SlingloadMenu = MENU_GROUP:New( TaskGroup, "Slingload cargo", RouteToPickupMenu ):SetTime( MenuTime ):SetTag( "Cargo" )
+                            MENU_GROUP_COMMAND:New( TaskUnit:GetGroup(), Cargo.Name, SlingloadMenu, self.MenuRouteToPickup, self, Cargo ):SetTime(MenuTime):SetTag("Cargo"):SetRemoveParent()
+                          end
+                        end
+                      end
+                    end
                   end
                 end
               end
@@ -607,11 +743,11 @@ do -- TASK_CARGO
               -- Cargo in deployzones are flagged as deployed.
               for DeployZoneName, DeployZone in pairs( Task.DeployZones ) do
                 if Cargo:IsInZone( DeployZone ) then
-                  Task:E( { CargoIsDeployed = Task.CargoDeployed and "true" or "false" } )
+                  Task:I( { CargoIsDeployed = Task.CargoDeployed and "true" or "false" } )
                   if Cargo:IsDeployed() == false then
                     Cargo:SetDeployed( true )
                     -- Now we call a callback method to handle the CargoDeployed event.
-                    Task:E( { CargoIsAlive = Cargo:IsAlive() and "true" or "false" } )
+                    Task:I( { CargoIsAlive = Cargo:IsAlive() and "true" or "false" } )
                     if Cargo:IsAlive() then
                       Task:CargoDeployed( TaskUnit, Cargo, DeployZone )
                     end
@@ -881,7 +1017,7 @@ do -- TASK_CARGO
           else
             Cargo:MessageToGroup( "Boarding ...", TaskUnit:GetGroup() )
             if not Cargo:IsBoarding() then
-              Cargo:Board( TaskUnit, 20, self )
+              Cargo:Board( TaskUnit, nil, self )
             end
           end
         else
@@ -1225,10 +1361,19 @@ do -- TASK_CARGO
   end
   
   --- @param #TASK_CARGO self
-  function TASK_CARGO:UpdateTaskInfo( DetectedItem )
+  function TASK_CARGO:UpdateTaskInfo()
   
     if self:IsStatePlanned() or self:IsStateAssigned() then
+      self.TaskInfo:AddTaskName( 0, "MSOD" )
       self.TaskInfo:AddCargoSet( self.SetCargo, 10, "SOD", true )
+      local Coordinates = {}
+      for CargoName, Cargo in pairs( self.SetCargo:GetSet() ) do
+        local Cargo = Cargo -- Cargo.Cargo#CARGO
+        if not Cargo:IsLoaded() then
+          Coordinates[#Coordinates+1] = Cargo:GetCoordinate()
+        end
+      end
+      self.TaskInfo:AddCoordinates( Coordinates, 1, "M" )
     end
   end
 

Moose Development/Moose/Tasking/Task_Cargo_CSAR.lua

@@ -152,6 +152,114 @@ do -- TASK_CARGO_CSAR
   -- It is better you use the cargo dispatcher to generate CSAR tasks and it will work as it is intended.
   -- By doing this, CSAR tasking will become a dynamic experience.
   -- 
+  -- # 2) Create a task using the @{Tasking.Task_Cargo_Dispatcher} module.
+  -- 
+  -- Actually, it is better to **GENERATE** these tasks using the @{Tasking.Task_Cargo_Dispatcher} module.
+  -- Using the dispatcher module, transport tasks can be created much more easy.
+  -- 
+  -- Find below an example how to use the TASK_CARGO_DISPATCHER class:
+  -- 
+  -- 
+  --      -- Find the HQ group.
+  --      HQ = GROUP:FindByName( "HQ", "Bravo" )
+  --    
+  --      -- Create the command center with the name "Lima".
+  --      CommandCenter = COMMANDCENTER
+  --        :New( HQ, "Lima" )
+  --    
+  --      -- Create the mission, for the command center, with the name "CSAR Mission", a "Tactical" mission, with the mission briefing "Rescue downed pilots.", for the RED coalition.
+  --      Mission = MISSION
+  --        :New( CommandCenter, "CSAR Mission", "Tactical", "Rescue downed pilots.", coalition.side.RED )
+  --    
+  --      -- Create the SET of GROUPs containing clients (players) that will transport the cargo.
+  --      -- These are have a name that start with "Rescue" and are of the "red" coalition.
+  --      AttackGroups = SET_GROUP:New():FilterCoalitions( "red" ):FilterPrefixes( "Rescue" ):FilterStart()
+  --    
+  --    
+  --      -- Here we create the TASK_CARGO_DISPATCHER object! This is where we assign the dispatcher to generate tasks in the Mission for the AttackGroups.
+  --      TaskDispatcher = TASK_CARGO_DISPATCHER:New( Mission, AttackGroups )
+  --    
+  --      
+  --      -- Here the task dispatcher will generate automatically CSAR tasks once a pilot ejects.
+  --      TaskDispatcher:StartCSARTasks( 
+  --        "CSAR", 
+  --        { ZONE_UNIT:New( "Hospital", STATIC:FindByName( "Hospital" ), 100 ) }, 
+  --        "One of our pilots has ejected. Go out to Search and Rescue our pilot!\n" .. 
+  --        "Use the radio menu to let the command center assist you with the CSAR tasking."
+  --      )
+  -- 
+  -- # 3) Handle cargo task events.
+  -- 
+  -- When a player is picking up and deploying cargo using his carrier, events are generated by the tasks. These events can be captured and tailored with your own code.
+  -- 
+  -- In order to properly capture the events and avoid mistakes using the documentation, it is advised that you execute the following actions:
+  -- 
+  --   * **Copy / Paste** the code section into your script.
+  --   * **Change** the CLASS literal to the task object name you have in your script.
+  --   * Within the function, you can now **write your own code**!
+  --   * **IntelliSense** will recognize the type of the variables provided by the function. Note: the From, Event and To variables can be safely ignored, 
+  --     but you need to declare them as they are automatically provided by the event handling system of MOOSE.
+  -- 
+  -- You can send messages or fire off any other events within the code section. The sky is the limit!
+  -- 
+  -- NOTE: CSAR tasks are actually automatically created by the TASK_CARGO_DISPATCHER. So the underlying is not really applicable for mission designers as they will use the dispatcher instead
+  -- of capturing these events from manually created CSAR tasks!
+  -- 
+  -- ## 3.1) Handle the **CargoPickedUp** event.
+  -- 
+  -- Find below an example how to tailor the **CargoPickedUp** event, generated by the CSARTask:
+  -- 
+  --      function CSARTask:OnAfterCargoPickedUp( From, Event, To, TaskUnit, Cargo )
+  --        
+  --        MESSAGE:NewType( "Unit " .. TaskUnit:GetName().. " has picked up cargo.", MESSAGE.Type.Information ):ToAll()
+  --        
+  --      end
+  -- 
+  -- If you want to code your own event handler, use this code fragment to tailor the event when a player carrier has picked up a cargo object in the CarrierGroup.
+  -- You can use this event handler to post messages to players, or provide status updates etc.
+  -- 
+  --      --- CargoPickedUp event handler OnAfter for CLASS.
+  --      -- @param #CLASS self
+  --      -- @param #string From A string that contains the "*from state name*" when the event was triggered.
+  --      -- @param #string Event A string that contains the "*event name*" when the event was triggered.
+  --      -- @param #string To A string that contains the "*to state name*" when the event was triggered.
+  --      -- @param Wrapper.Unit#UNIT TaskUnit The unit (client) of the player that has picked up the cargo.
+  --      -- @param Cargo.Cargo#CARGO Cargo The cargo object that has been picked up. Note that this can be a CARGO_GROUP, CARGO_CRATE or CARGO_SLINGLOAD object!
+  --      function CLASS:OnAfterCargoPickedUp( From, Event, To, TaskUnit, Cargo )
+  --      
+  --        -- Write here your own code.
+  --      
+  --      end
+  -- 
+  -- 
+  -- ## 3.2) Handle the **CargoDeployed** event.
+  -- 
+  -- Find below an example how to tailor the **CargoDeployed** event, generated by the CSARTask:
+  -- 
+  --      function CSARTask:OnAfterCargoDeployed( From, Event, To, TaskUnit, Cargo, DeployZone )
+  --        
+  --        MESSAGE:NewType( "Unit " .. TaskUnit:GetName().. " has deployed cargo at zone " .. DeployZone:GetName(), MESSAGE.Type.Information ):ToAll()
+  --        
+  --      end
+  -- 
+  -- If you want to code your own event handler, use this code fragment to tailor the event when a player carrier has deployed a cargo object from the CarrierGroup.
+  -- You can use this event handler to post messages to players, or provide status updates etc.
+  -- 
+  -- 
+  --      --- CargoDeployed event handler OnAfter for CLASS.
+  --      -- @param #CLASS self
+  --      -- @param #string From A string that contains the "*from state name*" when the event was triggered.
+  --      -- @param #string Event A string that contains the "*event name*" when the event was triggered.
+  --      -- @param #string To A string that contains the "*to state name*" when the event was triggered.
+  --      -- @param Wrapper.Unit#UNIT TaskUnit The unit (client) of the player that has deployed the cargo.
+  --      -- @param Cargo.Cargo#CARGO Cargo The cargo object that has been deployed. Note that this can be a CARGO_GROUP, CARGO_CRATE or CARGO_SLINGLOAD object!
+  --      -- @param Core.Zone#ZONE DeployZone The zone wherein the cargo is deployed. This can be any zone type, like a ZONE, ZONE_GROUP, ZONE_AIRBASE.
+  --      function CLASS:OnAfterCargoDeployed( From, Event, To, TaskUnit, Cargo, DeployZone )
+  --      
+  --        -- Write here your own code.
+  --      
+  --      end
+  --      
   -- ===
   -- 
   -- @field #TASK_CARGO_CSAR
@@ -181,16 +289,6 @@ do -- TASK_CARGO_CSAR
     
     self:F( { CargoDeployed = self.CargoDeployed ~= nil and "true" or "false" } )
     
-      --- OnBefore Transition Handler for Event CargoPickedUp.
-      -- @function [parent=#TASK_CARGO_CSAR] OnBeforeCargoPickedUp
-      -- @param #TASK_CARGO_CSAR self
-      -- @param #string From The From State string.
-      -- @param #string Event The Event string.
-      -- @param #string To The To State string.
-      -- @param Wrapper.Unit#UNIT TaskUnit The Unit (Client) that PickedUp the cargo. You can use this to retrieve the PlayerName etc.
-      -- @param Core.Cargo#CARGO Cargo The Cargo that got PickedUp by the TaskUnit. You can use this to check Cargo Status.
-      -- @return #boolean Return false to cancel Transition.
-      
       --- OnAfter Transition Handler for Event CargoPickedUp.
       -- @function [parent=#TASK_CARGO_CSAR] OnAfterCargoPickedUp
       -- @param #TASK_CARGO_CSAR self
@@ -200,30 +298,6 @@ do -- TASK_CARGO_CSAR
       -- @param Wrapper.Unit#UNIT TaskUnit The Unit (Client) that PickedUp the cargo. You can use this to retrieve the PlayerName etc.
       -- @param Core.Cargo#CARGO Cargo The Cargo that got PickedUp by the TaskUnit. You can use this to check Cargo Status.
         
-      --- Synchronous Event Trigger for Event CargoPickedUp.
-      -- @function [parent=#TASK_CARGO_CSAR] CargoPickedUp
-      -- @param #TASK_CARGO_CSAR self
-      -- @param Wrapper.Unit#UNIT TaskUnit The Unit (Client) that PickedUp the cargo. You can use this to retrieve the PlayerName etc.
-      -- @param Core.Cargo#CARGO Cargo The Cargo that got PickedUp by the TaskUnit. You can use this to check Cargo Status.
-      
-      --- Asynchronous Event Trigger for Event CargoPickedUp.
-      -- @function [parent=#TASK_CARGO_CSAR] __CargoPickedUp
-      -- @param #TASK_CARGO_CSAR self
-      -- @param #number Delay The delay in seconds.
-      -- @param Wrapper.Unit#UNIT TaskUnit The Unit (Client) that PickedUp the cargo. You can use this to retrieve the PlayerName etc.
-      -- @param Core.Cargo#CARGO Cargo The Cargo that got PickedUp by the TaskUnit. You can use this to check Cargo Status.
-    
-      --- OnBefore Transition Handler for Event CargoDeployed.
-      -- @function [parent=#TASK_CARGO_CSAR] OnBeforeCargoDeployed
-      -- @param #TASK_CARGO_CSAR self
-      -- @param #string From The From State string.
-      -- @param #string Event The Event string.
-      -- @param #string To The To State string.
-      -- @param Wrapper.Unit#UNIT TaskUnit The Unit (Client) that Deployed the cargo. You can use this to retrieve the PlayerName etc.
-      -- @param Core.Cargo#CARGO Cargo The Cargo that got PickedUp by the TaskUnit. You can use this to check Cargo Status.
-      -- @param Core.Zone#ZONE DeployZone The zone where the Cargo got Deployed or UnBoarded.
-      -- @return #boolean Return false to cancel Transition.
-      
       --- OnAfter Transition Handler for Event CargoDeployed.
       -- @function [parent=#TASK_CARGO_CSAR] OnAfterCargoDeployed
       -- @param #TASK_CARGO_CSAR self
@@ -234,21 +308,6 @@ do -- TASK_CARGO_CSAR
       -- @param Core.Cargo#CARGO Cargo The Cargo that got PickedUp by the TaskUnit. You can use this to check Cargo Status.
       -- @param Core.Zone#ZONE DeployZone The zone where the Cargo got Deployed or UnBoarded.
         
-      --- Synchronous Event Trigger for Event CargoDeployed.
-      -- @function [parent=#TASK_CARGO_CSAR] CargoDeployed
-      -- @param #TASK_CARGO_CSAR self
-      -- @param Wrapper.Unit#UNIT TaskUnit The Unit (Client) that Deployed the cargo. You can use this to retrieve the PlayerName etc.
-      -- @param Core.Cargo#CARGO Cargo The Cargo that got PickedUp by the TaskUnit. You can use this to check Cargo Status.
-      -- @param Core.Zone#ZONE DeployZone The zone where the Cargo got Deployed or UnBoarded.
-      
-      --- Asynchronous Event Trigger for Event CargoDeployed.
-      -- @function [parent=#TASK_CARGO_CSAR] __CargoDeployed
-      -- @param #TASK_CARGO_CSAR self
-      -- @param #number Delay The delay in seconds.
-      -- @param Wrapper.Unit#UNIT TaskUnit The Unit (Client) that Deployed the cargo. You can use this to retrieve the PlayerName etc.
-      -- @param Core.Cargo#CARGO Cargo The Cargo that got PickedUp by the TaskUnit. You can use this to check Cargo Status.
-      -- @param Core.Zone#ZONE DeployZone The zone where the Cargo got Deployed or UnBoarded.
-
     local Fsm = self:GetUnitProcess()
 
     local CargoReport = REPORT:New( "Rescue a downed pilot from the following position:")
@@ -271,6 +330,8 @@ do -- TASK_CARGO_CSAR
     
     return self
   end 
+  
+
 
   function TASK_CARGO_CSAR:ReportOrder( ReportGroup ) 
     

Moose Development/Moose/Tasking/Task_Cargo_Dispatcher.lua

@@ -1,5 +1,58 @@
 --- **Tasking** - Creates and manages player TASK_CARGO tasks.
 -- 
+-- The **TASK_CARGO_DISPATCHER** allows you to setup various tasks for let human
+-- players transport cargo as part of a task. 
+--  
+-- The cargo dispatcher will implement for you mechanisms to create cargo transportation tasks:
+--  
+--   * As setup by the mission designer.
+--   * Dynamically create CSAR missions (when a pilot is downed as part of a downed plane).
+--   * Dynamically spawn new cargo and create cargo taskings!
+--   
+-- 
+--   
+-- **Specific features:**
+-- 
+--   * Creates a task to transport @{Cargo.Cargo} to and between deployment zones.
+--   * Derived from the TASK_CARGO class, which is derived from the TASK class.
+--   * Orchestrate the task flow, so go from Planned to Assigned to Success, Failed or Cancelled.
+--   * Co-operation tasking, so a player joins a group of players executing the same task.
+-- 
+-- 
+-- **A complete task menu system to allow players to:**
+--   
+--   * Join the task, abort the task.
+--   * Mark the task location on the map.
+--   * Provide details of the target.
+--   * Route to the cargo.
+--   * Route to the deploy zones.
+--   * Load/Unload cargo.
+--   * Board/Unboard cargo.
+--   * Slingload cargo.
+--   * Display the task briefing.
+--   
+--   
+-- **A complete mission menu system to allow players to:**
+--   
+--   * Join a task, abort the task.
+--   * Display task reports.
+--   * Display mission statistics.
+--   * Mark the task locations on the map.
+--   * Provide details of the targets.
+--   * Display the mission briefing.
+--   * Provide status updates as retrieved from the command center.
+--   * Automatically assign a random task as part of a mission.
+--   * Manually assign a specific task as part of a mission.
+--   
+--   
+--  **A settings system, using the settings menu:**
+--  
+--   * Tweak the duration of the display of messages.
+--   * Switch between metric and imperial measurement system.
+--   * Switch between coordinate formats used in messages: BR, BRA, LL DMS, LL DDM, MGRS.
+--   * Different settings modes for A2G and A2A operations.
+--   * Various other options.
+--   
 -- ===
 -- 
 -- ### Author: **FlightControl**
@@ -9,7 +62,7 @@
 -- ===
 -- 
 -- @module Tasking.Task_Cargo_Dispatcher
--- @image MOOSE.JPG
+-- @image Task_Cargo_Dispatcher.JPG
 
 do -- TASK_CARGO_DISPATCHER
 
@@ -17,6 +70,7 @@ do -- TASK_CARGO_DISPATCHER
   -- @type TASK_CARGO_DISPATCHER
   -- @extends Tasking.Task_Manager#TASK_MANAGER
   -- @field TASK_CARGO_DISPATCHER.CSAR CSAR
+  -- @field Core.Set#SET_ZONE SetZonesCSAR
 
   --- @type TASK_CARGO_DISPATCHER.CSAR
   -- @field Wrapper.Unit#UNIT PilotUnit
@@ -25,148 +79,292 @@ do -- TASK_CARGO_DISPATCHER
 
   --- Implements the dynamic dispatching of cargo tasks.
   -- 
-  -- ![Banner Image](..\Presentations\TASK_CARGO_DISPATCHER\Dia3.JPG)
+  -- The **TASK_CARGO_DISPATCHER** allows you to setup various tasks for let human
+  -- players transport cargo as part of a task. 
   -- 
-  -- The EWR will detect units, will group them, and will dispatch @{Task}s to groups. Depending on the type of target detected, different tasks will be dispatched.
-  -- Find a summary below describing for which situation a task type is created:
+  -- There are currently **two types of tasks** that can be constructed:
   -- 
-  -- ![Banner Image](..\Presentations\TASK_CARGO_DISPATCHER\Dia9.JPG)
+  --   * A **normal cargo transport** task, which tasks humans to transport cargo from a location towards a deploy zone.
+  --   * A **CSAR** cargo transport task. CSAR tasks are **automatically generated** when a friendly (AI) plane is downed and the friendly pilot ejects... 
+  --   You as a player (the helo pilot) can go out in the battlefield, fly behind enemy lines, and rescue the pilot (back to a deploy zone).
   -- 
-  --   * **CSAR Task**: Is created when a fiendly pilot has ejected from a plane, and needs to be rescued (sometimes behind enemy lines).
+  -- Let's explore **step by step** how to setup the task cargo dispatcher.
   -- 
-  -- ## 1. TASK\_A2A\_DISPATCHER constructor:
+  -- # 1. Setup a mission environment.
   -- 
-  -- The @{#TASK_CARGO_DISPATCHER.New}() method creates a new TASK\_A2A\_DISPATCHER instance.
+  -- It is easy, as it works just like any other task setup, so setup a command center and a mission.
   -- 
-  -- ### 1.1. Define or set the **Mission**:
+  -- ## 1.1. Create a command center.
   -- 
-  -- Tasking is executed to accomplish missions. Therefore, a MISSION object needs to be given as the first parameter.
+  -- First you need to create a command center using the @{Tasking.CommandCenter#COMMANDCENTER.New}() constructor.
   -- 
-  --     local HQ = GROUP:FindByName( "HQ", "Bravo" )
-  --     local CommandCenter = COMMANDCENTER:New( HQ, "Lima" )
-  --     local Mission = MISSION:New( CommandCenter, "A2A Mission", "High", "Watch the air enemy units being detected.", coalition.side.RED )
-  -- 
-  -- Missions are governed by COMMANDCENTERS, so, ensure you have a COMMANDCENTER object installed and setup within your mission.
-  -- Create the MISSION object, and hook it under the command center.
-  -- 
-  -- ### 1.2. Build a set of the groups seated by human players:
-  -- 
-  -- ![Banner Image](..\Presentations\TASK_CARGO_DISPATCHER\Dia6.JPG)
-  -- 
-  -- A set or collection of the groups wherein human players can be seated, these can be clients or units that can be joined as a slot or jumping into.
+  --     local CommandCenter = COMMANDCENTER
+  --        :New( HQ, "Lima" ) -- Create the CommandCenter.
   --     
-  --     local AttackGroups = SET_GROUP:New():FilterCoalitions( "red" ):FilterPrefixes( "Defender" ):FilterStart()
-  --     
-  -- The set is built using the SET_GROUP class. Apply any filter criteria to identify the correct groups for your mission.
-  -- Only these slots or units will be able to execute the mission and will receive tasks for this mission, once available.
+  -- ## 1.2. Create a mission.
   -- 
-  -- ### 1.3. Define the **EWR network**:
+  -- Tasks work in a mission, which groups these tasks to achieve a joint mission goal.
+  -- A command center can govern multiple missions.
+  -- Create a new mission, using the @{Tasking.Mission#MISSION.New}() constructor.
   -- 
-  -- As part of the TASK\_A2A\_DISPATCHER constructor, an EWR network must be given as the third parameter.
-  -- An EWR network, or, Early Warning Radar network, is used to early detect potential airborne targets and to understand the position of patrolling targets of the enemy.
+  --     -- Declare the Mission for the Command Center.
+  --     local Mission = MISSION
+  --       :New( CommandCenter, 
+  --             "Overlord", 
+  --             "High", 
+  --             "Transport the cargo.", 
+  --             coalition.side.RED 
+  --           ) 
   -- 
-  -- ![Banner Image](..\Presentations\TASK_CARGO_DISPATCHER\Dia5.JPG)
   -- 
-  -- Typically EWR networks are setup using 55G6 EWR, 1L13 EWR, Hawk sr and Patriot str ground based radar units. 
-  -- These radars have different ranges and 55G6 EWR and 1L13 EWR radars are Eastern Bloc units (eg Russia, Ukraine, Georgia) while the Hawk and Patriot radars are Western (eg US).
-  -- Additionally, ANY other radar capable unit can be part of the EWR network! Also AWACS airborne units, planes, helicopters can help to detect targets, as long as they have radar.
-  -- The position of these units is very important as they need to provide enough coverage 
-  -- to pick up enemy aircraft as they approach so that CAP and GCI flights can be tasked to intercept them.
+  -- # 2. Dispatch a **transport cargo** task.
   -- 
-  -- ![Banner Image](..\Presentations\TASK_CARGO_DISPATCHER\Dia7.JPG)
+  -- So, now that we have a command center and a mission, we now create the transport task.
+  -- We create the transport task using the @{#TASK_CARGO_DISPATCHER.AddTransportTask}() constructor.
+  -- 
+  -- ## 2.1. Create the cargo in the mission.
+  -- 
+  -- Because a transport task will not generate the cargo itself, you'll need to create it first.
+  -- 
+  --     -- Here we define the "cargo set", which is a collection of cargo objects.
+  --     -- The cargo set will be the input for the cargo transportation task.
+  --     -- So a transportation object is handling a cargo set, which is automatically updated when new cargo is added/deleted.
+  --     local WorkmaterialsCargoSet = SET_CARGO:New():FilterTypes( "Workmaterials" ):FilterStart()
+  --    
+  --     -- Now we add cargo into the battle scene.
+  --     local PilotGroup = GROUP:FindByName( "Engineers" )
+  --      
+  --     -- CARGO_GROUP can be used to setup cargo with a GROUP object underneath.
+  --     -- We name the type of this group "Workmaterials", so that this cargo group will be included within the WorkmaterialsCargoSet.
+  --     -- Note that the name of the cargo is "Engineer Team 1".
+  --     local CargoGroup = CARGO_GROUP:New( PilotGroup, "Workmaterials", "Engineer Team 1", 500 )
+  -- 
+  -- What is also needed, is to have a set of @{Core.Group}s defined that contains the clients of the players.
+  -- 
+  --     -- Allocate the Transport, which are the helicopters to retrieve the pilot, that can be manned by players.
+  --     -- The name of these helicopter groups containing one client begins with "Transport", as modelled within the mission editor.
+  --     local PilotGroupSet = SET_GROUP:New():FilterPrefixes( "Transport" ):FilterStart()
+  -- 
+  -- ## 2.2. Setup the cargo transport task.
+  -- 
+  -- First, we need to create a TASK_CARGO_DISPATCHER object.
+  -- 
+  --     TaskDispatcher = TASK_CARGO_DISPATCHER:New( Mission, PilotGroupSet )
+  -- 
+  -- So, the variable `TaskDispatcher` will contain the object of class TASK_CARGO_DISPATCHER, which will allow you to dispatch cargo transport tasks:
   --  
-  -- Additionally in a hot war situation where the border is no longer respected the placement of radars has a big effect on how fast the war escalates. 
-  -- For example if they are a long way forward and can detect enemy planes on the ground and taking off 
-  -- they will start to vector CAP and GCI flights to attack them straight away which will immediately draw a response from the other coalition. 
-  -- Having the radars further back will mean a slower escalation because fewer targets will be detected and 
-  -- therefore less CAP and GCI flights will spawn and this will tend to make just the border area active rather than a melee over the whole map. 
-  -- It all depends on what the desired effect is. 
+  --   * for mission `Mission`.
+  --   * for the group set `PilotGroupSet`.
   -- 
-  -- EWR networks are **dynamically constructed**, that is, they form part of the @{Functional.Detection#DETECTION_BASE} object that is given as the input parameter of the TASK\_A2A\_DISPATCHER class.
-  -- By defining in a **smart way the names or name prefixes of the groups** with EWR capable units, these groups will be **automatically added or deleted** from the EWR network, 
-  -- increasing or decreasing the radar coverage of the Early Warning System.
+  -- Now that we have `TaskDispatcher` object, we can now **create the TransportTask**, using the @{#TASK_CARGO_DISPATCHER.AddTransportTask}() method!
   -- 
-  -- See the following example to setup an EWR network containing EWR stations and AWACS.
+  --     local TransportTask = TaskDispatcher:AddTransportTask( 
+  --       "Transport workmaterials", 
+  --       WorkmaterialsCargoSet, 
+  --       "Transport the workers, engineers and the equipment near the Workplace." )
   -- 
-  --     local EWRSet = SET_GROUP:New():FilterPrefixes( "EWR" ):FilterCoalitions("red"):FilterStart()
-  --
-  --     local EWRDetection = DETECTION_AREAS:New( EWRSet, 6000 )
-  --     EWRDetection:SetFriendliesRange( 10000 )
-  --     EWRDetection:SetRefreshTimeInterval(30)
-  --
-  --     -- Setup the A2A dispatcher, and initialize it.
-  --     A2ADispatcher = TASK_CARGO_DISPATCHER:New( Mission, AttackGroups, EWRDetection )
+  -- As a result of this code, the `TransportTask` (returned) variable will contain an object of @{#TASK_CARGO_TRANSPORT}!
+  -- We pass to the method the title of the task, and the `WorkmaterialsCargoSet`, which is the set of cargo groups to be transported!
+  -- This object can also be used to setup additional things, or to control this specific task with special actions.
   -- 
-  -- The above example creates a SET_GROUP instance, and stores this in the variable (object) **EWRSet**.
-  -- **EWRSet** is then being configured to filter all active groups with a group name starting with **EWR** to be included in the Set.
-  -- **EWRSet** is then being ordered to start the dynamic filtering. Note that any destroy or new spawn of a group with the above names will be removed or added to the Set.
-  -- Then a new **EWRDetection** object is created from the class DETECTION_AREAS. A grouping radius of 6000 is choosen, which is 6km.
-  -- The **EWRDetection** object is then passed to the @{#TASK_CARGO_DISPATCHER.New}() method to indicate the EWR network configuration and setup the A2A tasking and detection mechanism.
+  -- And you're done! As you can see, it is a bit of work, but the reward is great.
+  -- And, because all this is done using program interfaces, you can build a mission with a **dynamic cargo transport task mechanism** yourself!
+  -- Based on events happening within your mission, you can use the above methods to create new cargo, and setup a new task for cargo transportation to a group of players!
   -- 
-  -- ### 2. Define the detected **target grouping radius**:
+  --     
+  -- # 3. Dispatch CSAR tasks.
   -- 
-  -- ![Banner Image](..\Presentations\TASK_CARGO_DISPATCHER\Dia8.JPG)
+  -- CSAR tasks can be dynamically created when a friendly pilot ejects, or can be created manually.
+  -- We'll explore both options.
   -- 
-  -- The target grouping radius is a property of the Detection object, that was passed to the AI\_A2A\_DISPATCHER object, but can be changed.
-  -- The grouping radius should not be too small, but also depends on the types of planes and the era of the simulation.
-  -- Fast planes like in the 80s, need a larger radius than WWII planes.  
-  -- Typically I suggest to use 30000 for new generation planes and 10000 for older era aircraft.
+  -- ## 3.1. CSAR task dynamic creation.
   -- 
-  -- Note that detected targets are constantly re-grouped, that is, when certain detected aircraft are moving further than the group radius, then these aircraft will become a separate
-  -- group being detected. This may result in additional GCI being started by the dispatcher! So don't make this value too small!
+  -- Because there is an "event" in a running simulation that creates CSAR tasks, the method @{#TASK_CARGO_DISPATCHER.StartCSARTasks}() will create automatically:
   -- 
-  -- ## 3. Set the **Engage radius**:
+  --   1. a new downed pilot at the location where the plane was shot
+  --   2. declare that pilot as cargo
+  --   3. creates a CSAR task automatically to retrieve that pilot
+  --   4. requires deploy zones to be specified where to transport the downed pilot to, in order to complete that task.
   -- 
-  -- Define the radius to engage any target by airborne friendlies, which are executing cap or returning from an intercept mission.
+  -- You create a CSAR task dynamically in a very easy way:
   -- 
-  -- ![Banner Image](..\Presentations\TASK_CARGO_DISPATCHER\Dia11.JPG)
+  --     TaskDispatcher:StartCSARTasks( 
+  --       "CSAR", 
+  --       { ZONE_UNIT:New( "Hospital", STATIC:FindByName( "Hospital" ), 100 ) }, 
+  --       "One of our pilots has ejected. Go out to Search and Rescue our pilot!\n" .. 
+  --       "Use the radio menu to let the command center assist you with the CSAR tasking."
+  --     )
   -- 
-  -- So, if there is a target area detected and reported, 
-  -- then any friendlies that are airborne near this target area, 
-  -- will be commanded to (re-)engage that target when available (if no other tasks were commanded).
-  -- For example, if 100000 is given as a value, then any friendly that is airborne within 100km from the detected target, 
-  -- will be considered to receive the command to engage that target area.
-  -- You need to evaluate the value of this parameter carefully.
-  -- If too small, more intercept missions may be triggered upon detected target areas.
-  -- If too large, any airborne cap may not be able to reach the detected target area in time, because it is too far.
+  -- The method @{#TASK_CARGO_DISPATCHER.StopCSARTasks}() will automatically stop with the creation of CSAR tasks when friendly pilots eject.
   -- 
-  -- ## 4. Set **Scoring** and **Messages**:
+  -- **Remarks:** 
+  --   
+  --   * the ZONE_UNIT can also be a ZONE, or a ZONE_POLYGON object, or any other ZONE_ object!
+  --   * you can declare the array of zones in another variable, or course!
   -- 
-  -- The TASK\_A2A\_DISPATCHER is a state machine. It triggers the event Assign when a new player joins a @{Task} dispatched by the TASK\_A2A\_DISPATCHER.
-  -- An _event handler_ can be defined to catch the **Assign** event, and add **additional processing** to set _scoring_ and to _define messages_,
-  -- when the player reaches certain achievements in the task.
   -- 
-  -- The prototype to handle the **Assign** event needs to be developed as follows:
+  -- ## 3.2. CSAR task manual creation.
   -- 
-  --      TaskDispatcher = TASK_CARGO_DISPATCHER:New( ... )
+  -- We create the CSAR task using the @{#TASK_CARGO_DISPATCHER.AddCSARTask}() constructor.
   -- 
-  --      --- @param #TaskDispatcher self
-  --      -- @param #string From Contains the name of the state from where the Event was triggered.
-  --      -- @param #string Event Contains the name of the event that was triggered. In this case Assign.
-  --      -- @param #string To Contains the name of the state that will be transitioned to.
-  --      -- @param Tasking.Task_A2A#TASK_A2A Task The Task object, which is any derived object from TASK_A2A.
-  --      -- @param Wrapper.Unit#UNIT TaskUnit The Unit or Client that contains the Player.
-  --      -- @param #string PlayerName The name of the Player that joined the TaskUnit.
-  --      function TaskDispatcher:OnAfterAssign( From, Event, To, Task, TaskUnit, PlayerName )
-  --        Task:SetScoreOnProgress( PlayerName, 20, TaskUnit )
-  --        Task:SetScoreOnSuccess( PlayerName, 200, TaskUnit )
-  --        Task:SetScoreOnFail( PlayerName, -100, TaskUnit )
+  -- The method will create a new CSAR task, and will generate the pilots cargo itself, at the specified coordinate.
+  -- 
+  -- What is first needed, is to have a set of @{Core.Group}s defined that contains the clients of the players.
+  -- 
+  --     -- Allocate the Transport, which are the helicopter to retrieve the pilot, that can be manned by players.
+  --     local GroupSet = SET_GROUP:New():FilterPrefixes( "Transport" ):FilterStart()
+  -- 
+  -- We need to create a TASK_CARGO_DISPATCHER object.
+  -- 
+  --     TaskDispatcher = TASK_CARGO_DISPATCHER:New( Mission, GroupSet )
+  -- 
+  -- So, the variable `TaskDispatcher` will contain the object of class TASK_CARGO_DISPATCHER, which will allow you to dispatch cargo CSAR tasks:
+  --  
+  --   * for mission `Mission`.
+  --   * for the group of players (pilots) captured within the `GroupSet` (those groups with a name starting with `"Transport"`).
+  -- 
+  -- Now that we have a PilotsCargoSet and a GroupSet, we can now create the CSAR task manually.
+  -- 
+  --     -- Declare the CSAR task.
+  --     local CSARTask = TaskDispatcher:AddCSARTask( 
+  --       "CSAR Task",
+  --       Coordinate,
+  --       270,
+  --       "Bring the pilot back!"
+  --     )
+  -- 
+  -- As a result of this code, the `CSARTask` (returned) variable will contain an object of @{#TASK_CARGO_CSAR}!
+  -- We pass to the method the title of the task, and the `WorkmaterialsCargoSet`, which is the set of cargo groups to be transported!
+  -- This object can also be used to setup additional things, or to control this specific task with special actions.
+  -- Note that when you declare a CSAR task manually, you'll still need to specify a deployment zone!
+  -- 
+  -- # 4. Setup the deploy zone(s).
+  -- 
+  -- The task cargo dispatcher also foresees methods to setup the deployment zones to where the cargo needs to be transported!
+  -- 
+  -- There are two levels on which deployment zones can be configured:
+  -- 
+  --   * Default deploy zones: The TASK_CARGO_DISPATCHER object can have default deployment zones, which will apply over all tasks active in the task dispatcher.
+  --   * Task specific deploy zones: The TASK_CARGO_DISPATCHER object can have specific deployment zones which apply to a specific task only!
+  -- 
+  -- Note that for Task specific deployment zones, there are separate deployment zone creation methods per task type!
+  -- 
+  -- ## 4.1. Setup default deploy zones.
+  -- 
+  -- Use the @{#TASK_CARGO_DISPATCHER.SetDefaultDeployZone}() to setup one deployment zone, and @{#TASK_CARGO_DISPATCHER.SetDefaultDeployZones}() to setup multiple default deployment zones in one call.
+  -- 
+  -- ## 4.2. Setup task specific deploy zones for a **transport task**.
+  -- 
+  -- Use the @{#TASK_CARGO_DISPATCHER.SetTransportDeployZone}() to setup one deployment zone, and @{#TASK_CARGO_DISPATCHER.SetTransportDeployZones}() to setup multiple default deployment zones in one call.
+  -- 
+  -- ## 4.3. Setup task specific deploy zones for a **CSAR task**. 
+  -- 
+  -- Use the @{#TASK_CARGO_DISPATCHER.SetCSARDeployZone}() to setup one deployment zone, and @{#TASK_CARGO_DISPATCHER.SetCSARDeployZones}() to setup multiple default deployment zones in one call.
+  -- 
+  -- ## 4.4. **CSAR ejection zones**. 
+  -- 
+  -- Setup a set of zones where the pilots will only eject and a task is created for CSAR. When such a set of zones is given, any ejection outside those zones will not result in a pilot created for CSAR!
+  -- 
+  -- Use the @{#TASK_CARGO_DISPATCHER.SetCSARZones}() to setup the set of zones.
+  -- 
+  -- ## 4.5. **CSAR ejection maximum**.
+  -- 
+  -- Setup how many pilots will eject the maximum. This to avoid an overload of CSAR tasks being created :-) The default is endless CSAR tasks.
+  -- 
+  -- Use the @{#TASK_CARGO_DISPATCHER.SetMaxCSAR}() to setup the maximum of pilots that will eject for CSAR.
+  -- 
+  -- 
+  -- # 5) Handle cargo task events.
+  -- 
+  -- When a player is picking up and deploying cargo using his carrier, events are generated by the dispatcher. These events can be captured and tailored with your own code.
+  -- 
+  -- In order to properly capture the events and avoid mistakes using the documentation, it is advised that you execute the following actions:
+  -- 
+  --   * **Copy / Paste** the code section into your script.
+  --   * **Change** the CLASS literal to the task object name you have in your script.
+  --   * Within the function, you can now **write your own code**!
+  --   * **IntelliSense** will recognize the type of the variables provided by the function. Note: the From, Event and To variables can be safely ignored, 
+  --     but you need to declare them as they are automatically provided by the event handling system of MOOSE.
+  -- 
+  -- You can send messages or fire off any other events within the code section. The sky is the limit!
+  -- 
+  -- First, we need to create a TASK_CARGO_DISPATCHER object.
+  -- 
+  --      TaskDispatcher = TASK_CARGO_DISPATCHER:New( Mission, PilotGroupSet )
+  -- 
+  -- Second, we create a new cargo transport task for the transportation of workmaterials.
+  -- 
+  --      TaskDispatcher:AddTransportTask( 
+  --        "Transport workmaterials", 
+  --        WorkmaterialsCargoSet, 
+  --        "Transport the workers, engineers and the equipment near the Workplace." )
+  -- 
+  -- Note that we don't really need to keep the resulting task, it is kept internally also in the dispatcher.
+  -- 
+  -- Using the `TaskDispatcher` object, we can now cpature the CargoPickedUp and CargoDeployed events.
+  -- 
+  -- ## 5.1) Handle the **CargoPickedUp** event.
+  -- 
+  -- Find below an example how to tailor the **CargoPickedUp** event, generated by the `TaskDispatcher`:
+  -- 
+  --      function TaskDispatcher:OnAfterCargoPickedUp( From, Event, To, Task, TaskPrefix, TaskUnit, Cargo )
+  --        
+  --        MESSAGE:NewType( "Unit " .. TaskUnit:GetName().. " has picked up cargo for task " .. Task:GetName() .. ".", MESSAGE.Type.Information ):ToAll()
+  --        
   --      end
   -- 
-  -- The **OnAfterAssign** method (function) is added to the TaskDispatcher object.
-  -- This method will be called when a new player joins a unit in the set of groups in scope of the dispatcher.
-  -- So, this method will be called only **ONCE** when a player joins a unit in scope of the task.
+  -- If you want to code your own event handler, use this code fragment to tailor the event when a player carrier has picked up a cargo object in the CarrierGroup.
+  -- You can use this event handler to post messages to players, or provide status updates etc.
+  -- 
+  --      --- CargoPickedUp event handler OnAfter for CLASS.
+  --      -- @param #CLASS self
+  --      -- @param #string From A string that contains the "*from state name*" when the event was triggered.
+  --      -- @param #string Event A string that contains the "*event name*" when the event was triggered.
+  --      -- @param #string To A string that contains the "*to state name*" when the event was triggered.
+  --      -- @param Tasking.Task_Cargo#TASK_CARGO Task The cargo task for which the cargo has been picked up. Note that this will be a derived TAKS_CARGO object!
+  --      -- @param #string TaskPrefix The prefix of the task that was provided when the task was created.
+  --      -- @param Wrapper.Unit#UNIT TaskUnit The unit (client) of the player that has picked up the cargo.
+  --      -- @param Cargo.Cargo#CARGO Cargo The cargo object that has been picked up. Note that this can be a CARGO_GROUP, CARGO_CRATE or CARGO_SLINGLOAD object!
+  --      function CLASS:OnAfterCargoPickedUp( From, Event, To, Task, TaskPrefix, TaskUnit, Cargo )
+  --      
+  --        -- Write here your own code.
+  --      
+  --      end
+  -- 
+  -- 
+  -- ## 5.2) Handle the **CargoDeployed** event.
+  -- 
+  -- Find below an example how to tailor the **CargoDeployed** event, generated by the `TaskDispatcher`:
+  -- 
+  --       function WorkplaceTask:OnAfterCargoDeployed( From, Event, To, Task, TaskPrefix, TaskUnit, Cargo, DeployZone )
+  --        
+  --         MESSAGE:NewType( "Unit " .. TaskUnit:GetName().. " has deployed cargo at zone " .. DeployZone:GetName() .. " for task " .. Task:GetName() .. ".", MESSAGE.Type.Information ):ToAll()
+  --        
+  --         Helos[ math.random(1,#Helos) ]:Spawn()
+  --         EnemyHelos[ math.random(1,#EnemyHelos) ]:Spawn()
+  --       end
+  -- 
+  -- If you want to code your own event handler, use this code fragment to tailor the event when a player carrier has deployed a cargo object from the CarrierGroup.
+  -- You can use this event handler to post messages to players, or provide status updates etc.
+  -- 
+  -- 
+  --      --- CargoDeployed event handler OnAfter for CLASS.
+  --      -- @param #CLASS self
+  --      -- @param #string From A string that contains the "*from state name*" when the event was triggered.
+  --      -- @param #string Event A string that contains the "*event name*" when the event was triggered.
+  --      -- @param #string To A string that contains the "*to state name*" when the event was triggered.
+  --      -- @param Tasking.Task_Cargo#TASK_CARGO Task The cargo task for which the cargo has been deployed. Note that this will be a derived TAKS_CARGO object!
+  --      -- @param #string TaskPrefix The prefix of the task that was provided when the task was created.
+  --      -- @param Wrapper.Unit#UNIT TaskUnit The unit (client) of the player that has deployed the cargo.
+  --      -- @param Cargo.Cargo#CARGO Cargo The cargo object that has been deployed. Note that this can be a CARGO_GROUP, CARGO_CRATE or CARGO_SLINGLOAD object!
+  --      -- @param Core.Zone#ZONE DeployZone The zone wherein the cargo is deployed. This can be any zone type, like a ZONE, ZONE_GROUP, ZONE_AIRBASE.
+  --      function CLASS:OnAfterCargoDeployed( From, Event, To, Task, TaskPrefix, TaskUnit, Cargo, DeployZone )
+  --      
+  --        -- Write here your own code.
+  --      
+  --      end
   -- 
-  -- The TASK class implements various methods to additional **set scoring** for player achievements:
   -- 
-  --   * @{Tasking.Task#TASK.SetScoreOnProgress}() will add additional scores when a player achieves **Progress** while executing the task.
-  --     Examples of **task progress** can be destroying units, arriving at zones etc.
-  --   
-  --   * @{Tasking.Task#TASK.SetScoreOnSuccess}() will add additional scores when the task goes into **Success** state. 
-  --     This means the **task has been successfully completed**.
-  --     
-  --   * @{Tasking.Task#TASK.SetScoreOnSuccess}() will add additional (negative) scores when the task goes into **Failed** state. 
-  --     This means the **task has not been successfully completed**, and the scores must be given with a negative value!
   -- 
   -- @field #TASK_CARGO_DISPATCHER
   TASK_CARGO_DISPATCHER = {
@@ -194,6 +392,8 @@ do -- TASK_CARGO_DISPATCHER
     self.Mission = Mission
     
     self:AddTransition( "Started", "Assign", "Started" )
+    self:AddTransition( "Started", "CargoPickedUp", "Started" )
+    self:AddTransition( "Started", "CargoDeployed", "Started" )
     
     --- OnAfter Transition Handler for Event Assign.
     -- @function [parent=#TASK_CARGO_DISPATCHER] OnAfterAssign
@@ -208,6 +408,9 @@ do -- TASK_CARGO_DISPATCHER
     self:SetCSARRadius()
     self:__StartTasks( 5 )
     
+    self.MaxCSAR = nil
+    self.CountCSAR = 0
+    
     -- For CSAR missions, we process the event when a pilot ejects.
     
     self:HandleEvent( EVENTS.Ejection )
@@ -216,6 +419,47 @@ do -- TASK_CARGO_DISPATCHER
   end
 
 
+  --- Sets the set of zones were pilots will only be spawned (eject) when the planes crash.  
+  -- Note that because this is a set of zones, the MD can create the zones dynamically within his mission!
+  -- Just provide a set of zones, see usage, but find the tactical situation here:
+  -- 
+  -- ![CSAR Zones](../Tasking/CSAR_Zones.JPG)
+  -- 
+  -- @param #TASK_CARGO_DISPATCHER self
+  -- @param Core.Set#SET_ZONE SetZonesCSAR The set of zones where pilots will only be spawned for CSAR when they eject.
+  -- @usage
+  -- 
+  --      TaskDispatcher = TASK_CARGO_DISPATCHER:New( Mission, AttackGroups )
+  -- 
+  --      -- Use this call to pass the set of zones.
+  --      -- Note that you can create the set of zones inline, because the FilterOnce method (and other SET_ZONE methods return self).
+  --      -- So here the zones can be created as normal trigger zones (MOOSE creates a collection of ZONE objects when teh mission starts of all trigger zones).
+  --      -- Just name them as CSAR zones here.
+  --      TaskDispatcher:SetCSARZones( SET_ZONE:New():FilterPrefixes("CSAR"):FilterOnce() )
+  -- 
+  function TASK_CARGO_DISPATCHER:SetCSARZones( SetZonesCSAR )
+
+    self.SetZonesCSAR = SetZonesCSAR
+  
+  end
+
+
+  --- Sets the maximum of pilots that will be spawned (eject) when the planes crash.  
+  -- @param #TASK_CARGO_DISPATCHER self
+  -- @param #number MaxCSAR The maximum of pilots that will eject for CSAR.
+  -- @usage
+  -- 
+  --      TaskDispatcher = TASK_CARGO_DISPATCHER:New( Mission, AttackGroups )
+  -- 
+  --      -- Use this call to the maximum of CSAR to 10.
+  --      TaskDispatcher:SetMaxCSAR( 10 )
+  -- 
+  function TASK_CARGO_DISPATCHER:SetMaxCSAR( MaxCSAR )
+
+    self.MaxCSAR = MaxCSAR
+  
+  end
+
 
 
   --- Handle the event when a pilot ejects.
@@ -233,8 +477,15 @@ do -- TASK_CARGO_DISPATCHER
       
       -- Only add a CSAR task if the coalition of the mission is equal to the coalition of the ejected unit.
       if CSARCoalition == self.Mission:GetCommandCenter():GetCoalition() then
-        local CSARTaskName = self:AddCSARTask( self.CSARTaskName, CSARCoordinate, CSARHeading, CSARCountry, self.CSARBriefing )     
-        self:SetCSARDeployZones( CSARTaskName, self.CSARDeployZones )
+        -- And only add if the eject is in one of the zones, if defined.
+        if not self.SetZonesCSAR or ( self.SetZonesCSAR and self.SetZonesCSAR:IsCoordinateInZone( CSARCoordinate ) ) then
+          -- And only if the maximum of pilots is not reached that ejected!
+          if not self.MaxCSAR or ( self.MaxCSAR and self.CountCSAR < self.MaxCSAR ) then
+            local CSARTaskName = self:AddCSARTask( self.CSARTaskName, CSARCoordinate, CSARHeading, CSARCountry, self.CSARBriefing )     
+            self:SetCSARDeployZones( CSARTaskName, self.CSARDeployZones )
+            self.CountCSAR = self.CountCSAR + 1
+          end
+        end
       end
     end
     
@@ -321,11 +572,11 @@ do -- TASK_CARGO_DISPATCHER
   -- 
   --   -- Add a CSAR task to rescue a downed pilot from within a coordinate.
   --   local Coordinate = PlaneUnit:GetPointVec2()
-  --   TaskA2ADispatcher:AddCSARTask( Coordinate )
+  --   TaskA2ADispatcher:AddCSARTask( "CSAR Task", Coordinate )
   --   
   --   -- Add a CSAR task to rescue a downed pilot from within a coordinate of country RUSSIA, which is pointing to the west (270°).
   --   local Coordinate = PlaneUnit:GetPointVec2()
-  --   TaskA2ADispatcher:AddCSARTask( Coordinate, 270, Country.RUSSIA )
+  --   TaskA2ADispatcher:AddCSARTask( "CSAR Task", Coordinate, 270, Country.RUSSIA )
   --   
   function TASK_CARGO_DISPATCHER:AddCSARTask( CSARTaskPrefix, CSARCoordinate, CSARHeading, CSARCountry, CSARBriefing )
 
@@ -368,6 +619,7 @@ do -- TASK_CARGO_DISPATCHER
     self.CSAR[CSARTaskName].PilotGroup = CSARGroup
     self.CSAR[CSARTaskName].Briefing = CSARBriefing
     self.CSAR[CSARTaskName].Task = nil
+    self.CSAR[CSARTaskName].TaskPrefix = CSARTaskPrefix
     
     return CSARTaskName
   end
@@ -453,16 +705,17 @@ do -- TASK_CARGO_DISPATCHER
   --  -- Here we set a TransportDeployZone. We use the WorkplaceTask as the reference, and provide a ZONE object.
   --  TaskDispatcher:SetTransportDeployZone( WorkplaceTask, ZONE:New( "Workplace" ) )
   --  
-  function TASK_CARGO_DISPATCHER:AddTransportTask( TaskName, SetCargo, Briefing )
+  function TASK_CARGO_DISPATCHER:AddTransportTask( TaskPrefix, SetCargo, Briefing )
 
     self.TransportCount = self.TransportCount + 1
     
-    local TaskName = string.format( ( TaskName or "Transport" ) .. ".%03d", self.TransportCount )
+    local TaskName = string.format( ( TaskPrefix or "Transport" ) .. ".%03d", self.TransportCount )
     
     self.Transport[TaskName] = {} 
     self.Transport[TaskName].SetCargo = SetCargo
     self.Transport[TaskName].Briefing = Briefing
     self.Transport[TaskName].Task = nil
+    self.Transport[TaskName].TaskPrefix = TaskPrefix
     
     self:ManageTasks()
     
@@ -485,6 +738,8 @@ do -- TASK_CARGO_DISPATCHER
     else
       error( "Task does not exist" )
     end
+
+    self:ManageTasks()
   
     return self
   end
@@ -503,6 +758,8 @@ do -- TASK_CARGO_DISPATCHER
     else
       error( "Task does not exist" )
     end
+
+    self:ManageTasks()
   
     return self
   end
@@ -565,6 +822,7 @@ do -- TASK_CARGO_DISPATCHER
           -- New CSAR Task
           local SetCargo = self:EvaluateCSAR( CSAR.PilotGroup )
           CSAR.Task = TASK_CARGO_CSAR:New( Mission, self.SetGroup, CSARName, SetCargo, CSAR.Briefing )
+          CSAR.Task.TaskPrefix = CSAR.TaskPrefix -- We keep the TaskPrefix for further reference!
           Mission:AddTask( CSAR.Task )
           TaskReport:Add( CSARName )
           if CSAR.DeployZones then
@@ -572,6 +830,17 @@ do -- TASK_CARGO_DISPATCHER
           else
             CSAR.Task:SetDeployZones( self.DefaultDeployZones or {} )
           end
+          
+          -- Now broadcast the onafterCargoPickedUp event to the Task Cargo Dispatcher.
+          function CSAR.Task.OnAfterCargoPickedUp( Task, From, Event, To, TaskUnit, Cargo )
+            self:CargoPickedUp( Task, Task.TaskPrefix, TaskUnit, Cargo )
+          end
+
+          -- Now broadcast the onafterCargoDeployed event to the Task Cargo Dispatcher.
+          function CSAR.Task.OnAfterCargoDeployed( Task, From, Event, To, TaskUnit, Cargo, DeployZone )
+            self:CargoDeployed( Task, Task.TaskPrefix, TaskUnit, Cargo, DeployZone )
+          end
+          
         end
       end
       
@@ -582,32 +851,43 @@ do -- TASK_CARGO_DISPATCHER
         if not Transport.Task then
           -- New Transport Task
           Transport.Task = TASK_CARGO_TRANSPORT:New( Mission, self.SetGroup, TransportName, Transport.SetCargo, Transport.Briefing )
+          Transport.Task.TaskPrefix = Transport.TaskPrefix -- We keep the TaskPrefix for further reference!
           Mission:AddTask( Transport.Task )
           TaskReport:Add( TransportName )
-          if Transport.DeployZones then
-            Transport.Task:SetDeployZones( Transport.DeployZones or {} )
-          else
-            Transport.Task:SetDeployZones( self.DefaultDeployZones or {} )
-          end
-
           function Transport.Task.OnEnterSuccess( Task, From, Event, To )
             self:Success( Task )
           end
 
-          function Transport.Task.onenterCancelled( Task, From, Event, To )
+          function Transport.Task.OnEnterCancelled( Task, From, Event, To )
             self:Cancelled( Task )
           end
           
-          function Transport.Task.onenterFailed( Task, From, Event, To )
+          function Transport.Task.OnEnterFailed( Task, From, Event, To )
             self:Failed( Task )
           end
 
-          function Transport.Task.onenterAborted( Task, From, Event, To )
+          function Transport.Task.OnEnterAborted( Task, From, Event, To )
             self:Aborted( Task )
           end
-            
 
+          -- Now broadcast the onafterCargoPickedUp event to the Task Cargo Dispatcher.
+          function Transport.Task.OnAfterCargoPickedUp( Task, From, Event, To, TaskUnit, Cargo )
+            self:CargoPickedUp( Task, Task.TaskPrefix, TaskUnit, Cargo )
+          end
+
+          -- Now broadcast the onafterCargoDeployed event to the Task Cargo Dispatcher.
+          function Transport.Task.OnAfterCargoDeployed( Task, From, Event, To, TaskUnit, Cargo, DeployZone )
+            self:CargoDeployed( Task, Task.TaskPrefix, TaskUnit, Cargo, DeployZone )
+          end
+          
         end
+        
+        if Transport.DeployZones then
+          Transport.Task:SetDeployZones( Transport.DeployZones or {} )
+        else
+          Transport.Task:SetDeployZones( self.DefaultDeployZones or {} )
+        end
+        
       end
       
       

Moose Development/Moose/Tasking/Task_Cargo_Transport.lua

@@ -67,11 +67,8 @@ do -- TASK_CARGO_TRANSPORT
   -- 
   -- ===
   -- 
-  -- A transport task can be created manually, but actually, it is better to **GENERATE** these tasks using the 
-  -- @{Tasking.Task_Cargo_Dispatcher} module.
-  -- 
-  -- Using the dispatcher, transport tasks can be created much more easy.
-  -- 
+  -- A transport task can be created manually.
+  --  
   -- # 1) Create a transport task manually (code it).
   -- 
   -- Although it is recommended to use the dispatcher, you can create a transport task yourself as a mission designer.
@@ -141,6 +138,124 @@ do -- TASK_CARGO_TRANSPORT
   -- It is better you use the cargo dispatcher to create transport tasks and it will work as it is intended.
   -- By doing this, cargo transport tasking will become a dynamic experience.
   -- 
+  -- 
+  -- # 2) Create a task using the @{Tasking.Task_Cargo_Dispatcher} module.
+  -- 
+  -- Actually, it is better to **GENERATE** these tasks using the @{Tasking.Task_Cargo_Dispatcher} module.
+  -- Using the dispatcher module, transport tasks can be created much more easy.
+  -- 
+  -- Find below an example how to use the TASK_CARGO_DISPATCHER class:
+  -- 
+  -- 
+  --    -- Find the HQ group.
+  --    HQ = GROUP:FindByName( "HQ", "Bravo" )
+  --    
+  --    -- Create the command center with the name "Lima".
+  --    CommandCenter = COMMANDCENTER
+  --      :New( HQ, "Lima" )
+  --    
+  --    -- Create the mission, for the command center, with the name "Operation Cargo Fun", a "Tactical" mission, with the mission briefing "Transport Cargo", for the BLUE coalition.
+  --    Mission = MISSION
+  --      :New( CommandCenter, "Operation Cargo Fun", "Tactical", "Transport Cargo", coalition.side.BLUE )
+  --    
+  --    -- Create the SET of GROUPs containing clients (players) that will transport the cargo.
+  --    -- These are have a name that start with "Transport" and are of the "blue" coalition.
+  --    TransportGroups = SET_GROUP:New():FilterCoalitions( "blue" ):FilterPrefixes( "Transport" ):FilterStart()
+  --    
+  --    
+  --    -- Here we create the TASK_CARGO_DISPATCHER object! This is where we assign the dispatcher to generate tasks in the Mission for the TransportGroups.
+  --    TaskDispatcher = TASK_CARGO_DISPATCHER:New( Mission, TransportGroups )
+  --    
+  --    
+  --    -- Here we declare the SET of CARGOs called "Workmaterials".
+  --    local CargoSetWorkmaterials = SET_CARGO:New():FilterTypes( "Workmaterials" ):FilterStart()
+  --    
+  --    -- Here we declare (add) CARGO_GROUP objects of various types, that are filtered and added in the CargoSetworkmaterials cargo set.
+  --    -- These cargo objects have the type "Workmaterials" which is exactly the type of cargo the CargoSetworkmaterials is filtering on.
+  --    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 )
+  --    
+  --    -- And here we create a new WorkplaceTask, using the :AddTransportTask method of the TaskDispatcher.
+  --    local WorkplaceTask = TaskDispatcher:AddTransportTask( "Build a Workplace", CargoSetWorkmaterials, "Transport the workers, engineers and the equipment near the Workplace." )
+  --    TaskDispatcher:SetTransportDeployZone( WorkplaceTask, ZONE:New( "Workplace" ) )
+  -- 
+  -- # 3) Handle cargo task events.
+  -- 
+  -- When a player is picking up and deploying cargo using his carrier, events are generated by the tasks. These events can be captured and tailored with your own code.
+  -- 
+  -- In order to properly capture the events and avoid mistakes using the documentation, it is advised that you execute the following actions:
+  -- 
+  --   * **Copy / Paste** the code section into your script.
+  --   * **Change** the CLASS literal to the task object name you have in your script.
+  --   * Within the function, you can now **write your own code**!
+  --   * **IntelliSense** will recognize the type of the variables provided by the function. Note: the From, Event and To variables can be safely ignored, 
+  --     but you need to declare them as they are automatically provided by the event handling system of MOOSE.
+  -- 
+  -- You can send messages or fire off any other events within the code section. The sky is the limit!
+  -- 
+  -- 
+  -- ## 3.1) Handle the CargoPickedUp event.
+  -- 
+  -- Find below an example how to tailor the **CargoPickedUp** event, generated by the WorkplaceTask:
+  -- 
+  --      function WorkplaceTask:OnAfterCargoPickedUp( From, Event, To, TaskUnit, Cargo )
+  --        
+  --        MESSAGE:NewType( "Unit " .. TaskUnit:GetName().. " has picked up cargo.", MESSAGE.Type.Information ):ToAll()
+  --        
+  --      end
+  -- 
+  -- If you want to code your own event handler, use this code fragment to tailor the event when a player carrier has picked up a cargo object in the CarrierGroup.
+  -- You can use this event handler to post messages to players, or provide status updates etc.
+  -- 
+  --      --- CargoPickedUp event handler OnAfter for CLASS.
+  --      -- @param #CLASS self
+  --      -- @param #string From A string that contains the "*from state name*" when the event was triggered.
+  --      -- @param #string Event A string that contains the "*event name*" when the event was triggered.
+  --      -- @param #string To A string that contains the "*to state name*" when the event was triggered.
+  --      -- @param Wrapper.Unit#UNIT TaskUnit The unit (client) of the player that has picked up the cargo.
+  --      -- @param Cargo.Cargo#CARGO Cargo The cargo object that has been picked up. Note that this can be a CARGO_GROUP, CARGO_CRATE or CARGO_SLINGLOAD object!
+  --      function CLASS:OnAfterCargoPickedUp( From, Event, To, TaskUnit, Cargo )
+  --      
+  --        -- Write here your own code.
+  --      
+  --      end
+  -- 
+  -- 
+  -- ## 3.2) Handle the CargoDeployed event.
+  -- 
+  -- Find below an example how to tailor the **CargoDeployed** event, generated by the WorkplaceTask:
+  -- 
+  --      function WorkplaceTask:OnAfterCargoDeployed( From, Event, To, TaskUnit, Cargo, DeployZone )
+  --        
+  --        MESSAGE:NewType( "Unit " .. TaskUnit:GetName().. " has deployed cargo at zone " .. DeployZone:GetName(), MESSAGE.Type.Information ):ToAll()
+  --        
+  --        Helos[ math.random(1,#Helos) ]:Spawn()
+  --        EnemyHelos[ math.random(1,#EnemyHelos) ]:Spawn()
+  --      end
+  -- 
+  -- If you want to code your own event handler, use this code fragment to tailor the event when a player carrier has deployed a cargo object from the CarrierGroup.
+  -- You can use this event handler to post messages to players, or provide status updates etc.
+  -- 
+  -- 
+  --      --- CargoDeployed event handler OnAfter for CLASS.
+  --      -- @param #CLASS self
+  --      -- @param #string From A string that contains the "*from state name*" when the event was triggered.
+  --      -- @param #string Event A string that contains the "*event name*" when the event was triggered.
+  --      -- @param #string To A string that contains the "*to state name*" when the event was triggered.
+  --      -- @param Wrapper.Unit#UNIT TaskUnit The unit (client) of the player that has deployed the cargo.
+  --      -- @param Cargo.Cargo#CARGO Cargo The cargo object that has been deployed. Note that this can be a CARGO_GROUP, CARGO_CRATE or CARGO_SLINGLOAD object!
+  --      -- @param Core.Zone#ZONE DeployZone The zone wherein the cargo is deployed. This can be any zone type, like a ZONE, ZONE_GROUP, ZONE_AIRBASE.
+  --      function CLASS:OnAfterCargoDeployed( From, Event, To, TaskUnit, Cargo, DeployZone )
+  --      
+  --        -- Write here your own code.
+  --      
+  --      end
+  -- 
+  -- 
+  -- 
   -- ===
   -- 
   -- @field #TASK_CARGO_TRANSPORT

Moose Development/Moose/Utilities/Utils.lua

@@ -591,4 +591,71 @@ function UTILS.DisplayMissionTime(duration)
   local local_time=UTILS.SecondsToClock(Tnow)  
   local text=string.format("Time: %s - %02d:%02d", local_time, mission_time_minutes, mission_time_seconds)
   MESSAGE:New(text, duration):ToAll()
-end
+end
+
+
+--- Generate a Gaussian pseudo-random number.
+-- @param #number x0 Expectation value of distribution.
+-- @param #number sigma (Optional) Standard deviation. Default 10.
+-- @param #number xmin (Optional) Lower cut-off value.
+-- @param #number xmax (Optional) Upper cut-off value.
+-- @param #number imax (Optional) Max number of tries to get a value between xmin and xmax (if specified). Default 100.
+-- @return #number Gaussian random number.
+function UTILS.RandomGaussian(x0, sigma, xmin, xmax, imax)
+
+  -- Standard deviation. Default 10 if not given.
+  sigma=sigma or 10
+  
+  -- Max attempts.
+  imax=imax or 100
+    
+  local r
+  local gotit=false
+  local i=0
+  while not gotit do
+  
+    -- Uniform numbers in [0,1). We need two.
+    local x1=math.random()
+    local x2=math.random()
+  
+    -- Transform to Gaussian exp(-(x-x0)²/(2*sigma²).
+    r = math.sqrt(-2*sigma*sigma * math.log(x1)) * math.cos(2*math.pi * x2) + x0
+    
+    i=i+1
+    if (r>=xmin and r<=xmax) or i>imax then
+      gotit=true
+    end
+  end
+  
+  return r
+end
+
+--- Randomize a value by a certain amount.
+-- @param #number value The value which should be randomized
+-- @param #number fac Randomization factor.
+-- @param #number lower (Optional) Lower limit of the returned value.
+-- @param #number upper (Optional) Upper limit of the returned value.
+-- @return #number Randomized value.
+-- @usage UTILS.Randomize(100, 0.1) returns a value between 90 and 110, i.e. a plus/minus ten percent variation.
+-- @usage UTILS.Randomize(100, 0.5, nil, 120) returns a value between 50 and 120, i.e. a plus/minus fivty percent variation with upper bound 120.
+function UTILS.Randomize(value, fac, lower, upper)
+  local min
+  if lower then
+    min=math.max(value-value*fac, lower)
+  else
+    min=value-value*fac
+  end
+  local max
+  if upper then
+    max=math.min(value+value*fac, upper)
+  else
+    max=value+value*fac
+  end
+  
+  local r=math.random(min, max)
+  
+  return r
+end
+
+
+

Moose Development/Moose/Wrapper/Airbase.lua

@@ -4,7 +4,7 @@
 -- 
 -- ### Author: **FlightControl**
 -- 
--- ### Contributions: 
+-- ### Contributions: **funkyfranky**
 -- 
 -- ===
 -- 
@@ -260,20 +260,39 @@ AIRBASE.PersianGulf = {
   ["Shiraz_International_Airport"] = "Shiraz International Airport",
   ["Kerman_Airport"] = "Kerman Airport",
   }
+  
+--- AIRBASE.ParkingSpot ".Coordinate, ".TerminalID", ".TerminalType", ".TOAC", ".Free", ".TerminalID0", ".DistToRwy".
+-- @type AIRBASE.ParkingSpot
+-- @field Core.Point#COORDINATE Coordinate Coordinate of the parking spot.
+-- @field #number TerminalID Terminal ID of the spot. Generally, this is not the same number as displayed in the mission editor.
+-- @field #AIRBASE.TerminalType TerminalType Type of the spot, i.e. for which type of aircraft it can be used.
+-- @field #boolean TOAC Takeoff or landing aircarft. I.e. this stop is occupied currently by an aircraft until it took of or until it landed.
+-- @field #boolean Free This spot is currently free, i.e. there is no alive aircraft on it at the present moment.
+-- @field #number TerminalID0 Unknown what this means. If you know, please tell us!
+-- @field #number DistToRwy Distance to runway in meters. Currently bugged and giving the same number as the TerminalID.
  
 --- Terminal Types of parking spots. See also https://wiki.hoggitworld.com/view/DCS_func_getParking
 -- 
 -- Supported types are:
 -- 
--- * AIRBASE.TerminalType.Runway: Valid spawn points on runway.
--- * AIRBASE.TerminalType.HelicopterOnly: Special spots for Helicopers.
--- * AIRBASE.TerminalType.Shelter: Hardened Air Shelter. Currently only on Caucaus map.
--- * AIRBASE.TerminalType.OpenMed: Open/Shelter air airplane only.
--- * AIRBASE.TerminalType.OpenBig: Open air spawn points. Generally larger but does not guarantee large aircraft are capable of spawning there.
--- * AIRBASE.TerminalType.OpenMedOrBig: Combines OpenMed and OpenBig spots.
--- * AIRBASE.TerminalType.HelicopterUnsable: Combines HelicopterOnly, OpenMed and OpenBig.
--- * AIRBASE.TerminalType.FighterAircraft: Combines Shelter. OpenMed and OpenBig spots. So effectively all spots usable by fixed wing aircraft.
--- @field TerminalType
+-- * AIRBASE.TerminalType.Runway = 16: Valid spawn points on runway.
+-- * AIRBASE.TerminalType.HelicopterOnly = 40: Special spots for Helicopers.
+-- * AIRBASE.TerminalType.Shelter = 68: Hardened Air Shelter. Currently only on Caucaus map.
+-- * AIRBASE.TerminalType.OpenMed = 72: Open/Shelter air airplane only.
+-- * AIRBASE.TerminalType.OpenBig = 104: Open air spawn points. Generally larger but does not guarantee large aircraft are capable of spawning there.
+-- * AIRBASE.TerminalType.OpenMedOrBig = 176: Combines OpenMed and OpenBig spots.
+-- * AIRBASE.TerminalType.HelicopterUnsable = 216: Combines HelicopterOnly, OpenMed and OpenBig.
+-- * AIRBASE.TerminalType.FighterAircraft = 244: Combines Shelter. OpenMed and OpenBig spots. So effectively all spots usable by fixed wing aircraft.
+-- 
+-- @type AIRBASE.TerminalType
+-- @field #number Runway 16: Valid spawn points on runway.
+-- @field #number HelicopterOnly 40: Special spots for Helicopers.
+-- @field #number Shelter 68: Hardened Air Shelter. Currently only on Caucaus map.
+-- @field #number OpenMed 72: Open/Shelter air airplane only.
+-- @field #number OpenBig 104: Open air spawn points. Generally larger but does not guarantee large aircraft are capable of spawning there.
+-- @field #number OpenMedOrBig 176: Combines OpenMed and OpenBig spots.
+-- @field #number HelicopterUnsable 216: Combines HelicopterOnly, OpenMed and OpenBig.
+-- @field #number FighterAircraft 244: Combines Shelter. OpenMed and OpenBig spots. So effectively all spots usable by fixed wing aircraft.
 AIRBASE.TerminalType = {
   Runway=16,
   HelicopterOnly=40,
@@ -349,7 +368,7 @@ function AIRBASE.GetAllAirbases(coalition)
   
   local airbases={}
   for _,airbase in pairs(_DATABASE.AIRBASES) do
-    if (coalition~=nil and self:GetCoalition()==coalition) or coalition==nil then
+    if (coalition~=nil and airbase:GetCoalition()==coalition) or coalition==nil then
       table.insert(airbases, airbase)
     end
   end
@@ -594,8 +613,9 @@ end
 -- @param #boolean scanscenery (Optional) Scan for scenery as obstacles. Default false. Can cause problems with e.g. shelters.
 -- @param #boolean verysafe (Optional) If true, wait until an aircraft has taken off until the parking spot is considered to be free. Defaul false.
 -- @param #number nspots (Optional) Number of freeparking spots requested. Default is the number of aircraft in the group. 
+-- @param #table parkingdata (Optional) Parking spots data table. If not given it is automatically derived from the GetParkingSpotsTable() function.
 -- @return #table Table of coordinates and terminal IDs of free parking spots. Each table entry has the elements .Coordinate and .TerminalID.
-function AIRBASE:FindFreeParkingSpotForAircraft(group, terminaltype, scanradius, scanunits, scanstatics, scanscenery, verysafe, nspots)
+function AIRBASE:FindFreeParkingSpotForAircraft(group, terminaltype, scanradius, scanunits, scanstatics, scanscenery, verysafe, nspots, parkingdata)
 
   -- Init default
   scanradius=scanradius or 50
@@ -647,7 +667,7 @@ function AIRBASE:FindFreeParkingSpotForAircraft(group, terminaltype, scanradius,
   -- 1. A spot is considered as NOT free until an aircraft that is present has finally taken off. This might be a bit long especiall at smaller airports.
   -- 2. A "free" spot does not take the aircraft size into accound. So if two big aircraft are spawned on spots next to each other, they might overlap and get destroyed.
   -- 3. The routine return a free spot, if there a static objects placed on the spot.
-  local parkingdata=self:GetParkingSpotsTable(terminaltype)
+  parkingdata=parkingdata or self:GetParkingSpotsTable(terminaltype)
   
   -- Get the aircraft size, i.e. it's longest side of x,z.
   local aircraft=group:GetUnit(1)
@@ -679,99 +699,102 @@ function AIRBASE:FindFreeParkingSpotForAircraft(group, terminaltype, scanradius,
     local _spot=parkingspot.Coordinate   -- Core.Point#COORDINATE
     local _termid=parkingspot.TerminalID
     
-    -- Very safe uses the DCS getParking() info to check if a spot is free. Unfortunately, the function returns free=false until the aircraft has actually taken-off.
-    if verysafe and (parkingspot.Free==false or parkingspot.TOAC==true) then
-        
-      -- DCS getParking() routine returned that spot is not free.
-      self:E(string.format("%s: Parking spot id %d NOT free (or aircraft has not taken off yet). Free=%s, TOAC=%s.", airport, parkingspot.TerminalID, tostring(parkingspot.Free), tostring(parkingspot.TOAC)))
-  
-    else
+    if AIRBASE._CheckTerminalType(parkingspot.TerminalType, terminaltype) then
+    
+      -- Very safe uses the DCS getParking() info to check if a spot is free. Unfortunately, the function returns free=false until the aircraft has actually taken-off.
+      if verysafe and (parkingspot.Free==false or parkingspot.TOAC==true) then
           
-      -- Scan a radius of 50 meters around the spot.
-      local _,_,_,_units,_statics,_sceneries=_spot:ScanObjects(scanradius, scanunits, scanstatics, scanscenery)
+        -- DCS getParking() routine returned that spot is not free.
+        self:E(string.format("%s: Parking spot id %d NOT free (or aircraft has not taken off yet). Free=%s, TOAC=%s.", airport, parkingspot.TerminalID, tostring(parkingspot.Free), tostring(parkingspot.TOAC)))
     
-      -- Loop over objects within scan radius.
-      local occupied=false
-  
-      -- Check all units.    
-      for _,unit in pairs(_units) do
-      
-        local _vec3=unit:getPoint()
-        local _coord=COORDINATE:NewFromVec3(_vec3)
-        local _dist=_coord:Get2DDistance(_spot)      
-        local _safe=_overlap(aircraft, true, unit, false,_dist)
-        
-        if markobstacles then
-          local l,x,y,z=_GetObjectSize(unit)      
-          _coord:MarkToAll(string.format("Unit %s\nx=%.1f y=%.1f z=%.1f\nl=%.1f d=%.1f\nspot %d safe=%s", unit:getName(),x,y,z,l,_dist, _termid, tostring(_safe)))
-        end
-        
-        if scanunits and not _safe then
-          occupied=true
-        end      
-      end
-    
-      -- Check all statics.
-      for _,static in pairs(_statics) do
-        local _vec3=static:getPoint()
-        local _coord=COORDINATE:NewFromVec3(_vec3)
-        local _dist=_coord:Get2DDistance(_spot)      
-        local _safe=_overlap(aircraft, true, static, false,_dist)
-        
-        if markobstacles then
-          local l,x,y,z=_GetObjectSize(static)
-          _coord:MarkToAll(string.format("Static %s\nx=%.1f y=%.1f z=%.1f\nl=%.1f d=%.1f\nspot %d safe=%s", static:getName(),x,y,z,l,_dist, _termid, tostring(_safe)))
-        end
-        
-        if scanstatics and not _safe then
-          occupied=true
-        end            
-      end
-      
-      -- Check all scenery.
-      for _,scenery in pairs(_sceneries) do
-        local _vec3=scenery:getPoint()
-        local _coord=COORDINATE:NewFromVec3(_vec3)
-        local _dist=_coord:Get2DDistance(_spot)
-        local _safe=_overlap(aircraft, true, scenery, false,_dist)
-        
-        if markobstacles then
-          local l,x,y,z=_GetObjectSize(scenery)
-          _coord:MarkToAll(string.format("Scenery %s\nx=%.1f y=%.1f z=%.1f\nl=%.1f d=%.1f\nspot %d safe=%s", scenery:getTypeName(),x,y,z,l,_dist, _termid, tostring(_safe)))
-        end
-        
-        if scanscenery and not _safe then
-          occupied=true
-        end                  
-      end
-      
-      -- Now check the already given spots so that we do not put a large aircraft next to one we already assigned a nearby spot.
-      for _,_takenspot in pairs(validspots) do
-        local _dist=_takenspot.Coordinate:Get2DDistance(_spot)
-        local _safe=_overlap(aircraft, true, aircraft, true,_dist)
-        if not _safe then
-          occupied=true
-        end
-      end
-            
-      --_spot:MarkToAll(string.format("Parking spot %d free=%s", parkingspot.TerminalID, tostring(not occupied)))
-      if occupied then
-        self:T(string.format("%s: Parking spot id %d occupied.", airport, _termid))
       else
-        self:E(string.format("%s: Parking spot id %d free.", airport, _termid))      
-        if nvalid<_nspots then
-          table.insert(validspots, {Coordinate=_spot, TerminalID=_termid})
-        end
-        nvalid=nvalid+1
-      end
+            
+        -- Scan a radius of 50 meters around the spot.
+        local _,_,_,_units,_statics,_sceneries=_spot:ScanObjects(scanradius, scanunits, scanstatics, scanscenery)
       
-    end -- loop over units
-       
-    -- We found enough spots.
-    if nvalid>=_nspots then
-      return validspots
-    end
+        -- Loop over objects within scan radius.
+        local occupied=false
     
+        -- Check all units.    
+        for _,unit in pairs(_units) do
+          -- Unis are now returned as MOOSE units not DCS units!
+          --local _vec3=unit:getPoint()
+          --local _coord=COORDINATE:NewFromVec3(_vec3)
+          local _coord=unit:GetCoordinate()
+          local _dist=_coord:Get2DDistance(_spot)      
+          local _safe=_overlap(aircraft, true, unit, true,_dist)
+          
+          if markobstacles then
+            local l,x,y,z=_GetObjectSize(unit)      
+            _coord:MarkToAll(string.format("Unit %s\nx=%.1f y=%.1f z=%.1f\nl=%.1f d=%.1f\nspot %d safe=%s", unit:getName(),x,y,z,l,_dist, _termid, tostring(_safe)))
+          end
+          
+          if scanunits and not _safe then
+            occupied=true
+          end      
+        end
+      
+        -- Check all statics.
+        for _,static in pairs(_statics) do
+          local _vec3=static:getPoint()
+          local _coord=COORDINATE:NewFromVec3(_vec3)
+          local _dist=_coord:Get2DDistance(_spot)      
+          local _safe=_overlap(aircraft, true, static, false,_dist)
+          
+          if markobstacles then
+            local l,x,y,z=_GetObjectSize(static)
+            _coord:MarkToAll(string.format("Static %s\nx=%.1f y=%.1f z=%.1f\nl=%.1f d=%.1f\nspot %d safe=%s", static:getName(),x,y,z,l,_dist, _termid, tostring(_safe)))
+          end
+          
+          if scanstatics and not _safe then
+            occupied=true
+          end            
+        end
+        
+        -- Check all scenery.
+        for _,scenery in pairs(_sceneries) do
+          local _vec3=scenery:getPoint()
+          local _coord=COORDINATE:NewFromVec3(_vec3)
+          local _dist=_coord:Get2DDistance(_spot)
+          local _safe=_overlap(aircraft, true, scenery, false,_dist)
+          
+          if markobstacles then
+            local l,x,y,z=_GetObjectSize(scenery)
+            _coord:MarkToAll(string.format("Scenery %s\nx=%.1f y=%.1f z=%.1f\nl=%.1f d=%.1f\nspot %d safe=%s", scenery:getTypeName(),x,y,z,l,_dist, _termid, tostring(_safe)))
+          end
+          
+          if scanscenery and not _safe then
+            occupied=true
+          end                  
+        end
+        
+        -- Now check the already given spots so that we do not put a large aircraft next to one we already assigned a nearby spot.
+        for _,_takenspot in pairs(validspots) do
+          local _dist=_takenspot.Coordinate:Get2DDistance(_spot)
+          local _safe=_overlap(aircraft, true, aircraft, true,_dist)
+          if not _safe then
+            occupied=true
+          end
+        end
+              
+        --_spot:MarkToAll(string.format("Parking spot %d free=%s", parkingspot.TerminalID, tostring(not occupied)))
+        if occupied then
+          self:T(string.format("%s: Parking spot id %d occupied.", airport, _termid))
+        else
+          self:E(string.format("%s: Parking spot id %d free.", airport, _termid))      
+          if nvalid<_nspots then
+            table.insert(validspots, {Coordinate=_spot, TerminalID=_termid})
+          end
+          nvalid=nvalid+1
+        end
+        
+      end -- loop over units
+         
+      -- We found enough spots.
+      if nvalid>=_nspots then
+        return validspots
+      end
+    end -- check terminal type
   end  
     
   -- Retrun spots we found, even if there were not enough.

Moose Development/Moose/Wrapper/Client.lua

@@ -376,8 +376,8 @@ end
 -- @param #CLIENT self
 -- @return Wrapper.Unit#UNIT
 function CLIENT:GetClientGroupUnit()
-	self:F2()
-
+  self:F2()
+  
 	local ClientDCSUnit = Unit.getByName( self.ClientName )
 
   self:T( self.ClientDCSUnit )
@@ -433,11 +433,7 @@ function CLIENT:ShowCargo()
 
 end
 
--- TODO (1) I urgently need to revise this.
---- A local function called by the DCS World Menu system to switch off messages.
-function CLIENT.SwitchMessages( PrmTable )
-	PrmTable[1].MessageSwitch = PrmTable[2]
-end
+
 
 --- The main message driver for the CLIENT.
 -- This function displays various messages to the Player logged into the CLIENT through the DCS World Messaging system.

Moose Development/Moose/Wrapper/Controllable.lua

@@ -13,9 +13,9 @@
 
 
 --- @type CONTROLLABLE
--- @extends Wrapper.Positionable#POSITIONABLE
 -- @field DCS#Controllable DCSControllable The DCS controllable class.
 -- @field #string ControllableName The name of the controllable.
+-- @extends Wrapper.Positionable#POSITIONABLE
 
 
 
@@ -26,13 +26,13 @@
 --  * Handle local Controllable Controller.
 --  * Manage the "state" of the DCS Controllable.
 --
--- ## CONTROLLABLE constructor
+-- # 1) CONTROLLABLE constructor
 -- 
 -- The CONTROLLABLE class provides the following functions to construct a CONTROLLABLE instance:
 --
 --  * @{#CONTROLLABLE.New}(): Create a CONTROLLABLE instance.
 --
--- ## CONTROLLABLE Task methods
+-- # 2) CONTROLLABLE Task methods
 -- 
 -- Several controllable task methods are available that help you to prepare tasks. 
 -- These methods return a string consisting of the task description, which can then be given to either a @{Wrapper.Controllable#CONTROLLABLE.PushTask} or @{Wrapper.Controllable#SetTask} method to assign the task to the CONTROLLABLE.
@@ -40,7 +40,7 @@
 -- Each task description where applicable indicates for which controllable category the task is valid.
 -- There are 2 main subdivisions of tasks: Assigned tasks and EnRoute tasks.
 -- 
--- ### Task assignment
+-- ## 2.1) Task assignment
 -- 
 -- Assigned task methods make the controllable execute the task where the location of the (possible) targets of the task are known before being detected.
 -- This is different from the EnRoute tasks, where the targets of the task need to be detected before the task can be executed.
@@ -71,7 +71,7 @@
 --   * @{#CONTROLLABLE.TaskRouteToZone}: (AIR + GROUND) Route the controllable to a given zone.
 --   * @{#CONTROLLABLE.TaskReturnToBase}: (AIR) Route the controllable to an airbase.
 --
--- ### EnRoute assignment
+-- ## 2.2) EnRoute assignment
 -- 
 -- EnRoute tasks require the targets of the task need to be detected by the controllable (using its sensors) before the task can be executed:
 -- 
@@ -84,7 +84,7 @@
 --   * @{#CONTROLLABLE.EnRouteTaskFAC_EngageControllable}: (AIR + GROUND) The task makes the controllable/unit a FAC and lets the FAC to choose the target (enemy ground controllable) as well as other assigned targets.
 --   * @{#CONTROLLABLE.EnRouteTaskTanker}: (AIR) Aircraft will act as a tanker for friendly units. No parameters.
 -- 
--- ### Task preparation
+-- ## 2.3) Task preparation
 -- 
 -- There are certain task methods that allow to tailor the task behaviour:
 --
@@ -93,7 +93,7 @@
 --   * @{#CONTROLLABLE.TaskCondition}: Return a condition section for a controlled task.
 --   * @{#CONTROLLABLE.TaskControlled}: Return a Controlled Task taking a Task and a TaskCondition.
 -- 
--- ### Call a function as a Task
+-- ## 2.4) Call a function as a Task
 -- 
 -- A function can be called which is part of a Task. The method @{#CONTROLLABLE.TaskFunction}() prepares
 -- a Task that can call a GLOBAL function from within the Controller execution.
@@ -102,27 +102,27 @@
 -- 
 -- Demonstration Mission: [GRP-502 - Route at waypoint to random point](https://github.com/FlightControl-Master/MOOSE_MISSIONS/tree/release-2-2-pre/GRP - Group Commands/GRP-502 - Route at waypoint to random point)
 -- 
--- ### Tasks at Waypoints
+-- ## 2.5) Tasks at Waypoints
 -- 
 -- Special Task methods are available to set tasks at certain waypoints.
 -- The method @{#CONTROLLABLE.SetTaskWaypoint}() helps preparing a Route, embedding a Task at the Waypoint of the Route.
 -- 
 -- This creates a Task element, with an action to call a function as part of a Wrapped Task.
 -- 
--- ### Obtain the mission from controllable templates
+-- ## 2.6) Obtain the mission from controllable templates
 -- 
 -- Controllable templates contain complete mission descriptions. Sometimes you want to copy a complete mission from a controllable and assign it to another:
 -- 
 --   * @{#CONTROLLABLE.TaskMission}: (AIR + GROUND) Return a mission task from a mission template.
 --
--- ## CONTROLLABLE Command methods
+-- # 3) Command methods
 -- 
 -- Controllable **command methods** prepare the execution of commands using the @{#CONTROLLABLE.SetCommand} method:
 -- 
 --   * @{#CONTROLLABLE.CommandDoScript}: Do Script command.
 --   * @{#CONTROLLABLE.CommandSwitchWayPoint}: Perform a switch waypoint command.
 -- 
--- ## Routing of Controllables
+-- # 4) Routing of Controllables
 -- 
 -- Different routing methods exist to route GROUPs and UNITs to different locations:
 --   
@@ -130,11 +130,11 @@
 --   * @{#CONTROLLABLE.RouteGroundTo}(): Make the GROUND Controllable to drive towards a specific coordinate.
 --   * @{#CONTROLLABLE.RouteAirTo}(): Make the AIR Controllable to fly towards a specific coordinate. 
 -- 
--- ## Option methods
+-- # 5) Option methods
 -- 
 -- Controllable **Option methods** change the behaviour of the Controllable while being alive.
 -- 
--- ### Rule of Engagement:
+-- ## 5.1) Rule of Engagement:
 -- 
 --   * @{#CONTROLLABLE.OptionROEWeaponFree} 
 --   * @{#CONTROLLABLE.OptionROEOpenFire}
@@ -148,7 +148,7 @@
 --   * @{#CONTROLLABLE.OptionROEReturnFirePossible}
 --   * @{#CONTROLLABLE.OptionROEEvadeFirePossible}
 -- 
--- ### Rule on thread:
+-- ## 5.2) Rule on thread:
 -- 
 --   * @{#CONTROLLABLE.OptionROTNoReaction}
 --   * @{#CONTROLLABLE.OptionROTPassiveDefense}
@@ -162,6 +162,12 @@
 --   * @{#CONTROLLABLE.OptionROTEvadeFirePossible}
 --   * @{#CONTROLLABLE.OptionROTVerticalPossible}
 -- 
+-- ## 5.3) Alarm state:
+-- 
+--   * @{#CONTROLLABLE.OptionAlarmStateAuto}
+--   * @{#CONTROLLABLE.OptionAlarmStateGreen}
+--   * @{#CONTROLLABLE.OptionAlarmStateRed}
+-- 
 -- @field #CONTROLLABLE
 CONTROLLABLE = {
   ClassName = "CONTROLLABLE",
@@ -356,6 +362,8 @@ end
 
 --- Clearing the Task Queue and Setting the Task on the queue from the controllable.
 -- @param #CONTROLLABLE self
+-- @param #DCS.Task DCSTask DCS Task array.
+-- @param #number WaitTime Time in seconds, before the task is set.
 -- @return Wrapper.Controllable#CONTROLLABLE self
 function CONTROLLABLE:SetTask( DCSTask, WaitTime )
   self:F2( { DCSTask = DCSTask } )
@@ -424,6 +432,17 @@ end
 function CONTROLLABLE:TaskCondition( time, userFlag, userFlagValue, condition, duration, lastWayPoint )
   self:F2( { time, userFlag, userFlagValue, condition, duration, lastWayPoint } )
 
+--[[
+ StopCondition = { 
+   time = Time, 
+   userFlag = string, 
+   userFlagValue = boolean, 
+   condition = string, 
+   duration = Time, 
+   lastWaypoint = number, 
+ }
+--]]
+
   local DCSStopCondition = {}
   DCSStopCondition.time = time
   DCSStopCondition.userFlag = userFlag
@@ -598,6 +617,19 @@ function CONTROLLABLE:CommandStopRoute( StopRoute )
 end
 
 
+--- Give an uncontrolled air controllable the start command.
+-- @param #CONTROLLABLE self
+-- @param #number delay (Optional) Delay before start command in seconds.
+-- @return #CONTROLLABLE self
+function CONTROLLABLE:StartUncontrolled(delay)
+  if delay and delay>0 then
+    SCHEDULER:New(nil, CONTROLLABLE.StartUncontrolled, {self}, delay)    
+  else
+    self:SetCommand({id='Start', params={}})
+  end
+  return self
+end
+
 -- TASKS FOR AIR CONTROLLABLES
 
 
@@ -705,28 +737,56 @@ end
 -- @param DCS#Azimuth Direction (optional) Desired ingress direction from the target to the attacking aircraft. Controllable/aircraft will make its attacks from the direction. Of course if there is no way to attack from the direction due the terrain controllable/aircraft will choose another direction.
 -- @param #number Altitude (optional) The altitude from where to attack.
 -- @param #number WeaponType (optional) The WeaponType.
+-- @param #boolean Divebomb (optional) Perform dive bombing. Default false.
 -- @return DCS#Task The DCS task structure.
-function CONTROLLABLE:TaskBombing( Vec2, GroupAttack, WeaponExpend, AttackQty, Direction, Altitude, WeaponType )
-  self:F2( { self.ControllableName, Vec2, GroupAttack, WeaponExpend, AttackQty, Direction, Altitude, WeaponType } )
+function CONTROLLABLE:TaskBombing( Vec2, GroupAttack, WeaponExpend, AttackQty, Direction, Altitude, WeaponType, Divebomb )
+  self:E( { self.ControllableName, Vec2, GroupAttack, WeaponExpend, AttackQty, Direction, Altitude, WeaponType, Divebomb } )
+  
+  local _groupattack=false
+  if GroupAttack then
+    _groupattack=GroupAttack
+  end
+  
+  local _direction=0
+  local _directionenabled=false
+  if Direction then
+    _direction=math.rad(Direction)
+    _directionenabled=true
+  end
+  
+  local _altitude=5000
+  local _altitudeenabled=false
+  if Altitude then
+    _altitude=Altitude
+    _altitudeenabled=true
+  end
+  
+  local _attacktype=nil
+  if Divebomb then
+    _attacktype="Dive"
+  end
+  
 
   local DCSTask
   DCSTask = { 
     id = 'Bombing',
     params = {
-      point = Vec2,
-      groupAttack = GroupAttack or false,
+      x = Vec2.x,
+      y = Vec2.y,
+      groupAttack = _groupattack,
       expend = WeaponExpend or "Auto",
-      attackQtyLimit = AttackQty and true or false,
-      attackQty = AttackQty, 
-      directionEnabled = Direction and true or false,
-      direction = Direction, 
-      altitudeEnabled = Altitude and true or false,
-      altitude = Altitude or 30,
+      attackQtyLimit = false, --AttackQty and true or false,
+      attackQty = AttackQty or 1,
+      directionEnabled = _directionenabled,
+      direction = _direction, 
+      altitudeEnabled = _altitudeenabled,
+      altitude = _altitude,
       weaponType = WeaponType, 
+      --attackType=_attacktype,
       },
-  },
+  }
 
-  self:T3( { DCSTask } )
+  self:E( { TaskBombing=DCSTask } )
   return DCSTask
 end
 
@@ -1017,10 +1077,10 @@ end
 -- The unit / controllable will follow lead unit of another controllable, wingmens of both controllables will continue following their leaders. 
 -- The unit / controllable will also protect that controllable from threats of specified types.
 -- @param #CONTROLLABLE self
--- @param Wrapper.Controllable#CONTROLLABLE EscortControllable The controllable to be escorted.
+-- @param Wrapper.Controllable#CONTROLLABLE FollowControllable The controllable to be escorted.
 -- @param DCS#Vec3 Vec3 Position of the unit / lead unit of the controllable relative lead unit of another controllable in frame reference oriented by course of lead unit of another controllable. If another controllable is on land the unit / controllable will orbit around.
 -- @param #number LastWaypointIndex Detach waypoint of another controllable. Once reached the unit / controllable Follow task is finished.
--- @param #number EngagementDistanceMax Maximal distance from escorted controllable to threat. If the threat is already engaged by escort escort will disengage if the distance becomes greater than 1.5 * engagementDistMax. 
+-- @param #number EngagementDistance Maximal distance from escorted controllable to threat. If the threat is already engaged by escort escort will disengage if the distance becomes greater than 1.5 * engagementDistMax. 
 -- @param DCS#AttributeNameArray TargetTypes Array of AttributeName that is contains threat categories allowed to engage. 
 -- @return DCS#Task The DCS task structure.
 function CONTROLLABLE:TaskEscort( FollowControllable, Vec3, LastWaypointIndex, EngagementDistance, TargetTypes )
@@ -1043,6 +1103,8 @@ function CONTROLLABLE:TaskEscort( FollowControllable, Vec3, LastWaypointIndex, E
     LastWaypointIndexFlag = true
   end
   
+  TargetTypes=TargetTypes or {}
+  
   local DCSTask
   DCSTask = { id = 'Escort',
     params = {
@@ -1592,7 +1654,6 @@ end
 --    RouteToZone( GroundGroup, ZoneList[1] )
 -- 
 function CONTROLLABLE:TaskFunction( FunctionString, ... )
-  self:F2( { FunctionString, arg } )
 
   local DCSTask
 
@@ -1603,17 +1664,12 @@ function CONTROLLABLE:TaskFunction( FunctionString, ... )
     local ArgumentKey = '_' .. tostring( arg ):match("table: (.*)")
     self:SetState( self, ArgumentKey, arg )
     DCSScript[#DCSScript+1] = "local Arguments = MissionControllable:GetState( MissionControllable, '" .. ArgumentKey .. "' ) "
-    --DCSScript[#DCSScript+1] = "MissionControllable:ClearState( MissionControllable, '" .. ArgumentKey .. "' ) "
     DCSScript[#DCSScript+1] = FunctionString .. "( MissionControllable, unpack( Arguments ) )"
   else
     DCSScript[#DCSScript+1] = FunctionString .. "( MissionControllable )"
   end
 
-  DCSTask = self:TaskWrappedAction(
-    self:CommandDoScript(
-      table.concat( DCSScript )
-    )
-  )
+  DCSTask = self:TaskWrappedAction(self:CommandDoScript(table.concat( DCSScript )))
 
   self:T( DCSTask )
 
@@ -1924,7 +1980,7 @@ do -- Route methods
   -- @param #CONTROLLABLE self
   -- @return #CONTROLLABLE
   function CONTROLLABLE:RouteStop()
-    self:F("RouteStop")
+    self:F(self:GetName() .. " RouteStop")
     
     local CommandStop = self:CommandStopRoute( true )
     self:SetCommand( CommandStop )
@@ -1935,7 +1991,7 @@ do -- Route methods
   -- @param #CONTROLLABLE self
   -- @return #CONTROLLABLE
   function CONTROLLABLE:RouteResume()
-    self:F("RouteResume")
+    self:F( self:GetName() .. " RouteResume")
     
     local CommandResume = self:CommandStopRoute( false )
     self:SetCommand( CommandResume )
@@ -1983,6 +2039,28 @@ do -- Route methods
   
     return self
   end
+  
+  --- Make the TRAIN Controllable to drive towards a specific point using railroads.
+  -- @param #CONTROLLABLE self
+  -- @param Core.Point#COORDINATE ToCoordinate A Coordinate to drive to.
+  -- @param #number Speed (Optional) Speed in km/h. The default speed is 20 km/h.
+  -- @param #number DelaySeconds (Optional) Wait for the specified seconds before executing the Route. Default is one second.
+  -- @return #CONTROLLABLE The CONTROLLABLE.
+  function CONTROLLABLE:RouteGroundOnRailRoads( ToCoordinate, Speed, DelaySeconds)
+  
+    -- Defaults.
+    Speed=Speed or 20
+    DelaySeconds=DelaySeconds or 1
+  
+    -- Get the route task.
+    local route=self:TaskGroundOnRailRoads(ToCoordinate, Speed)
+    
+    -- Route controllable to destination.
+    self:Route( route, DelaySeconds )
+  
+    return self
+  end  
+  
 
   
   --- Make a task for a GROUND Controllable to drive towards a specific point using (mostly) roads.
@@ -1991,16 +2069,18 @@ do -- Route methods
   -- @param #number Speed (Optional) Speed in km/h. The default speed is 20 km/h.
   -- @param #string OffRoadFormation (Optional) The formation at initial and final waypoint. Default is "Off Road".
   -- @param #boolean Shortcut (Optional) If true, controllable will take the direct route if the path on road is 10x longer or path on road is less than 5% of total path.
-  -- @return Task
-  function CONTROLLABLE:TaskGroundOnRoad( ToCoordinate, Speed, OffRoadFormation, Shortcut )
+  -- @param Core.Point#COORDINATE FromCoordinate (Optional) Explicit initial coordinate. Default is the position of the controllable.
+  -- @return DCS#Task Task.
+  -- @return #boolean If true, path on road is possible. If false, task will route the group directly to its destination.
+  function CONTROLLABLE:TaskGroundOnRoad( ToCoordinate, Speed, OffRoadFormation, Shortcut, FromCoordinate )
     self:F2({ToCoordinate=ToCoordinate, Speed=Speed, OffRoadFormation=OffRoadFormation})
     
     -- Defaults.
     Speed=Speed or 20
     OffRoadFormation=OffRoadFormation or "Off Road"
   
-    -- Current coordinate.
-    local FromCoordinate = self:GetCoordinate()
+    -- Initial (current) coordinate.
+    FromCoordinate = FromCoordinate or self:GetCoordinate()
     
     -- Get path and path length on road including the end points (From and To).
     local PathOnRoad, LengthOnRoad=FromCoordinate:GetPathOnRoad(ToCoordinate, true)
@@ -2009,28 +2089,36 @@ do -- Route methods
     local _,LengthRoad=FromCoordinate:GetPathOnRoad(ToCoordinate, false)
 
     -- Off road part of the rout: Total=OffRoad+OnRoad.    
-    local LengthOffRoad=LengthOnRoad-LengthRoad
+    local LengthOffRoad
+    local LongRoad
     
     -- Calculate the direct distance between the initial and final points.
     local LengthDirect=FromCoordinate:Get2DDistance(ToCoordinate)
     
-    -- Debug info.
-    self:T(string.format("Length on road   = %.3f km", LengthOnRoad/1000))
-    self:T(string.format("Length directly  = %.3f km", LengthDirect/1000))
-    self:T(string.format("Length fraction  = %.3f km", LengthOnRoad/LengthDirect))
-    self:T(string.format("Length only road = %.3f km", LengthRoad/1000))
-    self:T(string.format("Length off road  = %.3f km", LengthOffRoad/1000))
-    self:T(string.format("Percent on road  = %.1f", LengthRoad/LengthOnRoad*100))
+    if PathOnRoad then
     
+      -- Off road part of the rout: Total=OffRoad+OnRoad.
+      LengthOffRoad=LengthOnRoad-LengthRoad
+
+      -- Length on road is 10 times longer than direct route or path on road is very short (<5% of total path).
+      LongRoad=LengthOnRoad and ((LengthOnRoad > LengthDirect*10) or (LengthRoad/LengthOnRoad*100<5))
+    
+      -- Debug info.
+      self:T(string.format("Length on road   = %.3f km", LengthOnRoad/1000))
+      self:T(string.format("Length directly  = %.3f km", LengthDirect/1000))
+      self:T(string.format("Length fraction  = %.3f km", LengthOnRoad/LengthDirect))
+      self:T(string.format("Length only road = %.3f km", LengthRoad/1000))
+      self:T(string.format("Length off road  = %.3f km", LengthOffRoad/1000))
+      self:T(string.format("Percent on road  = %.1f", LengthRoad/LengthOnRoad*100))
+      
+    end
+        
     -- Route, ground waypoints along road.
     local route={}
-        
-    -- Length on road is 10 times longer than direct route or path on road is very short (<5% of total path).
-    local LongRoad=LengthOnRoad and ((LengthOnRoad > LengthDirect*10) or (LengthRoad/LengthOnRoad*100<5))
-    
+    local canroad=false
+                
     -- Check if a valid path on road could be found.
     if PathOnRoad then
-
       -- Check whether the road is very long compared to direct path.
       if LongRoad and Shortcut then
 
@@ -2049,10 +2137,13 @@ do -- Route methods
         local dist=ToCoordinate:Get2DDistance(PathOnRoad[#PathOnRoad-1])
         if dist>10 then
           table.insert(route, ToCoordinate:WaypointGround(Speed, OffRoadFormation))
+          table.insert(route, ToCoordinate:GetRandomCoordinateInRadius(10,5):WaypointGround(5, OffRoadFormation))
+          table.insert(route, ToCoordinate:GetRandomCoordinateInRadius(10,5):WaypointGround(5, OffRoadFormation))
         end
         
       end
       
+      canroad=true
     else
     
       -- No path on road could be found (can happen!) ==> Route group directly from A to B.
@@ -2061,10 +2152,43 @@ do -- Route methods
             
     end
 
+    return route, canroad
+  end
+
+  --- Make a task for a TRAIN Controllable to drive towards a specific point using railroad.
+  -- @param #CONTROLLABLE self
+  -- @param Core.Point#COORDINATE ToCoordinate A Coordinate to drive to.
+  -- @param #number Speed (Optional) Speed in km/h. The default speed is 20 km/h.
+  -- @return Task
+  function CONTROLLABLE:TaskGroundOnRailRoads(ToCoordinate, Speed)
+    self:F2({ToCoordinate=ToCoordinate, Speed=Speed})
+    
+    -- Defaults.
+    Speed=Speed or 20
+  
+    -- Current coordinate.
+    local FromCoordinate = self:GetCoordinate()
+    
+    -- Get path and path length on railroad.
+    local PathOnRail, LengthOnRail=FromCoordinate:GetPathOnRoad(ToCoordinate, false, true)
+        
+    -- Debug info.
+    self:T(string.format("Length on railroad = %.3f km", LengthOnRail/1000))
+    
+    -- Route, ground waypoints along road.
+    local route={}
+            
+    -- Check if a valid path on railroad could be found.
+    if PathOnRail then
+
+      table.insert(route, PathOnRail[1]:WaypointGround(Speed, "On Railroad"))
+      table.insert(route, PathOnRail[2]:WaypointGround(Speed, "On Railroad"))
+                        
+    end
+
     return route 
   end
 
-  
   --- Make the AIR Controllable fly towards a specific point.
   -- @param #CONTROLLABLE self
   -- @param Core.Point#COORDINATE ToCoordinate A Coordinate to drive to.

Moose Development/Moose/Wrapper/Group.lua

@@ -2,7 +2,9 @@
 -- 
 -- ===
 -- 
--- The @{#GROUP} class is a wrapper class to handle the DCS Group objects:
+-- The @{#GROUP} class is a wrapper class to handle the DCS Group objects.
+-- 
+-- ## Features:
 --
 --  * Support all DCS Group APIs.
 --  * Enhance with Group specific APIs not in the DCS Group API set.
@@ -11,7 +13,16 @@
 --
 -- **IMPORTANT: ONE SHOULD NEVER SANATIZE these GROUP OBJECT REFERENCES! (make the GROUP object references nil).**
 --
--- See the detailed documentation on the GROUP class.
+-- ===
+-- 
+-- For each DCS Group object alive within a running mission, a GROUP wrapper object (instance) will be created within the _@{DATABASE} object.
+-- This is done at the beginning of the mission (when the mission starts), and dynamically when new DCS Group objects are spawned (using the @{SPAWN} class).
+-- 
+-- The GROUP class does not contain a :New() method, rather it provides :Find() methods to retrieve the object reference
+-- using the DCS Group or the DCS GroupName.
+--
+-- The GROUP methods will reference the DCS Group object by name when it is needed during API execution.
+-- If the DCS Group object does not exist or is nil, the GROUP methods will return nil and may log an exception in the DCS.log file.
 -- 
 -- ===
 -- 
@@ -34,24 +45,76 @@
 
 --- Wrapper class of the DCS world Group object.
 -- 
--- For each DCS Group object alive within a running mission, a GROUP wrapper object (instance) will be created within the _@{DATABASE} object.
--- This is done at the beginning of the mission (when the mission starts), and dynamically when new DCS Group objects are spawned (using the @{SPAWN} class).
---
--- The GROUP class does not contain a :New() method, rather it provides :Find() methods to retrieve the object reference
--- using the DCS Group or the DCS GroupName.
---
--- Another thing to know is that GROUP objects do not "contain" the DCS Group object.
--- The GROUP methods will reference the DCS Group object by name when it is needed during API execution.
--- If the DCS Group object does not exist or is nil, the GROUP methods will return nil and log an exception in the DCS.log file.
---
 -- The GROUP class provides the following functions to retrieve quickly the relevant GROUP instance:
 --
 --  * @{#GROUP.Find}(): Find a GROUP instance from the _DATABASE object using a DCS Group object.
 --  * @{#GROUP.FindByName}(): Find a GROUP instance from the _DATABASE object using a DCS Group name.
 --
--- ## GROUP task methods
+-- # 1. Tasking of groups
 --
--- A GROUP is a @{Wrapper.Controllable}. See the @{Wrapper.Controllable} task methods section for a description of the task methods.
+-- A GROUP is derived from the wrapper class CONTROLLABLE (@{Wrapper.Controllable#CONTROLLABLE}). 
+-- See the @{Wrapper.Controllable} task methods section for a description of the task methods.
+--
+-- But here is an example how a group can be assigned a task.
+-- 
+-- This test demonstrates the use(s) of the SwitchWayPoint method of the GROUP class.
+-- 
+-- First we look up the objects. We create a GROUP object `HeliGroup`, using the @{#GROUP:FindByName}() method, looking up the `"Helicopter"` group object.
+-- Same for the `"AttackGroup"`.
+--          
+--          local HeliGroup = GROUP:FindByName( "Helicopter" )
+--          local AttackGroup = GROUP:FindByName( "AttackGroup" )
+-- 
+-- Now we retrieve the @{Wrapper.Unit#UNIT} objects of the `AttackGroup` object, using the method `:GetUnits()`.   
+--       
+--          local AttackUnits = AttackGroup:GetUnits()
+--          
+-- Tasks are actually text strings that we build using methods of GROUP.
+-- So first, we declare an list of `Tasks`.  
+--        
+--          local Tasks = {}
+-- 
+-- Now we loop over the `AttackUnits` using a for loop.
+-- We retrieve the `AttackUnit` using the `AttackGroup:GetUnit()` method.
+-- Each `AttackUnit` found, will be attacked by `HeliGroup`, using the method `HeliGroup:TaskAttackUnit()`.
+-- This method returns a string containing a command line to execute the task to the `HeliGroup`.
+-- The code will assign the task string command to the next element in the `Task` list, using `Tasks[#Tasks+1]`.
+-- This little code will take the count of `Task` using `#` operator, and will add `1` to the count.
+-- This result will be the index of the `Task` element.
+--          
+--          for i = 1, #AttackUnits do
+--            local AttackUnit = AttackGroup:GetUnit( i )
+--            Tasks[#Tasks+1] = HeliGroup:TaskAttackUnit( AttackUnit )
+--          end
+--          
+-- Once these tasks have been executed, a function `_Resume` will be called ...
+--          
+--          Tasks[#Tasks+1] = HeliGroup:TaskFunction( "_Resume", { "''" } )
+--          
+--          --- @param Wrapper.Group#GROUP HeliGroup
+--          function _Resume( HeliGroup )
+--            env.info( '_Resume' )
+--          
+--            HeliGroup:MessageToAll( "Resuming",10,"Info")
+--          end
+-- 
+-- Now here is where the task gets assigned!
+-- Using `HeliGroup:PushTask`, the task is pushed onto the task queue of the group `HeliGroup`.
+-- Since `Tasks` is an array of tasks, we use the `HeliGroup:TaskCombo` method to execute the tasks.
+-- The `HeliGroup:PushTask` method can receive a delay parameter in seconds.
+-- In the example, `30` is given as a delay.
+-- 
+-- 
+--          HeliGroup:PushTask( 
+--            HeliGroup:TaskCombo(
+--            Tasks
+--            ), 30 
+--          ) 
+-- 
+-- That's it!
+-- But again, please refer to the @{Wrapper.Controllable} task methods section for a description of the different task methods that are available.
+-- 
+-- 
 --
 -- ### Obtain the mission from group templates
 -- 
@@ -121,13 +184,16 @@ GROUPTEMPLATE.Takeoff = {
 -- @return #GROUP self
 function GROUP:NewTemplate( GroupTemplate, CoalitionSide, CategoryID, CountryID )
   local GroupName = GroupTemplate.name
+
   _DATABASE:_RegisterGroupTemplate( GroupTemplate, CoalitionSide, CategoryID, CountryID, GroupName )
-  self = BASE:Inherit( self, CONTROLLABLE:New( GroupName ) )
-  self:F2( GroupName )
+
+  local self = BASE:Inherit( self, CONTROLLABLE:New( GroupName ) )
   self.GroupName = GroupName
-  
-  _DATABASE:AddGroup( GroupName )
-  
+
+  if not _DATABASE.GROUPS[GroupName] then
+    _DATABASE.GROUPS[GroupName] = self
+  end  
+
   self:SetEventPriority( 4 )
   return self
 end
@@ -140,7 +206,6 @@ end
 -- @return #GROUP self
 function GROUP:Register( GroupName )
   local self = BASE:Inherit( self, CONTROLLABLE:New( GroupName ) ) -- #GROUP
-  self:F( GroupName )
   self.GroupName = GroupName
   
   self:SetEventPriority( 4 )
@@ -203,18 +268,18 @@ function GROUP:GetPositionVec3() -- Overridden from POSITIONABLE:GetPositionVec3
   return nil
 end
 
---- Returns if the Group is alive.
+--- Returns if the group is alive.
 -- The Group must:
 -- 
 --   * Exist at run-time.
 --   * Has at least one unit.
 -- 
--- When the first @{Wrapper.Unit} of the Group is active, it will return true.
--- If the first @{Wrapper.Unit} of the Group is inactive, it will return false.
+-- When the first @{Wrapper.Unit} of the group is active, it will return true.
+-- If the first @{Wrapper.Unit} of the group is inactive, it will return false.
 -- 
 -- @param #GROUP self
--- @return #boolean true if the Group is alive and active.
--- @return #boolean false if the Group is alive but inactive.
+-- @return #boolean true if the group is alive and active.
+-- @return #boolean false if the group is alive but inactive.
 -- @return #nil if the group does not exist anymore.
 function GROUP:IsAlive()
   self:F2( self.GroupName )
@@ -235,6 +300,26 @@ function GROUP:IsAlive()
   return nil
 end
 
+--- Returns if the group is activated.
+-- @param #GROUP self
+-- @return #boolean true if group is activated.
+-- @return #nil The group is not existing or alive.  
+function GROUP:IsActive()
+  self:F2( self.GroupName )
+
+  local DCSGroup = self:GetDCSObject() -- DCS#Group
+  
+  if DCSGroup then
+  
+    local GroupIsActive = DCSGroup:getUnit(1):isActive()
+    return GroupIsActive 
+  end
+
+  return nil
+end
+
+
+
 --- Destroys the DCS Group and all of its DCS Units.
 -- Note that this destroy method also can raise a destroy event at run-time.
 -- So all event listeners will catch the destroy event of this group for each unit in the group.
@@ -252,20 +337,30 @@ end
 -- @usage
 -- -- Ship unit example: destroy the Ship silently.
 -- Ship = GROUP:FindByName( "Ship" )
--- Ship:Destroy( true )
+-- Ship:Destroy()
+-- 
+-- @usage
+-- -- Destroy without event generation example.
+-- Ship = GROUP:FindByName( "Boat" )
+-- Ship:Destroy( false ) -- Don't generate an event upon destruction.
+-- 
 function GROUP:Destroy( GenerateEvent )
   self:F2( self.GroupName )
 
   local DCSGroup = self:GetDCSObject()
 
   if DCSGroup then
-    if GenerateEvent and GenerateEvent == true then
-      for Index, UnitData in pairs( DCSGroup:getUnits() ) do
+    for Index, UnitData in pairs( DCSGroup:getUnits() ) do
+      if GenerateEvent and GenerateEvent == true then
         if self:IsAir() then
           self:CreateEventCrash( timer.getTime(), UnitData )
         else
           self:CreateEventDead( timer.getTime(), UnitData )
         end
+      elseif GenerateEvent == false then
+        -- Do nothing!
+      else
+        self:CreateEventRemoveUnit( timer.getTime(), UnitData )
       end
     end
     USERFLAG:New( self:GetName() ):Set( 100 )
@@ -335,8 +430,7 @@ end
 
 --- Returns the country of the DCS Group.
 -- @param #GROUP self
--- @return DCS#country.id The country identifier.
--- @return #nil The DCS Group is not existing or alive.
+-- @return DCS#country.id The country identifier or nil if the DCS Group is not existing or alive.
 function GROUP:GetCountry()
   self:F2( self.GroupName )
 
@@ -350,6 +444,40 @@ function GROUP:GetCountry()
   return nil
 end
 
+
+--- Check if at least one (or all) unit(s) has (have) a certain attribute.
+-- See [hoggit documentation](https://wiki.hoggitworld.com/view/DCS_func_hasAttribute).
+-- @param #GROUP self
+-- @param #string attribute The name of the attribute the group is supposed to have. Valid attributes can be found in the "db_attributes.lua" file which is located at in "C:\Program Files\Eagle Dynamics\DCS World\Scripts\Database".
+-- @param #boolean all If true, all units of the group must have the attribute in order to return true. Default is only one unit of a heterogenious group needs to have the attribute.
+-- @return #boolean Group has this attribute.
+function GROUP:HasAttribute(attribute, all)
+
+  -- Get all units of the group.
+  local _units=self:GetUnits()
+  
+  local _allhave=true
+  local _onehas=false
+  
+  for _,_unit in pairs(_units) do
+    local _unit=_unit --Wrapper.Unit#UNIT
+    if _unit then
+      local _hastit=_unit:HasAttribute(attribute)
+      if _hastit==true then
+        _onehas=true
+      else
+        _allhave=false
+      end
+    end 
+  end
+  
+  if all==true then
+    return _allhave
+  else
+    return _onehas
+  end
+end
+
 --- Returns the maximum speed of the group.
 -- If the group is heterogenious and consists of different units, the max speed of the slowest unit is returned.
 -- @param #GROUP self
@@ -380,6 +508,38 @@ function GROUP:GetSpeedMax()
   return nil
 end
 
+--- Returns the maximum range of the group.
+-- If the group is heterogenious and consists of different units, the smallest range of all units is returned.
+-- @param #GROUP self
+-- @return #number Range in meters.
+function GROUP:GetRange()
+  self:F2( self.GroupName )
+
+  local DCSGroup = self:GetDCSObject()
+  if DCSGroup then
+  
+    local Units=self:GetUnits()
+    
+    local Rangemin=nil
+    
+    for _,unit in pairs(Units) do
+      local unit=unit --Wrapper.Unit#UNIT
+      local range=unit:GetRange()
+      if range then
+        if Rangemin==nil then
+          Rangemin=range
+        elseif range<Rangemin then
+          Rangemin=range
+        end
+      end
+    end
+    
+    return Rangemin
+  end
+  
+  return nil
+end
+
 
 --- Returns a list of @{Wrapper.Unit} objects of the @{Wrapper.Group}.
 -- @param #GROUP self
@@ -526,8 +686,7 @@ end
 --- Returns the average group height in meters.
 -- @param Wrapper.Group#GROUP self
 -- @param #boolean FromGround Measure from the ground or from sea level. Provide **true** for measuring from the ground. **false** or **nil** if you measure from sea level. 
--- @return DCS#Vec3 The height of the group.
--- @return #nil The GROUP is not existing or alive.  
+-- @return DCS#Vec3 The height of the group or nil if is not existing or alive.  
 function GROUP:GetHeight( FromGround )
   self:F2( self.GroupName )
 
@@ -595,8 +754,9 @@ function GROUP:GetDCSUnits()
 end
 
 
---- Activates a GROUP.
+--- Activates a late activated GROUP.
 -- @param #GROUP self
+-- @return #GROUP self
 function GROUP:Activate()
   self:F2( { self.GroupName } )
   trigger.action.activateGroup( self:GetDCSObject() )
@@ -856,7 +1016,7 @@ function GROUP:IsCompletelyInZone( Zone )
   return true
 end
 
---- Returns true if some units of the group are within a @{Zone}.
+--- Returns true if some but NOT ALL units of the group are within a @{Zone}.
 -- @param #GROUP self
 -- @param Core.Zone#ZONE_BASE Zone The zone to test.
 -- @return #boolean Returns true if the Group is partially within the @{Core.Zone#ZONE_BASE}
@@ -884,6 +1044,14 @@ function GROUP:IsPartlyInZone( Zone )
   end
 end
 
+--- Returns true if part or all units of the group are within a @{Zone}.
+-- @param #GROUP self
+-- @param Core.Zone#ZONE_BASE Zone The zone to test.
+-- @return #boolean Returns true if the Group is partially or completely within the @{Core.Zone#ZONE_BASE}.
+function GROUP:IsPartlyOrCompletelyInZone( Zone )
+  return self:IsPartlyInZone(Zone) or self:IsCompletelyInZone(Zone)
+end
+
 --- Returns true if none of the group units of the group are within a @{Zone}.
 -- @param #GROUP self
 -- @param Core.Zone#ZONE_BASE Zone The zone to test.
@@ -903,6 +1071,23 @@ function GROUP:IsNotInZone( Zone )
   return true
 end
 
+--- Returns true if any units of the group are within a @{Core.Zone}.
+-- @param #GROUP self
+-- @param Core.Zone#ZONE_BASE Zone The zone to test.
+-- @return #boolean Returns true if any unit of the Group is within the @{Core.Zone#ZONE_BASE}
+function GROUP:IsAnyInZone( Zone )
+
+  if not self:IsAlive() then return false end
+
+  for UnitID, UnitData in pairs( self:GetUnits() ) do
+    local Unit = UnitData -- Wrapper.Unit#UNIT
+    if Zone:IsVec3InZone( Unit:GetVec3() ) then
+      return true
+    end
+  end
+  return false
+end
+
 --- Returns the number of UNITs that are in the @{Zone}
 -- @param #GROUP self
 -- @param Core.Zone#ZONE_BASE Zone The zone to test.
@@ -1112,6 +1297,25 @@ end
 function GROUP:GetMinHeight()
   self:F2()
 
+  local DCSGroup = self:GetDCSObject()
+
+  if DCSGroup then
+    local GroupHeightMin = 999999999
+
+    for Index, UnitData in pairs( DCSGroup:getUnits() ) do
+      local UnitData = UnitData -- DCS#Unit
+
+      local UnitHeight = UnitData:getPoint()
+
+      if UnitHeight < GroupHeightMin then
+        GroupHeightMin = UnitHeight
+      end
+    end
+
+    return GroupHeightMin
+  end
+
+  return nil
 end
 
 --- Returns the current maximum height of the group.
@@ -1121,6 +1325,25 @@ end
 function GROUP:GetMaxHeight()
   self:F2()
 
+  local DCSGroup = self:GetDCSObject()
+
+  if DCSGroup then
+    local GroupHeightMax = -999999999
+
+    for Index, UnitData in pairs( DCSGroup:getUnits() ) do
+      local UnitData = UnitData -- DCS#Unit
+
+      local UnitHeight = UnitData:getPoint()
+
+      if UnitHeight > GroupHeightMax then
+        GroupHeightMax = UnitHeight
+      end
+    end
+
+    return GroupHeightMax
+  end
+
+  return nil
 end
 
 -- RESPAWNING
@@ -1332,97 +1555,109 @@ function GROUP:Respawn( Template, Reset )
 end
 
 
---- @param Wrapper.Group#GROUP self
-function GROUP:RespawnAtAirbase( AirbaseRespawn, Takeoff, TakeoffAltitude ) -- R2.4
-  self:F( { AirbaseRespawn, Takeoff, TakeoffAltitude } )
-
-  local PointVec3 = AirbaseRespawn:GetPointVec3()
+--- Respawn a group at an airbase.
+-- Note that the group has to be on parking spots at the airbase already in order for this to work.
+-- So each unit of the group is respawned at exactly the same parking spot as it currently occupies.
+-- @param Wrapper.Group#GROUP self
+-- @param #table SpawnTemplate (Optional) The spawn template for the group. If no template is given it is exacted from the group.
+-- @param Core.Spawn#SPAWN.Takeoff Takeoff (Optional) Takeoff type. Sould be either SPAWN.Takeoff.Cold or SPAWN.Takeoff.Hot. Default is SPAWN.Takeoff.Hot.
+-- @param #boolean Uncontrolled (Optional) If true, spawn in uncontrolled state.
+-- @return Wrapper.Group#GROUP Group spawned at airbase or nil if group could not be spawned.
+function GROUP:RespawnAtCurrentAirbase(SpawnTemplate, Takeoff, Uncontrolled) -- R2.4
+  self:F2( { SpawnTemplate, Takeoff, Uncontrolled} )
 
+  -- Get closest airbase. Should be the one we are currently on.
+  local airbase=self:GetCoordinate():GetClosestAirbase()
+  
+  if airbase then
+    self:F2("Closest airbase = "..airbase:GetName())
+  else
+    self:E("ERROR: could not find closest airbase!")
+    return nil
+  end
+  -- Takeoff type. Default hot.
   Takeoff = Takeoff or SPAWN.Takeoff.Hot
   
-  local SpawnTemplate = self:GetTemplate()
+  -- Coordinate of the airbase.
+  local AirbaseCoord=airbase:GetCoordinate()
+  
+  -- Spawn template.  
+  SpawnTemplate = SpawnTemplate or self:GetTemplate()
 
   if SpawnTemplate then
 
-    local SpawnPoint = SpawnTemplate.route.points[1] 
+    local SpawnPoint = SpawnTemplate.route.points[1]
 
     -- These are only for ships.
     SpawnPoint.linkUnit = nil
     SpawnPoint.helipadId = nil
     SpawnPoint.airdromeId = nil
 
-    local AirbaseID = AirbaseRespawn:GetID()
-    local AirbaseCategory = AirbaseRespawn:GetDesc().category
-    self:F( { AirbaseCategory = AirbaseCategory, Ship = Airbase.Category.SHIP, Helipad = Airbase.Category.HELIPAD, Airdrome = Airbase.Category.AIRDROME } )
+    -- Aibase id and category.
+    local AirbaseID       = airbase:GetID()
+    local AirbaseCategory = airbase:GetDesc().category
     
-    if AirbaseCategory == Airbase.Category.SHIP then
-      SpawnPoint.linkUnit = AirbaseID
-      SpawnPoint.helipadId = AirbaseID
-    elseif AirbaseCategory == Airbase.Category.HELIPAD then
-      SpawnPoint.linkUnit = AirbaseID
+    if AirbaseCategory == Airbase.Category.SHIP or AirbaseCategory == Airbase.Category.HELIPAD then
+      SpawnPoint.linkUnit  = AirbaseID
       SpawnPoint.helipadId = AirbaseID
     elseif AirbaseCategory == Airbase.Category.AIRDROME then
       SpawnPoint.airdromeId = AirbaseID
     end
 
-    SpawnPoint.alt = 0
-            
-    SpawnPoint.type = GROUPTEMPLATE.Takeoff[Takeoff][1] -- type
+    
+    SpawnPoint.type   = GROUPTEMPLATE.Takeoff[Takeoff][1] -- type
     SpawnPoint.action = GROUPTEMPLATE.Takeoff[Takeoff][2] -- action
     
+    -- Get the units of the group.
+    local units=self:GetUnits()
 
-    -- Translate the position of the Group Template to the Vec3.
-    for UnitID = 1, #SpawnTemplate.units do
-      self:T( 'Before Translation SpawnTemplate.units['..UnitID..'].x = ' .. SpawnTemplate.units[UnitID].x .. ', SpawnTemplate.units['..UnitID..'].y = ' .. SpawnTemplate.units[UnitID].y )
+    local x
+    local y
+    for UnitID=1,#units do
+        
+      local unit=units[UnitID] --Wrapper.Unit#UNIT
 
-      -- These cause a lot of confusion.
-      local UnitTemplate = SpawnTemplate.units[UnitID]
-
-      UnitTemplate.parking = 15
-      UnitTemplate.parking_id = "30"
-      UnitTemplate.alt = 0
-
-      local SX = UnitTemplate.x
-      local SY = UnitTemplate.y 
-      local BX = SpawnPoint.x
-      local BY = SpawnPoint.y
-      local TX = PointVec3.x + ( SX - BX )
-      local TY = PointVec3.z + ( SY - BY )
+      -- Get closest parking spot of current unit. Note that we look for occupied spots since the unit is currently sitting on it!
+      local Parkingspot, TermialID, Distance=unit:GetCoordinate():GetClosestParkingSpot(airbase)
       
-      UnitTemplate.x = TX
-      UnitTemplate.y = TY
+      --Parkingspot:MarkToAll("parking spot")
+      self:T2(string.format("Closest parking spot distance = %s, terminal ID=%s", tostring(Distance), tostring(TermialID)))
+
+      -- Get unit coordinates for respawning position.
+      local uc=unit:GetCoordinate()
+      --uc:MarkToAll(string.format("re-spawnplace %s terminal %d", unit:GetName(), TermialID))
       
-      if Takeoff == GROUP.Takeoff.Air then
-        UnitTemplate.alt = PointVec3.y + ( TakeoffAltitude or 200 )
-      --else
-      --  UnitTemplate.alt = PointVec3.y + 10
-      end
-      self:T( 'After Translation SpawnTemplate.units['..UnitID..'].x = ' .. UnitTemplate.x .. ', SpawnTemplate.units['..UnitID..'].y = ' .. UnitTemplate.y )
-    end
-    
-    SpawnPoint.x = PointVec3.x
-    SpawnPoint.y = PointVec3.z
-    
-    if Takeoff == GROUP.Takeoff.Air then
-      SpawnPoint.alt = PointVec3.y + ( TakeoffAltitude or 200 )
-    --else
-    --  SpawnPoint.alt = PointVec3.y + 10
-    end
+      SpawnTemplate.units[UnitID].x   = uc.x --Parkingspot.x
+      SpawnTemplate.units[UnitID].y   = uc.z --Parkingspot.z
+      SpawnTemplate.units[UnitID].alt = uc.y --Parkingspot.y
 
-    SpawnTemplate.x = PointVec3.x
-    SpawnTemplate.y = PointVec3.z
-    
-    local GroupSpawned = self:Respawn( SpawnTemplate )
-    
-    -- When spawned in the air, we need to generate a Takeoff Event
-    
-    if Takeoff == GROUP.Takeoff.Air then
-      for UnitID, UnitSpawned in pairs( GroupSpawned:GetUnits() ) do
-        SCHEDULER:New( nil, BASE.CreateEventTakeoff, { GroupSpawned, timer.getTime(), UnitSpawned:GetDCSObject() } , 1 )
-      end
+      SpawnTemplate.units[UnitID].parking    = TermialID
+      SpawnTemplate.units[UnitID].parking_id = nil
+      
+      --SpawnTemplate.units[UnitID].unitId=nil
     end
+    
+    --SpawnTemplate.groupId=nil
+    
+    SpawnPoint.x   = SpawnTemplate.units[1].x   --x --AirbaseCoord.x
+    SpawnPoint.y   = SpawnTemplate.units[1].y   --y --AirbaseCoord.z
+    SpawnPoint.alt = SpawnTemplate.units[1].alt --AirbaseCoord:GetLandHeight()
+               
+    SpawnTemplate.x = SpawnTemplate.units[1].x  --x --AirbaseCoord.x
+    SpawnTemplate.y = SpawnTemplate.units[1].y  --y --AirbaseCoord.z
+    
+    -- Set uncontrolled state.
+    SpawnTemplate.uncontrolled=Uncontrolled
 
-    return GroupSpawned
+    -- Destroy old group.
+    self:Destroy(false)
+    
+    _DATABASE:Spawn( SpawnTemplate )
+  
+    -- Reset events.
+    self:ResetEvents()
+
+    return self
   end
   
   return nil
@@ -1517,8 +1752,7 @@ end
 
 --- Returns true if the first unit of the GROUP is in the air.
 -- @param Wrapper.Group#GROUP self
--- @return #boolean true if in the first unit of the group is in the air.
--- @return #nil The GROUP is not existing or not alive.  
+-- @return #boolean true if in the first unit of the group is in the air or #nil if the GROUP is not existing or not alive.   
 function GROUP:InAir()
   self:F2( self.GroupName )
 
@@ -1536,6 +1770,23 @@ function GROUP:InAir()
   return nil
 end
 
+--- Returns the DCS descriptor table of the nth unit of the group.
+-- @param #GROUP self
+-- @param #number n (Optional) The number of the unit for which the dscriptor is returned.
+-- @return DCS#Object.Desc The descriptor of the first unit of the group or #nil if the group does not exist any more.   
+function GROUP:GetDCSDesc(n)
+  -- Default.
+  n=n or 1
+  
+  local unit=self:GetUnit(n)
+  if unit and unit:IsAlive()~=nil then
+    local desc=unit:GetDesc()
+    return desc
+  end
+  
+  return nil
+end
+
 do -- Route methods
 
   --- (AIR) Return the Group to an @{Wrapper.Airbase#AIRBASE}.  

Moose Development/Moose/Wrapper/Identifiable.lua

@@ -206,8 +206,19 @@ function IDENTIFIABLE:GetCountry()
   self:F( self.ClassName .. " " .. self.IdentifiableName .. " not found!" )
   return nil
 end
- 
 
+--- Returns country name of the Identifiable.
+-- @param #IDENTIFIABLE self
+-- @return #string Name of the country.  
+function IDENTIFIABLE:GetCountryName()
+  self:F2( self.IdentifiableName ) 
+  local countryid=self:GetCountry()
+  for name,id in pairs(country.id) do
+    if countryid==id then
+      return name
+    end
+  end
+end
 
 --- Returns Identifiable descriptor. Descriptor type depends on Identifiable category.
 -- @param #IDENTIFIABLE self
@@ -216,7 +227,7 @@ end
 function IDENTIFIABLE:GetDesc()
   self:F2( self.IdentifiableName )
 
-  local DCSIdentifiable = self:GetDCSObject()
+  local DCSIdentifiable = self:GetDCSObject() -- DCS#Object
   
   if DCSIdentifiable then
     local IdentifiableDesc = DCSIdentifiable:getDesc()

Moose Development/Moose/Wrapper/Object.lua

@@ -54,8 +54,7 @@ end
 
 --- Returns the unit's unique identifier.
 -- @param Wrapper.Object#OBJECT self
--- @return DCS#Object.ID ObjectID
--- @return #nil The DCS Object is not existing or alive.  
+-- @return DCS#Object.ID ObjectID or #nil if the DCS Object is not existing or alive. Note that the ID is passed as a string and not a number. 
 function OBJECT:GetID()
 
   local DCSObject = self:GetDCSObject()

Moose Development/Moose/Wrapper/Positionable.lua

@@ -69,6 +69,58 @@ function POSITIONABLE:New( PositionableName )
   return self
 end
 
+--- Destroys the POSITIONABLE.
+-- @param #POSITIONABLE self
+-- @param #boolean GenerateEvent (Optional) true if you want to generate a crash or dead event for the unit.
+-- @return #nil The DCS Unit is not existing or alive.  
+-- @usage
+-- -- Air unit example: destroy the Helicopter and generate a S_EVENT_CRASH for each unit in the Helicopter group.
+-- Helicopter = UNIT:FindByName( "Helicopter" )
+-- Helicopter:Destroy( true )
+-- @usage
+-- -- Ground unit example: destroy the Tanks and generate a S_EVENT_DEAD for each unit in the Tanks group.
+-- Tanks = UNIT:FindByName( "Tanks" )
+-- Tanks:Destroy( true )
+-- @usage
+-- -- Ship unit example: destroy the Ship silently.
+-- Ship = STATIC:FindByName( "Ship" )
+-- Ship:Destroy()
+-- 
+-- @usage
+-- -- Destroy without event generation example.
+-- Ship = STATIC:FindByName( "Boat" )
+-- Ship:Destroy( false ) -- Don't generate an event upon destruction.
+-- 
+function POSITIONABLE:Destroy( GenerateEvent )
+  self:F2( self.ObjectName )
+
+  local DCSObject = self:GetDCSObject()
+  
+  if DCSObject then
+  
+    local UnitGroup = self:GetGroup()
+    local UnitGroupName = UnitGroup:GetName()
+    self:F( { UnitGroupName = UnitGroupName } )
+    
+    if GenerateEvent and GenerateEvent == true then
+      if self:IsAir() then
+        self:CreateEventCrash( timer.getTime(), DCSObject )
+      else
+        self:CreateEventDead( timer.getTime(), DCSObject )
+      end
+    elseif GenerateEvent == false then
+      -- Do nothing!
+    else
+      self:CreateEventRemoveUnit( timer.getTime(), DCSObject )
+    end
+    
+    USERFLAG:New( UnitGroupName ):Set( 100 )
+    DCSObject:destroy()
+  end
+
+  return nil
+end
+
 --- Returns the @{DCS#Position3} position vectors indicating the point and direction vectors in 3D of the POSITIONABLE within the mission.
 -- @param Wrapper.Positionable#POSITIONABLE self
 -- @return DCS#Position The 3D position vectors of the POSITIONABLE.
@@ -243,7 +295,7 @@ end
 
 --- Get the bounding box of the underlying POSITIONABLE DCS Object.
 -- @param #POSITIONABLE self
--- @return DCS#Distance The bounding box of the POSITIONABLE.
+-- @return DCS#Box3 The bounding box of the POSITIONABLE.
 -- @return #nil The POSITIONABLE is not existing or alive.  
 function POSITIONABLE:GetBoundingBox() --R2.1
   self:F2()
@@ -264,6 +316,29 @@ function POSITIONABLE:GetBoundingBox() --R2.1
 end
 
 
+--- Get the bounding radius of the underlying POSITIONABLE DCS Object.
+-- @param #POSITIONABLE self
+-- @param #number mindist (Optional) If bounding box is smaller than this value, mindist is returned. 
+-- @return DCS#Distance The bounding radius of the POSITIONABLE or #nil if the POSITIONABLE is not existing or alive.  
+function POSITIONABLE:GetBoundingRadius(mindist)
+  self:F2()
+
+  local Box = self:GetBoundingBox()
+  
+  local boxmin=mindist or 0
+  if Box then
+    local X = Box.max.x - Box.min.x
+    local Z = Box.max.z - Box.min.z
+    local CX = X / 2
+    local CZ = Z / 2
+    return math.max( math.max( CX, CZ ), boxmin )
+  end
+  
+  BASE:E( { "Cannot GetBoundingRadius", Positionable = self, Alive = self:IsAlive() } )
+
+  return nil
+end
+
 --- Returns the altitude of the POSITIONABLE.
 -- @param Wrapper.Positionable#POSITIONABLE self
 -- @return DCS#Distance The altitude of the POSITIONABLE.
@@ -323,7 +398,7 @@ end
 
 --- Returns the POSITIONABLE heading in degrees.
 -- @param Wrapper.Positionable#POSITIONABLE self
--- @return #number The POSTIONABLE heading
+-- @return #number The POSITIONABLE heading
 -- @return #nil The POSITIONABLE is not existing or alive.
 function POSITIONABLE:GetHeading()
   local DCSPositionable = self:GetDCSObject()
@@ -347,6 +422,52 @@ function POSITIONABLE:GetHeading()
   return nil
 end
 
+-- Is Methods
+
+--- Returns if the unit is of an air category.
+-- If the unit is a helicopter or a plane, then this method will return true, otherwise false.
+-- @param #POSITIONABLE self
+-- @return #boolean Air category evaluation result.
+function POSITIONABLE:IsAir()
+  self:F2()
+  
+  local DCSUnit = self:GetDCSObject()
+  
+  if DCSUnit then
+    local UnitDescriptor = DCSUnit:getDesc()
+    self:T3( { UnitDescriptor.category, Unit.Category.AIRPLANE, Unit.Category.HELICOPTER } )
+    
+    local IsAirResult = ( UnitDescriptor.category == Unit.Category.AIRPLANE ) or ( UnitDescriptor.category == Unit.Category.HELICOPTER )
+  
+    self:T3( IsAirResult )
+    return IsAirResult
+  end
+  
+  return nil
+end
+
+--- Returns if the unit is of an ground category.
+-- If the unit is a ground vehicle or infantry, this method will return true, otherwise false.
+-- @param #POSITIONABLE self
+-- @return #boolean Ground category evaluation result.
+function POSITIONABLE:IsGround()
+  self:F2()
+  
+  local DCSUnit = self:GetDCSObject()
+  
+  if DCSUnit then
+    local UnitDescriptor = DCSUnit:getDesc()
+    self:T3( { UnitDescriptor.category, Unit.Category.GROUND_UNIT } )
+    
+    local IsGroundResult = ( UnitDescriptor.category == Unit.Category.GROUND_UNIT )
+  
+    self:T3( IsGroundResult )
+    return IsGroundResult
+  end
+  
+  return nil
+end
+
 
 --- Returns true if the POSITIONABLE is in the air.
 -- Polymorphic, is overridden in GROUP and UNIT.
@@ -798,56 +919,176 @@ function POSITIONABLE:GetLaserCode() --R2.1
   return self.LaserCode
 end
 
---- Add cargo.
--- @param #POSITIONABLE self
--- @param Core.Cargo#CARGO Cargo
--- @return #POSITIONABLE
-function POSITIONABLE:AddCargo( Cargo )
-  self.__.Cargo[Cargo] = Cargo
-  return self
-end
+do -- Cargo
 
---- Get all contained cargo.
--- @param #POSITIONABLE self
--- @return #POSITIONABLE
-function POSITIONABLE:GetCargo()
-  return self.__.Cargo
-end
-
-
-
---- Remove cargo.
--- @param #POSITIONABLE self
--- @param Core.Cargo#CARGO Cargo
--- @return #POSITIONABLE
-function POSITIONABLE:RemoveCargo( Cargo )
-  self.__.Cargo[Cargo] = nil
-  return self
-end
-
---- Returns if carrier has given cargo.
--- @param #POSITIONABLE self
--- @return Core.Cargo#CARGO Cargo
-function POSITIONABLE:HasCargo( Cargo )
-  return self.__.Cargo[Cargo]
-end
-
---- Clear all cargo.
--- @param #POSITIONABLE self
-function POSITIONABLE:ClearCargo()
-  self.__.Cargo = {}
-end
-
---- Get cargo item count.
--- @param #POSITIONABLE self
--- @return Core.Cargo#CARGO Cargo
-function POSITIONABLE:CargoItemCount()
-  local ItemCount = 0
-  for CargoName, Cargo in pairs( self.__.Cargo ) do
-    ItemCount = ItemCount + Cargo:GetCount()
+  --- Add cargo.
+  -- @param #POSITIONABLE self
+  -- @param Core.Cargo#CARGO Cargo
+  -- @return #POSITIONABLE
+  function POSITIONABLE:AddCargo( Cargo )
+    self.__.Cargo[Cargo] = Cargo
+    return self
   end
-  return ItemCount
-end
+  
+  --- Get all contained cargo.
+  -- @param #POSITIONABLE self
+  -- @return #POSITIONABLE
+  function POSITIONABLE:GetCargo()
+    return self.__.Cargo
+  end
+  
+  
+  
+  --- Remove cargo.
+  -- @param #POSITIONABLE self
+  -- @param Core.Cargo#CARGO Cargo
+  -- @return #POSITIONABLE
+  function POSITIONABLE:RemoveCargo( Cargo )
+    self.__.Cargo[Cargo] = nil
+    return self
+  end
+  
+  --- Returns if carrier has given cargo.
+  -- @param #POSITIONABLE self
+  -- @return Core.Cargo#CARGO Cargo
+  function POSITIONABLE:HasCargo( Cargo )
+    return self.__.Cargo[Cargo]
+  end
+  
+  --- Clear all cargo.
+  -- @param #POSITIONABLE self
+  function POSITIONABLE:ClearCargo()
+    self.__.Cargo = {}
+  end
+  
+  --- Is cargo bay empty.
+  -- @param #POSITIONABLE self
+  function POSITIONABLE:IsCargoEmpty()
+    local IsEmpty = true
+    for _, Cargo in pairs( self.__.Cargo ) do
+      IsEmpty = false
+      break
+    end
+    return IsEmpty
+  end
+  
+  --- Get cargo item count.
+  -- @param #POSITIONABLE self
+  -- @return Core.Cargo#CARGO Cargo
+  function POSITIONABLE:CargoItemCount()
+    local ItemCount = 0
+    for CargoName, Cargo in pairs( self.__.Cargo ) do
+      ItemCount = ItemCount + Cargo:GetCount()
+    end
+    return ItemCount
+  end
+  
+--  --- Get Cargo Bay Free Volume in m3.
+--  -- @param #POSITIONABLE self
+--  -- @return #number CargoBayFreeVolume
+--  function POSITIONABLE:GetCargoBayFreeVolume()
+--    local CargoVolume = 0
+--    for CargoName, Cargo in pairs( self.__.Cargo ) do
+--      CargoVolume = CargoVolume + Cargo:GetVolume()
+--    end
+--    return self.__.CargoBayVolumeLimit - CargoVolume
+--  end
+-- 
+ 
+  --- Get Cargo Bay Free Weight in kg.
+  -- @param #POSITIONABLE self
+  -- @return #number CargoBayFreeWeight
+  function POSITIONABLE:GetCargoBayFreeWeight()
+  
+    -- When there is no cargo bay weight limit set, then calculate this for this positionable!
+    if not self.__.CargoBayWeightLimit then
+      self:SetCargoBayWeightLimit()
+    end
+    
+    local CargoWeight = 0
+    for CargoName, Cargo in pairs( self.__.Cargo ) do
+      CargoWeight = CargoWeight + Cargo:GetWeight()
+    end
+    return self.__.CargoBayWeightLimit - CargoWeight
+  end
+
+--  --- Get Cargo Bay Volume Limit in m3.
+--  -- @param #POSITIONABLE self
+--  -- @param #number VolumeLimit
+--  function POSITIONABLE:SetCargoBayVolumeLimit( VolumeLimit )
+--    self.__.CargoBayVolumeLimit = VolumeLimit
+--  end
+
+  --- Set Cargo Bay Weight Limit in kg.
+  -- @param #POSITIONABLE self
+  -- @param #number WeightLimit
+  function POSITIONABLE:SetCargoBayWeightLimit( WeightLimit )
+    
+    if WeightLimit then
+      self.__.CargoBayWeightLimit = WeightLimit
+    elseif self.__.CargoBayWeightLimit~=nil then
+      -- Value already set ==> Do nothing!
+    else
+      -- If weightlimit is not provided, we will calculate it depending on the type of unit.
+      
+      -- When an airplane or helicopter, we calculate the weightlimit based on the descriptor.
+      if self:IsAir() then
+        local Desc = self:GetDesc()
+        self:F({Desc=Desc})
+
+        local Weights = { 
+          ["C-17A"] = 35000,   --77519 cannot be used, because it loads way too much apcs and infantry.,
+          ["C-130"] = 22000    --The real value cannot be used, because it loads way too much apcs and infantry.,
+        } 
+
+        self.__.CargoBayWeightLimit = Weights[Desc.typeName] or ( Desc.massMax - ( Desc.massEmpty + Desc.fuelMassMax ) )
+      else
+        local Desc = self:GetDesc()
+
+        local Weights = { 
+          ["M1126 Stryker ICV"] = 9,
+          ["M-113"] = 9,
+          ["AAV7"] = 25,
+          ["M2A1_halftrack"] = 9,
+          ["BMD-1"] = 9,
+          ["BMP-1"] = 8,
+          ["BMP-2"] = 7,
+          ["BMP-3"] = 8,
+          ["Boman"] = 25,
+          ["BTR-80"] = 9,
+          ["BTR_D"] = 12,
+          ["Cobra"] = 8,
+          ["LAV-25"] = 6,
+          ["M-2 Bradley"] = 6,
+          ["M1043 HMMWV Armament"] = 4,
+          ["M1045 HMMWV TOW"] = 4,
+          ["M1126 Stryker ICV"] = 9,
+          ["M1134 Stryker ATGM"] = 9,
+          ["Marder"] = 6,
+          ["MCV-80"] = 9,
+          ["MLRS FDDM"] = 4,
+          ["MTLB"] = 25,
+          ["TPZ"] = 10,
+          ["Ural-4320 APA-5D"] = 10,
+          ["GAZ-66"] = 8,
+          ["GAZ-3307"] = 12,
+          ["GAZ-3308"] = 14,
+          ["Tigr_233036"] = 6,
+          ["KAMAZ Truck"] = 12,
+          ["KrAZ6322"] = 12,
+          ["M 818"] = 12,
+          ["Ural-375"] = 12,
+          ["Ural-4320-31"] = 14,
+          ["Ural-4320T"] = 14,
+        }
+    
+        local CargoBayWeightLimit = ( Weights[Desc.typeName] or 0 ) * 95
+        self.__.CargoBayWeightLimit = CargoBayWeightLimit
+      end
+    end
+    self:F({CargoBayWeightLimit = self.__.CargoBayWeightLimit})
+  end
+end --- Cargo
 
 --- Signal a flare at the position of the POSITIONABLE.
 -- @param #POSITIONABLE self

Moose Development/Moose/Wrapper/Static.lua

@@ -89,6 +89,59 @@ function STATIC:FindByName( StaticName, RaiseError )
   return nil
 end
 
+--- Destroys the STATIC.
+-- @param #STATIC self
+-- @param #boolean GenerateEvent (Optional) true if you want to generate a crash or dead event for the static.
+-- @return #nil The DCS StaticObject is not existing or alive.  
+-- @usage
+-- -- Air static example: destroy the static Helicopter and generate a S_EVENT_CRASH.
+-- Helicopter = STATIC:FindByName( "Helicopter" )
+-- Helicopter:Destroy( true )
+-- 
+-- @usage
+-- -- Ground static example: destroy the static Tank and generate a S_EVENT_DEAD.
+-- Tanks = UNIT:FindByName( "Tank" )
+-- Tanks:Destroy( true )
+-- 
+-- @usage
+-- -- Ship static example: destroy the Ship silently.
+-- Ship = STATIC:FindByName( "Ship" )
+-- Ship:Destroy()
+-- 
+-- @usage
+-- -- Destroy without event generation example.
+-- Ship = STATIC:FindByName( "Boat" )
+-- Ship:Destroy( false ) -- Don't generate an event upon destruction.
+-- 
+function STATIC:Destroy( GenerateEvent )
+  self:F2( self.ObjectName )
+
+  local DCSObject = self:GetDCSObject()
+  
+  if DCSObject then
+  
+    local StaticName = DCSObject:getName()
+    self:F( { StaticName = StaticName } )
+    
+    if GenerateEvent and GenerateEvent == true then
+      if self:IsAir() then
+        self:CreateEventCrash( timer.getTime(), DCSObject )
+      else
+        self:CreateEventDead( timer.getTime(), DCSObject )
+      end
+    elseif GenerateEvent == false then
+      -- Do nothing!
+    else
+      self:CreateEventRemoveUnit( timer.getTime(), DCSObject )
+    end
+    
+    DCSObject:destroy()
+  end
+
+  return nil
+end
+
+
 
 function STATIC:GetDCSObject()
   local DCSStatic = StaticObject.getByName( self.StaticName )
@@ -141,9 +194,10 @@ end
 --- Respawn the @{Wrapper.Unit} at the same location with the same properties.
 -- This is useful to respawn a cargo after it has been destroyed.
 -- @param #STATIC self
-function STATIC:ReSpawn()
+-- @param DCS#country.id countryid The country ID used for spawning the new static.
+function STATIC:ReSpawn(countryid)
 
-  local SpawnStatic = SPAWNSTATIC:NewFromStatic( self.StaticName )
+  local SpawnStatic = SPAWNSTATIC:NewFromStatic( self.StaticName, countryid )
   
   SpawnStatic:ReSpawn()
 end

Moose Development/Moose/Wrapper/Unit.lua

@@ -119,10 +119,12 @@ end
 -- @param DCS#Unit DCSUnit An existing DCS Unit object reference.
 -- @return #UNIT self
 function UNIT:Find( DCSUnit )
-
-  local UnitName = DCSUnit:getName()
-  local UnitFound = _DATABASE:FindUnit( UnitName )
-  return UnitFound
+  if DCSUnit then
+    local UnitName = DCSUnit:getName()
+    local UnitFound = _DATABASE:FindUnit( UnitName )
+    return UnitFound
+  end
+  return nil
 end
 
 --- Find a UNIT in the _DATABASE using the name of an existing DCS Unit.
@@ -157,35 +159,7 @@ function UNIT:GetDCSObject()
   return nil
 end
 
---- Destroys the UNIT.
--- @param #UNIT self
--- @param #boolean GenerateEvent (Optional) true if you want to generate a crash or dead event for the unit.
--- @return #nil The DCS Unit is not existing or alive.  
-function UNIT:Destroy( GenerateEvent )
-  self:F2( self.ObjectName )
 
-  local DCSObject = self:GetDCSObject()
-  
-  if DCSObject then
-  
-    local UnitGroup = self:GetGroup()
-    local UnitGroupName = UnitGroup:GetName()
-    self:F( { UnitGroupName = UnitGroupName } )
-    
-    if GenerateEvent and GenerateEvent == true then
-      if self:IsAir() then
-        self:CreateEventCrash( timer.getTime(), DCSObject )
-      else
-        self:CreateEventDead( timer.getTime(), DCSObject )
-      end
-    end
-    
-    USERFLAG:New( UnitGroupName ):Set( 100 )
-    DCSObject:destroy()
-  end
-
-  return nil
-end
 
 
 --- Respawn the @{Wrapper.Unit} using a (tweaked) template of the parent Group.
@@ -358,12 +332,12 @@ function UNIT:GetPlayerName()
   
     local PlayerName = DCSUnit:getPlayerName()
     -- TODO Workaround DCS-BUG-3 - https://github.com/FlightControl-Master/MOOSE/issues/696
-    if PlayerName == nil or PlayerName == "" then
-      local PlayerCategory = DCSUnit:getDesc().category
-      if PlayerCategory == Unit.Category.GROUND_UNIT or PlayerCategory == Unit.Category.SHIP then
-        PlayerName = "Player" .. DCSUnit:getID()
-      end
-    end
+--    if PlayerName == nil or PlayerName == "" then
+--      local PlayerCategory = DCSUnit:getDesc().category
+--      if PlayerCategory == Unit.Category.GROUND_UNIT or PlayerCategory == Unit.Category.SHIP then
+--        PlayerName = "Player" .. DCSUnit:getID()
+--      end
+--    end
 --    -- Good code
 --    if PlayerName == nil then 
 --      PlayerName = nil
@@ -416,6 +390,28 @@ function UNIT:GetSpeedMax()
   return nil
 end
 
+--- Returns the unit's max range in meters derived from the DCS descriptors.
+-- For ground units it will return a range of 10,000 km as they have no real range.
+-- @param #UNIT self
+-- @return #number Range in meters.
+function UNIT:GetRange()
+  self:F2( self.UnitName )
+
+  local Desc = self:GetDesc()
+  
+  if Desc then
+    local Range = Desc.range --This is in nautical miles for some reason. But should check again!
+    if Range then
+      Range=UTILS.NMToMeters(Range)
+    else
+      Range=10000000 --10.000 km if no range
+    end
+    return Range
+  end
+
+  return nil
+end
+
 --- Returns the unit's group if it exist and nil otherwise.
 -- @param Wrapper.Unit#UNIT self
 -- @return Wrapper.Group#GROUP The Group of the Unit.
@@ -854,51 +850,7 @@ end
 
 
 
--- Is methods
 
---- Returns if the unit is of an air category.
--- If the unit is a helicopter or a plane, then this method will return true, otherwise false.
--- @param #UNIT self
--- @return #boolean Air category evaluation result.
-function UNIT:IsAir()
-  self:F2()
-  
-  local DCSUnit = self:GetDCSObject()
-  
-  if DCSUnit then
-    local UnitDescriptor = DCSUnit:getDesc()
-    self:T3( { UnitDescriptor.category, Unit.Category.AIRPLANE, Unit.Category.HELICOPTER } )
-    
-    local IsAirResult = ( UnitDescriptor.category == Unit.Category.AIRPLANE ) or ( UnitDescriptor.category == Unit.Category.HELICOPTER )
-  
-    self:T3( IsAirResult )
-    return IsAirResult
-  end
-  
-  return nil
-end
-
---- Returns if the unit is of an ground category.
--- If the unit is a ground vehicle or infantry, this method will return true, otherwise false.
--- @param #UNIT self
--- @return #boolean Ground category evaluation result.
-function UNIT:IsGround()
-  self:F2()
-  
-  local DCSUnit = self:GetDCSObject()
-  
-  if DCSUnit then
-    local UnitDescriptor = DCSUnit:getDesc()
-    self:T3( { UnitDescriptor.category, Unit.Category.GROUND_UNIT } )
-    
-    local IsGroundResult = ( UnitDescriptor.category == Unit.Category.GROUND_UNIT )
-  
-    self:T3( IsGroundResult )
-    return IsGroundResult
-  end
-  
-  return nil
-end
 
 --- Returns if the unit is a friendly unit.
 -- @param #UNIT self

Moose Setup/Moose.files

@@ -57,6 +57,7 @@ Functional/ZoneCaptureCoalition.lua
 Functional/Artillery.lua
 Functional/Suppression.lua
 Functional/PseudoATC.lua
+Functional/Warehouse.lua
 
 AI/AI_Balancer.lua
 AI/AI_A2A.lua
@@ -69,6 +70,7 @@ AI/AI_Cap.lua
 AI/AI_Cas.lua
 AI/AI_Bai.lua
 AI/AI_Formation.lua
+AI/AI_Cargo.lua
 AI/AI_Cargo_APC.lua
 AI/AI_Cargo_Helicopter.lua
 AI/AI_Cargo_Airplane.lua