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 function name and the square brackets before the action is executed.

Some examples of actions with replacements:

// set the script local variable local_x to a number between 1 and 100
set: local_x [d100_number]

// then set the script local variable local_y to a number between 1 and 100
set: local_y [d100_number]

// and add local_x to it - notice local_y isn't in brackets because the first word has
// to be the name of the variable to be acted upon, not it's value
add: local_y [local_x]

// print a message to the log
debugMessage: Commander [commander_name] has [local_x] widgets and [local_y] twigs

Here is the longway.oxp script converted to oos format, with comments added:

// Giles Williams' LongWay mission converted to oos format
//
long_way_round

// This is a pretty fast way to ensure no unnecessary processing is performed.
// This single condition can avoid all the other conditions getting evaluated
// if the player isn't in galaxy 0
//
if galaxy_number equal 0 then

        // As above, this one condition can save evaluating the three enclosed conditions
        // while the player is in space.
        //
	if dockedAtMainStation_bool equal YES then

                // If the player docks at the main station at XXX then start the
                // mission. Doesn't seem to be a way to refuse to do the mission.
                //
		if mission_longwayround undefined and planet_number equal 3 then
			setMissionMusic: none
			setGuiToMissionScreen
			addMissionText: long_way_round_Biarge_briefing
			set: mission_longwayround STAGE1
			setMissionDescription: em1_short_desc1
		endif

                // If the player docks at the main station of YYY and they're doing
                // the longway mission then reward them for partially completing it and
                // send them on the next step.
                //
		if mission_longwayround equal STAGE1 and plaent_number equal 248 then
			setMissionMusic: none
			setGuiToMissionScreen
			addMissionText: long_way_round_Soladies_briefing
			awardCredits: 500
			set: mission_longwayround STAGE2
			setMissionDescription: em1_short_desc2
		endif

                // If the player docks at the main station of ZZZ and they're on the
                // 2nd step of the mission, mark it complete and reward the player again.
                //
		if mission_longwayround equal STAGE2 and planet_number equal 233 then
			setMissionMusic: none
			setMissionImage: loyalistflag.png
			setGuiToMissionScreen
			addMissionText: long_way_round_Qubeen_briefing
			awardCredits: 2000
			setMissionImage: none
			set: mission_longwayround MISSION_COMPLETE
			clearMissionDescription
		endif
	endif

        // If the player is on the second step of the mission and jumps in system ZZZ
        // to complete the mission, ambush them with a couple of rebel ships!
        //
	if mission_longwayround equal STAGE2 and
	   planet_number equal 233 and
	   status_string equal STATUS_EXITING_WITCHSPACE then
		addShips: rebel 2
	endif

        // Continually harass the player while they're in system ZZZ trying to finish
        // the mission.
        //
	if mission_longwayround equal STAGE2 and
	   status_string equal STATUS_IN_FLIGHT and
	   planet_number equal 233 and
	   scriptTimer_number lessthan 60 then
		checkForShips: rebel
		if shipsFound_number lessthan 5 and d100_number lessthan 50 then
			addShips: rebel 1
		endif
	endif
endif