String expansion - Revision history

Cholmondely: Added link to list of expansions in Missiontext.plist

2025-03-31T09:41:33Z

Added link to list of expansions in Missiontext.plist

Massively Locked: cleared up wording

2022-09-19T20:53:00Z

cleared up wording

Milo: corrected operator examples

2020-06-24T16:17:10Z

corrected operator examples

Milo: more detailed explanation of string expansion

2020-06-20T21:00:42Z

more detailed explanation of string expansion

Show changes

Cim: /* When are things switched */ Note correlation issues

2013-11-30T16:50:50Z

‎When are things switched: Note correlation issues

Svengali: changed links from Misc_plists to their redirects

2013-01-12T14:11:54Z

changed links from Misc_plists to their redirects

Ahruman: Language cleanup, uniqueness constraint note.

2007-10-23T07:02:48Z

Language cleanup, uniqueness constraint note.

Eric Walch: /* What is switched */

2007-10-04T12:20:54Z

‎What is switched

Eric Walch: /* When are things switched */

2007-09-27T21:38:38Z

‎When are things switched

Eric Walch: /* When are things switched */

2007-09-27T21:36:21Z

‎When are things switched

@@ Line 42: / Line 42: @@
 *#* As a last resort, Oolite attempts to expand a key by treating it as a legacy script query method and invoking it. Only [[whitelist.plist|whitelisted]] query_methods and query_method_aliases are permitted. Examples:  [systemGovernment_string] (a whitelisted query method), [fuelLevel_number] (a whitelisted query method) or [fuel_level_number] (a whitelisted alias for [fuelLevel_number])
 * If no suitable replacement is found, the text will be displayed unchanged and a warning will be logged.
 '''Operators:'''

@@ Line 64: / Line 64: @@
 *In [[Oolite_JavaScript_Reference:_Global#expandDescription|expandDescription]] and [[Oolite_JavaScript_Reference:_Global#expandMissionText|expandMissionText]].
-The way things work means that you can create complicated structures. You can use for example:
   addSystemShips: my_ship 1 0.[d100_number]
-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 ship roles. When you then use:
+You can also define a [[descriptions.plist]] entry of my_random_ship and define a list of several ship roles.  When you use:
   addSystemShips: [my_random_ship] 1 0.[d100_number]
-the system will randomly pick a ship from the list and replace the d100_number with a value and return the expanded string. This will than be executed.
+the system will randomly pick a ship from the list, replace [d100_number] with a value and return the expanded string.  This will then be executed.
 [[Category:Oolite scripting]]

@@ Line 46: / Line 46: @@
 If a vertical bar ('|') is found between square brackets, Oolite will interpret whatever is on the left side of the bar as the ''key'' and whatever is on the right side of the bar as an ''operator''. An ''operator'' tells Oolite to apply a change after the key has been expanded. Some operators also require an input value, a colon (':'). The available ''operators'' are:
-* dcr       - displays the text as a credit value, interpreting the value as floating point deci-credits (e.g., if the value is 100.7, display 10.7 credits)
+* cr        - displays the text as a credit value, interpreting the value as floating point credits (e.g., if the value is 1007.7, display 1007.7 ₢)
-* cr        - displays the text as a credit value, interpreting the value as floating point credits (e.g., if the value is 100.7, display 100.7 credits)
+* dcr       - displays the text as a credit value, interpreting the value as floating point deci-credits (e.g., if the value is 1007.7, display 100.7 ₢)
-* icr       - displays the text as a credit value, interpreting the value as integer credits (e.g., if the value is 100.7, display 100.0 credits)
+* icr       - displays the text as a credit value, interpreting the value as integer credits (e.g., if the value is 1007.7, display 1007 ₢)
-* idcr      - displays the text as a credit value, interpreting the value as integer deci-credits, rounded (e.g., if the value is 100.7, display 10.0 credits)
+* idcr      - displays the text as a credit value, interpreting the value as integer deci-credits, rounded (e.g., if the value is 1007.7, display 101 ₢)
 * precision - displays the text as a floating point value with an integer-specified number of decimal places, must be specified as ''precision'':number (e.g., [distance|precision:2])
 * multiply  - displays the text as a floating point value multiplied with another floating point value, which must be provided as ''multiply'':othervalue (e.g., [fuelLevel_number|multiply:0.5])

@@ Line 10: / Line 10: @@
 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.)
+*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.

@@ Line 3: / Line 3: @@
 == 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 [[misc plists|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 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.
@@ Line 9: / Line 9: @@
 == 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 [[misc plists|descriptions.plist]] entry.
+*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 [[misc plists|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.)
+*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.
@@ Line 21: / Line 21: @@
   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 [[misc plists|descriptions.plist]] entry of my_random_ship and define a list of several ships roles. When you then use:
+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.
 [[Category:Oolite scripting]]