Script.oos

script.oos Used by OXP's to check conditions and perform scripted actions accordingly.

The "oos" file format allows scripts to be written using a more BASIC-like syntax than the plist file format permits. Scripts in "oos" format have all the same features available as the plist scripts, except only one script per file can be defined.

If both script.plist and script.oos files exist in an OXP's Config directory, script.oos is loaded in preference to script.plist.

Structure

A script.oos file consists of the script name on the first non-comment, non-blank line, followed by one or more "if/then/else/endif" clauses.

Blank lines, leading and trailing whitespace, and lines starting with "//" are ignored.

The body of an "if/then" or "else" consists of one or more actions, one per line.

A trivial script is:

testscript
if dockedAtMainStation_bool = YES then
    debugMessage: Player is docked at the main station.
else
    debugMessage: Player is not docked at the main station.
endif

Specifying "if" conditions

An "if" statement must be followed by one or more conditions. If multiple conditions are required they must be separated by the keyword "and". There is no option for an "or".

Where multiple conditions are specified they must all be true for the actions following "then" to be executed.

If any of the conditions of an "if" are false and an "else" clause is present, the actions given in the "else" clause are executed.

The form of the conditions is the same as for conditions, except that <, >, and = are used in place of the words lessthan, greaterthan, and equal.

if X op Y [ and X op Y ] then
    actions
else
    actions
endif

Where:

• X is one of mission_var, local_var, function_string, function_number, function_bool
• op is one of <, =, >, undefined, oneof
• Y is one of function_string, function_number, function_bool, or a set of one or more words

If op is "<" or ">" then Y should only be a single value and both X and Y are converted to numbers and compared.

If op is "=" then a string comparison is performed between X and Y. This is the only valid value for op when X is a function_bool and in this case Y must be one of "YES" or "NO".

If op is "undefined" then X must be a mission_var or local_var and Y is ignored. The condition is true if the mission or local variable has not yet been defined, or false if it has.

If op is "oneof" then Y is considered to be a list of values separated by commas and the condition is true if X is equal to any one of them.

do

do consists of an array of actions (and further conditional statements if required), executed if the conditions are met.

Example:

<key>do</key>
<dict>
    <array>
        <string>addShips: asp-cloaked 1</string>
        <string>addShips: pirate 12</string>
    </array>
</dict>

else

else consists of an array of actions (and further conditional statements if required), executed if the conditions are NOT met.

Example:

<key>else</key>
<dict>
    <array>
        <string>addShips: super-pirate 1</string>
    </array>
</dict>