Road-hog123

OMSI Scripting Language

OMSI uses a proprietary scripting system with some quite unique language features...

One and two you must add together

Although you won't know it by name, you should be familiar with Infix Notation, e.g. 1 + 2—the operator (the action being performed, in this case addition) is placed in between the operands (the values the action is being performed upon). OMSI's scripting system is most unusual its use of Postfix (or Reverse Polish) Notation, where the operator is placed after the operands: 1 2 +.

This notation is much easier to implement—infix notation has execution order rules that have to be applied to the whole statement in order for the execution to reach the correct result, e.g. 1 + 2 × 3 is 7; you have to write (1 + 2) × 3 to get 9. With postfix notation you simply write the order of execution: 1 2 + 3 ×.

The Stack

The script system needs some "working memory" in which to store the operands (and results of previous operators, which are likely to become operands) until the operator that needs them is read. This comes in the form of the stack, which is a data structure that can be interacted with in three ways:

  1. Look at the top stack value (peek)
  2. Remove the top stack value (pop)
  3. Put another value on top of the stack (push)

1 2 + 3 × is five instructions:

  1. Push 1 onto the stack
  2. Push 2 onto the stack
  3. Pop the top two stack values (1 and 2), add them together and push the result (3) onto the stack
  4. Push 3 onto the stack
  5. Pop the top two stack values (3 and 3), multiply them together and push the result (9) onto the stack

The stack can only hold 8 values—pushing a ninth value will result in the first value being lost forever—but if you're careful you can write a great many lines of code between where a value is pushed onto the stack and where it is next used, thereby creating highly unreadable code just like the founding fathers (Marcel & Rüdiger) intended.

Registers

Sometimes it is necessary to compute operands in a different order than an operator needs them, in which case some operands will need to be stored outside the stack and pushed back in the correct order.

For this purpose 10* "registers" are provided; you can save values with the commands s0–s9 (the saved value remains on the stack) and load them with l0–l9 (the saved value remains in the register).

  1. The official wiki does not document 8 & 9, but I have not personally noticed issues when using them.

These registers can of course be used for any purpose for which temporary variables are useful.

Boolean and String Values

All numerical values are single-precision (32-bit) signed floats, because OMSI is a 32-bit application. For boolean inputs OMSI treats zero as false and any non-zero value as true, but boolean outputs will always be 0 or 1.

Strings have their own independent stack (holds 8 strings), but no registers. Raw string values like "example" are surrounded by double quotes.

Operators can read/write to/from either or both stacks.

Operators

For the purpose of these descriptions the operands are abbreviated f0–f7 for the float stack and $0–$7 for the string stack, and are consumed unless otherwise noted. Because the stacks are independent, string operands can come before, after or intermingled amongst float operands.

Stack Operators

f0 d
Peek f0 and push the same value, duplicating it.
$0 $d
Peek $0 and push the same value, duplicating it.

Logical Operators

f1 f0 &&
0 if either f0 or f1 are 0, 1 otherwise (AND).
f1 f0 ||
0 if both f0 and f1 are 0, 1 otherwise (OR).
f0 !
1 if f0 is 0, 0 otherwise (NOT).

Comparison Operators

f1 f0 =
1 if f0 and f1 are identical, otherwise 0. Due to float precision loss this can be unexpectedly false.
f1 f0 <
1 if f1 < f0, 0 otherwise.
f1 f0 >
1 if f1 > f0, 0 otherwise.
f1 f0 <=
1 if f1 <= f0, 0 otherwise.
f1 f0 >=
1 if f1 >= f0, 0 otherwise.
$1 $0 $=
1 if $0 and $1 are identical, otherwise 0.
$1 $0 <
1 if $1 is alphabetically before $0 (like a dictionary), 0 otherwise.
$1 $0 >
1 if $1 is alphabetically after $0, 0 otherwise.
$1 $0 <=
1 if $1 is alphabetically before or identical to $0, 0 otherwise.
$1 $0 >=
1 i$ $1 is alphabetically after or identical to $0, 0 otherwise.

Mathematical Operators

f1 f0 +
Addition, f1 + f0.
f1 f0 -
Subtraction, f1 - f0.
f1 f0 *
Multiplication, f1 × f0.
f1 f0 /
Division, f1 ÷ f0. Notably if f0 is zero this returns zero, not infinity.
f1 f0 %
Remainder of division, equivalent to writing f0 - trunc(f1 / f0) * f1.
f0 /-/
Invert the sign, equivalent to multiplying by -1.
f0 sin
Sine of angle f0 (in degrees, °).
f0 arcsin
Arcsine of f0 (in degrees, °).
Added in version 2.00.
f0 arctan
Arctangent of f0 (in degrees, °).
Added in version 2.00.
f1 f0 min
Return the smaller of f1 or f0.
f1 f0 max
Return the larger of f1 or f0.
f0 exp
Raise e to the power f0 (ef0).
f0 sqr
Find the square of f0 (f02).
f0 sqrt
Find the square root of f0 (f0-2).
f0 sgn
Return the sign of f0 (-1, 0 or 1).
pi
Return pi.
f0 random
Generate a pseudo-random integer between 0 (inclusive) and f0 (exclusive) (0 <= x < f0).
f0 abs
Absolute value of f0, i.e. ignore f0's sign and make it positive.
f0 trunc
Truncate f0, removing the decimal part (making it an integer) and rounding it towards zero.

String Operators

$1 $0 $+
Concatenate (join) $1 and $0, e.g. "Omnibus" "simulator" $+ returns "Omnibussimulator".
$0 f0 $*
Repeat $0 until it would be longer than f0 characters, e.g. "ab" 7 $* returns "ababab".
$0 $length
Return the length of $0 in characters to the float stack.
$0 f0 $cutBegin
Return $0 with f0 characters removed from the beginning.
$0 f0 $cutEnd
Return $0 with f0 characters removed from the end.
$0 f0 $SetLengthL
Return $0 with characters removed from, or spaces added to, the end to make it f0 characters in length.
f0 is not consumed!
$0 f0 $SetLengthR
Return $0 with characters removed from, or spaces added to, the beginning to make it f0 characters in length.
f0 is not consumed!
$0 f0 $SetLengthC
Return $0 with characters removed from, or spaces added to both ends, to make it f0 characters in length.
f0 is not consumed!
Added in version 2.00.
f0 $IntToStr
Returns a string representation of f0 after it has been truncated.
f0 $0 $IntToStrEnh
Returns a string representation of f0 after it has been truncated, but $0 is a formatting string: the first character is used as a padding character, subsequent characters are the length of the returned string.
35 " 5" $IntToStrEnh returns " 35"; 123456789 "011" $IntToStrEnh returns "00123456789". "ERROR" is returned on failure.
$0 $StrToFloat
Tries to interpret $0 as a decimal number, returning -1 on failure.
$0 $RemoveSpaces
Returns $0 with leading and trailing space characters removed.
Added in version 2.00.

Files and Telling OMSI to Load Them

The actual script code is in *.osc files which are loaded using the [script] keyword. Variables

Entrypoints

{init}

When the asset is first loaded, OMSI runs the initialisation