Module Process_PatrolZone
(AI) Make AI patrol routes or zones.
1) #PROCESS_PATROLZONE class, extends StateMachine#STATEMACHINE
The #PROCESS_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) PROCESS_PATROLZONE constructor:
- PROCESS_PATROLZONE.New(): Creates a new PROCESS_PATROLZONE object.
1.2) PROCESS_PATROLZONE state machine:
The PROCESS_PATROLZONE is a state machine: it manages the different events and states of the AIControllable it is controlling.
1.2.1) PROCESS_PATROLZONE Events:
- PROCESS_PATROLZONE.Route( AIControllable ): A new 3D route point is selected and the AIControllable will fly towards that point with the given speed.
- PROCESS_PATROLZONE.Patrol( AIControllable ): The AIControllable reports it is patrolling. This event is called every 30 seconds.
- PROCESS_PATROLZONE.RTB( AIControllable ): The AIControllable will report return to base.
- PROCESS_PATROLZONE.End( AIControllable ): The end of the PROCESS_PATROLZONE process.
- PROCESS_PATROLZONE.Dead( AIControllable ): The AIControllable is dead. The PROCESS_PATROLZONE process will be ended.
1.2.2) PROCESS_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 function 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) PROCESS_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 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 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 PROCESS_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 = PROCESS_PATROLZONE:New( PatrolZone, 3000, 6000, 300, 600 )
Patrol:SetControllable( PatrolGroup )
Patrol:ManageFuel( 0.2, 60 )
OnBeforeRTB( AIGroup ) will be called by the PROCESS_PATROLZONE object when the AIGroup reports RTB, but before the RTB default action is processed by the PROCESS_PATROLZONE object.
--- State transition function for the PROCESS\_PATROLZONE **Patrol** object
-- @param #PROCESS_PATROLZONE self
-- @param Controllable#CONTROLLABLE 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
OnAfterRTB( AIGroup ) will be called by the PROCESS_PATROLZONE object when the AIGroup reports RTB, but after the RTB default action was processed by the PROCESS_PATROLZONE object.
--- State transition function for the PROCESS\_PATROLZONE **Patrol** object
-- @param #PROCESS_PATROLZONE self
-- @param Controllable#CONTROLLABLE AIGroup
-- @return #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 PROCESS_PATROLZONE parameters:
The following methods are available to modify the parameters of a PROCESS_PATROLZONE object:
- PROCESS_PATROLZONE.SetControllable(): Set the AIControllable.
- PROCESS_PATROLZONE.GetControllable(): Get the AIControllable.
- PROCESS_PATROLZONE.SetSpeed(): Set the patrol speed of the AI, for the next patrol.
- PROCESS_PATROLZONE.SetAltitude(): Set altitude of the AI, for the next patrol.
1.3) Manage the out of fuel in the PROCESS_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 PROCESS_PATROLZONE. Once the time is finished, the old AIControllable will return to the base. Use the method PROCESS_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)
| PROCESS_PATROLZONE | |
| _NewPatrolRoute(AIControllable) |
Type PROCESS_PATROLZONE
Global(s)
- _NewPatrolRoute(AIControllable)
-
Parameter
-
Controllable#CONTROLLABLE AIControllable:
-
Type Process_PatrolZone
Type PROCESS_PATROLZONE
PROCESS_PATROLZONE class
Field(s)
- Controllable#CONTROLLABLE PROCESS_PATROLZONE.AIControllable
-
The Controllable patrolling.
- #string PROCESS_PATROLZONE.ClassName
- PROCESS_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 PROCESS_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
#PROCESS_PATROLZONE: self
-
- PROCESS_PATROLZONE:New(PatrolZone, PatrolFloorAltitude, PatrolCeilingAltitude, PatrolMinSpeed, PatrolMaxSpeed)
-
Creates a new PROCESS_PATROLZONE object
Parameters
-
Zone#ZONE_BASE PatrolZone: The Zone where the patrol needs to be executed. -
DCSTypes#Altitude PatrolFloorAltitude: The lowest altitude in meters where to execute the patrol. -
DCSTypes#Altitude PatrolCeilingAltitude: The highest altitude in meters where to execute the patrol. -
DCSTypes#Speed PatrolMinSpeed: The minimum speed of the Controllable in km/h. -
DCSTypes#Speed PatrolMaxSpeed: The maximum speed of the Controllable in km/h.
Return value
#PROCESS_PATROLZONE: self
Usage:
-- Define a new PROCESS_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 = PROCESS_PATROLZONE:New( PatrolZone, 3000, 6000, 600, 900 ) -
- PROCESS_PATROLZONE:OnAfterRoute(Controllable)
-
OnAfter State Transition Function
Parameter
-
Controllable#CONTROLLABLE Controllable:
-
- PROCESS_PATROLZONE:OnBeforeRoute(Controllable)
-
OnBefore State Transition Function
Parameter
-
Controllable#CONTROLLABLE Controllable:
Return value
#boolean:
-
- DCSTypes#Altitude PROCESS_PATROLZONE.PatrolCeilingAltitude
-
The highest altitude in meters where to execute the patrol.
- DCSTypes#Altitude PROCESS_PATROLZONE.PatrolFloorAltitude
-
The lowest altitude in meters where to execute the patrol.
- #boolean PROCESS_PATROLZONE.PatrolManageFuel
- DCSTypes#Speed PROCESS_PATROLZONE.PatrolMaxSpeed
-
The maximum speed of the Controllable in km/h.
- DCSTypes#Speed PROCESS_PATROLZONE.PatrolMinSpeed
-
The minimum speed of the Controllable in km/h.
- Zone#ZONE_BASE PROCESS_PATROLZONE.PatrolZone
-
The Zone where the patrol needs to be executed.
- PROCESS_PATROLZONE:SetAltitude(PatrolFloorAltitude, PatrolCeilingAltitude)
-
Sets the floor and ceiling altitude of the patrol.
Parameters
-
DCSTypes#Altitude PatrolFloorAltitude: The lowest altitude in meters where to execute the patrol. -
DCSTypes#Altitude PatrolCeilingAltitude: The highest altitude in meters where to execute the patrol.
Return value
#PROCESS_PATROLZONE: self
-
- PROCESS_PATROLZONE:SetSpeed(PatrolMinSpeed, PatrolMaxSpeed)
-
Sets (modifies) the minimum and maximum speed of the patrol.
Parameters
-
DCSTypes#Speed PatrolMinSpeed: The minimum speed of the Controllable in km/h. -
DCSTypes#Speed PatrolMaxSpeed: The maximum speed of the Controllable in km/h.
Return value
#PROCESS_PATROLZONE: self
-
- PROCESS_PATROLZONE:onenterRoute()
-
Defines a new patrol route using the Process_PatrolZone parameters and settings.
Return value
#PROCESS_PATROLZONE: self