Methods
From Elite Wiki
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>
Contents
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 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.
Querying states
Player status
// mission_string // returns the key for the current mission // status_string // returns one of: // TODO // gui_screen_string // returns one of: // TODO // 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, [station name] 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
// scriptTimer_number // returns the script timer's current value in seconds // 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:- // TODO // 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
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.
- This article is a stub. You can help EliteWiki by expanding it.
