Module Patrol
(AI) (FSM) Make AI patrol routes or zones.
1) #AI_PATROLZONE class, extends Core.Fsm#FSM_CONTROLLABLE
The #AI_PATROLZONE class implements the core functions to patrol a Zone by an AIR Controllable 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 AIControllable it is controlling.
1.2.1) AI_PATROLZONE Events:
- AI_PATROLZONE.Route( AIControllable ): A new 3D route point is selected and the AIControllable will fly towards that point with the given speed.
- AI_PATROLZONE.Patrol( AIControllable ): The AIControllable reports it is patrolling. This event is called every 30 seconds.
- AI_PATROLZONE.RTB( AIControllable ): The AIControllable will report return to base.
- AI_PATROLZONE.End( AIControllable ): The end of the AI_PATROLZONE process.
- AI_PATROLZONE.Dead( AIControllable ): The AIControllable 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 AIControllable will fly towards that point with the given speed.
- Patrol: The AIControllable is patrolling. This state is set every 30 seconds, so every 30 seconds, a state transition method can be used.
- RTB: The AIControllable reports it wants to return to the base.
- Dead: The AIControllable is dead ...
- End: The process has come to an end.
1.2.3) AI_PATROLZONE state transition methods:
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 methods will be called by the state machine:
Before the state transition. The state transition method needs to start with the name OnBefore + the name of the state. If the state transition method returns false, then the processing of the state transition will not be done! If you want to change the behaviour of the AIControllable at this event, return false, but then you'll need to specify your own logic using the AIControllable!
After the state transition. The state transition method needs to start with the name OnAfter + the name of the state. These state transition methods 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:SetControllable( PatrolGroup )
Patrol:ManageFuel( 0.2, 60 )
OnBeforeRTB( AIGroup ) will be called by the AIPATROLZONE object when the AIGroup reports RTB, but before the RTB default action is processed by the AIPATROLZONE object.
--- State transition function for the AI_PATROLZONE **Patrol** object
-- @param #AI_PATROLZONE self
-- @param Wrapper.Controllable#CONTROLLABLE AIGroup
-- @return #boolean If false is returned, then the OnAfter state transition method will not be called.
function Patrol:OnBeforeRTB( AIGroup )
AIGroup:MessageToRed( "Returning to base", 20 )
end
OnAfterRTB( AIGroup ) will be called by the AIPATROLZONE object when the AIGroup reports RTB, but after the RTB default action was processed by the AIPATROLZONE object.
--- State transition function for the AI_PATROLZONE **Patrol** object
-- @param #AI_PATROLZONE self
-- @param Wrapper.Controllable#CONTROLLABLE AIGroup
-- @return #Wrapper.Controllable#CONTROLLABLE The new AIGroup object that is set to be patrolling the zone.
function Patrol:OnAfterRTB( AIGroup )
return PatrolSpawn:Spawn()
end
1.3) Manage the AI_PATROLZONE parameters:
The following methods are available to modify the parameters of a AI_PATROLZONE object:
- AI_PATROLZONE.SetControllable(): Set the AIControllable.
- AI_PATROLZONE.GetControllable(): Get the AIControllable.
- 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 AIControllable is out of fuel, it is required that a new AIControllable is started, before the old AIControllable 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 AIControllable will continue for a given time its patrol task in orbit, while a new AIControllable is targetted to the AI_PATROLZONE. Once the time is finished, the old AIControllable 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-09-01: Initial class and API.
AUTHORS and CONTRIBUTIONS
Contributions:
- DutchBaron: Testing.
- Pikey: Testing and API concept review.
Authors:
- FlightControl: Design & Programming.
Global(s)
| AI_PATROLZONE | |
| _NewPatrolRoute(AIControllable) |
Type AI_PATROLZONE
Global(s)
- _NewPatrolRoute(AIControllable)
-
Parameter
-
Wrapper.Controllable#CONTROLLABLE AIControllable:
-
Type Patrol
Type AI_PATROLZONE
AI_PATROLZONE class
Field(s)
- #string AI_PATROLZONE.ClassName
- AI_PATROLZONE:ManageFuel(PatrolFuelTresholdPercentage, PatrolOutOfFuelOrbitTime)
-
When the AIControllable is out of fuel, it is required that a new AIControllable is started, before the old AIControllable 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 AIControllable will continue for a given time its patrol task in orbit, while a new AIControllable is targetted to the AI_PATROLZONE. Once the time is finished, the old AIControllable will return to the base.
Parameters
-
#number PatrolFuelTresholdPercentage: The treshold in percentage (between 0 and 1) when the AIControllable is considered to get out of fuel. -
#number PatrolOutOfFuelOrbitTime: The amount of seconds the out of fuel AIControllable will orbit before returning to the base.
Return value
#AI_PATROLZONE: self
-
- AI_PATROLZONE:New(PatrolZone, PatrolFloorAltitude, PatrolCeilingAltitude, PatrolMinSpeed, PatrolMaxSpeed)
-
Creates a new AI_PATROLZONE object
Parameters
-
Core.Zone#ZONE_BASE PatrolZone: The Zone where the patrol needs to be executed. -
Dcs.DCSTypes#Altitude PatrolFloorAltitude: The lowest altitude in meters where to execute the patrol. -
Dcs.DCSTypes#Altitude PatrolCeilingAltitude: The highest altitude in meters where to execute the patrol. -
Dcs.DCSTypes#Speed PatrolMinSpeed: The minimum speed of the Controllable in km/h. -
Dcs.DCSTypes#Speed PatrolMaxSpeed: The maximum speed of the Controllable in km/h.
Return value
#AI_PATROLZONE: self
Usage:
-- Define a new AI_PATROLZONE Object. This PatrolArea will patrol an AIControllable 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 ) -
- AI_PATROLZONE:OnAfterRoute(Controllable)
-
OnAfter State Transition Function
Parameter
-
Wrapper.Controllable#CONTROLLABLE Controllable:
-
- AI_PATROLZONE:OnBeforeRoute(Controllable)
-
OnBefore State Transition Function
Parameter
-
Wrapper.Controllable#CONTROLLABLE Controllable:
Return value
#boolean:
-
- Dcs.DCSTypes#Altitude AI_PATROLZONE.PatrolCeilingAltitude
-
The highest altitude in meters where to execute the patrol.
- Dcs.DCSTypes#Altitude AI_PATROLZONE.PatrolFloorAltitude
-
The lowest altitude in meters where to execute the patrol.
- #boolean AI_PATROLZONE.PatrolManageFuel
- Dcs.DCSTypes#Speed AI_PATROLZONE.PatrolMaxSpeed
-
The maximum speed of the Controllable in km/h.
- Dcs.DCSTypes#Speed AI_PATROLZONE.PatrolMinSpeed
-
The minimum speed of the Controllable in km/h.
- Core.Zone#ZONE_BASE AI_PATROLZONE.PatrolZone
-
The Zone where the patrol needs to be executed.
- AI_PATROLZONE:SetAltitude(PatrolFloorAltitude, PatrolCeilingAltitude)
-
Sets the floor and ceiling altitude of the patrol.
Parameters
-
Dcs.DCSTypes#Altitude PatrolFloorAltitude: The lowest altitude in meters where to execute the patrol. -
Dcs.DCSTypes#Altitude PatrolCeilingAltitude: The highest altitude in meters where to execute the patrol.
Return value
#AI_PATROLZONE: self
-
- AI_PATROLZONE:SetSpeed(PatrolMinSpeed, PatrolMaxSpeed)
-
Sets (modifies) the minimum and maximum speed of the patrol.
Parameters
-
Dcs.DCSTypes#Speed PatrolMinSpeed: The minimum speed of the Controllable in km/h. -
Dcs.DCSTypes#Speed PatrolMaxSpeed: The maximum speed of the Controllable in km/h.
Return value
#AI_PATROLZONE: self
-
- AI_PATROLZONE:onenterRoute()
-
Defines a new patrol route using the Process_PatrolZone parameters and settings.
Return value
#AI_PATROLZONE: self