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

resetScriptTimer
// resets a timer for scripting purposes 'deprecated - do not use

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

sendAllShipsAway
// Makes all the ships in the system hyperspace away

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)

addPlanet: <planetinfo.plist key>
// adds a planet to the universe from data in planetinfo.plist.

addMoon: <planetinfo.plist key>
// adds a moon to the universe from data in planetinfo.plist.
// (Moons do not get an atmosphere or clouds like planets).

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 aft 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

Querying states

Player status

// mission_string
// returns the key for the current mission

// status_string
// returns one of:
// STATUS_AUTOPILOT_ENGAGED
// STATUS_DEAD
// STATUS_DEMO
// STATUS_DOCKING
// STATUS_DOCKED
// STATUS_EFFECT
// STATUS_ENTERING_WITCHSPACE
// STATUS_ESCAPE_SEQUENCE
// STATUS_EXITING_WITCHSPACE
// STATUS_EXPERIMENTAL
// STATUS_IN_FLIGHT
// STATUS_IN_HOLD
// STATUS_INACTIVE
// STATUS_LAUNCHING
// STATUS_TEST
// STATUS_WITCHSPACE_COUNTDOWN
// UNDEFINED

// gui_screen_string
// returns one of:
// GUI_SCREEN_EQUIP_SHIP
// GUI_SCREEN_INTRO1
// GUI_SCREEN_INTRO2
// GUI_SCREEN_INVENTORY
// GUI_SCREEN_LONG_RANGE_CHART
// GUI_SCREEN_MAIN
// GUI_SCREEN_MARKET
// GUI_SCREEN_MISSION
// GUI_SCREEN_OPTIONS
// GUI_SCREEN_SHORT_RANGE_CHART
// GUI_SCREEN_STATUS
// GUI_SCREEN_SYSTEM_DATA
// UNDEFINED

// galaxy_number
// returns a value between 0 and 7

// planet_number
// returns a value between 0 and 255

// score_number
// returns the number of the player's current ship kills

// credits_number
// returns the player's credits x10

// legalStatus_number
// returns the bounty on the players head

// fuel_level_number
// returns the fuel level in LY

// dockedAtMainStation_bool
// returns YES if docked at a systems main station, NO otherwise

// dockedStationName_string
// returns NONE if the player isn't docked, the name of the station (from shipdata.plist) if it is, UNKNOWN otherwise

Results from other methods

// shipsFound_number
// returns the number of ships found by checkForShips:

// foundEquipment_bool
// returns the result of the last testForEquipment
// returns YES if the equipment was found, NO otherwise
 
// missionChoice_string
// returns the result of the player's selection from a list of missionChoices
// returns UNDEFINED or the key for the chosen option

Random numbers

// d100_number
// returns a random value from 0 to 99

// pseudoFixedD100_number
// returns a random number from 0 to 99 that will
// remain fixed as long as the player remains in this system

Time

// clock_number
// returns the game time in seconds
// clock_secs_number
// returns the game time in seconds
// clock_mins_number
// returns the game time in minutes
// clock_hours_number
// returns the game time in hours
// clock_days_number
// returns the game time in days

System states

// sunWillGoNova_bool
// returns whether the sun is going to go nova, either YES or NO

// sunGoneNova_bool
// returns whether the sun has gone nova, either YES or NO

// systemGovernment_string
// returns one of:-
// Anarchy
// Feudal
// Multi-Government
// Dictatorship
// Communist
// Confederacy
// Democracy
// Corporate State

// systemGovernment_number
// returns a value from 0 to 7

// systemEconomy_number
// returns a value from 0 to 7

// systemTechLevel_number
// returns a value from 0 to 14

// systemPopulation_number
// returns a value representing the system's population

// systemProductivity_number
// returns a value representing the system's productivity

// scriptTimer_number
// returns the script timer's current value in seconds (deprecated - do not use)

Debugging scripts

debugOn
// sends script debugging messages to the console.

debugOff
// cancels script debugging messages

debugMessage: <message>
// sends the given message to the console.

AI

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