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.). Because of the random number generator used for expansion the use of deep recursion may cause correlations which are not random - consider for example that "mud" is always followed by "tennis" or "hockey" in planetary descriptions, never anything else. In Oolite 1.79 certain ways of expanding descriptions from Javascript will use a higher quality random number generator which does not have correlation problems.
• 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.