Difference between revisions of "Oolite Javascript Reference: PriorityAI Documentation"
m (→Usage: beginningFight comms message) |
(→Constructor: typo fix) |
||
Line 9: | Line 9: | ||
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. | 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[ | + | var ai = new worldScripts["oolite-libPriorityAI"].PriorityAIController(this.ship); |
=== Properties === | === Properties === |
Revision as of 20:13, 16 April 2014
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 the priority AI tutorial to be more useful as an introduction.
Priority-based Javascript AI is available from Oolite 1.79 onwards.
Contents
- 1 Constructor and general functions
- 2 Writing a priority list
- 3 Behaviour functions
- 3.1 General behaviours
- 3.1.1 behaviourApproachDestination
- 3.1.2 behaviourAvoidCascadeExplosion
- 3.1.3 behaviourBecomeInactiveThargon
- 3.1.4 behaviourCollectSalvage
- 3.1.5 behaviourCommenceAttackOnCurrentTarget
- 3.1.6 behaviourDestroyCurrentTarget
- 3.1.7 behaviourDockWithStation
- 3.1.8 behaviourEnterWitchspace
- 3.1.9 behaviourEscortMothership
- 3.1.10 behaviourFineCurrentTarget
- 3.1.11 behaviourFleeCombat
- 3.1.12 behaviourFollowCurrentTarget
- 3.1.13 behaviourFollowGroupLeader
- 3.1.14 behaviourGuardTarget
- 3.1.15 behaviourJoinTargetGroup
- 3.1.16 behaviourLandOnPlanet
- 3.1.17 behaviourLeaveVicinityOfDestination
- 3.1.18 behaviourLeaveVicinityOfTarget
- 3.1.19 behaviourMineTarget
- 3.1.20 behaviourOfferToEscort
- 3.1.21 behaviourPayOffPirates
- 3.1.22 behaviourReconsider
- 3.1.23 behaviourRejoinMothership
- 3.1.24 behaviourRepelCurrentTarget
- 3.1.25 behaviourRespondToDistressCall
- 3.1.26 behaviourRobTarget
- 3.1.27 behaviourSunskim
- 3.1.28 behaviourTumble
- 3.2 Missile behaviours
- 3.3 Station behaviours
- 3.1 General behaviours
- 4 Condition functions
- 4.1 Combat conditions
- 4.1.1 conditionCascadeDetected
- 4.1.2 conditionCombatOdds*
- 4.1.3 conditionGroupAttritionReached
- 4.1.4 conditionGroupSuppliesLow
- 4.1.5 conditionInCombat
- 4.1.6 conditionInCombatWithHostiles
- 4.1.7 conditionLosingCombat
- 4.1.8 conditionMothershipInCombat
- 4.1.9 conditionMothershipIsAttacking
- 4.1.10 conditionMothershipIsAttackingHostileTarget
- 4.1.11 conditionMothershipUnderAttack
- 4.1.12 conditionSuppliesLow
- 4.2 Navigation conditions
- 4.2.1 conditionCanWitchspaceOnRoute
- 4.2.2 conditionCanWitchspaceOut
- 4.2.3 conditionFriendlyStationExists
- 4.2.4 conditionFriendlyStationNearby
- 4.2.5 conditionGroupIsSeparated
- 4.2.6 conditionHasSelectedPlanet
- 4.2.7 conditionHasSelectedStation
- 4.2.8 conditionHomeStationExists
- 4.2.9 conditionHomeStationNearby
- 4.2.10 conditionHostileStationNearby
- 4.2.11 conditionInInterstellarSpace
- 4.2.12 conditionMainPlanetNearby
- 4.2.13 conditionNearDestination
- 4.2.14 conditionPlayerNearby
- 4.2.15 conditionReadyToSunskim
- 4.2.16 conditionSelectedStationNearby
- 4.2.17 conditionSelectedStationNearMainPlanet
- 4.2.18 conditionStationNearby
- 4.2.19 conditionSunskimPossible
- 4.2.20 conditionWormholeNearby
- 4.3 Piracy-related conditions
- 4.4 Scanning conditions
- 4.4.1 conditionScannerContainsAssassinationTarget
- 4.4.2 conditionScannerContainsCleanShip
- 4.4.3 conditionScannerContainsCourier
- 4.4.4 conditionScannerContainsEscapePods
- 4.4.5 conditionScannerContainsFineableOffender
- 4.4.6 conditionScannerContainsFugitive
- 4.4.7 conditionScannerContainsHuntableOffender
- 4.4.8 conditionScannerContainsSeriousOffender
- 4.4.9 conditionScannerContainsHunters
- 4.4.10 conditionScannerContainsLoneVictim
- 4.4.11 conditionScannerContainsMiningOpportunity
- 4.4.12 conditionScannerContainsNonThargoid
- 4.4.13 conditionScannerContainsPirateLeader
- 4.4.14 conditionScannerContainsPirateVictims
- 4.4.15 conditionScannerContainsReadyThargoidMothership
- 4.4.16 conditionScannerContainsRocks
- 4.4.17 conditionScannerContainsSalvage
- 4.4.18 conditionScannerContainsSalvageForGroup
- 4.4.19 conditionScannerContainsSalvageForMe
- 4.4.20 conditionScannerContainsShipNeedingEscort
- 4.4.21 conditionScannerContainsSuspiciousShip
- 4.4.22 conditionScannerContainsThargoidMothership
- 4.4.23 conditionScannerContainsUnspreadMissile
- 4.5 State querying conditions
- 4.5.1 conditionAllEscortsInFlight
- 4.5.2 conditionCanScoopCargo
- 4.5.3 conditionCargoIsProfitableHere
- 4.5.4 conditionCoinFlip
- 4.5.5 conditionGroupLeaderIsStation
- 4.5.6 conditionHasInterceptCoordinates
- 4.5.7 conditionHasMothership
- 4.5.8 conditionHasNonThargoidTarget
- 4.5.9 conditionHasReceivedDistressCall
- 4.5.10 conditionHasRememberedTarget
- 4.5.11 conditionHasTarget
- 4.5.12 conditionHasWaypoint
- 4.5.13 conditionIsActiveThargon
- 4.5.14 conditionIsEscorting
- 4.5.15 conditionIsGroupLeader
- 4.5.16 conditionMissileOutOfFuel
- 4.5.17 conditionPatrolIsOver
- 4.5.18 conditionWitchspaceEntryRequested
- 4.1 Combat conditions
- 5 Configuration functions
- 5.1 Destination configurations
- 5.1.1 configurationMissileAdjustSpread
- 5.1.2 configurationSetDestinationToHomeStation
- 5.1.3 configurationSetDestinationToGroupLeader
- 5.1.4 configurationSetDestinationToMainPlanet
- 5.1.5 configurationSetDestinationToMainStation
- 5.1.6 configurationSetDestinationToNearestHostileStation
- 5.1.7 configurationSetDestinationToNearestFriendlyStation
- 5.1.8 configurationSetDestinationToNearestStation
- 5.1.9 configurationSetDestinationToNearestWormhole
- 5.1.10 configurationSetDestinationToPirateLurk
- 5.1.11 configurationSetDestinationToScannedTarget
- 5.1.12 configurationSetDestinationToSelectedPlanet
- 5.1.13 configurationSetDestinationToSelectedStation
- 5.1.14 configurationSetDestinationToSunskimEnd
- 5.1.15 configurationSetDestinationToSunskimStart
- 5.1.16 configurationSetDestinationToWaypoint
- 5.1.17 configurationSetDestinationToWitchpoint
- 5.1.18 configurationSetWaypoint
- 5.2 Docking configurations
- 5.3 Miscellaneous configurations
- 5.4 Navigation configurations
- 5.5 Station configurations
- 5.6 Target acquisition configurations
- 5.1 Destination configurations
- 6 Response definition functions and components
- 7 Template functions
- 8 Utility functions
- 8.1 allied
- 8.2 broadcastDistressMessage
- 8.3 checkScannerWithPredicate
- 8.4 cruiseSpeed
- 8.5 distance
- 8.6 entityCommsParams
- 8.7 fineThreshold
- 8.8 friendlyStation
- 8.9 homeStation
- 8.10 ignorePlayerFriendlyFire
- 8.11 isAggressive
- 8.12 isEscaping
- 8.13 isFighting
- 8.14 noteDistraction
- 8.15 oddsAssessment
- 8.16 playerRoleAssessment
- 8.17 respondToThargoids
- 8.18 setWitchspaceRouteTo
- 8.19 shipHasRiskyContracts
- 8.20 shipInRoleCategory
- 8.21 stationAllegiance
- 8.22 threatAssessment
- 9 Waypoint Generators
- 10 Global Configuration
- 10.1 Usage
- 10.1.1 oolite_agreeingToDumpCargo
- 10.1.2 oolite_attackLowEnergy
- 10.1.3 oolite_beginningAttack
- 10.1.4 oolite_beginningAttackInanimate
- 10.1.5 oolite_beginningAttackThargoid
- 10.1.6 oolite_beginningFight
- 10.1.7 oolite_continueFleeing
- 10.1.8 oolite_continuingAttack
- 10.1.9 oolite_continuingAttackInanimate
- 10.1.10 oolite_continuingAttackThargoid
- 10.1.11 oolite_distressResponseAggressor
- 10.1.12 oolite_distressResponseSender
- 10.1.13 oolite_dockingWait
- 10.1.14 oolite_eject
- 10.1.15 oolite_engageWitchspaceDrive
- 10.1.16 oolite_escortAccepted
- 10.1.17 oolite_escortFormation
- 10.1.18 oolite_escortMotherAccepted
- 10.1.19 oolite_firedMissile
- 10.1.20 oolite_friendlyFire
- 10.1.21 oolite_groupIsOutnumbered
- 10.1.22 oolite_hitTarget
- 10.1.23 oolite_incomingMissile
- 10.1.24 oolite_killedAlly
- 10.1.25 oolite_killedTarget
- 10.1.26 oolite_killedNonTarget
- 10.1.27 oolite_killedUncrewedTarget
- 10.1.28 oolite_killedUncrewedNonTarget
- 10.1.29 oolite_landingOnPlanet
- 10.1.30 oolite_launchDefenseShips, oolite_launchMiner, oolite_launchPatrol, oolite_launchSalvager
- 10.1.31 oolite_leaveVicinity
- 10.1.32 oolite_makeDistressCall
- 10.1.33 oolite_makePirateDemand
- 10.1.34 oolite_markForFines
- 10.1.35 oolite_mining
- 10.1.36 oolite_newAssailiant
- 10.1.37 oolite_offenceDetected
- 10.1.38 oolite_patrolReportIn
- 10.1.39 oolite_quiriumCascade
- 10.1.40 oolite_scoopedCargo
- 10.1.41 oolite_selectedStation
- 10.1.42 oolite_selectedWitchspaceDestination
- 10.1.43 oolite_startFleeing
- 10.1.44 oolite_startHelping
- 10.1.45 oolite_surrender
- 10.1.46 oolite_thanksForHelp
- 10.1.47 oolite_thargoidAttack
- 10.1.48 oolite_waypointReached
- 10.1.49 oolite_witchspaceBlocked
- 10.2 Methods
- 10.1 Usage
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
ship
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.
applyHandlers
function applyHandlers(handlers : Object)
Deletes any existing event handlers applied to the ship's AI Script by a previous invocation of applyHandlers
, and copies the handlers in the argument object to the AI Script. All handlers applied this way run with 'this
' equal to the PriorityAIController, not to the AI Script.
clearHandlers
function clearHandlers(handlers : Object)
Deletes any existing event handlers applied to the ship's AI Script by a previous invocation of applyHandlers
.
communicate
function communicate(key : String, params : Object, priority : Number)
If the communication "key" has previously been defined for this ship's communications role and personality, retrieves it, calls expandDescription
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:
oolite_entityClass
=ship.shipClassName
oolite_entityName
=ship.shipUniqueName
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.
getParameter
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.
getWaypointGenerator
function getWaypointGenerator() : Function
If a waypoint generation function has previously been set, return it.
noteCommsHeard
function noteCommsHeard()
This function is used to reset the timers for priority 3 and 4 communications. The standard event handlers will call this for you, but you may need to call it manually otherwise.
reconsiderIn
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. delay
must be at least 0.1 seconds.
reconsiderNow
function reconsiderNow()
Force a reconsideration of the AI's priority list ahead of schedule.
setCommunicationsRole
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.
setCommunicationsPersonality
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.
setParameter
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 section below for parameter keys used by the core AIs and the standard priority AI library.
setPriorities
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.
setWaypointGenerator
function setWaypointGenerator(generator : Function)
Sets the AI's Waypoint Generators waypoint generator function.
Parameters
The following parameters are used by the standard library and accessed using getParameter and 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_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_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 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 'this
' variable when one of these functions is run therefore points to the priority AI, not to the AI Script.
Note that this.ship
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 this.ship.AIScript.property
. Properties and methods of the priority AI may be accessed directly, e.g. this.allied(this.ship,this.ship.target)
.
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 responsesAddStandard
, and occasionally add others.
behaviourApproachDestination
function behaviourApproachDestination()
Travels from the current position to within desiredRange
of destination
, 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.
behaviourAvoidCascadeExplosion
function behaviourAvoidCascadeExplosion()
Fly, using injectors if available, to a safe distance from any nearby quirium cascades (or active mines)
behaviourBecomeInactiveThargon
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.
behaviourCollectSalvage
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.
behaviourCommenceAttackOnCurrentTarget
function behaviourCommenceAttackOnCurrentTarget()
This behaviour attacks the current target, only stopping when interrupted or when the target is destroyed. Unlike the behaviourDestroyCurrentTarget
behaviour, it may first send the "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.
behaviourDestroyCurrentTarget
function behaviourDestroyCurrentTarget()
This behaviour attacks the current target, only stopping when interrupted or when the target is destroyed.
behaviourDockWithStation
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.
behaviourEnterWitchspace
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.
behaviourEscortMothership
function behaviourEscortMothership()
This behaviour performs non-combat escorting of the ship's group leader, in the formation requested by the lead ship.
behaviourFineCurrentTarget
function behaviourFineCurrentTarget()
If the ship has scan class "CLASS_POLICE" and a current target, mark that target for fines when it next docks.
behaviourFleeCombat
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
behaviourFollowCurrentTarget
function behaviourFollowCurrentTarget()
The ship will follow the current target, including through a witchspace jump if necessary, and will additionally remember the target.
behaviourFollowGroupLeader
function behaviourFollowGroupLeader()
The ship will follow the group leader if there is one, attempting to remain within a few kilometres of it.
behaviourGuardTarget
function behaviourGuardTarget()
The ship will fly to within a few kilometres of its current target. Similar to behaviourFollowCurrentTarget
but will not follow the target into witchspace and will not remember that it was doing so if distracted.
behaviourJoinTargetGroup
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.
behaviourLandOnPlanet
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.
behaviourLeaveVicinityOfDestination
function behaviourLeaveVicinityOfDestination()
Moves outside scanner range of the current destination coordinates.
behaviourLeaveVicinityOfTarget
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.
behaviourMineTarget
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.
behaviourOfferToEscort
function behaviourOfferToEscort()
Offers to escort the ship identified by the parameter "oolite_scanResultSpecific". Unless this parameter has been set by the scanner condition conditionScannerContainsShipNeedingEscort this is extremely likely to fail.
To be accepted as an escort, the ship must have a primary role in the oolite-escorts
role category.
behaviourPayOffPirates
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
behaviourReconsider
function behaviourReconsider()
Does nothing except schedule a re-evaluation of the priority list.
behaviourRejoinMothership
function behaviourRejoinMothership()
This behaviour flies to rejoin the mothership, and then escorts it as in behaviourEscortMothership.
behaviourRepelCurrentTarget
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.
behaviourRespondToDistressCall
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.
behaviourRobTarget
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.
behaviourSunskim
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), and configurationSetDestinationToSunskimEnd should be used to set a safe sunskimming direction.
behaviourTumble
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 responsesAddMissile
. More discussion of setting missile parameters, ECM response, and detonation can be found there.
behaviourMissileInterceptCoordinates
function behaviourMissileInterceptCoordinates()
Close to the desired missile range (default 25m, or specified by the oolite_missile_proximity
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.
behaviourMissileInterceptTarget
function behaviourMissileInterceptTarget()
Close to the desired missile range (default 25m, or specified by the oolite_missile_proximity
key in script info), detonating when reached.
behaviourMissileSelfDestruct
function behaviourMissileSelfDestruct()
Destroys the missile without detonating the payload.
Station behaviours
Station behaviours use responsesAddStation
to set up their general handlers, as most standard behaviours are unnecessary or unhelpful for a stationary station.
behaviourStationLaunchDefenseShips
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.
behaviourStationLaunchMiner
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.
behaviourStationLaunchPatrol
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.
behaviourStationLaunchSalvager
function behaviourStationLaunchMiner()
Launches a salvager. Also reduces the alert condition by one step.
behaviourStationManageTraffic
function behaviourStationManageTraffic()
The station idles. If the system repopulator has requested launches that this station can fulfil, it may launch a ship.
behaviourStationRespondToDistressCall
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.
conditionCascadeDetected
function conditionCascadeDetected() : Boolean
Returns true if a cascade explosion has been detected recently (as given by the parameter "oolite_cascadeDetected" containing the explosion coordinates).
conditionCombatOdds*
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.
conditionGroupAttritionReached
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.
conditionGroupSuppliesLow
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.
conditionInCombat
function conditionInCombat() : Boolean
The ship is currently attacking other ships, or a ship in its group or one of its escorts is.
conditionInCombatWithHostiles
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)
conditionLosingCombat
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.
conditionMothershipInCombat
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.
conditionMothershipIsAttacking
function conditionMothershipIsAttacking() : Boolean
This ship's group leader is attacking a target. This ship must be able to see its leader's target.
conditionMothershipIsAttackingHostileTarget
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.
conditionMothershipUnderAttack
function conditionMothershipUnderAttack() : Boolean
This ship's group leader is currently being targeted. This ship must be able to see the attacker.
conditionSuppliesLow
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 ship.damageAssessment()
.
Conditions related to the ship's surroundings and navigation through the system.
conditionCanWitchspaceOnRoute
function conditionCanWitchspaceOnRoute() : Boolean
The ship has a witchspace drive, a witchspace route, and the next system on its route is within range with the current fuel supply.
conditionCanWitchspaceOut
function conditionCanWitchspaceOut() : Boolean
The ship has a witchspace drive, and at least one other system is within range with the current fuel supply.
conditionFriendlyStationExists
function conditionFriendlyStationExists() : Boolean
There is at least one friendly station in the system.
conditionFriendlyStationNearby
function conditionFriendlyStationNearby() : Boolean
There is at least one friendly station within scanner range
conditionGroupIsSeparated
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)
conditionHasSelectedPlanet
function conditionHasSelectedPlanet() : Boolean
The ship has a valid planet in the "oolite_selectedPlanet" parameter.
conditionHasSelectedStation
function conditionHasSelectedStation() : Boolean
The ship has a valid planet in the "oolite_selectedStation" parameter.
conditionHomeStationExists
function conditionHomeStationExists() : Boolean
The ship's home station still exists
conditionHomeStationNearby
function conditionHomeStationNearby() : Boolean
The ship's home station is within scanner range.
conditionHostileStationNearby
function conditionHostileStationNearby() : Boolean
There is at least one hostile station within scanner range
conditionInInterstellarSpace
function conditionInInterstellarSpace() : Boolean
The ship is currently in interstellar space.
conditionMainPlanetNearby
function conditionMainPlanetNearby() : Boolean
The ship is within 3 radii of the surface of the main planet
conditionNearDestination
function conditionNearDestination() : Boolean
The ship is closer than the desired range to its destination
conditionPlayerNearby
function conditionPlayerNearby() : Boolean
The player's ship is within scanner range.
conditionReadyToSunskim
function conditionReadyToSunskim() : Boolean
The ship is close enough to the sun to scoop fuel.
conditionSelectedStationNearby
function conditionSelectedStationNearby() : Boolean
The ship has a selected station in the "oolite_selectedStation" parameter, and it is within scanner range.
conditionSelectedStationNearMainPlanet
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.
conditionStationNearby
function conditionStationNearby() : Boolean
There is a station within scanner range.
conditionSunskimPossible
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.
conditionWormholeNearby
function conditionWormholeNearby() : Boolean
There is an entry wormhole within scanner range.
Conditions involved in piratical activities.
conditionCargoDemandsMet
function conditionCargoDemandsMet() : Boolean
Since this ship (or an ally) made a cargo demand, this ship has seen enough cargo dropped to meet that demand.
conditionGroupHasEnoughLoot
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.
conditionPiratesCanBePaidOff
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) 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.
conditionScannerContainsAssassinationTarget
function conditionScannerContainsAssassinationTarget() : Boolean
The scan contains an assassination target (i.e. an escape capsule)
conditionScannerContainsCleanShip
function conditionScannerContainsCleanShip() : Boolean
The scan contains a clean ship
conditionScannerContainsCourier
function conditionScannerContainsCourier() : Boolean
The scan contains a courier ship
conditionScannerContainsEscapePods
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.
conditionScannerContainsFineableOffender
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.
conditionScannerContainsFugitive
function conditionScannerContainsFugitive() : Boolean
The scan contains a fugitive ship
conditionScannerContainsHuntableOffender
function conditionScannerContainsHuntableOffender() : Boolean
The scan contains a piloted ship with an offender legal status not too small to bother with (varies with government).
conditionScannerContainsSeriousOffender
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).
conditionScannerContainsHunters
function conditionScannerContainsHunters() : Boolean
The scan contains a ship with role "hunter", or a police ship, or the main station.
conditionScannerContainsLoneVictim
function conditionScannerContainsLoneVictim() : Boolean
The scan contains a single pirate victim and no other unallied ships.
conditionScannerContainsMiningOpportunity
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.
conditionScannerContainsNonThargoid
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.
conditionScannerContainsPirateLeader
function conditionScannerContainsPirateLeader() : Boolean
The scan contains a pirate leader (usually a heavily-armed freighter)
conditionScannerContainsPirateVictims
function conditionScannerContainsPirateVictims() : Boolean
The scan contains a pirate victim (as defined by role-categories.plist
) which is carrying at least some cargo and has not recently been robbed.
conditionScannerContainsReadyThargoidMothership
function conditionScannerContainsReadyThargoidMothership() : Boolean
The scan contains a thargoid mothership which has the capability to control at least one more thargon.
conditionScannerContainsRocks
function conditionScannerContainsRocks() : Boolean
The scan contains boulders (preferentially) or asteroids.
conditionScannerContainsSalvage
function conditionScannerContainsSalvage() : Boolean
The scan contains cargo which could in theory be scooped.
conditionScannerContainsSalvageForGroup
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..
conditionScannerContainsSalvageForMe
function conditionScannerContainsSalvageForMe() : Boolean
The scan contains cargo which can be scooped by this ship (travelling slowly enough, and this ship has scoops and space)
conditionScannerContainsShipNeedingEscort
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.
conditionScannerContainsSuspiciousShip
function conditionScannerContainsSuspiciousShip() : Boolean
The scan contains a ship with a criminal reputation (whether or not it currently carries a bounty)
conditionScannerContainsThargoidMothership
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.
conditionScannerContainsUnspreadMissile
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
conditionAllEscortsInFlight
function conditionAllEscortsInFlight() : Boolean
If the ship has living escorts, then this function returns true
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 true
.
conditionCanScoopCargo
function conditionCanScoopCargo() : Boolean
The ship has a working fuel scoop and at least 1 TC of free space in its hold.
conditionCargoIsProfitableHere
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.
conditionCoinFlip
function conditionCoinFlip() : Boolean
Returns true half the time.
conditionGroupLeaderIsStation
function conditionGroupLeaderIsStation() : Boolean
The ship has a group leader and the group leader is a station.
conditionHasInterceptCoordinates
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.
conditionHasMothership
function conditionHasMothership() : Boolean
The ship has a group leader which is not itself.
conditionHasNonThargoidTarget
function conditionHasNonThargoidTarget() : Boolean
The ship's target is not null, and is not a thargoid ship (by scan class).
conditionHasReceivedDistressCall
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.
conditionHasRememberedTarget
function conditionHasRememberedTarget() : Boolean
The ship has a remembered target. This is set by behaviourFollowCurrentTarget to allow persistent tracking of a ship.
conditionHasTarget
function conditionHasTarget() : Boolean
The ship's target is not null.
conditionHasWaypoint
function conditionHasWaypoint() : Boolean
The ship has a waypoint set by its waypoint generator.
conditionIsActiveThargon
function conditionIsActiveThargon() : Boolean
The ship is a thargon ("EQ_THARGON") and is active.
conditionIsEscorting
function conditionIsEscorting() : Boolean
The ship is currently escorting another ship. Stricter than conditionHasMothership: this also requires this ship to be in the group leader's escort group.
conditionIsGroupLeader
function conditionIsGroupLeader() : Boolean
The ship is in a group and is the leader of the group
conditionMissileOutOfFuel
function conditionMissileOutOfFuel() : Boolean
The ship has travelled beyond the maximum missile range. The default is 30km, but this may be overridden by the oolite_missile_range
parameter in the ship's script info.
conditionPatrolIsOver
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.
conditionWitchspaceEntryRequested
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. Unless otherwise stated, 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.
configurationMissileAdjustSpread
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.
configurationSetDestinationToHomeStation
function configurationSetDestinationToHomeStation()
Locates the home station, sets the destination to its position and the desired range to 15km.
configurationSetDestinationToGroupLeader
function configurationSetDestinationToGroupLeader()
Locates the group leader, sets the destination to its position and the desired range to 15km. Maximum flight speed is used.
configurationSetDestinationToMainPlanet
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).
configurationSetDestinationToMainStation
function configurationSetDestinationToMainStation()
Sets the destination to the main station's position, and the desired range to 15km
configurationSetDestinationToNearestHostileStation
function configurationSetDestinationToNearestHostileStation()
Locates the nearest friendly station, sets the destination to its position and the desired range to 15km.
configurationSetDestinationToNearestFriendlyStation
function configurationSetDestinationToNearestFriendlyStation()
Locates the nearest friendly station, sets the destination to its position and the desired range to 15km.
configurationSetDestinationToNearestStation
function configurationSetDestinationToNearestStation()
Locates the nearest station, sets the destination to its position and the desired range to 15km.
configurationSetDestinationToNearestWormhole
function configurationSetDestinationToNearestWormhole()
Locates the nearest entry wormhole, sets the destination to its position and the desired range to zero.
configurationSetDestinationToPirateLurk
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.
configurationSetDestinationToScannedTarget
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.
configurationSetDestinationToSelectedPlanet
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.
configurationSetDestinationToSelectedStation
function configurationSetDestinationToSelectedStation()
Sets the destination to the position of the station in the parameter "oolite_selectedStation", and the desired range to 15km.
configurationSetDestinationToSunskimEnd
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.
configurationSetDestinationToSunskimStart
function configurationSetDestinationToSunskimStart()
Sets the destination to the sun's position, and the desired range to sunskimming height.
configurationSetDestinationToWaypoint
function configurationSetDestinationToWaypoint()
If the parameters "oolite_waypoint" and "oolite_waypointRange" are set, use those as the destination and desired range.
configurationSetDestinationToWitchpoint
function configurationSetDestinationToWitchpoint()
Sets the destination to the witchpoint and the range to 10km
configurationSetWaypoint
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
configurationSetNearbyFriendlyStationForDocking
function configurationSetNearbyFriendlyStationForDocking()
Sets the "oolite_dockingStation" parameter to a friendly station in scanner range, if possible.
configurationSetHomeStationForDocking
function configurationSetHomeStationForDocking()
Sets the "oolite_dockingStation" parameter to the ship's home station.
configurationSetSelectedStationForDocking
function configurationSetHomeStationForDocking()
Sets the "oolite_dockingStation" parameter to the station in the parameter "oolite_selectedStation".
Miscellaneous configurations
configurationAppointGroupLeader
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.
configurationEscortGroupLeader
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.
configurationForgetCargoDemand
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.
configurationLeaveEscortGroup
function configurationLeaveEscortGroup()
If the ship is currently escorting another ship, leave the escort group.
configurationLightsOff
function configurationLightsOff()
Set the ship's flashers to the 'off' state.
configurationLightsOn
function configurationLightsOn()
Set the ship's flashers to the 'on' state.
configurationSetRemoteControl
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.
configurationSelectPlanet
function configurationSelectPlanet()
This function places a randomly selected planet or moon in the parameter "oolite_selectedPlanet"
configurationSelectRandomTradeStation
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)
configurationSelectShuttleDestination
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".
configurationSelectWitchspaceDestination
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.
configurationSelectWitchspaceDestinationInbound
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.
configurationSelectWitchspaceDestinationOutbound
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
configurationStationReduceAlertLevel
function configurationStationReduceAlertLevel()
Reduce the alert level of the station by one stage if it is not already Green.
configurationStationValidateTarget
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
configurationAcquireCombatTarget
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).
configurationAcquireDefensiveEscortTarget
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.
configurationAcquireHostileCombatTarget
function configurationAcquireHostileCombatTarget()
As configurationAcquireCombatTarget but only targets which are hostile (i.e. would be valid for behaviourRepelTarget) will be selected.
configurationAcquireOffensiveEscortTarget
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.
configurationAcquirePlayerAsTarget
function configurationAcquirePlayerAsTarget()
Set this ship's target to the player.
configurationAcquireScannedTarget
function configurationAcquireScannedTarget()
Set this ship's target to the entity in the parameter "oolite_scanResultSpecific". This parameter is set by the checkScannerWithPredicate function, which is usually called from a conditionScannerContains...
condition.
configurationCheckScanner
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 conditionScannerContains...
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);
responsesAddDocking
function responsesAddDocking(handlers : Object)
Provides some additional event handlers for use when docking with a station.
responsesAddEscort
function responsesAddEscort(handlers : Object)
Provides some additional event handlers for use when escorting a ship, and changes the response to in-group help requests.
responsesAddMissile
function responsesAddMissile(handlers : Object)
A standard set of event handlers for missiles, which should be used instead of responsesAddStandard
.
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.
responsesAddScooping
function responsesAddScooping(handlers : Object)
Provides some additional event handlers for use when scooping fuel.
responsesAddStandard
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
approachingPlanetSurface
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.
responsesAddStation
function responsesAddStation(handlers : Object)
A standard set of event handlers for stations, which should be used instead of responsesAddStandard
. The "oolite_flag_listenForDistressCall" and "oolite_flag_markOffenders" parameters have the same use as in responsesAddStandard
.
Response definition components
The components are standard event handlers used by the standard response functions. The following response components are available. Each is named "responseComponent_responseGroup_handlerName
". 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
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.
allied
function allied(ship1, ship2) : Boolean
Returns true
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.
broadcastDistressMessage
function broadcastDistressMessage()
Broadcasts a distress message, but with a delay to ensure that ship.broadcastDistressMessage() is not called too often.
checkScannerWithPredicate
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 "oolite_scanResultSpecific"
, and the method will return true
. Otherwise the method returns false
.
cruiseSpeed
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.
distance
function distance(position : vectorExpression)
Returns the distance to the given coordinates. This is more efficient than calling this.ship.position.distanceTo(position)
.
entityCommsParams
function entityCommsParams(entity : Entity) : Object
Returns an object of communications parameters relating to the given entity. Used internally by communicate() but may be of use elsewhere.
fineThreshold
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.
friendlyStation
function friendlyStation(station) : Boolean
Returns true
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. Other stations are only considered unfriendly to their current combat target.
homeStation
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 null
.
ignorePlayerFriendlyFire
function ignorePlayerFriendlyFire() : Boolean
Returns true
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.
isAggressive
function isAggressive() : Boolean
Returns true
if the ship is an active danger to its current target (approximately: it is in a combat behaviour other than fleeing)
isEscaping
function isEscaping() : Boolean
Returns true
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.
isFighting
function isAggressive() : Boolean
Returns true
if the ship is in combat (including fleeing). Similar to ship.hasHostileTarget
but works for stations as well.
noteDistraction
function noteDistraction(whom : Entity)
If this ship is switching combat targets because another ship distracted it, then call this function just before switching. whom
is the entity that this ship will soon switch to attacking. This calls the shipAttackerDistracted
event handler on the current target.
oddsAssessment
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.
playerRoleAssessment
function playerRoleAssessment() : String
Determines a single perceived role for the player based on player.roleWeights. In general, the perception will be the same for all ships in a group. This can then be used with Ship.roleIsInCategory to determine the appropriate response.
respondToThargoids
function respondToThargoids(whom : Ship, passon : Boolean) : Boolean
This function causes the ship (and if the passon
parameter is set, its group members) to respond to the appearance of the Thargoid ship whom
. It will return true
if this ship responds, or false
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 passon
as this may cause an infinite loop.
setWitchspaceRouteTo
function setWitchspaceRouteTo(dest : Number)
This function sets the oolite_witchspaceDestination
parameter according to the needs of reaching the system with the system ID equal to dest
. 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.
shipHasRiskyContracts
function shipHasRiskyContracts(ship : Ship) : Boolean
Sometimes returns true
(non-deterministically) if the target ship is carrying contracts that someone might want assassinated or destroyed. The chance of returning true
increases with the number of risky contracts carried. Currently this will always return false
for a non-player ship: you can check these with the oolite-courier
role category instead.
shipInRoleCategory
function shipInRoleCategory(ship : Ship, category : String) : Boolean
This is a wrapper around Ship.roleIsInCategory
which accounts for the player's effective role not being the same as player.ship.primaryRole
. You should generally call this instead of calling Ship.roleIsInCategory
directly.
stationAllegiance
function stationAllegiance(station : Station) : String
Returns station.allegiance
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.
threatAssessment
function threatAssessment(ship : Ship, full : Boolean) : Number
This is a wrapper around _threatAssessment
which is itself a wrapper around ship.threatAssessment()
. 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.
waypointsSpacelanePatrol
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.
waypointsStationPatrol
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.
waypointsWitchpointPatrol
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.
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_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 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 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. 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 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.
Methods
_getCommunication
function _getCommunication(role : String, personality : String, key : String) : StringOrFunction
This function returns either a string suitable for passing to expandDescription
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. 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;