MOOSE/Moose Development/Moose/AI/AI_Air_Patrol.lua

--- **AI** -- Models the process of A2G patrolling and engaging ground targets for airplanes and helicopters.
--
-- ===
-- 
-- ### Author: **FlightControl**
-- 
-- ===       
--
-- @module AI.AI_Air_Patrol
-- @image AI_Air_To_Ground_Patrol.JPG

--- @type AI_AIR_PATROL
-- @extends AI.AI_Air#AI_AIR


--- The AI_AIR_PATROL class implements the core functions to patrol a @{Zone} by an AI @{Wrapper.Group} or @{Wrapper.Group} 
-- and automatically engage any airborne enemies that are within a certain range or within a certain zone.
-- 
-- ![Process](..\Presentations\AI_CAP\Dia3.JPG)
-- 
-- The AI_AIR_PATROL is assigned a @{Wrapper.Group} and this must be done before the AI_AIR_PATROL process can be started using the **Start** event.
-- 
-- ![Process](..\Presentations\AI_CAP\Dia4.JPG)
-- 
-- The AI will fly towards the random 3D point within the patrol zone, using a random speed within the given altitude and speed limits.
-- Upon arrival at the 3D point, a new random 3D point will be selected within the patrol zone using the given limits.
-- 
-- ![Process](..\Presentations\AI_CAP\Dia5.JPG)
-- 
-- This cycle will continue.
-- 
-- ![Process](..\Presentations\AI_CAP\Dia6.JPG)
-- 
-- During the patrol, the AI will detect enemy targets, which are reported through the **Detected** event.
--
-- ![Process](..\Presentations\AI_CAP\Dia9.JPG)
-- 
-- When enemies are detected, the AI will automatically engage the enemy.
-- 
-- ![Process](..\Presentations\AI_CAP\Dia10.JPG)
-- 
-- Until a fuel or damage threshold has been reached by the AI, or when the AI is commanded to RTB.
-- When the fuel threshold has been reached, the airplane will fly towards the nearest friendly airbase and will land.
-- 
-- ![Process](..\Presentations\AI_CAP\Dia13.JPG)
-- 
-- ## 1. AI_AIR_PATROL constructor
--   
--   * @{#AI_AIR_PATROL.New}(): Creates a new AI_AIR_PATROL object.
-- 
-- ## 2. AI_AIR_PATROL is a FSM
-- 
-- ![Process](..\Presentations\AI_CAP\Dia2.JPG)
-- 
-- ### 2.1 AI_AIR_PATROL States
-- 
--   * **None** ( Group ): The process is not started yet.
--   * **Patrolling** ( Group ): The AI is patrolling the Patrol Zone.
--   * **Engaging** ( Group ): The AI is engaging the bogeys.
--   * **Returning** ( Group ): The AI is returning to Base..
-- 
-- ### 2.2 AI_AIR_PATROL Events
-- 
--   * **@{AI.AI_Patrol#AI_PATROL_ZONE.Start}**: Start the process.
--   * **@{AI.AI_Patrol#AI_PATROL_ZONE.PatrolRoute}**: Route the AI to a new random 3D point within the Patrol Zone.
--   * **@{#AI_AIR_PATROL.Engage}**: Let the AI engage the bogeys.
--   * **@{#AI_AIR_PATROL.Abort}**: Aborts the engagement and return patrolling in the patrol zone.
--   * **@{AI.AI_Patrol#AI_PATROL_ZONE.RTB}**: Route the AI to the home base.
--   * **@{AI.AI_Patrol#AI_PATROL_ZONE.Detect}**: The AI is detecting targets.
--   * **@{AI.AI_Patrol#AI_PATROL_ZONE.Detected}**: The AI has detected new targets.
--   * **@{#AI_AIR_PATROL.Destroy}**: The AI has destroyed a bogey @{Wrapper.Unit}.
--   * **@{#AI_AIR_PATROL.Destroyed}**: The AI has destroyed all bogeys @{Wrapper.Unit}s assigned in the CAS task.
--   * **Status** ( Group ): The AI is checking status (fuel and damage). When the thresholds have been reached, the AI will RTB.
--
-- ## 3. Set the Range of Engagement
-- 
-- ![Range](..\Presentations\AI_CAP\Dia11.JPG)
-- 
-- An optional range can be set in meters, 
-- that will define when the AI will engage with the detected airborne enemy targets.
-- The range can be beyond or smaller than the range of the Patrol Zone.
-- The range is applied at the position of the AI.
-- Use the method @{AI.AI_CAP#AI_AIR_PATROL.SetEngageRange}() to define that range.
--
-- ## 4. Set the Zone of Engagement
-- 
-- ![Zone](..\Presentations\AI_CAP\Dia12.JPG)
-- 
-- An optional @{Zone} can be set, 
-- that will define when the AI will engage with the detected airborne enemy targets.
-- Use the method @{AI.AI_Cap#AI_AIR_PATROL.SetEngageZone}() to define that Zone.
--  
-- ===
-- 
-- @field #AI_AIR_PATROL
AI_AIR_PATROL = {
  ClassName = "AI_AIR_PATROL",
}

--- Creates a new AI_AIR_PATROL object
-- @param #AI_AIR_PATROL self
-- @param AI.AI_Air#AI_AIR AI_Air The AI_AIR FSM.
-- @param Wrapper.Group#GROUP AIGroup The AI group.
-- @param Core.Zone#ZONE_BASE PatrolZone The @{Zone} where the patrol needs to be executed.
-- @param DCS#Altitude PatrolFloorAltitude (optional, default = 1000m ) The lowest altitude in meters where to execute the patrol.
-- @param DCS#Altitude PatrolCeilingAltitude (optional, default = 1500m ) The highest altitude in meters where to execute the patrol.
-- @param DCS#Speed  PatrolMinSpeed (optional, default = 50% of max speed) The minimum speed of the @{Wrapper.Group} in km/h.
-- @param DCS#Speed  PatrolMaxSpeed (optional, default = 75% of max speed) The maximum speed of the @{Wrapper.Group} in km/h.
-- @param DCS#AltitudeType PatrolAltType The altitude type ("RADIO"=="AGL", "BARO"=="ASL"). Defaults to RADIO.
-- @return #AI_AIR_PATROL
function AI_AIR_PATROL:New( AI_Air, AIGroup, PatrolZone, PatrolFloorAltitude, PatrolCeilingAltitude, PatrolMinSpeed, PatrolMaxSpeed, PatrolAltType )

  -- Inherits from BASE
  local self = BASE:Inherit( self, AI_Air ) -- #AI_AIR_PATROL

  local SpeedMax = AIGroup:GetSpeedMax()
  
  self.PatrolZone = PatrolZone
  
  self.PatrolFloorAltitude = PatrolFloorAltitude or 1000
  self.PatrolCeilingAltitude = PatrolCeilingAltitude or 1500
  self.PatrolMinSpeed = PatrolMinSpeed or SpeedMax * 0.5
  self.PatrolMaxSpeed = PatrolMaxSpeed or SpeedMax * 0.75
  
  -- defafult PatrolAltType to "RADIO" if not specified
  self.PatrolAltType = PatrolAltType or "RADIO"
  
  self:AddTransition( { "Started", "Airborne", "Refuelling" }, "Patrol", "Patrolling" )

  --- OnBefore Transition Handler for Event Patrol.
  -- @function [parent=#AI_AIR_PATROL] OnBeforePatrol
  -- @param #AI_AIR_PATROL self
  -- @param Wrapper.Group#GROUP AIPatrol The Group Object managed by the FSM.
  -- @param #string From The From State string.
  -- @param #string Event The Event string.
  -- @param #string To The To State string.
  -- @return #boolean Return false to cancel Transition.
  
  --- OnAfter Transition Handler for Event Patrol.
  -- @function [parent=#AI_AIR_PATROL] OnAfterPatrol
  -- @param #AI_AIR_PATROL self
  -- @param Wrapper.Group#GROUP AIPatrol The Group Object managed by the FSM.
  -- @param #string From The From State string.
  -- @param #string Event The Event string.
  -- @param #string To The To State string.
    
  --- Synchronous Event Trigger for Event Patrol.
  -- @function [parent=#AI_AIR_PATROL] Patrol
  -- @param #AI_AIR_PATROL self
  
  --- Asynchronous Event Trigger for Event Patrol.
  -- @function [parent=#AI_AIR_PATROL] __Patrol
  -- @param #AI_AIR_PATROL self
  -- @param #number Delay The delay in seconds.
  
  --- OnLeave Transition Handler for State Patrolling.
  -- @function [parent=#AI_AIR_PATROL] OnLeavePatrolling
  -- @param #AI_AIR_PATROL self
  -- @param Wrapper.Group#GROUP AIPatrol The Group Object managed by the FSM.
  -- @param #string From The From State string.
  -- @param #string Event The Event string.
  -- @param #string To The To State string.
  -- @return #boolean Return false to cancel Transition.
  
  --- OnEnter Transition Handler for State Patrolling.
  -- @function [parent=#AI_AIR_PATROL] OnEnterPatrolling
  -- @param #AI_AIR_PATROL self
  -- @param Wrapper.Group#GROUP AIPatrol The Group Object managed by the FSM.
  -- @param #string From The From State string.
  -- @param #string Event The Event string.
  -- @param #string To The To State string.
  
    self:AddTransition( "Patrolling", "PatrolRoute", "Patrolling" ) -- FSM_CONTROLLABLE Transition for type #AI_AIR_PATROL.
  
  --- OnBefore Transition Handler for Event PatrolRoute.
  -- @function [parent=#AI_AIR_PATROL] OnBeforePatrolRoute
  -- @param #AI_AIR_PATROL self
  -- @param Wrapper.Group#GROUP AIPatrol The Group Object managed by the FSM.
  -- @param #string From The From State string.
  -- @param #string Event The Event string.
  -- @param #string To The To State string.
  -- @return #boolean Return false to cancel Transition.
  
  --- OnAfter Transition Handler for Event PatrolRoute.
  -- @function [parent=#AI_AIR_PATROL] OnAfterPatrolRoute
  -- @param #AI_AIR_PATROL self
  -- @param Wrapper.Group#GROUP AIPatrol The Group Object managed by the FSM.
  -- @param #string From The From State string.
  -- @param #string Event The Event string.
  -- @param #string To The To State string.
    
  --- Synchronous Event Trigger for Event PatrolRoute.
  -- @function [parent=#AI_AIR_PATROL] PatrolRoute
  -- @param #AI_AIR_PATROL self
  
  --- Asynchronous Event Trigger for Event PatrolRoute.
  -- @function [parent=#AI_AIR_PATROL] __PatrolRoute
  -- @param #AI_AIR_PATROL self
  -- @param #number Delay The delay in seconds.


  self:AddTransition( "*", "Reset", "Patrolling" ) -- FSM_CONTROLLABLE Transition for type #AI_AIR_PATROL.

  return self
end


--- Set the Engage Range when the AI will engage with airborne enemies. 
-- @param #AI_AIR_PATROL self
-- @param #number EngageRange The Engage Range.
-- @return #AI_AIR_PATROL self
function AI_AIR_PATROL:SetEngageRange( EngageRange )
  self:F2()

  if EngageRange then  
    self.EngageRange = EngageRange
  else
    self.EngageRange = nil
  end
end

--- Set race track parameters. CAP flights will perform race track patterns rather than randomly patrolling the zone.
-- @param #AI_AIR_PATROL self
-- @param #number LegMin Min Length of the race track leg in meters. Default 10,000 m.
-- @param #number LegMax Max length of the race track leg in meters. Default 15,000 m.
-- @param #number HeadingMin Min heading of the race track in degrees. Default 0 deg, i.e. from South to North.
-- @param #number HeadingMax Max heading of the race track in degrees. Default 180 deg, i.e. from South to North.
-- @param #number DurationMin (Optional) Min duration before switching the orbit position. Default is keep same orbit until RTB or engage.
-- @param #number DurationMax (Optional) Max duration before switching the orbit position. Default is keep same orbit until RTB or engage.
-- @param #table CapCoordinates Table of coordinates of first race track point. Second point is determined by leg length and heading. 
-- @return #AI_AIR_PATROL self
function AI_AIR_PATROL:SetRaceTrackPattern(LegMin, LegMax, HeadingMin, HeadingMax, DurationMin, DurationMax, CapCoordinates)
  
  self.racetrack=true
  self.racetracklegmin=LegMin or 10000
  self.racetracklegmax=LegMax or 15000
  self.racetrackheadingmin=HeadingMin or 0
  self.racetrackheadingmax=HeadingMax or 180
  self.racetrackdurationmin=DurationMin
  self.racetrackdurationmax=DurationMax
  
  if self.racetrackdurationmax and not self.racetrackdurationmin then
    self.racetrackdurationmin=self.racetrackdurationmax
  end
  
  self.racetrackcapcoordinates=CapCoordinates
  
end



--- Defines a new patrol route using the @{Process_PatrolZone} parameters and settings.
-- @param #AI_AIR_PATROL self
-- @return #AI_AIR_PATROL self
-- @param Wrapper.Group#GROUP AIPatrol The Group Object 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_AIR_PATROL:onafterPatrol( AIPatrol, From, Event, To )
  self:F2()

  self:ClearTargetDistance()

  self:__PatrolRoute( self.TaskDelay )
  
  AIPatrol:OnReSpawn(
    function( PatrolGroup )
      self:__Reset( self.TaskDelay )
      self:__PatrolRoute( self.TaskDelay )
    end
  )
end

--- This statis method is called from the route path within the last task at the last waaypoint of the AIPatrol.
-- Note that this method is required, as triggers the next route when patrolling for the AIPatrol.
-- @param Wrapper.Group#GROUP AIPatrol The AI group.
-- @param #AI_AIR_PATROL Fsm The FSM.
function AI_AIR_PATROL.___PatrolRoute( AIPatrol, Fsm )

  AIPatrol:F( { "AI_AIR_PATROL.___PatrolRoute:", AIPatrol:GetName() } )

  if AIPatrol and AIPatrol:IsAlive() then
    Fsm:PatrolRoute()
  end
  
end

--- Defines a new patrol route using the @{Process_PatrolZone} parameters and settings.
-- @param #AI_AIR_PATROL self
-- @param Wrapper.Group#GROUP AIPatrol The 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_AIR_PATROL:onafterPatrolRoute( AIPatrol, From, Event, To )

  self:F2()

  -- When RTB, don't allow anymore the routing.
  if From == "RTB" then
    return
  end

  
  if AIPatrol and  AIPatrol:IsAlive() then
    
    local PatrolRoute = {}

    --- Calculate the target route point.
    
    local CurrentCoord = AIPatrol:GetCoordinate()
    
    local altitude= math.random( self.PatrolFloorAltitude, self.PatrolCeilingAltitude )
    
    local ToTargetCoord = self.PatrolZone:GetRandomPointVec2()
    ToTargetCoord:SetAlt( altitude )
    self:SetTargetDistance( ToTargetCoord ) -- For RTB status check
    
    local ToTargetSpeed = math.random( self.PatrolMinSpeed, self.PatrolMaxSpeed )
    local speedkmh=ToTargetSpeed

    local FromWP = CurrentCoord:WaypointAir(self.PatrolAltType or "RADIO", POINT_VEC3.RoutePointType.TurningPoint, POINT_VEC3.RoutePointAction.TurningPoint, ToTargetSpeed, true)
    PatrolRoute[#PatrolRoute+1] = FromWP

    if self.racetrack then
      
      -- Random heading.
      local heading = math.random(self.racetrackheadingmin, self.racetrackheadingmax)
      
      -- Random leg length.
      local leg=math.random(self.racetracklegmin, self.racetracklegmax)
      
      -- Random duration if any.
      local duration = self.racetrackdurationmin
      if self.racetrackdurationmax then
        duration=math.random(self.racetrackdurationmin, self.racetrackdurationmax)
      end
      
      -- CAP coordinate.
      local c0=self.PatrolZone:GetRandomCoordinate()
      if self.racetrackcapcoordinates and #self.racetrackcapcoordinates>0 then
        c0=self.racetrackcapcoordinates[math.random(#self.racetrackcapcoordinates)]
      end
      
      -- Race track points.
      local c1=c0:SetAltitude(altitude) --Core.Point#COORDINATE
      local c2=c1:Translate(leg, heading):SetAltitude(altitude)
      
      self:SetTargetDistance(c0) -- For RTB status check
      
      -- Debug:
      self:T(string.format("Patrol zone race track: v=%.1f knots, h=%.1f ft, heading=%03d, leg=%d m, t=%s sec", UTILS.KmphToKnots(speedkmh), UTILS.MetersToFeet(altitude), heading, leg, tostring(duration)))
      --c1:MarkToAll("Race track c1")
      --c2:MarkToAll("Race track c2")

      -- Task to orbit.              
      local taskOrbit=AIPatrol:TaskOrbit(c1, altitude, UTILS.KmphToMps(speedkmh), c2)
      
      -- Task function to redo the patrol at other random position.
      local taskPatrol=AIPatrol:TaskFunction("AI_AIR_PATROL.___PatrolRoute", self)
      
      -- Controlled task with task condition.
      local taskCond=AIPatrol:TaskCondition(nil, nil, nil, nil, duration, nil)
      local taskCont=AIPatrol:TaskControlled(taskOrbit, taskCond)
      
      -- Second waypoint
      PatrolRoute[2]=c1:WaypointAirTurningPoint(self.PatrolAltType, speedkmh, {taskCont, taskPatrol}, "CAP Orbit")

    else
    
      --- Create a route point of type air.
      local ToWP = ToTargetCoord:WaypointAir(self.PatrolAltType, POINT_VEC3.RoutePointType.TurningPoint, POINT_VEC3.RoutePointAction.TurningPoint, ToTargetSpeed, true)  
      PatrolRoute[#PatrolRoute+1] = ToWP
      
      local Tasks = {}
      Tasks[#Tasks+1] = AIPatrol:TaskFunction("AI_AIR_PATROL.___PatrolRoute", self)
      PatrolRoute[#PatrolRoute].task = AIPatrol:TaskCombo( Tasks )
      
    end
    
    AIPatrol:OptionROEReturnFire()
    AIPatrol:OptionROTEvadeFire()
  
    AIPatrol:Route( PatrolRoute, self.TaskDelay )
    
  end

end

--- @param Wrapper.Group#GROUP AIPatrol
function AI_AIR_PATROL.Resume( AIPatrol, Fsm )

  AIPatrol:F( { "AI_AIR_PATROL.Resume:", AIPatrol:GetName() } )
  if AIPatrol and AIPatrol:IsAlive() then
    Fsm:__Reset( Fsm.TaskDelay )
    Fsm:__PatrolRoute( Fsm.TaskDelay )
  end
  
end