Elite Wiki - User contributions [en]

Oolite Javascript Reference: PriorityAI Documentation

2014-08-01T03:01:06Z

Phasted: /* conditionMissileNeedsLaunchEvasion */

This page describes the priority-based Javascript AI system, which allows more flexible behaviour than the old plist-based AIs to be written in fewer lines of code. New programmers may find [[Oolite_PriorityAI_Tutorial|the priority AI tutorial]] to be more useful as an introduction.

Priority-based Javascript AI is available from Oolite 1.79 onwards.

== Constructor and general functions ==

==== Constructor ====
'''new PriorityAIController'''(ship : Ship) : PriorityAIController
Creates a priority AI and attaches it to the specified ship. Using this from anywhere other than that ship's AI script is not recommended.

var ai = new worldScripts["oolite-libPriorityAI"].PriorityAIController(this.ship);

=== Properties ===

==== <code>ship</code> ====
'''ship''' : Ship (read-only)
The ship to which the priority AI is attached.

=== General Methods ===

Additional methods are described in later sections, sorted by purpose.

==== <code>applyHandlers</code> ====
function '''applyHandlers'''(handlers : Object)
Deletes any existing event handlers applied to the ship's AI Script by a previous invocation of <code>applyHandlers</code>, and copies the handlers in the argument object to the AI Script. All handlers applied this way run with '<code>this</code>' equal to the PriorityAIController, not to the AI Script.

==== <code>clearHandlers</code> ====
function '''clearHandlers'''(handlers : Object)
Deletes any existing event handlers applied to the ship's AI Script by a previous invocation of <code>applyHandlers</code>.

==== <code>communicate</code> ====
function '''communicate'''(key : String, params : Object, priority : Number)
If the communication "key" has previously been [[#_setCommunication|defined]] for this ship's [[#setCommunicationsRole|communications role]] and [[#setCommunicationsPersonality|personality]], retrieves it, calls <code>expandDescription</code> on it, using the parameters in the object (which can either be a dictionary, or a Ship). This message may then broadcast on the public channel, depending on the priority. If the object is a Ship, it will be converted to a dictionary for expandDescription with the following parameters:
* <code>oolite_entityClass</code> = <code>ship.shipClassName</code>
* <code>oolite_entityName</code> = <code>ship.shipUniqueName</code>
Other parameters may be added later to this expansion.

The priority can be a number from 1 to 4
# Always send this message
# Send this message if no messages sent in the last 10 seconds
# Send this message if no messages sent or received in the last 10 seconds
# Send this message if no messages sent or received in the last 60 seconds
This is used to prevent an overwhelming number of comms messages being sent. While priority 1 is necessary for messages which must be heard by the player, care must be taken to ensure by other means that they cannot be sent repeatedly.

==== <code>communicationsPersonality</code> ====
function '''communicationsPersonality'''() : String
The current communications personality

==== <code>communicationsRole</code> ====
function '''communicationsRole'''() : String
The current communications role

==== <code>getParameter</code> ====
function '''getParameter'''(key : String) : Value
If a parameter with that key has previously been set, return its value. Otherwise return null. Note that the return value can be of any type, so you must be careful when setting and retrieving parameters to avoid type errors.

==== <code>getWaypointGenerator</code> ====
function '''getWaypointGenerator'''() : Function
If a waypoint generation function has previously been set, return it.

==== <code>noteCommsHeard</code> ====
function '''noteCommsHeard'''()
This function is used to reset the timers for [[#communicate|priority 3 and 4 communications]]. The standard event handlers will call this for you, but you may need to call it manually otherwise.

==== <code>reconsiderIn</code> ====
function '''reconsiderIn'''(delay : Number)
Force a reconsideration of the AI's priority list ahead of schedule, if no request for sooner reconsideration has already been received. <code>delay</code> must be at least 0.1 seconds.

==== <code>reconsiderNow</code> ====
function '''reconsiderNow'''()
Force a reconsideration of the AI's priority list ahead of schedule.

==== <code>setCommunicationsRole</code> ====
function '''setCommunicationsRole'''(role : String)
Sets the ship's communications role to the given value. This is then used to vary the communications messages as defined by [[#_setCommunication|_setCommunication]].

If personalities have previously been defined for this role, and the ship's current personality is either "generic" or not one defined for this role, then it will also select a new communications personality at this point, based on [[Oolite_JavaScript_Reference:_Ship#entityPersonality|ship.entityPersonality]]. If the "oolite_personalityMatchesLeader" parameter has been set, then this is a 0..1 chance that the ship will instead take the personality of its group leader (if this ship is the group leader, this instead is the chance it will copy its personality to group members)

==== <code>setCommunicationsPersonality</code> ====
function '''setCommunicationsPersonality'''(role : String)
Sets the ship's communications personality to the given value. This is then used to vary the communications messages as defined by [[#_setCommunication|_setCommunication]].

==== <code>setParameter</code> ====
function '''setParameter'''(key : String, value : Value)
Set the named parameter to the given value. Values may be of any type. To remove a parameter, use a value of null. See the [[#Parameters|Parameters]] section below for parameter keys used by the core AIs and the standard priority AI library.

==== <code>setPriorities</code> ====
function '''setPriorities'''(priorities : Array [, delay: Number])
Set the priority list for the AI, and evaluate it. The format of the priority list is described in the next section.

An optional delay parameter can be set, which will cause evaluation to start only after this many seconds. If it is unset, the AI will start after a random period between 0 and 1 seconds.

==== <code>setWaypointGenerator</code> ====
function '''setWaypointGenerator'''(generator : Function)
Sets the AI's [[#Waypoint_Generators|Waypoint Generators]] waypoint generator function.

=== Parameters ===
The following parameters are used by the standard library and accessed using [[#getParameter|getParameter]] and [[#setParameter|setParameter]], but you can also define your own for custom AIs. More detailed documentation will be provided soon.

As with all custom items, prefixing new parameter names with a key unique to your OXP is strongly advised.

==== Flag Parameters ====
Flag parameters are intended to be set in the AI initialisation routine to vary the behaviour of the AI.

oolite_flag_allowPlanetaryLanding
oolite_flag_autoSpreadMissiles
oolite_flag_behaviourLogging
oolite_flag_continueUnlikelyPursuits
oolite_flag_escortsCoverRetreat
oolite_flag_fightsNearHostileStations
oolite_flag_fleesPreemptively
oolite_flag_likesInterstellarSpace
oolite_flag_listenForDistressCall
oolite_flag_markOffenders
oolite_flag_neverFleeToWitchspace
oolite_flag_noDockingUntilDestination
oolite_flag_noSpecialThargoidReaction
oolite_flag_patrolStation
oolite_flag_scanIgnoresUnpowered
oolite_flag_selfDestructAbandonedShip
oolite_flag_sendsDistressCalls
oolite_flag_surrendersEarly
oolite_flag_surrendersLate
oolite_flag_watchForCargo
oolite_flag_witchspacePursuit

==== Other parameters ====
These parameters are used for storage of long-term state that may need to be kept between runs of the priority tree. In general, Configuration and Response functions set them, and Condition, Behaviour and Response functions read them, but this is only a guideline. Implementors of custom functions may need to get or set these parameters for proper interaction with built-in functions used by the same AI.

oolite_cargoDropped
oolite_cascadeDetected
oolite_distressAggressor
oolite_distressSender
oolite_distressTimestamp
oolite_dockingStation
oolite_escortRole
oolite_friendlyRoles
oolite_groupPower
oolite_interceptCoordinates
oolite_interceptTarget
oolite_lastAssist
oolite_lastFleeing
oolite_lastPirateVictim
oolite_leaderRole
oolite_personalityMatchesLeader
oolite_pirateLurk
oolite_playerFriendlyFireAlready
oolite_rememberedTarget
oolite_scanResults
oolite_scanResultSpecific
oolite_selectedPlanet
oolite_selectedStation
oolite_stationPatrolRole
oolite_waypoint
oolite_waypointRange
oolite_waypoints
oolite_witchspaceDestination
oolite_witchspaceEntry
oolite_witchspaceWormhole

== Writing a priority list ==

The priority list is the core of the priority AI. The list will be reevaluated periodically - either timed, or when events occur - and on each reevaluation it will be searched from top to bottom. When a valid priority is found, searching will stop, and that priority will be executed.

If the parameter "oolite_flag_behaviourLogging" is set with [[#setParameter|setParameter]] then verbose information will be written to the log file regarding the processing of the priority list. It is generally advisable to use the debug console to do this for one ship at a time, rather than setting it generally!

=== Basic structure ===

The priority list is an array of objects. Each object contains a set
of keys and values. The keys are considered in the
following order and are all optional.
* '''preconfiguration''': function run unconditionally if this element of the list is reached.
* '''condition''': function run unconditionally if this element of the list is reached. If it returns false, the remainder of the object is ignored, and consideration moves to the next list element.
* '''notcondition''': function run unconditionally if this element of the list is reached. If it returns true, the remainder of the object is ignored, and consideration moves to the next list element.
If neither '''condition''' nor '''notcondition''' are set, this is treated as if a condition was set and was true.
* '''configuration''': function run if conditions allow
* '''behaviour''': function run if conditions allow. If this exists, no further elements of the priority list will be considered.
* '''reconsider''': A number. If a behaviour is executed, the priority list will next be reconsidered in this many seconds. If this value is absent the priority list will only be considered if an event causes it.
* '''truebranch''': a priority list array. If there was no behaviour, but the conditions allow one to be run, the truebranch will be evaluated as a priority list. If the truebranch causes a behaviour to be executed, consideration will end here. If the truebranch reaches its end without executing a behaviour, consideration will continue with the next element of the main priority list.
* '''falsebranch''': a priority list array. This will be executed if the the conditions caused the previous four elements to be skipped.

If evaluation reaches the end of the main priority list without finding a behaviour to execute, an error will be noted in the log. In general the last element of the main priority list should always be unconditional (or have a truebranch and a falsebranch, both of which have an unconditional last element).

Example of simple behaviour: (from thargoid AI)
{
preconfiguration: ai.configurationCheckScanner,
condition: ai.conditionScannerContainsNonThargoid,
configuration: ai.configurationAcquireScannedTarget,
behaviour: ai.behaviourDestroyCurrentTarget,
reconsider: 1
},

Example of branch usage: (from police AI)
{
/* The group leader leads the patrol */
condition: ai.conditionIsGroupLeader,
truebranch: [
/* Nothing interesting here. Patrol for a bit */
{
condition: ai.conditionHasWaypoint,
configuration: ai.configurationSetDestinationToWaypoint,
behaviour: ai.behaviourApproachDestination,
reconsider: 30
},
/* No patrol route set up. Make one */
{
configuration: ai.configurationSetWaypoint,
behaviour: ai.behaviourApproachDestination,
reconsider: 30
}
],
/* Other ships in the group will set themselves up
* as escorts if possible, or looser followers if
* not */
falsebranch: [
{
preconfiguration: ai.configurationEscortGroupLeader,
condition: ai.conditionIsEscorting,
behaviour: ai.behaviourEscortMothership,
reconsider: 30
},
/* if we can't set up as an escort */
{
behaviour: ai.behaviourFollowGroupLeader,
reconsider: 15
}
]
}

The AI Library provides a selection of standard condition,
configuration and behaviour functions for us in AIs, but you can also
write your own.
/* Ship is unstable and may explode under stress */
{
condition: function()
{
return Math.random() < 0.01; // 1% chance per evaluation
}
behaviour: function()
{
this.ship.explode();
}
}

=== Evaluation context ===

All condition, configuration and behaviour functions are evaluated in the context of the AI object. The '<code>this</code>' variable when one of these functions is run therefore points to the priority AI, '''not''' to the AI Script.

Note that <code>this.ship</code> is defined and will be equivalent to the this.ship seen by the AI Script. However, if you wish to access properties of the AI Script you must use <code>this.ship.AIScript.''property''</code>. Properties and methods of the priority AI may be accessed directly, e.g. <code>[[#allied|this.allied]](this.ship,this.ship.target)</code>.

== Behaviour functions ==

Behaviour functions determine what the ship will do next. They
generally begin a particular behaviour, and set up event handlers
(generally aided by the response templates) to allow interruption or
modification of that behaviour should anything interesting happen.

Behaviour functions take no arguments and return nothing.

=== General behaviours ===

Behaviours intended for ships in general. These mostly use <code>responsesAddStandard</code>, and occasionally add others.

==== <code>behaviourApproachDestination</code> ====
function '''behaviourApproachDestination'''()
Travels from the current position to within <code>desiredRange</code> of <code>destination</code>, avoiding obstacles on the way.

If a waypoint is set in the parameters "oolite_waypoint" and "oolite_waypointRange", it will clear these parameters if when it reaches its destination it is sufficiently close to the waypoint. If the parameter "oolite_flag_patrolStation" is set, and its group leader is a station, it will report in to the station upon reaching the waypoint.

Temporary waypoints needed to avoid obstacles will be stored in the
"oolite_waypoints" parameter.

==== <code>behaviourAssassinateCurrentTarget</code> ====
function '''behaviourAssassinateCurrentTarget'''()
This behaviour attacks the current target, only stopping when interrupted or when the target is destroyed. It will potentially send both "oolite_beginningAssassination" and "oolite_beginningFight" communications messages (though if the former is defined, the latter will not be sent due to the communications priority system). This is otherwise identical in behaviour to [[#behaviourCommenceAttackOnCurrentTarget|behaviourCommenceAttackOnCurrentTarget]]

==== <code>behaviourAvoidCascadeExplosion</code> ====
function '''behaviourAvoidCascadeExplosion'''()
Fly, using injectors if available, to a safe distance from any nearby quirium cascades (or active mines)

==== <code>behaviourBecomeInactiveThargon</code> ====
function '''behaviourBecomeInactiveThargon'''()
This behaviour is intended to deactivate thargons and should generally only be used for that purpose. It changes the scan class to CLASS_CARGO, clears the ship's targeting information, brings it to a stop, removes it from its ship groups, and removes it from nearby NPCs targeting systems (it can be retargeted). Unlike the equivalent plist AI command, it does not remove it as a player target.

==== <code>behaviourCollectSalvage</code> ====
function '''behaviourCollectSalvage'''()
This behaviour attempts to scoop the current target. If it is successful, the "oolite_cargoDropped" parameter recording the number of seen cargo pods will be cleared.

==== <code>behaviourCommenceAttackOnCurrentTarget</code> ====
function '''behaviourCommenceAttackOnCurrentTarget'''()
This behaviour attacks the current target, only stopping when interrupted or when the target is destroyed. Unlike the <code>behaviourDestroyCurrentTarget</code> behaviour, it may first send the "[[#oolite_beginningFight|oolite_beginningFight]]" communications message, so should only be used when starting a fight with a new target/group - not when in the middle of a fight.

==== <code>behaviourDestroyCurrentTarget</code> ====
function '''behaviourDestroyCurrentTarget'''()
This behaviour attacks the current target, only stopping when interrupted or when the target is destroyed.

==== <code>behaviourDockWithStation</code> ====
function '''behaviourDockWithStation'''()
This behaviour docks with the station specified in the parameter "oolite_dockingStation". If the target refuses docking or the ship is too big to dock, the parameter will be cleared.

==== <code>behaviourEnterWitchspace</code> ====
function '''behaviourEnterWitchspace'''()
This behaviour attempts to enter witchspace. It can do this in several ways:
* If the parameter "oolite_witchspaceWormhole" is set to an active wormhole, it will try to fly to and use that wormhole.
* If the parameter "oolite_witchspaceDestination" is set, then it will try to jump to that destination using its own drive. It will wait for its escorts to be launched, and will start spinning up this drive. Calling this behaviour again after 15 seconds will cause it to jump out.
* Otherwise, it will wait for a wormhole to be suggested by another member of its group, or for the player to create one.

==== <code>behaviourEscortMothership</code> ====
function '''behaviourEscortMothership'''()
This behaviour performs non-combat escorting of the ship's group leader, in the formation requested by the lead ship.

==== <code>behaviourFineCurrentTarget</code> ====
function '''behaviourFineCurrentTarget'''()
If the ship has scan class "CLASS_POLICE" and a current target, mark that target for fines when it next docks.

==== <code>behaviourFleeCombat</code> ====
function '''behaviourFleeCombat'''()
The ship will flee from hostility, in the following order:
* Cascade explosions (coordinates from the parameter "oolite_cascadeDetected")
* Its current target, if it can see it
* Its defense targets, if it can see them

==== <code>behaviourFollowCurrentTarget</code> ====
function '''behaviourFollowCurrentTarget'''()
The ship will follow the current target, including through a witchspace jump if necessary, and will additionally [[#conditionHasRememberedTarget|remember]] the target.

==== <code>behaviourFollowGroupLeader</code> ====
function '''behaviourFollowGroupLeader'''()
The ship will follow the group leader if there is one, attempting to remain within a few kilometres of it.

==== <code>behaviourGuardTarget</code> ====
function '''behaviourGuardTarget'''()
The ship will fly to within a few kilometres of its current target. Similar to <code>behaviourFollowCurrentTarget</code> but will not follow the target into witchspace and will not remember that it was doing so if distracted.

==== <code>behaviourJoinTargetGroup</code> ====
function '''behaviourJoinTargetGroup'''()
The ship will add itself to its target's ship group. You should previously have used appropriate condition tests to check that this is appropriate behaviour.

==== <code>behaviourLandOnPlanet</code> ====
function '''behaviourLandOnPlanet'''()
Lands on the nearest planet. Unlike most behaviours, this one does not include the standard responses, so you should generally wait until the ship is only a few hundred metres above the surface before using it.

==== <code>behaviourLeaveVicinityOfDestination</code> ====
function '''behaviourLeaveVicinityOfDestination'''()
Moves outside scanner range of the current destination coordinates.

==== <code>behaviourLeaveVicinityOfTarget</code> ====
function '''behaviourLeaveVicinityOfTarget'''()
Moves outside scanner range of the current target. Unlike fleeing, this does not use fuel injectors if they are fitted, and does not cause the ship to appear hostile to its target.

==== <code>behaviourMineTarget</code> ====
function '''behaviourMineTarget'''()
Attacks the current target with a mining laser to break it into splinters. If the current target is not a rock, this behaviour will be cancelled and the target will be lost.

==== <code>behaviourOfferToEscort</code> ====
function '''behaviourOfferToEscort'''()
Offers to escort the ship identified by the parameter "oolite_scanResultSpecific". Unless this parameter has been set by the scanner condition [[#conditionScannerContainsShipNeedingEscort|conditionScannerContainsShipNeedingEscort]] this is extremely likely to fail.

To be accepted as an escort, the ship must have a primary role in the <code>oolite-escorts</code> [[role-categories.plist|role category]].

==== <code>behaviourPayOffPirates</code> ====
function '''behaviourPayOffPirates'''()
If a pirate demand to dump cargo exists, dump that many cargo canisters (or all of them, if fewer), and then switch to [[#behaviourFleeCombat|behaviourFleeCombat]]

==== <code>behaviourReconsider</code> ====
function '''behaviourReconsider'''()
Does nothing except schedule a re-evaluation of the priority list.

==== <code>behaviourRejoinMothership</code> ====
function '''behaviourRejoinMothership'''()
This behaviour flies to rejoin the mothership, and then escorts it as in [[#behaviourEscortMothership|behaviourEscortMothership]].

==== <code>behaviourRepelCurrentTarget</code> ====
function '''behaviourRepelCurrentTarget'''()
This behaviour attacks the current target, but will break off the attack (and ask its escorts to do the same) if the target starts fleeing.

==== <code>behaviourRespondToDistressCall</code> ====
function '''behaviourRespondToDistressCall'''()
If the ship has a valid distress call represented by the parameters "oolite_distressAggressor" and "oolite_distressSender" it will attack the aggressor if it can see it. Otherwise it will fly (with injectors if available) to near the sender, attempting to locate the aggressor.

If the aggressor has a lower bounty than the sender, then the ship will assume that the distress call is "unjust", and attack the sender instead.

==== <code>behaviourRobTarget</code> ====
function '''behaviourRobTarget'''()
If an existing group demand for cargo is in effect, attack the current target in the hope that it meets it. Demands are stored with the group leader if possible.

If there is no existing demand for cargo, create one based on the cargo capacity of the target ship, the current system government, the cargo capacity of the group, and other factors.

==== <code>behaviourSunskim</code> ====
function '''behaviourSunskim'''()
Fly along until fuel tanks are full. In general, this behaviour should not be started until sunskimming height is reached (test with [[#conditionReadyToSunskim|conditionReadyToSunskim]]), and [[#configurationSetDestinationToSunskimEnd|configurationSetDestinationToSunskimEnd]] should be used to set a safe sunskimming direction.

==== <code>behaviourTumble</code> ====
function '''behaviourTumble'''()
Start tumbling. Unlike most behaviours, this one does not include the standard responses, so you will need to manually request a reconsideration of priorities if one is needed.

=== Missile behaviours ===

Missile behaviours use <code>responsesAddMissile</code>. More discussion of setting missile parameters, ECM response, and detonation can be found there.

==== <code>behaviourMissileInterceptCoordinates</code> ====
function '''behaviourMissileInterceptCoordinates'''()
Close to the desired missile range (default 25m, or specified by the <code>oolite_missile_proximity</code> key in script info), detonating when reached. The coordinates to close in on are specified in the "oolite_interceptCoordinates". This is used to track missile targets which cloak.

==== <code>behaviourMissileInterceptTarget</code> ====
function '''behaviourMissileInterceptTarget'''()
Close to the desired missile range (default 25m, or specified by the <code>oolite_missile_proximity</code> key in script info), detonating when reached.

==== <code>behaviourMissileSelfDestruct</code> ====
function '''behaviourMissileSelfDestruct'''()
Destroys the missile without detonating the payload.

=== Station behaviours ===

Station behaviours use <code>responsesAddStation</code> to set up their general handlers, as most standard behaviours are unnecessary or unhelpful for a stationary station.

==== <code>behaviourStationLaunchDefenseShips</code> ====
function '''behaviourStationLaunchDefenseShips'''()
If the station has a target and the target is aggressive, launches a defense ship if any remain, increases the alert condition to Red, and requests a group attack on the target. Otherwise does nothing.

==== <code>behaviourStationLaunchMiner</code> ====
function '''behaviourStationLaunchMiner'''()
If the station does not currently have a miner in its ship group, launches one. Also reduces the alert condition by one step.

==== <code>behaviourStationLaunchPatrol</code> ====
function '''behaviourStationLaunchPatrol'''()
If the station does not currently have a ship in its ship group with the primary role equal to the parameter "oolite_stationPatrolRole", launches one. Also reduces the alert condition by one step.

==== <code>behaviourStationLaunchSalvager</code> ====
function '''behaviourStationLaunchMiner'''()
Launches a salvager. Also reduces the alert condition by one step.

==== <code>behaviourStationManageTraffic</code> ====
function '''behaviourStationManageTraffic'''()
The station idles. If the system repopulator has requested launches that this station can fulfil, it may launch a ship.

==== <code>behaviourStationRespondToDistressCall</code> ====
function '''behaviourStationRespondToDistressCall'''()
Locates the aggressor and sender in the same way as [[#behaviourRespondToDistressCall|behaviourRespondToDistressCall]. If the aggressor is not visible, does nothing, otherwise sets the aggressor as a target, increases alert condition to Red, and launches a defense ship to attack the aggressor.

== Condition functions ==

Condition functions are used to determine whether to execute a
priority AI behaviour. They take no arguments and return a Boolean.

=== Combat conditions ===

Conditions related to the ship's performance in combat.

==== <code>conditionCascadeDetected</code> ====
function '''conditionCascadeDetected'''() : Boolean
Returns true if a cascade explosion has been detected recently (as given by the parameter "oolite_cascadeDetected" containing the explosion coordinates).

==== <code>conditionCombatOdds*</code> ====
function '''conditionCombatOddsTerrible'''() : Boolean
function '''conditionCombatOddsBad'''() : Boolean
function '''conditionCombatOddsGood'''() : Boolean
function '''conditionCombatOddsExcellent'''() : Boolean
These functions return true if the perceived odds of this ship's group winning a fight against the target ship's group can reasonably be described with the appropriate description. "Good" and "Excellent" require the odds to be better than a particular threshold (so Excellent odds are always also Good), while "Bad" and "Terrible" require the odds to be worse than that threshold.

==== <code>conditionGroupAttritionReached</code> ====
function '''conditionGroupAttritionReached'''() : Boolean
This condition is true if the ship is in a group and that group has lost more than a quarter of its initial ships.

==== <code>conditionGroupSuppliesLow</code> ====
function '''conditionGroupSuppliesLow'''() : Boolean
This condition is true if the ship's group is running out of consumables such as missiles or fuel, or has several damaged ships.

==== <code>conditionInCombat</code> ====
function '''conditionInCombat'''() : Boolean
The ship is currently attacking other ships, or a ship in its group or one of its escorts is.

==== <code>conditionInCombatWithHostiles</code> ====
function '''conditionInCombat'''() : Boolean
The ship is currently attacking other ships, or a ship in its group or one of its escorts is. Additionally, at least one of the targets of those ships is itself attacking (though not necessarily attacking anything from this ship's group)

==== <code>conditionLosingCombat</code> ====
function '''conditionLosingCombat'''() : Boolean
The ship is in combat, but is losing. The exact definition of "losing" may vary, and is intended to account for the overall tactical situation.

==== <code>conditionMothershipInCombat</code> ====
function '''conditionMothershipInCombat'''() : Boolean
This ship's group leader is attacking and/or being attacked. Other ships in the group are not considered. This ship must be able to see its leader's target.

==== <code>conditionMothershipIsAttacking</code> ====
function '''conditionMothershipIsAttacking'''() : Boolean
This ship's group leader is attacking a target. This ship must be able to see its leader's target.

==== <code>conditionMothershipIsAttackingHostileTarget</code> ====
function '''conditionMothershipIsAttacking'''() : Boolean
This ship's group leader is attacking a target which is itself attacking something. This ship must be able to see its leader's target.

==== <code>conditionMothershipUnderAttack</code> ====
function '''conditionMothershipUnderAttack'''() : Boolean
This ship's group leader is currently being targeted. This ship must be able to see the attacker.

==== <code>conditionSuppliesLow</code> ====
function '''conditionSuppliesLow'''() : Boolean
This condition is true if this ship is personally running out of consumables such as missiles or fuel, or is damaged. This is effectively a wrapper around <code>ship.damageAssessment()</code>.

=== Navigation conditions ===

Conditions related to the ship's surroundings and navigation through the system.

==== <code>conditionCanWitchspaceOnRoute</code> ====
function '''conditionCanWitchspaceOnRoute'''() : Boolean
The ship has a witchspace drive, a witchspace route, and the next system on its [[#setWitchspaceRouteTowitchspace|route]] is within range with the current fuel supply.

==== <code>conditionCanWitchspaceOut</code> ====
function '''conditionCanWitchspaceOut'''() : Boolean
The ship has a witchspace drive, and at least one other system is within range with the current fuel supply.

==== <code>conditionFriendlyStationExists</code> ====
function '''conditionFriendlyStationExists'''() : Boolean
There is at least one friendly station in the system.

==== <code>conditionFriendlyStationNearby</code> ====
function '''conditionFriendlyStationNearby'''() : Boolean
There is at least one friendly station within scanner range

==== <code>conditionGroupIsSeparated</code> ====
function '''conditionGroupIsSeparated'''() : Boolean
The ship is in a group and has a group leader, and is out of scanner range of that leader (or out of 2x scanner range if the leader is a station)

==== <code>conditionHasSelectedPlanet</code> ====
function '''conditionHasSelectedPlanet'''() : Boolean
The ship has a valid planet in the "oolite_selectedPlanet" parameter.

==== <code>conditionHasSelectedStation</code> ====
function '''conditionHasSelectedStation'''() : Boolean
The ship has a valid planet in the "oolite_selectedStation" parameter.

==== <code>conditionHomeStationExists</code> ====
function '''conditionHomeStationExists'''() : Boolean
The ship's home station still exists

==== <code>conditionHomeStationNearby</code> ====
function '''conditionHomeStationNearby'''() : Boolean
The ship's home station is within scanner range.

==== <code>conditionHostileStationNearby</code> ====
function '''conditionHostileStationNearby'''() : Boolean
There is at least one hostile station within scanner range

==== <code>conditionInInterstellarSpace</code> ====
function '''conditionInInterstellarSpace'''() : Boolean
The ship is currently in interstellar space.

==== <code>conditionMainPlanetNearby</code> ====
function '''conditionMainPlanetNearby'''() : Boolean
The ship is within 3 radii of the surface of the main planet

==== <code>conditionNearDestination</code> ====
function '''conditionNearDestination'''() : Boolean
The ship is closer than the desired range to its destination

==== <code>conditionPlayerNearby</code> ====
function '''conditionPlayerNearby'''() : Boolean
The player's ship is within scanner range.

==== <code>conditionReadyToSunskim</code> ====
function '''conditionReadyToSunskim'''() : Boolean
The ship is close enough to the sun to scoop fuel.

==== <code>conditionSelectedStationNearby</code> ====
function '''conditionSelectedStationNearby'''() : Boolean
The ship has a selected station in the "oolite_selectedStation" parameter, and it is within scanner range.

==== <code>conditionSelectedStationNearMainPlanet</code> ====
function '''conditionSelectedStationNearMainPlanet'''() : Boolean
The ship has a selected station in the "oolite_selectedStation" parameter, and it is within 3 radii of the surface of the main planet.

==== <code>conditionStationNearby</code> ====
function '''conditionStationNearby'''() : Boolean
There is a station within scanner range.

==== <code>conditionSunskimPossible</code> ====
function '''conditionSunskimPossible'''() : Boolean
There is a sun, it's not going nova, it hasn't gone nova, the ship has a non-full fuel tank and fuel scoops, and the ship has sufficient heat insulation to skim safely.

==== <code>conditionWormholeNearby</code> ====
function '''conditionWormholeNearby'''() : Boolean
There is an entry wormhole within scanner range.

=== Piracy-related conditions ===

Conditions involved in piratical activities.

==== <code>conditionCargoDemandsMet</code> ====
function '''conditionCargoDemandsMet'''() : Boolean
Since this ship (or an ally) made a cargo demand, this ship has seen enough cargo dropped to meet that demand.

==== <code>conditionGroupHasEnoughLoot</code> ====
function '''conditionGroupHasEnoughLoot'''() : Boolean
The group this ship belongs to has obtained enough cargo to call it a day. Currently this happens when cargo space usage is above 50%, but more sophisticated checks are planned involving damage or lost ships, expenditure of consumables, and so on.

==== <code>conditionPiratesCanBePaidOff</code> ====
function '''conditionPiratesCanBePaidOff'''() : Boolean
Pirates have demanded that this ship dump cargo, and it currently has enough cargo on board to meet that demand.

=== Scanning conditions ===

These conditions check the ship's latest scan ([[#configurationCheckScanner|configurationCheckScanner]]) for ships meeting particular requirements. If a ship is found, it will be placed in the "oolite_scanResultsSpecific" parameter, in addition to the condition returning true.

==== <code>conditionScannerContainsAssassinationTarget</code> ====
function '''conditionScannerContainsAssassinationTarget'''() : Boolean
The scan contains an assassination target (i.e. an escape capsule)

==== <code>conditionScannerContainsCleanShip</code> ====
function '''conditionScannerContainsCleanShip'''() : Boolean
The scan contains a clean ship

==== <code>conditionScannerContainsCourier</code> ====
function '''conditionScannerContainsCourier'''() : Boolean
The scan contains a courier ship

==== <code>conditionScannerContainsEscapePods</code> ====
function '''conditionScannerContainsEscapePods'''() : Boolean
The scan contains an escape pod travelling slower than this ship's maximum speed, and this ship is able to scoop cargo.

==== <code>conditionScannerContainsFineableOffender</code> ====
function '''conditionScannerContainsFineableOffender'''() : Boolean
The scan contains a piloted ship with an offender legal status at or below the system threshold (varies with government) that has not already been marked for fines.

==== <code>conditionScannerContainsFugitive</code> ====
function '''conditionScannerContainsFugitive'''() : Boolean
The scan contains a fugitive ship

==== <code>conditionScannerContainsHuntableOffender</code> ====
function '''conditionScannerContainsHuntableOffender'''() : Boolean
The scan contains a piloted ship with an offender legal status not too small to bother with (varies with government).

==== <code>conditionScannerContainsSeriousOffender</code> ====
function '''conditionScannerContainsSeriousOffender'''() : Boolean
The scan contains a piloted ship with an offender legal status at or above the system threshold for fines (varies with government).

==== <code>conditionScannerContainsHunters</code> ====
function '''conditionScannerContainsHunters'''() : Boolean
The scan contains a ship with role "hunter", or a police ship, or the main station.

==== <code>conditionScannerContainsLoneVictim</code> ====
function '''conditionScannerContainsLoneVictim'''() : Boolean
The scan contains a single pirate victim and no other unallied ships.

==== <code>conditionScannerContainsMiningOpportunity</code> ====
function '''conditionScannerContainsMiningOpportunity'''() : Boolean
The scan contains a boulder (preferentially) or an asteroid, and the ship has a mining laser, a fuel scoop, and a non-full hold.

==== <code>conditionScannerContainsNonThargoid</code> ====
function '''conditionScannerContainsNonThargoid'''() : Boolean
The scan contains a ship which is not a Thargoid ship. Rocks and cargo will only be returned if there is nothing more interesting about.

==== <code>conditionScannerContainsPirateLeader</code> ====
function '''conditionScannerContainsPirateLeader'''() : Boolean
The scan contains a pirate leader (usually a heavily-armed freighter)

==== <code>conditionScannerContainsPirateVictims</code> ====
function '''conditionScannerContainsPirateVictims'''() : Boolean
The scan contains a pirate victim (as defined by <code>[[role-categories.plist]]</code>) which is carrying at least some cargo and has not recently been robbed.

==== <code>conditionScannerContainsReadyThargoidMothership</code> ====
function '''conditionScannerContainsReadyThargoidMothership'''() : Boolean
The scan contains a thargoid mothership which has the capability to control at least one more thargon.

==== <code>conditionScannerContainsRocks</code> ====
function '''conditionScannerContainsRocks'''() : Boolean
The scan contains boulders (preferentially) or asteroids.

==== <code>conditionScannerContainsSalvage</code> ====
function '''conditionScannerContainsSalvage'''() : Boolean
The scan contains cargo which could in theory be scooped.

==== <code>conditionScannerContainsSalvageForGroup</code> ====
function '''conditionScannerContainsSalvageForGroup'''() : Boolean
The scan contains cargo which could in theory be scooped, and it is travelling slowly enough that at least one of the ships in the group with fuel scoops and cargo space can collect it..

==== <code>conditionScannerContainsSalvageForMe</code> ====
function '''conditionScannerContainsSalvageForMe'''() : Boolean
The scan contains cargo which can be scooped by this ship (travelling slowly enough, and this ship has scoops and space)

==== <code>conditionScannerContainsShipNeedingEscort</code> ====
function '''conditionScannerContainsShipNeedingEscort'''() : Boolean
The scan contains a ship which has fewer escorts than its maximum. If the ship is clean, this will only detect other clean ships. If the ship is not clean, this will only detect other non-clean ships.

==== <code>conditionScannerContainsSuspiciousShip</code> ====
function '''conditionScannerContainsSuspiciousShip'''() : Boolean
The scan contains a ship with a criminal reputation (whether or not it currently carries a bounty)

==== <code>conditionScannerContainsThargoidMothership</code> ====
function '''conditionScannerContainsThargoidMothership'''() : Boolean
The scan contains a thargoid mothership which has the capability to control thargons. The number of thargons currently being controlled is irrelevant to this scan.

==== <code>conditionScannerContainsUnspreadMissile</code> ====
function '''conditionScannerContainsUnspreadMissile'''() : Boolean
The scan contains a missile which has the same target and owner as this ship, but is closer to the target and within 500 metres of this ship. This is mainly used for "smart" missiles to ensure that impact times for a salvo are spread out.

=== State querying conditions ===

Conditions related to the state of the ship

==== <code>conditionAllEscortsInFlight</code> ====
function '''conditionAllEscortsInFlight'''() : Boolean
If the ship has living escorts, then this function returns <code>true</code> only if they are all in normal flight (and not docked, launching, or in a wormhole). If the ship has no escorts then this function also returns <code>true</code>.

==== <code>conditionCanScoopCargo</code> ====
function '''conditionCanScoopCargo'''() : Boolean
The ship has a working fuel scoop and at least 1 TC of free space in its hold.

==== <code>conditionCargoIsProfitableHere</code> ====
function '''conditionCargoIsProfitableHere'''() : Boolean
The current contents of the ship's hold can be sold at an above average price at the main station (this is currently determined very approximately - solely asking "is the current system on the right side of the Ind/Agri divide" - rather than checking station prices.

==== <code>conditionCoinFlip</code> ====
function '''conditionCoinFlip'''() : Boolean
Returns true half the time.

==== <code>conditionGroupLeaderIsStation</code> ====
function '''conditionGroupLeaderIsStation'''() : Boolean
The ship has a group leader and the group leader is a station.

==== <code>conditionHasInterceptCoordinates</code> ====
function '''conditionHasInterceptCoordinates'''() : Boolean
The ship has intercept coordinates set in the parameter "oolite_interceptCoordinates". These are used by missiles to home in on a last-known location if the target cloaks.

==== <code>conditionHasMothership</code> ====
function '''conditionHasMothership'''() : Boolean
The ship has a group leader which is not itself.

==== <code>conditionHasNonThargoidTarget</code> ====
function '''conditionHasNonThargoidTarget'''() : Boolean
The ship's target is not null, and is not a thargoid ship (by scan class).

==== <code>conditionHasReceivedDistressCall</code> ====
function '''conditionHasReceivedDistressCall'''() : Boolean
The ship has recently received a distress call. Distress calls expire after 30 seconds, or if the sender is no longer visible, or if the aggressor is dead.

==== <code>conditionHasRememberedTarget</code> ====
function '''conditionHasRememberedTarget'''() : Boolean
The ship has a remembered target. This is set by [[#behaviourFollowCurrentTarget|behaviourFollowCurrentTarget]] to allow persistent tracking of a ship.

==== <code>conditionHasTarget</code> ====
function '''conditionHasTarget'''() : Boolean
The ship's target is not null.

==== <code>conditionHasWaypoint</code> ====
function '''conditionHasWaypoint'''() : Boolean
The ship has a waypoint set by its [[#|waypoint generator]].

==== <code>conditionIsActiveThargon</code> ====
function '''conditionIsActiveThargon'''() : Boolean
The ship is a thargon ("EQ_THARGON") and is active.

==== <code>conditionIsEscorting</code> ====
function '''conditionIsEscorting'''() : Boolean
The ship is currently escorting another ship. Stricter than [[#conditionHasMothership|conditionHasMothership]]: this also requires this ship to be in the group leader's escort group.

==== <code>conditionIsGroupLeader</code> ====
function '''conditionIsGroupLeader'''() : Boolean
The ship is in a group and is the leader of the group

==== <code>conditionMissileNeedsLaunchEvasion</code> ====
function '''conditionMissileNeedsLaunchEvasion'''() : Boolean
This function checks if the <code>oolite_flag_launchAdjustMissile</code> parameter is set to a non-null value, and returns true if so.

Missile AI scripts may find the following code useful to set this flag to avoid collisions with the launching ship.

this.shipSpawned = function()
{
/* Launch correction when fired at target in aft arc */
var s = this.ship;
if(s.target && s.target.position.subtract(s.position).direction().dot(s.vectorForward) < -0.8)
{
this.oolite_priorityai.setParameter("oolite_flag_launchAdjustMissile",true);
}
}

See also [[#configurationMissileAdjustLaunch|configurationMissileAdjustLaunch]]

==== <code>conditionMissileOutOfFuel</code> ====
function '''conditionMissileOutOfFuel'''() : Boolean
The ship has travelled beyond the maximum missile range. The default is 30km, but this may be overridden by the <code>oolite_missile_range</code> parameter in the ship's script info.

==== <code>conditionPatrolIsOver</code> ====
function '''conditionPatrolIsOver'''() : Boolean
The ship's patrol is over (either due to distance travelled or a need to re-arm and repair). Note that the distance threshold is relatively low, so for ships on long patrol routes between system bodies this function should only be called when reaching appropriate waypoints.

==== <code>conditionWitchspaceEntryRequested</code> ====
function '''conditionWitchspaceEntryRequested'''() : Boolean
The ship has been requested to enter a wormhole set in the "oolite_witchspaceWormhole" parameter.

== Configuration functions ==

Configuration functions are usually used to set up parameters needed for a behaviour, though some may be used at the preconfiguration stage to set up parameters for a condition test. They take no arguments and do not return anything.

=== Destination configurations ===

These configurations set a destination, a desired range and a desired speed suitable for use with [[#behaviourApproachDestination|behaviourApproachDestination]]. Unless otherwise stated, [[#cruiseSpeed|cruiseSpeed]] will be used as the desired speed.

If they are unable to set a destination, they may set the destination to the ship's current position, or may do nothing. Generally a condition should be used to check that the configuration is sensible.

==== <code>configurationMissileAdjustLaunch</code> ====
function '''configurationMissileAdjustLaunch'''()
This function causes the missile to dive sharply. The intended use is in conjunction with [[#conditionMissileNeedsLaunchEvasion|conditionMissileNeedsLaunchEvasion]] to avoid collisions with the launching ship.

==== <code>configurationMissileAdjustSpread</code> ====
function '''configurationMissileAdjustSpread'''()
This function sets an intermediate destination for "smart" missiles which are adjusting their flight path to spread out a salvo's impacts on target.

==== <code>configurationSetDestinationToHomeStation</code> ====
function '''configurationSetDestinationToHomeStation'''()
Locates the home station, sets the destination to its position and the desired range to 15km.

==== <code>configurationSetDestinationToGroupLeader</code> ====
function '''configurationSetDestinationToGroupLeader'''()
Locates the group leader, sets the destination to its position and the desired range to 15km. Maximum flight speed is used.

==== <code>configurationSetDestinationToMainPlanet</code> ====
function '''configurationSetDestinationToMainPlanet'''()
Sets the destination to the main planet's position, and the desired range to 3 radii (i.e. 2 radii from the surface).

==== <code>configurationSetDestinationToMainStation</code> ====
function '''configurationSetDestinationToMainStation'''()
Sets the destination to the main station's position, and the desired range to 15km

==== <code>configurationSetDestinationToNearestHostileStation</code> ====
function '''configurationSetDestinationToNearestHostileStation'''()
Locates the nearest friendly station, sets the destination to its position and the desired range to 15km.

==== <code>configurationSetDestinationToNearestFriendlyStation</code> ====
function '''configurationSetDestinationToNearestFriendlyStation'''()
Locates the nearest friendly station, sets the destination to its position and the desired range to 15km.

==== <code>configurationSetDestinationToNearestStation</code> ====
function '''configurationSetDestinationToNearestStation'''()
Locates the nearest station, sets the destination to its position and the desired range to 15km.

==== <code>configurationSetDestinationToNearestWormhole</code> ====
function '''configurationSetDestinationToNearestWormhole'''()
Locates the nearest entry wormhole, sets the destination to its position and the desired range to zero.

==== <code>configurationSetDestinationToPirateLurk</code> ====
function '''configurationSetDestinationToPirateLurk'''()
If the parameter "oolite_pirateLurk" is set, then set the destination to that. If currently on a lane, set the destination to the current position. Otherwise, pick a random point on one of the lanes (strongly preferring witchpoint-planet). Once a destination is selected, store it to the parameter "oolite_pirateLurk".

The desired range is 1km.

==== <code>configurationSetDestinationToScannedTarget</code> ====
function '''configurationSetDestinationToScannedTarget'''()
Sets the destination to the position of the ship in the parameter "oolite_scanResultSpecific", and the desired range to 400m. This can be used to follow a ship without targeting it.

==== <code>configurationSetDestinationToSelectedPlanet</code> ====
function '''configurationSetDestinationToSelectedPlanet'''()
Sets the destination to the position of the planet in the parameter "oolite_selectedPlanet", and the desired range to 100m from the surface.

==== <code>configurationSetDestinationToSelectedStation</code> ====
function '''configurationSetDestinationToSelectedStation'''()
Sets the destination to the position of the station in the parameter "oolite_selectedStation", and the desired range to 15km.

==== <code>configurationSetDestinationToSunskimEnd</code> ====
function '''configurationSetDestinationToSunskimEnd'''()
Sets the destination to a course parallel to the sun's surface, at a range which should allow the fuel tanks to be completely refilled. The desired range is 0, and the desired speed is maximum speed.

Note: if this function is used above sunskimming height, it will still
move parallel to the sun's surface, but this will not be much use.

==== <code>configurationSetDestinationToSunskimStart</code> ====
function '''configurationSetDestinationToSunskimStart'''()
Sets the destination to the sun's position, and the desired range to sunskimming height.

==== <code>configurationSetDestinationToWaypoint</code> ====
function '''configurationSetDestinationToWaypoint'''()
If the parameters "oolite_waypoint" and "oolite_waypointRange" are set, use those as the destination and desired range.

==== <code>configurationSetDestinationToWitchpoint</code> ====
function '''configurationSetDestinationToWitchpoint'''()
Sets the destination to the witchpoint and the range to 10km

==== <code>configurationSetWaypoint</code> ====
function '''configurationSetWaypoint'''()
If a waypoint generator function has been registered, runs that function to set the "oolite_waypoint" and "oolite_waypointRange" parameters, then sets the destination from those parameters.

=== Docking configurations ===

Each of these configurations sets the "oolite_dockingStation" parameter used by [[#behaviourDockWithStation|behaviourDockWithStation]]

==== <code>configurationSetNearbyFriendlyStationForDocking</code> ====
function '''configurationSetNearbyFriendlyStationForDocking'''()
Sets the "oolite_dockingStation" parameter to a friendly station in scanner range, if possible.

==== <code>configurationSetHomeStationForDocking</code> ====
function '''configurationSetHomeStationForDocking'''()
Sets the "oolite_dockingStation" parameter to the ship's home station.

==== <code>configurationSetSelectedStationForDocking</code> ====
function '''configurationSetHomeStationForDocking'''()
Sets the "oolite_dockingStation" parameter to the station in the parameter "oolite_selectedStation".

=== Miscellaneous configurations ===

==== <code>configurationAppointGroupLeader</code> ====
function '''configurationAppointGroupLeader'''()
If the ship is in a group but the group has no leader, set one of the ships in the group to be the leader. Witchspace-capable ships will be preferred over those which are not.

If the parameter "oolite_leaderRole" is set, the primary role of the new leader will be changed to that role.

==== <code>configurationEscortGroupLeader</code> ====
function '''configurationEscortGroupLeader'''()
If the ship is in a group and the group has a leader which is not this ship and the ship is not already escorting the group leader, and the parameter "oolite_escortRole" is set, then attempt to escort the group leader. The ship's primary role will be set to "oolite_escortRole" if the escort attempt is successful, and this role must therefore be a valid escort role.

==== <code>configurationForgetCargoDemand</code> ====
function '''configurationForgetCargoDemand'''()
If the ship has a cargo demand active (the demand must be stored on this ship, not just on a group member), discard it, and reset the "oolite_cargoDropped" parameter of this ship and all group members to zero.

==== <code>configurationLeaveEscortGroup</code> ====
function '''configurationLeaveEscortGroup'''()
If the ship is currently escorting another ship, leave the escort group.

==== <code>configurationLightsOff</code> ====
function '''configurationLightsOff'''()
Set the ship's flashers to the 'off' state.

==== <code>configurationLightsOn</code> ====
function '''configurationLightsOn'''()
Set the ship's flashers to the 'on' state.

==== <code>configurationSetRemoteControl</code> ====
function '''configurationSetRemoteControl'''()
If the ship has a group leader, set its own accuracy to that ship's accuracy. This is used by thargons when the mothership controlling them is changed.

=== Navigation configurations ===

==== <code>configurationSelectPlanet</code> ====
function '''configurationSelectPlanet'''()
This function places a randomly selected planet or moon in the parameter "oolite_selectedPlanet"

==== <code>configurationSelectRandomTradeStation</code> ====
function '''configurationSelectRandomTradeStation'''()
This function places a suitable station in the parameter "oolite_selectedStation". If the ship is clean, then 90% of the time this will be the main station. If the ship is an offender, but has a bounty not greater than the fine threshold, then 50% of the time this will be the main station.

If the main station was not selected at the previous step, a random
friendly station will be selected (which may be the main station
anyway)

==== <code>configurationSelectShuttleDestination</code> ====
function '''configurationSelectShuttleDestination'''()
This function selects a random planet or station. The entity selected must be at least 10km from the ship. If any such entities are within 5 times the radius of the main planet from the ship, more distant entities will be ignored.

If the selected entity was a planet, it will be stored in "oolite_selectedPlanet". Otherwise, it will be stored in "oolite_selectedStation".

==== <code>configurationSelectWitchspaceDestination</code> ====
function '''configurationSelectWitchspaceDestination'''()
If the ship has no witchspace drive, unset the "oolite_witchspaceDestination" parameter. If that parameter is already set, and is not the current system, and the ship has enough fuel to reach that system, do nothing. Otherwise, select a random system in range and place its ID in the "oolite_witchspaceDestination" parameter.

==== <code>configurationSelectWitchspaceDestinationInbound</code> ====
function '''configurationSelectWitchspaceDestination'''()
If the ship has no witchspace drive, unset the "oolite_witchspaceDestination" parameter. If the ship's home system and destination system are unequal, select the next system on the route to the home system. Otherwise, select a random system in range and place its ID in the "oolite_witchspaceDestination" parameter.

==== <code>configurationSelectWitchspaceDestinationOutbound</code> ====
function '''configurationSelectWitchspaceDestination'''()
If the ship has no witchspace drive, unset the "oolite_witchspaceDestination" parameter. If the ship's home system and destination system are unequal, select the next system on the route to the destination system. Otherwise, select a random system in range and place its ID in the "oolite_witchspaceDestination" parameter.

=== Station configurations ===

==== <code>configurationStationReduceAlertLevel</code> ====
function '''configurationStationReduceAlertLevel'''()
Reduce the alert level of the station by one stage if it is not already Green.

==== <code>configurationStationValidateTarget</code> ====
function '''configurationStationValidateTarget'''()
Check that the station's current target is within scanner range, and discard it if not. This is necessary for stations as unlike ships their low-level behaviour does not generally do this automatically.

=== Target acquisition configurations ===

==== <code>configurationAcquireCombatTarget</code> ====
function '''configurationAcquireCombatTarget'''()
If the ship's target is valid, not cargo and not an ally, keep the current target. Otherwise, promote one defense target to a target. If the ship has no defense targets, check to see if any ships in the group or escort group have a combat target (but do not check their defense targets).

==== <code>configurationAcquireDefensiveEscortTarget</code> ====
function '''configurationAcquireDefensiveEscortTarget'''()
Search the current group leader's target and defense targets for a visible ship attacking the group leader, and target it if one is found. Otherwise, retain current target.

==== <code>configurationAcquireHostileCombatTarget</code> ====
function '''configurationAcquireHostileCombatTarget'''()
As [[#configurationAcquireCombatTarget|configurationAcquireCombatTarget]] but only targets which are hostile (i.e. would be valid for [[#behaviourRepelTarget|behaviourRepelTarget]]) will be selected.

==== <code>configurationAcquireOffensiveEscortTarget</code> ====
function '''configurationAcquireOffensiveEscortTarget'''()
If this ship's group leader is attacking a target, and this ship can see that target, acquire that target. Otherwise retain current target.

==== <code>configurationAcquirePlayerAsTarget</code> ====
function '''configurationAcquirePlayerAsTarget'''()
Set this ship's target to the player.

==== <code>configurationAcquireScannedTarget</code> ====
function '''configurationAcquireScannedTarget'''()
Set this ship's target to the entity in the parameter "oolite_scanResultSpecific". This parameter is set by the [[#checkScannerWithPredicate|checkScannerWithPredicate]] function, which is usually called from a <code>conditionScannerContains...</code> condition.

==== <code>configurationCheckScanner</code> ====
function '''configurationCheckScanner'''()
Scans the ship's scanner range, placing a list of detected targets into the "oolite_scanResults" parameter. This is generally called in a preconfiguration before the first use of a <code>conditionScannerContains...</code> condition in the priority list.

If the scanner is particularly full, the list will not contain all visible objects. The current scan limit is 16.

== Response definition functions and components ==

=== Response definition functions ===

Response definition functions are used to set up event handlers in the AI script. They take an object as an argument, and add event handlers to that object. They do not return anything as such, but modify their argument.

They are generally used in behaviour functions to set up common responses.
var handlers = {}; // new handler object
this.responsesAddStandard(handlers); // add standard response set
// add a handler for this behaviour
handlers.shipEnteredStationAegis = function(station)
{
this.ship.beaconCode = null; // stop transmitting
}
this.applyHandlers(handlers);

==== <code>responsesAddDocking</code> ====
function '''responsesAddDocking'''(handlers : Object)
Provides some additional event handlers for use when docking with a station.

==== <code>responsesAddEscort</code> ====
function '''responsesAddEscort'''(handlers : Object)
Provides some additional event handlers for use when escorting a ship, and changes the response to in-group help requests.

==== <code>responsesAddMissile</code> ====
function '''responsesAddMissile'''(handlers : Object)
A standard set of event handlers for missiles, which should be used instead of <code>responsesAddStandard</code>.

A number of script info keys are used to modify the responses.
* oolite_missile_blastPower, oolite_missile_blastRadius, oolite_missile_blastShaping: If oolite_missile_detonation is not set, the default detonation function calls this.ship.dealEnergyDamage with the defined power, radius, and shaping. If these parameters are not set the defaults are power 170, radius 32.5, and shaping 0.25.
* oolite_missile_detonation: names a function in the AI script. This function will be called when the missile reaches the desired range from its target or destination. If this function is not set, the oolite_missile_blast* keys are used to set up an explosion.
* oolite_missile_ecmResponse: names a function in the AI script. This function will be called if the missile detects an ECM pulse. If no function is set, the missile will self destruct.

==== <code>responsesAddScooping</code> ====
function '''responsesAddScooping'''(handlers : Object)
Provides some additional event handlers for use when scooping fuel.

==== <code>responsesAddStandard</code> ====
function '''responsesAddStandard'''(handlers : Object)
Sets up standard event handlers to detect and respond to attacks, and to manage other common events. Certain parameter flags are used:
* oolite_flag_allowPlanetaryLanding: if true, the ship will land on a planet if it receives the <code>approachingPlanetSurface</code> event. Otherwise, it will immediately reconsider its behaviour.
* oolite_flag_listenForDistressCall: if true, the ship will set the "oolite_distressAggressor", "oolite_distressSender" and "oolite_distressTimestamp" parameters if it receives a distress call.
* oolite_flag_markOffenders: if true, the ship will apply a small bounty increase to ships it sees committing crimes.
* oolite_flag_sendsDistressCalls: if true, the ship will send distress calls when attacked.
* oolite_flag_watchForCargo: if true, the ship will increment the "oolite_cargoDropped" parameter if cargo is dumped nearby.

If multiple standard responses are being applied, this one should be the first one applied.

==== <code>responsesAddStation</code> ====
function '''responsesAddStation'''(handlers : Object)
A standard set of event handlers for stations, which should be used instead of <code>responsesAddStandard</code>. The "oolite_flag_listenForDistressCall" and "oolite_flag_markOffenders" parameters have the same use as in <code>responsesAddStandard</code>.

=== Response definition components ===

The components are standard event handlers used by the standard response functions. The following response components are available. Each is named "<code>responseComponent_''responseGroup''_''handlerName''</code>". You can use them in your own handler definition functions for efficiency.
var handlers = {};
handlers.approachingPlanetSurface = this.responseComponent_standard_approachingPlanetSurface;
// .. etc ..
this.applyHandlers(handlers);

==== Standard components ====
Standard event handlers for normal ships.
responseComponent_standard_approachingPlanetSurface
responseComponent_standard_cargoDumpedNearby
responseComponent_standard_cascadeWeaponDetected
responseComponent_standard_commsMessageReceived
responseComponent_standard_distressMessageReceived
responseComponent_standard_escortAccepted
responseComponent_standard_helpRequestReceived
responseComponent_standard_offenceCommittedNearby
responseComponent_standard_playerWillEnterWitchspace
responseComponent_standard_shipAcceptedEscort
responseComponent_standard_shipAchievedDesiredRange
responseComponent_standard_shipAttackedOther
responseComponent_standard_shipAttackedWithMissile
responseComponent_standard_shipAttackerDistracted
responseComponent_standard_shipBeingAttacked
responseComponent_standard_shipBeingAttackedUnsuccessfully
responseComponent_standard_shipFiredMissile
responseComponent_standard_shipKilledOther
responseComponent_standard_shipLaunchedEscapePod
responseComponent_standard_shipLaunchedFromStation
responseComponent_standard_shipScoopedOther
responseComponent_standard_shipTargetLost
responseComponent_standard_shipWillEnterWormhole
responseComponent_standard_shipWitchspaceBlocked
responseComponent_standard_wormholeSuggested

==== Missile components ====
Standard event handlers for missiles.
responseComponent_missile_commsMessageReceived
responseComponent_missile_shipHitByECM
responseComponent_missile_shipTargetCloaked
responseComponent_missile_shipTargetLost
responseComponent_missile_shipAchievedDesiredRange

==== Station components ====
Standard event handlers for stations.
responseComponent_station_commsMessageReceived
responseComponent_station_cascadeWeaponDetected
responseComponent_station_shipAttackedWithMissile
responseComponent_station_shipBeingAttacked
responseComponent_station_shipAttackedOther
responseComponent_station_shipFiredMissile
responseComponent_station_shipKilledOther
responseComponent_station_shipTargetLost
responseComponent_station_helpRequestReceived
responseComponent_station_distressMessageReceived
responseComponent_station_offenceCommittedNearby

==== Docking components ====
Alternative event handlers for docking ships.
responseComponent_docking_shipAchievedDesiredRange
responseComponent_docking_stationWithdrewDockingClearance
responseComponent_docking_shipAIFrustrated

==== Escort components ====
Alternative event handlers for escorts.
responseComponent_escort_escortDock
responseComponent_escort_helpRequestReceived

==== Expect-witchspace components ====
Alternative event handlers for ships expecting that their target might enter witchspace to escape
responseComponent_expectWitchspace_shipTargetLost

==== Scooping components ====
Alternative event handlers for ships scooping fuel.
responseComponent_scooping_shipAchievedDesiredRange
responseComponent_scooping_shipScoopedFuel

==== Track-player components ====
Alternative event handlers for ships following the player.
responseComponent_trackPlayer_playerWillEnterWitchspace

== Template functions ==

These functions return standard blocks of priorities for insertion into a priority list. Each of them returns an array, so can be used as a branch in its own right, or concatenated on to an existing array. Remember that unlike a standard priority entry, you need the result of these functions, not a reference to the function.
{
condition: ai.conditionInCombat,
falsebranch: ai.templateReturnToBase()
}
or
priorities.concat(ai.templateReturnToBase());

==== templateLeadHuntingMission ====
function '''templateLeadHuntingMission'''() : Array
Return the priorities for leading a patrol between waypoints. Setting the waypoint generator and handling fighting and scanning along the course of the patrol should be handled by higher priorities.

==== templateLeadPirateMission ====
function '''templateLeadPirateMission'''() : Array
Return the priorities for selecting targets to rob if any are about, or moving to a suitable lurk position otherwise.

==== templateReturnToBase ====
function '''templateReturnToBase'''() : Array
Return the priorities for travelling to and docking with a suitable station.

==== templateReturnToBaseOrPlanet ====
function '''templateReturnToBaseOrPlanet'''() : Array
Return the priorities for travelling to and docking with a suitable station, or landing on a planet if no suitable stations are found.

==== templateWitchspaceJumpAnywhere ====
function '''templateWitchspaceJumpAnywhere'''() : Array
Returns priorities for getting the ship out of the current system somehow - either by jumping out, or by finding a wormhole to hitchhike.

==== templateWitchspaceJumpInbound ====
function '''templateWitchspaceJumpInbound'''() : Array
Returns priorities for jumping closer to the home system, sunskimming if fuel is short. You should previously have checked that the ship is not in the home system.

==== templateWitchspaceJumpOutbound ====
function '''templateWitchspaceJumpOutbound'''() : Array
Returns priorities for jumping closer to the destination system, sunskimming if fuel is short. You should previously have checked that the ship is not in the destination system.

== Utility functions ==

These functions are provided to make standardised checks easier to write and to wrap certain ship methods to make them easier to work with in the AI controller.

==== <code>allied</code> ====
function '''allied'''(ship1, ship2) : Boolean
Returns <code>true</code> if the two ships are considered allied, false otherwise. Ships are considered allied if they are in the same group, or if they are escorts of ships in the same group.

==== <code>broadcastDistressMessage</code> ====
function '''broadcastDistressMessage'''()
Broadcasts a distress message, but with a delay to ensure that [[Oolite_JavaScript_Reference:_Ship#broadcastDistressMessage|ship.broadcastDistressMessage()]] is not called too often.

==== <code>checkScannerWithPredicate</code> ====
function '''checkScannerWithPredicate'''(function) : Boolean
Called after configurationCheckScanner to locate a ship on the scanner matching a particular predicate. The predicate function must take a Ship, and return a Boolean.

If the predicate function matches a ship, the first such match will be stored in the parameter <code>"oolite_scanResultSpecific"</code>, and the method will return <code>true</code>. Otherwise the method returns <code>false</code>.

==== <code>cruiseSpeed</code> ====
function '''cruiseSpeed'''() : Number
Returns a suitable speed for the ship to travel at if it is interested in preserving group or escort coherence. Generally this will be 80% of its maximum speed, but it will be slower if other group members or escorts are slower.

==== <code>distance</code> ====
function '''distance'''(position : [[Oolite_JavaScript_Reference:_Vector3D#Vector_Expressions|vectorExpression]])
Returns the distance to the given coordinates. This is more efficient than calling <code>this.ship.position.distanceTo(position)</code>.

==== <code>entityCommsParams</code> ====
function '''entityCommsParams'''(entity : Entity) : Object
Returns an object of communications parameters relating to the given entity. Used internally by [[#communicate|communicate()]] but may be of use elsewhere.

==== <code>fineThreshold</code> ====
function '''fineThreshold'''() : Number
The maximum bounty at which an offender should be fined rather than attacked by police ships. (Ships caught redhanded may be attacked regardless of bounty) Varies from system to system.

==== <code>friendlyStation</code> ====
function '''friendlyStation'''(station) : Boolean
Returns <code>true</code> if the station is friendly to the current ship, false otherwise. The main station is unfriendly to Fugitive ships and Offenders above the current [[#fineThreshold|fineThreshold]]. Other stations are only considered unfriendly to their current combat target.

==== <code>homeStation</code> ====
function '''homeStation'''() : Boolean
Returns the home station of this ship. If the ship has an owner, and
the owner is a station, then that is the home station. Otherwise, the
first station in the ship's group is returned.

If no home station can be found, returns <code>null</code>.

==== <code>ignorePlayerFriendlyFire</code> ====
function '''ignorePlayerFriendlyFire'''() : Boolean
Returns <code>true</code> if this ship should ignore friendly fire from the player as they would for a known ally. Note that this function's results will change if called repeatedly, so you should only call it once per instance of friendly fire, and never call it speculatively.

==== <code>isAggressive</code> ====
function '''isAggressive'''() : Boolean
Returns <code>true</code> if the ship is an active danger to its current target (approximately: it is in a combat behaviour other than fleeing)

==== <code>isEscaping</code> ====
function '''isEscaping'''() : Boolean
Returns <code>true</code> if the ship is successfully running away from this ship (i.e. it is not attacking, it is travelling faster than this ship can, and it is already outside effective weapons range.

==== <code>isFighting</code> ====
function '''isAggressive'''() : Boolean
Returns <code>true</code> if the ship is in combat (including fleeing). Similar to <code>ship.hasHostileTarget</code> but works for stations as well.

==== <code>noteDistraction</code> ====
function '''noteDistraction'''(whom : Entity)
If this ship is switching combat targets because another ship distracted it, then call this function just before switching. <code>whom</code> is the entity that this ship will soon switch to attacking. This calls the <code>shipAttackerDistracted</code> event handler on the current target.

==== <code>oddsAssessment</code> ====
function '''oddsAssessment'''() : Number
Carry out an odds assessment of this ship's group versus the target ship's group. This will return a positive number of the ratio between the two values, with a number greater than 1 implying that this ship's group is stronger, and a number less than 1 implying the target's group is stronger. The odds assessment of the target group will omit certain information unless the target is currently in combat. Ships outside of scanner range, whether friendly or hostile, will also be ignored in the assessment.

==== <code>playerRoleAssessment</code> ====
function '''playerRoleAssessment'''() : String
Determines a single perceived role for the player based on [[Oolite_JavaScript_Reference:_Player#roleWeights|player.roleWeights]]. In general, the perception will be the same for all ships in a group. This can then be used with [[Oolite_JavaScript_Reference:_Ship#roleIsInCategory|Ship.roleIsInCategory]] to determine the appropriate response.

==== <code>respondToThargoids</code> ====
function '''respondToThargoids'''(whom : Ship, passon : Boolean) : Boolean
This function causes the ship (and if the <code>passon</code> parameter is set, its group members) to respond to the appearance of the Thargoid ship <code>whom</code>. It will return <code>true</code> if this ship responds, or <code>false</code> if not.

You must ensure that ships responding to a Thargoid as a result of a notification by a group member do not themselves set <code>passon</code> as this may cause an infinite loop.

==== <code>setWitchspaceRouteTo</code> ====
function '''setWitchspaceRouteTo'''(dest : Number)
This function sets the <code>oolite_witchspaceDestination</code> parameter according to the needs of reaching the system with the system ID equal to <code>dest</code>. As this function involves route planning, which is relatively slow, it should be called only rarely. This can then be used to determine whether to refuel or attempt to jump.

==== <code>shipHasRiskyContracts</code> ====
function '''shipHasRiskyContracts'''(ship : Ship) : Boolean
Sometimes returns <code>true</code> (non-deterministically) if the target ship is carrying contracts that someone might want assassinated or destroyed. The chance of returning <code>true</code> increases with the number of risky contracts carried. Currently this will always return <code>false</code> for a non-player ship: you can check these with the <code>oolite-courier</code> role category instead.

==== <code>shipInRoleCategory</code> ====
function '''shipInRoleCategory'''(ship : Ship, category : String) : Boolean
This is a wrapper around <code>Ship.roleIsInCategory</code> which accounts for the player's effective role not being the same as <code>player.ship.primaryRole</code>. You should generally call this instead of calling <code>Ship.roleIsInCategory</code> directly.

==== <code>stationAllegiance</code> ====
function '''stationAllegiance'''(station : Station) : String
Returns <code>station.allegiance</code> for the given station, but if this is null (as it will be for pre-1.79 stations), first sets it using a heuristic calculation.

==== <code>threatAssessment</code> ====
function '''threatAssessment'''(ship : Ship, full : Boolean) : Number
This is a wrapper around <code>[[#_threatAssessment|_threatAssessment]]</code> which is itself a wrapper around <code>[[Oolite_JavaScript_Reference:_Ship#threatAssessment|ship.threatAssessment()]]</code>. The combination of the two ensures that the assessment is correct for the relative combat states of this ship and the ship being assessed, as well as including effects of the player's reputation.

== Waypoint Generators ==

Waypoint generators are used to set patrol or other multipoint routes. When called, they should consider the ship's current position (and possibly other things), and then set the parameters "oolite_waypoint" and "oolite_waypointRange". These functions have no arguments and no return value.

In general, you should only call a waypoint generator if a waypoint is not already set.

==== <code>waypointsSpacelanePatrol</code> ====
function '''waypointsSpacelanePatrol'''()
If the ship is near the main planet, sun, or witchpoint, pick one of the other two points (biased towards the witchpoint-planet route) and set that as the waypoint. Otherwise, if the ship is on a lane already, pick one end of the lane at random. Otherwise, pick the planet.

Set a waypoint within 7500m of the witchpoint, 2 radii of the centre of the planet, or 2.5 radii of the centre of the sun.

==== <code>waypointsStationPatrol</code> ====
function '''waypointsStationPatrol'''()
If the ship has a station as its group leader, define waypoints from that station. Otherwise define them from the main station. If there is no main station either, set the witchpoint as the waypoint.

If there is a station, pick four points describing a square of diagonal length 50km centred on the station and lying in the station's xy plane. If the ship is not within 500 metres of any of these points, select one of the points as the waypoint. Otherwise, select the next point around the list as the waypoint.

==== <code>waypointsWitchpointPatrol</code> ====
function '''waypointsWitchpointPatrol'''()

Pick four points describing a square of diagonal length 30km centred on the witchpoint and lying approximately in the system's xy plane. If the ship is not within 500 metres of any of these points, select one of the points as the waypoint. Otherwise, select the next point around the list as the waypoint.

== Global Configuration ==
All PriorityAIControllers share a single communications message library. This library may be edited using functions in the priority AI worldscript

=== Usage ===

When a key is asked for, the communications library will be checked in the following order:
# for a key with the specified role and personality
# if the role does not start with "_", a key with the specified personality and the role "generic"
# if the personality does not start with "_", a key with the specified role and the personality "generic"
# if neither role nor personality start with "_", a key with "generic" role and personality.
In general, setting keys for the generic role (and especially with a generic personality as well) should be used with caution.

The key's value is then expanded using expandDescription (possibly with added parameters), so entries in [[descriptions.plist]] may be used to add variety to the communications. Alternatively, a static text string also works as the value.

==== Standard Communications Keys ====

The following communications keys are currently defined in standard Oolite, but you can define more. Those with a parameter of Ship can have a Ship object passed to them, which will be replaced with definitions for the parameters "oolite_entityClass", "oolite_entityCrew" and "oolite_entityName".

===== oolite_agreeingToDumpCargo =====
Parameter: "oolite_demandSize" (size of demand in TC)
Priority: 1
Used when a ship dumps cargo to satisfy a pirate demand

===== oolite_attackLowEnergy =====
Parameter: Ship,
Priority: 2
Used when requesting help as under attack and close to death

===== oolite_beginningAssassination =====
Parameter: Ship, plus "oolite_entityContracts" parameter
Priority: 3
Used when commencing a fight with the Ship defined in the parameter, like [[#oolite_beginningFight|oolite_beginningFight]], but specifically for an assassination target. The extra communications parameter contains the name of a passenger (or parcel owner) relevant to this ship (for the player, this may intentionally be someone for whom delivery has been completed - either it's a revenge hit, or they're just working from outdated intelligence)

===== oolite_beginningAttack =====
Parameter: Ship
Priority: 3
Used when commencing an attack on the Ship defined in the parameter.

===== oolite_beginningAttackInanimate =====
Parameter: Ship
Priority: 3
Used when commencing an attack on the Ship (expected to be an uncrewed object like an asteroid, cargo pod, etc.) defined in the parameter.

===== oolite_beginningAttackThargoid =====
Parameter: Ship
Priority: 3
Used when commencing an attack on the Ship (expected to be a Thargoid ship) defined in the parameter.

===== oolite_beginningFight =====
Parameter: Ship
Priority: 3
Used when commencing a fight with the Ship defined in the parameter. (Beginning Attack means attacking a target previously not under attack but which there may have been a reason to fight from previous combats; Beginning Fight is stronger - this ship is initiating hostilities)

===== oolite_continueFleeing =====
Parameter: Ship
Priority: 4
Used when the ship has been unable to reach safety from its attacker.

===== oolite_continuingAttack =====
Parameter: Ship
Priority: 4
Used when continuing an attack on the Ship defined in the parameter (the low priority means this is relatively rarely used, of course)

===== oolite_continuingAttackInanimate =====
Parameter: Ship
Priority: 4
Used when continuing an attack on the Ship (if likely to be uncrewed) defined in the parameter (the low priority means this is relatively rarely used, of course)

===== oolite_continuingAttackThargoid =====
Parameter: Ship
Priority: 4
Used when continuing an attack on the Ship (if Thargoid) defined in the parameter (the low priority means this is relatively rarely used, of course)

===== oolite_distressResponseAggressor =====
Parameter: Ship
Priority: 2
Used to threaten the ship a distress call has been sent about.

===== oolite_distressResponseSender =====
Parameter: Ship
Priority: 2 or 3
Used to reassure a ship sending a distress call that help is on the way. [[#oolite_distressResponseAggressor|oolite_distressResponseAggressor]] is preferred - this will only be used if the ship sending the message is near the sender but not the aggressor.

===== oolite_dockingWait =====
Parameter: none
Priority: 4
Used when a ship is waiting in a docking queue.

===== oolite_eject =====
Parameter: none
Priority: 1
Used when a ship launches an escape pod (the communication comes from the ship, not the pod, as the pod is being launched)

===== oolite_engageWitchspaceDrive =====
Parameter: none
Priority: 4
Used when a lone ship is beginning its witchspace entry sequence, and is expected to enter witchspace in around 15 seconds.

===== oolite_engageWitchspaceDriveFlee =====
Parameter: none
Priority: 2
Used when a ship is preparing to escape from a fight by making a witchspace jump

===== oolite_engageWitchspaceDriveGroup =====
Parameter: none
Priority: 4
Used when a grouped ship is beginning its witchspace entry sequence, and is expected to enter witchspace in around 15 seconds.

===== oolite_escortAccepted =====
Parameter: Ship
Priority: 2
Used when a ship accepts a new escort. The new escort will be passed as the parameter.

===== oolite_escortFormation =====
Parameter: Ship
Priority: 4
Used when a ship is entering or maintaining escort formation. The mothership will be passed as the parameter.

===== oolite_escortMotherAccepted =====
Parameter: Ship
Priority: 2
Used when a ship is accepted as a new escort. The ship being escorted will be passed as the parameter.

===== oolite_firedMissile =====
Parameter: Ship
Priority: 4
Used when firing a missile. The target of the missile will be passed as the parameter.

===== oolite_friendlyFire =====
Parameter: Ship
Priority: 2, 3 or 4 depending on circumstances
Used when a ship is hit by weapons fire from another ship it considers "on its side" either because of common group or because of similar roles.

===== oolite_groupIsOutnumbered =====
Parameter: none
Priority: 2 if group leader, 4 otherwise
Used when a ship realises it is in a fight with a group which seriously outclasses it, and therefore should flee.

===== oolite_hitTarget =====
Parameter: Ship
Priority: 4
Used when the ship hits its target. The target is passed as the parameter.

===== oolite_incomingMissile =====
Parameter: Ship
Priority: 3
Used when the ship has had a missile launched at it and is unable to use ECM. The missile is passed as the parameter.

===== oolite_killedAlly =====
Parameter: Ship
Priority: 3
Used when the ship destroys an allied ship. The target is passed as the parameter.

===== oolite_killedTarget =====
Parameter: Ship
Priority: 2 (3 for stations)
Used when the ship destroys its current target. The target is passed as the parameter.

===== oolite_killedNonTarget =====
Parameter: Ship
Priority: 3
Used when the ship destroys something other than its current target. The target is passed as the parameter.

===== oolite_killedUncrewedTarget =====
Parameter: Ship
Priority: 3 (4 for stations)
Used when the ship destroys an uncrewed object which is its current target. The target is passed as the parameter.

===== oolite_killedUncrewedNonTarget =====
Parameter: Ship
Priority: 3 (4 for stations)
Used when the ship destroys an uncrewed object other than its current target. The target is passed as the parameter.

===== oolite_landingOnPlanet =====
Parameter: none
Priority: 4
Used when beginning final landing approach to a planet.

===== oolite_launchDefenseShips, oolite_launchMiner, oolite_launchPatrol, oolite_launchSalvager =====
Parameter: Ship
Priority: 3
Used when a station launches a ship of a particular type. The parameter is the station's current target.

===== oolite_leaveVicinity =====
Parameter: Ship
Priority: 3
Used when a ship is executing [[#behaviourLeaveVicinityOfDestination|behaviourLeaveVicinityOfDestination]]. The parameter is the current target.

===== oolite_makeDistressCall =====
Parameter: Ship
Priority: 2
Used as the message when a distress call is sent. The parameter is the ship's primary aggressor.

===== oolite_makePirateDemand =====
Parameter: Ship and "oolite_demandSize"
Priority: 1
Used when making a piracy demand on a ship. The Ship parameters are from the ship being robbed.

===== oolite_markForFines =====
Parameter: Ship
Priority: 1
Used when a police ship is marking another ship for fines on docking. The parameter is the ship being marked.

===== oolite_mining =====
Parameter: none
Priority: 4
Used when carrying out mining activity

===== oolite_newAssailiant =====
Parameter: Ship
Priority: 3
Used when the ship is attacked by someone not previously considered hostile. The attacker is the parameter.

===== oolite_offenceDetected =====
Parameter: Ship
Priority: 3 if this increases the aggressor's bounty, 4 otherwise
Used when a police ship detects illegal hostilities. The parameter is the aggressor.

===== oolite_patrolReportIn =====
Parameter: Ship
Priority: 4
Used when a station patrol ship reaches a waypoint. The parameter is its parent station.

===== oolite_quiriumCascade =====
Parameter: none
Priority: 3
Used when a quirium cascade or an imminent cascade is detected.

===== oolite_scoopedCargo =====
Parameter: "oolite_goodsDescription" is a description of the cargo commodity
Priority: 4
Used when this ship scoops cargo.

===== oolite_selectedStation =====
Parameter: Ship
Priority: 4
Used when a ship selects a station to navigate to (e.g. traders, shuttles). The parameter is the selected station.

===== oolite_selectedWitchspaceDestination =====
Parameter: "oolite_witchspaceDestination" is the name of the destination system
Priority: 4
Used when a ship selects its witchspace destination.

===== oolite_startFleeing =====
Parameter: Ship
Priority: 3
Used when a ship begins fleeing combat, with the parameter being the ship's current target.

===== oolite_startHelping =====
Parameter: Ship
Priority: 4
Used when a ship responds to a request for help from another grouped ship by changing its target. The parameter is the new target.

===== oolite_surrender =====
Parameter: none
Priority: 3
Messages sent by fleeing ships still being fired upon, in attempt to beg for mercy. [[#oolite_agreeingToDumpCargo|oolite_agreeingToDumpCargo]] is used instead in the one case in the core game where an attacker might accept a surrender (as opposed to breaking off an attack on a fleeing ship to attack a non-fleeing one)

===== oolite_thanksForHelp =====
Parameter: Ship
Priority: 1 if thanking the player, 3 otherwise
This message is sent if an attack on this ship's aggressor causes it to break off its own attack. The parameter is the ship helping out.

===== oolite_thargoidAttack =====
Parameter: Ship
Priority: 2
This message is sent if the ship is attacked by a Thargoid ship while not previously fighting Thargoids. The parameter is the Thargoid ship. This is generally accompanied by a quick cessation of hostilities between Cooperative vessels for a short-term truce against the invaders.

===== oolite_waypointReached =====
Parameter: none
Priority: 3
This message is sent when a ship reaches a waypoint set with the waypoint generator function.

===== oolite_witchspaceBlocked =====
Parameter: Ship
Priority: 3
This message is sent when a large nearby mass (usually a station or asteroid) prevents witchspace entry. The parameter is the blocking mass.

==== Standard Communications Roles ====

The following communications roles are used by the standard Oolite AIs. Some of the roles have fallback roles used by the standard AIs, noted below. If the fallback role does not exist, or is not specified, it will fall back to using "generic" as usual.

Note that OXP AIs might not specify the same fallback roles. OXP AIs wishing to can use code like

if (worldScripts["oolite-libPriorityAI"]._getCommunicationPersonalities("hermit").length > 0)
{
ai.setCommunicationsRole("hermit");
}
else
{
ai.setCommunicationsRole("station");
}

* '''assassin''' - assassins
* '''defenseShip''' - defense ships
* '''escapepod''' - escape pods
* '''escort''' - escorts
* '''hermit''' - rock hermits. If no personalities are defined for this role, "station" will be used instead.
* '''hunter''' - bounty hunters
* '''pirate''' - pirates
* '''pirate-aegis-raider''' - pirates showing off by attacking the main station. If no personalities are defined for this role, "pirate" will be used instead.
* '''pirate-freighter''' - pirate freighters leading a pack. If no personalities are defined for this role, "pirate" will be used instead.
* '''pirate-interceptor''' - pirates assigned to distract police and hunters. If no personalities are defined for this role, "pirate" will be used instead.
* '''police''' - police ships
* '''scavenger''' - scavengers and miners.
* '''shuttle''' - orbital shuttles (usually unarmed)
* '''station''' - stations.
* '''trader''' - traders
* '''trader-courier''' - couriers. If no personalities are defined for this role, "trader" will be used instead.
* '''trader-opportunist''' - opportunistic traders. If no personalities are defined for this role, "trader" will be used instead.
* '''trader-smuggler''' - smugglers. If no personalities are defined for this role, "trader" will be used instead.

Thargoids are set slightly differently: all the core game ones get the "_thargoid" role, with the warships getting the "thargoid" personality, and the drones getting the "tharglet" personality, even if those personalities are not otherwise defined. Note that the underscore in the role prevents fallback to "generic" messages here.

=== Methods ===

==== _getCommunication ====
function '''_getCommunication'''(role : String, personality : String, key : String) : StringOrFunction
This function returns either a string suitable for passing to <code>expandDescription</code> containing the communications for the specified key, or a function called with key and parameters returning a communications string, if a ship of the specified role and personality is speaking.

==== _getCommunicationPersonalities ====
function '''_getCommunicationPersonalities'''(role : String) : Array
Returns the personalities which have at least one communication key defined for the given role.

==== _setCommunication ====
function '''_setCommunication'''(role : String, personality : String, key : String, value : StringOrFunction)
This function sets the communications values returned by [[#_getCommunication|getCommunication]]. The value may either be:
* a String, which will be passed to expandDescription
* a Function, which will be called with two parameters: the key, and the parameters object.

For example
worldScripts["oolite-libPriorityAI"]._setCommunication("myoxp_role","generic",
"oolite_continuingAttack","[myoxp_role_continuesAttack]");
worldScripts["oolite-libPriorityAI"]._setCommunication("myoxp_role","generic",
"oolite_continuingAttack",function(k,p) { return "Targeting the "+p.oolite_entityName+". Cover me."; });

==== _setCommunications ====
function '''_setCommunications'''(comms : Object)
This function can be used to set multiple communications keys at once. The format of the object is
comms[role][personality][key] = value;

[[Category:Oolite JavaScript Reference]]

Oolite Javascript Reference: PriorityAI Documentation

2014-08-01T02:53:03Z

Phasted: /* Basic structure */

This page describes the priority-based Javascript AI system, which allows more flexible behaviour than the old plist-based AIs to be written in fewer lines of code. New programmers may find [[Oolite_PriorityAI_Tutorial|the priority AI tutorial]] to be more useful as an introduction.

Priority-based Javascript AI is available from Oolite 1.79 onwards.

== Constructor and general functions ==

==== Constructor ====
'''new PriorityAIController'''(ship : Ship) : PriorityAIController
Creates a priority AI and attaches it to the specified ship. Using this from anywhere other than that ship's AI script is not recommended.

var ai = new worldScripts["oolite-libPriorityAI"].PriorityAIController(this.ship);

=== Properties ===

==== <code>ship</code> ====
'''ship''' : Ship (read-only)
The ship to which the priority AI is attached.

=== General Methods ===

Additional methods are described in later sections, sorted by purpose.

==== <code>applyHandlers</code> ====
function '''applyHandlers'''(handlers : Object)
Deletes any existing event handlers applied to the ship's AI Script by a previous invocation of <code>applyHandlers</code>, and copies the handlers in the argument object to the AI Script. All handlers applied this way run with '<code>this</code>' equal to the PriorityAIController, not to the AI Script.

==== <code>clearHandlers</code> ====
function '''clearHandlers'''(handlers : Object)
Deletes any existing event handlers applied to the ship's AI Script by a previous invocation of <code>applyHandlers</code>.

==== <code>communicate</code> ====
function '''communicate'''(key : String, params : Object, priority : Number)
If the communication "key" has previously been [[#_setCommunication|defined]] for this ship's [[#setCommunicationsRole|communications role]] and [[#setCommunicationsPersonality|personality]], retrieves it, calls <code>expandDescription</code> on it, using the parameters in the object (which can either be a dictionary, or a Ship). This message may then broadcast on the public channel, depending on the priority. If the object is a Ship, it will be converted to a dictionary for expandDescription with the following parameters:
* <code>oolite_entityClass</code> = <code>ship.shipClassName</code>
* <code>oolite_entityName</code> = <code>ship.shipUniqueName</code>
Other parameters may be added later to this expansion.

The priority can be a number from 1 to 4
# Always send this message
# Send this message if no messages sent in the last 10 seconds
# Send this message if no messages sent or received in the last 10 seconds
# Send this message if no messages sent or received in the last 60 seconds
This is used to prevent an overwhelming number of comms messages being sent. While priority 1 is necessary for messages which must be heard by the player, care must be taken to ensure by other means that they cannot be sent repeatedly.

==== <code>communicationsPersonality</code> ====
function '''communicationsPersonality'''() : String
The current communications personality

==== <code>communicationsRole</code> ====
function '''communicationsRole'''() : String
The current communications role

==== <code>getParameter</code> ====
function '''getParameter'''(key : String) : Value
If a parameter with that key has previously been set, return its value. Otherwise return null. Note that the return value can be of any type, so you must be careful when setting and retrieving parameters to avoid type errors.

==== <code>getWaypointGenerator</code> ====
function '''getWaypointGenerator'''() : Function
If a waypoint generation function has previously been set, return it.

==== <code>noteCommsHeard</code> ====
function '''noteCommsHeard'''()
This function is used to reset the timers for [[#communicate|priority 3 and 4 communications]]. The standard event handlers will call this for you, but you may need to call it manually otherwise.

==== <code>reconsiderIn</code> ====
function '''reconsiderIn'''(delay : Number)
Force a reconsideration of the AI's priority list ahead of schedule, if no request for sooner reconsideration has already been received. <code>delay</code> must be at least 0.1 seconds.

==== <code>reconsiderNow</code> ====
function '''reconsiderNow'''()
Force a reconsideration of the AI's priority list ahead of schedule.

==== <code>setCommunicationsRole</code> ====
function '''setCommunicationsRole'''(role : String)
Sets the ship's communications role to the given value. This is then used to vary the communications messages as defined by [[#_setCommunication|_setCommunication]].

If personalities have previously been defined for this role, and the ship's current personality is either "generic" or not one defined for this role, then it will also select a new communications personality at this point, based on [[Oolite_JavaScript_Reference:_Ship#entityPersonality|ship.entityPersonality]]. If the "oolite_personalityMatchesLeader" parameter has been set, then this is a 0..1 chance that the ship will instead take the personality of its group leader (if this ship is the group leader, this instead is the chance it will copy its personality to group members)

==== <code>setCommunicationsPersonality</code> ====
function '''setCommunicationsPersonality'''(role : String)
Sets the ship's communications personality to the given value. This is then used to vary the communications messages as defined by [[#_setCommunication|_setCommunication]].

==== <code>setParameter</code> ====
function '''setParameter'''(key : String, value : Value)
Set the named parameter to the given value. Values may be of any type. To remove a parameter, use a value of null. See the [[#Parameters|Parameters]] section below for parameter keys used by the core AIs and the standard priority AI library.

==== <code>setPriorities</code> ====
function '''setPriorities'''(priorities : Array [, delay: Number])
Set the priority list for the AI, and evaluate it. The format of the priority list is described in the next section.

An optional delay parameter can be set, which will cause evaluation to start only after this many seconds. If it is unset, the AI will start after a random period between 0 and 1 seconds.

==== <code>setWaypointGenerator</code> ====
function '''setWaypointGenerator'''(generator : Function)
Sets the AI's [[#Waypoint_Generators|Waypoint Generators]] waypoint generator function.

=== Parameters ===
The following parameters are used by the standard library and accessed using [[#getParameter|getParameter]] and [[#setParameter|setParameter]], but you can also define your own for custom AIs. More detailed documentation will be provided soon.

As with all custom items, prefixing new parameter names with a key unique to your OXP is strongly advised.

==== Flag Parameters ====
Flag parameters are intended to be set in the AI initialisation routine to vary the behaviour of the AI.

oolite_flag_allowPlanetaryLanding
oolite_flag_autoSpreadMissiles
oolite_flag_behaviourLogging
oolite_flag_continueUnlikelyPursuits
oolite_flag_escortsCoverRetreat
oolite_flag_fightsNearHostileStations
oolite_flag_fleesPreemptively
oolite_flag_likesInterstellarSpace
oolite_flag_listenForDistressCall
oolite_flag_markOffenders
oolite_flag_neverFleeToWitchspace
oolite_flag_noDockingUntilDestination
oolite_flag_noSpecialThargoidReaction
oolite_flag_patrolStation
oolite_flag_scanIgnoresUnpowered
oolite_flag_selfDestructAbandonedShip
oolite_flag_sendsDistressCalls
oolite_flag_surrendersEarly
oolite_flag_surrendersLate
oolite_flag_watchForCargo
oolite_flag_witchspacePursuit

==== Other parameters ====
These parameters are used for storage of long-term state that may need to be kept between runs of the priority tree. In general, Configuration and Response functions set them, and Condition, Behaviour and Response functions read them, but this is only a guideline. Implementors of custom functions may need to get or set these parameters for proper interaction with built-in functions used by the same AI.

oolite_cargoDropped
oolite_cascadeDetected
oolite_distressAggressor
oolite_distressSender
oolite_distressTimestamp
oolite_dockingStation
oolite_escortRole
oolite_friendlyRoles
oolite_groupPower
oolite_interceptCoordinates
oolite_interceptTarget
oolite_lastAssist
oolite_lastFleeing
oolite_lastPirateVictim
oolite_leaderRole
oolite_personalityMatchesLeader
oolite_pirateLurk
oolite_playerFriendlyFireAlready
oolite_rememberedTarget
oolite_scanResults
oolite_scanResultSpecific
oolite_selectedPlanet
oolite_selectedStation
oolite_stationPatrolRole
oolite_waypoint
oolite_waypointRange
oolite_waypoints
oolite_witchspaceDestination
oolite_witchspaceEntry
oolite_witchspaceWormhole

== Writing a priority list ==

The priority list is the core of the priority AI. The list will be reevaluated periodically - either timed, or when events occur - and on each reevaluation it will be searched from top to bottom. When a valid priority is found, searching will stop, and that priority will be executed.

If the parameter "oolite_flag_behaviourLogging" is set with [[#setParameter|setParameter]] then verbose information will be written to the log file regarding the processing of the priority list. It is generally advisable to use the debug console to do this for one ship at a time, rather than setting it generally!

=== Basic structure ===

The priority list is an array of objects. Each object contains a set
of keys and values. The keys are considered in the
following order and are all optional.
* '''preconfiguration''': function run unconditionally if this element of the list is reached.
* '''condition''': function run unconditionally if this element of the list is reached. If it returns false, the remainder of the object is ignored, and consideration moves to the next list element.
* '''notcondition''': function run unconditionally if this element of the list is reached. If it returns true, the remainder of the object is ignored, and consideration moves to the next list element.
If neither '''condition''' nor '''notcondition''' are set, this is treated as if a condition was set and was true.
* '''configuration''': function run if conditions allow
* '''behaviour''': function run if conditions allow. If this exists, no further elements of the priority list will be considered.
* '''reconsider''': A number. If a behaviour is executed, the priority list will next be reconsidered in this many seconds. If this value is absent the priority list will only be considered if an event causes it.
* '''truebranch''': a priority list array. If there was no behaviour, but the conditions allow one to be run, the truebranch will be evaluated as a priority list. If the truebranch causes a behaviour to be executed, consideration will end here. If the truebranch reaches its end without executing a behaviour, consideration will continue with the next element of the main priority list.
* '''falsebranch''': a priority list array. This will be executed if the the conditions caused the previous four elements to be skipped.

If evaluation reaches the end of the main priority list without finding a behaviour to execute, an error will be noted in the log. In general the last element of the main priority list should always be unconditional (or have a truebranch and a falsebranch, both of which have an unconditional last element).

Example of simple behaviour: (from thargoid AI)
{
preconfiguration: ai.configurationCheckScanner,
condition: ai.conditionScannerContainsNonThargoid,
configuration: ai.configurationAcquireScannedTarget,
behaviour: ai.behaviourDestroyCurrentTarget,
reconsider: 1
},

Example of branch usage: (from police AI)
{
/* The group leader leads the patrol */
condition: ai.conditionIsGroupLeader,
truebranch: [
/* Nothing interesting here. Patrol for a bit */
{
condition: ai.conditionHasWaypoint,
configuration: ai.configurationSetDestinationToWaypoint,
behaviour: ai.behaviourApproachDestination,
reconsider: 30
},
/* No patrol route set up. Make one */
{
configuration: ai.configurationSetWaypoint,
behaviour: ai.behaviourApproachDestination,
reconsider: 30
}
],
/* Other ships in the group will set themselves up
* as escorts if possible, or looser followers if
* not */
falsebranch: [
{
preconfiguration: ai.configurationEscortGroupLeader,
condition: ai.conditionIsEscorting,
behaviour: ai.behaviourEscortMothership,
reconsider: 30
},
/* if we can't set up as an escort */
{
behaviour: ai.behaviourFollowGroupLeader,
reconsider: 15
}
]
}

The AI Library provides a selection of standard condition,
configuration and behaviour functions for us in AIs, but you can also
write your own.
/* Ship is unstable and may explode under stress */
{
condition: function()
{
return Math.random() < 0.01; // 1% chance per evaluation
}
behaviour: function()
{
this.ship.explode();
}
}

=== Evaluation context ===

All condition, configuration and behaviour functions are evaluated in the context of the AI object. The '<code>this</code>' variable when one of these functions is run therefore points to the priority AI, '''not''' to the AI Script.

Note that <code>this.ship</code> is defined and will be equivalent to the this.ship seen by the AI Script. However, if you wish to access properties of the AI Script you must use <code>this.ship.AIScript.''property''</code>. Properties and methods of the priority AI may be accessed directly, e.g. <code>[[#allied|this.allied]](this.ship,this.ship.target)</code>.

== Behaviour functions ==

Behaviour functions determine what the ship will do next. They
generally begin a particular behaviour, and set up event handlers
(generally aided by the response templates) to allow interruption or
modification of that behaviour should anything interesting happen.

Behaviour functions take no arguments and return nothing.

=== General behaviours ===

Behaviours intended for ships in general. These mostly use <code>responsesAddStandard</code>, and occasionally add others.

==== <code>behaviourApproachDestination</code> ====
function '''behaviourApproachDestination'''()
Travels from the current position to within <code>desiredRange</code> of <code>destination</code>, avoiding obstacles on the way.

If a waypoint is set in the parameters "oolite_waypoint" and "oolite_waypointRange", it will clear these parameters if when it reaches its destination it is sufficiently close to the waypoint. If the parameter "oolite_flag_patrolStation" is set, and its group leader is a station, it will report in to the station upon reaching the waypoint.

Temporary waypoints needed to avoid obstacles will be stored in the
"oolite_waypoints" parameter.

==== <code>behaviourAssassinateCurrentTarget</code> ====
function '''behaviourAssassinateCurrentTarget'''()
This behaviour attacks the current target, only stopping when interrupted or when the target is destroyed. It will potentially send both "oolite_beginningAssassination" and "oolite_beginningFight" communications messages (though if the former is defined, the latter will not be sent due to the communications priority system). This is otherwise identical in behaviour to [[#behaviourCommenceAttackOnCurrentTarget|behaviourCommenceAttackOnCurrentTarget]]

==== <code>behaviourAvoidCascadeExplosion</code> ====
function '''behaviourAvoidCascadeExplosion'''()
Fly, using injectors if available, to a safe distance from any nearby quirium cascades (or active mines)

==== <code>behaviourBecomeInactiveThargon</code> ====
function '''behaviourBecomeInactiveThargon'''()
This behaviour is intended to deactivate thargons and should generally only be used for that purpose. It changes the scan class to CLASS_CARGO, clears the ship's targeting information, brings it to a stop, removes it from its ship groups, and removes it from nearby NPCs targeting systems (it can be retargeted). Unlike the equivalent plist AI command, it does not remove it as a player target.

==== <code>behaviourCollectSalvage</code> ====
function '''behaviourCollectSalvage'''()
This behaviour attempts to scoop the current target. If it is successful, the "oolite_cargoDropped" parameter recording the number of seen cargo pods will be cleared.

==== <code>behaviourCommenceAttackOnCurrentTarget</code> ====
function '''behaviourCommenceAttackOnCurrentTarget'''()
This behaviour attacks the current target, only stopping when interrupted or when the target is destroyed. Unlike the <code>behaviourDestroyCurrentTarget</code> behaviour, it may first send the "[[#oolite_beginningFight|oolite_beginningFight]]" communications message, so should only be used when starting a fight with a new target/group - not when in the middle of a fight.

==== <code>behaviourDestroyCurrentTarget</code> ====
function '''behaviourDestroyCurrentTarget'''()
This behaviour attacks the current target, only stopping when interrupted or when the target is destroyed.

==== <code>behaviourDockWithStation</code> ====
function '''behaviourDockWithStation'''()
This behaviour docks with the station specified in the parameter "oolite_dockingStation". If the target refuses docking or the ship is too big to dock, the parameter will be cleared.

==== <code>behaviourEnterWitchspace</code> ====
function '''behaviourEnterWitchspace'''()
This behaviour attempts to enter witchspace. It can do this in several ways:
* If the parameter "oolite_witchspaceWormhole" is set to an active wormhole, it will try to fly to and use that wormhole.
* If the parameter "oolite_witchspaceDestination" is set, then it will try to jump to that destination using its own drive. It will wait for its escorts to be launched, and will start spinning up this drive. Calling this behaviour again after 15 seconds will cause it to jump out.
* Otherwise, it will wait for a wormhole to be suggested by another member of its group, or for the player to create one.

==== <code>behaviourEscortMothership</code> ====
function '''behaviourEscortMothership'''()
This behaviour performs non-combat escorting of the ship's group leader, in the formation requested by the lead ship.

==== <code>behaviourFineCurrentTarget</code> ====
function '''behaviourFineCurrentTarget'''()
If the ship has scan class "CLASS_POLICE" and a current target, mark that target for fines when it next docks.

==== <code>behaviourFleeCombat</code> ====
function '''behaviourFleeCombat'''()
The ship will flee from hostility, in the following order:
* Cascade explosions (coordinates from the parameter "oolite_cascadeDetected")
* Its current target, if it can see it
* Its defense targets, if it can see them

==== <code>behaviourFollowCurrentTarget</code> ====
function '''behaviourFollowCurrentTarget'''()
The ship will follow the current target, including through a witchspace jump if necessary, and will additionally [[#conditionHasRememberedTarget|remember]] the target.

==== <code>behaviourFollowGroupLeader</code> ====
function '''behaviourFollowGroupLeader'''()
The ship will follow the group leader if there is one, attempting to remain within a few kilometres of it.

==== <code>behaviourGuardTarget</code> ====
function '''behaviourGuardTarget'''()
The ship will fly to within a few kilometres of its current target. Similar to <code>behaviourFollowCurrentTarget</code> but will not follow the target into witchspace and will not remember that it was doing so if distracted.

==== <code>behaviourJoinTargetGroup</code> ====
function '''behaviourJoinTargetGroup'''()
The ship will add itself to its target's ship group. You should previously have used appropriate condition tests to check that this is appropriate behaviour.

==== <code>behaviourLandOnPlanet</code> ====
function '''behaviourLandOnPlanet'''()
Lands on the nearest planet. Unlike most behaviours, this one does not include the standard responses, so you should generally wait until the ship is only a few hundred metres above the surface before using it.

==== <code>behaviourLeaveVicinityOfDestination</code> ====
function '''behaviourLeaveVicinityOfDestination'''()
Moves outside scanner range of the current destination coordinates.

==== <code>behaviourLeaveVicinityOfTarget</code> ====
function '''behaviourLeaveVicinityOfTarget'''()
Moves outside scanner range of the current target. Unlike fleeing, this does not use fuel injectors if they are fitted, and does not cause the ship to appear hostile to its target.

==== <code>behaviourMineTarget</code> ====
function '''behaviourMineTarget'''()
Attacks the current target with a mining laser to break it into splinters. If the current target is not a rock, this behaviour will be cancelled and the target will be lost.

==== <code>behaviourOfferToEscort</code> ====
function '''behaviourOfferToEscort'''()
Offers to escort the ship identified by the parameter "oolite_scanResultSpecific". Unless this parameter has been set by the scanner condition [[#conditionScannerContainsShipNeedingEscort|conditionScannerContainsShipNeedingEscort]] this is extremely likely to fail.

To be accepted as an escort, the ship must have a primary role in the <code>oolite-escorts</code> [[role-categories.plist|role category]].

==== <code>behaviourPayOffPirates</code> ====
function '''behaviourPayOffPirates'''()
If a pirate demand to dump cargo exists, dump that many cargo canisters (or all of them, if fewer), and then switch to [[#behaviourFleeCombat|behaviourFleeCombat]]

==== <code>behaviourReconsider</code> ====
function '''behaviourReconsider'''()
Does nothing except schedule a re-evaluation of the priority list.

==== <code>behaviourRejoinMothership</code> ====
function '''behaviourRejoinMothership'''()
This behaviour flies to rejoin the mothership, and then escorts it as in [[#behaviourEscortMothership|behaviourEscortMothership]].

==== <code>behaviourRepelCurrentTarget</code> ====
function '''behaviourRepelCurrentTarget'''()
This behaviour attacks the current target, but will break off the attack (and ask its escorts to do the same) if the target starts fleeing.

==== <code>behaviourRespondToDistressCall</code> ====
function '''behaviourRespondToDistressCall'''()
If the ship has a valid distress call represented by the parameters "oolite_distressAggressor" and "oolite_distressSender" it will attack the aggressor if it can see it. Otherwise it will fly (with injectors if available) to near the sender, attempting to locate the aggressor.

If the aggressor has a lower bounty than the sender, then the ship will assume that the distress call is "unjust", and attack the sender instead.

==== <code>behaviourRobTarget</code> ====
function '''behaviourRobTarget'''()
If an existing group demand for cargo is in effect, attack the current target in the hope that it meets it. Demands are stored with the group leader if possible.

If there is no existing demand for cargo, create one based on the cargo capacity of the target ship, the current system government, the cargo capacity of the group, and other factors.

==== <code>behaviourSunskim</code> ====
function '''behaviourSunskim'''()
Fly along until fuel tanks are full. In general, this behaviour should not be started until sunskimming height is reached (test with [[#conditionReadyToSunskim|conditionReadyToSunskim]]), and [[#configurationSetDestinationToSunskimEnd|configurationSetDestinationToSunskimEnd]] should be used to set a safe sunskimming direction.

==== <code>behaviourTumble</code> ====
function '''behaviourTumble'''()
Start tumbling. Unlike most behaviours, this one does not include the standard responses, so you will need to manually request a reconsideration of priorities if one is needed.

=== Missile behaviours ===

Missile behaviours use <code>responsesAddMissile</code>. More discussion of setting missile parameters, ECM response, and detonation can be found there.

==== <code>behaviourMissileInterceptCoordinates</code> ====
function '''behaviourMissileInterceptCoordinates'''()
Close to the desired missile range (default 25m, or specified by the <code>oolite_missile_proximity</code> key in script info), detonating when reached. The coordinates to close in on are specified in the "oolite_interceptCoordinates". This is used to track missile targets which cloak.

==== <code>behaviourMissileInterceptTarget</code> ====
function '''behaviourMissileInterceptTarget'''()
Close to the desired missile range (default 25m, or specified by the <code>oolite_missile_proximity</code> key in script info), detonating when reached.

==== <code>behaviourMissileSelfDestruct</code> ====
function '''behaviourMissileSelfDestruct'''()
Destroys the missile without detonating the payload.

=== Station behaviours ===

Station behaviours use <code>responsesAddStation</code> to set up their general handlers, as most standard behaviours are unnecessary or unhelpful for a stationary station.

==== <code>behaviourStationLaunchDefenseShips</code> ====
function '''behaviourStationLaunchDefenseShips'''()
If the station has a target and the target is aggressive, launches a defense ship if any remain, increases the alert condition to Red, and requests a group attack on the target. Otherwise does nothing.

==== <code>behaviourStationLaunchMiner</code> ====
function '''behaviourStationLaunchMiner'''()
If the station does not currently have a miner in its ship group, launches one. Also reduces the alert condition by one step.

==== <code>behaviourStationLaunchPatrol</code> ====
function '''behaviourStationLaunchPatrol'''()
If the station does not currently have a ship in its ship group with the primary role equal to the parameter "oolite_stationPatrolRole", launches one. Also reduces the alert condition by one step.

==== <code>behaviourStationLaunchSalvager</code> ====
function '''behaviourStationLaunchMiner'''()
Launches a salvager. Also reduces the alert condition by one step.

==== <code>behaviourStationManageTraffic</code> ====
function '''behaviourStationManageTraffic'''()
The station idles. If the system repopulator has requested launches that this station can fulfil, it may launch a ship.

==== <code>behaviourStationRespondToDistressCall</code> ====
function '''behaviourStationRespondToDistressCall'''()
Locates the aggressor and sender in the same way as [[#behaviourRespondToDistressCall|behaviourRespondToDistressCall]. If the aggressor is not visible, does nothing, otherwise sets the aggressor as a target, increases alert condition to Red, and launches a defense ship to attack the aggressor.

== Condition functions ==

Condition functions are used to determine whether to execute a
priority AI behaviour. They take no arguments and return a Boolean.

=== Combat conditions ===

Conditions related to the ship's performance in combat.

==== <code>conditionCascadeDetected</code> ====
function '''conditionCascadeDetected'''() : Boolean
Returns true if a cascade explosion has been detected recently (as given by the parameter "oolite_cascadeDetected" containing the explosion coordinates).

==== <code>conditionCombatOdds*</code> ====
function '''conditionCombatOddsTerrible'''() : Boolean
function '''conditionCombatOddsBad'''() : Boolean
function '''conditionCombatOddsGood'''() : Boolean
function '''conditionCombatOddsExcellent'''() : Boolean
These functions return true if the perceived odds of this ship's group winning a fight against the target ship's group can reasonably be described with the appropriate description. "Good" and "Excellent" require the odds to be better than a particular threshold (so Excellent odds are always also Good), while "Bad" and "Terrible" require the odds to be worse than that threshold.

==== <code>conditionGroupAttritionReached</code> ====
function '''conditionGroupAttritionReached'''() : Boolean
This condition is true if the ship is in a group and that group has lost more than a quarter of its initial ships.

==== <code>conditionGroupSuppliesLow</code> ====
function '''conditionGroupSuppliesLow'''() : Boolean
This condition is true if the ship's group is running out of consumables such as missiles or fuel, or has several damaged ships.

==== <code>conditionInCombat</code> ====
function '''conditionInCombat'''() : Boolean
The ship is currently attacking other ships, or a ship in its group or one of its escorts is.

==== <code>conditionInCombatWithHostiles</code> ====
function '''conditionInCombat'''() : Boolean
The ship is currently attacking other ships, or a ship in its group or one of its escorts is. Additionally, at least one of the targets of those ships is itself attacking (though not necessarily attacking anything from this ship's group)

==== <code>conditionLosingCombat</code> ====
function '''conditionLosingCombat'''() : Boolean
The ship is in combat, but is losing. The exact definition of "losing" may vary, and is intended to account for the overall tactical situation.

==== <code>conditionMothershipInCombat</code> ====
function '''conditionMothershipInCombat'''() : Boolean
This ship's group leader is attacking and/or being attacked. Other ships in the group are not considered. This ship must be able to see its leader's target.

==== <code>conditionMothershipIsAttacking</code> ====
function '''conditionMothershipIsAttacking'''() : Boolean
This ship's group leader is attacking a target. This ship must be able to see its leader's target.

==== <code>conditionMothershipIsAttackingHostileTarget</code> ====
function '''conditionMothershipIsAttacking'''() : Boolean
This ship's group leader is attacking a target which is itself attacking something. This ship must be able to see its leader's target.

==== <code>conditionMothershipUnderAttack</code> ====
function '''conditionMothershipUnderAttack'''() : Boolean
This ship's group leader is currently being targeted. This ship must be able to see the attacker.

==== <code>conditionSuppliesLow</code> ====
function '''conditionSuppliesLow'''() : Boolean
This condition is true if this ship is personally running out of consumables such as missiles or fuel, or is damaged. This is effectively a wrapper around <code>ship.damageAssessment()</code>.

=== Navigation conditions ===

Conditions related to the ship's surroundings and navigation through the system.

==== <code>conditionCanWitchspaceOnRoute</code> ====
function '''conditionCanWitchspaceOnRoute'''() : Boolean
The ship has a witchspace drive, a witchspace route, and the next system on its [[#setWitchspaceRouteTowitchspace|route]] is within range with the current fuel supply.

==== <code>conditionCanWitchspaceOut</code> ====
function '''conditionCanWitchspaceOut'''() : Boolean
The ship has a witchspace drive, and at least one other system is within range with the current fuel supply.

==== <code>conditionFriendlyStationExists</code> ====
function '''conditionFriendlyStationExists'''() : Boolean
There is at least one friendly station in the system.

==== <code>conditionFriendlyStationNearby</code> ====
function '''conditionFriendlyStationNearby'''() : Boolean
There is at least one friendly station within scanner range

==== <code>conditionGroupIsSeparated</code> ====
function '''conditionGroupIsSeparated'''() : Boolean
The ship is in a group and has a group leader, and is out of scanner range of that leader (or out of 2x scanner range if the leader is a station)

==== <code>conditionHasSelectedPlanet</code> ====
function '''conditionHasSelectedPlanet'''() : Boolean
The ship has a valid planet in the "oolite_selectedPlanet" parameter.

==== <code>conditionHasSelectedStation</code> ====
function '''conditionHasSelectedStation'''() : Boolean
The ship has a valid planet in the "oolite_selectedStation" parameter.

==== <code>conditionHomeStationExists</code> ====
function '''conditionHomeStationExists'''() : Boolean
The ship's home station still exists

==== <code>conditionHomeStationNearby</code> ====
function '''conditionHomeStationNearby'''() : Boolean
The ship's home station is within scanner range.

==== <code>conditionHostileStationNearby</code> ====
function '''conditionHostileStationNearby'''() : Boolean
There is at least one hostile station within scanner range

==== <code>conditionInInterstellarSpace</code> ====
function '''conditionInInterstellarSpace'''() : Boolean
The ship is currently in interstellar space.

==== <code>conditionMainPlanetNearby</code> ====
function '''conditionMainPlanetNearby'''() : Boolean
The ship is within 3 radii of the surface of the main planet

==== <code>conditionNearDestination</code> ====
function '''conditionNearDestination'''() : Boolean
The ship is closer than the desired range to its destination

==== <code>conditionPlayerNearby</code> ====
function '''conditionPlayerNearby'''() : Boolean
The player's ship is within scanner range.

==== <code>conditionReadyToSunskim</code> ====
function '''conditionReadyToSunskim'''() : Boolean
The ship is close enough to the sun to scoop fuel.

==== <code>conditionSelectedStationNearby</code> ====
function '''conditionSelectedStationNearby'''() : Boolean
The ship has a selected station in the "oolite_selectedStation" parameter, and it is within scanner range.

==== <code>conditionSelectedStationNearMainPlanet</code> ====
function '''conditionSelectedStationNearMainPlanet'''() : Boolean
The ship has a selected station in the "oolite_selectedStation" parameter, and it is within 3 radii of the surface of the main planet.

==== <code>conditionStationNearby</code> ====
function '''conditionStationNearby'''() : Boolean
There is a station within scanner range.

==== <code>conditionSunskimPossible</code> ====
function '''conditionSunskimPossible'''() : Boolean
There is a sun, it's not going nova, it hasn't gone nova, the ship has a non-full fuel tank and fuel scoops, and the ship has sufficient heat insulation to skim safely.

==== <code>conditionWormholeNearby</code> ====
function '''conditionWormholeNearby'''() : Boolean
There is an entry wormhole within scanner range.

=== Piracy-related conditions ===

Conditions involved in piratical activities.

==== <code>conditionCargoDemandsMet</code> ====
function '''conditionCargoDemandsMet'''() : Boolean
Since this ship (or an ally) made a cargo demand, this ship has seen enough cargo dropped to meet that demand.

==== <code>conditionGroupHasEnoughLoot</code> ====
function '''conditionGroupHasEnoughLoot'''() : Boolean
The group this ship belongs to has obtained enough cargo to call it a day. Currently this happens when cargo space usage is above 50%, but more sophisticated checks are planned involving damage or lost ships, expenditure of consumables, and so on.

==== <code>conditionPiratesCanBePaidOff</code> ====
function '''conditionPiratesCanBePaidOff'''() : Boolean
Pirates have demanded that this ship dump cargo, and it currently has enough cargo on board to meet that demand.

=== Scanning conditions ===

These conditions check the ship's latest scan ([[#configurationCheckScanner|configurationCheckScanner]]) for ships meeting particular requirements. If a ship is found, it will be placed in the "oolite_scanResultsSpecific" parameter, in addition to the condition returning true.

==== <code>conditionScannerContainsAssassinationTarget</code> ====
function '''conditionScannerContainsAssassinationTarget'''() : Boolean
The scan contains an assassination target (i.e. an escape capsule)

==== <code>conditionScannerContainsCleanShip</code> ====
function '''conditionScannerContainsCleanShip'''() : Boolean
The scan contains a clean ship

==== <code>conditionScannerContainsCourier</code> ====
function '''conditionScannerContainsCourier'''() : Boolean
The scan contains a courier ship

==== <code>conditionScannerContainsEscapePods</code> ====
function '''conditionScannerContainsEscapePods'''() : Boolean
The scan contains an escape pod travelling slower than this ship's maximum speed, and this ship is able to scoop cargo.

==== <code>conditionScannerContainsFineableOffender</code> ====
function '''conditionScannerContainsFineableOffender'''() : Boolean
The scan contains a piloted ship with an offender legal status at or below the system threshold (varies with government) that has not already been marked for fines.

==== <code>conditionScannerContainsFugitive</code> ====
function '''conditionScannerContainsFugitive'''() : Boolean
The scan contains a fugitive ship

==== <code>conditionScannerContainsHuntableOffender</code> ====
function '''conditionScannerContainsHuntableOffender'''() : Boolean
The scan contains a piloted ship with an offender legal status not too small to bother with (varies with government).

==== <code>conditionScannerContainsSeriousOffender</code> ====
function '''conditionScannerContainsSeriousOffender'''() : Boolean
The scan contains a piloted ship with an offender legal status at or above the system threshold for fines (varies with government).

==== <code>conditionScannerContainsHunters</code> ====
function '''conditionScannerContainsHunters'''() : Boolean
The scan contains a ship with role "hunter", or a police ship, or the main station.

==== <code>conditionScannerContainsLoneVictim</code> ====
function '''conditionScannerContainsLoneVictim'''() : Boolean
The scan contains a single pirate victim and no other unallied ships.

==== <code>conditionScannerContainsMiningOpportunity</code> ====
function '''conditionScannerContainsMiningOpportunity'''() : Boolean
The scan contains a boulder (preferentially) or an asteroid, and the ship has a mining laser, a fuel scoop, and a non-full hold.

==== <code>conditionScannerContainsNonThargoid</code> ====
function '''conditionScannerContainsNonThargoid'''() : Boolean
The scan contains a ship which is not a Thargoid ship. Rocks and cargo will only be returned if there is nothing more interesting about.

==== <code>conditionScannerContainsPirateLeader</code> ====
function '''conditionScannerContainsPirateLeader'''() : Boolean
The scan contains a pirate leader (usually a heavily-armed freighter)

==== <code>conditionScannerContainsPirateVictims</code> ====
function '''conditionScannerContainsPirateVictims'''() : Boolean
The scan contains a pirate victim (as defined by <code>[[role-categories.plist]]</code>) which is carrying at least some cargo and has not recently been robbed.

==== <code>conditionScannerContainsReadyThargoidMothership</code> ====
function '''conditionScannerContainsReadyThargoidMothership'''() : Boolean
The scan contains a thargoid mothership which has the capability to control at least one more thargon.

==== <code>conditionScannerContainsRocks</code> ====
function '''conditionScannerContainsRocks'''() : Boolean
The scan contains boulders (preferentially) or asteroids.

==== <code>conditionScannerContainsSalvage</code> ====
function '''conditionScannerContainsSalvage'''() : Boolean
The scan contains cargo which could in theory be scooped.

==== <code>conditionScannerContainsSalvageForGroup</code> ====
function '''conditionScannerContainsSalvageForGroup'''() : Boolean
The scan contains cargo which could in theory be scooped, and it is travelling slowly enough that at least one of the ships in the group with fuel scoops and cargo space can collect it..

==== <code>conditionScannerContainsSalvageForMe</code> ====
function '''conditionScannerContainsSalvageForMe'''() : Boolean
The scan contains cargo which can be scooped by this ship (travelling slowly enough, and this ship has scoops and space)

==== <code>conditionScannerContainsShipNeedingEscort</code> ====
function '''conditionScannerContainsShipNeedingEscort'''() : Boolean
The scan contains a ship which has fewer escorts than its maximum. If the ship is clean, this will only detect other clean ships. If the ship is not clean, this will only detect other non-clean ships.

==== <code>conditionScannerContainsSuspiciousShip</code> ====
function '''conditionScannerContainsSuspiciousShip'''() : Boolean
The scan contains a ship with a criminal reputation (whether or not it currently carries a bounty)

==== <code>conditionScannerContainsThargoidMothership</code> ====
function '''conditionScannerContainsThargoidMothership'''() : Boolean
The scan contains a thargoid mothership which has the capability to control thargons. The number of thargons currently being controlled is irrelevant to this scan.

==== <code>conditionScannerContainsUnspreadMissile</code> ====
function '''conditionScannerContainsUnspreadMissile'''() : Boolean
The scan contains a missile which has the same target and owner as this ship, but is closer to the target and within 500 metres of this ship. This is mainly used for "smart" missiles to ensure that impact times for a salvo are spread out.

=== State querying conditions ===

Conditions related to the state of the ship

==== <code>conditionAllEscortsInFlight</code> ====
function '''conditionAllEscortsInFlight'''() : Boolean
If the ship has living escorts, then this function returns <code>true</code> only if they are all in normal flight (and not docked, launching, or in a wormhole). If the ship has no escorts then this function also returns <code>true</code>.

==== <code>conditionCanScoopCargo</code> ====
function '''conditionCanScoopCargo'''() : Boolean
The ship has a working fuel scoop and at least 1 TC of free space in its hold.

==== <code>conditionCargoIsProfitableHere</code> ====
function '''conditionCargoIsProfitableHere'''() : Boolean
The current contents of the ship's hold can be sold at an above average price at the main station (this is currently determined very approximately - solely asking "is the current system on the right side of the Ind/Agri divide" - rather than checking station prices.

==== <code>conditionCoinFlip</code> ====
function '''conditionCoinFlip'''() : Boolean
Returns true half the time.

==== <code>conditionGroupLeaderIsStation</code> ====
function '''conditionGroupLeaderIsStation'''() : Boolean
The ship has a group leader and the group leader is a station.

==== <code>conditionHasInterceptCoordinates</code> ====
function '''conditionHasInterceptCoordinates'''() : Boolean
The ship has intercept coordinates set in the parameter "oolite_interceptCoordinates". These are used by missiles to home in on a last-known location if the target cloaks.

==== <code>conditionHasMothership</code> ====
function '''conditionHasMothership'''() : Boolean
The ship has a group leader which is not itself.

==== <code>conditionHasNonThargoidTarget</code> ====
function '''conditionHasNonThargoidTarget'''() : Boolean
The ship's target is not null, and is not a thargoid ship (by scan class).

==== <code>conditionHasReceivedDistressCall</code> ====
function '''conditionHasReceivedDistressCall'''() : Boolean
The ship has recently received a distress call. Distress calls expire after 30 seconds, or if the sender is no longer visible, or if the aggressor is dead.

==== <code>conditionHasRememberedTarget</code> ====
function '''conditionHasRememberedTarget'''() : Boolean
The ship has a remembered target. This is set by [[#behaviourFollowCurrentTarget|behaviourFollowCurrentTarget]] to allow persistent tracking of a ship.

==== <code>conditionHasTarget</code> ====
function '''conditionHasTarget'''() : Boolean
The ship's target is not null.

==== <code>conditionHasWaypoint</code> ====
function '''conditionHasWaypoint'''() : Boolean
The ship has a waypoint set by its [[#|waypoint generator]].

==== <code>conditionIsActiveThargon</code> ====
function '''conditionIsActiveThargon'''() : Boolean
The ship is a thargon ("EQ_THARGON") and is active.

==== <code>conditionIsEscorting</code> ====
function '''conditionIsEscorting'''() : Boolean
The ship is currently escorting another ship. Stricter than [[#conditionHasMothership|conditionHasMothership]]: this also requires this ship to be in the group leader's escort group.

==== <code>conditionIsGroupLeader</code> ====
function '''conditionIsGroupLeader'''() : Boolean
The ship is in a group and is the leader of the group

==== <code>conditionMissileNeedsLaunchEvasion</code> ====
function '''conditionMissileNeedsLaunchEvasion'''() : Boolean
This function checks if the <code>oolite_flag_launchAdjustMissile</code> parameter is set to a non-null value, and returns true if so.

Missile AI scripts may find the following code useful to set this flag to avoid collisions with the launching ship.

this.shipSpawned = function()
{
/* Launch correction when fired at target in aft arc */
if (this.ship.target && this.ship.target.position.subtract(this.ship.position).direction().dot(this.ship.vectorForward) < -0.8)
{
this.oolite_priorityai.setParameter("oolite_flag_launchAdjustMissile",true);
}
}

See also [[#configurationMissileAdjustLaunch|configurationMissileAdjustLaunch]]

==== <code>conditionMissileOutOfFuel</code> ====
function '''conditionMissileOutOfFuel'''() : Boolean
The ship has travelled beyond the maximum missile range. The default is 30km, but this may be overridden by the <code>oolite_missile_range</code> parameter in the ship's script info.

==== <code>conditionPatrolIsOver</code> ====
function '''conditionPatrolIsOver'''() : Boolean
The ship's patrol is over (either due to distance travelled or a need to re-arm and repair). Note that the distance threshold is relatively low, so for ships on long patrol routes between system bodies this function should only be called when reaching appropriate waypoints.

==== <code>conditionWitchspaceEntryRequested</code> ====
function '''conditionWitchspaceEntryRequested'''() : Boolean
The ship has been requested to enter a wormhole set in the "oolite_witchspaceWormhole" parameter.

== Configuration functions ==

Configuration functions are usually used to set up parameters needed for a behaviour, though some may be used at the preconfiguration stage to set up parameters for a condition test. They take no arguments and do not return anything.

=== Destination configurations ===

These configurations set a destination, a desired range and a desired speed suitable for use with [[#behaviourApproachDestination|behaviourApproachDestination]]. Unless otherwise stated, [[#cruiseSpeed|cruiseSpeed]] will be used as the desired speed.

If they are unable to set a destination, they may set the destination to the ship's current position, or may do nothing. Generally a condition should be used to check that the configuration is sensible.

==== <code>configurationMissileAdjustLaunch</code> ====
function '''configurationMissileAdjustLaunch'''()
This function causes the missile to dive sharply. The intended use is in conjunction with [[#conditionMissileNeedsLaunchEvasion|conditionMissileNeedsLaunchEvasion]] to avoid collisions with the launching ship.

==== <code>configurationMissileAdjustSpread</code> ====
function '''configurationMissileAdjustSpread'''()
This function sets an intermediate destination for "smart" missiles which are adjusting their flight path to spread out a salvo's impacts on target.

==== <code>configurationSetDestinationToHomeStation</code> ====
function '''configurationSetDestinationToHomeStation'''()
Locates the home station, sets the destination to its position and the desired range to 15km.

==== <code>configurationSetDestinationToGroupLeader</code> ====
function '''configurationSetDestinationToGroupLeader'''()
Locates the group leader, sets the destination to its position and the desired range to 15km. Maximum flight speed is used.

==== <code>configurationSetDestinationToMainPlanet</code> ====
function '''configurationSetDestinationToMainPlanet'''()
Sets the destination to the main planet's position, and the desired range to 3 radii (i.e. 2 radii from the surface).

==== <code>configurationSetDestinationToMainStation</code> ====
function '''configurationSetDestinationToMainStation'''()
Sets the destination to the main station's position, and the desired range to 15km

==== <code>configurationSetDestinationToNearestHostileStation</code> ====
function '''configurationSetDestinationToNearestHostileStation'''()
Locates the nearest friendly station, sets the destination to its position and the desired range to 15km.

==== <code>configurationSetDestinationToNearestFriendlyStation</code> ====
function '''configurationSetDestinationToNearestFriendlyStation'''()
Locates the nearest friendly station, sets the destination to its position and the desired range to 15km.

==== <code>configurationSetDestinationToNearestStation</code> ====
function '''configurationSetDestinationToNearestStation'''()
Locates the nearest station, sets the destination to its position and the desired range to 15km.

==== <code>configurationSetDestinationToNearestWormhole</code> ====
function '''configurationSetDestinationToNearestWormhole'''()
Locates the nearest entry wormhole, sets the destination to its position and the desired range to zero.

==== <code>configurationSetDestinationToPirateLurk</code> ====
function '''configurationSetDestinationToPirateLurk'''()
If the parameter "oolite_pirateLurk" is set, then set the destination to that. If currently on a lane, set the destination to the current position. Otherwise, pick a random point on one of the lanes (strongly preferring witchpoint-planet). Once a destination is selected, store it to the parameter "oolite_pirateLurk".

The desired range is 1km.

==== <code>configurationSetDestinationToScannedTarget</code> ====
function '''configurationSetDestinationToScannedTarget'''()
Sets the destination to the position of the ship in the parameter "oolite_scanResultSpecific", and the desired range to 400m. This can be used to follow a ship without targeting it.

==== <code>configurationSetDestinationToSelectedPlanet</code> ====
function '''configurationSetDestinationToSelectedPlanet'''()
Sets the destination to the position of the planet in the parameter "oolite_selectedPlanet", and the desired range to 100m from the surface.

==== <code>configurationSetDestinationToSelectedStation</code> ====
function '''configurationSetDestinationToSelectedStation'''()
Sets the destination to the position of the station in the parameter "oolite_selectedStation", and the desired range to 15km.

==== <code>configurationSetDestinationToSunskimEnd</code> ====
function '''configurationSetDestinationToSunskimEnd'''()
Sets the destination to a course parallel to the sun's surface, at a range which should allow the fuel tanks to be completely refilled. The desired range is 0, and the desired speed is maximum speed.

Note: if this function is used above sunskimming height, it will still
move parallel to the sun's surface, but this will not be much use.

==== <code>configurationSetDestinationToSunskimStart</code> ====
function '''configurationSetDestinationToSunskimStart'''()
Sets the destination to the sun's position, and the desired range to sunskimming height.

==== <code>configurationSetDestinationToWaypoint</code> ====
function '''configurationSetDestinationToWaypoint'''()
If the parameters "oolite_waypoint" and "oolite_waypointRange" are set, use those as the destination and desired range.

==== <code>configurationSetDestinationToWitchpoint</code> ====
function '''configurationSetDestinationToWitchpoint'''()
Sets the destination to the witchpoint and the range to 10km

==== <code>configurationSetWaypoint</code> ====
function '''configurationSetWaypoint'''()
If a waypoint generator function has been registered, runs that function to set the "oolite_waypoint" and "oolite_waypointRange" parameters, then sets the destination from those parameters.

=== Docking configurations ===

Each of these configurations sets the "oolite_dockingStation" parameter used by [[#behaviourDockWithStation|behaviourDockWithStation]]

==== <code>configurationSetNearbyFriendlyStationForDocking</code> ====
function '''configurationSetNearbyFriendlyStationForDocking'''()
Sets the "oolite_dockingStation" parameter to a friendly station in scanner range, if possible.

==== <code>configurationSetHomeStationForDocking</code> ====
function '''configurationSetHomeStationForDocking'''()
Sets the "oolite_dockingStation" parameter to the ship's home station.

==== <code>configurationSetSelectedStationForDocking</code> ====
function '''configurationSetHomeStationForDocking'''()
Sets the "oolite_dockingStation" parameter to the station in the parameter "oolite_selectedStation".

=== Miscellaneous configurations ===

==== <code>configurationAppointGroupLeader</code> ====
function '''configurationAppointGroupLeader'''()
If the ship is in a group but the group has no leader, set one of the ships in the group to be the leader. Witchspace-capable ships will be preferred over those which are not.

If the parameter "oolite_leaderRole" is set, the primary role of the new leader will be changed to that role.

==== <code>configurationEscortGroupLeader</code> ====
function '''configurationEscortGroupLeader'''()
If the ship is in a group and the group has a leader which is not this ship and the ship is not already escorting the group leader, and the parameter "oolite_escortRole" is set, then attempt to escort the group leader. The ship's primary role will be set to "oolite_escortRole" if the escort attempt is successful, and this role must therefore be a valid escort role.

==== <code>configurationForgetCargoDemand</code> ====
function '''configurationForgetCargoDemand'''()
If the ship has a cargo demand active (the demand must be stored on this ship, not just on a group member), discard it, and reset the "oolite_cargoDropped" parameter of this ship and all group members to zero.

==== <code>configurationLeaveEscortGroup</code> ====
function '''configurationLeaveEscortGroup'''()
If the ship is currently escorting another ship, leave the escort group.

==== <code>configurationLightsOff</code> ====
function '''configurationLightsOff'''()
Set the ship's flashers to the 'off' state.

==== <code>configurationLightsOn</code> ====
function '''configurationLightsOn'''()
Set the ship's flashers to the 'on' state.

==== <code>configurationSetRemoteControl</code> ====
function '''configurationSetRemoteControl'''()
If the ship has a group leader, set its own accuracy to that ship's accuracy. This is used by thargons when the mothership controlling them is changed.

=== Navigation configurations ===

==== <code>configurationSelectPlanet</code> ====
function '''configurationSelectPlanet'''()
This function places a randomly selected planet or moon in the parameter "oolite_selectedPlanet"

==== <code>configurationSelectRandomTradeStation</code> ====
function '''configurationSelectRandomTradeStation'''()
This function places a suitable station in the parameter "oolite_selectedStation". If the ship is clean, then 90% of the time this will be the main station. If the ship is an offender, but has a bounty not greater than the fine threshold, then 50% of the time this will be the main station.

If the main station was not selected at the previous step, a random
friendly station will be selected (which may be the main station
anyway)

==== <code>configurationSelectShuttleDestination</code> ====
function '''configurationSelectShuttleDestination'''()
This function selects a random planet or station. The entity selected must be at least 10km from the ship. If any such entities are within 5 times the radius of the main planet from the ship, more distant entities will be ignored.

If the selected entity was a planet, it will be stored in "oolite_selectedPlanet". Otherwise, it will be stored in "oolite_selectedStation".

==== <code>configurationSelectWitchspaceDestination</code> ====
function '''configurationSelectWitchspaceDestination'''()
If the ship has no witchspace drive, unset the "oolite_witchspaceDestination" parameter. If that parameter is already set, and is not the current system, and the ship has enough fuel to reach that system, do nothing. Otherwise, select a random system in range and place its ID in the "oolite_witchspaceDestination" parameter.

==== <code>configurationSelectWitchspaceDestinationInbound</code> ====
function '''configurationSelectWitchspaceDestination'''()
If the ship has no witchspace drive, unset the "oolite_witchspaceDestination" parameter. If the ship's home system and destination system are unequal, select the next system on the route to the home system. Otherwise, select a random system in range and place its ID in the "oolite_witchspaceDestination" parameter.

==== <code>configurationSelectWitchspaceDestinationOutbound</code> ====
function '''configurationSelectWitchspaceDestination'''()
If the ship has no witchspace drive, unset the "oolite_witchspaceDestination" parameter. If the ship's home system and destination system are unequal, select the next system on the route to the destination system. Otherwise, select a random system in range and place its ID in the "oolite_witchspaceDestination" parameter.

=== Station configurations ===

==== <code>configurationStationReduceAlertLevel</code> ====
function '''configurationStationReduceAlertLevel'''()
Reduce the alert level of the station by one stage if it is not already Green.

==== <code>configurationStationValidateTarget</code> ====
function '''configurationStationValidateTarget'''()
Check that the station's current target is within scanner range, and discard it if not. This is necessary for stations as unlike ships their low-level behaviour does not generally do this automatically.

=== Target acquisition configurations ===

==== <code>configurationAcquireCombatTarget</code> ====
function '''configurationAcquireCombatTarget'''()
If the ship's target is valid, not cargo and not an ally, keep the current target. Otherwise, promote one defense target to a target. If the ship has no defense targets, check to see if any ships in the group or escort group have a combat target (but do not check their defense targets).

==== <code>configurationAcquireDefensiveEscortTarget</code> ====
function '''configurationAcquireDefensiveEscortTarget'''()
Search the current group leader's target and defense targets for a visible ship attacking the group leader, and target it if one is found. Otherwise, retain current target.

==== <code>configurationAcquireHostileCombatTarget</code> ====
function '''configurationAcquireHostileCombatTarget'''()
As [[#configurationAcquireCombatTarget|configurationAcquireCombatTarget]] but only targets which are hostile (i.e. would be valid for [[#behaviourRepelTarget|behaviourRepelTarget]]) will be selected.

==== <code>configurationAcquireOffensiveEscortTarget</code> ====
function '''configurationAcquireOffensiveEscortTarget'''()
If this ship's group leader is attacking a target, and this ship can see that target, acquire that target. Otherwise retain current target.

==== <code>configurationAcquirePlayerAsTarget</code> ====
function '''configurationAcquirePlayerAsTarget'''()
Set this ship's target to the player.

==== <code>configurationAcquireScannedTarget</code> ====
function '''configurationAcquireScannedTarget'''()
Set this ship's target to the entity in the parameter "oolite_scanResultSpecific". This parameter is set by the [[#checkScannerWithPredicate|checkScannerWithPredicate]] function, which is usually called from a <code>conditionScannerContains...</code> condition.

==== <code>configurationCheckScanner</code> ====
function '''configurationCheckScanner'''()
Scans the ship's scanner range, placing a list of detected targets into the "oolite_scanResults" parameter. This is generally called in a preconfiguration before the first use of a <code>conditionScannerContains...</code> condition in the priority list.

If the scanner is particularly full, the list will not contain all visible objects. The current scan limit is 16.

== Response definition functions and components ==

=== Response definition functions ===

Response definition functions are used to set up event handlers in the AI script. They take an object as an argument, and add event handlers to that object. They do not return anything as such, but modify their argument.

They are generally used in behaviour functions to set up common responses.
var handlers = {}; // new handler object
this.responsesAddStandard(handlers); // add standard response set
// add a handler for this behaviour
handlers.shipEnteredStationAegis = function(station)
{
this.ship.beaconCode = null; // stop transmitting
}
this.applyHandlers(handlers);

==== <code>responsesAddDocking</code> ====
function '''responsesAddDocking'''(handlers : Object)
Provides some additional event handlers for use when docking with a station.

==== <code>responsesAddEscort</code> ====
function '''responsesAddEscort'''(handlers : Object)
Provides some additional event handlers for use when escorting a ship, and changes the response to in-group help requests.

==== <code>responsesAddMissile</code> ====
function '''responsesAddMissile'''(handlers : Object)
A standard set of event handlers for missiles, which should be used instead of <code>responsesAddStandard</code>.

A number of script info keys are used to modify the responses.
* oolite_missile_blastPower, oolite_missile_blastRadius, oolite_missile_blastShaping: If oolite_missile_detonation is not set, the default detonation function calls this.ship.dealEnergyDamage with the defined power, radius, and shaping. If these parameters are not set the defaults are power 170, radius 32.5, and shaping 0.25.
* oolite_missile_detonation: names a function in the AI script. This function will be called when the missile reaches the desired range from its target or destination. If this function is not set, the oolite_missile_blast* keys are used to set up an explosion.
* oolite_missile_ecmResponse: names a function in the AI script. This function will be called if the missile detects an ECM pulse. If no function is set, the missile will self destruct.

==== <code>responsesAddScooping</code> ====
function '''responsesAddScooping'''(handlers : Object)
Provides some additional event handlers for use when scooping fuel.

==== <code>responsesAddStandard</code> ====
function '''responsesAddStandard'''(handlers : Object)
Sets up standard event handlers to detect and respond to attacks, and to manage other common events. Certain parameter flags are used:
* oolite_flag_allowPlanetaryLanding: if true, the ship will land on a planet if it receives the <code>approachingPlanetSurface</code> event. Otherwise, it will immediately reconsider its behaviour.
* oolite_flag_listenForDistressCall: if true, the ship will set the "oolite_distressAggressor", "oolite_distressSender" and "oolite_distressTimestamp" parameters if it receives a distress call.
* oolite_flag_markOffenders: if true, the ship will apply a small bounty increase to ships it sees committing crimes.
* oolite_flag_sendsDistressCalls: if true, the ship will send distress calls when attacked.
* oolite_flag_watchForCargo: if true, the ship will increment the "oolite_cargoDropped" parameter if cargo is dumped nearby.

If multiple standard responses are being applied, this one should be the first one applied.

==== <code>responsesAddStation</code> ====
function '''responsesAddStation'''(handlers : Object)
A standard set of event handlers for stations, which should be used instead of <code>responsesAddStandard</code>. The "oolite_flag_listenForDistressCall" and "oolite_flag_markOffenders" parameters have the same use as in <code>responsesAddStandard</code>.

=== Response definition components ===

The components are standard event handlers used by the standard response functions. The following response components are available. Each is named "<code>responseComponent_''responseGroup''_''handlerName''</code>". You can use them in your own handler definition functions for efficiency.
var handlers = {};
handlers.approachingPlanetSurface = this.responseComponent_standard_approachingPlanetSurface;
// .. etc ..
this.applyHandlers(handlers);

==== Standard components ====
Standard event handlers for normal ships.
responseComponent_standard_approachingPlanetSurface
responseComponent_standard_cargoDumpedNearby
responseComponent_standard_cascadeWeaponDetected
responseComponent_standard_commsMessageReceived
responseComponent_standard_distressMessageReceived
responseComponent_standard_escortAccepted
responseComponent_standard_helpRequestReceived
responseComponent_standard_offenceCommittedNearby
responseComponent_standard_playerWillEnterWitchspace
responseComponent_standard_shipAcceptedEscort
responseComponent_standard_shipAchievedDesiredRange
responseComponent_standard_shipAttackedOther
responseComponent_standard_shipAttackedWithMissile
responseComponent_standard_shipAttackerDistracted
responseComponent_standard_shipBeingAttacked
responseComponent_standard_shipBeingAttackedUnsuccessfully
responseComponent_standard_shipFiredMissile
responseComponent_standard_shipKilledOther
responseComponent_standard_shipLaunchedEscapePod
responseComponent_standard_shipLaunchedFromStation
responseComponent_standard_shipScoopedOther
responseComponent_standard_shipTargetLost
responseComponent_standard_shipWillEnterWormhole
responseComponent_standard_shipWitchspaceBlocked
responseComponent_standard_wormholeSuggested

==== Missile components ====
Standard event handlers for missiles.
responseComponent_missile_commsMessageReceived
responseComponent_missile_shipHitByECM
responseComponent_missile_shipTargetCloaked
responseComponent_missile_shipTargetLost
responseComponent_missile_shipAchievedDesiredRange

==== Station components ====
Standard event handlers for stations.
responseComponent_station_commsMessageReceived
responseComponent_station_cascadeWeaponDetected
responseComponent_station_shipAttackedWithMissile
responseComponent_station_shipBeingAttacked
responseComponent_station_shipAttackedOther
responseComponent_station_shipFiredMissile
responseComponent_station_shipKilledOther
responseComponent_station_shipTargetLost
responseComponent_station_helpRequestReceived
responseComponent_station_distressMessageReceived
responseComponent_station_offenceCommittedNearby

==== Docking components ====
Alternative event handlers for docking ships.
responseComponent_docking_shipAchievedDesiredRange
responseComponent_docking_stationWithdrewDockingClearance
responseComponent_docking_shipAIFrustrated

==== Escort components ====
Alternative event handlers for escorts.
responseComponent_escort_escortDock
responseComponent_escort_helpRequestReceived

==== Expect-witchspace components ====
Alternative event handlers for ships expecting that their target might enter witchspace to escape
responseComponent_expectWitchspace_shipTargetLost

==== Scooping components ====
Alternative event handlers for ships scooping fuel.
responseComponent_scooping_shipAchievedDesiredRange
responseComponent_scooping_shipScoopedFuel

==== Track-player components ====
Alternative event handlers for ships following the player.
responseComponent_trackPlayer_playerWillEnterWitchspace

== Template functions ==

These functions return standard blocks of priorities for insertion into a priority list. Each of them returns an array, so can be used as a branch in its own right, or concatenated on to an existing array. Remember that unlike a standard priority entry, you need the result of these functions, not a reference to the function.
{
condition: ai.conditionInCombat,
falsebranch: ai.templateReturnToBase()
}
or
priorities.concat(ai.templateReturnToBase());

==== templateLeadHuntingMission ====
function '''templateLeadHuntingMission'''() : Array
Return the priorities for leading a patrol between waypoints. Setting the waypoint generator and handling fighting and scanning along the course of the patrol should be handled by higher priorities.

==== templateLeadPirateMission ====
function '''templateLeadPirateMission'''() : Array
Return the priorities for selecting targets to rob if any are about, or moving to a suitable lurk position otherwise.

==== templateReturnToBase ====
function '''templateReturnToBase'''() : Array
Return the priorities for travelling to and docking with a suitable station.

==== templateReturnToBaseOrPlanet ====
function '''templateReturnToBaseOrPlanet'''() : Array
Return the priorities for travelling to and docking with a suitable station, or landing on a planet if no suitable stations are found.

==== templateWitchspaceJumpAnywhere ====
function '''templateWitchspaceJumpAnywhere'''() : Array
Returns priorities for getting the ship out of the current system somehow - either by jumping out, or by finding a wormhole to hitchhike.

==== templateWitchspaceJumpInbound ====
function '''templateWitchspaceJumpInbound'''() : Array
Returns priorities for jumping closer to the home system, sunskimming if fuel is short. You should previously have checked that the ship is not in the home system.

==== templateWitchspaceJumpOutbound ====
function '''templateWitchspaceJumpOutbound'''() : Array
Returns priorities for jumping closer to the destination system, sunskimming if fuel is short. You should previously have checked that the ship is not in the destination system.

== Utility functions ==

These functions are provided to make standardised checks easier to write and to wrap certain ship methods to make them easier to work with in the AI controller.

==== <code>allied</code> ====
function '''allied'''(ship1, ship2) : Boolean
Returns <code>true</code> if the two ships are considered allied, false otherwise. Ships are considered allied if they are in the same group, or if they are escorts of ships in the same group.

==== <code>broadcastDistressMessage</code> ====
function '''broadcastDistressMessage'''()
Broadcasts a distress message, but with a delay to ensure that [[Oolite_JavaScript_Reference:_Ship#broadcastDistressMessage|ship.broadcastDistressMessage()]] is not called too often.

==== <code>checkScannerWithPredicate</code> ====
function '''checkScannerWithPredicate'''(function) : Boolean
Called after configurationCheckScanner to locate a ship on the scanner matching a particular predicate. The predicate function must take a Ship, and return a Boolean.

If the predicate function matches a ship, the first such match will be stored in the parameter <code>"oolite_scanResultSpecific"</code>, and the method will return <code>true</code>. Otherwise the method returns <code>false</code>.

==== <code>cruiseSpeed</code> ====
function '''cruiseSpeed'''() : Number
Returns a suitable speed for the ship to travel at if it is interested in preserving group or escort coherence. Generally this will be 80% of its maximum speed, but it will be slower if other group members or escorts are slower.

==== <code>distance</code> ====
function '''distance'''(position : [[Oolite_JavaScript_Reference:_Vector3D#Vector_Expressions|vectorExpression]])
Returns the distance to the given coordinates. This is more efficient than calling <code>this.ship.position.distanceTo(position)</code>.

==== <code>entityCommsParams</code> ====
function '''entityCommsParams'''(entity : Entity) : Object
Returns an object of communications parameters relating to the given entity. Used internally by [[#communicate|communicate()]] but may be of use elsewhere.

==== <code>fineThreshold</code> ====
function '''fineThreshold'''() : Number
The maximum bounty at which an offender should be fined rather than attacked by police ships. (Ships caught redhanded may be attacked regardless of bounty) Varies from system to system.

==== <code>friendlyStation</code> ====
function '''friendlyStation'''(station) : Boolean
Returns <code>true</code> if the station is friendly to the current ship, false otherwise. The main station is unfriendly to Fugitive ships and Offenders above the current [[#fineThreshold|fineThreshold]]. Other stations are only considered unfriendly to their current combat target.

==== <code>homeStation</code> ====
function '''homeStation'''() : Boolean
Returns the home station of this ship. If the ship has an owner, and
the owner is a station, then that is the home station. Otherwise, the
first station in the ship's group is returned.

If no home station can be found, returns <code>null</code>.

==== <code>ignorePlayerFriendlyFire</code> ====
function '''ignorePlayerFriendlyFire'''() : Boolean
Returns <code>true</code> if this ship should ignore friendly fire from the player as they would for a known ally. Note that this function's results will change if called repeatedly, so you should only call it once per instance of friendly fire, and never call it speculatively.

==== <code>isAggressive</code> ====
function '''isAggressive'''() : Boolean
Returns <code>true</code> if the ship is an active danger to its current target (approximately: it is in a combat behaviour other than fleeing)

==== <code>isEscaping</code> ====
function '''isEscaping'''() : Boolean
Returns <code>true</code> if the ship is successfully running away from this ship (i.e. it is not attacking, it is travelling faster than this ship can, and it is already outside effective weapons range.

==== <code>isFighting</code> ====
function '''isAggressive'''() : Boolean
Returns <code>true</code> if the ship is in combat (including fleeing). Similar to <code>ship.hasHostileTarget</code> but works for stations as well.

==== <code>noteDistraction</code> ====
function '''noteDistraction'''(whom : Entity)
If this ship is switching combat targets because another ship distracted it, then call this function just before switching. <code>whom</code> is the entity that this ship will soon switch to attacking. This calls the <code>shipAttackerDistracted</code> event handler on the current target.

==== <code>oddsAssessment</code> ====
function '''oddsAssessment'''() : Number
Carry out an odds assessment of this ship's group versus the target ship's group. This will return a positive number of the ratio between the two values, with a number greater than 1 implying that this ship's group is stronger, and a number less than 1 implying the target's group is stronger. The odds assessment of the target group will omit certain information unless the target is currently in combat. Ships outside of scanner range, whether friendly or hostile, will also be ignored in the assessment.

==== <code>playerRoleAssessment</code> ====
function '''playerRoleAssessment'''() : String
Determines a single perceived role for the player based on [[Oolite_JavaScript_Reference:_Player#roleWeights|player.roleWeights]]. In general, the perception will be the same for all ships in a group. This can then be used with [[Oolite_JavaScript_Reference:_Ship#roleIsInCategory|Ship.roleIsInCategory]] to determine the appropriate response.

==== <code>respondToThargoids</code> ====
function '''respondToThargoids'''(whom : Ship, passon : Boolean) : Boolean
This function causes the ship (and if the <code>passon</code> parameter is set, its group members) to respond to the appearance of the Thargoid ship <code>whom</code>. It will return <code>true</code> if this ship responds, or <code>false</code> if not.

You must ensure that ships responding to a Thargoid as a result of a notification by a group member do not themselves set <code>passon</code> as this may cause an infinite loop.

==== <code>setWitchspaceRouteTo</code> ====
function '''setWitchspaceRouteTo'''(dest : Number)
This function sets the <code>oolite_witchspaceDestination</code> parameter according to the needs of reaching the system with the system ID equal to <code>dest</code>. As this function involves route planning, which is relatively slow, it should be called only rarely. This can then be used to determine whether to refuel or attempt to jump.

==== <code>shipHasRiskyContracts</code> ====
function '''shipHasRiskyContracts'''(ship : Ship) : Boolean
Sometimes returns <code>true</code> (non-deterministically) if the target ship is carrying contracts that someone might want assassinated or destroyed. The chance of returning <code>true</code> increases with the number of risky contracts carried. Currently this will always return <code>false</code> for a non-player ship: you can check these with the <code>oolite-courier</code> role category instead.

==== <code>shipInRoleCategory</code> ====
function '''shipInRoleCategory'''(ship : Ship, category : String) : Boolean
This is a wrapper around <code>Ship.roleIsInCategory</code> which accounts for the player's effective role not being the same as <code>player.ship.primaryRole</code>. You should generally call this instead of calling <code>Ship.roleIsInCategory</code> directly.

==== <code>stationAllegiance</code> ====
function '''stationAllegiance'''(station : Station) : String
Returns <code>station.allegiance</code> for the given station, but if this is null (as it will be for pre-1.79 stations), first sets it using a heuristic calculation.

==== <code>threatAssessment</code> ====
function '''threatAssessment'''(ship : Ship, full : Boolean) : Number
This is a wrapper around <code>[[#_threatAssessment|_threatAssessment]]</code> which is itself a wrapper around <code>[[Oolite_JavaScript_Reference:_Ship#threatAssessment|ship.threatAssessment()]]</code>. The combination of the two ensures that the assessment is correct for the relative combat states of this ship and the ship being assessed, as well as including effects of the player's reputation.

== Waypoint Generators ==

Waypoint generators are used to set patrol or other multipoint routes. When called, they should consider the ship's current position (and possibly other things), and then set the parameters "oolite_waypoint" and "oolite_waypointRange". These functions have no arguments and no return value.

In general, you should only call a waypoint generator if a waypoint is not already set.

==== <code>waypointsSpacelanePatrol</code> ====
function '''waypointsSpacelanePatrol'''()
If the ship is near the main planet, sun, or witchpoint, pick one of the other two points (biased towards the witchpoint-planet route) and set that as the waypoint. Otherwise, if the ship is on a lane already, pick one end of the lane at random. Otherwise, pick the planet.

Set a waypoint within 7500m of the witchpoint, 2 radii of the centre of the planet, or 2.5 radii of the centre of the sun.

==== <code>waypointsStationPatrol</code> ====
function '''waypointsStationPatrol'''()
If the ship has a station as its group leader, define waypoints from that station. Otherwise define them from the main station. If there is no main station either, set the witchpoint as the waypoint.

If there is a station, pick four points describing a square of diagonal length 50km centred on the station and lying in the station's xy plane. If the ship is not within 500 metres of any of these points, select one of the points as the waypoint. Otherwise, select the next point around the list as the waypoint.

==== <code>waypointsWitchpointPatrol</code> ====
function '''waypointsWitchpointPatrol'''()

Pick four points describing a square of diagonal length 30km centred on the witchpoint and lying approximately in the system's xy plane. If the ship is not within 500 metres of any of these points, select one of the points as the waypoint. Otherwise, select the next point around the list as the waypoint.

== Global Configuration ==
All PriorityAIControllers share a single communications message library. This library may be edited using functions in the priority AI worldscript

=== Usage ===

When a key is asked for, the communications library will be checked in the following order:
# for a key with the specified role and personality
# if the role does not start with "_", a key with the specified personality and the role "generic"
# if the personality does not start with "_", a key with the specified role and the personality "generic"
# if neither role nor personality start with "_", a key with "generic" role and personality.
In general, setting keys for the generic role (and especially with a generic personality as well) should be used with caution.

The key's value is then expanded using expandDescription (possibly with added parameters), so entries in [[descriptions.plist]] may be used to add variety to the communications. Alternatively, a static text string also works as the value.

==== Standard Communications Keys ====

The following communications keys are currently defined in standard Oolite, but you can define more. Those with a parameter of Ship can have a Ship object passed to them, which will be replaced with definitions for the parameters "oolite_entityClass", "oolite_entityCrew" and "oolite_entityName".

===== oolite_agreeingToDumpCargo =====
Parameter: "oolite_demandSize" (size of demand in TC)
Priority: 1
Used when a ship dumps cargo to satisfy a pirate demand

===== oolite_attackLowEnergy =====
Parameter: Ship,
Priority: 2
Used when requesting help as under attack and close to death

===== oolite_beginningAssassination =====
Parameter: Ship, plus "oolite_entityContracts" parameter
Priority: 3
Used when commencing a fight with the Ship defined in the parameter, like [[#oolite_beginningFight|oolite_beginningFight]], but specifically for an assassination target. The extra communications parameter contains the name of a passenger (or parcel owner) relevant to this ship (for the player, this may intentionally be someone for whom delivery has been completed - either it's a revenge hit, or they're just working from outdated intelligence)

===== oolite_beginningAttack =====
Parameter: Ship
Priority: 3
Used when commencing an attack on the Ship defined in the parameter.

===== oolite_beginningAttackInanimate =====
Parameter: Ship
Priority: 3
Used when commencing an attack on the Ship (expected to be an uncrewed object like an asteroid, cargo pod, etc.) defined in the parameter.

===== oolite_beginningAttackThargoid =====
Parameter: Ship
Priority: 3
Used when commencing an attack on the Ship (expected to be a Thargoid ship) defined in the parameter.

===== oolite_beginningFight =====
Parameter: Ship
Priority: 3
Used when commencing a fight with the Ship defined in the parameter. (Beginning Attack means attacking a target previously not under attack but which there may have been a reason to fight from previous combats; Beginning Fight is stronger - this ship is initiating hostilities)

===== oolite_continueFleeing =====
Parameter: Ship
Priority: 4
Used when the ship has been unable to reach safety from its attacker.

===== oolite_continuingAttack =====
Parameter: Ship
Priority: 4
Used when continuing an attack on the Ship defined in the parameter (the low priority means this is relatively rarely used, of course)

===== oolite_continuingAttackInanimate =====
Parameter: Ship
Priority: 4
Used when continuing an attack on the Ship (if likely to be uncrewed) defined in the parameter (the low priority means this is relatively rarely used, of course)

===== oolite_continuingAttackThargoid =====
Parameter: Ship
Priority: 4
Used when continuing an attack on the Ship (if Thargoid) defined in the parameter (the low priority means this is relatively rarely used, of course)

===== oolite_distressResponseAggressor =====
Parameter: Ship
Priority: 2
Used to threaten the ship a distress call has been sent about.

===== oolite_distressResponseSender =====
Parameter: Ship
Priority: 2 or 3
Used to reassure a ship sending a distress call that help is on the way. [[#oolite_distressResponseAggressor|oolite_distressResponseAggressor]] is preferred - this will only be used if the ship sending the message is near the sender but not the aggressor.

===== oolite_dockingWait =====
Parameter: none
Priority: 4
Used when a ship is waiting in a docking queue.

===== oolite_eject =====
Parameter: none
Priority: 1
Used when a ship launches an escape pod (the communication comes from the ship, not the pod, as the pod is being launched)

===== oolite_engageWitchspaceDrive =====
Parameter: none
Priority: 4
Used when a lone ship is beginning its witchspace entry sequence, and is expected to enter witchspace in around 15 seconds.

===== oolite_engageWitchspaceDriveFlee =====
Parameter: none
Priority: 2
Used when a ship is preparing to escape from a fight by making a witchspace jump

===== oolite_engageWitchspaceDriveGroup =====
Parameter: none
Priority: 4
Used when a grouped ship is beginning its witchspace entry sequence, and is expected to enter witchspace in around 15 seconds.

===== oolite_escortAccepted =====
Parameter: Ship
Priority: 2
Used when a ship accepts a new escort. The new escort will be passed as the parameter.

===== oolite_escortFormation =====
Parameter: Ship
Priority: 4
Used when a ship is entering or maintaining escort formation. The mothership will be passed as the parameter.

===== oolite_escortMotherAccepted =====
Parameter: Ship
Priority: 2
Used when a ship is accepted as a new escort. The ship being escorted will be passed as the parameter.

===== oolite_firedMissile =====
Parameter: Ship
Priority: 4
Used when firing a missile. The target of the missile will be passed as the parameter.

===== oolite_friendlyFire =====
Parameter: Ship
Priority: 2, 3 or 4 depending on circumstances
Used when a ship is hit by weapons fire from another ship it considers "on its side" either because of common group or because of similar roles.

===== oolite_groupIsOutnumbered =====
Parameter: none
Priority: 2 if group leader, 4 otherwise
Used when a ship realises it is in a fight with a group which seriously outclasses it, and therefore should flee.

===== oolite_hitTarget =====
Parameter: Ship
Priority: 4
Used when the ship hits its target. The target is passed as the parameter.

===== oolite_incomingMissile =====
Parameter: Ship
Priority: 3
Used when the ship has had a missile launched at it and is unable to use ECM. The missile is passed as the parameter.

===== oolite_killedAlly =====
Parameter: Ship
Priority: 3
Used when the ship destroys an allied ship. The target is passed as the parameter.

===== oolite_killedTarget =====
Parameter: Ship
Priority: 2 (3 for stations)
Used when the ship destroys its current target. The target is passed as the parameter.

===== oolite_killedNonTarget =====
Parameter: Ship
Priority: 3
Used when the ship destroys something other than its current target. The target is passed as the parameter.

===== oolite_killedUncrewedTarget =====
Parameter: Ship
Priority: 3 (4 for stations)
Used when the ship destroys an uncrewed object which is its current target. The target is passed as the parameter.

===== oolite_killedUncrewedNonTarget =====
Parameter: Ship
Priority: 3 (4 for stations)
Used when the ship destroys an uncrewed object other than its current target. The target is passed as the parameter.

===== oolite_landingOnPlanet =====
Parameter: none
Priority: 4
Used when beginning final landing approach to a planet.

===== oolite_launchDefenseShips, oolite_launchMiner, oolite_launchPatrol, oolite_launchSalvager =====
Parameter: Ship
Priority: 3
Used when a station launches a ship of a particular type. The parameter is the station's current target.

===== oolite_leaveVicinity =====
Parameter: Ship
Priority: 3
Used when a ship is executing [[#behaviourLeaveVicinityOfDestination|behaviourLeaveVicinityOfDestination]]. The parameter is the current target.

===== oolite_makeDistressCall =====
Parameter: Ship
Priority: 2
Used as the message when a distress call is sent. The parameter is the ship's primary aggressor.

===== oolite_makePirateDemand =====
Parameter: Ship and "oolite_demandSize"
Priority: 1
Used when making a piracy demand on a ship. The Ship parameters are from the ship being robbed.

===== oolite_markForFines =====
Parameter: Ship
Priority: 1
Used when a police ship is marking another ship for fines on docking. The parameter is the ship being marked.

===== oolite_mining =====
Parameter: none
Priority: 4
Used when carrying out mining activity

===== oolite_newAssailiant =====
Parameter: Ship
Priority: 3
Used when the ship is attacked by someone not previously considered hostile. The attacker is the parameter.

===== oolite_offenceDetected =====
Parameter: Ship
Priority: 3 if this increases the aggressor's bounty, 4 otherwise
Used when a police ship detects illegal hostilities. The parameter is the aggressor.

===== oolite_patrolReportIn =====
Parameter: Ship
Priority: 4
Used when a station patrol ship reaches a waypoint. The parameter is its parent station.

===== oolite_quiriumCascade =====
Parameter: none
Priority: 3
Used when a quirium cascade or an imminent cascade is detected.

===== oolite_scoopedCargo =====
Parameter: "oolite_goodsDescription" is a description of the cargo commodity
Priority: 4
Used when this ship scoops cargo.

===== oolite_selectedStation =====
Parameter: Ship
Priority: 4
Used when a ship selects a station to navigate to (e.g. traders, shuttles). The parameter is the selected station.

===== oolite_selectedWitchspaceDestination =====
Parameter: "oolite_witchspaceDestination" is the name of the destination system
Priority: 4
Used when a ship selects its witchspace destination.

===== oolite_startFleeing =====
Parameter: Ship
Priority: 3
Used when a ship begins fleeing combat, with the parameter being the ship's current target.

===== oolite_startHelping =====
Parameter: Ship
Priority: 4
Used when a ship responds to a request for help from another grouped ship by changing its target. The parameter is the new target.

===== oolite_surrender =====
Parameter: none
Priority: 3
Messages sent by fleeing ships still being fired upon, in attempt to beg for mercy. [[#oolite_agreeingToDumpCargo|oolite_agreeingToDumpCargo]] is used instead in the one case in the core game where an attacker might accept a surrender (as opposed to breaking off an attack on a fleeing ship to attack a non-fleeing one)

===== oolite_thanksForHelp =====
Parameter: Ship
Priority: 1 if thanking the player, 3 otherwise
This message is sent if an attack on this ship's aggressor causes it to break off its own attack. The parameter is the ship helping out.

===== oolite_thargoidAttack =====
Parameter: Ship
Priority: 2
This message is sent if the ship is attacked by a Thargoid ship while not previously fighting Thargoids. The parameter is the Thargoid ship. This is generally accompanied by a quick cessation of hostilities between Cooperative vessels for a short-term truce against the invaders.

===== oolite_waypointReached =====
Parameter: none
Priority: 3
This message is sent when a ship reaches a waypoint set with the waypoint generator function.

===== oolite_witchspaceBlocked =====
Parameter: Ship
Priority: 3
This message is sent when a large nearby mass (usually a station or asteroid) prevents witchspace entry. The parameter is the blocking mass.

==== Standard Communications Roles ====

The following communications roles are used by the standard Oolite AIs. Some of the roles have fallback roles used by the standard AIs, noted below. If the fallback role does not exist, or is not specified, it will fall back to using "generic" as usual.

Note that OXP AIs might not specify the same fallback roles. OXP AIs wishing to can use code like

if (worldScripts["oolite-libPriorityAI"]._getCommunicationPersonalities("hermit").length > 0)
{
ai.setCommunicationsRole("hermit");
}
else
{
ai.setCommunicationsRole("station");
}

* '''assassin''' - assassins
* '''defenseShip''' - defense ships
* '''escapepod''' - escape pods
* '''escort''' - escorts
* '''hermit''' - rock hermits. If no personalities are defined for this role, "station" will be used instead.
* '''hunter''' - bounty hunters
* '''pirate''' - pirates
* '''pirate-aegis-raider''' - pirates showing off by attacking the main station. If no personalities are defined for this role, "pirate" will be used instead.
* '''pirate-freighter''' - pirate freighters leading a pack. If no personalities are defined for this role, "pirate" will be used instead.
* '''pirate-interceptor''' - pirates assigned to distract police and hunters. If no personalities are defined for this role, "pirate" will be used instead.
* '''police''' - police ships
* '''scavenger''' - scavengers and miners.
* '''shuttle''' - orbital shuttles (usually unarmed)
* '''station''' - stations.
* '''trader''' - traders
* '''trader-courier''' - couriers. If no personalities are defined for this role, "trader" will be used instead.
* '''trader-opportunist''' - opportunistic traders. If no personalities are defined for this role, "trader" will be used instead.
* '''trader-smuggler''' - smugglers. If no personalities are defined for this role, "trader" will be used instead.

Thargoids are set slightly differently: all the core game ones get the "_thargoid" role, with the warships getting the "thargoid" personality, and the drones getting the "tharglet" personality, even if those personalities are not otherwise defined. Note that the underscore in the role prevents fallback to "generic" messages here.

=== Methods ===

==== _getCommunication ====
function '''_getCommunication'''(role : String, personality : String, key : String) : StringOrFunction
This function returns either a string suitable for passing to <code>expandDescription</code> containing the communications for the specified key, or a function called with key and parameters returning a communications string, if a ship of the specified role and personality is speaking.

==== _getCommunicationPersonalities ====
function '''_getCommunicationPersonalities'''(role : String) : Array
Returns the personalities which have at least one communication key defined for the given role.

==== _setCommunication ====
function '''_setCommunication'''(role : String, personality : String, key : String, value : StringOrFunction)
This function sets the communications values returned by [[#_getCommunication|getCommunication]]. The value may either be:
* a String, which will be passed to expandDescription
* a Function, which will be called with two parameters: the key, and the parameters object.

For example
worldScripts["oolite-libPriorityAI"]._setCommunication("myoxp_role","generic",
"oolite_continuingAttack","[myoxp_role_continuesAttack]");
worldScripts["oolite-libPriorityAI"]._setCommunication("myoxp_role","generic",
"oolite_continuingAttack",function(k,p) { return "Targeting the "+p.oolite_entityName+". Cover me."; });

==== _setCommunications ====
function '''_setCommunications'''(comms : Object)
This function can be used to set multiple communications keys at once. The format of the object is
comms[role][personality][key] = value;

[[Category:Oolite JavaScript Reference]]

User talk:Phasted

2014-07-31T10:01:29Z

Phasted: /* Real-Life Economics */

== Real-Life Economics ==

Hi, you created the article [[Real-Life Economics]], but removed its content later on. Why? Greetings: [[User:Makarius|Makarius]] 07:59, 14 July 2014 (BST)

I just decided it would be easier to write it as a text file and cut-and-paste it into place later...

2014-07-06T05:16:21Z

Phasted:

Real-Life Economics

2014-07-06T05:15:42Z

Phasted:

{{Infobox OXPb| title = Real-Life Economics
|image = [[Image:OreProcessorSplinter.png|right|thumb|300px|A field of splinters to be extracted]]
|equipName = Ore Processor
|equipCost = 3500
|equipTL = 12
}}
===Overview===

For me, one of the least satisfying elements of this game (going all the way back to the good ol' days playing Elite on my ancient Commodore 128) has always been the extremely unrealistic economics model.

In Elite, this behavior is hard-coded into the game; beyond the reach of all but Mr. Bell and Mr. Braben. Oolite, thanks to Mr. Williams and Mr. Ayton (among others)

===The Lazy-Trader Shuffle===

"How brilliant of me to notice that! I must be some kind of a genius! I'll just find a Rich Industrial/Poor Agricultural pair -- reasonably close to one another -- and make a killing hauling Computers one way and Liquor/Wines back... it's idiot-proof!"

2014-07-06T04:47:36Z

Phasted: /* Overview */

Real-Life Economics

2014-07-06T04:45:41Z

Phasted: /* Overview */

Real-Life Economics

2014-07-06T04:44:56Z

Phasted: /* Overview */

===Overview===

For me, one of the least satisfying elements of this game (going all the way back to the good ol' days playing Elite on my ancient Commodore 128) was the extremely unrealistic economics model.

Real-Life Economics

2014-07-06T04:40:37Z

Phasted: Created page with "===Overview==="

===Overview===