mirror of
https://github.com/FlightControl-Master/MOOSE.git
synced 2025-10-29 16:58:06 +00:00
389 lines
17 KiB
Lua
389 lines
17 KiB
Lua
--- This module contains the AI\_PATROLZONE class.
|
|
--
|
|
-- ===
|
|
--
|
|
-- 1) @{#AI_PATROLZONE} class, extends @{StateMachine#STATEMACHINE}
|
|
-- ================================================================
|
|
-- The @{#AI_PATROLZONE} class implements the core functions to patrol a @{Zone} by an AIR @{Group}.
|
|
-- The patrol algorithm works that for each airplane patrolling, upon arrival at the patrol zone,
|
|
-- a random point is selected as the route point within the 3D space, within the given boundary limits.
|
|
-- The airplane 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 random 3D point, a new 3D random point will be selected within the patrol zone using the given limits.
|
|
-- This cycle will continue until a fuel treshold has been reached by the airplane.
|
|
-- When the fuel treshold has been reached, the airplane will fly towards the nearest friendly airbase and will land.
|
|
--
|
|
-- 1.1) AI\_PATROLZONE constructor:
|
|
-- ----------------------------
|
|
--
|
|
-- * @{#AI_PATROLZONE.New}(): Creates a new AI\_PATROLZONE object.
|
|
--
|
|
-- 1.2) AI\_PATROLZONE state machine:
|
|
-- ----------------------------------
|
|
-- The AI\_PATROLZONE is a state machine: it manages the different events and states of the AIGroup it is controlling.
|
|
--
|
|
-- ### 1.2.1) AI\_PATROLZONE Events:
|
|
--
|
|
-- * @{#AI_PATROLZONE.Route}( AIGroup ): A new 3D route point is selected and the AIGroup will fly towards that point with the given speed.
|
|
-- * @{#AI_PATROLZONE.Patrol}( AIGroup ): The AIGroup reports it is patrolling. This event is called every 30 seconds.
|
|
-- * @{#AI_PATROLZONE.RTB}( AIGroup ): The AIGroup will report return to base.
|
|
-- * @{#AI_PATROLZONE.End}( AIGroup ): The end of the AI\_PATROLZONE process.
|
|
-- * @{#AI_PATROLZONE.Dead}( AIGroup ): The AIGroup is dead. The AI\_PATROLZONE process will be ended.
|
|
--
|
|
-- ### 1.2.2) AI\_PATROLZONE States:
|
|
--
|
|
-- * **Route**: A new 3D route point is selected and the AIGroup will fly towards that point with the given speed.
|
|
-- * **Patrol**: The AIGroup is patrolling. This state is set every 30 seconds, so every 30 seconds, a state transition function can be used.
|
|
-- * **RTB**: The AIGroup reports it wants to return to the base.
|
|
-- * **Dead**: The AIGroup is dead ...
|
|
-- * **End**: The process has come to an end.
|
|
--
|
|
-- ### 1.2.3) AI\_PATROLZONE state transition functions:
|
|
--
|
|
-- State transition functions can be set **by the mission designer** customizing or improving the behaviour of the state.
|
|
-- There are 2 moments when state transition functions will be called by the state machine:
|
|
--
|
|
-- * **Before** the state transition.
|
|
-- The state transition function needs to start with the name **OnBefore + the name of the state**.
|
|
-- If the state transition function returns false, then the processing of the state transition will not be done!
|
|
-- If you want to change the behaviour of the AIGroup at this event, return false,
|
|
-- but then you'll need to specify your own logic using the AIGroup!
|
|
--
|
|
-- * **After** the state transition.
|
|
-- The state transition function needs to start with the name **OnAfter + the name of the state**.
|
|
-- These state transition functions need to provide a return value, which is specified at the function description.
|
|
--
|
|
-- An example how to manage a state transition for an AI\_PATROLZONE object **Patrol** for the state **RTB**:
|
|
--
|
|
-- local PatrolZoneGroup = GROUP:FindByName( "Patrol Zone" )
|
|
-- local PatrolZone = ZONE_POLYGON:New( "PatrolZone", PatrolZoneGroup )
|
|
--
|
|
-- local PatrolSpawn = SPAWN:New( "Patrol Group" )
|
|
-- local PatrolGroup = PatrolSpawn:Spawn()
|
|
--
|
|
-- local Patrol = AI_PATROLZONE:New( PatrolZone, 3000, 6000, 300, 600 )
|
|
-- Patrol:AddGroup( PatrolGroup )
|
|
-- Patrol:ManageFuel( 0.2, 60 )
|
|
--
|
|
-- **OnBefore**RTB( AIGroup ) will be called by the AI\_PATROLZONE object when the AIGroup reports RTB, but **before** the RTB default action is processed by the AI_PATROLZONE object.
|
|
--
|
|
-- --- State transition function for the AI\_PATROLZONE **Patrol** object
|
|
-- -- @param #AI_PATROLZONE self
|
|
-- -- @param Group#GROUP AIGroup
|
|
-- -- @return #boolean If false is returned, then the OnAfter state transition function will not be called.
|
|
-- function Patrol:OnBeforeRTB( AIGroup )
|
|
-- AIGroup:MessageToRed( "Returning to base", 20 )
|
|
-- end
|
|
--
|
|
-- **OnAfter**RTB( AIGroup ) will be called by the AI\_PATROLZONE object when the AIGroup reports RTB, but **after** the RTB default action was processed by the AI_PATROLZONE object.
|
|
--
|
|
-- --- State transition function for the AI\_PATROLZONE **Patrol** object
|
|
-- -- @param #AI_PATROLZONE self
|
|
-- -- @param Group#GROUP AIGroup
|
|
-- -- @return #Group#GROUP The new AIGroup object that is set to be patrolling the zone.
|
|
-- function Patrol:OnAfterRTB( AIGroup )
|
|
-- return PatrolSpawn:Spawn()
|
|
-- end
|
|
--
|
|
-- 1.3) Modify the AI\_PATROLZONE parameters:
|
|
-- --------------------------------------
|
|
-- The following methods are available to modify the parameters of a AI\_PATROLZONE object:
|
|
--
|
|
-- * @{#AI_PATROLZONE.SetGroup}(): Set the AI Patrol Group.
|
|
-- * @{#AI_PATROLZONE.SetSpeed}(): Set the patrol speed of the AI, for the next patrol.
|
|
-- * @{#AI_PATROLZONE.SetAltitude}(): Set altitude of the AI, for the next patrol.
|
|
--
|
|
-- 1.3) Manage the out of fuel in the AI\_PATROLZONE:
|
|
-- ----------------------------------------------
|
|
-- When the PatrolGroup is out of fuel, it is required that a new PatrolGroup is started, before the old PatrolGroup can return to the home base.
|
|
-- Therefore, with a parameter and a calculation of the distance to the home base, the fuel treshold is calculated.
|
|
-- When the fuel treshold is reached, the PatrolGroup will continue for a given time its patrol task in orbit, while a new PatrolGroup is targetted to the AI\_PATROLZONE.
|
|
-- Once the time is finished, the old PatrolGroup will return to the base.
|
|
-- Use the method @{#AI_PATROLZONE.ManageFuel}() to have this proces in place.
|
|
--
|
|
-- ====
|
|
--
|
|
-- **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:
|
|
--
|
|
-- 2016-08-17: AI\_PATROLZONE:New( **PatrolSpawn,** PatrolZone, PatrolFloorAltitude, PatrolCeilingAltitude, PatrolMinSpeed, PatrolMaxSpeed ) replaces AI\_PATROLZONE:New( PatrolZone, PatrolFloorAltitude, PatrolCeilingAltitude, PatrolMinSpeed, PatrolMaxSpeed )
|
|
--
|
|
-- 2016-07-01: Initial class and API.
|
|
--
|
|
-- ===
|
|
--
|
|
-- AUTHORS and CONTRIBUTIONS
|
|
-- =========================
|
|
--
|
|
-- ### Contributions:
|
|
--
|
|
-- * **DutchBaron**: Testing.
|
|
--
|
|
-- ### Authors:
|
|
--
|
|
-- * **FlightControl**: Design & Programming
|
|
--
|
|
--
|
|
-- @module AI_PatrolZone
|
|
|
|
|
|
|
|
--- AI\_PATROLZONE class
|
|
-- @type AI_PATROLZONE
|
|
-- @field Group#GROUP PatrolGroup The @{Group} patrolling.
|
|
-- @field Zone#ZONE_BASE PatrolZone The @{Zone} where the patrol needs to be executed.
|
|
-- @field DCSTypes#Altitude PatrolFloorAltitude The lowest altitude in meters where to execute the patrol.
|
|
-- @field DCSTypes#Altitude PatrolCeilingAltitude The highest altitude in meters where to execute the patrol.
|
|
-- @field DCSTypes#Speed PatrolMinSpeed The minimum speed of the @{Group} in km/h.
|
|
-- @field DCSTypes#Speed PatrolMaxSpeed The maximum speed of the @{Group} in km/h.
|
|
-- @extends StateMachine#StateMachine
|
|
AI_PATROLZONE = {
|
|
ClassName = "AI_PATROLZONE",
|
|
}
|
|
|
|
|
|
|
|
--- Creates a new AI\_PATROLZONE object
|
|
-- @param #AI_PATROLZONE self
|
|
-- @param Zone#ZONE_BASE PatrolZone The @{Zone} where the patrol needs to be executed.
|
|
-- @param DCSTypes#Altitude PatrolFloorAltitude The lowest altitude in meters where to execute the patrol.
|
|
-- @param DCSTypes#Altitude PatrolCeilingAltitude The highest altitude in meters where to execute the patrol.
|
|
-- @param DCSTypes#Speed PatrolMinSpeed The minimum speed of the @{Group} in km/h.
|
|
-- @param DCSTypes#Speed PatrolMaxSpeed The maximum speed of the @{Group} in km/h.
|
|
-- @return #AI_PATROLZONE self
|
|
-- @usage
|
|
-- -- Define a new AI_PATROLZONE Object. This PatrolArea will patrol a group within PatrolZone between 3000 and 6000 meters, with a variying speed between 600 and 900 km/h.
|
|
-- PatrolZone = ZONE:New( 'PatrolZone' )
|
|
-- PatrolSpawn = SPAWN:New( 'Patrol Group' )
|
|
-- PatrolArea = AI_PATROLZONE:New( PatrolZone, 3000, 6000, 600, 900 )
|
|
function AI_PATROLZONE:New( PatrolZone, PatrolFloorAltitude, PatrolCeilingAltitude, PatrolMinSpeed, PatrolMaxSpeed )
|
|
|
|
local FSMT = {
|
|
initial = 'None',
|
|
events = {
|
|
{ name = 'Start', from = '*', to = 'Route' },
|
|
{ name = 'Route', from = '*', to = 'Route' },
|
|
{ name = 'Patrol', from = { 'Patrol', 'Route' }, to = 'Patrol' },
|
|
{ name = 'RTB', from = 'Patrol', to = 'RTB' },
|
|
{ name = 'End', from = '*', to = 'End' },
|
|
{ name = 'Dead', from = '*', to = 'End' },
|
|
},
|
|
callbacks = {
|
|
onenterRoute = self._EnterRoute,
|
|
onenterPatrol = self._EnterPatrol,
|
|
onenterRTB = self._EnterRTB,
|
|
onenterEnd = self._EnterEnd,
|
|
},
|
|
}
|
|
|
|
-- Inherits from BASE
|
|
local self = BASE:Inherit( self, STATEMACHINE:New( FSMT ) )
|
|
|
|
self.PatrolZone = PatrolZone
|
|
self.PatrolFloorAltitude = PatrolFloorAltitude
|
|
self.PatrolCeilingAltitude = PatrolCeilingAltitude
|
|
self.PatrolMinSpeed = PatrolMinSpeed
|
|
self.PatrolMaxSpeed = PatrolMaxSpeed
|
|
|
|
return self
|
|
end
|
|
|
|
|
|
|
|
--- Set the @{Group} to act as the Patroller.
|
|
-- @param #AI_PATROLZONE self
|
|
-- @param Group#GROUP PatrolGroup The @{Group} patrolling.
|
|
-- @return #AI_PATROLZONE self
|
|
function AI_PATROLZONE:SetGroup( PatrolGroup )
|
|
|
|
self.PatrolGroup = PatrolGroup
|
|
self.PatrolGroupTemplateName = PatrolGroup:GetName()
|
|
|
|
return self
|
|
end
|
|
|
|
|
|
|
|
--- Sets (modifies) the minimum and maximum speed of the patrol.
|
|
-- @param #AI_PATROLZONE self
|
|
-- @param DCSTypes#Speed PatrolMinSpeed The minimum speed of the @{Group} in km/h.
|
|
-- @param DCSTypes#Speed PatrolMaxSpeed The maximum speed of the @{Group} in km/h.
|
|
-- @return #AI_PATROLZONE self
|
|
function AI_PATROLZONE:SetSpeed( PatrolMinSpeed, PatrolMaxSpeed )
|
|
self:F2( { PatrolMinSpeed, PatrolMaxSpeed } )
|
|
|
|
self.PatrolMinSpeed = PatrolMinSpeed
|
|
self.PatrolMaxSpeed = PatrolMaxSpeed
|
|
end
|
|
|
|
|
|
|
|
--- Sets the floor and ceiling altitude of the patrol.
|
|
-- @param #AI_PATROLZONE self
|
|
-- @param DCSTypes#Altitude PatrolFloorAltitude The lowest altitude in meters where to execute the patrol.
|
|
-- @param DCSTypes#Altitude PatrolCeilingAltitude The highest altitude in meters where to execute the patrol.
|
|
-- @return #AI_PATROLZONE self
|
|
function AI_PATROLZONE:SetAltitude( PatrolFloorAltitude, PatrolCeilingAltitude )
|
|
self:F2( { PatrolFloorAltitude, PatrolCeilingAltitude } )
|
|
|
|
self.PatrolFloorAltitude = PatrolFloorAltitude
|
|
self.PatrolCeilingAltitude = PatrolCeilingAltitude
|
|
end
|
|
|
|
|
|
|
|
--- @param Group#GROUP PatrolGroup
|
|
function _NewPatrolRoute( PatrolGroup )
|
|
|
|
PatrolGroup:T( "NewPatrolRoute" )
|
|
local PatrolZone = PatrolGroup:GetState( PatrolGroup, "PatrolZone" ) -- PatrolZone#AI_PATROLZONE
|
|
PatrolZone:__Route( 1, PatrolGroup )
|
|
end
|
|
|
|
|
|
|
|
|
|
--- When the PatrolGroup is out of fuel, it is required that a new PatrolGroup is started, before the old PatrolGroup can return to the home base.
|
|
-- Therefore, with a parameter and a calculation of the distance to the home base, the fuel treshold is calculated.
|
|
-- When the fuel treshold is reached, the PatrolGroup will continue for a given time its patrol task in orbit, while a new PatrolGroup is targetted to the AI\_PATROLZONE.
|
|
-- Once the time is finished, the old PatrolGroup will return to the base.
|
|
-- @param #AI_PATROLZONE self
|
|
-- @param #number PatrolFuelTresholdPercentage The treshold in percentage (between 0 and 1) when the PatrolGroup is considered to get out of fuel.
|
|
-- @param #number PatrolOutOfFuelOrbitTime The amount of seconds the out of fuel PatrolGroup will orbit before returning to the base.
|
|
-- @return #AI_PATROLZONE self
|
|
function AI_PATROLZONE:ManageFuel( PatrolFuelTresholdPercentage, PatrolOutOfFuelOrbitTime )
|
|
|
|
self.PatrolManageFuel = true
|
|
self.PatrolFuelTresholdPercentage = PatrolFuelTresholdPercentage
|
|
self.PatrolOutOfFuelOrbitTime = PatrolOutOfFuelOrbitTime
|
|
|
|
return self
|
|
end
|
|
|
|
--- Defines a new patrol route using the @{PatrolZone} parameters and settings.
|
|
-- @param #AI_PATROLZONE self
|
|
-- @return #AI_PATROLZONE self
|
|
function AI_PATROLZONE:_EnterRoute( AIGroup )
|
|
|
|
self:F2()
|
|
|
|
local PatrolRoute = {}
|
|
|
|
if self.PatrolGroup:IsAlive() then
|
|
--- Determine if the PatrolGroup is within the PatrolZone.
|
|
-- If not, make a waypoint within the to that the PatrolGroup will fly at maximum speed to that point.
|
|
|
|
-- --- Calculate the current route point.
|
|
-- local CurrentVec2 = self.PatrolGroup:GetVec2()
|
|
-- local CurrentAltitude = self.PatrolGroup:GetUnit(1):GetAltitude()
|
|
-- local CurrentPointVec3 = POINT_VEC3:New( CurrentVec2.x, CurrentAltitude, CurrentVec2.y )
|
|
-- local CurrentRoutePoint = CurrentPointVec3:RoutePointAir(
|
|
-- POINT_VEC3.RoutePointAltType.BARO,
|
|
-- POINT_VEC3.RoutePointType.TurningPoint,
|
|
-- POINT_VEC3.RoutePointAction.TurningPoint,
|
|
-- ToPatrolZoneSpeed,
|
|
-- true
|
|
-- )
|
|
--
|
|
-- PatrolRoute[#PatrolRoute+1] = CurrentRoutePoint
|
|
|
|
self:T2( PatrolRoute )
|
|
|
|
if self.PatrolGroup:IsNotInZone( self.PatrolZone ) then
|
|
--- Find a random 2D point in PatrolZone.
|
|
local ToPatrolZoneVec2 = self.PatrolZone:GetRandomVec2()
|
|
self:T2( ToPatrolZoneVec2 )
|
|
|
|
--- Define Speed and Altitude.
|
|
local ToPatrolZoneAltitude = math.random( self.PatrolFloorAltitude, self.PatrolCeilingAltitude )
|
|
local ToPatrolZoneSpeed = self.PatrolMaxSpeed
|
|
self:T2( ToPatrolZoneSpeed )
|
|
|
|
--- Obtain a 3D @{Point} from the 2D point + altitude.
|
|
local ToPatrolZonePointVec3 = POINT_VEC3:New( ToPatrolZoneVec2.x, ToPatrolZoneAltitude, ToPatrolZoneVec2.y )
|
|
|
|
--- Create a route point of type air.
|
|
local ToPatrolZoneRoutePoint = ToPatrolZonePointVec3:RoutePointAir(
|
|
POINT_VEC3.RoutePointAltType.BARO,
|
|
POINT_VEC3.RoutePointType.TurningPoint,
|
|
POINT_VEC3.RoutePointAction.TurningPoint,
|
|
ToPatrolZoneSpeed,
|
|
true
|
|
)
|
|
|
|
PatrolRoute[#PatrolRoute+1] = ToPatrolZoneRoutePoint
|
|
|
|
end
|
|
|
|
--- Define a random point in the @{Zone}. The AI will fly to that point within the zone.
|
|
|
|
--- Find a random 2D point in PatrolZone.
|
|
local ToTargetVec2 = self.PatrolZone:GetRandomVec2()
|
|
self:T2( ToTargetVec2 )
|
|
|
|
--- Define Speed and Altitude.
|
|
local ToTargetAltitude = math.random( self.PatrolFloorAltitude, self.PatrolCeilingAltitude )
|
|
local ToTargetSpeed = math.random( self.PatrolMinSpeed, self.PatrolMaxSpeed )
|
|
self:T2( { self.PatrolMinSpeed, self.PatrolMaxSpeed, ToTargetSpeed } )
|
|
|
|
--- Obtain a 3D @{Point} from the 2D point + altitude.
|
|
local ToTargetPointVec3 = POINT_VEC3:New( ToTargetVec2.x, ToTargetAltitude, ToTargetVec2.y )
|
|
|
|
--- Create a route point of type air.
|
|
local ToTargetRoutePoint = ToTargetPointVec3:RoutePointAir(
|
|
POINT_VEC3.RoutePointAltType.BARO,
|
|
POINT_VEC3.RoutePointType.TurningPoint,
|
|
POINT_VEC3.RoutePointAction.TurningPoint,
|
|
ToTargetSpeed,
|
|
true
|
|
)
|
|
|
|
--ToTargetPointVec3:SmokeRed()
|
|
|
|
PatrolRoute[#PatrolRoute+1] = ToTargetRoutePoint
|
|
|
|
--- Now we're going to do something special, we're going to call a function from a waypoint action at the PatrolGroup...
|
|
self.PatrolGroup:WayPointInitialize( PatrolRoute )
|
|
|
|
--- Do a trick, link the NewPatrolRoute function of the PATROLGROUP object to the PatrolGroup in a temporary variable ...
|
|
self.PatrolGroup:SetState( self.PatrolGroup, "PatrolZone", self )
|
|
self.PatrolGroup:WayPointFunction( #PatrolRoute, 1, "_NewPatrolRoute" )
|
|
|
|
--- NOW ROUTE THE GROUP!
|
|
self.PatrolGroup:WayPointExecute( 1 )
|
|
|
|
self:__Patrol( 30, self.PatrolGroup )
|
|
end
|
|
|
|
end
|
|
|
|
|
|
--- @param #AI_PATROLZONE self
|
|
function AI_PATROLZONE:_EnterPatrol( AIGroup )
|
|
self:F2()
|
|
|
|
if self.PatrolGroup and self.PatrolGroup:IsAlive() then
|
|
|
|
local Fuel = self.PatrolGroup:GetUnit(1):GetFuel()
|
|
if Fuel < self.PatrolFuelTresholdPercentage then
|
|
local OldPatrolGroup = self.PatrolGroup
|
|
local PatrolGroupTemplate = self.PatrolGroup:GetTemplate()
|
|
|
|
local OrbitTask = OldPatrolGroup:TaskOrbitCircle( math.random( self.PatrolFloorAltitude, self.PatrolCeilingAltitude ), self.PatrolMinSpeed )
|
|
local TimedOrbitTask = OldPatrolGroup:TaskControlled( OrbitTask, OldPatrolGroup:TaskCondition(nil,nil,nil,nil,self.PatrolOutOfFuelOrbitTime,nil ) )
|
|
OldPatrolGroup:SetTask( TimedOrbitTask, 10 )
|
|
|
|
self:RTB( self.PatrolGroup )
|
|
else
|
|
self:__Patrol( 30, self.PatrolGroup ) -- Execute the Patrol event after 30 seconds.
|
|
end
|
|
end
|
|
|
|
end
|