String expansion

Format

Oolite has a mechanism to replace text in strings by other text. At some places during script evaluation oolite searches for text between the square brackets []. If it finds this, it treats the text between the brackets as a kind of variable and tries to switch it, including the brackets fore the new text.

What is switched

If the text is a [mission_variable], a [local_variable] or a system variable like [shipsFound_number], the content is replaced by the content of that variable. If not it looks at the key's in the descriptions.plist. If it finds a match it uses one of the strings belonging to that key for switching. (Note that OXP-specific entries in descriptions.plist and missiontext.plist should have an OXP or creator-specific prefix to ensure uniqueness.)

If you use [0] till [32] the number is replaced by strings from the "System Descriptions" key of the descriptions.plist inside Oolite itself. [0] is the first set of 5 arrays, [1] the second and so on. This was not meant for OXP use but a few numbers are still suitable.

When are things switched

Oolite calls only at certain places the switching routine.

• The most often used place is in missiontext.plist. In every text line the text between brackets is replaced by a variable or a descriptions.plist entry.
• Inside a descriptions.plist entry you can also use brackets. This way you can get a recursive process. Look for example in the description.plist inside Oolite were it generates random names in a recursive way. (Recursion is limited to 32 times to prevent infinite looping.)
• During evaluation of a AI.plist it only uses the switching on the content of a "commsMessage".
• During evaluation of a script.plist all the lines in the DO or ELSE part of a condition statement are switched. For some reason nothing is switched in the CONDITIONS part of a command so you can not use anything in brackets there.

The way thing work means that you can create complicated structures. You can use for example:

addSystemShips: my_ship 1 0.[d100_number]

Oolite first offers above line to the replacement routine. That one replaces [d100_number] by a random number. e.g. 46. Than the routine returns:

addSystemShips: my_ship 1 0.46

This line will then be executed and the ship is placed at the calculated random position. You can also define a descriptions.plist entry of my_random_ship and define a list of several ships roles. When you then use:

addSystemShips: [my_random_ship] 1 0.[d100_number]

the system will randomly pick a ship from the list and replace the d100_number for a value and returns the expanded string. This will than be excecuted.