Methods

Legacy Scripting

This page is about legacy scripting. After Oolite 1.65 this is replaced by the much more flexible Java Scripts. Legacy scripting is still fully functional; however it is advised to not use it for new work. All functionality can be duplicated - often more effectively - with Javascript in Oolite 1.77 or later.

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

Starting with version 1.71 you can also use:
clearMissionScreen
// it clears the image, music and shipmodel in one singlee command.
// same as:  setMissionImage: none, showShipModel: none, setMissionMusic: none.
(In 1.70 this command also did clear the mission choices.)

Note that setMissionImage: displays an image OVER a ship displayed with showShipModel:. 
This means a normal image will cover the ship. To use both, an image must be used with a transparent main page 
and all the info must be in the alpha channel of the picture.

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

Star charts

addMissionDestination: <pnum>
// causes the given planets to be marked on the short and long range star charts
// multiple planet numbers may be supplied separated by spaces

removeMissionDestination: <pnum>
// causes the given planets to have their marks remove from the short and long range star charts
// multiple planet numbers may be supplied separated by spaces

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 witchpoint
// this is the only method in this category that calls Oolite's internal system populator, 
// which means some plist settings might be overridden, and the appearing ships will create
// a space distortion bubble as they enter the system.

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

addShipsWithinRadius: <role> <number> <coordinate-system> <x> <y> <z> <radius in metres>
// Example:
// "addShipsWithinRadius: asteroid 48 wpm 0 0 15000 5000"
// would add a 5km-wide asteroid field with 48 asteroids at a position roughly 15000m towards
// the planet from the witchpoint.

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)
//
// eg setPlanetinfo: description=a very dull planet
// (Note the '=' is required)

setSpecificPlanetInfo: <gnum>=<pnum>=<key>=<value>
// sets an override to the planetinfo.plist entry for the system
// specified by galaxy gnum and planet pnum
//
// eg setSpecificPlanetInfo: 0=7=description=Lave is not a very dull planet
// (Note the '=' is required between all 4 values)

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

blowUpStation
// blows up the main station. If there are more stations, the nearest becomes the main station were you can save files.
// the removal of the station is stored in the save-file

Mission Variables

As of 1.65? these methods can also be used with script local variables by suppling a "local_" variable rather than a "mission_" varaible. The difference is that "mission_" variables are stored within a save file and "local_" variables are not saved with the game and are only valid localy, within a mission script.

set: mission_variable <value>
// sets the mission_variable to the value given
// the value can be a particular string or numeric value,
// or a queriable state

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

Be aware that increment and decrement result in values with integer representation like "1", "2" and that "add" and "subtract" result in valus with a real representation like "1.000000" and "2.000000". This is important by comparing values with an equal statement.

Player rewards and penalties

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

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

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

setLegalStatus: <number>
// Sets the bounty on the player's head. See here - and several later posts - for an explanation.

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
// only positive numbers are allowed.

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
// STATUS_LAUNCHING is skipped, so no script action on that moment.

Communications

commsMessage: message 
// sends the player a message in the form of a text string.
// 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
//
consoleMessage3s: message 
consoleMessage6s: message 
// sends the player a message in the form of a text string with 3 or 6 second duration.
// 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
// difference with commsMessage is that it is not stored in the comms file and can not be recalled by the player.
//
Special Expansions
//As well as [commander_name] the following are available;
//[commander_shipname] - Displays the name of the players ship, as specified by shipdata.plist.
//{commander_rank] - Displays the players Elite rating.
//[commander_legal_status] - Displays the players current legal status.
//[x], where x is a key in descriptions.plist.
//%H - Will display the current system name; e.g., Isinor.
//%I - Displays the current system name with "ian" attached; e.g., Isinorian.
//%R - Random word. 
// An (incomplete) excell sheet detailing the default descriptions.plist
// See also the mission text page
//
//
//custom variable texts can be created by creating an array in a custom descriptions.plist,
//these can then be referenced like the above examples.
//Example of descriptions.plist entry: 
//<key>beg-for-mercy</key>
//	<array>
//		<string>No!</string>
//		<string>Help! Anyone!</string>
//		<string>etc, etc</string>
//	</array>

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_MANIFEST
// GUI_SCREEN_MARKET //doesnt work (v1.69.1)
// GUI_SCREEN_CONTRACTS 
// GUI_SCREEN_MISSION
// GUI_SCREEN_OPTIONS
// GUI_SCREEN_SHORT_RANGE_CHART
// GUI_SCREEN_STATUS
// GUI_SCREEN_SYSTEM_DATA
// GUI_SCREEN_SHIPYARD 
// 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 - see "setLegalStatus: <number>" below for link to explanation

// 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 always be the same for a certain system.

Starting with version 1.69 you can also use d256 numbers:
// d256_number
// returns a random value from 0 to 255

// pseudoFixedD256_number
// returns a random number from 0 to 255 that will always be the same for a certain system.

• How random is random (2013)

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. It resets on a witchspace jump (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. The message is written to the console regardless
// of whether debugOn has been performed or not. For GNUstep versions of Oolite, the console
// is a file called stderr.txt located in the game's installation directory. Mission variables
// and queriable states may be included in the message, eg:
//
// debugMessage: current galaxy is [galaxy_number]

debug keys
// pause game to enable debug keys.
// press d for full debug-mode.
// press b for collision debug-mode.
// press c for octree debug-mode.
// press o for an object dump.
// a full list: Debugging Keys

AI

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

OXP howto AI (.plist AI's)
AI (.plist AI's)
AI_methods (.plist AI's)
Oolite Javascript Reference: PriorityAI Documentation
Oolite PriorityAI Tutorial (Javascript AI's)