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. Nested "if/then/else/endif" clauses may also be included in the actions.

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

An example of a nested if statement:

testscript
if dockedAtMainStation_bool = YES then
    debugMessage: Player is docked at the main station, now checking mission variable.
    if mission_started undefined then
        set: mission_started YES
        // you would probably put up a mission page here
    else
        // the mission has already been started, do some stuff here
    endif
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.

Each condition is terminated by the word "and" or "then" and each condition can be on a separate line, for example:

if mission_x = A and
   mission_y = B then
        // some actions here
endif

Actions

If all the conditions in an "if" statement are met then the actions bounded by the "then" and the "else" or "endif" statement are executed. If any of the conditions in an "if" statement are not met and there is an "else" clause then the actions between the "else" and "endif" statement are executed.

Each action takes one line, and if finished by the end-of-line character(s).

The first word on an action line specifies the action to be performed. Some actions do not require any parameters, so the action line is a single word - "debugOn" for example. If the action requires any parameters, they are specified after a ":". There are examples of this above - "set" and "debugMessage".

Any word in the set of parameters surrounded by square brakets is assumed to be either a variable or the name of a function. If the word starts with mission_, local_, or commander_ it is assumed to be a variable and the variable's value replaces the variable name and the square brackets before the action is executed. If the word ends with _string, _number, or _bool it is assumed to be a function and the function's return value replaces the variable name and the square brackets before the action is executed.