Difference between revisions of "Script.oos"
Eric Walch (talk | contribs) (script example from Oolite -> scripting page) |
Cholmondely (talk | contribs) m (Tagged as Legacy scripting) |
||
(One intermediate revision by one other user not shown) | |||
Line 187: | Line 187: | ||
</pre> |
</pre> |
||
− | [[Category:Oolite |
+ | [[Category:Oolite]] |
+ | [[Category:Oolite scripting]] [[Category:Legacy scripting]] |
Latest revision as of 10:45, 9 August 2021
script.oos Used by OXP's to check conditions and perform scripted actions accordingly.
- Due to lack of adaptation, OOS support was be removed in Oolite 1.70.
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.
This format cannot be used in other plist files such as planetinfo.plist. It can only be used to replace 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