AI methods
This entry is meant to include the methods not mentioned in the general scripting methods wiki. Used in AI-scripting mostly.
Contents
AI mechanisms
pauseAI: x
AI waits for x seconds.
exitAI
Exits the current AI and returns to the AI one below in the AIstack.
setStateTo: SOME_STATE
Switches AI state to SOME_STATE, message EXIT is sent to current state before exiting.
switchAITo: someAI.plist
Exits current AI and starts the new AI.
setAITo: someAI.plist
Starts the new AI, current AI will be paused underneath the new AI, when newAI exits, the firstAI receives the message RESTARTED in the same state as when the newAI was called.
Script integration
scriptActionOnTarget
Forces script actions on the current target.
sendScriptMessage: message
Calls the method message() on the ship’s ship script. Added in Oolite 1.70.
Miscellaneous
targetNextBeaconWithCode: XX
Sets beacon with code xx as the target.
checkForFullHold
Checks the amount of cargo in the calling ship's hold, and if the hold is full sends the HOLD_FULL message.
performCollect
Sets the caller to collect the primary target, assumed to be a scoopable item.
While in the CONDITION_COLLECT_TARGET condition, the TARGET_LOST message will be received if the target is travelling faster than the collecting ship, and the FRUSTRATED message will be sent after 10 seconds, and thereafter every 5 seconds, while the item has not been collected.
becomeExplosion
Entity becomes explosion.
dealEnergyDamageWithinDesiredRange
Deals damage equal to weaponEnergy within all entities within desiredRange.
setDesiredRangeTo: xx
Sets desired range to xx metres.
becomeEnergyBlast
Used by QC-bomb, energy wave spreads from entity, detonating entities caught, who in turn detonate.
checkTargetLegalStatus
Returns: TARGET_CLEAN, TARGET_MINOR_OFFENDER, TARGET_OFFENDER, or TARGET_FUGITIVE.
markTargetForFines
Marks target for fines when docking.
switchLightsOn
Flashers are turned on (default).
switchLightsOff
Flashers are turned off.
fireECM
Forces ECM use.
setSpeedfactorTo: x.x
Set speed as a fraction of the maxspeed (1.0=100%)
setSpeedTo: xx
Sets speed to an absolute number, up to maximum speed of vehicle.
setRacepointsFromTarget
Navigation for racers
performFlyRacepoints
Go!!
setDesiredRangeTo: xx
Sets a range as xx metres, used by other methods. (double entry)
performIntercept
Sets the caller to intercept the primary target at maximum speed.
While in the CONDITION_INTERCEPT_TARGET condition, the DESIRED_RANGE_ACHIEVED message will be received if the target is within the current desired_range.
checkDistanceTravelled.
Compares to DesiredRange and messages GONE_BEYOND_RANGE
setDestinationToCurrentLocation
This method sets the destination of the current entity to its current location plus a random offset of up to 0.5 metres in the X, Y, and Z coordinates.
This can be used to make a ship idle in a small area of space without being completely still.
performFlyToRangeFromDestination
Sets the AI's current state to CONDITION_FLY_RANGE_FROM_DESTINATION.
While in this state the entity will attempt to fly to its current destination, stopping at the desired range from it.
requestDockingCoordinates
Sets the current coordinates to the nearest space station or other dockable entity in the current game area.
There may be no stations, for example in witchspace, in which case the NO_STATION_FOUND message is sent to the current AI state.
getWitchspaceEntryCoordinates
Sets the current coordinates to an appropriate point to make a witchspace jump.
"Appropriate" means either 10kms away from the nearest station, or if no station is found, the distance that can be flown forward in 10 seconds of flying at maximum speed (note that actual speed is not changed).
setDestinationFromCoordinates
Sets the ship's destination to the current value of coordinates.
performFaceDestination
Requests the ship stop and face the location given by destination. The message FACING_DESTINATION will be sent when this has been achieved
performTumble
Requests the ship randomly vary its pitch and roll until taken out of CONDITION_TUMBLE. Current speed is not affected.
performStop
Come to a complete halt
performIdle
Sets the AI's current state to CONDITION_IDLE and resets the frustration factor to zero.
Unlike performHold the current speed is not modified.
performHold
Sets the entity's speed to zero, sets the AI's current state to CONDITION_TRACK_TARGET and resets the frustration factor to zero.
performLanding
Used to land ships on planet.
landOnPlanet
...this one too. ?
performDocking
Docks ship-entity with a station-entity.
Is stated above as non-functioning, but is used in fighterInterceptAI.plist of the Behemoth.OXP
Scanning, targeting and attacking
scanForNearestShipHavingAnyRole: <role> <role2> ...
Looks for the nearest vessel with any of the specified roles in its role set within scanner range. Added in Oolite 1.70.
The calling entity remembers the found ship, but it does not become the current target.
It can be made the current target by responding to the TARGET_FOUND message with a call to setTargetToFoundTarget.
scanForNearestShipHavingRole: <role>
Looks for the nearest vessel with the specified role in its role set within scanner range. Added in Oolite 1.70.
The calling entity remembers the found ship, but it does not become the current target.
It can be made the current target by responding to the TARGET_FOUND message with a call to setTargetToFoundTarget.
scanForNearestShipNotHavingRole: <role>
Looks for the nearest vessel without the specified role in its role set within scanner range. Added in Oolite 1.70.
The calling entity remembers the found ship, but it does not become the current target.
It can be made the current target by responding to the TARGET_FOUND message with a call to setTargetToFoundTarget.
scanForNearestShipWithAnyPrimaryRole: <role1> <role2> ...
Looks for the nearest vessel with any of the specified primary roles within scanner range. Added in Oolite 1.70.
The calling entity remembers the found ship, but it does not become the current target.
It can be made the current target by responding to the TARGET_FOUND message with a call to setTargetToFoundTarget.
scanForNearestShipWithoutPrimaryRole: <role>
Looks for the nearest vessel without the specified primary role within scanner range. Added in Oolite 1.70.
The calling entity remembers the found ship, but it does not become the current target.
It can be made the current target by responding to the TARGET_FOUND message with a call to setTargetToFoundTarget.
scanForNearestShipWithPrimaryRole: <role>
New, more consistent name for scanForNearestShipWithRole: in Oolite 1.70.
scanForNearestShipWithRole: <role>
Looks for the nearest vessel with the specified primary role within scanner range. Added in Oolite 1.70.
The calling entity remembers the found ship, but it does not become the current target.
It can be made the current target by responding to the TARGET_FOUND message with a call to setTargetToFoundTarget.
scanForNearestShipWithScanClass: <role>
Looks for the nearest vessel with the specified scan class within scanner range. Added in Oolite 1.70.
The calling entity remembers the found ship, but it does not become the current target.
It can be made the current target by responding to the TARGET_FOUND message with a call to setTargetToFoundTarget.
scanForNearestShipWithoutScanClass: <role>
Looks for the nearest vessel without the specified scan class within scanner range. Added in Oolite 1.70.
The calling entity remembers the found ship, but it does not become the current target.
It can be made the current target by responding to the TARGET_FOUND message with a call to setTargetToFoundTarget.
scanForNearestMerchantmen
Looks for the nearest merchant vessel (including the player's ship) within scanner range.
The calling entity remembers the targeted ship, but it does not become the current target.
It can be made the current target by responding to the TARGET_FOUND message with a call to setTargetToFoundTarget.
scanForRandomMerchantmen
Randomly selects one of the merchant vessels within scanner range.
The calling entity remembers the targeted ship, but it does not become the current target.
It can be made the current target by responding to the TARGET_FOUND message with a call to setTargetToFoundTarget.
The player's ship has an equal chance of being selected, if it is within scanner range. The internal game setting of PIRATES_PREFER_PLAYER is ignored in this function.
scanForLoot
Selects the nearest scoopable item within scanner range.
The calling entity remembers the item, but it does not become the current target.
It can be made the current target by responding to the TARGET_FOUND message with a call to setTargetToFoundTarget.
scanForRandomLoot
Selects a random scoopable item from all those within scanner range.
The calling entity remembers the item, but it does not become the current target.
It can be made the current target by responding to the TARGET_FOUND message with a call to setTargetToFoundTarget.
scanForThargoid
Military scan for ships with role of thargoid.
scanForNonThargoids
Thargoid scan for ships with role other than thargoid.
setTargetToPrimaryAggressor
If there is no current primary aggressor against the caller, or the caller has already targeted the primary aggressor, this function does nothing.
If there is a primary aggressor and the caller is not currently attacking another target, the primary aggressor is targeted.
If the caller is already attacking another entity there is a 75% chance it will continue to attack the current target rather than change its target to the primary aggressor.
The game decides which entity, if any, is currently the primary aggressor against the caller.
setTargetToFoundTarget
Makes most recently found target the current target.
performFlee
Sets the caller to flee from the primary target at maximum speed.
While in the CONDITION_INTERCEPT_TARGET condition, the REACHED_SAFETY message will be received once the primary target is at least as far away as the current value of desired_range.
If the caller has a cloaking device, it will be activated.
performAttack
Tells the caller to start attacking its current target.
groupAttackTarget
Entity will perform attack together with groupmates.
fightOrFleeMissile
If a missile is in flight and is targeting the AI's ship or another ship in its group, all ships in the group have their found_target and primary_aggressor properties changed to that missile.
The first missile found is dealt with, range and bearing are not taken into account.
If the AI's ship has an ECM it will use it.
If not, the AI's ship and any ships in its group will flee the missile using performFlee with a desired_range of 10 kms.
In this case the FLEEING message is sent to the current AI state.
fightOrFleeHostiles
Outputs either a FIGHTING or FLEEING message to AI.
Group action
RequestNewTarget
Selects a random hostile vessel?
CheckGroupOddsVersusTarget
Checks odds (by absolute numbers or power?) of groups vs adversaries.
Returns several messages, ODDS_BAD, ODD_GOOD or ODDS_EQUAL.
escortCheckMother
Outputs ESCORTING or NOT_ESCORTING message.
messageMother: AI_MESSAGE
escort (or defenceship?) messages its mother with a AI message such as ATTACKED.
scanForFormationLeader
?
performEscort
escort will deploy in formation and follow mother.
deployEscorts
Requests escorts.
dockEscorts
Tells escorts to dock with station.
patrolReportIn
Probably similar to escorting, used to let patrols fly in formation. ?
wormholeEscorts
Tells escorts to search for the nearest wormhole and exit through it.
Stations and carriers
LaunchDefenceShip
Dock-capable entity launches a defenceship.
defenceship type can be defined in shipdata.plist.
LaunchScavenger
Launches a ship with role scavenger.
LaunchMiner
Launches a ship with role miner.
LaunchPolice
Launches a ship with role police.
IncreaseAlertLevel
Increases alert level. Levels are CONDITION_GREEN, YELLOW_ALERT, RED_ALERT.
decreaseAlertLevel
Decreases the alert level of entity by one level.
Communications
broadcastDistressMessage
General call for help. All in range get message.
sendTargetCommsMessage: hello!
AI sends a comms message to its current target.
Comms can use arrays from descriptions.plist as text in square brackets.
commsMessage: [thargoidcurses]
Sends a comms message to all in range.
