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

spawn: <role> <number>
// adds a number of ships matching <role> near the ship
// that's the target of this script (as script_actions or death_actions)

spawnShip: <shipdata.plist key>
// adds a ship with the unique shipdata.plist key given
// the position and facing of the ship are determined by a spawn dictionary in the
// ship's shipdata.plist entry with position and facing_position as strings describing
// coordinates according to one of the schemes above

Changing the universe

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

reset: mission_variable <value>
// sets the mission_variable to be undefined

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

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

add: mission_variable <value>
// adds the value given to the mission_variable
// the value can be a number or a queriable state
// like shipsFound_number

subtract: mission_variable <value>
// subtracts the value given from the mission_variable
// the value can be a number or a queriable state
// like shipsFound_number

Player rewards and penalties

These methods work on the player, not any other ship.

awardCredits: <number>
// awards number of tenths of credits.

awardShipKills: <number>
// Adds to the number of kills accredited to the player

setLegalStatus: <number>
// Sets the bounty on the player's head.

setFuelLeak: <amount>
// removes this amount from the fuel tank every second
// until the tanks drain and self-seal

awardFuel: <amount>
// The amount can be positive or negative, expressed in LY of range
// the fuel level is adjusted to a maximum of 7.0LY and minimum of 0.0.

Equipment

awardEquipment: <equipment key>
// if the player doesn't have the equipment already
// and their ship can be equipped witth it then this fits the
// player's ship with the equipment given
// valid keys can be found in equipment.plist (they all begin EQ_):-
//	EQ_FUEL
//	EQ_MISSILE
//	EQ_CARGO_BAY
//	EQ_ECM
//	EQ_FUEL_SCOOPS
//	EQ_ESCAPE_POD
//	EQ_ENERGY_BOMB
//	EQ_ENERGY_UNIT
//	EQ_NAVAL_ENERGY_UNIT
//	EQ_DOCK_COMP
//	EQ_GAL_DRIVE
//	EQ_CLOAKING_DEVICE
//	EQ_PASSENGER_BERTH
//	EQ_HARDENED_MISSILE
//	EQ_FUEL_INJECTION
//	EQ_SCANNER_SHOW_MISSILE_TARGET
//	EQ_MULTI_TARGET
//	EQ_ADVANCED_COMPASS
//	EQ_QC_MINE
//	EQ_SHIELD_BOOSTER
//	EQ_NAVAL_SHIELD_BOOSTER
//	EQ_WEAPON_TWIN_PLASMA_CANNON
//	EQ_MILITARY_JAMMER
//	EQ_MILITARY_SCANNER_FILTER

removeEquipment: <equipment key>
// removes the indicated equipment from the player's ship

testForEquipment: <equipment key>
// tests whether the player ship has a piece of equipment installed
// returns the result in foundEquipment_bool

Cargo

awardCargo: <amount> <Commodity name>
// awards a quantity of the cargo named
// the cargo name must match the name in commodities.plist exactly

removeAllCargo
// removes all cargo from the hold with no compensation to the player
// any special cargo is also removed (see below) restoring use of the cargo bay
// Gold, Platinum, and Gemstones are unaffected (they're in the cabin safe).

useSpecialCargo: <description of cargo>
// fills the cargo bay withthe cargo described effectively
// disabling the use of the cargo bay until the cargo is removed

Special

ejectItem: <shipdata.plist key>  
// Creates a ship or other entity from shipdata.plist and ejects from
// the ship's eft hatch

launchFromStation
// forces the player ship to launch

Communications

commsMessage: message 
// sends the player a message
// if the message contains elements enclosed in square brackets [like_this]
// that corresponds to a mission_variable or keys in descriptions.plist
// or to special expansions like [commander_name] then these are expanded
// and substituted into the original message

other methods

Some other methods that could be usefull in scripting. 

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
?
dealEnergyDamageWithinDesiredRange //Needs desiredRange to be set first, then deals weaponEnergy(Shipdata.plist) damage within this sphere.
becomeEnergyBlast  //Used in the Qbomb.
 becomeExplosion    ///
The entity model is replaced by an explosion.
 scriptActionOnTarget:(NSString*) action 
Will cause immediate reaction to any changes this makes.

AI

Note that although most of these methods affect the player some can also be usefully utilised by an AI. OXP_howto_AI.

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