AI methods

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

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 recieves 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.

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
//ISets 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
//his 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 it's 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, targetting 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 agressor against the caller, or the caller has already targeted the primary agressor, this function does nothing.
//If there is a primary agressor and the caller is not currently attacking another target, the primary agressor 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 agressor.
//The game decides which entity, if any, is currently the primary agressor 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 targetting the AI's ship or another ship in it's group, all ships in the group have their found_target and primary_aggressor  properties changed to that missle. 
//The first missle 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 it's group will flee the missle 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 nuimbers 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 simmilar to escorting, used to let patrolls 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 alertlevel. Levels are CONDITION_GREEN, YELLOW_ALERT, RED_ALERT.
decreaseAlertLevel
//depricates the alertlevel of entity by one level.

Communications

broadcastDistressMessage
//General call for help. All in range get message   
sendTargetCommsMessage: hello!
//AI sends a comms message to it's current target. 
//Comms can use arrays from descriptions.plist as text in square brackets.
commsMessage: [thargoidcurses]
//Sends a comms message to all in range.