Difference between revisions of "SCP SEXPs"
From FreeSpace Wiki
EatThePath (talk | contribs) (→Special: added remove-weapons) |
MatthTheGeek (talk | contribs) (Updated with sexp.html from nightly 20200617_4bb3132) |
||
| Line 1: | Line 1: | ||
This page is a reference of SEXPs that are only available in the SCP version of [[Portal:FRED|FRED]]. This also includes any retail SEXPs that have been modified from their original behaviour. To see the list of SEXPs that are available in retail FRED, go to the [[Retail SEXPs]] page. For tips and examples for how to properly use a SEXP when building missions, as well as warnings about potential pitfalls, follow the link to the detail page for the SEXP you are interested in. | This page is a reference of SEXPs that are only available in the SCP version of [[Portal:FRED|FRED]]. This also includes any retail SEXPs that have been modified from their original behaviour. To see the list of SEXPs that are available in retail FRED, go to the [[Retail SEXPs]] page. For tips and examples for how to properly use a SEXP when building missions, as well as warnings about potential pitfalls, follow the link to the detail page for the SEXP you are interested in. | ||
| − | == | + | =Objectives= |
| + | ===[[was-destroyed-by-delay]]=== | ||
| + | Was destroyed by delay (Boolean operator) | ||
| + | Becomes true <delay> seconds after all specified ships have been destroyed by the specified first ship. | ||
| + | |||
| + | Returns a boolean value. Takes 3 or more arguments... | ||
| + | 1: Time delay in seconds (see above). | ||
| + | 2: Ship that should have destroyed the other ships (see below). | ||
| + | Rest: Name of ships to check status of. | ||
| + | ===[[is-disarmed-delay]]=== | ||
| + | Is disarmed delay (Boolean operator) | ||
| + | Becomes true <delay> seconds after the specified ship(s) are disarmed. A ship is disarmed when all of its turret subsystems are destroyed. All ships must be disarmed for this function to return true. | ||
| + | |||
| + | Returns a boolean value. Takes 2 or more arguments... | ||
| + | 1: Time delay is seconds (see above). | ||
| + | Rest: Names of ships to check disarmed status of. | ||
| + | ===[[is-nav-visited]]=== | ||
| + | is-nav-visited | ||
| + | Returns true when the player has visited the given navpoint (Has closed to within 1000m of it). Takes 1 argument... | ||
| + | 1: The name of the navpoint | ||
===[[percent-ships-disabled]]=== | ===[[percent-ships-disabled]]=== | ||
percent-ships-disabled | percent-ships-disabled | ||
| − | + | Boolean function which returns true if the percentage of ships in the listed ships which have been disabled is greater or equal to the given percentage. | |
| − | |||
| − | |||
| − | + | Takes 2 or more arguments... | |
| − | + | 1: Percentge of disabled ships at which this function will return true. | |
| − | + | 2+: List of ships whose disabled status should be determined. | |
===[[percent-ships-disarmed]]=== | ===[[percent-ships-disarmed]]=== | ||
percent-ships-disarmed | percent-ships-disarmed | ||
| − | + | Boolean function which returns true if the percentage of ships in the listed ships which have been disarmed is greater or equal to the given percentage. | |
| − | + | ||
| − | + | Takes 2 or more arguments... | |
| + | 1: Percentge of disarmed ships at which this function will return true. | ||
| + | 2+: List of ships whose disarmed status should be determined. | ||
| + | ===[[percent-ships-arrived]]=== | ||
| + | percent-ships-arrived | ||
| + | Boolean function which returns true if the percentage of ships in the listed ships and wings which have arrived is greater or equal to the given percentage. For wings, all ships of all waves are used for calculation for the total possible ships to arrive. | ||
| + | |||
| + | Takes 2 or more arguments... | ||
| + | 1: Percentge of arriving ships at which this function will return true. | ||
| + | 2+: List of ships/wings whose arrival status should be determined. | ||
| + | =Time= | ||
| + | ===[[mission-time-msecs]]=== | ||
| + | Mission time, in milliseconds (Time operator) | ||
| + | Returns the current time into the mission, in milliseconds. Useful for more fine-grained timing than possible with normal second-based sexps. (Tip: when an event occurs, assign the result of mission-time-msecs to a variable. Then, in another event, wait until mission-time-msecs is greater than the value of that variable plus some delay amount. This second event should be chained or coupled with additional conditions so that it doesn't accidentally fire on an uninitialized variable!) | ||
| − | + | Returns a numeric value. Takes no arguments. | |
| − | + | =Logical= | |
| − | + | ===[[xor]]=== | |
| − | == | + | Xor (Boolean operator) |
| − | + | Xor is true if exactly one of its arguments is true. | |
| − | == | + | |
| + | Returns a boolean value. Takes 2 or more boolean arguments. | ||
| + | ===[[!=]]=== | ||
| + | Not Equal To (Boolean operator) | ||
| + | Is true if the first argument is not equal to any of the subsequent arguments. | ||
| + | |||
| + | Returns a boolean value. Takes 2 or more numeric arguments. | ||
| + | ===[[<=]]=== | ||
| + | Less Than Or Equal To (Boolean operator) | ||
| + | True if the first argument is less than or equal to the subsequent argument(s). | ||
| + | |||
| + | Returns a boolean value. Takes 2 numeric arguments. | ||
===[[string-equals]]=== | ===[[string-equals]]=== | ||
| − | + | String Equals (Boolean operator) | |
| − | + | Is true if all of its arguments are equal. | |
| − | |||
| − | + | Returns a boolean value. Takes 2 or more string arguments. | |
===[[string-greater-than]]=== | ===[[string-greater-than]]=== | ||
| − | + | String Greater Than (Boolean operator) | |
| − | + | True if the first argument is greater than the second argument. | |
| − | |||
| − | + | Returns a boolean value. Takes 2 string arguments. | |
===[[string-less-than]]=== | ===[[string-less-than]]=== | ||
| − | + | String Less Than (Boolean operator) | |
| − | + | True if the first argument is less than the second argument. | |
| − | |||
| − | + | Returns a boolean value. Takes 2 string arguments. | |
| − | ==Arithmetic | + | ===[[perform-actions]]=== |
| + | perform-actions | ||
| + | This sexp allows actions to be performed as part of a conditional test. It is most useful for assigning variables or performing some sort of pre-test action within the conditional part of "when", etc. It works well as the first branch of an "and" sexp, provided it returns true so as to not affect the return value of the "and". | ||
| + | |||
| + | Returns a boolean value. Takes 2 or more arguments. | ||
| + | 1: A boolean value to return after all successive actions have been performed. | ||
| + | Rest: Actions to perform, which would normally appear in a "when" sexp. | ||
| + | |||
| + | =Arithmetic= | ||
===[[rand-multiple]]=== | ===[[rand-multiple]]=== | ||
| − | + | Rand-multiple (Arithmetic operator) | |
| − | + | Gets a random number. This number can and will change between successive calls to this sexp. | |
| − | + | ||
| − | + | Returns a number. Takes 2 or 3 numeric arguments... | |
| − | + | 1: Low range of random number. | |
| − | + | 2: High range of random number. | |
| − | + | 3: (optional) A seed to use when generating numbers. (Setting this to 0 is the same as having no seed at all) | |
| − | |||
===[[abs]]=== | ===[[abs]]=== | ||
| − | + | Absolute value (Arithmetic operator) | |
| − | + | Returns the absolute value of a number. Takes 1 numeric argument. | |
| − | + | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
===[[avg]]=== | ===[[avg]]=== | ||
| − | + | Average value (Arithmetic operator) | |
| − | + | Returns the average (rounded to the nearest integer) of a set of numbers. Takes 1 or more numeric arguments. | |
| − | + | ||
| − | == | + | ===[[signum]]=== |
| − | ===[[is- | + | Signum (Arithmetic operator) |
| − | is- | + | Returns the sign of a number: -1 if it is negative, 0 if it is 0, and 1 if it is positive. Takes one argument. |
| − | + | ||
| − | + | ===[[is-nan]]=== | |
| − | + | Is-NaN (Arithmetic operator) | |
| − | + | Returns true if the argument is NaN (not-a-number). This can happen e.g. when checking statistics for ships that have departed. Takes one argument. | |
| − | + | ||
| − | + | ===[[nan-to-number]]=== | |
| + | NaN-to-Number (Arithmetic operator) | ||
| + | Used to safely filter NaN values from arithmetic operations, which would otherwise pass NaN up the sexp tree. If the argument is a number, it is returned. If the argument is NaN, a zero is returned. Takes one argument. | ||
| + | |||
| + | ===[[set-bit]]=== | ||
| + | set-bit | ||
| + | Turns on (sets to 1) a certain bit in the provided number, returning the result. This allows numbers to store up to 32 boolean flags, from 2^0 to 2^31. Takes 2 numeric arguments... | ||
| + | 1: The number whose bit should be set | ||
| + | 2: The index of the bit to set. Valid indexes are between 0 and 31, inclusive. | ||
| + | |||
| + | ===[[unset-bit]]=== | ||
| + | unset-bit | ||
| + | Turns off (sets to 0) a certain bit in the provided number, returning the result. This allows numbers to store up to 32 boolean flags, from 2^0 to 2^31. Takes 2 numeric arguments... | ||
| + | 1: The number whose bit should be unset | ||
| + | 2: The index of the bit to unset. Valid indexes are between 0 and 31, inclusive. | ||
| + | |||
| + | ===[[is-bit-set]]=== | ||
| + | is-bit-set | ||
| + | Returns true if the specified bit is set (equal to 1) in the provided number. Takes 2 numeric arguments... | ||
| + | 1: The number whose bit should be tested | ||
| + | 2: The index of the bit to test. Valid indexes are between 0 and 31, inclusive. | ||
| + | |||
| + | ===[[bitwise-and]]=== | ||
| + | bitwise-and | ||
| + | Performs the bitwise AND operator on its arguments. This is the same as if the logical AND operator was performed on each successive bit. Takes 2 or more numeric arguments. | ||
| + | |||
| + | ===[[bitwise-or]]=== | ||
| + | bitwise-or | ||
| + | Performs the bitwise OR operator on its arguments. This is the same as if the logical OR operator was performed on each successive bit. Takes 2 or more numeric arguments. | ||
| + | |||
| + | ===[[bitwise-not]]=== | ||
| + | bitwise-not | ||
| + | Performs the bitwise NOT operator on its argument. This is the same as if the logical NOT operator was performed on each successive bit. | ||
| + | |||
| + | Note that the operation is performed as if on an unsigned integer whose maximum value is INT_MAX. In other words, there is no need to worry about the sign bit. | ||
| + | |||
| + | Takes only 1 argument. | ||
| + | |||
| + | ===[[bitwise-xor]]=== | ||
| + | bitwise-xor | ||
| + | Performs the bitwise XOR operator on its arguments. This is the same as if the logical XOR operator was performed on each successive bit. Takes 2 or more numeric arguments. | ||
| + | |||
| + | =Status= | ||
| + | ==Mission== | ||
| + | ===[[num-ships-in-battle]]=== | ||
| + | num-ships-in-battle | ||
| + | Returns the number of ships in battle or the number of ships in battle out of a list of teams, wings, and ships. Takes 1 or more arguments... | ||
| + | (all): Teams, Wings, and Ships to query (optional) | ||
| + | ===[[num-ships-in-wing]]=== | ||
| + | num-ships-in-wing | ||
| + | Returns the number of ships in battle which belong to a given wing. Takes 1 or more arguments... | ||
| + | (all): Name of wing(s) to check | ||
| + | ===[[directive-value]]=== | ||
| + | directive-value | ||
| + | Causes a value to appear in the directive count | ||
| + | Always returns true. Takes 1 or more arguments... | ||
| + | |||
| + | 1: Value | ||
| + | 2: (Optional) Ignore the directive count set by any earlier SEXPs in the event. If set to false it will add instead | ||
| + | |||
| + | ===[[get-hotkey]]=== | ||
| + | get-hotkey | ||
| + | Returns the hotkey integer of the ship or wing. Return values range from -1 to 7. | ||
| + | Return of -1 is no hotkey, return of 0 is F5, return of 1 is F6, ..., return of 7 is F12. | ||
| + | |||
| + | Takes 1 argument. | ||
| + | |||
| + | 1: Ship or wing to get hotkey. | ||
| + | |||
| + | ==Player== | ||
| + | ===[[was-promotion-granted]]=== | ||
| + | Was promotion granted (Boolean operator) | ||
| + | Returns true if a promotion was granted via the 'Grant promotion' operator in the mission. | ||
| + | |||
| + | Returns a boolean value. Takes no arguments. | ||
| + | ===[[was-medal-granted]]=== | ||
| + | Was medal granted (Boolean operator) | ||
| + | Returns true if a medal was granted via via the 'Grant medal' operator in the mission. If you provide the optional argument to this operator, then true is only returned if the specified medal was granted. | ||
| + | |||
| + | Returns a boolean value. Takes 0 or 1 arguments... | ||
| + | 1: Name of medal to specifically check for (optional). | ||
| + | ===[[num_assists]]=== | ||
| + | num-assists | ||
| + | Returns the # of assists a player has. The ship specified in the first field should be the ship the player is in. | ||
| + | So, for single player, this would be Alpha 1. For multiplayer, it can be any ship with a player in it. If, at any | ||
| + | time there is no player in a given ship, this sexpression will return 0 | ||
| + | ===[[ship_score]]=== | ||
| + | ship-score | ||
| + | Returns the score a player has. The ship specified in the first field should be the ship the player is in. | ||
| + | So, for single player, this would be Alpha 1. For multiplayer, it can be any ship with a player in it. If, at any | ||
| + | time there is no player in a given ship, this sexpression will return 0 | ||
| + | ==Multiplayer== | ||
| + | ===[[ship-deaths]]=== | ||
| + | ship-deaths | ||
| + | Returns the # times a ship that is a player start has died. | ||
| + | The ship specified in the first field should be the ship that could have a player in.it | ||
| + | Only really useful for multiplayer. | ||
| + | ===[[respawns-left]]=== | ||
| + | respawns-left | ||
| + | Returns the # respawns a player (or AI that could have been a player) has remaining. | ||
| + | The ship specified in the first field should be the player start. | ||
| + | Only really useful for multiplayer. | ||
| + | ===[[is-player]]=== | ||
| + | is-player | ||
| + | Returns true if all the ships specified are currently under control of a player. | ||
| + | 1 (SinglePlayer) When true ships under AI control return false even if they are the player ship | ||
| + | (Multiplayer) When true ships that are respawning return true if the player is still connected | ||
| + | Rest List of ships to test | ||
| + | ==Ship Status== | ||
| + | ===[[is-in-mission]]=== | ||
| + | Is-In-Mission (Status operator) | ||
| + | Checks whether a given ship is presently in the mission. This sexp doesn't check the arrival list or exited status; it only tests to see if the ship is active. This means that internally the sexp only returns SEXP_TRUE or SEXP_FALSE and does not use any of the special shortcut values. This is useful for ships created with ship-create, as those ships will not have used the conventional ship arrival list. | ||
| + | |||
| + | Takes 1 or more string arguments, which are checked against the ship list. (If more than 1 argument is specified, the sexp will only evaluate to true if all ships are in the mission simultaneously.) | ||
| + | ===[[is-docked]]=== | ||
| + | Is-Docked (Status operator) | ||
| + | Checks whether the specified ships are currently docked. This sexp is different from has-docked-delay, which will return true if the ships have docked at any point in the past. The has-docked-delay sexp checks the mission log, whereas the is-docked sexp examines the actual dockpoints. | ||
| + | |||
| + | Takes 1 or more arguments. (If more than 2 arguments are specified, the sexp will only evaluate to true if all ships are docked simultaneously.) | ||
| + | If a single argument is supplied, the sexp will evaluate to true if anything is docked to the host ship. | ||
| + | 1: The host ship. | ||
| + | Rest: Ship to check as docked to the host ship. | ||
===[[is-ship-stealthy]]=== | ===[[is-ship-stealthy]]=== | ||
is-ship-stealthy | is-ship-stealthy | ||
| − | + | Check whether ship is currently stealthy. | |
| − | + | True if stealth flag set, false otherwise. Takes 1 argument... | |
| − | + | 1: Name of ship to check | |
| − | + | ||
===[[is-friendly-stealth-visible]]=== | ===[[is-friendly-stealth-visible]]=== | ||
is-friendly-stealth-visible | is-friendly-stealth-visible | ||
| − | + | Check whether ship will be visible to radar as a stealth friendly. | |
| − | + | Takes 1 argument... | |
| − | + | 1: Name of ship to check | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
===[[is-ai-class]]=== | ===[[is-ai-class]]=== | ||
| − | + | Is AI Class (Boolean operator) | |
| − | + | True if ship or ship subsystem(s) is/are all of the specified AI class. | |
| − | |||
| − | + | Returns a boolean value. Takes 2 or more arguments... | |
| − | + | 1: AI class ("None", "Coward", "Lieutenant", etc.) | |
| − | + | 2: Name of ship to check. | |
| − | + | Rest: Name of ship subsystem(s) to check (optional) | |
===[[is-ship-type]]=== | ===[[is-ship-type]]=== | ||
| − | + | Is Ship Type (Boolean operator) | |
| − | + | True if ship or ships is/are all of the specified ship type. | |
| − | + | ||
| + | Returns a boolean value. Takes 2 or more arguments... | ||
| + | 1: Ship type ("fighter", "bomber", etc.) | ||
| + | 2: Name of ship to check. | ||
| − | |||
| − | |||
| − | |||
===[[is-ship-class]]=== | ===[[is-ship-class]]=== | ||
| − | + | Is Ship Class (Boolean operator) | |
| − | + | True if ship or ships is/are all of the specified ship class. | |
| − | + | ||
| + | Returns a boolean value. Takes 2 or more arguments... | ||
| + | 1: Ship class | ||
| + | 2: Name of ship to check. | ||
| + | |||
| + | ===[[is-facing]]=== | ||
| + | Is Facing (Boolean training operator) | ||
| + | Is true as long as the second object is within the first ship's specified forward cone. A forward cone is defined as any point that the angle between the vector of the ship and point, and the forward facing vector is within the given angle. If the distance between the two is greater than the fourthparameter, this will return false. | ||
| + | |||
| + | Returns a boolean value. Takes 3 or 4 argument... | ||
| + | 1: Ship to check from. | ||
| + | 2: Object to check is within forward cone. | ||
| + | 3: Angle in degrees of the forward cone. | ||
| + | 4: Range in meters (optional). | ||
| + | ===[[are-ship-flags-set]]=== | ||
| + | Are ship flags set (Boolean operator) | ||
| + | Returns true if all of the specified flags have been set for this particular ship. | ||
| + | |||
| + | Takes 2 or more arguments... | ||
| + | 1: Name of the ship. Rest: Ship, object or ai flags which might be set for this ship.. | ||
| + | ===[[get-throttle-speed]]=== | ||
| + | Get-Throttle-Speed (Training operator) | ||
| + | Returns the current throttle speed that the ship has been set to. Reverse speeds are returned as a negative value. Takes 1 argument... | ||
| + | 1: Name of the player ship to check the throttle value for. | ||
| + | ===[[current-speed]]=== | ||
| + | current-speed | ||
| + | Returns the speed of the given object. Takes 1 argument... | ||
| + | 1: Name of the object | ||
| + | ===[[is-nav-linked]]=== | ||
| + | is-nav-linked | ||
| + | Determines if a ship is linked for autopilot ("set-nav-carry" or "set-nav-needslink" + linked)Takes 1 argument... | ||
| + | 1: Ship to check | ||
| + | |||
| + | ==Weapons, Shields, and Engines== | ||
| + | ===[[has-primary-weapon]]=== | ||
| + | has-primary-weapon | ||
| + | Returns true if the primary weapon bank specified has any of the weapons listed. Takes 3 or more arguments... | ||
| + | |||
| + | 1: Ship name | ||
| + | 2: Weapon bank number (This is a zero-based index. The first bank is numbered 0.) | ||
| + | Rest: Weapon name | ||
| + | |||
| + | ===[[has-secondary-weapon]]=== | ||
| + | has-secondary-weapon | ||
| + | Returns true if the secondary weapon bank specified has any of the weapons listed. Takes 3 or more arguments... | ||
| + | |||
| + | 1: Ship name | ||
| + | 2: Weapon bank number (This is a zero-based index. The first bank is numbered 0.) | ||
| + | Rest: Weapon name | ||
| + | |||
| + | ===[[primary-fired-since]]=== | ||
| + | primary-fired-since | ||
| + | Returns true if the primary weapon bank specified has been fired within the supplied window of time. Takes 3 arguments... | ||
| + | |||
| + | 1: Ship name | ||
| + | 2: Weapon bank number (This is a zero-based index. The first bank is numbered 0.) | ||
| + | 3: Time period to check if the weapon was fired (in milliseconds) | ||
| + | |||
| + | ===[[secondary-fired-since]]=== | ||
| + | secondary-fired-since | ||
| + | Returns true if the secondary weapon bank specified has been fired within the supplied window of time. Takes 3 arguments... | ||
| + | |||
| + | 1: Ship name | ||
| + | 2: Weapon bank number (This is a zero-based index. The first bank is numbered 0.) | ||
| + | 3: Time period to check if the weapon was fired (in milliseconds) | ||
| − | |||
| − | |||
| − | |||
===[[primary-ammo-pct]]=== | ===[[primary-ammo-pct]]=== | ||
primary-ammo-pct | primary-ammo-pct | ||
| − | + | Returns the percentage of ammo remaining in the specified ballistic primary bank (0 to 100). Non-ballistic primary banks return as 100%. | |
| − | + | 1: Ship name | |
| − | + | 2: Bank to check (from 0 to N-1, where N is the number of primary banks in the ship; N or higher will return the cumulative average for all banks) | |
| − | |||
| − | |||
===[[get-primary-ammo]]=== | ===[[get-primary-ammo]]=== | ||
get-primary-ammo | get-primary-ammo | ||
| − | + | Returns the amount of ammo remaining in the specified bank | |
| − | + | 1: Ship name | |
| − | + | 2: Bank to check (from 0 to N-1, where N is the number of primary banks in the ship; N or higher will return the cumulative total for all banks) | |
| − | |||
===[[get-secondary-ammo]]=== | ===[[get-secondary-ammo]]=== | ||
get-secondary-ammo | get-secondary-ammo | ||
| − | + | Returns the amount of ammo remaining in the specified bank | |
| − | + | 1: Ship name | |
| − | + | 2: Bank to check (from 0 to N-1, where N is the number of secondary banks in the ship; N or higher will return the cumulative total for all banks) | |
| − | + | ===[[get-num-countermeasures]]=== | |
| − | ===[[ | + | get-num-countermeasures |
| − | + | Returns the amount of countermeasures remaining | |
| − | + | 1: Ship name | |
| − | + | ||
| + | ===[[weapon-energy-pct]]=== | ||
| + | Weapon energy left | ||
| + | Returns a ship's current weapon energy as a percentage. | ||
| + | 1: Ship name | ||
| + | |||
| + | ===[[afterburner-energy-pct]]=== | ||
| + | Afterburner left | ||
| + | Returns a ship's current engine energy as a percentage. | ||
| + | 1: Ship name | ||
| + | |||
| + | ===[[is-in-turret-fov]]=== | ||
| + | is-in-turret-fov | ||
| + | Checks whether the given craft is within the field of view of a turret, and optionally within a specified range. Takes 3 to 4 arguments... | ||
| + | 1: Ship being targeted | ||
| + | 2: Ship which carries a turret | ||
| + | 3: Turret to check | ||
| + | 4: Range in meters (optional) | ||
| + | |||
| + | ==Cargo== | ||
| + | ==Damage== | ||
| + | ===[[hits-left-subsystem-generic]]=== | ||
| + | hits-left-subsystem-generic (status operator) | ||
| + | Returns the current level of integrity of a generic subsystem type, as a percentage. A "generic subsystem type" is a subsystem *category*, (for example, Engines), that includes one or more *individual* subsystems (for example, engine01, engine02, and engine03) on a ship. | ||
| − | + | This is the way FreeSpace tests certain subsystem thresholds internally; for example, if the integrity of all engine subsystems (that is, the combined strength of all engines divided by the maximum total strength of all engines) is less than 30%, the player cannot warp out. | |
| − | + | ||
| − | + | Returns a numeric value. Takes 2 arguments... | |
| − | + | 1: Name of ship to check | |
| + | 2: Name of subsystem type to check | ||
| + | |||
| + | ===[[hits-left-subsystem-specific]]=== | ||
| + | hits-left-subsystem-specific (status operator) | ||
| + | Returns the current level of integrity of a specific subsystem, as a percentage. | ||
| + | |||
| + | (If you were looking for the old hits-left-subsystem operator, this is almost certainly the operator you want. The hits-left-subsystem operator suffers from a serious design flaw that causes it to behave like hits-left-subsystem-generic. As such it has been deprecated and will not appear in the operator list; it can only be used if you type it in manually. Old missions using hits-left-subsystem will still work, but mission designers are strongly encouraged to use the new operators instead.) | ||
| + | |||
| + | Returns a numeric value. Takes 2 arguments... | ||
| + | 1: Name of ship to check | ||
| + | 2: Name of subsystem to check | ||
| + | |||
| + | ===[[sim-hits-left]]=== | ||
| + | Simulated Hits left (Status operator) | ||
| + | Returns the current level of the specified ship's simulated hull as a percentage. | ||
| + | |||
| + | Returns a numeric value. Takes 1 argument... | ||
| + | 1: Name of ship to check. | ||
| + | ===[[get-damage-caused]]=== | ||
| + | Get damage caused (Status operator) | ||
| + | Returns the amount of damage one or more ships have done to a ship. | ||
| + | |||
| + | Takes 2 or more arguments... | ||
| + | 1: Ship that has been damaged. | ||
| + | 2: Name of ships that may have damaged it. | ||
| + | ==Distance and Coordinates== | ||
| + | ===[[distance-to-center]]=== | ||
| + | Distance-To-Center (Status operator) | ||
| + | Returns the distance between the centers of two objects. These can be ships, wings, or waypoints. | ||
| + | When a wing or team is given (for either argument), the result will be the closest distance. | ||
| + | |||
| + | Returns a numeric value. Takes 2 arguments... | ||
| + | 1: The name of one of the objects. | ||
| + | 2: The name of the other object. | ||
| + | ===[[distance-to-bbox]]=== | ||
| + | Distance-To-BBox (Status operator) | ||
| + | Returns the distance between the bounding boxes of two objects. These can be ships, wings, or waypoints. | ||
| + | When a wing or team is given (for either argument), the result will be the closest distance. | ||
| + | |||
| + | Returns a numeric value. Takes 2 arguments... | ||
| + | 1: The name of one of the objects. | ||
| + | 2: The name of the other object. | ||
| + | ===[[distance-center-to-subsystem]]=== | ||
| + | Center distance from ship subsystem (Status operator) | ||
| + | Returns the distance between the center of an object and the center of a ship subsystem. The object can be a ship, wing, or waypoint. | ||
| + | When a wing or team is given, the result will be the closest distance. | ||
| + | |||
| + | Returns a numeric value. Takes 3 arguments... | ||
| + | 1: The name of the object. | ||
| + | 2: The name of the ship which houses the subsystem. | ||
| + | 3: The name of the subsystem. | ||
| + | ===[[distance-bbox-to-subsystem]]=== | ||
| + | BBox distance from ship subsystem (Status operator) | ||
| + | Returns the distance between the bounding box of an object and the center of a ship subsystem. The object can be a ship, wing, or waypoint. | ||
| + | When a wing or team is given, the result will be the closest distance. | ||
| + | |||
| + | Returns a numeric value. Takes 3 arguments... | ||
| + | 1: The name of the object. | ||
| + | 2: The name of the ship which houses the subsystem. | ||
| + | 3: The name of the subsystem. | ||
| + | ===[[distance-to-nav]]=== | ||
| + | distance-to-nav | ||
| + | Returns the distance from the center of the player ship to a nav point. Takes 1 argument... 1: The name of the navpoint | ||
===[[num-within-box]]=== | ===[[num-within-box]]=== | ||
| − | + | Number of specified objects in the box specified | |
| − | + | 1: Box center (X) | |
| − | + | 2: Box center (Y) | |
| − | + | 3: Box center (Z) | |
| − | + | 4: Box half-width (distance +/- away from center X) | |
| − | + | 5: Box half-height (distance +/- away from center Y) | |
| − | + | 6: Box half-depth (distance +/- away from center Z) | |
| − | + | Rest: Ships or wings to check | |
| − | |||
===[[is-in-box]]=== | ===[[is-in-box]]=== | ||
Whether an object is in the box specified. If a second ship is specified, the box is relative to that ship's reference frame. | Whether an object is in the box specified. If a second ship is specified, the box is relative to that ship's reference frame. | ||
| − | 1: Ships or | + | 1: Ships, wings, or points to check |
2: Min X | 2: Min X | ||
3: Max X | 3: Max X | ||
| Line 170: | Line 463: | ||
===[[get-object-x]]=== | ===[[get-object-x]]=== | ||
get-object-x | get-object-x | ||
| − | + | Returns the absolute X coordinate of a set of coordinates relative to a particular object (or object's subsystem). The input coordinates are the coordinates relative to the object's position and orientation. If no input coordinates are specified, the coordinate returned is the coordinate of the object (or object's subsystem) itself. Takes 1 to 5 arguments... | |
| − | + | 1: The name of a ship, wing, or waypoint. | |
| − | + | 2: A ship subsystem (or "<none>" if the first argument is not a ship - optional). | |
| − | + | 3: The relative X coordinate (optional). | |
| − | + | 4: The relative Y coordinate (optional). | |
| − | + | 5: The relative Z coordinate (optional). | |
| − | + | ||
| − | |||
| − | |||
===[[get-object-y]]=== | ===[[get-object-y]]=== | ||
get-object-y | get-object-y | ||
| − | + | Returns the absolute Y coordinate of a set of coordinates relative to a particular object (or object's subsystem). The input coordinates are the coordinates relative to the object's position and orientation. If no input coordinates are specified, the coordinate returned is the coordinate of the object (or object's subsystem) itself. Takes 1 to 5 arguments... | |
| − | + | 1: The name of a ship, wing, or waypoint. | |
| − | + | 2: A ship subsystem (or "<none>" if the first argument is not a ship - optional). | |
| − | + | 3: The relative X coordinate (optional). | |
| − | + | 4: The relative Y coordinate (optional). | |
| − | + | 5: The relative Z coordinate (optional). | |
| − | + | ||
| − | |||
| − | |||
===[[get-object-z]]=== | ===[[get-object-z]]=== | ||
get-object-z | get-object-z | ||
| − | + | Returns the absolute Z coordinate of a set of coordinates relative to a particular object (or object's subsystem). The input coordinates are the coordinates relative to the object's position and orientation. If no input coordinates are specified, the coordinate returned is the coordinate of the object (or object's subsystem) itself. Takes 1 to 5 arguments... | |
| − | + | 1: The name of a ship, wing, or waypoint. | |
| − | + | 2: A ship subsystem (or "<none>" if the first argument is not a ship - optional). | |
| − | + | 3: The relative X coordinate (optional). | |
| − | + | 4: The relative Y coordinate (optional). | |
| − | + | 5: The relative Z coordinate (optional). | |
| − | + | ||
| − | + | ===[[get-object-pitch]]=== | |
| − | + | get-object-pitch | |
| − | ===[[ | + | Returns the pitch angle, in degrees, of a particular object. The returned value will be between 0 and 360. Takes 1 argument... |
| − | + | 1: The name of a ship or wing. | |
| − | + | ||
| − | + | ===[[get-object-bank]]=== | |
| + | get-object-bank | ||
| + | Returns the bank angle, in degrees, of a particular object. The returned value will be between 0 and 360. Takes 1 argument... | ||
| + | 1: The name of a ship or wing. | ||
| + | |||
| + | ===[[get-object-heading]]=== | ||
| + | get-object-heading | ||
| + | Returns the heading angle, in degrees, of a particular object. The returned value will be between 0 and 360. Takes 1 argument... | ||
| + | 1: The name of a ship or wing. | ||
| + | |||
| + | ===[[get-object-speed-x]]=== | ||
| + | get-object-speed-x | ||
| + | Returns the X speed of a ship or wing as an integer.Takes 2 or 3 arguments... | ||
| + | 1: The name of the object. | ||
| + | 2: Whether the speed on the axis should be set according to the universe grid (when false) or according to the object's facing (when true); You almost always want to set this to true; (optional; defaults to false). | ||
| + | |||
| + | ===[[get-object-speed-y]]=== | ||
| + | get-object-speed-y | ||
| + | Returns the Y speed of a ship or wing as an integer.Takes 2 or 3 arguments... | ||
| + | 1: The name of the object. | ||
| + | 2: Whether the speed on the axis should be set according to the universe grid (when false) or according to the object's facing (when true); You almost always want to set this to true; (optional; defaults to false). | ||
| − | + | ===[[get-object-speed-z]]=== | |
| − | ===[[ | + | get-object-speed-z |
| − | + | Returns the Z speed of a ship or wing as an integer.Takes 2 or 3 arguments... | |
| − | + | 1: The name of the object. | |
| − | + | 2: Whether the speed on the axis should be set according to the universe grid (when false) or according to the object's facing (when true); You almost always want to set this to true; (optional; defaults to false). | |
| − | |||
| − | + | ==Variables== | |
| − | + | ===[[string-to-int]]=== | |
| − | === | + | string-to-int |
| − | + | Converts a string into an integer. All non-numeric characters (except for the negative sign) will be ignored, as will any fractional part of a decimal number. This behavior is somewhat different than the atoi() function in C or C++, which will abort if it encounters any non-numeric character. For a string like "turret31", this sexp will return 31, but atoi() will return 0. | |
| − | |||
| − | |||
| − | |||
| − | ===[[ | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | Takes 1 argument... | |
| − | + | 1: String to convert | |
| − | + | ===[[string-get-length]]=== | |
| − | + | string-get-length | |
| − | + | Returns the length of the specified string. Takes 1 argument. | |
| − | + | ==Other== | |
| − | + | =Change= | |
| − | ===[[ | + | ==Messages and Personas== |
| − | + | ===[[scramble-messages]]=== | |
| − | + | scramble-messages | |
| − | + | Causes messages to be sent as if the player has sustained communications subsystem or EMP damage. This effect can be reversed using unscramble-messages. Takes zero or more arguments. | |
| − | + | All (Optional): Name of the ship for which to scramble messages. If no ships are specified, message scrambling will be turned on for all messages the player receives. | |
| − | |||
| − | |||
| − | |||
| − | === | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | ===[[ | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | ===[[unscramble-messages]]=== | |
| − | + | unscramble-messages | |
| − | + | Undoes the effects of scramble-messages, causing messages to be sent clearly. Takes zero or more arguments. | |
| − | + | All (Optional): Name of the ship for which to scramble messages. If no ships are specified, message scrambling will be turned on for all messages the player receives. | |
| − | ===[[ | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
===[[disable-builtin-messages]]=== | ===[[disable-builtin-messages]]=== | ||
Disable builtin messages (Action operator) | Disable builtin messages (Action operator) | ||
| − | + | Turns the built in messages sent by command or pilots off | |
Takes 0 or more arguments.... | Takes 0 or more arguments.... | ||
| − | If no arguments are supplied all built in messages are disabled | + | If no arguments are supplied all built in messages are disabled. |
| − | + | Using the Any Wingman option silences for all ships in wings. | |
| + | All: Name of ship to be silenced. | ||
===[[enable-builtin-messages]]=== | ===[[enable-builtin-messages]]=== | ||
Enable builtin messages (Action operator) | Enable builtin messages (Action operator) | ||
| − | + | Turns the built in messages sent by command or pilots on | |
Takes 0 or more arguments... | Takes 0 or more arguments... | ||
If no arguments are supplied any ships not given individual silence orders will be able | If no arguments are supplied any ships not given individual silence orders will be able | ||
| − | to send | + | to send built in messages. Command will also be unsilenced |
| − | + | Using the Any Wingman option cancels radio silence for all ships in wings. | |
| − | ==AI | + | All: Name of ship to allow to talk. |
| + | ===[[set-persona]]=== | ||
| + | Set Persona (Action operator) | ||
| + | Sets the persona of the supplied ship to the persona supplied | ||
| + | Takes 2 or more arguments... | ||
| + | 1: Persona to use. Rest: Name of the ship. | ||
| + | ===[[set-death-message]]=== | ||
| + | set-death-message | ||
| + | Sets the message displayed when the specified players are killed. Takes 1 or more arguments... | ||
| + | 1: The message | ||
| + | Rest: The players for whom this message is displayed (optional) (currently not implemented) | ||
| + | ===[[set-mission-mood]]=== | ||
| + | set Mission Mood (Action operator) | ||
| + | Sets the mood of the mission, this affects the choice of builtin messages sent by wingmen | ||
| + | Takes 1 argument... | ||
| + | 1: Mission mood (from messages.tbl) to use. | ||
| + | ==AI Control== | ||
===[[remove-goal]]=== | ===[[remove-goal]]=== | ||
| − | + | Remove goal (Action operator) | |
| − | + | Removes a goal from a ship or wing. | |
| − | |||
| − | + | Takes 2 arguments... | |
| − | + | 1: Name of ship or wing to remove goal from. | |
| − | + | 2: Goal to remove. | |
===[[change-ai-class]]=== | ===[[change-ai-class]]=== | ||
| − | + | Change AI Class (Action operator) | |
| − | + | Sets the specified ship or ship subsystem(s) to the specified ai class. | |
| − | + | Takes 2 or more arguments... | |
| − | + | 1: AI Class to change to ("None", "Coward", "Lieutenant", etc.) | |
| − | + | 2: Name of ship to change AI class of | |
| − | + | Rest: Name of subsystem to change AI class of (optional) | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
===[[player-use-ai]]=== | ===[[player-use-ai]]=== | ||
player-use-ai | player-use-ai | ||
| − | + | Causes the player's ship to be controlled by the FreeSpace AI. Takes 0 arguments. | |
| − | + | ||
===[[player-not-use-ai]]=== | ===[[player-not-use-ai]]=== | ||
player-not-use-ai | player-not-use-ai | ||
| − | + | Causes the player's ship to not be controlled by the FreeSpace AI. Takes 0 arguments. | |
| − | + | ||
| − | + | ===[[set-player-orders]]=== | |
| − | + | set-player-orders | |
| − | + | Changes the orders friendly AI will accept. Takes 3 or more arguments. | |
| − | + | 1: Ship Name | |
| − | + | 2: True/False as to whether this order is allowed or not | |
| − | + | Rest: Order | |
| − | |||
| − | |||
| − | |||
| − | ===[[set- | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | set- | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
==Ship Status== | ==Ship Status== | ||
| − | ===[[ | + | ===[[turret-protect-ship]]=== |
| − | + | Turret Protect ship (Action operator) | |
| − | + | Protects a ship from being attacked with a turret weapon of a given type. Any ship that is turret protected will not come under enemy fire from that type of turret, though it may come under fire by other turrets. | |
| − | |||
| − | + | Takes 2 or more arguments... | |
| − | + | 1: Type of turret (currently supported types are "beam", "flak", "laser", and "missile") | |
| − | + | Rest: Name of ship(s) to protect. | |
| − | ===[[ | + | ===[[turret-unprotect-ship]]=== |
| − | ship | + | Turret Unprotect ship (Action operator) |
| − | + | Unprotects a ship from being attacked with a turret weapon of a given type. Any ship that is not turret protected can come under enemy fire from that type of turret. This function is the opposite of turret-protect-ship. | |
| − | |||
| − | |||
| − | + | Takes 2 or more arguments... | |
| − | + | 1: Type of turret (currently supported types are "beam", "flak", "laser", and "missile") | |
| − | + | Rest: Name of ship(s) to unprotect. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
===[[ship-stealthy]]=== | ===[[ship-stealthy]]=== | ||
ship-stealthy | ship-stealthy | ||
| − | + | Causes the ships listed in this sexpression to become stealth ships (i.e. invisible to radar). | |
| − | |||
| − | + | Takes 1 or more arguments... | |
| − | + | All: Name of ships to make stealthy. | |
===[[ship-unstealthy]]=== | ===[[ship-unstealthy]]=== | ||
ship-unstealthy | ship-unstealthy | ||
| − | + | Causes the ships listed in this sexpression to become non-stealth ships (i.e. visible to radar). | |
| − | |||
| − | + | Takes 1 or more arguments... | |
| − | + | All: Name of ships to make non-stealthy. | |
===[[friendly-stealth-invisible]]=== | ===[[friendly-stealth-invisible]]=== | ||
friendly-stealth-invisible | friendly-stealth-invisible | ||
| − | + | Causes the friendly ships listed in this sexpression to be invisible to radar, just like hostile stealth ships.It doesn't matter if the ship is friendly at the time this sexp executes: as long as it is a stealth ship, it willbe invisible to radar both as hostile and as friendly. | |
| − | |||
| − | |||
| − | |||
| − | + | Takes 1 or more arguments... | |
| − | + | All: Name of ships | |
===[[friendly-stealth-visible]]=== | ===[[friendly-stealth-visible]]=== | ||
friendly-stealth-visible | friendly-stealth-visible | ||
| − | + | Causes the friendly ships listed in this sexpression to resume their normal behavior of being visible to radar asstealth friendlies. Does not affect their visibility as stealth hostiles. | |
| − | + | ||
| − | + | Takes 1 or more arguments... | |
| + | All: Name of ships | ||
| + | ===[[primitive-sensors-set-range]]=== | ||
| + | primitive-sensors-set-range | ||
| + | Sets the range of the primitive sensors on a ship. Ships outside of this range will not appear on sensors. Has no effect on ships that do not have the "primitive-sensors" flag2 set. Takes 2 arguments... | ||
| + | 1: Ship on which to set range | ||
| + | 2: Range, in meters | ||
| − | |||
| − | |||
===[[ship-targetable-as-bomb]]=== | ===[[ship-targetable-as-bomb]]=== | ||
ship-targetable-as-bomb | ship-targetable-as-bomb | ||
| − | + | Causes the ships listed in this sexpression to be targetable with bomb targeting key. | |
| − | |||
| − | + | Takes 1 or more arguments... | |
| − | + | 1+: Name of ships to make targetable with bomb targeting key. | |
===[[ship-untargetable-as-bomb]]=== | ===[[ship-untargetable-as-bomb]]=== | ||
ship-untargetable-as-bomb | ship-untargetable-as-bomb | ||
| − | + | Causes the ships listed in this sexpression to not be targetable with bomb targeting key. | |
| − | + | ||
| + | Takes 1 or more arguments... | ||
| + | 1+: Name of ships to make nontargetable with bomb targeting key. | ||
| + | ===[[kamikaze]]=== | ||
| + | kamikaze | ||
| + | Tells ships to perform a kamikaze on its current target. Takes 2 or more arguments... | ||
| + | 1: Damage dealt when kamikaze is done | ||
| + | Rest: Names of ships to perform kamikaze | ||
| + | |||
| + | ===[[change-iff-color]]=== | ||
| + | Change IFF Color (Action operator) | ||
| + | Sets the specified ship(s) or wing(s) apparent color. | ||
| + | Takes 6 or more arguments... | ||
| + | 1: Name of the team from which target is observed from. | ||
| + | 2: Name of the team of the observed target to receive the alternate color. | ||
| + | 3: Red color (value from 0 to 255). | ||
| + | 4: Green color (value from 0 to 255). | ||
| + | 5: Blue color (value from 0 to 255). | ||
| + | Rest: Name of ship or wing to change team status of. | ||
| + | ===[[ship-change-alt-name]]=== | ||
| + | ship-change-alt-name | ||
| + | Changes the alternate ship class name displayed in the HUD target window. Takes 2 or more arguments... | ||
| + | 1: The ship class name to display | ||
| + | Rest: The ships to display the new class name | ||
| + | ===[[ship-change-callsign]]=== | ||
| + | ship-change-callsign | ||
| + | Changes the callsign of a ship. Takes 2 or more arguments... | ||
| + | 1: The callsign to display or empty to remove | ||
| + | Rest: The ships to display the new callsign | ||
| + | ===[[ship-tag]]=== | ||
| + | ship-tag | ||
| + | Tags a ship. Takes 3 or 8 arguments... | ||
| + | 1: The name of a ship. | ||
| + | 2: The tag level (currently 1, 2, or 3). | ||
| + | 3: The tag time (in seconds). | ||
| + | 4: A SSM missile (optional - used only for TAG-C). | ||
| + | 5: The X origin of the SSM missile (optional - used only for TAG-C). | ||
| + | 6: The Y origin of the SSM missile (optional - used only for TAG-C). | ||
| + | 7: The Z origin of the SSM missile (optional - used only for TAG-C). | ||
| + | 8: The team the SSM missile belongs to (optional - used only for TAG-C). | ||
| + | |||
| + | ===[[ship-untag]]=== | ||
| + | Min arguments: 1, Max arguments: 1 | ||
| + | ===[[set-arrival-info]]=== | ||
| + | set-arrival-info | ||
| + | Sets arrival information for a ship or wing. Takes 2 to 7 arguments... | ||
| + | 1: Ship or wing name | ||
| + | 2: Arrival location | ||
| + | 3: Arrival anchor (optional; only required for certain locations) | ||
| + | 4: Arrival path mask (optional; this is a bitfield where the bits set to 1 correspond to the paths to use; defaults to 0 which is a special case that means all paths can be used) | ||
| + | 5: Arrival distance (optional; defaults to 0) | ||
| + | 6: Arrival delay (optional; defaults to 0) | ||
| + | 7: Whether to show a jump effect if arriving from subspace (optional; defaults to true) | ||
| + | |||
| + | ===[[set-departure-info]]=== | ||
| + | set-departure-info | ||
| + | Sets departure information for a ship or wing. Takes 2 to 6 arguments... | ||
| + | 1: Ship or wing name | ||
| + | 2: Departure location | ||
| + | 3: Departure anchor (optional; only required for certain locations) | ||
| + | 4: Departure path mask (optional; this is a bitfield where the bits set to 1 correspond to the paths to use; defaults to 0 which is a special case that means all paths can be used) | ||
| + | 5: Departure delay (optional; defaults to 0) | ||
| + | 6: Whether to show a jump effect if departing to subspace (optional; defaults to true) | ||
| + | |||
| + | ===[[alter-ship-flag]]=== | ||
| + | alter-ship-flag | ||
| + | Sets a ships flag and/or parse flag. | ||
| + | |||
| + | Takes 4 or more arguments... | ||
| + | 1: Ship flag name | ||
| + | 2: True if turning on, false if turning off | ||
| + | 3: True\False - Apply this flag to future waves of this wing. Apply to ship if not present | ||
| + | Rest: (optional) Name of ships, wings, or entire teams. If not supplied, will work on all ships in the mission | ||
| + | |||
| + | Ship Flags: | ||
| + | invulnerable - Stops ship from taking any damage | ||
| + | protect-ship - Ship and Turret AI will ignore and not attack ship | ||
| + | beam-protect-ship - Turrets with beam weapons will ignore and not attack ship | ||
| + | no-shields - Ship will have no shields (ETS will be rebalanced if shields were off and are enabled) | ||
| + | targetable-as-bomb - Allows ship to be targetted with the bomb targetting key | ||
| + | flak-protect-ship - Turrets with flak weapons will ignore and not attack ship | ||
| + | laser-protect-ship - Turrets with laser weapons will ignore and not attack ship | ||
| + | missile-protect-ship - Turrets with missile weapons will ignore and not attack ship | ||
| + | immobile - Will not let a ship move or rotate in any fashion | ||
| + | vaporize - Causes a ship to vanish (no deathroll, no debris, no explosion) when destroyed | ||
| + | break-warp - Causes a ship's subspace drive to break. Can be repaired by a support ship | ||
| + | never-warp - Causes a ship's subspace drive to never work. Cannot be repaired by a support ship | ||
| + | afterburner-locked - Will stop a ship from firing their afterburner | ||
| + | primaries-locked - Will stop a ship from firing their primary weapons | ||
| + | secondaries-locked - Will stop a ship from firing their secondary weapons | ||
| + | no-subspace-drive - Will not allow a ship to jump into subspace | ||
| + | don't-collide-invisible - Will cause polygons with an invisible texture to stop colliding with objects | ||
| + | no-ets - Will not allow a ship to alter its ETS system | ||
| + | toggle-subsystem-scanning - Switches between being able to scan a whole ship or individual subsystems | ||
| + | scannable - Whether or not the ship can be scanned | ||
| + | cargo-known - If set, the ships cargo can be seen without scanning the ship | ||
| + | stealth - If set, the ship can't be targeted, is invisible on radar, and is ignored by AI unless firing | ||
| + | friendly-stealth-invisible - If set, the ship can't be targeted even by ships on the same team | ||
| + | hide-ship-name - If set, the ship name can't be seen when the ship is targeted | ||
| + | hidden-from-sensors - If set, the ship can't be targeted and appears on radar as a blinking dot | ||
| + | no-dynamic - Will stop allowing the AI to persue dynamic goals (eg: chasing ships it was not ordered to) | ||
| + | no-secondary-lock-on - Will disable target acquisition for secondaries of all types (does not affect turrets) | ||
| + | |||
| + | ==Weapons, Shields, and Engines== | ||
| + | ===[[set-weapon-energy]]=== | ||
| + | set-weapon-energy | ||
| + | Sets the weapon energy for the specified ship(s) | ||
| + | Takes 2 or more arguments | ||
| + | 1: percentage of maximum weapon energy. | ||
| + | (rest): Name(s) of ship(s) | ||
| + | ===[[set-shield-energy]]=== | ||
| + | set-shield-energy | ||
| + | Sets the shield energy for the specified ship(s) | ||
| + | Takes 2 or more arguments | ||
| + | 1: percentage of maximum shield energy. | ||
| + | (rest): Name(s) of ship(s) | ||
| + | ===[[set-player-throttle-speed]]=== | ||
| + | set-player-throttle-speed | ||
| + | Sets a player's throttle to a percentage of their maximum speed. | ||
| + | This SEXP has no effect if used on an AI ship, however it will still work on an AI-controlled player ship. | ||
| + | Takes 2 arguments... | ||
| + | 1: The player ship to set the throttle of. | ||
| + | 2: The percentage of the player's maximum speed to set their throttle to. | ||
| + | This is capped to either 0 or 100 if outside the valid range. | ||
| + | ===[[set-afterburner-energy]]=== | ||
| + | set-afterburner-energy | ||
| + | Sets the afterburner energy for the specified ship(s) | ||
| + | Takes 2 or more arguments | ||
| + | 1: percentage of maximum afterburner energy. | ||
| + | (rest): Name(s) of ship(s) | ||
| + | ===[[set-subspace-drive]]=== | ||
| + | set-subspace-drive | ||
| + | Turns on or off the subspace edrive for the given ships. A ship with no subspace drive will act as though it doesn't even occur to him to depart via subspace, and if ordered to do so, he will look for a friendly ship with a hangar bay. If the ship is the player, pressing Alt-J will not not initiate a jump, nor give any indication that a jump failed. Takes 2 or more arguments... | ||
| + | 1: True if the ship should have a drive; false otherwise | ||
| + | Rest: List of ships | ||
| + | ===[[set-primary-weapon]]=== | ||
| + | set-primary-weapon | ||
| + | Sets the weapon for the specified bank | ||
| + | 1: Ship name | ||
| + | 2: Bank to check (0, 1 and 2 are legal banks) | ||
| + | 3: Name of the primary weapon | ||
| + | 4: Number to set ammo of this bank to (If this is larger than the maximum, bank will be set to maximum) | ||
| + | 5: Rearm Limit. Support ships will only supply this number of weapons (If this is larger than the maximum, bank will be set to maximum) | ||
| + | ===[[set-secondary-weapon]]=== | ||
| + | set-secondary-weapon | ||
| + | Sets the weapon for the specified bank | ||
| + | 1: Ship name | ||
| + | 2: Bank to check (0, 1, 2 and 3 are legal banks) | ||
| + | 3: Name of the secondary weapon | ||
| + | 4: Number to set ammo of this bank to (If this is larger than the maximum, bank will be set to maximum) | ||
| + | 5: Rearm Limit. Support ships will only supply this number of weapons (If this is larger than the maximum, bank will be set to maximum) | ||
| + | ===[[set-primary-ammo]]=== | ||
| + | set-primary-ammo | ||
| + | Sets the amount of ammo for the specified ballistic bank | ||
| + | 1: Ship name | ||
| + | 2: Bank to check (0, 1, and 2 are legal banks) | ||
| + | 3: Number to set this bank to (If this is larger than the maximum, bank will be set to maximum). | ||
| + | 4: Rearm Limit. Support ships will only supply this number of weapons (If this is larger than the maximum, bank will be set to maximum) | ||
| + | ===[[set-secondary-ammo]]=== | ||
| + | set-secondary-ammo | ||
| + | Sets the amount of ammo for the specified bank | ||
| + | 1: Ship name | ||
| + | 2: Bank to check (0, 1, 2 and 3 are legal banks) | ||
| + | 3: Number to set this bank to (If this is larger than the maximum, bank will be set to maximum). | ||
| + | 4: Rearm Limit. Support ships will only supply this number of weapons (If this is larger than the maximum, bank will be set to maximum) | ||
| + | ===[[set-num-countermeasures]]=== | ||
| + | set-num-countermeasures | ||
| + | Sets the number of countermeasures the ship has | ||
| + | Values greater than the maximum a ship can carry are set to the maximum | ||
| + | 1: Ship name | ||
| + | 2: Number to set | ||
| + | ===[[lock-primary-weapon]]=== | ||
| + | lock-primary-weapon | ||
| + | Locks the primary banks for the specified ship(s) | ||
| + | Takes 1 or more arguments | ||
| + | (all): Name(s) of ship(s) to lock | ||
| + | ===[[unlock-primary-weapon]]=== | ||
| + | unlock-primary-weapon | ||
| + | Unlocks the primary banks for the specified ship(s) | ||
| + | Takes 1 or more arguments | ||
| + | (all): Name(s) of ship(s) to lock | ||
| + | ===[[lock-secondary-weapon]]=== | ||
| + | lock-secondary-weapon | ||
| + | Locks the secondary banks for the specified ship(s) | ||
| + | Takes 1 or more arguments | ||
| + | (all): Name(s) of ship(s) to lock | ||
| + | ===[[unlock-secondary-weapon]]=== | ||
| + | unlock-secondary-weapon | ||
| + | Unlocks the secondary banks for the specified ship(s) | ||
| + | Takes 1 or more arguments | ||
| + | (all): Name(s) of ship(s) to lock | ||
| + | ===[[lock-afterburner]]=== | ||
| + | lock-afterburner | ||
| + | Locks the afterburners on the specified ship(s) | ||
| + | Takes 1 or more arguments | ||
| + | (all): Name(s) of ship(s) to lock | ||
| + | ===[[unlock-afterburner]]=== | ||
| + | unlock-afterburner | ||
| + | Unlocks the afterburners on the specified ship(s) | ||
| + | Takes 1 or more arguments | ||
| + | (all): Name(s) of ship(s) to lock | ||
| + | ===[[shields-on]]=== | ||
| + | shields-on | ||
| + | Causes the ship listed in this sexpression to have their shields activated. | ||
| + | If the ship had no-shields prior to the sexp being called, the ETS will be rebalanced to default. | ||
| + | Takes 1 or more arguments... | ||
| + | 1+: Name of ships to activate shields on. | ||
| + | ===[[shields-off]]=== | ||
| + | shields-off | ||
| + | Causes the ships listed in this sexpression to have their shields deactivated. | ||
| + | |||
| + | Takes 1 or more arguments... | ||
| + | 1+: Name of ships to deactivate shields on. | ||
| + | ===[[force-glide]]=== | ||
| + | force-glide | ||
| + | Forces a given ship into glide mode, provided it is capable of gliding. Note that the player will not be able to leave glide mode on his own,, and that a ship in glide mode cannot warp out or enter autopilot.Takes 2 Arguments... | ||
| + | 1: Ship to force | ||
| + | 2: True to activate glide, False to deactivate | ||
| + | |||
| + | ===[[disable-ets]]=== | ||
| + | disable-ets | ||
| + | Switches a ships' ETS system off | ||
| + | |||
| + | Takes at least 1 argument... | ||
| + | All: List of ships this sexp applies to | ||
| + | |||
| + | ===[[enable-ets]]=== | ||
| + | enable-ets | ||
| + | Switches a ships' ETS system on | ||
| + | |||
| + | Takes at least 1 argument... | ||
| + | All: List of ships this sexp applies to | ||
| + | |||
| + | ===[[set-ets-values]]=== | ||
| + | set-ets-values | ||
| + | Sets ETS indexes for a ship | ||
| + | Index values are used in a hard-coded array to lookup recharge percentages | ||
| + | Each index has a valid range of 0 to 12 | ||
| + | Use index values retrieved with get-ets-value | ||
| + | Or if you use your own values, ensure they add up to 12 (e.g. 0,3,9) | ||
| + | 1: Engine index | ||
| + | 2: Shields index | ||
| + | 3: Weapons index | ||
| + | 4: Ship name | ||
| + | |||
| + | ==Subsystems and Health== | ||
| + | ===[[ship-guardian-threshold]]=== | ||
| + | ship-guardian-threshold | ||
| + | Same as ship-guardian, except the lowest possible hull value is specified by the sexp rather than defaulting to 1. | ||
| + | Call with a threshold of 0 (or use ship-no-guardian) to deactivate. | ||
| + | |||
| + | Takes 2 or more arguments... | ||
| + | 1: Threshold value. | ||
| + | 2+: Name of ships to make unkillable. | ||
| + | ===[[ship-subsys-guardian-threshold]]=== | ||
| + | ship-subsys-guardian-threshold | ||
| + | Same as ship-guardian-threshold, but works on subsystems. | ||
| + | Call with a threshold of 0 to deactivate. | ||
| + | |||
| + | Takes 3 or more arguments... | ||
| + | 1: Threshold value. | ||
| + | 2: Ship housing the subsystem(s). | ||
| + | 3+: Subsystems to make unkillable. | ||
| + | ===[[destroy-instantly]]=== | ||
| + | destroy-instantly | ||
| + | Self-destructs the named ship without explosion, death roll, or debris. That is, the ship is instantly gone from the mission and the only indication of what happened is a mission log entry. | ||
| + | Non-player ship only! | ||
| + | All: List of ship names to destroy. | ||
| + | |||
| + | ===[[destroy-subsys-instantly]]=== | ||
| + | destroy-subsys-instantly | ||
| + | Destroys the specified subsystems without effects.Takes 2 or more arguments... | ||
| + | 1: Name of ship subsystem is on. | ||
| + | Rest: Name of subsystem to destroy. | ||
| + | |||
| + | ===[[ship-copy-damage]]=== | ||
| + | ship-copy-damage | ||
| + | Copies the damage (hull, shields, and subsystems) from the first ship in the list to the rest. The initial ship must be currently present in the mission, but the target ships may be either in-mission or on the arrival list. Takes 2 or more arguments... | ||
| + | 1: The name of the ship that supplies the damage stats | ||
| + | Rest: The list of ships to be modified | ||
| + | ===[[lock-rotating-subsystem]]=== | ||
| + | lock-rotating-subsystem | ||
| + | Instantaneously locks a rotating subsystem so that it cannot rotate unless freed by free-rotating-subsystem. Takes 2 or more arguments... | ||
| + | 1: Name of the ship housing the subsystem | ||
| + | Rest: Name of the rotating subsystem to lock | ||
| + | ===[[free-rotating-subsystem]]=== | ||
| + | free-rotating-subsystem | ||
| + | Instantaneously frees a rotating subsystem previously locked by lock-rotating-subsystem. Takes 2 or more arguments... | ||
| + | 1: Name of the ship housing the subsystem | ||
| + | Rest: Name of the rotating subsystem to free | ||
| + | ===[[reverse-rotating-subsystem]]=== | ||
| + | reverse-rotating-subsystem | ||
| + | Instantaneously reverses the rotation direction of a rotating subsystem. Takes 2 or more arguments... | ||
| + | 1: Name of the ship housing the subsystem | ||
| + | Rest: Name of the rotating subsystem to reverse | ||
| + | ===[[rotating-subsys-set-turn-time]]=== | ||
| + | rotating-subsys-set-turn-time | ||
| + | Sets the turn time of a rotating subsystem. Takes 3 or 4 arguments... | ||
| + | 1: Name of the ship housing the subsystem | ||
| + | 2: Name of the rotating subsystem to configure | ||
| + | 3: The time for one complete rotation, in milliseconds (positive is counterclockwise, negative is clockwise) | ||
| + | 4: The acceleration (x1000, just as #3 is seconds x1000) to change from the current turn rate to the desired turn rate. This is actually the time to complete one rotation that changes in one second, or the reciprocal of what you might expect, meaning that larger numbers cause slower acceleration. (FS2 defaults to 2pi/0.5, or about 12.566, which would be 12566 in this sexp.) The advantage of this method is so that this argument can be directly compared to the previous argument using a ratio, without worrying about pi. Omit this argument if you want an instantaneous change. | ||
| + | ===[[trigger-submodel-animation]]=== | ||
| + | trigger-submodel-animation | ||
| + | Activates a submodel animation trigger for a given ship. Takes 4 to 6 arguments... | ||
| + | 1: The ship on which the animation should run | ||
| + | 2: The type of animation (named as one would see them in ships.tbl) | ||
| + | 3: The subtype of animation, which is type-dependent. For docking animations this is the dock index. | ||
| + | 4: The animation direction: 1 for forward, or -1 for reverse | ||
| + | 5: (Optional) Whether the animation should instantly snap to its final position | ||
| + | 6: (Optional) A subsystem, if the animation should trigger on only a specific subsystem as opposed to all applicable subsystems | ||
| + | |||
| + | ===[[change-subsystem-name]]=== | ||
| + | change-subsystem-name | ||
| + | Changes the name of the specified subsystem on the specified ship | ||
| + | Takes 3 or more arguments | ||
| + | 1: Name of the ship. | ||
| + | 2: New name for the subsystem (names larger than the maximum display size will be truncated | ||
| + | 3: Name(s) of subsystem(s) to rename | ||
| − | |||
| − | |||
===[[ship-subsys-targetable]]=== | ===[[ship-subsys-targetable]]=== | ||
ship-subsys-targetable | ship-subsys-targetable | ||
| − | + | Causes the specified ship subsystem(s) to be targetable on radar. | |
| − | + | Takes 2 or more arguments... | |
| − | + | 1: Name of a ship | |
| − | + | Rest: Name of the ship's subsystem(s) | |
| − | |||
===[[ship-subsys-untargetable]]=== | ===[[ship-subsys-untargetable]]=== | ||
ship-subsys-untargetable | ship-subsys-untargetable | ||
| − | + | Causes the specified ship subsystem(s) to not be targetable on radar. | |
| − | + | Takes 2 or more arguments... | |
| − | + | 1: Name of a ship | |
| − | + | Rest: Name of the ship's subsystem(s) | |
| − | + | ===[[ship-subsys-no-replace]]=== | |
| − | + | ship-subsys-no-replace | |
| + | Causes the -destroyed version of specified ship subsystem(s) to not render when it's destroyed. | ||
| + | Takes 3 or more arguments... | ||
| + | 1: Name of a ship | ||
| + | 2: True = Do not render or False = render if exists | ||
| + | Rest: Name of the ship's subsystem(s) Note: If subsystem is already dead it will vanish or reappear out of thin air | ||
| + | ===[[ship-subsys-no-live-debris]]=== | ||
| + | ship-subsys-no-live-debris | ||
| + | Causes the specified ship subsystem(s) to not render live debris when it's destroyed. | ||
| + | Takes 3 or more arguments... | ||
| + | 1: Name of a ship | ||
| + | 2: True = Do not render or False = render if exists | ||
| + | Rest: Name of the ship's subsystem(s) | ||
| + | ===[[ship-subsys-vanish]]=== | ||
| + | ship-subsys-vanish | ||
| + | Causes the subsystem to vanish without a trace - no fanfare, notification, or special effects. See also ship-vanish. | ||
| + | Single Player Only! Warning: This will cause subsystem destruction not to be logged, so 'has-departed', etc. will not work | ||
| + | Takes 3 or more arguments... | ||
| + | 1: Name of a ship | ||
| + | 2: True = vanish or False = don't vanish | ||
| + | Rest: Name of the ship's subsystem(s) Note: Useful for replacing subsystems with actual docked models. | ||
| + | ===[[ship-subsys-ignore_if_dead]]=== | ||
| + | ship-subsys-ignore-if-dead | ||
| + | Causes secondary weapons to ignore dead ship subsystem(s)and home on hull instead. | ||
| + | Takes 3 or more arguments... | ||
| + | 1: Name of a ship | ||
| + | 2: True = Ignore dead or False = don't ignore | ||
| + | Rest: Name of the ship's subsystem(s) | ||
| + | ==Cargo== | ||
| + | ===[[set-docked]]=== | ||
| + | set-docked | ||
| + | Causes one ship to become instantly docked to another at the specified docking ports. Takes 4 arguments... | ||
| + | 1: Docker ship | ||
| + | 1: Docker point | ||
| + | 1: Dockee ship | ||
| + | 1: Dockee point | ||
| + | |||
| + | ===[[set-scanned]]=== | ||
| + | set-scanned | ||
| + | Sets the cargo on the specified ship or ship subsystem as known or scanned. Takes 1 or more arguments... | ||
| + | 1: Name of a ship | ||
| + | Rest: Name of a subsystem on that ship (optional) | ||
| + | |||
| + | ===[[set-unscanned]]=== | ||
| + | set-unscanned | ||
| + | Sets the cargo on the specified ship or ship subsystem as unknown or unscanned. Takes 1 or more arguments... | ||
| + | 1: Name of a ship | ||
| + | Rest: Name of a subsystem on that ship (optional) | ||
| + | |||
| + | ===[[set-cargo]]=== | ||
| + | Set Cargo (Action operator) | ||
| + | Sets the cargo on a ship or ship subsystem. The cargo-no-deplete flag status is carried through to the new cargo. | ||
| + | Takes 2 or 3 arguments... | ||
| + | 1: Name of the cargo | ||
| + | 2: Name of the ship | ||
| + | 3: Name of the ship subsystem (optional) | ||
| + | ==Armor and Damage Types== | ||
| + | ===[[set-armor-type]]=== | ||
| + | set-armor-type | ||
| + | Sets the armor type for a ship or subsystem | ||
| + | 1: Ship subsystem is on | ||
| + | 2: Set = true/Reset to default = false | ||
| + | 3: Armor type to set or <none> | ||
| + | rest: Subsystems to set (hull for ship, shield for shields) | ||
| + | |||
| + | ===[[weapon-set-damage-type]]=== | ||
| + | weapon-set-damage-type | ||
| + | Sets the damage type for weapons or their shockwaves | ||
| + | 1: True = set weapon, False = set shockwave | ||
| + | 2: damage type to set or <none> | ||
| + | 3: Set = true/Reset to default = false | ||
| + | rest: Weapons to set | ||
| + | |||
| + | ===[[ship-set-damage-type]]=== | ||
| + | ship-set-damage-type | ||
| + | Sets the damage type for ships collision or debris | ||
| + | 1: true = set collision, False = set debris | ||
| + | 2: Damage type to set or <none> | ||
| + | 3: Set = true/Reset to default = false | ||
| + | rest: Ships to set | ||
| + | |||
| + | ===[[ship-set-shockwave-damage-type]]=== | ||
| + | ship-set-shockwave-damage-type | ||
| + | Sets the shockwave damage type for a class of ship. All ships of that class are changed. | ||
| + | 1: Damage type to set or <none> | ||
| + | 2: Set = true/Reset to default = false | ||
| + | rest: Ship classes to set | ||
| + | |||
| + | ===[[field-set-damage-type]]=== | ||
| + | field-set-damage-type | ||
| + | Sets the damage type for asteroid/debris fields | ||
| + | 1: Damage type to set or <none> | ||
| + | 2: Set = true/Reset to default = false | ||
| + | |||
==Beams and Turrets== | ==Beams and Turrets== | ||
| + | ===[[fire-beam-at-coordinates]]=== | ||
| + | fire-beam-at-coordinates | ||
| + | Fire a beam weapon from a specified subsystem at a set of coordinates. Not compatible with multiplayer. | ||
| + | 1: Ship which will be firing | ||
| + | 2: Turret which will fire the beam (note, this turret must have at least 1 beam weapon on it) | ||
| + | 3: x coordinate to be targeted | ||
| + | 4: y coordinate to be targeted | ||
| + | 5: z coordinate to be targeted | ||
| + | 6: (Optional Operator) Whether to force the beam to fire (disregarding FOV and subsystem status). Defaults to False | ||
| + | 7: second x coordinate to be targeted (optional; only used for slash beams) | ||
| + | 8: second y coordinate to be targeted (optional; only used for slash beams) | ||
| + | 9: second z coordinate to be targeted (optional; only used for slash beams) | ||
| + | |||
| + | ===[[beam-create]]=== | ||
| + | beam-create | ||
| + | Fire a beam weapon from the specified coordinates to the specified target. Not compatible with multiplayer. | ||
| + | 1: Beam weapon to fire | ||
| + | 2: Parent ship (for kill credit, if applicable; can be none) | ||
| + | 3: Team for this beam to be on (related to difficulty-based damage) | ||
| + | 4: X coordinate to fire from | ||
| + | 5: Y coordinate to fire from | ||
| + | 6: Z coordinate to fire from | ||
| + | 7: Target ship (can be none) | ||
| + | 8: Target subsystem (optional, can be none) | ||
| + | 9: X coordinate to fire at (optional) | ||
| + | 10: Y coordinate to fire at (optional) | ||
| + | 11: Z coordinate to fire at (optional) | ||
| + | 12: Second X coordinate to fire at (optional; used for slash beams) | ||
| + | 13: Second Y coordinate to fire at (optional; used for slash beams) | ||
| + | 14: Second Z coordinate to fire at (optional; used for slash beams) | ||
| + | |||
===[[turret-tagged-specific]]=== | ===[[turret-tagged-specific]]=== | ||
turret-tagged-specific | turret-tagged-specific | ||
| − | + | Specific turrets on a ship only fire at tagged targets, as opposed to all turrets doing this using turret-tagged-only | |
| − | + | It is safe to slave turrets already slaved | |
| − | + | Takes 2 or more arguments... | |
| − | + | 1: Name of ship to slave some turrets to target only tagged ships | |
| − | + | Rest: Turrets to slave | |
| − | + | ||
===[[turret-tagged-clear-specific]]=== | ===[[turret-tagged-clear-specific]]=== | ||
turret-tagged-clear-specific | turret-tagged-clear-specific | ||
| − | + | Specific turrets on a ship are free to fire on untagged ships, as opposed to all turrets doing this using turret-tagged-clear | |
| − | + | It is safe to unslave turrets already free | |
| − | + | Takes 2 or more arguments... | |
| − | + | 1: Name of ship to unslave some turrets to target any hostile ship | |
| − | + | Rest: Turrets to unslave | |
| − | + | ||
===[[turret-change-weapon]]=== | ===[[turret-change-weapon]]=== | ||
turret-change-weapon | turret-change-weapon | ||
| − | + | Sets a given turret weapon slot to the specified weapon | |
| − | + | 1: Ship turret is on | |
| − | + | 2: Turret | |
| − | + | 3: Weapon to set slot to | |
| − | + | 4: Primary slot (or 0 to use secondary) | |
| − | + | 5: Secondary slot (or 0 to use primary) | |
| − | + | ===[[turret-set-direction-preference]]=== | |
| + | turret-set-direction-preference | ||
| + | Sets specified ship turrets direction preference to the specified value | ||
| + | 1: Ship turrets are on | ||
| + | 2: Preference to set, 0 to disable, or negative to reset to default | ||
| + | rest: Turrets to set | ||
| + | |||
| + | ===[[turret-set-rate-of-fire]]=== | ||
| + | turret-set-rate-of-fire | ||
| + | Sets specified ship turrets rate of fire to the specified value | ||
| + | 1: Ship turrets are on | ||
| + | 2: Rate to set in percentage format (200 = 2x, 50 = .5x), 0 to set to number of fire points, or negative to reset to default | ||
| + | rest: Turrets to set | ||
| + | |||
| + | ===[[turret-set-optimum-range]]=== | ||
| + | turret-set-optimum-range | ||
| + | Sets specified ship turrets optimum range to the specified value | ||
| + | 1: Ship turrets are on | ||
| + | 2: Priority to set, 0 to disable, or negative to reset to default | ||
| + | rest: Turrets to set | ||
| + | |||
| + | ===[[turret-set-target-priorities]]=== | ||
| + | turret-set-target-priorities | ||
| + | Sets target priorities for the specified ship turret | ||
| + | 1: Ship turret is on | ||
| + | 2: Turret to set | ||
| + | 3: True = Set new list, False = Reset to turret default | ||
| + | rest: Priorities to set (max 32) or blank for no priorities | ||
| + | |||
===[[turret-set-target-order]]=== | ===[[turret-set-target-order]]=== | ||
turret-set-target-order | turret-set-target-order | ||
| − | + | Sets targeting order of a given turret | |
| − | + | 1: Ship turret is on | |
| − | + | 2: Turret | |
| − | + | rest: Target order type (Bombs,ships,asteroids) | |
| − | |||
===[[ship-turret-target-order]]=== | ===[[ship-turret-target-order]]=== | ||
ship-turret-target-order | ship-turret-target-order | ||
| − | + | Sets targeting order of all turrets on a given ship | |
| − | + | 1: Ship turrets are on | |
| − | + | rest: Target order type (Bombs,ships,asteroids) | |
| − | + | ===[[turret-subsys-target-disable]]=== | |
| − | + | turret-subsys-target-disable | |
| − | ===[[turret- | + | Prevents turrets from targeting only the subsystems when targeting large targets |
| − | turret- | + | 1: Ship to be operated on |
| − | + | rest: List of turrets that are affected | |
| − | + | ||
| − | + | ===[[turret-subsys-target-enable]]=== | |
| − | + | turret-subsys-target-enable | |
| − | + | Sets turret to target the subsystems when targeting large targets | |
| − | + | 1: Ship to be operated on | |
| − | ===[[turret- | + | rest: List of turrets that are affected |
| − | turret- | + | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
===[[turret-set-primary-ammo]]=== | ===[[turret-set-primary-ammo]]=== | ||
turret-set-primary-ammo | turret-set-primary-ammo | ||
| − | + | Sets the turret's primary bank ammo, only works with ballistic weapons | |
| − | + | 1: Ship turret is on | |
| − | + | 2: Turret the bank is on | |
| − | + | 3: Bank to add ammo to | |
| − | + | 4: Amount to add | |
| − | |||
| − | |||
===[[turret-set-secondary-ammo]]=== | ===[[turret-set-secondary-ammo]]=== | ||
turret-set-secondary-ammo | turret-set-secondary-ammo | ||
| − | + | Sets the turret's secondary bank ammo | |
| − | + | 1: Ship turret is on | |
| − | + | 2: Turret the bank is on | |
| − | + | 3: Bank to add ammo to | |
| − | + | 4: Amount to add | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
==Models and Textures== | ==Models and Textures== | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
===[[change-ship-class]]=== | ===[[change-ship-class]]=== | ||
change-ship-class | change-ship-class | ||
| − | + | Causes the listed ships' classes to be changed to the specified ship class. Takes 2 or more arguments... | |
| − | + | 1: The name of the new ship class | |
| − | + | Rest: The list of ships to change the classes of | |
| − | + | ===[[deactivate-glow-maps]]=== | |
| + | deactivate-glow-maps | ||
| + | Deactivates the glow maps for a ship. Takes 1 or more arguments... | ||
| + | All: Name of ship on which to deactivate glow maps | ||
| + | |||
| + | ===[[activate-glow-maps]]=== | ||
| + | activate-glow-maps | ||
| + | Activates the glow maps for a ship. Takes 1 or more arguments... | ||
| + | All: Name of ship on which to activate glow maps | ||
| + | |||
===[[deactivate-glow-points]]=== | ===[[deactivate-glow-points]]=== | ||
deactivate-glow-points | deactivate-glow-points | ||
| − | + | Deactivates all glow points on a ship. Takes 1 or more arguments... | |
| − | + | All: Name of ship on which to deactivate glow points | |
| − | + | ||
===[[activate-glow-points]]=== | ===[[activate-glow-points]]=== | ||
activate-glow-points | activate-glow-points | ||
| − | + | Activates all glow points on a ship. Takes 1 or more arguments... | |
| − | + | All: Name of ship on which to activate glow points | |
| − | + | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
===[[deactivate-glow-point-bank]]=== | ===[[deactivate-glow-point-bank]]=== | ||
deactivate-glow-point-bank | deactivate-glow-point-bank | ||
| − | + | Deactivates one or more glow point bank(s) on a ship. Takes 2 or more arguments... | |
| − | + | 1: Name of ship on which to deactivate glow point bank(s) | |
| − | + | Rest: Name of glow point bank to deactivate | |
| − | + | ||
===[[activate-glow-point-bank]]=== | ===[[activate-glow-point-bank]]=== | ||
activate-glow-point-bank | activate-glow-point-bank | ||
| − | + | Activates one or more glow point bank(s) on a ship. Takes 2 or more arguments... | |
| − | + | 1: Name of ship on which to activate glow point bank(s) | |
| − | + | Rest: Name of glow point bank to activate | |
| − | + | ||
| + | ===[[set-thrusters-status]]=== | ||
| + | set-thrusters-status | ||
| + | Manipulates the thrusters on a ship. | ||
| + | Takes 2 or more arguments... | ||
| + | 1: Boolean, true sets thrusters to visible, false deactivates them. | ||
| + | 2: Rest: List of ships this sexp will work on. | ||
| + | |||
| + | ===[[don't-collide-invisible]]=== | ||
| + | don't-collide-invisible | ||
| + | Sets the "don't collide invisible" flag on a list of ships. | ||
| + | Takes 1 or more arguments... | ||
| + | All: List of ships on which to set the "don't collide invisible" flag | ||
| + | ===[[collide-invisible]]=== | ||
| + | collide-invisible | ||
| + | Unsets the "don't collide invisible" flag on a list of ships. | ||
| + | Takes 1 or more arguments... | ||
| + | All: List of ships on which to unset the "don't collide invisible" flag | ||
| + | ===[[add-to-collision-group]]=== | ||
| + | add-to-collision-group | ||
| + | Adds a ship to the specified collision group(s). Note that there are 32 collision groups, and that an object may be in several collision groups at the same time | ||
| + | Takes 2 or more Arguments... | ||
| + | 1: Object to add | ||
| + | 2+: Group IDs. Valid IDs are 0 through 31 inclusive. | ||
| + | |||
| + | ===[[remove-from-collision-group]]=== | ||
| + | remove-from-collision-group | ||
| + | Removes a ship from the specified collision group(s). Note that there are 32 collision groups, | ||
| + | and that an object may be in several collision groups at the same time | ||
| + | Takes 2 or more Arguments... | ||
| + | 1: Object to add | ||
| + | 2+: Group IDs. Valid IDs are 0 through 31 inclusive. | ||
| + | |||
| + | ===[[get-collision-group]]=== | ||
| + | get-collision-group | ||
| + | Returns an objects' collision group ID. Note that this ID is a bitfield. | ||
| + | Takes 1 Argument... | ||
| + | 1: Object name | ||
| + | |||
===[[change-team-color]]=== | ===[[change-team-color]]=== | ||
change-team-color | change-team-color | ||
| − | + | Changes the team color setting for one or several ships. | |
| − | + | This sexp has no effect on ships that don't have team colors enabled for them. | |
| − | + | Takes 3 or more arguments... | |
| − | + | 1: The new team color name. Name must be defined in colors.tbl. | |
| − | + | 2: Crossfade time in milliseconds. During this time, colors will be mixed. | |
| − | + | 3: Rest: List of ships this sexp will operate on. | |
| − | |||
==Coordinate Manipulation== | ==Coordinate Manipulation== | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
===[[set-object-position]]=== | ===[[set-object-position]]=== | ||
set-object-position | set-object-position | ||
| − | + | Instantaneously sets an object's spatial coordinates.Takes 4 arguments... | |
| − | + | 1: The name of a ship, wing, or waypoint. | |
| − | + | 2: The new X coordinate. | |
| − | + | 3: The new Y coordinate. | |
| − | + | 4: The new Z coordinate. | |
| − | |||
===[[set-object-orientation]]=== | ===[[set-object-orientation]]=== | ||
set-object-orientation | set-object-orientation | ||
Instantaneously sets an object's spatial orientation.Takes 4 arguments... | Instantaneously sets an object's spatial orientation.Takes 4 arguments... | ||
| − | 1: The name of a ship | + | 1: The name of a ship or wing. |
2: The new pitch angle, in degrees. The angle can be any number; it does not have to be between 0 and 360. | 2: The new pitch angle, in degrees. The angle can be any number; it does not have to be between 0 and 360. | ||
3: The new bank angle, in degrees. The angle can be any can be any number; it does not have to be between 0 and 360. | 3: The new bank angle, in degrees. The angle can be any can be any number; it does not have to be between 0 and 360. | ||
4: The new heading angle, in degrees. The angle can be any number; it does not have to be between 0 and 360. | 4: The new heading angle, in degrees. The angle can be any number; it does not have to be between 0 and 360. | ||
| − | |||
===[[set-object-facing]]=== | ===[[set-object-facing]]=== | ||
set-object-facing | set-object-facing | ||
| − | + | Sets an object's orientation to face the specified coordinates. Takes 4 arguments... | |
| − | + | 1: The name of a ship or wing. | |
| − | + | 2: The X coordinate to face. | |
| − | + | 3: The Y coordinate to face. | |
| − | + | 4: The Z coordinate to face. | |
| − | + | 5: Turn time in milliseconds (optional) | |
| − | + | 6: Bank (optional). Enter a non-zero value to enable banking. | |
| − | + | Note that if Turn time is specified, this needs to be called once per frame, as the rotation is reset every frame. | |
| + | Note that Turn time is the time for the object to rotate a full revolution, *not* how long it will take to do this turn. | ||
===[[set-object-facing-object]]=== | ===[[set-object-facing-object]]=== | ||
set-object-facing-object | set-object-facing-object | ||
| − | + | Sets an object's orientation to face the specified object. Takes 2 arguments... | |
| − | + | 1: The name of a ship or wing. | |
| − | + | 2: The object to face. | |
| − | + | 3: Turn time in milliseconds (optional) | |
| − | + | 4: Bank (optional). Enter a non-zero value to enable banking. | |
| − | + | Note that if Turn time is specified, this needs to be called once per frame, as the rotation is reset every frame. | |
| − | + | Note that Turn time is the time for the object to rotate a full revolution, *not* how long it will take to do this turn. | |
| + | ===[[set-object-speed-x]]=== | ||
| + | set-object-speed-x (deprecated in favor of ship-maneuver) | ||
| + | Sets the X speed of a ship or wing.Takes 2 or 3 arguments... | ||
| + | 1: The name of the object. | ||
| + | 2: The speed to set. | ||
| + | 3: Whether the speed on the axis should be set according to the universe grid (when false) or according to the object's facing (when true); You almost always want to set this to true; (optional; defaults to false). | ||
| + | |||
| + | ===[[set-object-speed-y]]=== | ||
| + | set-object-speed-y (deprecated in favor of ship-maneuver) | ||
| + | Sets the Y speed of a ship or wing.Takes 2 or 3 arguments... | ||
| + | 1: The name of the object. | ||
| + | 2: The speed to set. | ||
| + | 3: Whether the speed on the axis should be set according to the universe grid (when false) or according to the object's facing (when true); You almost always want to set this to true; (optional; defaults to false). | ||
| + | |||
| + | ===[[set-object-speed-z]]=== | ||
| + | set-object-speed-z (deprecated in favor of ship-maneuver) | ||
| + | Sets the Z speed of a ship or wing.Takes 2 or 3 arguments... | ||
| + | 1: The name of the object. | ||
| + | 2: The speed to set. | ||
| + | 3: Whether the speed on the axis should be set according to the universe grid (when false) or according to the object's facing (when true); You almost always want to set this to true; (optional; defaults to false). | ||
| + | |||
| + | ===[[ship-maneuver]]=== | ||
| + | ship-maneuver | ||
| + | Combines the effects of the ship-rot-maneuver and ship-lat-maneuver sexps. Takes 10 or 11 arguments: | ||
| + | 1: The name of a ship or wing | ||
| + | 2: Duration of the maneuver, in milliseconds. Specifying 0 or 1 indicates infinite duration. | ||
| + | 3: Heading movement velocity, as a percentage (-100 to 100) of the tabled maximum heading velocity, or 0 to not modify the ship's current value | ||
| + | 4: Pitch movement velocity, as a percentage (-100 to 100) of the tabled maximum pitch velocity, or 0 to not modify the ship's current value | ||
| + | 5: Bank movement velocity, as a percentage (-100 to 100) of the tabled maximum bank velocity, or 0 to not modify the ship's current value | ||
| + | 6: Whether to apply all of the rotational velocity values even if any of them are 0 | ||
| + | 7: Vertical movement velocity, as a percentage (-100 to 100) of the tabled maximum vertical velocity, or 0 to not modify the ship's current value | ||
| + | 8: Sideways movement velocity, as a percentage (-100 to 100) of the tabled maximum sideways velocity, or 0 to not modify the ship's current value | ||
| + | 9: Forward movement velocity, as a percentage (-100 to 100) of the tabled maximum forward velocity, or 0 to not modify the ship's current value | ||
| + | 10: Whether to apply all of the lateral velocity values even if any of them are 0 | ||
| + | 11: Maneuver flags (optional): a bitfield with any of the following options: | ||
| + | 1 or 2^0: don't bank when changing heading | ||
| + | 2 or 2^1: allow maneuvers exceeding tabled maximums (outside the -100 to 100 range) | ||
| + | 4 or 2^2: instantaneously jump to the goal velocity | ||
| + | |||
| + | ===[[ship-rot-maneuver]]=== | ||
| + | ship-rot-maneuver | ||
| + | Causes a ship to move in a rotational direction. For the purposes of this sexp, this means the ship rotates along its own heading, pitch, or bank axis (or a combination of axes) without regard to normal ship rotation rules. You may find it necessary to disable the ship AI (e.g. by issuing a play-dead order) before running this sexp. | ||
| + | |||
| + | Takes 6 or 7 arguments: | ||
| + | 1: The name of a ship or wing | ||
| + | 2: Duration of the maneuver, in milliseconds. Specifying 0 or 1 indicates infinite duration. | ||
| + | 3: Heading movement velocity, as a percentage (-100 to 100) of the tabled maximum heading velocity, or 0 to not modify the ship's current value | ||
| + | 4: Pitch movement velocity, as a percentage (-100 to 100) of the tabled maximum pitch velocity, or 0 to not modify the ship's current value | ||
| + | 5: Bank movement velocity, as a percentage (-100 to 100) of the tabled maximum bank velocity, or 0 to not modify the ship's current value | ||
| + | 6: Whether to apply all of the above velocity values even if any of them are 0 | ||
| + | 7: Maneuver flags (optional): a bitfield with any of the following options: | ||
| + | 1 or 2^0: don't bank when changing heading | ||
| + | 2 or 2^1: allow maneuvers exceeding tabled maximums (outside the -100 to 100 range) | ||
| + | 4 or 2^2: instantaneously jump to the goal velocity | ||
| + | |||
| + | ===[[ship-lat-maneuver]]=== | ||
| + | ship-lat-maneuver | ||
| + | Causes a ship to move in a lateral direction. For the purposes of this sexp, this means the ship translates along its own X, Y, or Z axis (or a combination of axes) without regard to normal ship movement rules. You may find it necessary to disable the ship AI (e.g. by issuing a play-dead order) before running this sexp. | ||
| + | |||
| + | Takes 6 or 7 arguments: | ||
| + | 1: The name of a ship or wing | ||
| + | 2: Duration of the maneuver, in milliseconds. Specifying 0 or 1 indicates infinite duration. | ||
| + | 3: Vertical movement velocity, as a percentage (-100 to 100) of the tabled maximum vertical velocity, or 0 to not modify the ship's current value | ||
| + | 4: Sideways movement velocity, as a percentage (-100 to 100) of the tabled maximum sideways velocity, or 0 to not modify the ship's current value | ||
| + | 5: Forward movement velocity, as a percentage (-100 to 100) of the tabled maximum forward velocity, or 0 to not modify the ship's current value | ||
| + | 6: Whether to apply all of the above velocity values even if any of them are 0 | ||
| + | 7: Maneuver flags (optional): a bitfield with any of the following options: | ||
| + | 1 or 2^0: don't bank when changing heading (which won't have any affect for lat-maneuver) | ||
| + | 2 or 2^1: allow maneuvers exceeding tabled maximums (outside the -100 to 100 range) | ||
| + | 4 or 2^2: instantaneously jump to the goal velocity | ||
| + | |||
| + | ===[[set-immobile]]=== | ||
| + | set-immobile | ||
| + | Prevents the specified ship(s) from moving in any way. | ||
| + | Takes 1 or more arguments... | ||
| + | All: List of ships on which to set the "immobile" flag | ||
| + | ===[[set-mobile]]=== | ||
| + | set-mobile | ||
| + | Allows the specified ship(s) to move. Opposite of set-immobile. | ||
| + | Takes 1 or more arguments... | ||
| + | All: List of ships on which to unset the "immobile" flag | ||
| + | ==Mission and Campaign== | ||
| + | ===[[end-mission]]=== | ||
| + | end-mission | ||
| + | Ends the mission as if the player had engaged his subspace drive, but without him doing so. Dumps the player back into a normal debriefing. Does not invoke red-alert status. | ||
| + | 1: End Mission even if the player is dead (optional; defaults to true) | ||
| + | 2: Boot the player out into the main hall instead of going to the debriefing (optional; defaults to false; not supported in multi) | ||
| + | 3: Go to the mainhall instead of starting the next mission (optional; defaults to false; not yet tested in multi) | ||
| + | ===[[force-jump]]=== | ||
| + | force-jump | ||
| + | Forces activation of the player's subspace drive, thus ending the mission. Takes no arguments. | ||
| + | ===[[set-debriefing-toggled]]=== | ||
| + | set-debriefing-toggled | ||
| + | Sets or clears the "toggle debriefing" mission flag. If set, the mission will have its debriefing turned off, unless it is a multiplayer dogfight mission, in which case its debriefing will be turned on. Takes 1 argument. | ||
| + | |||
| + | ===[[allow-treason]]=== | ||
| + | allow-treason | ||
| + | Turns the Allow Traitor switch on or off in mission. Takes 0 arguments. | ||
| + | 1: True/False. | ||
| + | ===[[grant-promotion]]=== | ||
| + | Grant promotion (Action operator) | ||
| + | In a single player game, this function grants a player an automatic promotion to the next rank which the player can obtain. If he is already at the highest rank, this operator has no effect. It takes no arguments. | ||
| + | ===[[grant-medal]]=== | ||
| + | Grant medal (Action operator) | ||
| + | In single player missions, this function grants the given medal to the player. Currently, only 1 medal will be allowed to be given per mission. | ||
| + | |||
| + | Takes 1 argument... | ||
| + | 1: Name of medal to grant to player. | ||
| + | ===[[tech-add-ships]]=== | ||
| + | Tech add ship (Action operator) | ||
| + | This operator makes the given ship type available in the techroom database. Players will then be able to view this ship's specs there. | ||
| + | |||
| + | Takes 1 or more arguments... | ||
| + | All: Name of ship type (or ship class) to add. | ||
| + | ===[[tech-add-weapons]]=== | ||
| + | Tech add weapon (Action operator) | ||
| + | This operator makes the given weapon available in the techroom database. Players will then be able to view this weapon's specs there. | ||
| + | |||
| + | Takes 1 or more arguments... | ||
| + | All: Name of weapon (primary or secondary) to add. | ||
| + | ===[[tech-add-intel]]=== | ||
| + | Tech add intel (Action operator, deprecated in favor of tech-add-intel-xstr) | ||
| + | This operator makes the given intel entry available in the techroom database. Players will then be able to view this intel entry there. | ||
| + | |||
| + | Takes 1 or more arguments... | ||
| + | All: Name of intel entry to add. | ||
| + | ===[[tech-remove-intel]]=== | ||
| + | Tech remove intel (Action operator, deprecated in favor of tech-remove-intel-xstr) | ||
| + | This operator removes the given intel entry in the techroom database. Players will then not be able to view this intel entry there. | ||
| + | |||
| + | Takes 1 or more arguments... | ||
| + | All: Name of intel entry to remove. | ||
| + | ===[[tech-add-intel-xstr]]=== | ||
| + | Tech add intel XSTR (Action operator) | ||
| + | This operator makes the given intel entry available in the techroom database. Players will then be able to view this intel entry there. | ||
| + | |||
| + | Takes 2 or more arguments... | ||
| + | 1: Name of intel entry to add. | ||
| + | 2: XSTR ID of intel entry, or -1 if there is no XSTR entry. | ||
| + | Use Add-Data for multiple entries. | ||
| + | |||
| + | IMPORTANT: Each additional entry in the list MUST HAVE two fields; any entry without both fields will be ignored, as will any successive entries. | ||
| + | ===[[tech-remove-intel-xstr]]=== | ||
| + | Tech remove intel XSTR (Action operator) | ||
| + | This operator removes the given intel entry, so it is no longer available in the techroom database. Players will then not be able to view this intel entry there. | ||
| + | |||
| + | Takes 2 or more arguments... | ||
| + | 1: Name of intel entry to remove. | ||
| + | 2: XSTR ID of intel entry, or -1 if there is no XSTR entry. | ||
| + | Use Add-Data for multiple entries. | ||
| + | |||
| + | IMPORTANT: Each additional entry in the list MUST HAVE two fields; any entry without both fields will be ignored, as will any successive entries. | ||
| + | ===[[tech-reset-to-default]]=== | ||
| + | Tech reset to default (Action operator) | ||
| + | This operator resets the tech room to the default represented in the tables. This is useful for starting new campaigns, so that the player will not see tech entries carried over from previous campaigns. | ||
| + | |||
| + | Takes no arguments. | ||
| + | ===[[change-player-score]]=== | ||
| + | Change Player Score (Action operator) | ||
| + | This operator allows direct alteration of the player's score for this mission. | ||
| + | |||
| + | Takes 2 or more arguments. 1: Amount to alter the player's score by. | ||
| + | Rest: Name of ship the player is flying. | ||
| + | ===[[change-team-score]]=== | ||
| + | Change Team Score (Action operator) | ||
| + | This operator allows direct alteration of the team's score for a TvT mission (Does nothing otherwise). | ||
| + | |||
| + | Takes 2 arguments. 1: Amount to alter the team's score by. | ||
| + | 2: The team to alter the score for. (0 will add the score to all teams!) | ||
| + | ===[[set-respawns]]=== | ||
| + | set-respawns | ||
| + | Set the # respawns a player (or AI that could have been a player) has used. | ||
| + | 1: Number of respawns used up | ||
| + | Rest: The player start ship to operate on. | ||
| + | Only really useful for multiplayer. | ||
| + | ===[[add-remove-hotkey]]=== | ||
| + | add-remove-hotkey | ||
| + | Add or remove hotkey for the specified ship(s) or wing(s) | ||
| + | Takes 3 or more arguments | ||
| + | 1: Boolean. True adds hotkey and false removes hotkey. | ||
| + | 2: Integer of hotkey to add or remove. 0=F5, 1=F6, ... | ||
| + | (rest): Name(s) of ship(s) or wing(s) | ||
==Music and Sound== | ==Music and Sound== | ||
===[[change-soundtrack]]=== | ===[[change-soundtrack]]=== | ||
change-soundtrack | change-soundtrack | ||
| − | + | Changes the mission music. Takes 1 argument... | |
| − | + | 1: Name of the music selection (taken from music.tbl) | |
| − | |||
===[[play-sound-from-table]]=== | ===[[play-sound-from-table]]=== | ||
play-sound-from-table | play-sound-from-table | ||
| − | + | Plays a sound listed in the Game Sounds section of sounds.tbl. Note that if the sound is a non-3D sound (if the min and max radius are 0, or unspecified), the sound will just play without being fixed at a particular position in space. In this case, the origin coordinates will be ignored. (A better design would have put the sound index first and made the origin arguments optional, but the difference between 2D and 3D sounds was not understood at the time. C'est la vie.) | |
| − | + | ||
| − | + | Takes 4 arguments... | |
| − | + | 1: Origin X | |
| − | + | 2: Origin Y | |
| − | + | 3: Origin Z | |
| + | 4: Sound (index into sounds.tbl or name of the sound entry) | ||
===[[play-sound-from-file]]=== | ===[[play-sound-from-file]]=== | ||
play-sound-from-file | play-sound-from-file | ||
| − | + | Plays a sound, such as a music soundtrack, from a file. Multiple sounds can be played with this sexp by assigning each sound to a music handle stored in a variable. | |
| − | + | Takes 1 to 4 arguments... | |
| − | + | 1: Sound (file name) | |
| − | + | 2: Enter a non-zero number to loop. default is off (optional). | |
| − | + | 3: Enter a non-zero number to use environment effects. default is off (optional). | |
| + | 4: Variable in which the music handle is to be stored (optional). If no variable is specified, the 'default' handle is used. Only one 'default' track can be played at a time, but multiple variable-managed tracks can be played. | ||
| + | |||
===[[close-sound-from-file]]=== | ===[[close-sound-from-file]]=== | ||
close-sound-from-file | close-sound-from-file | ||
| − | + | Closes the currently playing sound started by play-sound-from-file, if there is any. Takes 0 to 2 arguments... | |
| − | + | 1: Fade (optional; default is true) | |
| − | + | 2: Variable containing a music handle (optional). If no variable is specified, the 'default' handle is used. | |
| − | == | + | ===[[pause-sound-from-file]]=== |
| + | pause-sound-from-file | ||
| + | Pauses or unpauses the currently playing sound started by play-sound-from-file, if there is any. Takes 1 or 2 arguments... | ||
| + | 1: Boolean - True to pause, False to unpause | ||
| + | 2: Variable containing a music handle (optional). If no variable is specified, the 'default' handle is used. | ||
| + | ===[[set-sound-environment]]=== | ||
| + | set-sound-environment | ||
| + | Sets the EAX environment for all sound effects. Optionally sets one or more parameters specific to the environment. Takes 1 or more arguments... | ||
| + | 1: Sound environment name (a value of "<none>" will disable the effects) | ||
| + | 2: Environment option (optional) | ||
| + | 3: Environment value x 1000, e.g. 10 is 0.01 (optional) | ||
| + | Use Add-Data to specify additional environment options in repeating option-value pairs, just like Send-Message-List can have additional messages in source-priority-message-delay groups. | ||
| + | |||
| + | IMPORTANT: each additional option in the list MUST HAVE two entries; any option without the two proper fields will be ignored, as will any successive options. | ||
| + | ===[[update-sound-environment]]=== | ||
| + | update-sound-environment | ||
| + | Updates the current EAX environment with new values. Takes 2 or more arguments... | ||
| + | 1: Environment option | ||
| + | 2: Environment value x 1000, e.g. 10 is 0.01 | ||
| + | Use Add-Data to specify additional environment options in repeating option-value pairs, just like Send-Message-List can have additional messages in source-priority-message-delay groups. | ||
| + | |||
| + | IMPORTANT: Each additional option in the list MUST HAVE two entries; any option without the two proper fields will be ignored, as will any successive options. | ||
| + | ===[[adjust-audio-volume]]=== | ||
| + | adjust-audio-volume | ||
| + | Adjusts the relative volume of one sound type. Takes 1 to 3 arguments.... | ||
| + | 1: Sound Type to adjust, either Music, Voice or Effects. Will act as a reset for the given category, if no other argument present | ||
| + | 2: Percentage of the users' settings to adjust to (optional), 0 will be silence, 100 means the maximum volume as set by the user | ||
| + | 3: Fade time (optional), time in milliseconds to adjust the volume | ||
| + | ==HUD== | ||
===[[hud-disable]]=== | ===[[hud-disable]]=== | ||
hud-disable | hud-disable | ||
| − | + | Sets whether the hud is disabled. Takes 1 argument... | |
| − | + | 1: Flag (1 to disable, 0 to re-enable) | |
| − | |||
===[[hud-disable-except-messages]]=== | ===[[hud-disable-except-messages]]=== | ||
hud-disable-except-messages | hud-disable-except-messages | ||
| − | + | Sets whether the hud (except for messages) is disabled. Takes 1 argument... | |
| − | + | 1: Flag (1 to disable, 0 to re-enable) | |
| − | + | ===[[hud-set-custom-gauge-active]]=== | |
| + | hud-set-custom-gauge-active | ||
| + | Activates or deactivates a custom hud gauge defined in hud_gauges.tbl.Takes 2 Arguments... | ||
| + | 1: Boolean, whether or not to display this gauge | ||
| + | Rest: HUD Gauge name | ||
| + | |||
| + | ===[[hud-set-retail-gauge-active]]=== | ||
| + | hud-set-custom-gauge-active | ||
| + | Activates or deactivates a retail hud gauge grouping.Takes 2 Arguments... | ||
| + | 1: Boolean, whether or not to display this gauge | ||
| + | Rest: HUD Gauge Group name | ||
| + | |||
===[[hud-set-text]]=== | ===[[hud-set-text]]=== | ||
hud-set-text | hud-set-text | ||
| − | + | Sets the text value of a given HUD gauge. Works for custom and certain retail gauges. Takes 2 arguments... | |
| − | + | 1: HUD gauge to be modified | |
| − | + | 2: Text to be set | |
| − | |||
===[[hud-set-text-num]]=== | ===[[hud-set-text-num]]=== | ||
hud-set-text-num | hud-set-text-num | ||
| − | + | Sets the text value of a given HUD gauge to a number. Works for custom and certain retail gauges. Takes 2 arguments... | |
| − | + | 1: HUD gauge to be modified | |
| − | + | 2: Number to be set | |
| − | + | ===[[hud-set-message]]=== | |
| − | ===[[hud-set- | + | hud-set-message |
| − | hud-set- | + | Sets the text value of a given HUD gauge to a message from the mission's message list. Works for custom and certain retail gauges. Takes 2 arguments... |
| − | + | 1: HUD gauge to be modified | |
| − | + | 2: Message | |
| − | + | ===[[hud-set-directive]]=== | |
| − | + | hud-set-directive | |
| − | + | Sets the text of a given custom hud gauge to the provided text.Takes 2 Arguments... | |
| + | 1: HUD Gauge name | ||
| + | 2: Text that will be displayed. This text will be treated as directive text, meaning that references to mapped keys will be replaced with the user's preferences. | ||
| + | |||
===[[hud-set-frame]]=== | ===[[hud-set-frame]]=== | ||
hud-set-frame | hud-set-frame | ||
| − | + | Sets the frame of a given HUD gauge's associated image. Works for custom and certain retail gauges. Takes 2 arguments... | |
| − | + | 1: HUD gauge to be modified | |
| − | + | 2: Frame number to be changed to | |
| − | + | ===[[hud-set-coords]]=== | |
| + | hud-set-coord | ||
| + | Sets the coordinates of a given HUD gauge. Works for custom and retail gauges. Takes 3 arguments... | ||
| + | 1: HUD gauge to be modified | ||
| + | 2: Coordinate X component | ||
| + | 2: Coordinate Y component | ||
===[[hud-set-color]]=== | ===[[hud-set-color]]=== | ||
hud-set-color | hud-set-color | ||
| − | + | Sets the color of a given HUD gauge. Works only for custom gauges Takes 4 arguments... | |
| − | + | 1: HUD gauge to be modified | |
| − | + | 2: Red component (0-255) | |
| − | + | 3: Green component (0-255) | |
| − | + | 4: Blue component (0-255) | |
| − | + | ===[[hud-display-gauge]]=== | |
| + | hud-display-gauge <milliseconds> <gauge> | ||
| + | Causes specified hud gauge to appear or disappear for so many milliseconds. Takes 1 argument... | ||
| + | 1: Number of milliseconds that the warpout gauge should appear on the HUD. 0 will immediately cause the gauge to disappear. | ||
| + | 2: Name of HUD element. Must be one of: | ||
| + | warpout - the "Subspace drive active" box that appears above the viewscreen. | ||
| + | |||
| + | ===[[hud-gauge-set-active]]=== | ||
| + | hud-gauge-set-active (deprecated) | ||
| + | Activates or deactivates a given custom gauge.Takes 2 Arguments... | ||
| + | 1: HUD Gauge name | ||
| + | 2: Boolean, whether or not to display this gauge | ||
| + | |||
| + | ===[[hud-activate-gauge-type]]=== | ||
| + | hud-activate-gauge-type (deprecated) | ||
| + | Activates or deactivates all hud gauges of a given type.Takes 2 Arguments... | ||
| + | 1: Gauge Type | ||
| + | 2: Boolean, whether or not to display this gauge | ||
| + | |||
===[[hud-clear-messages]]=== | ===[[hud-clear-messages]]=== | ||
hud-clear-messages | hud-clear-messages | ||
| − | + | Clears active messages displayed on the HUD.Takes no arguments | |
| − | + | ||
| − | ===[[ | + | ===[[hud-set-max-targeting-range]]=== |
| − | + | hud-set-max-targeting-range | |
| − | + | Sets the farthest distance at which an object can be targeted. Takes 1 argument... | |
| − | + | �: Maximum targeting distance (0 for infinite) | |
| − | + | ||
| − | + | ==Nav Points== | |
| + | ===[[add-nav-waypoint]]=== | ||
| + | add-nav-waypoint | ||
| + | Adds a Navpoint to a navpoint path. Takes 3 or 4 Arguments... | ||
| + | 1: Name of the new navpoint. | ||
| + | 2: Name of the navpoint path the new navpoint should be added to. | ||
| + | 3: Position where the new navpoint will be inserted. Note: This is 1-indexed, so the first waypoint in a path has position 1. | ||
| + | 4: (Optional Argument) Controls the visibility of the new navpoint. Only entities belonging to the chosen category will be able to see it. | ||
| + | |||
| + | ===[[add-nav-ship]]=== | ||
| + | add-nav-ship | ||
| + | Binds the named navpoint to the named ship - when the ship moves, the waypoint moves with it. Takes 2 Arguments... | ||
| + | 1: The NavPoint's Name | ||
| + | 2: The Ship's Name | ||
| + | |||
| + | ===[[del-nav]]=== | ||
| + | del-nav | ||
| + | Deletes a nav point. Takes 1 Argument... | ||
| + | 1: NavPoint Name | ||
| + | ===[[hide-nav]]=== | ||
| + | hide-nav | ||
| + | Hides a nav point. Takes 1 Argument... | ||
| + | 1: NavPoint Name, it then 'hides' that Nav Point | ||
| + | |||
| + | ===[[restrict-nav]]=== | ||
| + | restrict-nav | ||
| + | This causes the nav point to be unselectable. Takes 1 Argument... | ||
| + | 1: The Navpoint name | ||
| + | |||
| + | ===[[unhide-nav]]=== | ||
| + | unhide-nav | ||
| + | Restores a hidden navpoint. Takes 1 Argument... | ||
| + | 1: The Navpoint Name | ||
| + | |||
| + | ===[[unrestrict-nav]]=== | ||
| + | unrestrict-nav | ||
| + | Removes restrictions from a Navpoint. Takes 1 Argument... | ||
| + | 1: The Navpoint Name | ||
| + | |||
| + | ===[[set-nav-visited]]=== | ||
| + | set-nav-visited | ||
| + | Sets the status of the given Navpoint to "visited". Takes 1 Argument... | ||
| + | 1: The Navpoint Name | ||
| + | |||
| + | ===[[unset-nav-visited]]=== | ||
| + | unset-nav-visited | ||
| + | Removes the "visited" status from a Navpoint. Takes 1 Argument... | ||
| + | 1: The Navpoint Name | ||
| + | |||
| + | ===[[set-nav-carry]]=== | ||
| + | nav-set-carry | ||
| + | Sets the Nav Carry flag for all listed ships. Vessels with this flag will follow the player into and out of autopilot. | ||
| + | Takes 1 or more arguments... | ||
| + | 1: Ships and Wings that should receive the Nav Carry flag. | ||
| + | |||
| + | ===[[unset-nav-carry]]=== | ||
| + | unset-nav-carry | ||
| + | Removes the Nav Carry flag from all listed ships and wings. Takes 1 or more arguments... | ||
| + | 1: Ships and Wings to remove the Nav Carry flag from | ||
| + | |||
| + | ===[[set-nav-needslink]]=== | ||
| + | set-nav-needslink | ||
| + | Marks all listed ships as needing to link up before entering autopilot. | ||
| + | Takes 1 or more arguments... | ||
| + | 1: Ships to mark | ||
| + | |||
| + | ===[[unset-nav-needslink]]=== | ||
| + | unset-nav-needslink | ||
| + | Removes the requirement for the listed ships to link up before entering autopilot. | ||
| + | Takes 1 or more arguments... | ||
| + | 1: Ships to mark | ||
| + | |||
| + | ===[[use-nav-cinematics]]=== | ||
| + | use-nav-cinematics | ||
| + | Controls the use of the cinematic autopilot camera. Takes 1 Argument... 1: Set to true to enable automatic cinematics, set to false to disable automatic cinematics. | ||
| + | ===[[use-autopilot]]=== | ||
| + | use-autopilot | ||
| + | Takes 1 boolean argument. | ||
| + | 1: Set to true to enable autopilot, set to false to disable autopilot. | ||
| + | ===[[select-nav]]=== | ||
| + | nav-select (Action operator) | ||
| + | Selects a nav point. | ||
| + | |||
| + | Takes 1 argument... | ||
| + | 1: Name of the nav point. | ||
| + | ===[[unselect-nav]]=== | ||
| + | nav-deselect (Action operator) | ||
| + | Deselects any navpoint selected. | ||
| + | |||
| + | Takes no arguments... | ||
==Cutscenes== | ==Cutscenes== | ||
===[[set-cutscene-bars]]=== | ===[[set-cutscene-bars]]=== | ||
set-cutscene-bars | set-cutscene-bars | ||
| − | + | Shows bars at the top and bottom of screen. Takes 0 or 1 arguments... | |
| − | + | 1: Milliseconds for bars to slide in | |
| − | + | ||
===[[unset-cutscene-bars]]=== | ===[[unset-cutscene-bars]]=== | ||
unset-cutscene-bars | unset-cutscene-bars | ||
| − | + | Removes cutscene bars. Takes 0 or 1 arguments... | |
| − | + | 1: Milliseconds for bars to slide out | |
| − | + | ||
===[[fade-in]]=== | ===[[fade-in]]=== | ||
fade-in | fade-in | ||
| − | + | Fades in. Takes 0 to 4 arguments... | |
| − | + | 1: Time to fade in (in milliseconds) | |
| − | + | 2: Color to fade to (optional). If arguments 3 and 4 are specified, this is the R component of an RGB color. Otherwise it is 1 for white, 2 for red, and any other number for black. | |
| + | 3: G component of an RGB color (optional) | ||
| + | 4: B component of an RGB color (optional) | ||
| + | |||
===[[fade-out]]=== | ===[[fade-out]]=== | ||
fade-out | fade-out | ||
| − | + | Fades out. Takes 0 to 4 arguments... | |
| − | + | 1: Time to fade in (in milliseconds) | |
| − | + | 2: Color to fade to (optional). If arguments 3 and 4 are specified, this is the R component of an RGB color. Otherwise it is 1 for white, 2 for red, and any other number for black. | |
| − | + | 3: G component of an RGB color (optional) | |
| + | 4: B component of an RGB color (optional) | ||
| + | |||
| + | ===[[set-camera]]=== | ||
| + | set-camera | ||
| + | Sets SEXP camera, or another specified cutscene camera. Takes 0 to 1 arguments... | ||
| + | (optional) | ||
| + | 1: Camera name (created if nonexistent) | ||
| + | |||
===[[set-camera-position]]=== | ===[[set-camera-position]]=== | ||
set-camera-position | set-camera-position | ||
| − | + | Sets the camera position to a spot in mission space. Takes 3 to 6 arguments... | |
| − | + | 1: X position | |
| − | + | 2: Y position | |
| − | + | 3: Z position | |
| − | + | (optional) | |
| + | 4: Total turn time (milliseconds) | ||
| + | 5: Time to spend accelerating/decelerating (milliseconds) | ||
| + | 6: Time to spend decelerating (milliseconds) | ||
| + | |||
===[[set-camera-facing]]=== | ===[[set-camera-facing]]=== | ||
set-camera-facing | set-camera-facing | ||
| − | + | Makes the camera face the given point. Takes 3 to 6 arguments... | |
| − | + | 1: X position to face | |
| − | + | 2: Y position to face | |
| − | + | 3: Z position to face | |
| − | + | (optional) | |
| − | + | 4: Total turn time (milliseconds) | |
| − | + | 5: Time to spend accelerating/decelerating (milliseconds) | |
| + | 6: Time to spend decelerating (milliseconds) | ||
| + | |||
===[[set-camera-facing-object]]=== | ===[[set-camera-facing-object]]=== | ||
set-camera-facing-object | set-camera-facing-object | ||
| − | + | Makes the camera face the given object. Takes 1 to 4 arguments... | |
| − | + | 1: Object to face | |
| − | + | (optional) | |
| − | + | 2: Total turn time (milliseconds) | |
| − | + | 3: Time to spend accelerating/decelerating (milliseconds) | |
| + | 4: Time to spend decelerating (milliseconds) | ||
| + | |||
===[[set-camera-rotation]]=== | ===[[set-camera-rotation]]=== | ||
set-camera-rotation | set-camera-rotation | ||
| − | + | Sets the camera rotation. Takes 3 to 6 arguments... | |
| − | + | 1: Pitch (degrees) | |
| − | + | 2: Bank (degrees) | |
| − | + | 3: Heading (degrees) | |
| − | + | (optional) | |
| − | + | 4: Total turn time (milliseconds) | |
| − | + | 5: Time to spend accelerating/decelerating (milliseconds) | |
| + | 6: Time to spend decelerating (milliseconds) | ||
| + | |||
| + | ===[[set-camera-host]]=== | ||
| + | set-camera-host | ||
| + | Sets the object and subystem camera should view from. Camera position is offset from the host. If the selected subsystem or one of its children has an eyepoint bound to it it will be used for the camera position and orientation.If the selected subsystem is a turret and has no eyepoint the camera will be at the first firing point and look along the firing direction.If a valid camera target is set the direction to the target will override any other orientation.Takes 1 to 2 arguments... | ||
| + | 1: Ship to mount camera on | ||
| + | (optional) | ||
| + | 2: Subystem to mount camera on | ||
| + | |||
| + | ===[[set-camera-target]]=== | ||
| + | set-camera-target | ||
| + | Sets the object and subystem camera should track. Camera orientation is offset from the target. Takes 1 to 2 arguments... | ||
| + | 1: Ship to track | ||
| + | (optional) | ||
| + | 2: Subystem to track | ||
| + | |||
| + | ===[[set-camera-fov]]=== | ||
| + | set-camera-fov | ||
| + | Sets the camera field of view. Takes 1 to 4 arguments... | ||
| + | 1: New FOV (degrees) | ||
| + | (optional) | ||
| + | 2: Total zoom time (milliseconds) | ||
| + | 3: Time to spend accelerating/decelerating (milliseconds) | ||
| + | 4: Time to spend decelerating (milliseconds) | ||
| + | |||
===[[set-fov]]=== | ===[[set-fov]]=== | ||
set-fov | set-fov | ||
| − | + | Sets the field of view - overrides all camera settings. Takes 1 argument... | |
| − | + | 1: New FOV (degrees) | |
| − | + | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
===[[reset-fov]]=== | ===[[reset-fov]]=== | ||
reset-fov | reset-fov | ||
| − | + | Resets the field of view. | |
| − | |||
===[[reset-camera]]=== | ===[[reset-camera]]=== | ||
reset-camera | reset-camera | ||
| − | + | Releases cutscene camera control. Takes 1 optional argument... | |
| − | + | (optional) | |
| + | 1: Reset camera data (Position, facing, FOV...) (default: false) | ||
===[[show-subtitle]]=== | ===[[show-subtitle]]=== | ||
| − | show-subtitle | + | show-subtitle (deprecated) |
| − | + | Displays a subtitle, either an image or a string of text. As this operator tries to combine two functions into one and does not adjust coordinates for screen formats, it has been deprecated. | |
| − | + | Takes 4 to 13 arguments... | |
| − | + | 1: X position (negative value to be from right of screen) | |
| − | + | 2: Y position (negative value to be from bottom of screen) | |
| − | + | 3: Text to display | |
| − | + | 4: Time to be displayed, not including fadein/out | |
| − | + | 5: Image name (optional) | |
| − | + | 6: Fade in time (optional) | |
| − | + | 7: Center horizontally? (optional) | |
| − | + | 8: Center vertically? (optional) | |
| − | + | 9: Width (optional) | |
| − | + | 10: Text red component (0-255) (optional) | |
| − | + | 11: Text green component (0-255) (optional) | |
| − | + | 12: Text blue component (0-255) (optional) | |
| − | + | 13: Drawn after shading? (optional) | |
| − | + | ===[[show-subtitle-text]]=== | |
| − | ===[[ | + | show-subtitle-text |
| − | + | Displays a subtitle in the form of text. Note that because of the constraints of the subtitle system, textual subtitles are currently limited to 255 characters or fewer. | |
| − | + | Takes 6 to 13 arguments... | |
| − | + | 1: Text to display, or the name of a message containing text | |
| − | + | 2: X position, from 0 to 100% (positive measures from the left; negative measures from the right) | |
| − | + | 3: Y position, from 0 to 100% (positive measures from the top; negative measures from the bottom) | |
| − | + | 4: Center horizontally? (if true, overrides argument #2) | |
| − | ===[[ | + | 5: Center vertically? (if true, overrides argument #3) |
| − | + | 6: Time (in milliseconds) to be displayed, not including fade-in/fade-out | |
| − | + | 7: Fade time (in milliseconds) to be used for both fade-in and fade-out (optional) | |
| − | + | 8: Paragraph width, from 1 to 100% (optional; 0 uses default 200 pixels) | |
| + | 9: Text red component (0-255) (optional) | ||
| + | 10: Text green component (0-255) (optional) | ||
| + | 11: Text blue component (0-255) (optional) | ||
| + | 12: Text font (optional) | ||
| + | 13: Drawn after shading? (optional) | ||
| + | ===[[show-subtitle-image]]=== | ||
| + | show-subtitle-image | ||
| + | Displays a subtitle in the form of an image. | ||
| + | Takes 8 to 10 arguments... | ||
| + | 1: Image to display | ||
| + | 2: X position, from 0 to 100% (positive measures from the left; negative measures from the right) | ||
| + | 3: Y position, from 0 to 100% (positive measures from the top; negative measures from the bottom) | ||
| + | 4: Center horizontally? (if true, overrides argument #2) | ||
| + | 5: Center vertically? (if true, overrides argument #3) | ||
| + | 6: Image width, from 1 to 100% (0 uses original width) | ||
| + | 7: Image height, from 1 to 100% (0 uses original height) | ||
| + | 8: Time (in milliseconds) to be displayed, not including fade-in/fade-out | ||
| + | 9: Fade time (in milliseconds) to be used for both fade-in and fade-out (optional) | ||
| + | 10: Drawn after shading? (optional) | ||
| + | ===[[clear-subtitles]]=== | ||
| + | clear-subtitles | ||
| + | Clears the subtitle queue completely. | ||
| + | |||
===[[lock-perspective]]=== | ===[[lock-perspective]]=== | ||
lock-perspective | lock-perspective | ||
| − | + | Prevents or allows the player from changing the view mode. Takes 1 or 2 arguments... | |
| − | + | 1: True to lock the view mode, false to unlock it | |
| − | + | 2: What view mode to lock; 0 for first-person, 1 for chase, 2 for external, 3 for top-down | |
| − | |||
===[[set-camera-shudder]]=== | ===[[set-camera-shudder]]=== | ||
set-camera-shudder | set-camera-shudder | ||
| − | + | Causes the camera to shudder. Currently this will only work if the camera is showing the player's viewpoint (i.e. the HUD). | |
| − | + | ||
| + | Takes 2 arguments... | ||
| + | 1: Time (in milliseconds) | ||
| + | 2: Intensity. For comparison, the Maxim has an intensity of 1440. | ||
| + | ===[[supernova-stop]]=== | ||
| + | supernova-stop | ||
| + | Stops a supernova in progress. | ||
| + | Note this only works if the camera hasn't cut to the player's death animation yet. | ||
| + | |||
| + | ===[[set-motion-debris-override]]=== | ||
| + | set-motion-debris-override | ||
| + | Controls whether or not motion debris should be active. | ||
| + | This overrides any choice made by the user through the -nomotiondebris commandline flag.Takes 1 argument... | ||
| + | 1: Boolean: True will disable motion debris, False reenable it. | ||
| + | |||
| + | ==Backgrounds and Nebulae== | ||
| + | ===[[mission-set-nebula]]=== | ||
| + | mission-set-nebula | ||
| + | Turns nebula on/off | ||
| + | Takes1 argument... | ||
| + | 1: 0 for nebula off, 1 for nebula on | ||
| + | ===[[mission-set-subspace]]=== | ||
| + | mission-set-subspace | ||
| + | Turns subspace on/off | ||
| + | Takes 1 argument... | ||
| + | 1: 0 for subspace off, 1 for subspace on | ||
| + | ===[[add-background-bitmap]]=== | ||
| + | add-background-bitmap | ||
| + | Adds a background bitmap to the sky. Returns an integer that is stored in a variable so it can be deleted using remove-background-bitmap | ||
| + | |||
| + | Takes 8 to 9 arguments... | ||
| + | 1: Background bitmap name | ||
| + | 2: Pitch | ||
| + | 3: Bank | ||
| + | 4: Heading | ||
| + | 5: X scale (expressed as a percentage of the original size of the bitmap) | ||
| + | 6: Y scale (expressed as a percentage of the original size of the bitmap) | ||
| + | 7: X divisions. | ||
| + | 8: Y divisions. | ||
| + | 9: Variable in which to store result (optional) | ||
| + | |||
| + | ===[[remove-background-bitmap]]=== | ||
| + | remove-background-bitmap | ||
| + | Removes the nth background bitmap from the mission | ||
| + | |||
| + | Takes 1 argument... | ||
| + | 1: Zero based bitmap index from the 'Bitmap' box in the background editor | ||
| + | You can also use the result of a previous call to add-background-bitmap to remove that added bitmap | ||
| + | |||
| + | ===[[add-sun-bitmap]]=== | ||
| + | add-sun-bitmap | ||
| + | Adds a sun bitmap to the sky. Returns an integer that is stored in a variable so it can be deleted using remove-sun-bitmap | ||
| + | |||
| + | Takes 5 to 6 arguments... | ||
| + | 1: Sun bitmap name | ||
| + | 2: Pitch | ||
| + | 3: Bank | ||
| + | 4: Heading | ||
| + | 5: Scale (expressed as a percentage of the original size of the bitmap) | ||
| + | 6: Variable in which to store result (optional) | ||
| − | + | ===[[remove-sun-bitmap]]=== | |
| − | + | remove-sun-bitmap | |
| − | + | Removes the nth sun from the mission | |
| + | |||
| + | Takes 1 argument... | ||
| + | 1: Zero based sun index from the 'Suns' box in the background editor | ||
| + | You can also use the result of a previous call to add-sun-bitmap to remove that added sun | ||
| + | |||
| + | ===[[nebula-change-storm]]=== | ||
| + | nebula-change-storm | ||
| + | Changes the current nebula storm | ||
| + | |||
| + | Takes 1 argument... | ||
| + | 1: Nebula storm to change to | ||
| + | |||
| + | ===[[nebula-toggle-poof]]=== | ||
| + | nebula-toggle-poof | ||
| + | Toggles the state of a nebula poof | ||
| + | |||
| + | Takes 2 arguments... | ||
| + | 1: Name of nebula poof to toggle | ||
| + | 2: A True boolean expression will toggle this poof on. A false one will do the opposite. | ||
| + | ===[[nebula-change-pattern]]=== | ||
| + | nebula-change-pattern | ||
| + | Changes the current nebula background pattern (as defined in nebula.tbl) | ||
| + | |||
| + | Takes 1 argument... | ||
| + | 1: Nebula background pattern to change to | ||
| + | |||
| + | ===[[set-skybox-model]]=== | ||
| + | set-skybox-model | ||
| + | Sets the current skybox model. Takes 1-7 arguments | ||
| + | 1: Model filename (with .pof extension) to switch to | ||
| + | 2: Restart animated textures, if they exist (optional, defaults to true) | ||
| + | 3-8: Set or unset the following skyboxes flags (optional) | ||
| + | add-lighting, no-transparency, add-zbuffer | ||
| + | add-culling, no-glowmaps, force-clamp | ||
| + | |||
| + | Note: If the model filename is set to "default" with no extension then it will switch to the mission supplied default skybox. | ||
| + | ===[[set-skybox-orientation]]=== | ||
| + | set-skybox-orientation | ||
| + | Sets the current skybox orientation. Takes 3 arguments... | ||
| + | 1: Pitch | ||
| + | 2: Bank | ||
| + | 3: Heading | ||
| + | |||
| + | ===[[set-ambient-light]]=== | ||
| + | set-ambient-light | ||
| + | Sets the ambient light level for the mission | ||
| + | Takes 3 arguments | ||
| + | 1: Red (0 - 255). | ||
| + | 2: Green (0 - 255). | ||
| + | 3: Blue (0 - 255). | ||
==Jump Nodes== | ==Jump Nodes== | ||
| + | ===[[set-jumpnode-name]]=== | ||
| + | set-jumpnode-name | ||
| + | Sets the name of a jump node. Takes 2 arguments... | ||
| + | 1: Name of jump node to change name for | ||
| + | 2: New name for jump node | ||
| + | |||
| + | Note: SEXPs referencing the old name will not work after the name change. | ||
| + | |||
===[[set-jumpnode-color]]=== | ===[[set-jumpnode-color]]=== | ||
set-jumpnode-color | set-jumpnode-color | ||
| − | + | Sets the color of a jump node. Takes 5 arguments... | |
| − | + | 1: Jump node to change color for | |
| − | + | 2: Red value | |
| − | + | 3: Green value | |
| − | + | 4: Blue value | |
| − | + | 5: Alpha value | |
| − | + | ||
===[[set-jumpnode-model]]=== | ===[[set-jumpnode-model]]=== | ||
set-jumpnode-model | set-jumpnode-model | ||
| − | + | Sets the model of a jump node. Takes 3 arguments... | |
| − | + | 1: Jump node to change model for | |
| − | + | 2: Model filename | |
| − | + | 3: Show as normal model. When this is true, the jumpnode will be rendered like a normal model. | |
| − | + | ||
===[[show-jumpnode]]=== | ===[[show-jumpnode]]=== | ||
show-jumpnode | show-jumpnode | ||
| − | + | Sets a jump node to display on the screen. | |
| − | + | Any: Jump node to show | |
| − | + | ||
===[[hide-jumpnode]]=== | ===[[hide-jumpnode]]=== | ||
hide-jumpnode | hide-jumpnode | ||
| − | + | Sets a jump node to not display on the screen. | |
| − | + | Any: Jump node to hide | |
| − | + | ||
| − | ==Special== | + | ==Special Effects== |
| − | ===[[ | + | ===[[set-post-effect]]=== |
| − | + | set-post-effect | |
| − | + | Configures a post-processing effect. Takes 2 arguments... | |
| − | + | 1: Effect type | |
| − | + | 2: Effect intensity (0 - 100). 3: (Optional) Red (0 - 255). 4: (Optional) Green (0 - 255). 5: (Optional) Blue (0 - 255). | |
| − | + | ===[[reset-post-effects]]=== | |
| − | + | reset-post-effects | |
| − | + | Resets all post-processing effects to their default values. Takes no arguments. | |
| − | + | ||
| − | + | ===[[ship-effect]]=== | |
| − | + | ship-effect | |
| − | + | Plays an animated shader effect on the ship(s) or wing(s). | |
| − | + | Takes 3 or more arguments... | |
| − | + | 1: Effect name (as defined in post_processing.tbl) | |
| − | + | 2: How long the effect should take in milliseconds | |
| − | + | Rest: Ship or wing name | |
| − | |||
| − | ===[[ | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | ===[[ship- | ||
| − | ship- | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
===[[ship-create]]=== | ===[[ship-create]]=== | ||
ship-create | ship-create | ||
| − | + | Creates a new ship | |
| − | + | Takes 5 to 8 arguments... | |
| − | + | 1: Name of new ship (use "<none>" for a default name) | |
| − | + | 2: Class of new ship | |
| − | + | 3: X position | |
| − | + | 4: Y position | |
| − | + | 5: Z position | |
| − | + | 6: Pitch (optional) | |
| − | + | 7: Bank (optional) | |
| − | + | 8: Heading (optional) | |
| − | + | ||
===[[weapon-create]]=== | ===[[weapon-create]]=== | ||
weapon-create | weapon-create | ||
| − | + | Creates a new weapon | |
| − | + | Takes 5 to 10 arguments... | |
| − | + | 1: Name of parent ship (or "<none>" for no parent) | |
| − | + | 2: Class of new weapon | |
| − | + | 3: X position | |
| − | + | 4: Y position | |
| − | + | 5: Z position | |
| − | + | 6: Pitch (optional) | |
| − | + | 7: Bank (optional) | |
| − | + | 8: Heading (optional) | |
| − | + | 9: Targeted ship (optional) | |
| − | + | 10: Targeted subsystem (optional) | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | ===[[ship-vaporize]]=== | |
| − | + | ship-vaporize | |
| − | ===[[ | + | Sets the ship to vaporize when it is destroyed. Does not actually destroy the ship - use self-destruct for that. |
| − | + | Takes 1 or more arguments... | |
| − | + | All: List of ships on which to set the vaporize flag | |
| − | + | ===[[ship-no-vaporize]]=== | |
| + | ship-no-vaporize | ||
| + | Sets the ship to not vaporize when it is destroyed. Does not actually destroy the ship - use self-destruct for that. | ||
| + | Takes 1 or more arguments... | ||
| + | All: List of ships on which to unset the vaporize flag | ||
| + | ===[[set-explosion-option]]=== | ||
| + | set-explosion-option | ||
| + | Sets an explosion option on a particular ship. Takes 3 or more arguments... | ||
| + | 1: Ship name | ||
| + | 2: Explosion option | ||
| + | 3: Explosion value (for shockwave speed, 0 will produce no shockwave; for death roll time, 0 will use the default time) | ||
| + | Use Add-Data to specify additional explosion options in repeating option-value pairs, just like Send-Message-List can have additional messages in source-priority-message-delay groups. | ||
| − | + | IMPORTANT: Each additional option in the list MUST HAVE two entries; any option without the two proper fields will be ignored, as will any successive options. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
===[[explosion-effect]]=== | ===[[explosion-effect]]=== | ||
explosion-effect | explosion-effect | ||
| − | + | Causes an explosion at a given origin, with the given parameters. Takes 11 to 14 arguments... | |
| − | + | 1: Origin X | |
| − | + | 2: Origin Y | |
| − | + | 3: Origin Z | |
| − | + | 4: Damage | |
| − | + | 5: Blast force | |
| − | + | 6: Size of explosion (if 0, explosion will not be visible) | |
| − | + | 7: Inner radius to apply damage (if 0, explosion will not be visible) | |
| − | + | 8: Outer radius to apply damage (if 0, explosion will not be visible) | |
| − | + | 9: Shockwave speed (if 0, there will be no shockwave) | |
| − | + | 10: Fireball Type (unique ID of a fireball entry, OR a number: 0 = medium explosion [default, 1st in table], 1 = large explosion 1 [4th in table], 2 = large explosion 2 [5th in table], 3 or greater the respective entry in fireball.tbl) | |
| − | + | 11: Sound (index into sounds.tbl or name of the sound entry) | |
| − | + | 12: EMP intensity (optional) | |
| − | + | 13: EMP duration in seconds (optional) | |
| − | + | 14: Whether to use the full EMP time for capship turrets (optional, defaults to false) | |
===[[warp-effect]]=== | ===[[warp-effect]]=== | ||
warp-effect | warp-effect | ||
| − | + | Causes a subspace warp effect at a given origin, facing toward a given location, with the given parameters. | |
| − | + | Takes 12 to 14 arguments... | |
| − | + | 1: Origin X | |
| − | + | 2: Origin Y | |
| − | + | 3: Origin Z | |
| − | + | 4: Location X | |
| − | + | 5: Location Y | |
| − | + | 6: Location Z | |
| − | + | 7: Radius | |
| − | + | 8: Duration in seconds (values smaller than 4 are ignored) | |
| − | + | 9: Warp opening sound (index into sounds.tbl or name of the sound entry) | |
| − | + | 10: Warp closing sound (index into sounds.tbl or name of the sound entry) | |
| − | + | 11: Fireball Type (unique ID of a fireball entry, OR a number: 0 for standard blue [default], 1 for Knossos green, 2 or greater the respective entry in fireball.tbl) | |
| − | + | 12: Shape (0 for 2-D [default], 1 for 3-D) | |
| − | + | 13: Duration of the opening effect, in milliseconds (and also the closing effect if the next argument is not specified) | |
| + | 14: Duration of the closing effect, in milliseconds | ||
| + | |||
===[[remove-weapons]]=== | ===[[remove-weapons]]=== | ||
remove-weapons | remove-weapons | ||
| − | + | Removes all live weapons currently in the game 1: (Optional) Remove only this specific weapon | |
| − | |||
| − | |||
| − | ===[[ | + | ===[[set-time-compression]]=== |
| − | + | set-time-compression | |
| − | + | Sets the time compression and prevents it from being changed by the user. Takes 1 to 3 arguments... | |
| − | + | 1: New time compression (% of 1x) | |
| − | + | 2: Time in ms for change to take | |
| − | + | 3: Time compression to start from | |
| − | ===[[ | + | |
| − | + | ===[[reset-time-compression]]=== | |
| − | + | reset-time-compression | |
| − | + | Resets the time compression - that is to say, time compression is set back to 1x, and the time compression controls are unlocked. Always call this when done with set-time-compression. | |
| − | |||
| − | |||
===[[call-ssm-strike]]=== | ===[[call-ssm-strike]]=== | ||
call-ssm-strike | call-ssm-strike | ||
| − | + | Calls a subspace missile strike on the specified ship. | |
| − | + | Requires a ssm table (ssm.tbl). | |
| − | + | Takes 3 arguments... | |
| − | + | 1: Strike name. | |
| − | + | 2: Calling team. | |
| − | + | Rest: List of ships the strike will be called on. | |
| − | + | ==Variables== | |
| − | == | + | ===[[get-variable-by-index]]=== |
| − | ===[[ | + | get-variable-by-index (originally variable-array-get) |
| − | + | Gets the value of the variable specified by the given index. This is an alternate way to access variables rather than by their names, and it enables cool features such as arrays and pointers. | |
| − | + | ||
| − | + | Please note that only numeric variables are supported. Any attempt to access a string variable will result in a value of SEXP_NAN_FOREVER being returned. | |
| − | + | ||
| − | + | Takes 1 argument... | |
| − | ===[[ | + | 1: Index of variable, from 0 to MAX_SEXP_VARIABLES - 1. |
| − | + | ===[[set-variable-by-index]]=== | |
| − | + | set-variable-by-index (originally variable-array-set) | |
| − | + | Sets the value of the variable specified by the given index. This is an alternate way to modify variables rather than by their names, and it enables cool features such as arrays and pointers. | |
| − | + | ||
| + | In contrast to get-variable-by-index, note that this sexp *does* allow the modification of string variables. | ||
| + | |||
| + | Takes 2 arguments... | ||
| + | 1: Index of variable, from 0 to MAX_SEXP_VARIABLES - 1. | ||
| + | 2: Value to be set. | ||
| + | ===[[copy-variable-from-index]]=== | ||
| + | copy-variable-from-index | ||
| + | Retrieves the value of the variable specified by the given index and stores it in another variable. This is very similar to get-variable-by-index, except the result is stored in a new variable rather than being returned by value. One important difference is that this sexp can be used to copy string variables as well as numeric variables. | ||
| + | |||
| + | Takes 2 arguments... | ||
| + | 1: Index of source variable, from 0 to MAX_SEXP_VARIABLES - 1. | ||
| + | 2: Destination variable. The type of this variable must match the type of the variable referenced by the index. | ||
| + | ===[[copy-variable-between-indexes]]=== | ||
| + | copy-variable-between-indexes | ||
| + | Retrieves the value of the variable specified by the first index and stores it in the variable specified by the second index. The first variable is not modified. | ||
| + | |||
| + | Takes 2 arguments... | ||
| + | 1: Index of source variable, from 0 to MAX_SEXP_VARIABLES - 1. | ||
| + | 2: Index of destination variable, from 0 to MAX_SEXP_VARIABLES - 1. The types of both variables must match. | ||
| + | ===[[int-to-string]]=== | ||
| + | int-to-string | ||
| + | Converts an integer into a string. The destination must be a string variable. | ||
| + | Takes 2 argument... | ||
| + | 1: Integer to convert | ||
| + | 2: String variable to contain the result | ||
| + | |||
| + | ===[[string-concatenate]]=== | ||
| + | string-concatenate (deprecated in favor of string-concatenate-block) | ||
| + | Concatenates two strings, putting the result into a string variable. If the length of the string will exceed the sexp variable token limit (currently 32), it will be truncated. | ||
| + | |||
| + | Takes 3 arguments... | ||
| + | 1: First string | ||
| + | 2: Second string | ||
| + | 3: String variable to hold the result | ||
| + | |||
| + | ===[[string-concatenate-block]]=== | ||
| + | string-concatenate-block | ||
| + | Concatenates two or more strings, putting the result into a string variable. If the length of the string will exceed the sexp variable token limit (currently 32), it will be truncated. | ||
| + | |||
| + | Takes 3 or more arguments... | ||
| + | 1: String variable to hold the result | ||
| + | Rest: Strings to concatenate. At least two of these are required; the rest are optional. | ||
| − | + | ===[[string-get-substring]]=== | |
| − | + | string-get-substring | |
| − | + | Extracts a substring from a parent string, putting the result into a string variable. If the length of the string will exceed the sexp variable token limit (currently 32), it will be truncated. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | ===[[ | ||
| − | |||
| − | |||
| − | |||
| − | + | Takes 3 arguments... | |
| − | + | 1: Parent string | |
| − | + | 2: Index at which the substring begins (0-based) | |
| − | + | 3: Length of the substring | |
| − | + | 4: String variable to hold the result | |
| − | |||
| − | |||
| − | + | ===[[string-set-substring]]=== | |
| − | + | string-set-substring | |
| − | + | Replaces a substring from a parent string with a new string, putting the result into a string variable. If the length of the string will exceed the sexp variable token limit (currently 32), it will be truncated. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | ===[[ | ||
| − | |||
| − | |||
| − | |||
| − | + | Takes 3 arguments... | |
| − | + | 1: Parent string | |
| − | + | 2: Index at which the substring begins (0-based) | |
| − | + | 3: Length of the substring | |
| − | + | 4: New substring (which can be a different length than the old substring) | |
| − | + | 5: String variable to hold the result | |
| − | |||
| − | + | ===[[modify-variable-xstr]]=== | |
| − | + | modify-variable-xstr | |
| − | ===[[ | + | Sets a variable to a localized string. |
| − | |||
| − | |||
| − | |||
| − | + | Takes 3 arguments... | |
| − | + | 1: Name of Variable. | |
| − | + | 2: The default text if no localized version is available. | |
| − | + | 3: The XSTR index. If set to -1 then the default value will be used | |
| − | |||
| − | |||
| − | |||
| − | + | ==Other== | |
| − | + | =Conditionals= | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
===[[when-argument]]=== | ===[[when-argument]]=== | ||
| − | + | When-argument (Conditional operator) | |
| − | + | Performs specified actions when a condition, given a set of arguments, becomes true. | |
| − | |||
| − | + | Takes 3 or more arguments... | |
| − | + | 1: The arguments to evaluate (see any-of, every-of, random-of, etc.). | |
| − | + | 2: Boolean expression that must be true for actions to take place. | |
| − | + | Rest: Actions to take when the boolean expression becomes true. | |
===[[every-time]]=== | ===[[every-time]]=== | ||
| − | + | Every-time (Conditional operator) | |
| − | + | This is a version of "when" that will always evaluate its arguments. It's useful in situations where you need to repeatedly check things that may become true more than once. Since this sexp will execute every time it's evaluated, you may need to use it as an argument to "when" if you want to impose restrictions on how it's called. | |
| − | |||
| − | |||
| − | |||
| − | + | Takes 2 or more arguments... | |
| − | + | 1: Boolean expression that must be true for actions to take place. | |
| − | + | Rest: Actions to take when boolean expression is true. | |
===[[every-time-argument]]=== | ===[[every-time-argument]]=== | ||
| − | + | Every-time-argument (Conditional operator) | |
| − | + | This is a version of "when-argument" that will always evaluate its arguments. It's useful in situations where you need to repeatedly check things that may become true more than once. Since this sexp will execute every time it's evaluated, you may need to use it as an argument to "when" (not "when-argument") if you want to impose restrictions on how it's called. | |
| − | |||
| − | |||
| − | |||
| − | + | Takes 3 or more arguments... | |
| − | + | 1: The arguments to evaluate (see any-of, all-of, random-of, etc.). | |
| − | + | 2: Boolean expression that must be true for actions to take place. | |
| − | + | Rest: Actions to take when the boolean expression becomes true. | |
| − | |||
===[[if-then-else]]=== | ===[[if-then-else]]=== | ||
If-then-else (Conditional operator) | If-then-else (Conditional operator) | ||
| − | Performs one action if a condition is true (like "when"), or another action (or set of actions) if the | + | Performs one action if a condition is true (like "when"), or another action (or set of actions) if the condition is false. Note that this sexp only completes one of its branches once the condition has been determined; it does not come back later and evaluate the other branch if the condition happens to switch truth values. |
| − | |||
| − | |||
Takes 3 or more arguments... | Takes 3 or more arguments... | ||
| Line 1,293: | Line 2,303: | ||
2: Actions to take if that expression becomes true. | 2: Actions to take if that expression becomes true. | ||
Rest: Actions to take if that expression becomes false. | Rest: Actions to take if that expression becomes false. | ||
| − | + | ||
| + | ===[[functional-if-then-else]]=== | ||
| + | Functional If-then-else (Conditional operator) | ||
| + | Returns the first number if the condition is true, and the second number otherwise. | ||
| + | |||
| + | This sexp is very similar to the ?: ternary operator in C and other programming languages. Unfortunately, due to limitations of the sexp system, it is not possible to create an equivalent sexp for string values. | ||
| + | |||
| + | Takes exactly 3 arguments... | ||
| + | 1: Boolean expression to evaluate. | ||
| + | 2: Number to return if the expression is currently true. | ||
| + | 3: Number to return if the expression is not currently true.. | ||
| + | |||
===[[any-of]]=== | ===[[any-of]]=== | ||
| − | + | Any-of (Conditional operator) | |
| − | + | Supplies arguments for the <argument> special data item. Any of the supplied arguments can satisfy the expression(s) in which <argument> is used. | |
| − | |||
| − | + | In practice, this will behave like a standard "for-each" statement, evaluating the action operators for each argument that satisfies the condition. | |
| − | + | ||
| + | Takes 1 or more arguments... | ||
| + | All: Anything that could be used in place of <argument>. | ||
===[[every-of]]=== | ===[[every-of]]=== | ||
| − | + | Every-of (Conditional operator) | |
| − | + | Supplies arguments for the <argument> special data item. Every one of the supplied arguments will be evaluated to satisfy the expression(s) in which <argument> is used. | |
| − | |||
| − | |||
| − | + | Takes 1 or more arguments... | |
| − | + | All: Anything that could be used in place of <argument>. | |
===[[random-of]]=== | ===[[random-of]]=== | ||
| − | + | Random-of (Conditional operator) | |
| − | + | Supplies arguments for the <argument> special data item. A random supplied argument will be selected to satisfy the expression(s) in which <argument> is used. The same argument will be returned by all subsequent calls | |
| − | |||
| − | |||
| − | + | Takes 1 or more arguments... | |
| − | + | All: Anything that could be used in place of <argument>. | |
===[[random-multiple-of]]=== | ===[[random-multiple-of]]=== | ||
| − | + | Random-multiple-of (Conditional operator) | |
| − | + | Supplies arguments for the <argument> special data item. A random supplied argument will be selected to satisfy the expression(s) in which <argument> is used. | |
| − | |||
| − | |||
| − | + | Takes 1 or more arguments... | |
| − | + | All: Anything that could be used in place of <argument>. | |
===[[number-of]]=== | ===[[number-of]]=== | ||
| − | + | Number-of (Conditional operator) | |
| − | + | Supplies arguments for the <argument> special data item. Any [number] of the supplied arguments can satisfy the expression(s) in which <argument> is used. | |
| − | |||
| − | |||
| − | + | Takes 2 or more arguments... | |
| − | + | 1: Number of arguments, as above | |
| − | + | Rest: Anything that could be used in place of <argument>. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
===[[for-counter]]=== | ===[[for-counter]]=== | ||
For-Counter (Conditional operator) | For-Counter (Conditional operator) | ||
| − | Supplies counter values for the <argument> special data item. This sexp will count up from the start | + | Supplies counter values for the <argument> special data item. This sexp will count up from the start value to the stop value, and each value will be provided as an argument to the action operators. The default increment is 1, but if the optional increment parameter is provided, the counter will increment by that number. The stop value will be supplied if appropriate; e.g. counting from 0 to 10 by 2 will supply 0, 2, 4, 6, 8, and 10; but counting by 3 will supply 0, 3, 6, and 9. |
| + | |||
| + | Note that the counter values are all treated as valid arguments, and it is impossible to invalidate a counter argument. If you want to invalidate a counter value, use Any-of and list the values explicitly. | ||
| − | + | This sexp will usually need to be accompanied by the string-to-int sexp, as the counter variables are provided in string format but are most useful in integer format. | |
Takes 2 or 3 arguments... | Takes 2 or 3 arguments... | ||
| Line 1,359: | Line 2,360: | ||
2: Counter stop value | 2: Counter stop value | ||
3: Counter increment (optional) | 3: Counter increment (optional) | ||
| − | |||
===[[invalidate-argument]]=== | ===[[invalidate-argument]]=== | ||
| − | + | Invalidate-argument (Conditional operator) | |
| − | + | Removes an argument from future consideration as a <argument> special data item. | |
| − | + | Takes 1 or more arguments... | |
| − | + | All: The argument to remove from the preceding argument list. | |
| − | + | ===[[invalidate-all-arguments]]=== | |
| − | + | Invalidate-all-arguments (Conditional operator) | |
| − | ==Ai goals== | + | Removes all argument from future consideration as <argument> special data items. |
| + | Takes no arguments. | ||
| + | ===[[validate-argument]]=== | ||
| + | Validate-argument (Conditional operator) | ||
| + | Restores an argument for future consideration as a <argument> special data item. | ||
| + | If the argument hasn't been previously invalidated, it will do nothing. | ||
| + | Takes 1 or more arguments... | ||
| + | All: The argument to restore to the preceding argument list. | ||
| + | ===[[validate-all-arguments]]=== | ||
| + | Validate-all-arguments (Conditional operator) | ||
| + | Restores all arguments for future consideration as <argument> special data items. | ||
| + | If the argument hasn't been previously invalidated, it will do nothing. | ||
| + | Takes no arguments. | ||
| + | ===[[do-for-valid-arguments]]=== | ||
| + | Do-for-valid-arguments (Conditional operator) | ||
| + | Performs specified actions once for each valid <argument> in the parent conditional. | ||
| + | Must not be used for any SEXP that actually contains <argument> as these are already being executed | ||
| + | multiple times without using Do-for-valid-arguments. Any use of <argument> and will | ||
| + | prevent execution of the entire SEXP unless it is nested inside another when(or every-time)-argument SEXP. | ||
| + | |||
| + | Takes 1 or more arguments... | ||
| + | All: Actions to take. | ||
| + | ===[[num-valid-arguments]]=== | ||
| + | num-valid-arguments (Conditional operator) | ||
| + | Returns the number of valid arguments in the argument list. | ||
| + | |||
| + | Takes no arguments... | ||
| + | |||
| + | =Ai goals= | ||
| + | ===[[ai-chase-ship-class]]=== | ||
| + | Ai-chase ship class (Ship goal) | ||
| + | Causes the specified ship to chase and attack the specified target ship class. | ||
| + | |||
| + | Takes 2 or 3 arguments... | ||
| + | 1: Name of ship class to chase. | ||
| + | 2: Goal priority (number between 0 and 200. Player orders have a priority of 90-100). | ||
| + | 3 (optional): Whether to attack the target even if it is on the same team; defaults to false. | ||
===[[ai-ignore-new]]=== | ===[[ai-ignore-new]]=== | ||
| − | + | Ai-ignore-new (Ship goal) | |
| − | + | Tells the specified ship to ignore the given ship and not consider it as a valid target to attack. | |
| − | + | ||
| + | Takes 2 arguments... | ||
| + | 1: Name of ship to ignore. | ||
| + | 2: Goal priority (number between 0 and 89). | ||
| + | ===[[ai-play-dead-persistent]]=== | ||
| + | Ai-play-dead-persistent (Ship goal) | ||
| + | Causes the specified ship to pretend that it is dead and not do anything. This goal behaves exactly like ai-play-dead, with the important difference that the ship will not immediately come back to life whenever it is given an order or a new goal of any priority. The only ways this goal can be removed are via remove-goal, clear-goals, or a new goal of a *higher* priority. | ||
| + | |||
| + | Takes 1 argument... | ||
| + | 1: Goal priority (number between 0 and 89). | ||
| + | ===[[ai-form-on-wing]]=== | ||
| + | Ai-form-on-wing (Ship Goal) | ||
| + | Causes the ship to form on the specified ship's wing. This works analogous to the player order, and will cause all other goals specified for the ship to be purged. | ||
| + | |||
| + | Takes 1 argument... | ||
| + | 1: Ship to form on. | ||
| + | =Event/Goals= | ||
| + | ===[[is-event-true-msecs-delay]]=== | ||
| + | Mission Event True (Boolean operator) | ||
| + | Returns true N milliseconds after the specified event in the this mission is true (or succeeded). It returns false otherwise. | ||
| + | |||
| + | Returns a boolean value. Takes 2 required arguments and 1 optional argument... | ||
| + | 1: Name of the event in the mission. | ||
| + | 2: Number of milliseconds to delay before returning true. | ||
| + | 3: (Optional) Defaults to False. When set to false, directives will only appear as soon as the specified event is true. | ||
| + | When set to true, the event only affects whether the directive succeeds/fails, and has no effect on when it appears | ||
| + | ===[[is-event-false-msecs-delay]]=== | ||
| + | Mission Event False (Boolean operator) | ||
| + | Returns true N milliseconds after the specified event in the this mission is false (or failed). It returns false otherwise. | ||
| + | |||
| + | Returns a boolean value. Takes 2 required arguments and 1 optional argument... | ||
| + | 1: Name of the event in the mission. | ||
| + | 2: Number of milliseconds to delay before returning true. | ||
| + | 3: (Optional) Defaults to False. When set to false, directives will only appear as soon as the specified event is true. | ||
| + | When set to true, the event only affects whether the directive succeeds/fails, and has no effect on when it appears | ||
| + | =Training= | ||
| + | ===[[query-orders]]=== | ||
| + | Query-Orders (Boolean training operator) | ||
| + | Becomes true when the player had given the specified ship or wing the specified order. | ||
| + | |||
| + | Returns a boolean value. Takes 2 or more arguments... | ||
| + | 1: Name of ship or wing to check if given order to. | ||
| + | 2: Name of order to check if player has given. | ||
| + | 3: Maximum length of time since order was given. Use 0 for any time in the mission. | ||
| + | 4: Name of the target of the order (optional). | ||
| + | 5: Name of player ship giving the order(optional). | ||
| + | 6: Name of the subsystem for Destroy Subsystem orders.(optional) | ||
| + | ===[[reset-orders]]=== | ||
| + | Reset-Orders (Action training operator) | ||
| + | Resets the list of orders the player has given. | ||
| + | Takes no arguments. | ||
| + | ===[[primaries-depleted]]=== | ||
| + | primaries-depleted | ||
| + | Returns true if ship is out of primary weapons | ||
| + | 1: Ship name | ||
| + | |||
| + | ===[[ignore-key]]=== | ||
| + | ignore-key | ||
| + | Causes the game to ignore (or stop ignoring) a certain key. | ||
| + | Takes 2 or more arguments... | ||
| + | 1: Number of times to ignore this key (-1 = forever, 0 = stop ignoring). | ||
| + | Rest: Which key(s) to ignore. | ||
| + | |||
| + | ===[[node-targeted]]=== | ||
| + | Node-Targeted (Boolean training operator) | ||
| + | Is true as long as the player has the specified jump node targeted, or has been targeted for the specified amount of time. | ||
| − | + | Returns a boolean value. Takes 1 to 2 arguments (first required, rest optional): | |
| − | + | 1: Name of Jump Node to check if targeted by player. | |
| − | + | 2: Length of time target should have been kept for (optional). | |
| − | + | ===[[missile-locked]]=== | |
| − | + | Missile-locked (Boolean training operator) | |
| − | + | Is true as long as the player has had a missile lock for the specified amount of time. Optional arguments require lock to be maintained on a specified ship (or ship's subsystem). | |
| − | ===[[ | + | |
| − | + | Returns a boolean value. Takes 1 to 3 arguments (first required, rest optional): | |
| − | + | 1: Length of time missile lock should have been kept for. | |
| − | + | 2: Name of ship to check if locked onto by player (optional). | |
| − | + | 3: Name of subsystem on ship to check if locked onto (optional). | |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
[[Category:Lists]] | [[Category:Lists]] | ||
[[Category:FRED]] | [[Category:FRED]] | ||
[[Category:SCP SEXPs|*]] | [[Category:SCP SEXPs|*]] | ||
Revision as of 18:14, 18 June 2020
This page is a reference of SEXPs that are only available in the SCP version of FRED. This also includes any retail SEXPs that have been modified from their original behaviour. To see the list of SEXPs that are available in retail FRED, go to the Retail SEXPs page. For tips and examples for how to properly use a SEXP when building missions, as well as warnings about potential pitfalls, follow the link to the detail page for the SEXP you are interested in.
Contents
- 1 Objectives
- 2 Time
- 3 Logical
- 4 Arithmetic
- 5 Status
- 5.1 Mission
- 5.2 Player
- 5.3 Multiplayer
- 5.4 Ship Status
- 5.5 Weapons, Shields, and Engines
- 5.6 Cargo
- 5.7 Damage
- 5.8 Distance and Coordinates
- 5.8.1 distance-to-center
- 5.8.2 distance-to-bbox
- 5.8.3 distance-center-to-subsystem
- 5.8.4 distance-bbox-to-subsystem
- 5.8.5 distance-to-nav
- 5.8.6 num-within-box
- 5.8.7 is-in-box
- 5.8.8 get-object-x
- 5.8.9 get-object-y
- 5.8.10 get-object-z
- 5.8.11 get-object-pitch
- 5.8.12 get-object-bank
- 5.8.13 get-object-heading
- 5.8.14 get-object-speed-x
- 5.8.15 get-object-speed-y
- 5.8.16 get-object-speed-z
- 5.9 Variables
- 5.10 Other
- 6 Change
- 6.1 Messages and Personas
- 6.2 AI Control
- 6.3 Ship Status
- 6.3.1 turret-protect-ship
- 6.3.2 turret-unprotect-ship
- 6.3.3 ship-stealthy
- 6.3.4 ship-unstealthy
- 6.3.5 friendly-stealth-invisible
- 6.3.6 friendly-stealth-visible
- 6.3.7 primitive-sensors-set-range
- 6.3.8 ship-targetable-as-bomb
- 6.3.9 ship-untargetable-as-bomb
- 6.3.10 kamikaze
- 6.3.11 change-iff-color
- 6.3.12 ship-change-alt-name
- 6.3.13 ship-change-callsign
- 6.3.14 ship-tag
- 6.3.15 ship-untag
- 6.3.16 set-arrival-info
- 6.3.17 set-departure-info
- 6.3.18 alter-ship-flag
- 6.4 Weapons, Shields, and Engines
- 6.4.1 set-weapon-energy
- 6.4.2 set-shield-energy
- 6.4.3 set-player-throttle-speed
- 6.4.4 set-afterburner-energy
- 6.4.5 set-subspace-drive
- 6.4.6 set-primary-weapon
- 6.4.7 set-secondary-weapon
- 6.4.8 set-primary-ammo
- 6.4.9 set-secondary-ammo
- 6.4.10 set-num-countermeasures
- 6.4.11 lock-primary-weapon
- 6.4.12 unlock-primary-weapon
- 6.4.13 lock-secondary-weapon
- 6.4.14 unlock-secondary-weapon
- 6.4.15 lock-afterburner
- 6.4.16 unlock-afterburner
- 6.4.17 shields-on
- 6.4.18 shields-off
- 6.4.19 force-glide
- 6.4.20 disable-ets
- 6.4.21 enable-ets
- 6.4.22 set-ets-values
- 6.5 Subsystems and Health
- 6.5.1 ship-guardian-threshold
- 6.5.2 ship-subsys-guardian-threshold
- 6.5.3 destroy-instantly
- 6.5.4 destroy-subsys-instantly
- 6.5.5 ship-copy-damage
- 6.5.6 lock-rotating-subsystem
- 6.5.7 free-rotating-subsystem
- 6.5.8 reverse-rotating-subsystem
- 6.5.9 rotating-subsys-set-turn-time
- 6.5.10 trigger-submodel-animation
- 6.5.11 change-subsystem-name
- 6.5.12 ship-subsys-targetable
- 6.5.13 ship-subsys-untargetable
- 6.5.14 ship-subsys-no-replace
- 6.5.15 ship-subsys-no-live-debris
- 6.5.16 ship-subsys-vanish
- 6.5.17 ship-subsys-ignore_if_dead
- 6.6 Cargo
- 6.7 Armor and Damage Types
- 6.8 Beams and Turrets
- 6.8.1 fire-beam-at-coordinates
- 6.8.2 beam-create
- 6.8.3 turret-tagged-specific
- 6.8.4 turret-tagged-clear-specific
- 6.8.5 turret-change-weapon
- 6.8.6 turret-set-direction-preference
- 6.8.7 turret-set-rate-of-fire
- 6.8.8 turret-set-optimum-range
- 6.8.9 turret-set-target-priorities
- 6.8.10 turret-set-target-order
- 6.8.11 ship-turret-target-order
- 6.8.12 turret-subsys-target-disable
- 6.8.13 turret-subsys-target-enable
- 6.8.14 turret-set-primary-ammo
- 6.8.15 turret-set-secondary-ammo
- 6.9 Models and Textures
- 6.9.1 change-ship-class
- 6.9.2 deactivate-glow-maps
- 6.9.3 activate-glow-maps
- 6.9.4 deactivate-glow-points
- 6.9.5 activate-glow-points
- 6.9.6 deactivate-glow-point-bank
- 6.9.7 activate-glow-point-bank
- 6.9.8 set-thrusters-status
- 6.9.9 don't-collide-invisible
- 6.9.10 collide-invisible
- 6.9.11 add-to-collision-group
- 6.9.12 remove-from-collision-group
- 6.9.13 get-collision-group
- 6.9.14 change-team-color
- 6.10 Coordinate Manipulation
- 6.10.1 set-object-position
- 6.10.2 set-object-orientation
- 6.10.3 set-object-facing
- 6.10.4 set-object-facing-object
- 6.10.5 set-object-speed-x
- 6.10.6 set-object-speed-y
- 6.10.7 set-object-speed-z
- 6.10.8 ship-maneuver
- 6.10.9 ship-rot-maneuver
- 6.10.10 ship-lat-maneuver
- 6.10.11 set-immobile
- 6.10.12 set-mobile
- 6.11 Mission and Campaign
- 6.11.1 end-mission
- 6.11.2 force-jump
- 6.11.3 set-debriefing-toggled
- 6.11.4 allow-treason
- 6.11.5 grant-promotion
- 6.11.6 grant-medal
- 6.11.7 tech-add-ships
- 6.11.8 tech-add-weapons
- 6.11.9 tech-add-intel
- 6.11.10 tech-remove-intel
- 6.11.11 tech-add-intel-xstr
- 6.11.12 tech-remove-intel-xstr
- 6.11.13 tech-reset-to-default
- 6.11.14 change-player-score
- 6.11.15 change-team-score
- 6.11.16 set-respawns
- 6.11.17 add-remove-hotkey
- 6.12 Music and Sound
- 6.13 HUD
- 6.13.1 hud-disable
- 6.13.2 hud-disable-except-messages
- 6.13.3 hud-set-custom-gauge-active
- 6.13.4 hud-set-retail-gauge-active
- 6.13.5 hud-set-text
- 6.13.6 hud-set-text-num
- 6.13.7 hud-set-message
- 6.13.8 hud-set-directive
- 6.13.9 hud-set-frame
- 6.13.10 hud-set-coords
- 6.13.11 hud-set-color
- 6.13.12 hud-display-gauge
- 6.13.13 hud-gauge-set-active
- 6.13.14 hud-activate-gauge-type
- 6.13.15 hud-clear-messages
- 6.13.16 hud-set-max-targeting-range
- 6.14 Nav Points
- 6.14.1 add-nav-waypoint
- 6.14.2 add-nav-ship
- 6.14.3 del-nav
- 6.14.4 hide-nav
- 6.14.5 restrict-nav
- 6.14.6 unhide-nav
- 6.14.7 unrestrict-nav
- 6.14.8 set-nav-visited
- 6.14.9 unset-nav-visited
- 6.14.10 set-nav-carry
- 6.14.11 unset-nav-carry
- 6.14.12 set-nav-needslink
- 6.14.13 unset-nav-needslink
- 6.14.14 use-nav-cinematics
- 6.14.15 use-autopilot
- 6.14.16 select-nav
- 6.14.17 unselect-nav
- 6.15 Cutscenes
- 6.15.1 set-cutscene-bars
- 6.15.2 unset-cutscene-bars
- 6.15.3 fade-in
- 6.15.4 fade-out
- 6.15.5 set-camera
- 6.15.6 set-camera-position
- 6.15.7 set-camera-facing
- 6.15.8 set-camera-facing-object
- 6.15.9 set-camera-rotation
- 6.15.10 set-camera-host
- 6.15.11 set-camera-target
- 6.15.12 set-camera-fov
- 6.15.13 set-fov
- 6.15.14 reset-fov
- 6.15.15 reset-camera
- 6.15.16 show-subtitle
- 6.15.17 show-subtitle-text
- 6.15.18 show-subtitle-image
- 6.15.19 clear-subtitles
- 6.15.20 lock-perspective
- 6.15.21 set-camera-shudder
- 6.15.22 supernova-stop
- 6.15.23 set-motion-debris-override
- 6.16 Backgrounds and Nebulae
- 6.16.1 mission-set-nebula
- 6.16.2 mission-set-subspace
- 6.16.3 add-background-bitmap
- 6.16.4 remove-background-bitmap
- 6.16.5 add-sun-bitmap
- 6.16.6 remove-sun-bitmap
- 6.16.7 nebula-change-storm
- 6.16.8 nebula-toggle-poof
- 6.16.9 nebula-change-pattern
- 6.16.10 set-skybox-model
- 6.16.11 set-skybox-orientation
- 6.16.12 set-ambient-light
- 6.17 Jump Nodes
- 6.18 Special Effects
- 6.18.1 set-post-effect
- 6.18.2 reset-post-effects
- 6.18.3 ship-effect
- 6.18.4 ship-create
- 6.18.5 weapon-create
- 6.18.6 ship-vaporize
- 6.18.7 ship-no-vaporize
- 6.18.8 set-explosion-option
- 6.18.9 explosion-effect
- 6.18.10 warp-effect
- 6.18.11 remove-weapons
- 6.18.12 set-time-compression
- 6.18.13 reset-time-compression
- 6.18.14 call-ssm-strike
- 6.19 Variables
- 6.20 Other
- 7 Conditionals
- 7.1 when-argument
- 7.2 every-time
- 7.3 every-time-argument
- 7.4 if-then-else
- 7.5 functional-if-then-else
- 7.6 any-of
- 7.7 every-of
- 7.8 random-of
- 7.9 random-multiple-of
- 7.10 number-of
- 7.11 for-counter
- 7.12 invalidate-argument
- 7.13 invalidate-all-arguments
- 7.14 validate-argument
- 7.15 validate-all-arguments
- 7.16 do-for-valid-arguments
- 7.17 num-valid-arguments
- 8 Ai goals
- 9 Event/Goals
- 10 Training
Objectives
was-destroyed-by-delay
Was destroyed by delay (Boolean operator) Becomes true <delay> seconds after all specified ships have been destroyed by the specified first ship. Returns a boolean value. Takes 3 or more arguments... 1: Time delay in seconds (see above). 2: Ship that should have destroyed the other ships (see below). Rest: Name of ships to check status of.
is-disarmed-delay
Is disarmed delay (Boolean operator) Becomes true <delay> seconds after the specified ship(s) are disarmed. A ship is disarmed when all of its turret subsystems are destroyed. All ships must be disarmed for this function to return true. Returns a boolean value. Takes 2 or more arguments... 1: Time delay is seconds (see above). Rest: Names of ships to check disarmed status of.
is-nav-visited Returns true when the player has visited the given navpoint (Has closed to within 1000m of it). Takes 1 argument... 1: The name of the navpoint
percent-ships-disabled
percent-ships-disabled Boolean function which returns true if the percentage of ships in the listed ships which have been disabled is greater or equal to the given percentage. Takes 2 or more arguments... 1: Percentge of disabled ships at which this function will return true. 2+: List of ships whose disabled status should be determined.
percent-ships-disarmed
percent-ships-disarmed Boolean function which returns true if the percentage of ships in the listed ships which have been disarmed is greater or equal to the given percentage. Takes 2 or more arguments... 1: Percentge of disarmed ships at which this function will return true. 2+: List of ships whose disarmed status should be determined.
percent-ships-arrived
percent-ships-arrived Boolean function which returns true if the percentage of ships in the listed ships and wings which have arrived is greater or equal to the given percentage. For wings, all ships of all waves are used for calculation for the total possible ships to arrive. Takes 2 or more arguments... 1: Percentge of arriving ships at which this function will return true. 2+: List of ships/wings whose arrival status should be determined.
Time
mission-time-msecs
Mission time, in milliseconds (Time operator) Returns the current time into the mission, in milliseconds. Useful for more fine-grained timing than possible with normal second-based sexps. (Tip: when an event occurs, assign the result of mission-time-msecs to a variable. Then, in another event, wait until mission-time-msecs is greater than the value of that variable plus some delay amount. This second event should be chained or coupled with additional conditions so that it doesn't accidentally fire on an uninitialized variable!) Returns a numeric value. Takes no arguments.
Logical
xor
Xor (Boolean operator) Xor is true if exactly one of its arguments is true. Returns a boolean value. Takes 2 or more boolean arguments.
!=
Not Equal To (Boolean operator) Is true if the first argument is not equal to any of the subsequent arguments. Returns a boolean value. Takes 2 or more numeric arguments.
[[<=]]
Less Than Or Equal To (Boolean operator) True if the first argument is less than or equal to the subsequent argument(s). Returns a boolean value. Takes 2 numeric arguments.
string-equals
String Equals (Boolean operator) Is true if all of its arguments are equal. Returns a boolean value. Takes 2 or more string arguments.
string-greater-than
String Greater Than (Boolean operator) True if the first argument is greater than the second argument. Returns a boolean value. Takes 2 string arguments.
string-less-than
String Less Than (Boolean operator) True if the first argument is less than the second argument. Returns a boolean value. Takes 2 string arguments.
perform-actions
perform-actions This sexp allows actions to be performed as part of a conditional test. It is most useful for assigning variables or performing some sort of pre-test action within the conditional part of "when", etc. It works well as the first branch of an "and" sexp, provided it returns true so as to not affect the return value of the "and". Returns a boolean value. Takes 2 or more arguments. 1: A boolean value to return after all successive actions have been performed. Rest: Actions to perform, which would normally appear in a "when" sexp.
Arithmetic
rand-multiple
Rand-multiple (Arithmetic operator) Gets a random number. This number can and will change between successive calls to this sexp. Returns a number. Takes 2 or 3 numeric arguments... 1: Low range of random number. 2: High range of random number. 3: (optional) A seed to use when generating numbers. (Setting this to 0 is the same as having no seed at all)
abs
Absolute value (Arithmetic operator) Returns the absolute value of a number. Takes 1 numeric argument.
avg
Average value (Arithmetic operator) Returns the average (rounded to the nearest integer) of a set of numbers. Takes 1 or more numeric arguments.
signum
Signum (Arithmetic operator) Returns the sign of a number: -1 if it is negative, 0 if it is 0, and 1 if it is positive. Takes one argument.
is-nan
Is-NaN (Arithmetic operator) Returns true if the argument is NaN (not-a-number). This can happen e.g. when checking statistics for ships that have departed. Takes one argument.
nan-to-number
NaN-to-Number (Arithmetic operator) Used to safely filter NaN values from arithmetic operations, which would otherwise pass NaN up the sexp tree. If the argument is a number, it is returned. If the argument is NaN, a zero is returned. Takes one argument.
set-bit
set-bit Turns on (sets to 1) a certain bit in the provided number, returning the result. This allows numbers to store up to 32 boolean flags, from 2^0 to 2^31. Takes 2 numeric arguments... 1: The number whose bit should be set 2: The index of the bit to set. Valid indexes are between 0 and 31, inclusive.
unset-bit
unset-bit Turns off (sets to 0) a certain bit in the provided number, returning the result. This allows numbers to store up to 32 boolean flags, from 2^0 to 2^31. Takes 2 numeric arguments... 1: The number whose bit should be unset 2: The index of the bit to unset. Valid indexes are between 0 and 31, inclusive.
is-bit-set
is-bit-set Returns true if the specified bit is set (equal to 1) in the provided number. Takes 2 numeric arguments... 1: The number whose bit should be tested 2: The index of the bit to test. Valid indexes are between 0 and 31, inclusive.
bitwise-and
bitwise-and Performs the bitwise AND operator on its arguments. This is the same as if the logical AND operator was performed on each successive bit. Takes 2 or more numeric arguments.
bitwise-or
bitwise-or Performs the bitwise OR operator on its arguments. This is the same as if the logical OR operator was performed on each successive bit. Takes 2 or more numeric arguments.
bitwise-not
bitwise-not Performs the bitwise NOT operator on its argument. This is the same as if the logical NOT operator was performed on each successive bit. Note that the operation is performed as if on an unsigned integer whose maximum value is INT_MAX. In other words, there is no need to worry about the sign bit. Takes only 1 argument.
bitwise-xor
bitwise-xor Performs the bitwise XOR operator on its arguments. This is the same as if the logical XOR operator was performed on each successive bit. Takes 2 or more numeric arguments.
Status
Mission
num-ships-in-battle
num-ships-in-battle Returns the number of ships in battle or the number of ships in battle out of a list of teams, wings, and ships. Takes 1 or more arguments... (all): Teams, Wings, and Ships to query (optional)
num-ships-in-wing
num-ships-in-wing Returns the number of ships in battle which belong to a given wing. Takes 1 or more arguments... (all): Name of wing(s) to check
directive-value
directive-value Causes a value to appear in the directive count Always returns true. Takes 1 or more arguments... 1: Value 2: (Optional) Ignore the directive count set by any earlier SEXPs in the event. If set to false it will add instead
get-hotkey
get-hotkey Returns the hotkey integer of the ship or wing. Return values range from -1 to 7. Return of -1 is no hotkey, return of 0 is F5, return of 1 is F6, ..., return of 7 is F12. Takes 1 argument. 1: Ship or wing to get hotkey.
Player
was-promotion-granted
Was promotion granted (Boolean operator) Returns true if a promotion was granted via the 'Grant promotion' operator in the mission. Returns a boolean value. Takes no arguments.
was-medal-granted
Was medal granted (Boolean operator) Returns true if a medal was granted via via the 'Grant medal' operator in the mission. If you provide the optional argument to this operator, then true is only returned if the specified medal was granted. Returns a boolean value. Takes 0 or 1 arguments... 1: Name of medal to specifically check for (optional).
num_assists
num-assists Returns the # of assists a player has. The ship specified in the first field should be the ship the player is in. So, for single player, this would be Alpha 1. For multiplayer, it can be any ship with a player in it. If, at any time there is no player in a given ship, this sexpression will return 0
ship_score
ship-score Returns the score a player has. The ship specified in the first field should be the ship the player is in. So, for single player, this would be Alpha 1. For multiplayer, it can be any ship with a player in it. If, at any time there is no player in a given ship, this sexpression will return 0
Multiplayer
ship-deaths
ship-deaths Returns the # times a ship that is a player start has died. The ship specified in the first field should be the ship that could have a player in.it Only really useful for multiplayer.
respawns-left
respawns-left Returns the # respawns a player (or AI that could have been a player) has remaining. The ship specified in the first field should be the player start. Only really useful for multiplayer.
is-player
is-player Returns true if all the ships specified are currently under control of a player. 1 (SinglePlayer) When true ships under AI control return false even if they are the player ship (Multiplayer) When true ships that are respawning return true if the player is still connected Rest List of ships to test
Ship Status
is-in-mission
Is-In-Mission (Status operator) Checks whether a given ship is presently in the mission. This sexp doesn't check the arrival list or exited status; it only tests to see if the ship is active. This means that internally the sexp only returns SEXP_TRUE or SEXP_FALSE and does not use any of the special shortcut values. This is useful for ships created with ship-create, as those ships will not have used the conventional ship arrival list. Takes 1 or more string arguments, which are checked against the ship list. (If more than 1 argument is specified, the sexp will only evaluate to true if all ships are in the mission simultaneously.)
is-docked
Is-Docked (Status operator) Checks whether the specified ships are currently docked. This sexp is different from has-docked-delay, which will return true if the ships have docked at any point in the past. The has-docked-delay sexp checks the mission log, whereas the is-docked sexp examines the actual dockpoints. Takes 1 or more arguments. (If more than 2 arguments are specified, the sexp will only evaluate to true if all ships are docked simultaneously.) If a single argument is supplied, the sexp will evaluate to true if anything is docked to the host ship. 1: The host ship. Rest: Ship to check as docked to the host ship.
is-ship-stealthy
is-ship-stealthy Check whether ship is currently stealthy. True if stealth flag set, false otherwise. Takes 1 argument... 1: Name of ship to check
is-friendly-stealth-visible
is-friendly-stealth-visible Check whether ship will be visible to radar as a stealth friendly. Takes 1 argument... 1: Name of ship to check
is-ai-class
Is AI Class (Boolean operator)
True if ship or ship subsystem(s) is/are all of the specified AI class.
Returns a boolean value. Takes 2 or more arguments...
1: AI class ("None", "Coward", "Lieutenant", etc.)
2: Name of ship to check.
Rest: Name of ship subsystem(s) to check (optional)
is-ship-type
Is Ship Type (Boolean operator)
True if ship or ships is/are all of the specified ship type.
Returns a boolean value. Takes 2 or more arguments...
1: Ship type ("fighter", "bomber", etc.)
2: Name of ship to check.
is-ship-class
Is Ship Class (Boolean operator) True if ship or ships is/are all of the specified ship class. Returns a boolean value. Takes 2 or more arguments... 1: Ship class 2: Name of ship to check.
is-facing
Is Facing (Boolean training operator) Is true as long as the second object is within the first ship's specified forward cone. A forward cone is defined as any point that the angle between the vector of the ship and point, and the forward facing vector is within the given angle. If the distance between the two is greater than the fourthparameter, this will return false. Returns a boolean value. Takes 3 or 4 argument... 1: Ship to check from. 2: Object to check is within forward cone. 3: Angle in degrees of the forward cone. 4: Range in meters (optional).
are-ship-flags-set
Are ship flags set (Boolean operator) Returns true if all of the specified flags have been set for this particular ship. Takes 2 or more arguments... 1: Name of the ship. Rest: Ship, object or ai flags which might be set for this ship..
get-throttle-speed
Get-Throttle-Speed (Training operator) Returns the current throttle speed that the ship has been set to. Reverse speeds are returned as a negative value. Takes 1 argument... 1: Name of the player ship to check the throttle value for.
current-speed
current-speed Returns the speed of the given object. Takes 1 argument... 1: Name of the object
is-nav-linked
Determines if a ship is linked for autopilot ("set-nav-carry" or "set-nav-needslink" + linked)Takes 1 argument...
1: Ship to check
Weapons, Shields, and Engines
has-primary-weapon
has-primary-weapon Returns true if the primary weapon bank specified has any of the weapons listed. Takes 3 or more arguments... 1: Ship name 2: Weapon bank number (This is a zero-based index. The first bank is numbered 0.) Rest: Weapon name
has-secondary-weapon
has-secondary-weapon Returns true if the secondary weapon bank specified has any of the weapons listed. Takes 3 or more arguments... 1: Ship name 2: Weapon bank number (This is a zero-based index. The first bank is numbered 0.) Rest: Weapon name
primary-fired-since
primary-fired-since Returns true if the primary weapon bank specified has been fired within the supplied window of time. Takes 3 arguments... 1: Ship name 2: Weapon bank number (This is a zero-based index. The first bank is numbered 0.) 3: Time period to check if the weapon was fired (in milliseconds)
secondary-fired-since
secondary-fired-since Returns true if the secondary weapon bank specified has been fired within the supplied window of time. Takes 3 arguments... 1: Ship name 2: Weapon bank number (This is a zero-based index. The first bank is numbered 0.) 3: Time period to check if the weapon was fired (in milliseconds)
primary-ammo-pct
primary-ammo-pct Returns the percentage of ammo remaining in the specified ballistic primary bank (0 to 100). Non-ballistic primary banks return as 100%. 1: Ship name 2: Bank to check (from 0 to N-1, where N is the number of primary banks in the ship; N or higher will return the cumulative average for all banks)
get-primary-ammo
get-primary-ammo Returns the amount of ammo remaining in the specified bank 1: Ship name 2: Bank to check (from 0 to N-1, where N is the number of primary banks in the ship; N or higher will return the cumulative total for all banks)
get-secondary-ammo
get-secondary-ammo Returns the amount of ammo remaining in the specified bank 1: Ship name 2: Bank to check (from 0 to N-1, where N is the number of secondary banks in the ship; N or higher will return the cumulative total for all banks)
get-num-countermeasures
get-num-countermeasures Returns the amount of countermeasures remaining 1: Ship name
weapon-energy-pct
Weapon energy left Returns a ship's current weapon energy as a percentage. 1: Ship name
afterburner-energy-pct
Afterburner left Returns a ship's current engine energy as a percentage. 1: Ship name
is-in-turret-fov
is-in-turret-fov Checks whether the given craft is within the field of view of a turret, and optionally within a specified range. Takes 3 to 4 arguments... 1: Ship being targeted 2: Ship which carries a turret 3: Turret to check 4: Range in meters (optional)
Cargo
Damage
hits-left-subsystem-generic
hits-left-subsystem-generic (status operator) Returns the current level of integrity of a generic subsystem type, as a percentage. A "generic subsystem type" is a subsystem *category*, (for example, Engines), that includes one or more *individual* subsystems (for example, engine01, engine02, and engine03) on a ship. This is the way FreeSpace tests certain subsystem thresholds internally; for example, if the integrity of all engine subsystems (that is, the combined strength of all engines divided by the maximum total strength of all engines) is less than 30%, the player cannot warp out. Returns a numeric value. Takes 2 arguments... 1: Name of ship to check 2: Name of subsystem type to check
hits-left-subsystem-specific
hits-left-subsystem-specific (status operator) Returns the current level of integrity of a specific subsystem, as a percentage. (If you were looking for the old hits-left-subsystem operator, this is almost certainly the operator you want. The hits-left-subsystem operator suffers from a serious design flaw that causes it to behave like hits-left-subsystem-generic. As such it has been deprecated and will not appear in the operator list; it can only be used if you type it in manually. Old missions using hits-left-subsystem will still work, but mission designers are strongly encouraged to use the new operators instead.) Returns a numeric value. Takes 2 arguments... 1: Name of ship to check 2: Name of subsystem to check
sim-hits-left
Simulated Hits left (Status operator) Returns the current level of the specified ship's simulated hull as a percentage. Returns a numeric value. Takes 1 argument... 1: Name of ship to check.
get-damage-caused
Get damage caused (Status operator) Returns the amount of damage one or more ships have done to a ship. Takes 2 or more arguments... 1: Ship that has been damaged. 2: Name of ships that may have damaged it.
Distance and Coordinates
distance-to-center
Distance-To-Center (Status operator) Returns the distance between the centers of two objects. These can be ships, wings, or waypoints. When a wing or team is given (for either argument), the result will be the closest distance. Returns a numeric value. Takes 2 arguments... 1: The name of one of the objects. 2: The name of the other object.
distance-to-bbox
Distance-To-BBox (Status operator) Returns the distance between the bounding boxes of two objects. These can be ships, wings, or waypoints. When a wing or team is given (for either argument), the result will be the closest distance. Returns a numeric value. Takes 2 arguments... 1: The name of one of the objects. 2: The name of the other object.
distance-center-to-subsystem
Center distance from ship subsystem (Status operator) Returns the distance between the center of an object and the center of a ship subsystem. The object can be a ship, wing, or waypoint. When a wing or team is given, the result will be the closest distance. Returns a numeric value. Takes 3 arguments... 1: The name of the object. 2: The name of the ship which houses the subsystem. 3: The name of the subsystem.
distance-bbox-to-subsystem
BBox distance from ship subsystem (Status operator) Returns the distance between the bounding box of an object and the center of a ship subsystem. The object can be a ship, wing, or waypoint. When a wing or team is given, the result will be the closest distance. Returns a numeric value. Takes 3 arguments... 1: The name of the object. 2: The name of the ship which houses the subsystem. 3: The name of the subsystem.
distance-to-nav Returns the distance from the center of the player ship to a nav point. Takes 1 argument... 1: The name of the navpoint
num-within-box
Number of specified objects in the box specified 1: Box center (X) 2: Box center (Y) 3: Box center (Z) 4: Box half-width (distance +/- away from center X) 5: Box half-height (distance +/- away from center Y) 6: Box half-depth (distance +/- away from center Z) Rest: Ships or wings to check
is-in-box
Whether an object is in the box specified. If a second ship is specified, the box is relative to that ship's reference frame. 1: Ships, wings, or points to check 2: Min X 3: Max X 4: Min Y 5: Max Y 6: Min Z 7: Max Z 8: Ship to use as reference frame (optional).
get-object-x
get-object-x Returns the absolute X coordinate of a set of coordinates relative to a particular object (or object's subsystem). The input coordinates are the coordinates relative to the object's position and orientation. If no input coordinates are specified, the coordinate returned is the coordinate of the object (or object's subsystem) itself. Takes 1 to 5 arguments... 1: The name of a ship, wing, or waypoint. 2: A ship subsystem (or "<none>" if the first argument is not a ship - optional). 3: The relative X coordinate (optional). 4: The relative Y coordinate (optional). 5: The relative Z coordinate (optional).
get-object-y
get-object-y Returns the absolute Y coordinate of a set of coordinates relative to a particular object (or object's subsystem). The input coordinates are the coordinates relative to the object's position and orientation. If no input coordinates are specified, the coordinate returned is the coordinate of the object (or object's subsystem) itself. Takes 1 to 5 arguments... 1: The name of a ship, wing, or waypoint. 2: A ship subsystem (or "<none>" if the first argument is not a ship - optional). 3: The relative X coordinate (optional). 4: The relative Y coordinate (optional). 5: The relative Z coordinate (optional).
get-object-z
get-object-z Returns the absolute Z coordinate of a set of coordinates relative to a particular object (or object's subsystem). The input coordinates are the coordinates relative to the object's position and orientation. If no input coordinates are specified, the coordinate returned is the coordinate of the object (or object's subsystem) itself. Takes 1 to 5 arguments... 1: The name of a ship, wing, or waypoint. 2: A ship subsystem (or "<none>" if the first argument is not a ship - optional). 3: The relative X coordinate (optional). 4: The relative Y coordinate (optional). 5: The relative Z coordinate (optional).
get-object-pitch
get-object-pitch Returns the pitch angle, in degrees, of a particular object. The returned value will be between 0 and 360. Takes 1 argument... 1: The name of a ship or wing.
get-object-bank
get-object-bank Returns the bank angle, in degrees, of a particular object. The returned value will be between 0 and 360. Takes 1 argument... 1: The name of a ship or wing.
get-object-heading
get-object-heading Returns the heading angle, in degrees, of a particular object. The returned value will be between 0 and 360. Takes 1 argument... 1: The name of a ship or wing.
get-object-speed-x
get-object-speed-x Returns the X speed of a ship or wing as an integer.Takes 2 or 3 arguments... 1: The name of the object. 2: Whether the speed on the axis should be set according to the universe grid (when false) or according to the object's facing (when true); You almost always want to set this to true; (optional; defaults to false).
get-object-speed-y
get-object-speed-y Returns the Y speed of a ship or wing as an integer.Takes 2 or 3 arguments... 1: The name of the object. 2: Whether the speed on the axis should be set according to the universe grid (when false) or according to the object's facing (when true); You almost always want to set this to true; (optional; defaults to false).
get-object-speed-z
get-object-speed-z Returns the Z speed of a ship or wing as an integer.Takes 2 or 3 arguments... 1: The name of the object. 2: Whether the speed on the axis should be set according to the universe grid (when false) or according to the object's facing (when true); You almost always want to set this to true; (optional; defaults to false).
Variables
string-to-int
string-to-int Converts a string into an integer. All non-numeric characters (except for the negative sign) will be ignored, as will any fractional part of a decimal number. This behavior is somewhat different than the atoi() function in C or C++, which will abort if it encounters any non-numeric character. For a string like "turret31", this sexp will return 31, but atoi() will return 0. Takes 1 argument... 1: String to convert
string-get-length
string-get-length Returns the length of the specified string. Takes 1 argument.
Other
Change
Messages and Personas
scramble-messages
scramble-messages Causes messages to be sent as if the player has sustained communications subsystem or EMP damage. This effect can be reversed using unscramble-messages. Takes zero or more arguments. All (Optional): Name of the ship for which to scramble messages. If no ships are specified, message scrambling will be turned on for all messages the player receives.
unscramble-messages
unscramble-messages Undoes the effects of scramble-messages, causing messages to be sent clearly. Takes zero or more arguments. All (Optional): Name of the ship for which to scramble messages. If no ships are specified, message scrambling will be turned on for all messages the player receives.
disable-builtin-messages
Disable builtin messages (Action operator) Turns the built in messages sent by command or pilots off Takes 0 or more arguments.... If no arguments are supplied all built in messages are disabled. Using the Any Wingman option silences for all ships in wings. All: Name of ship to be silenced.
enable-builtin-messages
Enable builtin messages (Action operator) Turns the built in messages sent by command or pilots on Takes 0 or more arguments... If no arguments are supplied any ships not given individual silence orders will be able to send built in messages. Command will also be unsilenced Using the Any Wingman option cancels radio silence for all ships in wings. All: Name of ship to allow to talk.
set-persona
Set Persona (Action operator) Sets the persona of the supplied ship to the persona supplied Takes 2 or more arguments... 1: Persona to use. Rest: Name of the ship.
set-death-message
set-death-message Sets the message displayed when the specified players are killed. Takes 1 or more arguments... 1: The message Rest: The players for whom this message is displayed (optional) (currently not implemented)
set-mission-mood
set Mission Mood (Action operator) Sets the mood of the mission, this affects the choice of builtin messages sent by wingmen Takes 1 argument... 1: Mission mood (from messages.tbl) to use.
AI Control
remove-goal
Remove goal (Action operator) Removes a goal from a ship or wing. Takes 2 arguments... 1: Name of ship or wing to remove goal from. 2: Goal to remove.
change-ai-class
Change AI Class (Action operator)
Sets the specified ship or ship subsystem(s) to the specified ai class.
Takes 2 or more arguments...
1: AI Class to change to ("None", "Coward", "Lieutenant", etc.)
2: Name of ship to change AI class of
Rest: Name of subsystem to change AI class of (optional)
player-use-ai
player-use-ai Causes the player's ship to be controlled by the FreeSpace AI. Takes 0 arguments.
player-not-use-ai
player-not-use-ai Causes the player's ship to not be controlled by the FreeSpace AI. Takes 0 arguments.
set-player-orders
set-player-orders Changes the orders friendly AI will accept. Takes 3 or more arguments. 1: Ship Name 2: True/False as to whether this order is allowed or not Rest: Order
Ship Status
turret-protect-ship
Turret Protect ship (Action operator) Protects a ship from being attacked with a turret weapon of a given type. Any ship that is turret protected will not come under enemy fire from that type of turret, though it may come under fire by other turrets. Takes 2 or more arguments... 1: Type of turret (currently supported types are "beam", "flak", "laser", and "missile") Rest: Name of ship(s) to protect.
turret-unprotect-ship
Turret Unprotect ship (Action operator) Unprotects a ship from being attacked with a turret weapon of a given type. Any ship that is not turret protected can come under enemy fire from that type of turret. This function is the opposite of turret-protect-ship. Takes 2 or more arguments... 1: Type of turret (currently supported types are "beam", "flak", "laser", and "missile") Rest: Name of ship(s) to unprotect.
ship-stealthy
ship-stealthy Causes the ships listed in this sexpression to become stealth ships (i.e. invisible to radar). Takes 1 or more arguments... All: Name of ships to make stealthy.
ship-unstealthy
ship-unstealthy Causes the ships listed in this sexpression to become non-stealth ships (i.e. visible to radar). Takes 1 or more arguments... All: Name of ships to make non-stealthy.
friendly-stealth-invisible
friendly-stealth-invisible Causes the friendly ships listed in this sexpression to be invisible to radar, just like hostile stealth ships.It doesn't matter if the ship is friendly at the time this sexp executes: as long as it is a stealth ship, it willbe invisible to radar both as hostile and as friendly. Takes 1 or more arguments... All: Name of ships
friendly-stealth-visible
friendly-stealth-visible Causes the friendly ships listed in this sexpression to resume their normal behavior of being visible to radar asstealth friendlies. Does not affect their visibility as stealth hostiles. Takes 1 or more arguments... All: Name of ships
primitive-sensors-set-range
primitive-sensors-set-range Sets the range of the primitive sensors on a ship. Ships outside of this range will not appear on sensors. Has no effect on ships that do not have the "primitive-sensors" flag2 set. Takes 2 arguments... 1: Ship on which to set range 2: Range, in meters
ship-targetable-as-bomb
ship-targetable-as-bomb Causes the ships listed in this sexpression to be targetable with bomb targeting key. Takes 1 or more arguments... 1+: Name of ships to make targetable with bomb targeting key.
ship-untargetable-as-bomb
ship-untargetable-as-bomb Causes the ships listed in this sexpression to not be targetable with bomb targeting key. Takes 1 or more arguments... 1+: Name of ships to make nontargetable with bomb targeting key.
kamikaze
kamikaze Tells ships to perform a kamikaze on its current target. Takes 2 or more arguments... 1: Damage dealt when kamikaze is done Rest: Names of ships to perform kamikaze
change-iff-color
Change IFF Color (Action operator) Sets the specified ship(s) or wing(s) apparent color. Takes 6 or more arguments... 1: Name of the team from which target is observed from. 2: Name of the team of the observed target to receive the alternate color. 3: Red color (value from 0 to 255). 4: Green color (value from 0 to 255). 5: Blue color (value from 0 to 255). Rest: Name of ship or wing to change team status of.
ship-change-alt-name
ship-change-alt-name Changes the alternate ship class name displayed in the HUD target window. Takes 2 or more arguments... 1: The ship class name to display Rest: The ships to display the new class name
ship-change-callsign
ship-change-callsign Changes the callsign of a ship. Takes 2 or more arguments... 1: The callsign to display or empty to remove Rest: The ships to display the new callsign
ship-tag
ship-tag Tags a ship. Takes 3 or 8 arguments... 1: The name of a ship. 2: The tag level (currently 1, 2, or 3). 3: The tag time (in seconds). 4: A SSM missile (optional - used only for TAG-C). 5: The X origin of the SSM missile (optional - used only for TAG-C). 6: The Y origin of the SSM missile (optional - used only for TAG-C). 7: The Z origin of the SSM missile (optional - used only for TAG-C). 8: The team the SSM missile belongs to (optional - used only for TAG-C).
ship-untag
Min arguments: 1, Max arguments: 1
set-arrival-info
set-arrival-info Sets arrival information for a ship or wing. Takes 2 to 7 arguments... 1: Ship or wing name 2: Arrival location 3: Arrival anchor (optional; only required for certain locations) 4: Arrival path mask (optional; this is a bitfield where the bits set to 1 correspond to the paths to use; defaults to 0 which is a special case that means all paths can be used) 5: Arrival distance (optional; defaults to 0) 6: Arrival delay (optional; defaults to 0) 7: Whether to show a jump effect if arriving from subspace (optional; defaults to true)
set-departure-info
set-departure-info Sets departure information for a ship or wing. Takes 2 to 6 arguments... 1: Ship or wing name 2: Departure location 3: Departure anchor (optional; only required for certain locations) 4: Departure path mask (optional; this is a bitfield where the bits set to 1 correspond to the paths to use; defaults to 0 which is a special case that means all paths can be used) 5: Departure delay (optional; defaults to 0) 6: Whether to show a jump effect if departing to subspace (optional; defaults to true)
alter-ship-flag
alter-ship-flag Sets a ships flag and/or parse flag. Takes 4 or more arguments... 1: Ship flag name 2: True if turning on, false if turning off 3: True\False - Apply this flag to future waves of this wing. Apply to ship if not present Rest: (optional) Name of ships, wings, or entire teams. If not supplied, will work on all ships in the mission Ship Flags: invulnerable - Stops ship from taking any damage protect-ship - Ship and Turret AI will ignore and not attack ship beam-protect-ship - Turrets with beam weapons will ignore and not attack ship no-shields - Ship will have no shields (ETS will be rebalanced if shields were off and are enabled) targetable-as-bomb - Allows ship to be targetted with the bomb targetting key flak-protect-ship - Turrets with flak weapons will ignore and not attack ship laser-protect-ship - Turrets with laser weapons will ignore and not attack ship missile-protect-ship - Turrets with missile weapons will ignore and not attack ship immobile - Will not let a ship move or rotate in any fashion vaporize - Causes a ship to vanish (no deathroll, no debris, no explosion) when destroyed break-warp - Causes a ship's subspace drive to break. Can be repaired by a support ship never-warp - Causes a ship's subspace drive to never work. Cannot be repaired by a support ship afterburner-locked - Will stop a ship from firing their afterburner primaries-locked - Will stop a ship from firing their primary weapons secondaries-locked - Will stop a ship from firing their secondary weapons no-subspace-drive - Will not allow a ship to jump into subspace don't-collide-invisible - Will cause polygons with an invisible texture to stop colliding with objects no-ets - Will not allow a ship to alter its ETS system toggle-subsystem-scanning - Switches between being able to scan a whole ship or individual subsystems scannable - Whether or not the ship can be scanned cargo-known - If set, the ships cargo can be seen without scanning the ship stealth - If set, the ship can't be targeted, is invisible on radar, and is ignored by AI unless firing friendly-stealth-invisible - If set, the ship can't be targeted even by ships on the same team hide-ship-name - If set, the ship name can't be seen when the ship is targeted hidden-from-sensors - If set, the ship can't be targeted and appears on radar as a blinking dot no-dynamic - Will stop allowing the AI to persue dynamic goals (eg: chasing ships it was not ordered to) no-secondary-lock-on - Will disable target acquisition for secondaries of all types (does not affect turrets)
Weapons, Shields, and Engines
set-weapon-energy
set-weapon-energy Sets the weapon energy for the specified ship(s) Takes 2 or more arguments 1: percentage of maximum weapon energy. (rest): Name(s) of ship(s)
set-shield-energy
set-shield-energy Sets the shield energy for the specified ship(s) Takes 2 or more arguments 1: percentage of maximum shield energy. (rest): Name(s) of ship(s)
set-player-throttle-speed
set-player-throttle-speed Sets a player's throttle to a percentage of their maximum speed. This SEXP has no effect if used on an AI ship, however it will still work on an AI-controlled player ship. Takes 2 arguments... 1: The player ship to set the throttle of. 2: The percentage of the player's maximum speed to set their throttle to. This is capped to either 0 or 100 if outside the valid range.
set-afterburner-energy
set-afterburner-energy Sets the afterburner energy for the specified ship(s) Takes 2 or more arguments 1: percentage of maximum afterburner energy. (rest): Name(s) of ship(s)
set-subspace-drive
set-subspace-drive Turns on or off the subspace edrive for the given ships. A ship with no subspace drive will act as though it doesn't even occur to him to depart via subspace, and if ordered to do so, he will look for a friendly ship with a hangar bay. If the ship is the player, pressing Alt-J will not not initiate a jump, nor give any indication that a jump failed. Takes 2 or more arguments... 1: True if the ship should have a drive; false otherwise Rest: List of ships
set-primary-weapon
set-primary-weapon Sets the weapon for the specified bank 1: Ship name 2: Bank to check (0, 1 and 2 are legal banks) 3: Name of the primary weapon 4: Number to set ammo of this bank to (If this is larger than the maximum, bank will be set to maximum) 5: Rearm Limit. Support ships will only supply this number of weapons (If this is larger than the maximum, bank will be set to maximum)
set-secondary-weapon
set-secondary-weapon Sets the weapon for the specified bank 1: Ship name 2: Bank to check (0, 1, 2 and 3 are legal banks) 3: Name of the secondary weapon 4: Number to set ammo of this bank to (If this is larger than the maximum, bank will be set to maximum) 5: Rearm Limit. Support ships will only supply this number of weapons (If this is larger than the maximum, bank will be set to maximum)
set-primary-ammo
set-primary-ammo Sets the amount of ammo for the specified ballistic bank 1: Ship name 2: Bank to check (0, 1, and 2 are legal banks) 3: Number to set this bank to (If this is larger than the maximum, bank will be set to maximum). 4: Rearm Limit. Support ships will only supply this number of weapons (If this is larger than the maximum, bank will be set to maximum)
set-secondary-ammo
set-secondary-ammo Sets the amount of ammo for the specified bank 1: Ship name 2: Bank to check (0, 1, 2 and 3 are legal banks) 3: Number to set this bank to (If this is larger than the maximum, bank will be set to maximum). 4: Rearm Limit. Support ships will only supply this number of weapons (If this is larger than the maximum, bank will be set to maximum)
set-num-countermeasures
set-num-countermeasures Sets the number of countermeasures the ship has Values greater than the maximum a ship can carry are set to the maximum 1: Ship name 2: Number to set
lock-primary-weapon
lock-primary-weapon Locks the primary banks for the specified ship(s) Takes 1 or more arguments (all): Name(s) of ship(s) to lock
unlock-primary-weapon
unlock-primary-weapon Unlocks the primary banks for the specified ship(s) Takes 1 or more arguments (all): Name(s) of ship(s) to lock
lock-secondary-weapon
lock-secondary-weapon Locks the secondary banks for the specified ship(s) Takes 1 or more arguments (all): Name(s) of ship(s) to lock
unlock-secondary-weapon
unlock-secondary-weapon Unlocks the secondary banks for the specified ship(s) Takes 1 or more arguments (all): Name(s) of ship(s) to lock
lock-afterburner
lock-afterburner Locks the afterburners on the specified ship(s) Takes 1 or more arguments (all): Name(s) of ship(s) to lock
unlock-afterburner
unlock-afterburner Unlocks the afterburners on the specified ship(s) Takes 1 or more arguments (all): Name(s) of ship(s) to lock
shields-on
shields-on Causes the ship listed in this sexpression to have their shields activated. If the ship had no-shields prior to the sexp being called, the ETS will be rebalanced to default. Takes 1 or more arguments... 1+: Name of ships to activate shields on.
shields-off
shields-off Causes the ships listed in this sexpression to have their shields deactivated. Takes 1 or more arguments... 1+: Name of ships to deactivate shields on.
force-glide
force-glide Forces a given ship into glide mode, provided it is capable of gliding. Note that the player will not be able to leave glide mode on his own,, and that a ship in glide mode cannot warp out or enter autopilot.Takes 2 Arguments... 1: Ship to force 2: True to activate glide, False to deactivate
disable-ets
disable-ets Switches a ships' ETS system off Takes at least 1 argument... All: List of ships this sexp applies to
enable-ets
enable-ets Switches a ships' ETS system on Takes at least 1 argument... All: List of ships this sexp applies to
set-ets-values
set-ets-values Sets ETS indexes for a ship Index values are used in a hard-coded array to lookup recharge percentages Each index has a valid range of 0 to 12 Use index values retrieved with get-ets-value Or if you use your own values, ensure they add up to 12 (e.g. 0,3,9) 1: Engine index 2: Shields index 3: Weapons index 4: Ship name
Subsystems and Health
ship-guardian-threshold
ship-guardian-threshold Same as ship-guardian, except the lowest possible hull value is specified by the sexp rather than defaulting to 1. Call with a threshold of 0 (or use ship-no-guardian) to deactivate. Takes 2 or more arguments... 1: Threshold value. 2+: Name of ships to make unkillable.
ship-subsys-guardian-threshold
ship-subsys-guardian-threshold Same as ship-guardian-threshold, but works on subsystems. Call with a threshold of 0 to deactivate. Takes 3 or more arguments... 1: Threshold value. 2: Ship housing the subsystem(s). 3+: Subsystems to make unkillable.
destroy-instantly
destroy-instantly Self-destructs the named ship without explosion, death roll, or debris. That is, the ship is instantly gone from the mission and the only indication of what happened is a mission log entry. Non-player ship only! All: List of ship names to destroy.
destroy-subsys-instantly
destroy-subsys-instantly Destroys the specified subsystems without effects.Takes 2 or more arguments... 1: Name of ship subsystem is on. Rest: Name of subsystem to destroy.
ship-copy-damage
ship-copy-damage Copies the damage (hull, shields, and subsystems) from the first ship in the list to the rest. The initial ship must be currently present in the mission, but the target ships may be either in-mission or on the arrival list. Takes 2 or more arguments... 1: The name of the ship that supplies the damage stats Rest: The list of ships to be modified
lock-rotating-subsystem
lock-rotating-subsystem Instantaneously locks a rotating subsystem so that it cannot rotate unless freed by free-rotating-subsystem. Takes 2 or more arguments... 1: Name of the ship housing the subsystem Rest: Name of the rotating subsystem to lock
free-rotating-subsystem
free-rotating-subsystem Instantaneously frees a rotating subsystem previously locked by lock-rotating-subsystem. Takes 2 or more arguments... 1: Name of the ship housing the subsystem Rest: Name of the rotating subsystem to free
reverse-rotating-subsystem
reverse-rotating-subsystem Instantaneously reverses the rotation direction of a rotating subsystem. Takes 2 or more arguments... 1: Name of the ship housing the subsystem Rest: Name of the rotating subsystem to reverse
rotating-subsys-set-turn-time
rotating-subsys-set-turn-time Sets the turn time of a rotating subsystem. Takes 3 or 4 arguments... 1: Name of the ship housing the subsystem 2: Name of the rotating subsystem to configure 3: The time for one complete rotation, in milliseconds (positive is counterclockwise, negative is clockwise) 4: The acceleration (x1000, just as #3 is seconds x1000) to change from the current turn rate to the desired turn rate. This is actually the time to complete one rotation that changes in one second, or the reciprocal of what you might expect, meaning that larger numbers cause slower acceleration. (FS2 defaults to 2pi/0.5, or about 12.566, which would be 12566 in this sexp.) The advantage of this method is so that this argument can be directly compared to the previous argument using a ratio, without worrying about pi. Omit this argument if you want an instantaneous change.
trigger-submodel-animation
trigger-submodel-animation Activates a submodel animation trigger for a given ship. Takes 4 to 6 arguments... 1: The ship on which the animation should run 2: The type of animation (named as one would see them in ships.tbl) 3: The subtype of animation, which is type-dependent. For docking animations this is the dock index. 4: The animation direction: 1 for forward, or -1 for reverse 5: (Optional) Whether the animation should instantly snap to its final position 6: (Optional) A subsystem, if the animation should trigger on only a specific subsystem as opposed to all applicable subsystems
change-subsystem-name
change-subsystem-name Changes the name of the specified subsystem on the specified ship Takes 3 or more arguments 1: Name of the ship. 2: New name for the subsystem (names larger than the maximum display size will be truncated 3: Name(s) of subsystem(s) to rename
ship-subsys-targetable
ship-subsys-targetable Causes the specified ship subsystem(s) to be targetable on radar. Takes 2 or more arguments... 1: Name of a ship Rest: Name of the ship's subsystem(s)
ship-subsys-untargetable
ship-subsys-untargetable Causes the specified ship subsystem(s) to not be targetable on radar. Takes 2 or more arguments... 1: Name of a ship Rest: Name of the ship's subsystem(s)
ship-subsys-no-replace
ship-subsys-no-replace Causes the -destroyed version of specified ship subsystem(s) to not render when it's destroyed. Takes 3 or more arguments... 1: Name of a ship 2: True = Do not render or False = render if exists Rest: Name of the ship's subsystem(s) Note: If subsystem is already dead it will vanish or reappear out of thin air
ship-subsys-no-live-debris
ship-subsys-no-live-debris Causes the specified ship subsystem(s) to not render live debris when it's destroyed. Takes 3 or more arguments... 1: Name of a ship 2: True = Do not render or False = render if exists Rest: Name of the ship's subsystem(s)
ship-subsys-vanish
ship-subsys-vanish Causes the subsystem to vanish without a trace - no fanfare, notification, or special effects. See also ship-vanish. Single Player Only! Warning: This will cause subsystem destruction not to be logged, so 'has-departed', etc. will not work Takes 3 or more arguments... 1: Name of a ship 2: True = vanish or False = don't vanish Rest: Name of the ship's subsystem(s) Note: Useful for replacing subsystems with actual docked models.
ship-subsys-ignore_if_dead
ship-subsys-ignore-if-dead Causes secondary weapons to ignore dead ship subsystem(s)and home on hull instead. Takes 3 or more arguments... 1: Name of a ship 2: True = Ignore dead or False = don't ignore Rest: Name of the ship's subsystem(s)
Cargo
set-docked
set-docked Causes one ship to become instantly docked to another at the specified docking ports. Takes 4 arguments... 1: Docker ship 1: Docker point 1: Dockee ship 1: Dockee point
set-scanned
set-scanned Sets the cargo on the specified ship or ship subsystem as known or scanned. Takes 1 or more arguments... 1: Name of a ship Rest: Name of a subsystem on that ship (optional)
set-unscanned
set-unscanned Sets the cargo on the specified ship or ship subsystem as unknown or unscanned. Takes 1 or more arguments... 1: Name of a ship Rest: Name of a subsystem on that ship (optional)
set-cargo
Set Cargo (Action operator) Sets the cargo on a ship or ship subsystem. The cargo-no-deplete flag status is carried through to the new cargo. Takes 2 or 3 arguments... 1: Name of the cargo 2: Name of the ship 3: Name of the ship subsystem (optional)
Armor and Damage Types
set-armor-type
set-armor-type Sets the armor type for a ship or subsystem 1: Ship subsystem is on 2: Set = true/Reset to default = false 3: Armor type to set or <none> rest: Subsystems to set (hull for ship, shield for shields)
weapon-set-damage-type
weapon-set-damage-type Sets the damage type for weapons or their shockwaves 1: True = set weapon, False = set shockwave 2: damage type to set or <none> 3: Set = true/Reset to default = false rest: Weapons to set
ship-set-damage-type
ship-set-damage-type Sets the damage type for ships collision or debris 1: true = set collision, False = set debris 2: Damage type to set or <none> 3: Set = true/Reset to default = false rest: Ships to set
ship-set-shockwave-damage-type
ship-set-shockwave-damage-type Sets the shockwave damage type for a class of ship. All ships of that class are changed. 1: Damage type to set or <none> 2: Set = true/Reset to default = false rest: Ship classes to set
field-set-damage-type
field-set-damage-type Sets the damage type for asteroid/debris fields 1: Damage type to set or <none> 2: Set = true/Reset to default = false
Beams and Turrets
fire-beam-at-coordinates
fire-beam-at-coordinates Fire a beam weapon from a specified subsystem at a set of coordinates. Not compatible with multiplayer. 1: Ship which will be firing 2: Turret which will fire the beam (note, this turret must have at least 1 beam weapon on it) 3: x coordinate to be targeted 4: y coordinate to be targeted 5: z coordinate to be targeted 6: (Optional Operator) Whether to force the beam to fire (disregarding FOV and subsystem status). Defaults to False 7: second x coordinate to be targeted (optional; only used for slash beams) 8: second y coordinate to be targeted (optional; only used for slash beams) 9: second z coordinate to be targeted (optional; only used for slash beams)
beam-create
beam-create Fire a beam weapon from the specified coordinates to the specified target. Not compatible with multiplayer. 1: Beam weapon to fire 2: Parent ship (for kill credit, if applicable; can be none) 3: Team for this beam to be on (related to difficulty-based damage) 4: X coordinate to fire from 5: Y coordinate to fire from 6: Z coordinate to fire from 7: Target ship (can be none) 8: Target subsystem (optional, can be none) 9: X coordinate to fire at (optional) 10: Y coordinate to fire at (optional) 11: Z coordinate to fire at (optional) 12: Second X coordinate to fire at (optional; used for slash beams) 13: Second Y coordinate to fire at (optional; used for slash beams) 14: Second Z coordinate to fire at (optional; used for slash beams)
turret-tagged-specific
turret-tagged-specific Specific turrets on a ship only fire at tagged targets, as opposed to all turrets doing this using turret-tagged-only It is safe to slave turrets already slaved Takes 2 or more arguments... 1: Name of ship to slave some turrets to target only tagged ships Rest: Turrets to slave
turret-tagged-clear-specific
turret-tagged-clear-specific Specific turrets on a ship are free to fire on untagged ships, as opposed to all turrets doing this using turret-tagged-clear It is safe to unslave turrets already free Takes 2 or more arguments... 1: Name of ship to unslave some turrets to target any hostile ship Rest: Turrets to unslave
turret-change-weapon
turret-change-weapon Sets a given turret weapon slot to the specified weapon 1: Ship turret is on 2: Turret 3: Weapon to set slot to 4: Primary slot (or 0 to use secondary) 5: Secondary slot (or 0 to use primary)
turret-set-direction-preference
turret-set-direction-preference Sets specified ship turrets direction preference to the specified value 1: Ship turrets are on 2: Preference to set, 0 to disable, or negative to reset to default rest: Turrets to set
turret-set-rate-of-fire
turret-set-rate-of-fire Sets specified ship turrets rate of fire to the specified value 1: Ship turrets are on 2: Rate to set in percentage format (200 = 2x, 50 = .5x), 0 to set to number of fire points, or negative to reset to default rest: Turrets to set
turret-set-optimum-range
turret-set-optimum-range Sets specified ship turrets optimum range to the specified value 1: Ship turrets are on 2: Priority to set, 0 to disable, or negative to reset to default rest: Turrets to set
turret-set-target-priorities
turret-set-target-priorities Sets target priorities for the specified ship turret 1: Ship turret is on 2: Turret to set 3: True = Set new list, False = Reset to turret default rest: Priorities to set (max 32) or blank for no priorities
turret-set-target-order
turret-set-target-order Sets targeting order of a given turret 1: Ship turret is on 2: Turret rest: Target order type (Bombs,ships,asteroids)
ship-turret-target-order
ship-turret-target-order Sets targeting order of all turrets on a given ship 1: Ship turrets are on rest: Target order type (Bombs,ships,asteroids)
turret-subsys-target-disable
turret-subsys-target-disable Prevents turrets from targeting only the subsystems when targeting large targets 1: Ship to be operated on rest: List of turrets that are affected
turret-subsys-target-enable
turret-subsys-target-enable Sets turret to target the subsystems when targeting large targets 1: Ship to be operated on rest: List of turrets that are affected
turret-set-primary-ammo
turret-set-primary-ammo Sets the turret's primary bank ammo, only works with ballistic weapons 1: Ship turret is on 2: Turret the bank is on 3: Bank to add ammo to 4: Amount to add
turret-set-secondary-ammo
turret-set-secondary-ammo Sets the turret's secondary bank ammo 1: Ship turret is on 2: Turret the bank is on 3: Bank to add ammo to 4: Amount to add
Models and Textures
change-ship-class
change-ship-class Causes the listed ships' classes to be changed to the specified ship class. Takes 2 or more arguments... 1: The name of the new ship class Rest: The list of ships to change the classes of
deactivate-glow-maps
deactivate-glow-maps Deactivates the glow maps for a ship. Takes 1 or more arguments... All: Name of ship on which to deactivate glow maps
activate-glow-maps
activate-glow-maps Activates the glow maps for a ship. Takes 1 or more arguments... All: Name of ship on which to activate glow maps
deactivate-glow-points
deactivate-glow-points Deactivates all glow points on a ship. Takes 1 or more arguments... All: Name of ship on which to deactivate glow points
activate-glow-points
activate-glow-points Activates all glow points on a ship. Takes 1 or more arguments... All: Name of ship on which to activate glow points
deactivate-glow-point-bank
deactivate-glow-point-bank Deactivates one or more glow point bank(s) on a ship. Takes 2 or more arguments... 1: Name of ship on which to deactivate glow point bank(s) Rest: Name of glow point bank to deactivate
activate-glow-point-bank
activate-glow-point-bank Activates one or more glow point bank(s) on a ship. Takes 2 or more arguments... 1: Name of ship on which to activate glow point bank(s) Rest: Name of glow point bank to activate
set-thrusters-status
set-thrusters-status Manipulates the thrusters on a ship. Takes 2 or more arguments... 1: Boolean, true sets thrusters to visible, false deactivates them. 2: Rest: List of ships this sexp will work on.
don't-collide-invisible
don't-collide-invisible Sets the "don't collide invisible" flag on a list of ships. Takes 1 or more arguments... All: List of ships on which to set the "don't collide invisible" flag
collide-invisible
collide-invisible Unsets the "don't collide invisible" flag on a list of ships. Takes 1 or more arguments... All: List of ships on which to unset the "don't collide invisible" flag
add-to-collision-group
add-to-collision-group Adds a ship to the specified collision group(s). Note that there are 32 collision groups, and that an object may be in several collision groups at the same time Takes 2 or more Arguments... 1: Object to add 2+: Group IDs. Valid IDs are 0 through 31 inclusive.
remove-from-collision-group
remove-from-collision-group Removes a ship from the specified collision group(s). Note that there are 32 collision groups, and that an object may be in several collision groups at the same time Takes 2 or more Arguments... 1: Object to add 2+: Group IDs. Valid IDs are 0 through 31 inclusive.
get-collision-group
get-collision-group Returns an objects' collision group ID. Note that this ID is a bitfield. Takes 1 Argument... 1: Object name
change-team-color
change-team-color Changes the team color setting for one or several ships. This sexp has no effect on ships that don't have team colors enabled for them. Takes 3 or more arguments... 1: The new team color name. Name must be defined in colors.tbl. 2: Crossfade time in milliseconds. During this time, colors will be mixed. 3: Rest: List of ships this sexp will operate on.
Coordinate Manipulation
set-object-position
set-object-position Instantaneously sets an object's spatial coordinates.Takes 4 arguments... 1: The name of a ship, wing, or waypoint. 2: The new X coordinate. 3: The new Y coordinate. 4: The new Z coordinate.
set-object-orientation
set-object-orientation Instantaneously sets an object's spatial orientation.Takes 4 arguments... 1: The name of a ship or wing. 2: The new pitch angle, in degrees. The angle can be any number; it does not have to be between 0 and 360. 3: The new bank angle, in degrees. The angle can be any can be any number; it does not have to be between 0 and 360. 4: The new heading angle, in degrees. The angle can be any number; it does not have to be between 0 and 360.
set-object-facing
set-object-facing Sets an object's orientation to face the specified coordinates. Takes 4 arguments... 1: The name of a ship or wing. 2: The X coordinate to face. 3: The Y coordinate to face. 4: The Z coordinate to face. 5: Turn time in milliseconds (optional) 6: Bank (optional). Enter a non-zero value to enable banking. Note that if Turn time is specified, this needs to be called once per frame, as the rotation is reset every frame. Note that Turn time is the time for the object to rotate a full revolution, *not* how long it will take to do this turn.
set-object-facing-object
set-object-facing-object Sets an object's orientation to face the specified object. Takes 2 arguments... 1: The name of a ship or wing. 2: The object to face. 3: Turn time in milliseconds (optional) 4: Bank (optional). Enter a non-zero value to enable banking. Note that if Turn time is specified, this needs to be called once per frame, as the rotation is reset every frame. Note that Turn time is the time for the object to rotate a full revolution, *not* how long it will take to do this turn.
set-object-speed-x
set-object-speed-x (deprecated in favor of ship-maneuver) Sets the X speed of a ship or wing.Takes 2 or 3 arguments... 1: The name of the object. 2: The speed to set. 3: Whether the speed on the axis should be set according to the universe grid (when false) or according to the object's facing (when true); You almost always want to set this to true; (optional; defaults to false).
set-object-speed-y
set-object-speed-y (deprecated in favor of ship-maneuver) Sets the Y speed of a ship or wing.Takes 2 or 3 arguments... 1: The name of the object. 2: The speed to set. 3: Whether the speed on the axis should be set according to the universe grid (when false) or according to the object's facing (when true); You almost always want to set this to true; (optional; defaults to false).
set-object-speed-z
set-object-speed-z (deprecated in favor of ship-maneuver) Sets the Z speed of a ship or wing.Takes 2 or 3 arguments... 1: The name of the object. 2: The speed to set. 3: Whether the speed on the axis should be set according to the universe grid (when false) or according to the object's facing (when true); You almost always want to set this to true; (optional; defaults to false).
ship-maneuver
ship-maneuver Combines the effects of the ship-rot-maneuver and ship-lat-maneuver sexps. Takes 10 or 11 arguments: 1: The name of a ship or wing 2: Duration of the maneuver, in milliseconds. Specifying 0 or 1 indicates infinite duration. 3: Heading movement velocity, as a percentage (-100 to 100) of the tabled maximum heading velocity, or 0 to not modify the ship's current value 4: Pitch movement velocity, as a percentage (-100 to 100) of the tabled maximum pitch velocity, or 0 to not modify the ship's current value 5: Bank movement velocity, as a percentage (-100 to 100) of the tabled maximum bank velocity, or 0 to not modify the ship's current value 6: Whether to apply all of the rotational velocity values even if any of them are 0 7: Vertical movement velocity, as a percentage (-100 to 100) of the tabled maximum vertical velocity, or 0 to not modify the ship's current value 8: Sideways movement velocity, as a percentage (-100 to 100) of the tabled maximum sideways velocity, or 0 to not modify the ship's current value 9: Forward movement velocity, as a percentage (-100 to 100) of the tabled maximum forward velocity, or 0 to not modify the ship's current value 10: Whether to apply all of the lateral velocity values even if any of them are 0 11: Maneuver flags (optional): a bitfield with any of the following options: 1 or 2^0: don't bank when changing heading 2 or 2^1: allow maneuvers exceeding tabled maximums (outside the -100 to 100 range) 4 or 2^2: instantaneously jump to the goal velocity
ship-rot-maneuver
ship-rot-maneuver Causes a ship to move in a rotational direction. For the purposes of this sexp, this means the ship rotates along its own heading, pitch, or bank axis (or a combination of axes) without regard to normal ship rotation rules. You may find it necessary to disable the ship AI (e.g. by issuing a play-dead order) before running this sexp. Takes 6 or 7 arguments: 1: The name of a ship or wing 2: Duration of the maneuver, in milliseconds. Specifying 0 or 1 indicates infinite duration. 3: Heading movement velocity, as a percentage (-100 to 100) of the tabled maximum heading velocity, or 0 to not modify the ship's current value 4: Pitch movement velocity, as a percentage (-100 to 100) of the tabled maximum pitch velocity, or 0 to not modify the ship's current value 5: Bank movement velocity, as a percentage (-100 to 100) of the tabled maximum bank velocity, or 0 to not modify the ship's current value 6: Whether to apply all of the above velocity values even if any of them are 0 7: Maneuver flags (optional): a bitfield with any of the following options: 1 or 2^0: don't bank when changing heading 2 or 2^1: allow maneuvers exceeding tabled maximums (outside the -100 to 100 range) 4 or 2^2: instantaneously jump to the goal velocity
ship-lat-maneuver
ship-lat-maneuver Causes a ship to move in a lateral direction. For the purposes of this sexp, this means the ship translates along its own X, Y, or Z axis (or a combination of axes) without regard to normal ship movement rules. You may find it necessary to disable the ship AI (e.g. by issuing a play-dead order) before running this sexp. Takes 6 or 7 arguments: 1: The name of a ship or wing 2: Duration of the maneuver, in milliseconds. Specifying 0 or 1 indicates infinite duration. 3: Vertical movement velocity, as a percentage (-100 to 100) of the tabled maximum vertical velocity, or 0 to not modify the ship's current value 4: Sideways movement velocity, as a percentage (-100 to 100) of the tabled maximum sideways velocity, or 0 to not modify the ship's current value 5: Forward movement velocity, as a percentage (-100 to 100) of the tabled maximum forward velocity, or 0 to not modify the ship's current value 6: Whether to apply all of the above velocity values even if any of them are 0 7: Maneuver flags (optional): a bitfield with any of the following options: 1 or 2^0: don't bank when changing heading (which won't have any affect for lat-maneuver) 2 or 2^1: allow maneuvers exceeding tabled maximums (outside the -100 to 100 range) 4 or 2^2: instantaneously jump to the goal velocity
set-immobile
set-immobile Prevents the specified ship(s) from moving in any way. Takes 1 or more arguments... All: List of ships on which to set the "immobile" flag
set-mobile
set-mobile Allows the specified ship(s) to move. Opposite of set-immobile. Takes 1 or more arguments... All: List of ships on which to unset the "immobile" flag
Mission and Campaign
end-mission
end-mission Ends the mission as if the player had engaged his subspace drive, but without him doing so. Dumps the player back into a normal debriefing. Does not invoke red-alert status. 1: End Mission even if the player is dead (optional; defaults to true) 2: Boot the player out into the main hall instead of going to the debriefing (optional; defaults to false; not supported in multi) 3: Go to the mainhall instead of starting the next mission (optional; defaults to false; not yet tested in multi)
force-jump
force-jump Forces activation of the player's subspace drive, thus ending the mission. Takes no arguments.
set-debriefing-toggled
set-debriefing-toggled Sets or clears the "toggle debriefing" mission flag. If set, the mission will have its debriefing turned off, unless it is a multiplayer dogfight mission, in which case its debriefing will be turned on. Takes 1 argument.
allow-treason
allow-treason Turns the Allow Traitor switch on or off in mission. Takes 0 arguments. 1: True/False.
grant-promotion
Grant promotion (Action operator) In a single player game, this function grants a player an automatic promotion to the next rank which the player can obtain. If he is already at the highest rank, this operator has no effect. It takes no arguments.
grant-medal
Grant medal (Action operator) In single player missions, this function grants the given medal to the player. Currently, only 1 medal will be allowed to be given per mission. Takes 1 argument... 1: Name of medal to grant to player.
tech-add-ships
Tech add ship (Action operator) This operator makes the given ship type available in the techroom database. Players will then be able to view this ship's specs there. Takes 1 or more arguments... All: Name of ship type (or ship class) to add.
tech-add-weapons
Tech add weapon (Action operator) This operator makes the given weapon available in the techroom database. Players will then be able to view this weapon's specs there. Takes 1 or more arguments... All: Name of weapon (primary or secondary) to add.
tech-add-intel
Tech add intel (Action operator, deprecated in favor of tech-add-intel-xstr) This operator makes the given intel entry available in the techroom database. Players will then be able to view this intel entry there. Takes 1 or more arguments... All: Name of intel entry to add.
tech-remove-intel
Tech remove intel (Action operator, deprecated in favor of tech-remove-intel-xstr) This operator removes the given intel entry in the techroom database. Players will then not be able to view this intel entry there. Takes 1 or more arguments... All: Name of intel entry to remove.
tech-add-intel-xstr
Tech add intel XSTR (Action operator) This operator makes the given intel entry available in the techroom database. Players will then be able to view this intel entry there. Takes 2 or more arguments... 1: Name of intel entry to add. 2: XSTR ID of intel entry, or -1 if there is no XSTR entry. Use Add-Data for multiple entries. IMPORTANT: Each additional entry in the list MUST HAVE two fields; any entry without both fields will be ignored, as will any successive entries.
tech-remove-intel-xstr
Tech remove intel XSTR (Action operator) This operator removes the given intel entry, so it is no longer available in the techroom database. Players will then not be able to view this intel entry there. Takes 2 or more arguments... 1: Name of intel entry to remove. 2: XSTR ID of intel entry, or -1 if there is no XSTR entry. Use Add-Data for multiple entries. IMPORTANT: Each additional entry in the list MUST HAVE two fields; any entry without both fields will be ignored, as will any successive entries.
tech-reset-to-default
Tech reset to default (Action operator) This operator resets the tech room to the default represented in the tables. This is useful for starting new campaigns, so that the player will not see tech entries carried over from previous campaigns. Takes no arguments.
change-player-score
Change Player Score (Action operator) This operator allows direct alteration of the player's score for this mission. Takes 2 or more arguments. 1: Amount to alter the player's score by. Rest: Name of ship the player is flying.
change-team-score
Change Team Score (Action operator) This operator allows direct alteration of the team's score for a TvT mission (Does nothing otherwise). Takes 2 arguments. 1: Amount to alter the team's score by. 2: The team to alter the score for. (0 will add the score to all teams!)
set-respawns
set-respawns Set the # respawns a player (or AI that could have been a player) has used. 1: Number of respawns used up Rest: The player start ship to operate on. Only really useful for multiplayer.
add-remove-hotkey
add-remove-hotkey Add or remove hotkey for the specified ship(s) or wing(s) Takes 3 or more arguments 1: Boolean. True adds hotkey and false removes hotkey. 2: Integer of hotkey to add or remove. 0=F5, 1=F6, ... (rest): Name(s) of ship(s) or wing(s)
Music and Sound
change-soundtrack
change-soundtrack Changes the mission music. Takes 1 argument... 1: Name of the music selection (taken from music.tbl)
play-sound-from-table
play-sound-from-table Plays a sound listed in the Game Sounds section of sounds.tbl. Note that if the sound is a non-3D sound (if the min and max radius are 0, or unspecified), the sound will just play without being fixed at a particular position in space. In this case, the origin coordinates will be ignored. (A better design would have put the sound index first and made the origin arguments optional, but the difference between 2D and 3D sounds was not understood at the time. C'est la vie.) Takes 4 arguments... 1: Origin X 2: Origin Y 3: Origin Z 4: Sound (index into sounds.tbl or name of the sound entry)
play-sound-from-file
play-sound-from-file Plays a sound, such as a music soundtrack, from a file. Multiple sounds can be played with this sexp by assigning each sound to a music handle stored in a variable. Takes 1 to 4 arguments... 1: Sound (file name) 2: Enter a non-zero number to loop. default is off (optional). 3: Enter a non-zero number to use environment effects. default is off (optional). 4: Variable in which the music handle is to be stored (optional). If no variable is specified, the 'default' handle is used. Only one 'default' track can be played at a time, but multiple variable-managed tracks can be played.
close-sound-from-file
close-sound-from-file Closes the currently playing sound started by play-sound-from-file, if there is any. Takes 0 to 2 arguments... 1: Fade (optional; default is true) 2: Variable containing a music handle (optional). If no variable is specified, the 'default' handle is used.
pause-sound-from-file
pause-sound-from-file Pauses or unpauses the currently playing sound started by play-sound-from-file, if there is any. Takes 1 or 2 arguments... 1: Boolean - True to pause, False to unpause 2: Variable containing a music handle (optional). If no variable is specified, the 'default' handle is used.
set-sound-environment
set-sound-environment Sets the EAX environment for all sound effects. Optionally sets one or more parameters specific to the environment. Takes 1 or more arguments... 1: Sound environment name (a value of "<none>" will disable the effects) 2: Environment option (optional) 3: Environment value x 1000, e.g. 10 is 0.01 (optional) Use Add-Data to specify additional environment options in repeating option-value pairs, just like Send-Message-List can have additional messages in source-priority-message-delay groups. IMPORTANT: each additional option in the list MUST HAVE two entries; any option without the two proper fields will be ignored, as will any successive options.
update-sound-environment
update-sound-environment Updates the current EAX environment with new values. Takes 2 or more arguments... 1: Environment option 2: Environment value x 1000, e.g. 10 is 0.01 Use Add-Data to specify additional environment options in repeating option-value pairs, just like Send-Message-List can have additional messages in source-priority-message-delay groups. IMPORTANT: Each additional option in the list MUST HAVE two entries; any option without the two proper fields will be ignored, as will any successive options.
adjust-audio-volume
adjust-audio-volume Adjusts the relative volume of one sound type. Takes 1 to 3 arguments.... 1: Sound Type to adjust, either Music, Voice or Effects. Will act as a reset for the given category, if no other argument present 2: Percentage of the users' settings to adjust to (optional), 0 will be silence, 100 means the maximum volume as set by the user 3: Fade time (optional), time in milliseconds to adjust the volume
HUD
hud-disable
hud-disable Sets whether the hud is disabled. Takes 1 argument... 1: Flag (1 to disable, 0 to re-enable)
hud-disable-except-messages
hud-disable-except-messages Sets whether the hud (except for messages) is disabled. Takes 1 argument... 1: Flag (1 to disable, 0 to re-enable)
hud-set-custom-gauge-active
hud-set-custom-gauge-active Activates or deactivates a custom hud gauge defined in hud_gauges.tbl.Takes 2 Arguments... 1: Boolean, whether or not to display this gauge Rest: HUD Gauge name
hud-set-retail-gauge-active
hud-set-custom-gauge-active Activates or deactivates a retail hud gauge grouping.Takes 2 Arguments... 1: Boolean, whether or not to display this gauge Rest: HUD Gauge Group name
hud-set-text
hud-set-text Sets the text value of a given HUD gauge. Works for custom and certain retail gauges. Takes 2 arguments... 1: HUD gauge to be modified 2: Text to be set
hud-set-text-num
hud-set-text-num Sets the text value of a given HUD gauge to a number. Works for custom and certain retail gauges. Takes 2 arguments... 1: HUD gauge to be modified 2: Number to be set
hud-set-message
hud-set-message Sets the text value of a given HUD gauge to a message from the mission's message list. Works for custom and certain retail gauges. Takes 2 arguments... 1: HUD gauge to be modified 2: Message
hud-set-directive
hud-set-directive Sets the text of a given custom hud gauge to the provided text.Takes 2 Arguments... 1: HUD Gauge name 2: Text that will be displayed. This text will be treated as directive text, meaning that references to mapped keys will be replaced with the user's preferences.
hud-set-frame
hud-set-frame Sets the frame of a given HUD gauge's associated image. Works for custom and certain retail gauges. Takes 2 arguments... 1: HUD gauge to be modified 2: Frame number to be changed to
hud-set-coords
hud-set-coord Sets the coordinates of a given HUD gauge. Works for custom and retail gauges. Takes 3 arguments... 1: HUD gauge to be modified 2: Coordinate X component 2: Coordinate Y component
hud-set-color
hud-set-color Sets the color of a given HUD gauge. Works only for custom gauges Takes 4 arguments... 1: HUD gauge to be modified 2: Red component (0-255) 3: Green component (0-255) 4: Blue component (0-255)
hud-display-gauge
hud-display-gauge <milliseconds> <gauge> Causes specified hud gauge to appear or disappear for so many milliseconds. Takes 1 argument... 1: Number of milliseconds that the warpout gauge should appear on the HUD. 0 will immediately cause the gauge to disappear. 2: Name of HUD element. Must be one of: warpout - the "Subspace drive active" box that appears above the viewscreen.
hud-gauge-set-active
hud-gauge-set-active (deprecated) Activates or deactivates a given custom gauge.Takes 2 Arguments... 1: HUD Gauge name 2: Boolean, whether or not to display this gauge
hud-activate-gauge-type
hud-activate-gauge-type (deprecated) Activates or deactivates all hud gauges of a given type.Takes 2 Arguments... 1: Gauge Type 2: Boolean, whether or not to display this gauge
hud-clear-messages
hud-clear-messages Clears active messages displayed on the HUD.Takes no arguments
hud-set-max-targeting-range
hud-set-max-targeting-range Sets the farthest distance at which an object can be targeted. Takes 1 argument... �: Maximum targeting distance (0 for infinite)
add-nav-waypoint Adds a Navpoint to a navpoint path. Takes 3 or 4 Arguments... 1: Name of the new navpoint. 2: Name of the navpoint path the new navpoint should be added to. 3: Position where the new navpoint will be inserted. Note: This is 1-indexed, so the first waypoint in a path has position 1. 4: (Optional Argument) Controls the visibility of the new navpoint. Only entities belonging to the chosen category will be able to see it.
add-nav-ship Binds the named navpoint to the named ship - when the ship moves, the waypoint moves with it. Takes 2 Arguments... 1: The NavPoint's Name 2: The Ship's Name
del-nav Deletes a nav point. Takes 1 Argument... 1: NavPoint Name
hide-nav Hides a nav point. Takes 1 Argument... 1: NavPoint Name, it then 'hides' that Nav Point
restrict-nav This causes the nav point to be unselectable. Takes 1 Argument... 1: The Navpoint name
unhide-nav Restores a hidden navpoint. Takes 1 Argument... 1: The Navpoint Name
unrestrict-nav Removes restrictions from a Navpoint. Takes 1 Argument... 1: The Navpoint Name
set-nav-visited Sets the status of the given Navpoint to "visited". Takes 1 Argument... 1: The Navpoint Name
unset-nav-visited Removes the "visited" status from a Navpoint. Takes 1 Argument... 1: The Navpoint Name
nav-set-carry Sets the Nav Carry flag for all listed ships. Vessels with this flag will follow the player into and out of autopilot. Takes 1 or more arguments... 1: Ships and Wings that should receive the Nav Carry flag.
unset-nav-carry Removes the Nav Carry flag from all listed ships and wings. Takes 1 or more arguments... 1: Ships and Wings to remove the Nav Carry flag from
set-nav-needslink Marks all listed ships as needing to link up before entering autopilot. Takes 1 or more arguments... 1: Ships to mark
unset-nav-needslink Removes the requirement for the listed ships to link up before entering autopilot. Takes 1 or more arguments... 1: Ships to mark
use-nav-cinematics Controls the use of the cinematic autopilot camera. Takes 1 Argument... 1: Set to true to enable automatic cinematics, set to false to disable automatic cinematics.
use-autopilot
use-autopilot Takes 1 boolean argument. 1: Set to true to enable autopilot, set to false to disable autopilot.
nav-select (Action operator) Selects a nav point. Takes 1 argument... 1: Name of the nav point.
nav-deselect (Action operator) Deselects any navpoint selected. Takes no arguments...
Cutscenes
set-cutscene-bars
set-cutscene-bars Shows bars at the top and bottom of screen. Takes 0 or 1 arguments... 1: Milliseconds for bars to slide in
unset-cutscene-bars
unset-cutscene-bars Removes cutscene bars. Takes 0 or 1 arguments... 1: Milliseconds for bars to slide out
fade-in
fade-in Fades in. Takes 0 to 4 arguments... 1: Time to fade in (in milliseconds) 2: Color to fade to (optional). If arguments 3 and 4 are specified, this is the R component of an RGB color. Otherwise it is 1 for white, 2 for red, and any other number for black. 3: G component of an RGB color (optional) 4: B component of an RGB color (optional)
fade-out
fade-out Fades out. Takes 0 to 4 arguments... 1: Time to fade in (in milliseconds) 2: Color to fade to (optional). If arguments 3 and 4 are specified, this is the R component of an RGB color. Otherwise it is 1 for white, 2 for red, and any other number for black. 3: G component of an RGB color (optional) 4: B component of an RGB color (optional)
set-camera
set-camera Sets SEXP camera, or another specified cutscene camera. Takes 0 to 1 arguments... (optional) 1: Camera name (created if nonexistent)
set-camera-position
set-camera-position Sets the camera position to a spot in mission space. Takes 3 to 6 arguments... 1: X position 2: Y position 3: Z position (optional) 4: Total turn time (milliseconds) 5: Time to spend accelerating/decelerating (milliseconds) 6: Time to spend decelerating (milliseconds)
set-camera-facing
set-camera-facing Makes the camera face the given point. Takes 3 to 6 arguments... 1: X position to face 2: Y position to face 3: Z position to face (optional) 4: Total turn time (milliseconds) 5: Time to spend accelerating/decelerating (milliseconds) 6: Time to spend decelerating (milliseconds)
set-camera-facing-object
set-camera-facing-object Makes the camera face the given object. Takes 1 to 4 arguments... 1: Object to face (optional) 2: Total turn time (milliseconds) 3: Time to spend accelerating/decelerating (milliseconds) 4: Time to spend decelerating (milliseconds)
set-camera-rotation
set-camera-rotation Sets the camera rotation. Takes 3 to 6 arguments... 1: Pitch (degrees) 2: Bank (degrees) 3: Heading (degrees) (optional) 4: Total turn time (milliseconds) 5: Time to spend accelerating/decelerating (milliseconds) 6: Time to spend decelerating (milliseconds)
set-camera-host
set-camera-host Sets the object and subystem camera should view from. Camera position is offset from the host. If the selected subsystem or one of its children has an eyepoint bound to it it will be used for the camera position and orientation.If the selected subsystem is a turret and has no eyepoint the camera will be at the first firing point and look along the firing direction.If a valid camera target is set the direction to the target will override any other orientation.Takes 1 to 2 arguments... 1: Ship to mount camera on (optional) 2: Subystem to mount camera on
set-camera-target
set-camera-target Sets the object and subystem camera should track. Camera orientation is offset from the target. Takes 1 to 2 arguments... 1: Ship to track (optional) 2: Subystem to track
set-camera-fov
set-camera-fov Sets the camera field of view. Takes 1 to 4 arguments... 1: New FOV (degrees) (optional) 2: Total zoom time (milliseconds) 3: Time to spend accelerating/decelerating (milliseconds) 4: Time to spend decelerating (milliseconds)
set-fov
set-fov Sets the field of view - overrides all camera settings. Takes 1 argument... 1: New FOV (degrees)
reset-fov
reset-fov Resets the field of view.
reset-camera
reset-camera Releases cutscene camera control. Takes 1 optional argument... (optional) 1: Reset camera data (Position, facing, FOV...) (default: false)
show-subtitle
show-subtitle (deprecated) Displays a subtitle, either an image or a string of text. As this operator tries to combine two functions into one and does not adjust coordinates for screen formats, it has been deprecated. Takes 4 to 13 arguments... 1: X position (negative value to be from right of screen) 2: Y position (negative value to be from bottom of screen) 3: Text to display 4: Time to be displayed, not including fadein/out 5: Image name (optional) 6: Fade in time (optional) 7: Center horizontally? (optional) 8: Center vertically? (optional) 9: Width (optional) 10: Text red component (0-255) (optional) 11: Text green component (0-255) (optional) 12: Text blue component (0-255) (optional) 13: Drawn after shading? (optional)
show-subtitle-text
show-subtitle-text Displays a subtitle in the form of text. Note that because of the constraints of the subtitle system, textual subtitles are currently limited to 255 characters or fewer. Takes 6 to 13 arguments... 1: Text to display, or the name of a message containing text 2: X position, from 0 to 100% (positive measures from the left; negative measures from the right) 3: Y position, from 0 to 100% (positive measures from the top; negative measures from the bottom) 4: Center horizontally? (if true, overrides argument #2) 5: Center vertically? (if true, overrides argument #3) 6: Time (in milliseconds) to be displayed, not including fade-in/fade-out 7: Fade time (in milliseconds) to be used for both fade-in and fade-out (optional) 8: Paragraph width, from 1 to 100% (optional; 0 uses default 200 pixels) 9: Text red component (0-255) (optional) 10: Text green component (0-255) (optional) 11: Text blue component (0-255) (optional) 12: Text font (optional) 13: Drawn after shading? (optional)
show-subtitle-image
show-subtitle-image Displays a subtitle in the form of an image. Takes 8 to 10 arguments... 1: Image to display 2: X position, from 0 to 100% (positive measures from the left; negative measures from the right) 3: Y position, from 0 to 100% (positive measures from the top; negative measures from the bottom) 4: Center horizontally? (if true, overrides argument #2) 5: Center vertically? (if true, overrides argument #3) 6: Image width, from 1 to 100% (0 uses original width) 7: Image height, from 1 to 100% (0 uses original height) 8: Time (in milliseconds) to be displayed, not including fade-in/fade-out 9: Fade time (in milliseconds) to be used for both fade-in and fade-out (optional) 10: Drawn after shading? (optional)
clear-subtitles
clear-subtitles Clears the subtitle queue completely.
lock-perspective
lock-perspective Prevents or allows the player from changing the view mode. Takes 1 or 2 arguments... 1: True to lock the view mode, false to unlock it 2: What view mode to lock; 0 for first-person, 1 for chase, 2 for external, 3 for top-down
set-camera-shudder
set-camera-shudder Causes the camera to shudder. Currently this will only work if the camera is showing the player's viewpoint (i.e. the HUD). Takes 2 arguments... 1: Time (in milliseconds) 2: Intensity. For comparison, the Maxim has an intensity of 1440.
supernova-stop
supernova-stop Stops a supernova in progress. Note this only works if the camera hasn't cut to the player's death animation yet.
set-motion-debris-override
set-motion-debris-override Controls whether or not motion debris should be active. This overrides any choice made by the user through the -nomotiondebris commandline flag.Takes 1 argument... 1: Boolean: True will disable motion debris, False reenable it.
Backgrounds and Nebulae
mission-set-nebula
mission-set-nebula Turns nebula on/off Takes1 argument... 1: 0 for nebula off, 1 for nebula on
mission-set-subspace
mission-set-subspace Turns subspace on/off Takes 1 argument... 1: 0 for subspace off, 1 for subspace on
add-background-bitmap
add-background-bitmap Adds a background bitmap to the sky. Returns an integer that is stored in a variable so it can be deleted using remove-background-bitmap Takes 8 to 9 arguments... 1: Background bitmap name 2: Pitch 3: Bank 4: Heading 5: X scale (expressed as a percentage of the original size of the bitmap) 6: Y scale (expressed as a percentage of the original size of the bitmap) 7: X divisions. 8: Y divisions. 9: Variable in which to store result (optional)
remove-background-bitmap
remove-background-bitmap Removes the nth background bitmap from the mission Takes 1 argument... 1: Zero based bitmap index from the 'Bitmap' box in the background editor You can also use the result of a previous call to add-background-bitmap to remove that added bitmap
add-sun-bitmap
add-sun-bitmap Adds a sun bitmap to the sky. Returns an integer that is stored in a variable so it can be deleted using remove-sun-bitmap Takes 5 to 6 arguments... 1: Sun bitmap name 2: Pitch 3: Bank 4: Heading 5: Scale (expressed as a percentage of the original size of the bitmap) 6: Variable in which to store result (optional)
remove-sun-bitmap
remove-sun-bitmap Removes the nth sun from the mission Takes 1 argument... 1: Zero based sun index from the 'Suns' box in the background editor You can also use the result of a previous call to add-sun-bitmap to remove that added sun
nebula-change-storm
nebula-change-storm Changes the current nebula storm Takes 1 argument... 1: Nebula storm to change to
nebula-toggle-poof
nebula-toggle-poof Toggles the state of a nebula poof Takes 2 arguments... 1: Name of nebula poof to toggle 2: A True boolean expression will toggle this poof on. A false one will do the opposite.
nebula-change-pattern
nebula-change-pattern Changes the current nebula background pattern (as defined in nebula.tbl) Takes 1 argument... 1: Nebula background pattern to change to
set-skybox-model
set-skybox-model Sets the current skybox model. Takes 1-7 arguments 1: Model filename (with .pof extension) to switch to 2: Restart animated textures, if they exist (optional, defaults to true) 3-8: Set or unset the following skyboxes flags (optional) add-lighting, no-transparency, add-zbuffer add-culling, no-glowmaps, force-clamp Note: If the model filename is set to "default" with no extension then it will switch to the mission supplied default skybox.
set-skybox-orientation
set-skybox-orientation Sets the current skybox orientation. Takes 3 arguments... 1: Pitch 2: Bank 3: Heading
set-ambient-light
set-ambient-light Sets the ambient light level for the mission Takes 3 arguments 1: Red (0 - 255). 2: Green (0 - 255). 3: Blue (0 - 255).
Jump Nodes
set-jumpnode-name
set-jumpnode-name Sets the name of a jump node. Takes 2 arguments... 1: Name of jump node to change name for 2: New name for jump node Note: SEXPs referencing the old name will not work after the name change.
set-jumpnode-color
set-jumpnode-color Sets the color of a jump node. Takes 5 arguments... 1: Jump node to change color for 2: Red value 3: Green value 4: Blue value 5: Alpha value
set-jumpnode-model
set-jumpnode-model Sets the model of a jump node. Takes 3 arguments... 1: Jump node to change model for 2: Model filename 3: Show as normal model. When this is true, the jumpnode will be rendered like a normal model.
show-jumpnode
show-jumpnode Sets a jump node to display on the screen. Any: Jump node to show
hide-jumpnode
hide-jumpnode Sets a jump node to not display on the screen. Any: Jump node to hide
Special Effects
set-post-effect
set-post-effect Configures a post-processing effect. Takes 2 arguments... 1: Effect type 2: Effect intensity (0 - 100). 3: (Optional) Red (0 - 255). 4: (Optional) Green (0 - 255). 5: (Optional) Blue (0 - 255).
reset-post-effects
reset-post-effects Resets all post-processing effects to their default values. Takes no arguments.
ship-effect
ship-effect Plays an animated shader effect on the ship(s) or wing(s). Takes 3 or more arguments... 1: Effect name (as defined in post_processing.tbl) 2: How long the effect should take in milliseconds Rest: Ship or wing name
ship-create
ship-create Creates a new ship Takes 5 to 8 arguments... 1: Name of new ship (use "<none>" for a default name) 2: Class of new ship 3: X position 4: Y position 5: Z position 6: Pitch (optional) 7: Bank (optional) 8: Heading (optional)
weapon-create
weapon-create Creates a new weapon Takes 5 to 10 arguments... 1: Name of parent ship (or "<none>" for no parent) 2: Class of new weapon 3: X position 4: Y position 5: Z position 6: Pitch (optional) 7: Bank (optional) 8: Heading (optional) 9: Targeted ship (optional) 10: Targeted subsystem (optional)
ship-vaporize
ship-vaporize Sets the ship to vaporize when it is destroyed. Does not actually destroy the ship - use self-destruct for that. Takes 1 or more arguments... All: List of ships on which to set the vaporize flag
ship-no-vaporize
ship-no-vaporize Sets the ship to not vaporize when it is destroyed. Does not actually destroy the ship - use self-destruct for that. Takes 1 or more arguments... All: List of ships on which to unset the vaporize flag
set-explosion-option
set-explosion-option Sets an explosion option on a particular ship. Takes 3 or more arguments... 1: Ship name 2: Explosion option 3: Explosion value (for shockwave speed, 0 will produce no shockwave; for death roll time, 0 will use the default time) Use Add-Data to specify additional explosion options in repeating option-value pairs, just like Send-Message-List can have additional messages in source-priority-message-delay groups. IMPORTANT: Each additional option in the list MUST HAVE two entries; any option without the two proper fields will be ignored, as will any successive options.
explosion-effect
explosion-effect Causes an explosion at a given origin, with the given parameters. Takes 11 to 14 arguments... 1: Origin X 2: Origin Y 3: Origin Z 4: Damage 5: Blast force 6: Size of explosion (if 0, explosion will not be visible) 7: Inner radius to apply damage (if 0, explosion will not be visible) 8: Outer radius to apply damage (if 0, explosion will not be visible) 9: Shockwave speed (if 0, there will be no shockwave) 10: Fireball Type (unique ID of a fireball entry, OR a number: 0 = medium explosion [default, 1st in table], 1 = large explosion 1 [4th in table], 2 = large explosion 2 [5th in table], 3 or greater the respective entry in fireball.tbl) 11: Sound (index into sounds.tbl or name of the sound entry) 12: EMP intensity (optional) 13: EMP duration in seconds (optional) 14: Whether to use the full EMP time for capship turrets (optional, defaults to false)
warp-effect
warp-effect Causes a subspace warp effect at a given origin, facing toward a given location, with the given parameters. Takes 12 to 14 arguments... 1: Origin X 2: Origin Y 3: Origin Z 4: Location X 5: Location Y 6: Location Z 7: Radius 8: Duration in seconds (values smaller than 4 are ignored) 9: Warp opening sound (index into sounds.tbl or name of the sound entry) 10: Warp closing sound (index into sounds.tbl or name of the sound entry) 11: Fireball Type (unique ID of a fireball entry, OR a number: 0 for standard blue [default], 1 for Knossos green, 2 or greater the respective entry in fireball.tbl) 12: Shape (0 for 2-D [default], 1 for 3-D) 13: Duration of the opening effect, in milliseconds (and also the closing effect if the next argument is not specified) 14: Duration of the closing effect, in milliseconds
remove-weapons
remove-weapons Removes all live weapons currently in the game 1: (Optional) Remove only this specific weapon
set-time-compression
set-time-compression Sets the time compression and prevents it from being changed by the user. Takes 1 to 3 arguments... 1: New time compression (% of 1x) 2: Time in ms for change to take 3: Time compression to start from
reset-time-compression
reset-time-compression Resets the time compression - that is to say, time compression is set back to 1x, and the time compression controls are unlocked. Always call this when done with set-time-compression.
call-ssm-strike
call-ssm-strike Calls a subspace missile strike on the specified ship. Requires a ssm table (ssm.tbl). Takes 3 arguments... 1: Strike name. 2: Calling team. Rest: List of ships the strike will be called on.
Variables
get-variable-by-index
get-variable-by-index (originally variable-array-get) Gets the value of the variable specified by the given index. This is an alternate way to access variables rather than by their names, and it enables cool features such as arrays and pointers. Please note that only numeric variables are supported. Any attempt to access a string variable will result in a value of SEXP_NAN_FOREVER being returned. Takes 1 argument... 1: Index of variable, from 0 to MAX_SEXP_VARIABLES - 1.
set-variable-by-index
set-variable-by-index (originally variable-array-set) Sets the value of the variable specified by the given index. This is an alternate way to modify variables rather than by their names, and it enables cool features such as arrays and pointers. In contrast to get-variable-by-index, note that this sexp *does* allow the modification of string variables. Takes 2 arguments... 1: Index of variable, from 0 to MAX_SEXP_VARIABLES - 1. 2: Value to be set.
copy-variable-from-index
copy-variable-from-index Retrieves the value of the variable specified by the given index and stores it in another variable. This is very similar to get-variable-by-index, except the result is stored in a new variable rather than being returned by value. One important difference is that this sexp can be used to copy string variables as well as numeric variables. Takes 2 arguments... 1: Index of source variable, from 0 to MAX_SEXP_VARIABLES - 1. 2: Destination variable. The type of this variable must match the type of the variable referenced by the index.
copy-variable-between-indexes
copy-variable-between-indexes Retrieves the value of the variable specified by the first index and stores it in the variable specified by the second index. The first variable is not modified. Takes 2 arguments... 1: Index of source variable, from 0 to MAX_SEXP_VARIABLES - 1. 2: Index of destination variable, from 0 to MAX_SEXP_VARIABLES - 1. The types of both variables must match.
int-to-string
int-to-string Converts an integer into a string. The destination must be a string variable. Takes 2 argument... 1: Integer to convert 2: String variable to contain the result
string-concatenate
string-concatenate (deprecated in favor of string-concatenate-block) Concatenates two strings, putting the result into a string variable. If the length of the string will exceed the sexp variable token limit (currently 32), it will be truncated. Takes 3 arguments... 1: First string 2: Second string 3: String variable to hold the result
string-concatenate-block
string-concatenate-block Concatenates two or more strings, putting the result into a string variable. If the length of the string will exceed the sexp variable token limit (currently 32), it will be truncated. Takes 3 or more arguments... 1: String variable to hold the result Rest: Strings to concatenate. At least two of these are required; the rest are optional.
string-get-substring
string-get-substring Extracts a substring from a parent string, putting the result into a string variable. If the length of the string will exceed the sexp variable token limit (currently 32), it will be truncated. Takes 3 arguments... 1: Parent string 2: Index at which the substring begins (0-based) 3: Length of the substring 4: String variable to hold the result
string-set-substring
string-set-substring Replaces a substring from a parent string with a new string, putting the result into a string variable. If the length of the string will exceed the sexp variable token limit (currently 32), it will be truncated. Takes 3 arguments... 1: Parent string 2: Index at which the substring begins (0-based) 3: Length of the substring 4: New substring (which can be a different length than the old substring) 5: String variable to hold the result
modify-variable-xstr
modify-variable-xstr Sets a variable to a localized string. Takes 3 arguments... 1: Name of Variable. 2: The default text if no localized version is available. 3: The XSTR index. If set to -1 then the default value will be used
Other
Conditionals
when-argument
When-argument (Conditional operator) Performs specified actions when a condition, given a set of arguments, becomes true. Takes 3 or more arguments... 1: The arguments to evaluate (see any-of, every-of, random-of, etc.). 2: Boolean expression that must be true for actions to take place. Rest: Actions to take when the boolean expression becomes true.
every-time
Every-time (Conditional operator) This is a version of "when" that will always evaluate its arguments. It's useful in situations where you need to repeatedly check things that may become true more than once. Since this sexp will execute every time it's evaluated, you may need to use it as an argument to "when" if you want to impose restrictions on how it's called. Takes 2 or more arguments... 1: Boolean expression that must be true for actions to take place. Rest: Actions to take when boolean expression is true.
every-time-argument
Every-time-argument (Conditional operator) This is a version of "when-argument" that will always evaluate its arguments. It's useful in situations where you need to repeatedly check things that may become true more than once. Since this sexp will execute every time it's evaluated, you may need to use it as an argument to "when" (not "when-argument") if you want to impose restrictions on how it's called. Takes 3 or more arguments... 1: The arguments to evaluate (see any-of, all-of, random-of, etc.). 2: Boolean expression that must be true for actions to take place. Rest: Actions to take when the boolean expression becomes true.
if-then-else
If-then-else (Conditional operator) Performs one action if a condition is true (like "when"), or another action (or set of actions) if the condition is false. Note that this sexp only completes one of its branches once the condition has been determined; it does not come back later and evaluate the other branch if the condition happens to switch truth values. Takes 3 or more arguments... 1: Boolean expression to evaluate. 2: Actions to take if that expression becomes true. Rest: Actions to take if that expression becomes false.
functional-if-then-else
Functional If-then-else (Conditional operator) Returns the first number if the condition is true, and the second number otherwise. This sexp is very similar to the ?: ternary operator in C and other programming languages. Unfortunately, due to limitations of the sexp system, it is not possible to create an equivalent sexp for string values. Takes exactly 3 arguments... 1: Boolean expression to evaluate. 2: Number to return if the expression is currently true. 3: Number to return if the expression is not currently true..
any-of
Any-of (Conditional operator) Supplies arguments for the <argument> special data item. Any of the supplied arguments can satisfy the expression(s) in which <argument> is used. In practice, this will behave like a standard "for-each" statement, evaluating the action operators for each argument that satisfies the condition. Takes 1 or more arguments... All: Anything that could be used in place of <argument>.
every-of
Every-of (Conditional operator) Supplies arguments for the <argument> special data item. Every one of the supplied arguments will be evaluated to satisfy the expression(s) in which <argument> is used. Takes 1 or more arguments... All: Anything that could be used in place of <argument>.
random-of
Random-of (Conditional operator) Supplies arguments for the <argument> special data item. A random supplied argument will be selected to satisfy the expression(s) in which <argument> is used. The same argument will be returned by all subsequent calls Takes 1 or more arguments... All: Anything that could be used in place of <argument>.
random-multiple-of
Random-multiple-of (Conditional operator) Supplies arguments for the <argument> special data item. A random supplied argument will be selected to satisfy the expression(s) in which <argument> is used. Takes 1 or more arguments... All: Anything that could be used in place of <argument>.
number-of
Number-of (Conditional operator) Supplies arguments for the <argument> special data item. Any [number] of the supplied arguments can satisfy the expression(s) in which <argument> is used. Takes 2 or more arguments... 1: Number of arguments, as above Rest: Anything that could be used in place of <argument>.
for-counter
For-Counter (Conditional operator) Supplies counter values for the <argument> special data item. This sexp will count up from the start value to the stop value, and each value will be provided as an argument to the action operators. The default increment is 1, but if the optional increment parameter is provided, the counter will increment by that number. The stop value will be supplied if appropriate; e.g. counting from 0 to 10 by 2 will supply 0, 2, 4, 6, 8, and 10; but counting by 3 will supply 0, 3, 6, and 9. Note that the counter values are all treated as valid arguments, and it is impossible to invalidate a counter argument. If you want to invalidate a counter value, use Any-of and list the values explicitly. This sexp will usually need to be accompanied by the string-to-int sexp, as the counter variables are provided in string format but are most useful in integer format. Takes 2 or 3 arguments... 1: Counter start value 2: Counter stop value 3: Counter increment (optional)
invalidate-argument
Invalidate-argument (Conditional operator) Removes an argument from future consideration as a <argument> special data item. Takes 1 or more arguments... All: The argument to remove from the preceding argument list.
invalidate-all-arguments
Invalidate-all-arguments (Conditional operator) Removes all argument from future consideration as <argument> special data items. Takes no arguments.
validate-argument
Validate-argument (Conditional operator) Restores an argument for future consideration as a <argument> special data item. If the argument hasn't been previously invalidated, it will do nothing. Takes 1 or more arguments... All: The argument to restore to the preceding argument list.
validate-all-arguments
Validate-all-arguments (Conditional operator) Restores all arguments for future consideration as <argument> special data items. If the argument hasn't been previously invalidated, it will do nothing. Takes no arguments.
do-for-valid-arguments
Do-for-valid-arguments (Conditional operator) Performs specified actions once for each valid <argument> in the parent conditional. Must not be used for any SEXP that actually contains <argument> as these are already being executed multiple times without using Do-for-valid-arguments. Any use of <argument> and will prevent execution of the entire SEXP unless it is nested inside another when(or every-time)-argument SEXP. Takes 1 or more arguments... All: Actions to take.
num-valid-arguments
num-valid-arguments (Conditional operator) Returns the number of valid arguments in the argument list. Takes no arguments...
Ai goals
ai-chase-ship-class
Ai-chase ship class (Ship goal) Causes the specified ship to chase and attack the specified target ship class. Takes 2 or 3 arguments... 1: Name of ship class to chase. 2: Goal priority (number between 0 and 200. Player orders have a priority of 90-100). 3 (optional): Whether to attack the target even if it is on the same team; defaults to false.
ai-ignore-new
Ai-ignore-new (Ship goal) Tells the specified ship to ignore the given ship and not consider it as a valid target to attack. Takes 2 arguments... 1: Name of ship to ignore. 2: Goal priority (number between 0 and 89).
ai-play-dead-persistent
Ai-play-dead-persistent (Ship goal) Causes the specified ship to pretend that it is dead and not do anything. This goal behaves exactly like ai-play-dead, with the important difference that the ship will not immediately come back to life whenever it is given an order or a new goal of any priority. The only ways this goal can be removed are via remove-goal, clear-goals, or a new goal of a *higher* priority. Takes 1 argument... 1: Goal priority (number between 0 and 89).
ai-form-on-wing
Ai-form-on-wing (Ship Goal) Causes the ship to form on the specified ship's wing. This works analogous to the player order, and will cause all other goals specified for the ship to be purged. Takes 1 argument... 1: Ship to form on.
Event/Goals
is-event-true-msecs-delay
Mission Event True (Boolean operator) Returns true N milliseconds after the specified event in the this mission is true (or succeeded). It returns false otherwise. Returns a boolean value. Takes 2 required arguments and 1 optional argument... 1: Name of the event in the mission. 2: Number of milliseconds to delay before returning true. 3: (Optional) Defaults to False. When set to false, directives will only appear as soon as the specified event is true. When set to true, the event only affects whether the directive succeeds/fails, and has no effect on when it appears
is-event-false-msecs-delay
Mission Event False (Boolean operator) Returns true N milliseconds after the specified event in the this mission is false (or failed). It returns false otherwise. Returns a boolean value. Takes 2 required arguments and 1 optional argument... 1: Name of the event in the mission. 2: Number of milliseconds to delay before returning true. 3: (Optional) Defaults to False. When set to false, directives will only appear as soon as the specified event is true. When set to true, the event only affects whether the directive succeeds/fails, and has no effect on when it appears
Training
query-orders
Query-Orders (Boolean training operator) Becomes true when the player had given the specified ship or wing the specified order. Returns a boolean value. Takes 2 or more arguments... 1: Name of ship or wing to check if given order to. 2: Name of order to check if player has given. 3: Maximum length of time since order was given. Use 0 for any time in the mission. 4: Name of the target of the order (optional). 5: Name of player ship giving the order(optional). 6: Name of the subsystem for Destroy Subsystem orders.(optional)
reset-orders
Reset-Orders (Action training operator) Resets the list of orders the player has given. Takes no arguments.
primaries-depleted
primaries-depleted Returns true if ship is out of primary weapons 1: Ship name
ignore-key
ignore-key Causes the game to ignore (or stop ignoring) a certain key. Takes 2 or more arguments... 1: Number of times to ignore this key (-1 = forever, 0 = stop ignoring). Rest: Which key(s) to ignore.
node-targeted
Node-Targeted (Boolean training operator) Is true as long as the player has the specified jump node targeted, or has been targeted for the specified amount of time. Returns a boolean value. Takes 1 to 2 arguments (first required, rest optional): 1: Name of Jump Node to check if targeted by player. 2: Length of time target should have been kept for (optional).
missile-locked
Missile-locked (Boolean training operator) Is true as long as the player has had a missile lock for the specified amount of time. Optional arguments require lock to be maintained on a specified ship (or ship's subsystem). Returns a boolean value. Takes 1 to 3 arguments (first required, rest optional): 1: Length of time missile lock should have been kept for. 2: Name of ship to check if locked onto by player (optional). 3: Name of subsystem on ship to check if locked onto (optional).
