Methods

Methods

Methods are the actions that are performed when conditions (defined in a script) are met, or when a particular set of actions (like death_actions or script_actions) are called for, or when an AI calls for a script action to be performed.

All methods are stored in plists as strings (in XML this means between a <string> tag and a </string> closing tag). If they take any parameters then these follow a colon and a space (: ) after the 'command' part of the method.

For example: if the ship containing this death_actions entry is destroyed - the player gets a message and the sun goes Nova two seconds later!

<key>death_actions</key>
<array>
	<string>commsMessage: Oh dear [commander_name]!</string>
	<string>setSunNovaIn: 2.0</string>
</array>

The Mission Screen

setGuiToMissionScreen
// opens the mission screen

addMissionText: <missiontext.plist key> 
// adds text to the mission screen from an entry in missiontext.plist
// with the given key

showShipModel: <role>
// shows a rotating model of a ship with the role given
// role refers to a value in one of shipdata.plist's entries'
// roles key value pair

setMissionMusic: <filename>
// plays the music file given
// if it exists within any OXP's Music folder

setMissionImage: <filename>
// displays the picture file given
// if it exists within any OXP's Images folder

setMissionChoices: <missiontext.plist key>
// sets the array of choices presented at the bottom of the mission page to those described in the
// entry in missiontext.plist that corresponds to the key given

resetMissionChoice
// makes missionChoice undefined

setMissionDescription: <missiontext.plist key>
// sets the short description given on the player's manifest screen

clearMissionDescription
// clears the short description

Looking for, and adding ships

checkForShips: <role>
// returns the number of ships found in the current system that match the role
// this number can be queried with shipsFound_number

addShips: <role> <number>
// causes a number of ships matching the given role to appear near the withpoint

addSystemShips: <role> <number> <position>
// causes a number of ships matching the given role to appear near a point
// on a line from the witchpoint to the planet's station. <position> should be a floating point
// number where 0.0  represents the witchpoint and 1.0 represents the station

addShipsAt: <role> <number> <coordinate scheme> <x> <y> <z>
// causes a number of ships matching the given role to appear near a point
// defined by the <coordinate scheme> and the floating point coordinates x,y and z
// <coordinate scheme> consists of a three letter code:
// 
// The first letter indicates the feature that is the origin of the coordinate system.
// w => witchpoint
// s => sun
// p => planet
// 
// The next letter indicates the feature on the 'z' axis of the coordinate system.
// w => witchpoint
// s => sun
// p => planet
// 
// Then the 'y' axis of the system is normal to the plane formed by the planet, sun and witchpoint.
// And the 'x' axis of the system is normal to the y and z axes.
// So:
// ps:  z axis = (planet -> sun)  y axis = normal to (planet - sun - witchpoint)  x axis = normal to y and z axes
// pw:  z axis = (planet -> witchpoint)  y axis = normal to (planet - witchpoint - sun)  x axis = normal to y and z axes
// sp:  z axis = (sun -> planet)  y axis = normal to (sun - planet - witchpoint)  x axis = normal to y and z axes
// sw:  z axis = (sun -> witchpoint)  y axis = normal to (sun - witchpoint - planet)  x axis = normal to y and z axes
// wp:  z axis = (witchpoint -> planet)  y axis = normal to (witchpoint - planet - sun)  x axis = normal to y and z axes
// ws:  z axis = (witchpoint -> sun)  y axis = normal to (witchpoint - sun - planet)  x axis = normal to y and z axes
// 
// The third letter denotes the units used:
// m:  meters
// p:  planetary radii
// s:  solar radii
// u:  distance between first two features indicated (eg. spu means that u = distance from sun to the planet)
// 
// in witchspace (== no sun) coordinates are absolute irrespective of the system used

addShipsAtPrecisely: <role> <number> <coordinate scheme> <x> <y> <z>
// This adds the ships as close as possible to the specified point

setSunNovaIn: <seconds>
// Sets the sun to go nova after the given time in seconds

setPlanetinfo: <key> <value>
// sets an override to the planetinfo.plist entry for the current system
// the value for the given key is set to match the value
// (see planetinfo.plist)

Mission Variables

set: mission_variable <value>
// sets the mission_variable to the value given
// the value could be a particular string or numeric value

increment: mission_variable
// increases the mission variable's value by 1.0

decrement: mission_variable
// decreases the mission variable's value by 1.0

player state methods

awardCargo: # Commodity
awardCredits: # //in deciCredits.
awardEquipment: EQ_SOME_PIECE_OF_KIT
awardFuel: # //Changes fuel level, maximum up to 7.0LY or down to 0.0.
awardShipKills: #
commsMessage: Happy Newyear!
commsMessage: [text] --refers to entry in descriptions.plist.
launchFromStation
removeAllCargo
setLegalStatus: #
setFuelLeak: #
testForEquipment: EQ_COOL_TOY
useSpecialCargo: A load full of '['thargoid_curses']'

other methods

So far I have summed up the methods used in script.plists, next are the other sources. 
spawn: <role> #
Spawns # entities of the type 'role', randomly clustered around the calling entity.
clock_number
now returns the game-time in seconds as a float rather than an integer. 
clock_secs_number
returns the game-time in seconds as an integer. 
fuel_level_number 
returns the fuel level in LY as a float 
dockedStationName_string 
returns the displayed name of the station, or 'NONE' if the player isn't docked 
systeminfodata_number

Internal Links

OXP_howto_AI.

This article is a stub. You can help EliteWiki by expanding it.