AI methods

This entry is meant to include the methods not mentioned in the general scripting methods wiki. Used in AI-scripting mostly.

AI mechanisms

pauseAI: x

AI waits for x seconds.

exitAI

Exits the current AI and returns to the AI one below in the AI stack.

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. (The name comes from an implementation perspective, where the ship, the AI and the script are three different objects, sending messages to each other.)

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.

Navigation

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

See cim's notes on coding the scanner here: https://bb.oolite.space/viewtopic.php?p=208476#p208476 (2013)

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 (and possibly everywhere else too).

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.

Cholly's chunterings

I'm not a programmer, but:

1) Naval fleet cohesion - see 2013 thread here

2) Be aware of cim's Escort Formations & Norby's Convoys & Freighter Convoys

3) Be aware of szaumix's 2022 critique: here and especially this post

Links

OXP howto
OXP howto AI (.plist AI's)
Methods 
AI (.plist AI's)
Oolite Javascript Reference: PriorityAI Documentation
Oolite PriorityAI Tutorial (Javascript AI's)
Role