OXP howto AI

AI Script Format

The AI system consists of a stack of state machines (only the top one of which is active), which respond to game events sent to them as messages. They respond by calling a series of methods which affect the behaviour of the entity and possibly trigger changes to the AI by changing the state or (more drastically) the state machine.

Each state machine (or AI script) is described in a property list in either ASCII or XML format, which can be edited with a text editor or with Property List Editor. The structure is of a dictionary containing each of the machine's possible states referenced by an identifying state name. Each state comprises a dictionary of responses to messages the AI might receive, referenced by the message itself. Each response is an array of methods that will be called when the AI receives that message.

The AI function calls within a message handler are separated from each other by a comma. If a function takes a parameter the value is separated from the function name by a colon and a space, and both the function name and value are enclosed in double quotes.

In ASCII format a simple (two-state) machine looks like this:

{
     "STATE_1" = {
         "ENTER" = ();
         "MESSAGE_A" = ("method1: value", method2, method3);
         "MESSAGE_B" = (method4, "setStateTo: STATE_2");
         EXIT = ();
         UPDATE = ();
     };
     "STATE_2" = {
         "ENTER" = ();
         "MESSAGE_A" = ("method1: another_value", method5);
         "MESSAGE_B" = (method6, method7, "setStateTo: STATE_1");
         EXIT = ();
         UPDATE = ();
     };
}

The same script in XML.

AI

Method	Description
exitAI	Exits current AI.
messageMother:(NSString *)msgString	Sends a AImessage to the mothership/leader of a group. Example: INCOMING_MISSILE = ("messageMother: INCOMING_MISSILE"); The mothership will then behave as if it was targetted by the missile.
pauseAI:(NSString *)intervalString	Sets AI think-time in seconds.
setAITo:(NSString *)aiString	Pauses current AI and switches to anotherAI.plist, this becomes the top AI on the 'AI-stack'. When anotherAI.plist exits (exitAI), the previousAI becomes topAI again and AI-state is messaged RESTARTED.
setStateTo: SOMESTATE	Changes the AI state to SOMESTATE.
switchAITo:(NSString *)aiString	Switches entity AI to another *AI.plist, the previous AI will be exited.

AI choices

Method	Description
fightOrFleeHostiles	Deploys escorts if he has them. If he has enough missiles left he might fire one. Then decides between issue the FIGHTING or FLEEING message. Returns "FIGHTING", "DEPLOYING_ESCORTS" or "FLEEING".
fightOrFleeMissile	Deals with missiles, launches ECM if available, flees if not, marks as offender if police.

Perform Action

Method	Description
acceptDistressMessageFrom:(ShipEntity *)other	Has police either respond to a distress call, or possibly decide it is too busy or too scared.
becomeEnergyBlast	Used in the Q bomb.
becomeExplosion	The entity model is replaced by an explosion. If player is docked at exploding station it first launches the player.
becomeLargeExplosion	Used at player entity death, not for use in other instances.
dealEnergyDamageWithinDesiredRange	Needs desiredRange to be set first, then deals weaponEnergy (Shipdata.plist) damage within this sphere.
decreaseAlertLevel	Can only be used on stations. Decreases station alertlevel. Returns: "CONDITION_YELLOW", "CONDITION_GREEN".
deployEscorts	Deploys existing escorts to attack the current target.
ejectCargo	Ejects cargo.
enterTargetWormhole	Will locate nearest wormhole, and enter it.
escortCheckMother	Returns "ESCORTING" or "NOT_ESCORTING".
fireECM	Used by stations and hermits to engage ECM.
groupAttackTarget	All ships in group will have their targets set to this entity's target and performAttack.
increaseAlertLevel	Can only be used on stations. Increases station alertlevel. Returns: "YELLOW_ALERT", "RED_ALERT".
landOnPlanet	Selects the nearest planet it can find, lands (10km from planet) and 'removes' the entity. Returns: "LANDED_ON_PLANET"
Launch..SomeShip	Launches a ship fron a dockable entity, various types of this method exist. See also Station Ships. LaunchDefenceShip LaunchEscort LaunchMiner LaunchPatrol LaunchPirateShip LaunchPolice LaunchScavenger LaunchShipWithRole: <Role> LaunchShuttle LaunchTrader
markTargetForFines	Deals out a fine to target. Example: "markTargetForFines: 100" Will fine the target 10Cr. N.B. for commercial transactions "awardMoney -$" is a more suitable method.
markTargetForOffence:(NSString*) valueString	Has police mark up the criminal record (Legal status) of target entity.
messageMother:(NSString *)msgString	Sends a AImessage to the mothership/leader of a group. Example: INCOMING_MISSILE = ("messageMother: INCOMING_MISSILE"); The mothership will then behave as if it was targetted by the missile.
performAttack	Attacks target.
performCollect	Performs 'collection' of target.
performDocking	NOT YET IMPLEMENTED.
performEscort	Performs escorting.
performFaceDestination	Has entity face destination. Returns "FACING_DESTINATION" when turn is compleated.
performFlee	Sets the caller (AI) to flee from it's primary target at maximum speed. If the caller has a cloacking device, it will be activated.
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.
performFlyToPlanet	Used in shuttleAI. combined method to target and fly towards planet?
performHold	Performs idleness while tracking a potential target, speed is set to zero. frustration level is reset.
performHyperSpaceExit	Gets a list of destinations within range, checks if clear of nearby masses, and select one at random. May return "WITCHSPACE UNAVAILABLE" or "WITCHSPACE BLOCKED".
performIdle	Performs idleness. Ship corrects its roll and pitch to 'horizontal' flight, speed is unaffected. frustration level is reset to zero.
performIntercept	Performs target interception.
performLanding	Same as landOnPlanet, duplicate method or no longer in use?
performMining	Performs mining. (Finds, intercepts and shoots asteroids with mining laser, if fitted.)
performTumble	Performs random pitch and roll, 'evasive maneuvers'.
setSpeedTo:(NSString *)speedString	Sets desired speed to an absolute value, entity cannot go faster than maxspeed value determined in the shipdata.plist. If speed is above maxspeed, entity will use fuelinjectors if available.
setSpeedFactorTo:(NSString *)speedString	Sets the desired speed to a percentage of maxspeed (0->1=0%->100%). If speedfactor is set above 100%, entity will use fuelinjectors if available.
setUpEscorts	Useful to quickly establish (by name and number the shipdata.plist prescribed) escorts, when a ship is introduced to a system.
suggestEscort	Has an escort seek employment and either gets accepted or rejected by the "mother".
switchLightsOff	If an entity has lights (or flashers), this command will turn them off. Default state is on. (See shipdata.plist)
switchLightsOn	Will turn flashers back on.
wormholeEntireGroup	Wormholes ships in this group.
wormholeEscorts	Wormholes official escorts.
wormholeGroup	Wormholes ships in group of which this is a leader.

Navigation

Method	Description
abortDocking	Signal the motherstation that the docking is aborted. see Docking Instructions
getWitchspaceEntryCoordinates	Calculates coordinates at 10 km from the nearest station it can find, or just fly 10s forward.
recallDockingInstructions	see Docking Instructions
requestDockingCoordinates	Requests coordinates from the nearest station it can find (which may be a Rock hermit). Returns: "NO_STATION_FOUND", "TRY_AGAIN_LATER", "HOLD_POSITION", "BACK_OFF" or "APPROACH". see also Docking Instructions
setCoordinates:(NSString *)system_x_y_z	Sets destination coords, see addShipsAt.
setCourseToPlanet	Selects the nearest planet it can find, reaching desired range 50 m from the planet. This will probably crash normal ships on the surface but a collission between the planet and a ship with role "shuttle" is interpreted as landing.
setCourseToWitchpoint	Sets destination coords to Witchpoint area and sets "DesiredRange" to 10 km.
setDesiredRangeTo:(NSString *)rangeString	Some methods (such as scanForNearestMerchantmen, checkCourseToDestination, checkDistanceTravelled, etc) require a "desired range" parameter to be set before they can be used. This method is used to set the desired range. There is only one value for desired range within an instance of the AI. The value of desired range is modified internally by AI methods such as fightOrFleeMissile, setCourseToWitchpoint, and setPlanetPatrolCoordinates.
setDestinationFromCoordinates	Enables the plotting of manual waypoints.
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.
setDestinationToDockingAbort	DockingAbort coordinates 8000 meter distance from the dockingslit.
setDestinationToStationBeacon	Gets station beacon position.
setDestinationToTarget	Sets destination to target coords.
setDestinationToWitchpoint	Sets destination coordinates to WitchspaceExitPosition.
setDestinationWithinTarget	Handy for ramming and racing.
setPlanetPatrolCoordinates	Request coordinates for planet control. Read more in setPlanetPatrolCoordinates.
setSunSkimEndCoordinates	...
setSunSkimExitCoordinates	...
setSunSkimStartCoordinates	...
setTargetToSystemStation	...
setTargetToStation	...

Communication

Method	Description
broadcastDistressMessage	Locates all the stations, bounty hunters and police ships in range and tells them that you are under attack. This command resets the found target to none.
commsMessage:(NSString *)valueString	Broadcasts a general message to player. Example: "sendCommsMessage: [thargoid_curses]"
patrolReportIn	...
sendTargetCommsMessage:(NSString*) message	Sends any message to the established (found) target. Example: "sendTargetCommsMessage: Listen to me!!"

Locating entities

All these methods require a range to be set by setDesiredRange or by <scanner_range> in shipdata.plist, all will return the message TARGET_FOUND or NOTHING_FOUND. The calling entity remembers the found target, but it does not become the current (universal) target. It can be made the current target by responding to the TARGET_FOUND message with a call to setTargetToFoundTarget.

Method	Description
findNearestPlanet	Will scan for planetentity.
scanForFormationLeader	Locates the nearest suitable formation leader in range.
scanForHostiles	Locates all the ships in range targeting the receiver and ships with "SCANNCLASS_TARGOID" and chooses the nearest.
scanForLoot	Scans for nearest debris in range. Returns: "HOLD_FULL", "TARGET_FOUND" or "NOTHING_FOUND". If scanning ship is station or has no scoop it always return: "NOTHING_FOUND". If scanning ship has scanClass: "CLASS_POLICE", it only finds slaves and lifepods.
scanForNearestMerchantmen	Scans for ships with role: Trader or Player and selects the nearest. If scanning ship has role Pirate it prefers the player. Returns: "TARGET_FOUND" or "NOTHING_FOUND"
scanForNearestShipWithRole:(NSString*) scanRole	Locates all the ships in range and chooses the nearest.
scanForNonThargoid	Locates all the non thargoid ships in range and chooses the nearest. It finds everything except cargo and ships with a role starting with: "tharg". If it finds the player it prefers the player.
scanForOffenders	Locates all the ships in range and compares their legal status or bounty, and chooses the worst offender.
scanForRandomLoot	Scans for debris in range and selects one at random from the first 16 found. Returns: "HOLD_FULL", "TARGET_FOUND" or "NOTHING_FOUND" If scanning ship is station or has no scoop it always return: "NOTHING_FOUND".
scanForRandomMerchantmen	Scans for ships with role: Trader or Player and selects one at random. Returns: "TARGET_FOUND" or "NOTHING_FOUND".
scanForRocks	Scans for nearest boulder in range. When nothing found then scans for nearest asteroid in range. Returns "TARGET_FOUND" or "NOTING_FOUND".
scanForThargoid	Locates all the ships with role "thargoid" in range and chooses the nearest.
checkCourseToDestination	Will return "COURSE_OK" or in case of obstacles on the direct route, "WAYPOINT_SET".
checkDistanceTravelled	May return "GONE_BEYOND_RANGE" or "DESIRED_RANGE_ACHIEVED".
checkGroupOddsVersusTarget	Will return "ODDS_GOOD" or "ODDS_BAD".
checkForFullHold	If entity's cargo capacity is reached, will return "HOLD_FULL".
checkForMotherStation	Will return "STATION_FOUND" or "NOTHING_FOUND".
checkForNormalSpace	Will return "NORMAL_SPACE" or "INTERSTELLAR_SPACE".
checkForShips: <role>	Returns with shipsFound_number = #.
checkTargetLegalStatus	Returns "TARGET_CLEAN, "TARGET_MINOR_OFFENDER", "TARGET_OFFENDER", "TARGET_FUGITIVE" or "NO_TARGET".

Targeting

Method	Description
requestNewTarget	Locates all the ships in range targeting the mother ship, and chooses the nearest/biggest.
setTargetToFoundTarget	Affirms a TARGET_FOUND by a scanFor- or find-Something-method as the universal target.
setTargetToPrimaryAggressor	Changes to a different enemy target if attacked, unless already very involved in attacking another.

Miscellaneous

Method	Description
addFuel:(NSString*) fuel_number	Changes player's fuel level by fuel_number LY's, max to 7.0 min to 0.0.
becomeUncontrolledThargon	Changes ship into cargo with scannClass "CLASS_CARGO" and sets AI to "dumbAI". If also the the cargo type is defined in ShipData.plist it can be picked up like any other cargo.
initialiseTurret	Prepares the turret.
rollD:(NSString*) die_number	Uses "dice" for random situation use. Example 1, 3 options in someAI.plist: GLOBAL = { ENTER = ("rollD: 3"); "ROLL_1" = (action1); "ROLL_2" = (action2); "ROLL_3" = (action3);} Example 2, 50% chance in script.plist; conditions = ("d100_number lessthan 50"); do = (action1); else = (action2); is similar in function.
scriptActionOnTarget:(NSString*) action	Will cause immediate reaction to any changes this makes.
setTakeOffFromPlanet	Selects the nearest planet it can find and adds entity 10 km from planet, unless there is no planet to be found.

---