Oolite Javascript Reference: PriorityAI Documentation - Revision history

Phkb: Updating BB links

2024-02-29T02:19:47Z

Updating BB links

Cholmondely: /* Links */ Added link for Group AI

2023-01-21T20:02:46Z

‎Links: Added link for Group AI

Cholmondely: /* Links */ Oops!

2023-01-19T22:47:17Z

‎Links: Oops!

Cholmondely: /* Links */ Added "Role"

2023-01-19T22:46:56Z

‎Links: Added "Role"

Cholmondely: Added Links

2023-01-18T10:41:51Z

Added Links

Massively Locked: uniform null format (x6)

2022-10-30T14:35:59Z

uniform null format (x6)

Massively Locked: uniform boolean format (x18)

2022-10-28T04:25:33Z

uniform boolean format (x18)

Massively Locked: fixed names

2022-10-01T15:53:25Z

fixed names

Alnivel: Fixed links

2022-09-21T19:32:16Z

Fixed links

Cim: /* behaviourWaitHere */ 1.81

2015-01-24T14:33:54Z

‎behaviourWaitHere: 1.81

@@ Line 1,662: / Line 1,662: @@
   [[Role]]
-  [http://aegidian.org/bb/viewtopic.php?p=196417#p196417: The effectiveness of "group AI" in Oolite v.1.77 and plans for v.1.80]
+  [https://bb.oolite.space/viewtopic.php?p=196417#p196417: The effectiveness of "group AI" in Oolite v.1.77 and plans for v.1.80]
 [[Category:Oolite JavaScript Reference]]

← Older revision		Revision as of 20:02, 21 January 2023
Line 1,661:		Line 1,661:

	[[Role]]		[[Role]]
		+
		+	[http://aegidian.org/bb/viewtopic.php?p=196417#p196417: The effectiveness of "group AI" in Oolite v.1.77 and plans for v.1.80]
		+

	[[Category:Oolite JavaScript Reference]]		[[Category:Oolite JavaScript Reference]]

@@ Line 1,657: / Line 1,657: @@
   [[AI]] (.plist AI's)
   [[AI_methods]] (.plist AI's)
-−
   [[Oolite PriorityAI Tutorial]] (''Javascript'' AI's)
-−
   [[Role]]
 [[Category:Oolite JavaScript Reference]]

← Older revision		Revision as of 22:46, 19 January 2023
Line 1,659:		Line 1,659:

	[[Oolite PriorityAI Tutorial]] (''Javascript'' AI's)		[[Oolite PriorityAI Tutorial]] (''Javascript'' AI's)
		+
		+	[[Role]]

	[[Category:Oolite JavaScript Reference]]		[[Category:Oolite JavaScript Reference]]

@@ Line 1,650: / Line 1,650: @@
 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]]

@@ Line 53: / Line 53: @@
 ==== <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.
+If a parameter with that key has previously been set, return its value. Otherwise return <code>null</code>. 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> ====
@@ Line 83: / Line 83: @@
 ==== <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.
+Set the named parameter to the given value. Values may be of any type. To remove a parameter, use a value of <code>null</code>. See the [[#Parameters|Parameters]] section below for parameter keys used by the core AIs and the standard priority AI library.
 ==== <code>setPriorities</code> ====
@@ Line 737: / Line 737: @@
 ==== <code>conditionHasNonThargoidTarget</code> ====
   function '''conditionHasNonThargoidTarget'''() : Boolean
-The ship's target is not null, and is not a thargoid ship (by scan class).
+The ship's target is not <code>null</code> and is not a thargoid ship (by scan class).
 ==== <code>conditionHasReceivedDistressCall</code> ====
@@ Line 749: / Line 749: @@
 ==== <code>conditionHasTarget</code> ====
   function '''conditionHasTarget'''() : Boolean
-The ship's target is not null.
+The ship's target is not <code>null</code>.
 ==== <code>conditionHasWaypoint</code> ====
@@ Line 769: / Line 769: @@
 ==== <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 <code>true</code> if so.
+This function checks if the <code>oolite_flag_launchAdjustMissile</code> parameter is set to a non-<code>null</code> value, and returns <code>true</code> if so.
 Missile AI scripts may find the following code useful to set this flag to avoid collisions with the launching ship.
@@ Line 1,281: / Line 1,281: @@
 ==== <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.
+Returns <code>station.allegiance</code> for the given station, but if this is <code>null</code> (as it will be for pre-1.79 stations), first sets it using a heuristic calculation.
 ==== <code>threatAssessment</code> ====

@@ Line 171: / Line 171: @@
 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.
+* '''condition''': function run unconditionally if this element of the list is reached. If it returns <code>false</code>, 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.
+* '''notcondition''': function run unconditionally if this element of the list is reached. If it returns <code>true</code>, 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.
+If neither '''condition''' nor '''notcondition''' are set, this is treated as if a condition was set and was <code>true</code>.
 * '''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.
@@ Line 458: / Line 458: @@
 ==== <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).
+Returns <code>true</code> if a cascade explosion has been detected recently (as given by the parameter "oolite_cascadeDetected" containing the explosion coordinates).
 ==== <code>conditionCombatOdds*</code> ====
@@ Line 465: / Line 465: @@
   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.
+These functions return <code>true</code> 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.
+This condition is <code>true</code> 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.
+This condition is <code>true</code> if the ship's group is running out of consumables such as missiles or fuel, or has several damaged ships.
 ==== <code>conditionInCombat</code> ====
@@ Line 505: / Line 505: @@
 ==== <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>.
+This condition is <code>true</code> 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 ===
@@ Line 609: / Line 609: @@
 === 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_scanResultSpecific" parameter, in addition to the condition returning true.
+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_scanResultSpecific" parameter, in addition to the condition returning <code>true</code>.
 ==== <code>conditionScannerContainsAssassinationTarget</code> ====
@@ Line 721: / Line 721: @@
 ==== <code>conditionCoinFlip</code> ====
   function '''conditionCoinFlip'''() : Boolean
-Returns true half the time.
+Returns <code>true</code> half the time.
 ==== <code>conditionGroupLeaderIsStation</code> ====
@@ Line 769: / Line 769: @@
 ==== <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.
+This function checks if the <code>oolite_flag_launchAdjustMissile</code> parameter is set to a non-null value, and returns <code>true</code> if so.
 Missile AI scripts may find the following code useful to set this flag to avoid collisions with the launching ship.
@@ Line 1,053: / Line 1,053: @@
   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_allowPlanetaryLanding: if <code>true</code>, 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_listenForDistressCall: if <code>true</code>, 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_markOffenders: if <code>true</code>, 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_sendsDistressCalls: if <code>true</code>, 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.
+* oolite_flag_watchForCargo: if <code>true</code>, 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.
@@ Line 1,192: / Line 1,192: @@
 ==== <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.
+Returns <code>true</code> if the two ships are considered allied, <code>false</code> 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> ====
@@ Line 1,223: / Line 1,223: @@
 ==== <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.
+Returns <code>true</code> if the station is friendly to the current ship, <code>false</code> 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> ====

@@ Line 436: / Line 436: @@
 ==== <code>behaviourStationLaunchSalvager</code> ====
-  function '''behaviourStationLaunchMiner'''()
+  function '''behaviourStationLaunchSalvager'''()
 Launches a salvager. Also reduces the alert condition by one step.
@@ Line 480: / Line 480: @@
 ==== <code>conditionInCombatWithHostiles</code> ====
-  function '''conditionInCombat'''() : Boolean
+  function '''conditionInCombatWithHostiles'''() : 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)
@@ Line 496: / Line 496: @@
 ==== <code>conditionMothershipIsAttackingHostileTarget</code> ====
-  function '''conditionMothershipIsAttacking'''() : Boolean
+  function '''conditionMothershipIsAttackingHostileTarget'''() : 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.
@@ Line 964: / Line 964: @@
 ==== <code>configurationSelectWitchspaceDestinationInbound</code> ====
-  function '''configurationSelectWitchspaceDestination'''()
+  function '''configurationSelectWitchspaceDestinationInbound'''()
 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'''()
+  function '''configurationSelectWitchspaceDestinationOutbound'''()
 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.
@@ Line 1,246: / Line 1,246: @@
 ==== <code>isFighting</code> ====
-  function '''isAggressive'''() : Boolean
+  function '''isFighting'''() : 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.

@@ Line 31: / Line 31: @@
 ==== <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:
+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>
@@ Line 73: / Line 73: @@
 ==== <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]].
+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)
@@ Line 79: / Line 79: @@
 ==== <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]].
+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> ====
@@ Line 753: / Line 753: @@
 ==== <code>conditionHasWaypoint</code> ====
   function '''conditionHasWaypoint'''() : Boolean
-The ship has a waypoint set by its [[#|waypoint generator]].
+The ship has a waypoint set by its [[#Waypoint_Generators|waypoint generator]].
 ==== <code>conditionIsActiveThargon</code> ====
@@ Line 1,285: / Line 1,285: @@
 ==== <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.
+This is a wrapper around <code>_threatAssessment</code> (intentionally not documented) 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 ==
@@ Line 1,636: / Line 1,636: @@
 ==== _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:
+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.

@@ Line 396: / Line 396: @@
   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 ===