Difference between revisions of "Methods"
Eric Walch (talk | contribs) (added picture info) |
SimonRaven (talk | contribs) (→Communications: fix i.e. (which means "that is", not "for example"); fix external link) |
||
Line 314: | Line 314: | ||
//[Thargoid_curses] - Random Thargoid curses. | //[Thargoid_curses] - Random Thargoid curses. | ||
//[police_attack_warning] - Random warning of immediate(?) attack. | //[police_attack_warning] - Random warning of immediate(?) attack. | ||
− | //%H - Will display the current system name | + | //%H - Will display the current system name; e.g., Isinor. |
− | //%I - Displays the current system name with "ian" attached | + | //%I - Displays the current system name with "ian" attached; e.g., Isinorian. |
//%R - Random word. | //%R - Random word. | ||
− | // An (incomplete) excell sheet detailing the default [http://home.tiscali.nl/arexack/descriptions%20array.xls | + | // An (incomplete) excell sheet detailing the default [http://home.tiscali.nl/arexack/descriptions%20array.xls descriptions.plist] |
// | // | ||
// | // |
Revision as of 21:13, 15 June 2008
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 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 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 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. 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. //[Thanks-for-assist] - Err, thanks the player for their assistance. //[Thargoid_curses] - Random Thargoid curses. //[police_attack_warning] - Random warning of immediate(?) attack. //%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 // // //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 // 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.
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: Debug_Keys
AI
Note that although most of these methods affect the player, some can also be utilised by an AI.