Changes for page Mission Director Guide
Last modified by Klaus Meyer on 2025/03/31 16:39
From version 32940.1
edited by Daniel Turner
on 2023/08/22 16:50
on 2023/08/22 16:50
Change comment:
There is no comment for this version
To version 32946.1
edited by Daniel Turner
on 2023/08/22 18:43
on 2023/08/22 18:43
Change comment:
There is no comment for this version
Summary
-
Page properties (3 modified, 0 added, 0 removed)
Details
- Page properties
-
- Title
-
... ... @@ -1,1 +1,1 @@ 1 - X4:X4 Documentation/X4 Game Design/0 General/Mission Director Guide1 +Mission Director Guide - Parent
-
... ... @@ -1,0 +1,1 @@ 1 +X Rebirth Wiki.Modding support.WebHome - Content
-
... ... @@ -1,6 +1,6 @@ 1 1 The Mission Director (MD) is a subsystem of the game and interprets mission scripts, which are written in an XML-based language. The Mission Director in X Rebirth and X4 is based on the MD in X3: Terran Conflict, with some major changes based on feedback from MD users.\\ 2 2 3 -An introduction to the original MD can be found in the[[ ┬á(%style="color: rgb(0,0,153);text-decoration: underline;" %)Egosoft forums>>url:http://forum.egosoft.com/viewtopic.php?t=196971]](%%). There is also a PDF guide for the X3 Mission Director, which is partially used as a template for this document.3 +An introduction to the original MD can be found in the[[(% &text-decoration: underline;" %)Egosoft forums>>url:http://forum.egosoft.com/viewtopic.php?t=196971]](%%). There is also a PDF guide for the X3 Mission Director, which is partially used as a template for this document. 4 4 5 5 This document is primarily supposed to be a guide for MD users (people who use the MD to develop missions or write other MD scripts), not for MD programmers (people who work on the MD engine in C++). 6 6 ... ... @@ -14,9 +14,9 @@ 14 14 15 15 MD scripts are not necessarily missions. An MD file can contain a part of a mission, multiple missions, or no mission at all, as the MD is used for more than just missions. 16 16 17 -MD files are XML files located in the game folder {{code}}md{{/code}}. All XML files in that folder are loaded at game start. The file names are irrelevant, since the internally used script names are read from the XML root nodes. However, it ΓÇÖs recommended to keep file name and internal script name identical to avoid having to look up the names.17 +MD files are XML files located in the game folder {{code}}md{{/code}}. All XML files in that folder are loaded at game start. The file names are irrelevant, since the internally used script names are read from the XML root nodes. However, it's recommended to keep file name and internal script name identical to avoid having to look up the names. 18 18 19 -To edit MD scripts, an XML editing tool is needed. Microsoft Visual Studio (if available) or [[(% style="color: rgb(0,0,153);text-decoration: underline;" %)Microsoft Visual Web Developer>>url:http://www.microsoft.com/express/vwd/]](%%) (for free) are highly recommended because they have pretty good support for XML schemas (XSD). The provided Mission Director schema files help you create the XML file by displaying all available tags and attributes as you edit the XML.19 +To edit MD scripts, an XML editing tool is needed. Microsoft Visual Studio (if available) or [[(% &text-decoration: underline;" %)Microsoft Visual Web Developer>>url:http://www.microsoft.com/express/vwd/]](%%) (for free) are highly recommended because they have pretty good support for XML schemas (XSD). The provided Mission Director schema files help you create the XML file by displaying all available tags and attributes as you edit the XML. 20 20 21 21 This functionality is only available if the schema files **md.xsd** and **common.xsd** are in the correct folder. If you are editing the XML in the game folder directly, all is well and the files are loaded from the libraries folder. However, if you are editing in a separate folder, copy those XSD files from the libraries folder directly into the folder where your XML files are located. 22 22 ... ... @@ -46,7 +46,7 @@ 46 46 47 47 In this section we will look at how to start the whole process by creating a new MD mission file and the basic steps in producing mission content with XML code. There will be a description of the key elements of the mission file. 48 48 49 -The XML root node of an MD file is called ΓÇ£mdscriptΓÇ¥and looks like this:49 +The XML root node of an MD file is called "mdscript" and looks like this: 50 50 51 51 {{code language="xml"}} 52 52 <?xml version="1.0" encoding="utf-8"?> ... ... @@ -53,7 +53,7 @@ 53 53 <mdscript name="ScriptName" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="md.xsd"> 54 54 {{/code}} 55 55 56 - ΓÇ£ScriptNameΓÇ¥is the name used for this script regardless of the file name. It **has to start with an upper case letter and must be unique** among all MD script names. It also should not contain spaces, so other MD scripts can use it as an identifier to access this scriptΓÇÖs contents easily.56 +"ScriptName" is the name used for this script regardless of the file name. It **has to start with an upper case letter and must be unique** among all MD script names. It also should not contain spaces, so other MD scripts can use it as an identifier to access this script's contents easily. 57 57 58 58 The only allowed sub-node of <mdscript> is <cues>, which can only contain <cue> sub-nodes: 59 59 ... ... @@ -86,7 +86,7 @@ 86 86 87 87 \\ 88 88 89 -{{no te body="There can be a delay between the activation and performing the actions if the<delay>tag is used. In this case, sub-cues will be enter the waiting state before the parent's actions are performed.<br/>"/}}89 +{{info}}There can be a delay between the activation and performing the actions if the <delay> tag is used. In this case, sub-cues will be enter the waiting state before the parent's actions are performed.{{/info}} 90 90 91 91 This is how a cue node looks like: 92 92 ... ... @@ -110,7 +110,7 @@ 110 110 111 111 **Non-event conditions** are checked either once or repeatedly in a fixed interval. They may be based on simple values or ranges, such as a particular in-game time having been reached or the player having a certain amount of money. They may also be based on more complex player information, such as what ships they own, whether the player is in a particular area or near a particular object. 112 112 113 -**Event conditions** are triggered when the corresponding event happens, such as the event that a particular object has been targeted, attacked or destroyed. All event nodes have the prefix ΓÇ£event_ΓÇ¥so you can easily determine a condition type. After an event condition you can specify one or more non-event conditions, which will be checked additionally whenever the event happens. If a condition uses an event, it must be in the first sub-node of the <conditions> node. It is even possible to define multiple alternative events that should activate the cue. The first sub-node should be <check_any> in this case, so only one of its sub-conditions has to be met.113 +**Event conditions** are triggered when the corresponding event happens, such as the event that a particular object has been targeted, attacked or destroyed. All event nodes have the prefix "event_" so you can easily determine a condition type. After an event condition you can specify one or more non-event conditions, which will be checked additionally whenever the event happens. If a condition uses an event, it must be in the first sub-node of the <conditions> node. It is even possible to define multiple alternative events that should activate the cue. The first sub-node should be <check_any> in this case, so only one of its sub-conditions has to be met. 114 114 115 115 Example for an event condition: 116 116 ... ... @@ -150,11 +150,11 @@ 150 150 151 151 If a cue has a <conditions> node without any event, it must have one of the attributes //**onfail**// or //**checkinterval**//. 152 152 153 -* Use //onfail// if the conditions should be checked only once. The possible attribute values are ΓÇ£//cancel//ΓÇ¥andΓÇ£//complete//ΓÇ¥. If the conditions are met, the cue will activate and perform the cue actions. Otherwise it's a failure and the cue will be cancelled or completed, based on the onfail attribute. Typically //onfail="cancel"// is used to prevent any further action. //onfail="complete"// can be used to continue with the sub-cues even in case of failure (but skipping the current cue actions).\\153 +* Use //onfail// if the conditions should be checked only once. The possible attribute values are "//cancel//" and "//complete//". If the conditions are met, the cue will activate and perform the cue actions. Otherwise it's a failure and the cue will be cancelled or completed, based on the onfail attribute. Typically //onfail="cancel"// is used to prevent any further action. //onfail="complete"// can be used to continue with the sub-cues even in case of failure (but skipping the current cue actions).\\ 154 154 155 155 156 156 157 -* With //checkinterval//, you can specify a constant time interval between condition checks. The conditions will be checked regularly forever until they are met, unless the cue ΓÇÖs state is changed explicitly by an external event.157 +* With //checkinterval//, you can specify a constant time interval between condition checks. The conditions will be checked regularly forever until they are met, unless the cue's state is changed explicitly by an external event. 158 158 159 159 Additionally, you can use the attribute **checktime** to set the time of the first condition check (also possible in combination with //onfail//). The //checktime// can be an expression with variables and is evaluated when the cue is enabled (when the condition checks would normally start ΓÇô for root cues that happens at game start, otherwise after the parent cue becomes active). 160 160 ... ... @@ -182,7 +182,7 @@ 182 182 183 183 184 184 185 -{{no te body="Reminder: When using an XSD-capable editor, it's a great help, but you cannot rely on that alone to verify correctness. Please also check the documentation and look for errors in the game debug output. Concretely, the schema cannot tell whether the above cue attributes are used correctly."/}}185 +{{info}}Reminder: When using an XSD-capable editor, it's a great help, but you cannot rely on that alone to verify correctness. Please also check the documentation and look for errors in the game debug output. Concretely, the schema cannot tell whether the above cue attributes are used correctly.{{/info}} 186 186 187 187 == Actions == 188 188 ... ... @@ -198,7 +198,7 @@ 198 198 <event_cue_completed cue="parent"/> 199 199 {{/code}} 200 200 201 -<actions> is optional. Leaving it out may be useful if you only want to enable sub-cues after the cue ΓÇÖs condition check. The state transition from active to complete will still take the <delay> node into account.201 +<actions> is optional. Leaving it out may be useful if you only want to enable sub-cues after the cue's condition check. The state transition from active to complete will still take the <delay> node into account. 202 202 203 203 Note that the MD script language is not designed as a programming language. The actions are performed in sequence, although they can be nested to form more complex structures. Loops and conditionals exist to some extent, but not necessarily in the sense that a programmer might expect. Analogously to <check_all> and <check_any>, you can use **<do_all>** to perform all the contained sub-node actions, and **<do_any>** to perform only one of them. <do_all> is particularly useful when nested in a <do_any>. 204 204 ... ... @@ -216,7 +216,7 @@ 216 216 217 217 218 218 219 -{{no te body="Messages printed with<debug_text>are usually only visible when theΓÇ£scriptsΓÇ¥debug filter is enabled, see[[NULL|Script debug output]]."/}}219 +{{info}}Messages printed with <debug_text> are usually only visible when the "scripts" debug filter is enabled, see Script debug output{{/info}} 220 220 221 221 222 222 ... ... @@ -232,7 +232,7 @@ 232 232 233 233 Libraries are cues which are not created directly but only serve as templates for other cues. This allows for modularisation, so you can re-use library cues in many different missions. 234 234 235 -{{no te body="<span style=~"color: rgb(0,0,0);~">The syntax of libraries is considerably different from the syntax in the MD of X3TC."/}}235 +{{info}}The syntax of libraries is considerably different from the syntax in the MD of X3TC.{{/info}} 236 236 237 237 238 238 ... ... @@ -245,7 +245,7 @@ 245 245 </library> 246 246 {{/code}} 247 247 248 -Although it is called library, it ΓÇÖs basically just a cue that doesnΓÇÖt do anything. You can mix cues and libraries as you want, as root cues or sub-cues - the location within the file is unimportant. All that counts is the library name, which has to be unique within the MD script, like all other cue names.248 +Although it is called library, it's basically just a cue that doesn't do anything. You can mix cues and libraries as you want, as root cues or sub-cues - the location within the file is unimportant. All that counts is the library name, which has to be unique within the MD script, like all other cue names. 249 249 250 250 To use a library, use the attribute ref: 251 251 ... ... @@ -286,13 +286,12 @@ 286 286 {{/code}} 287 287 288 288 289 +{{warning}}These examples are definitely <u>not</u> examples of good scripting style.{{/warning}} 289 289 290 -{{warning body="These examples are definitely <u>not</u> examples of good scripting style."/}} 291 291 292 292 293 +So when writing the library, you don't have to worry about name confusion, just use the names of cues in your library and it will work as expected when the library is used. Names of cues that do not belong to the library will not be available in expressions (see Foo in the example above), however, names of other libraries in the file are available when referencing them in the ref attribute. 293 293 294 -So when writing the library, you donΓÇÖt have to worry about name confusion, just use the names of cues in your library and it will work as expected when the library is used. Names of cues that do not belong to the library will not be available in expressions (see Foo in the example above), however, names of other libraries in the file are available when referencing them in the ref attribute. 295 - 296 296 Notes: 297 297 298 298 * It is //not// possible to directly call a cue which is 'inside' the library from 'outside' of the library, but it is possible to signal the library ref itself (possibly with parameters) and have a sub-cue inside the library listen to the signal on the library ref (possibly checking the parameters). ... ... @@ -316,7 +316,7 @@ 316 316 </library> 317 317 {{/code}} 318 318 319 -If a default value is supplied, the parameter is regarded as optional, otherwise it ΓÇÖs required. When providing the actual parameters in a referencing cue, note that there is no <params> node:318 +If a default value is supplied, the parameter is regarded as optional, otherwise it's required. When providing the actual parameters in a referencing cue, note that there is no <params> node: 320 320 321 321 {{code language="xml"}} 322 322 <cue name="Foo" ref="Lib"> ... ... @@ -325,7 +325,7 @@ 325 325 </cue> 326 326 {{/code}} 327 327 328 -The values (including default values) can be variable expressions and will be evaluated when the cue is enabled, i.e. when it starts checking the conditions. They will be available to the cue as variables, using the parameter name with a ΓÇÿ$ ΓÇÖprefix. In the example above, the variables $foo, $bar, and $baz would be created.327 +The values (including default values) can be variable expressions and will be evaluated when the cue is enabled, i.e. when it starts checking the conditions. They will be available to the cue as variables, using the parameter name with a ΓÇÿ$' prefix. In the example above, the variables $foo, $bar, and $baz would be created. 329 329 330 330 {{code language="xml"}} 331 331 <library name="Lib"> ... ... @@ -342,27 +342,27 @@ 342 342 343 343 = Instantiation = 344 344 345 -One of the possible cue attributes is //**instantiate**//. If you set it to true, this changes what happens when a cue's conditions are met. Normally, if a cue is (% style="color: rgb(0,0,0);text-decoration: underline;" %)not instantiated, the cue's actions are run (taking a delay node into account) and the cue is marked as completed. But with **instantiate'//, a// **copy of the cue** (and all its sub-cues) is made when the conditions are met, and it is this copy in which the actions are performed and it is the copy whose status is set to complete when they are finished - this means that the original cue (the so-called **static cue**) remains in the //waiting// state, and if the conditions are met again then the whole thing happens all over again.**346 -\\An instantiating cue should only be used with conditions that are only going to be met once (or a fairly limited number of times), or with conditions that include an event condition. Instantiation should (% style="color: rgb(0,0,0);text-decoration: underline;" %)not be used in a cue which, say, just depends on the game time being greater than a specific value as this will result in a copy of the cue being made after each check interval, which could increase memory usage a lot. The most common use of an instantiated cue is in responding to events such as the player ship changing sector, to react every time that event happens.344 +One of the possible cue attributes is //**instantiate**//. If you set it to true, this changes what happens when a cue's conditions are met. Normally, if a cue is not instantiated, the cue's actions are run (taking a delay node into account) and the cue is marked as completed. But with **instantiate'//, a// **copy of the cue** (and all its sub-cues) is made when the conditions are met, and it is this copy in which the actions are performed and it is the copy whose status is set to complete when they are finished - this means that the original cue (the so-called **static cue**) remains in the //waiting// state, and if the conditions are met again then the whole thing happens all over again.** 345 +\\An instantiating cue should only be used with conditions that are only going to be met once (or a fairly limited number of times), or with conditions that include an event condition. Instantiation should not be used in a cue which, say, just depends on the game time being greater than a specific value as this will result in a copy of the cue being made after each check interval, which could increase memory usage a lot. The most common use of an instantiated cue is in responding to events such as the player ship changing sector, to react every time that event happens. 347 347 \\Instances that are created via //instantiate// are called **instantiated cues**. But sub-cues of instances are also instances (**sub-instances**) - they are created when they enter the waiting state. An instance is removed again (thereby freeing its memory) when it is complete or cancelled, and when all its instance sub-cues have been removed before. The simplest case is an instantiating cue with no sub-cues: The instance is created, the actions are performed, and the instance is removed immediately on completion. A pitfall could be an instance with a sub-cue that is forever in the waiting state (e.g. waiting for an event from an already destroyed object). It can never be removed, so you should clean up such a cue yourself, e.g. by cancelling it explicitly. 348 348 349 349 == Cleaning up instances explicitly == 350 350 351 -Cancelling a cue with **<cancel_cue>** also cancels all its sub-cues, and cancelling a static cue stops it from instantiating more cues - but it does not cancel its instances. Resetting a cue with **<reset_cue>** resets both sub-cues and instantiated cues, but has the (desired) side effect that condition checks will start again if the parent cue ΓÇÖs state allows it. Even a sub-instance that has been reset can return to the //waiting// state. Resetting an instantiated cue will stop it forever, because it is not supposed to be in the //waiting// state (only its static cue is). Resetting will also induce the clean-up reliably, but keep in mind that this is not the case for instance sub-cues.350 +Cancelling a cue with **<cancel_cue>** also cancels all its sub-cues, and cancelling a static cue stops it from instantiating more cues - but it does not cancel its instances. Resetting a cue with **<reset_cue>** resets both sub-cues and instantiated cues, but has the (desired) side effect that condition checks will start again if the parent cue's state allows it. Even a sub-instance that has been reset can return to the //waiting// state. Resetting an instantiated cue will stop it forever, because it is not supposed to be in the //waiting// state (only its static cue is). Resetting will also induce the clean-up reliably, but keep in mind that this is not the case for instance sub-cues. 352 352 353 -{{info body=" <cancel_cue>and<reset_cue>only take effect after all remaining actions of the current cue are performed. So you can even safely cancel the cue that you are currently in (keywordΓÇ£'''this'''ΓÇ¥) or any ancestor cue, and still perform more actions afterwards."/}}352 +{{info body="<cancel_cue> and <reset_cue> only take effect after all remaining actions of the current cue are performed. So you can even safely cancel the cue that you are currently in (keyword "'''this'''") or any ancestor cue, and still perform more actions afterwards."/}} 354 354 355 355 == Access to instances == 356 356 357 357 358 358 359 -{{no te body="This sub-section requires basic knowledge of[[NULL|script expressions]]."/}}358 +{{info}}This sub-section requires basic knowledge of script expressions.{{/info}} 360 360 361 361 362 362 363 363 In case of instances with sub-instances, you will often want to access a related instance from the current one. Like in the non-instance case, you can simply write the cue name in an expression to reference that cue. However, you should be aware of the pitfalls that are accompanied by this. 364 364 365 -When you use a cue name from the same script in an expression, it will always be resolved to some cue - usually a static cue, even if it is still in the disabled state, but it can also be an instance, if it is ΓÇ£relatedΓÇ¥to the current one.364 +When you use a cue name from the same script in an expression, it will always be resolved to some cue - usually a static cue, even if it is still in the disabled state, but it can also be an instance, if it is "related" to the current one. 366 366 367 367 Related means that this cue and the referenced cue have a common ancestor instance, and the referenced cue is a direct (non-instantiated) descendant of that common ancestor. 368 368 ... ... @@ -375,11 +375,11 @@ 375 375 Example situations: 376 376 377 377 * In the static tree: Cue names in expressions are always resolved to the static cues. 378 -* In the inst-2 tree: ΓÇ£SubBarΓÇ¥in an expression will be resolved to SubBar (inst 2).379 -* In the inst-1 tree: ΓÇ£SubBarΓÇ¥in an expression will be resolved to SubBar (static) (!) because the SubBar child of Bar (inst 1) does not exist yet, or not any more.380 -* In the inst-2a tree: ΓÇ£SubBazΓÇ¥in an expression will be resolved to SubBaz (inst 2a)381 -* In the inst-2a tree: ΓÇ£BarΓÇ¥in an expression will be resolved to Bar (inst 2) because Foo (inst 2) is a common ancestor.382 -* In the inst-2 tree: ΓÇ£SubBazΓÇ¥in an expression will be resolved to SubBaz (static) (!) because SubBaz (inst 2a) is **not** a direct descendant of the common ancestor Foo (inst 2), instead Baz (inst 2a) has been instantiated.377 +* In the inst-2 tree: "SubBar" in an expression will be resolved to SubBar (inst 2). 378 +* In the inst-1 tree: "SubBar" in an expression will be resolved to SubBar (static) (!) because the SubBar child of Bar (inst 1) does not exist yet, or not any more. 379 +* In the inst-2a tree: "SubBaz" in an expression will be resolved to SubBaz (inst 2a) 380 +* In the inst-2a tree: "Bar" in an expression will be resolved to Bar (inst 2) because Foo (inst 2) is a common ancestor. 381 +* In the inst-2 tree: "SubBaz" in an expression will be resolved to SubBaz (static) (!) because SubBaz (inst 2a) is **not** a direct descendant of the common ancestor Foo (inst 2), instead Baz (inst 2a) has been instantiated. 383 383 384 384 In expressions, you can use the cue property **static** to access the static cue that instantiated a cue. This does not work for sub-cues of other cues, and the result is not necessarily a real static cue! In the example above, it would only work for cues with a dotted arrow pointing at them, and is resolved to the source of the arrow. In other cases the result is null. 385 385 ... ... @@ -395,12 +395,16 @@ 395 395 396 396 * **Conditions with results:** If the instantiating cue has conditions with results, those results are stored in variables - but in the variables of the static cue, not of the instance! So in the <actions> you have to access the variables via the **static **keyword:\\ 397 397 398 -{{code}}<debug_text┬átext="static.$foo"/>{{/code}}(% style="color: rgb(0,0,255);text-decoration: none;" %) 399 -\\It may even be necessary to copy the variables over to the instance because the static variables can be overwritten by the next condition check: 400 -\\{{code}}<set_value┬áname="$foo"┬áexact="static.$foo"/>{{/code}} 397 +{{code language="xml"}} 398 + <debug_text text="static.$foo"/> 399 +{{/code}} 400 +It may even be necessary to copy the variables over to the instance because the static variables can be overwritten by the next condition check: 401 +{{code language="xml"}} 402 +<set_value name="$foo" exact="static.$foo"/> 403 +{{/code}} 401 401 402 -* **Resetting completed/cancelled instances:** As explained above, sub-instances are only created when needed (when going to the //waiting// state) and are destroyed when they are not needed any more (when they are completed or cancelled, including all sub-cues). There are cases in which you want to access cues that don ΓÇÖt exist any more - it simply doesnΓÇÖt work. In some cases you are safe: You can be sure that all your ancestors exist, and instantiating cues wonΓÇÖt be removed until they are cancelled. In some other cases you simply donΓÇÖt know and have to check if the instance is already (or still) there.403 -* **Lifetime of instances:** Do not make assumptions about when an instance is removed! Just looking at it in the Debug Manager keeps it alive for the time being. So, sometimes you could still have a completed instance that wouldn ΓÇÖt exist under other circumstances.405 +* **Resetting completed/cancelled instances:** As explained above, sub-instances are only created when needed (when going to the //waiting// state) and are destroyed when they are not needed any more (when they are completed or cancelled, including all sub-cues). There are cases in which you want to access cues that don't exist any more - it simply doesn't work. In some cases you are safe: You can be sure that all your ancestors exist, and instantiating cues won't be removed until they are cancelled. In some other cases you simply don't know and have to check if the instance is already (or still) there. 406 +* **Lifetime of instances:** Do not make assumptions about when an instance is removed! Just looking at it in the Debug Manager keeps it alive for the time being. So, sometimes you could still have a completed instance that wouldn't exist under other circumstances. 404 404 405 405 = Expressions = 406 406 ... ... @@ -409,12 +409,12 @@ 409 409 * {{code}}0{{/code}} (integer number) 410 410 * {{code}}0772{{/code}} (leading 0 means octal integer number) 411 411 * {{code}}3.14159{{/code}} (floating point number) 412 -* {{code}}5e12{{/code}} (float in exponent notation, ΓÇ£times ten to the power ofΓÇ¥)415 +* {{code}}5e12{{/code}} (float in exponent notation, "times ten to the power of") 413 413 * {{code}}0xCAFE{{/code}} (hexadecimal integer number) 414 414 415 415 416 416 417 -{{no te body="Since octal numbers are hardly ever used (usually unknowingly), the parser is will produce a warning if an octal number is encountered."/}}420 +{{info}}Since octal numbers are hardly ever used (usually unknowingly), the parser is will produce a warning if an octal number is encountered."{{/info}} 418 418 419 419 420 420 ... ... @@ -426,11 +426,11 @@ 426 426 427 427 428 428 429 -{{no te body="Since expressions are written in XML attribute values, you have to use the single quotes inside the double quotes for the actual attribute value. To write characters like '''<>"&''' in an expression string (or anywhere else in an XML attribute value), youΓÇÖll have to escape them as '''&lt; &gt; &quot; &amp;''' respectively. The backslash '''\''' can be used in strings for escape characters like in C/C++. Most important are '''\'''' for a single quote as part of the string, and '''\\''' for the backslash itself."/}}432 +{{info}}Since expressions are written in XML attribute values, you have to use the single quotes inside the double quotes for the actual attribute value. To write characters like '''< > " &''' in an expression string (or anywhere else in an XML attribute value), you'll have to escape them as '''< > " &''' respectively. The backslash '''\''' can be used in strings for escape characters like in C/C++. Most important are '''\'''' for a single quote as part of the string, and '''\\''' for the backslash itself.{{/info}} 430 430 431 431 == Numeric data types and suffixes == 432 432 433 -Numbers can have a suffix that determines their numeric type. There are also numerical data types like ΓÇ£moneyΓÇ¥orΓÇ£timeΓÇ¥which can only be expressed by using an appropriate unit suffix:436 +Numbers can have a suffix that determines their numeric type. There are also numerical data types like "money" or "time" which can only be expressed by using an appropriate unit suffix: 434 434 435 435 * {{code}}5000000000L{{/code}} (large integer) 436 436 * {{code}}1f{{/code}} (floating point number, same as 1.0, just 1 would be an integer) ... ... @@ -478,11 +478,11 @@ 478 478 \\24h|Time in milliseconds, seconds, minutes, or hours, respectively. A time value is always stored in seconds. 479 479 ))) 480 480 481 -{{no te body="All unit data types are floating point types, except for money, which is an integer data type."/}}484 +{{info}}All unit data types are floating point types, except for money, which is an integer data type.{{/info}} 482 482 483 483 == Operators == 484 484 485 -You can build expressions by combining sub-expressions with operators. For Boolean operations, expressions are considered ΓÇ£falseΓÇ¥if they are equal to zero,ΓÇ£trueΓÇ¥otherwise. The following operators, delimiters, and constants are supported488 +You can build expressions by combining sub-expressions with operators. For Boolean operations, expressions are considered "false" if they are equal to zero, "true" otherwise. The following operators, delimiters, and constants are supported 486 486 487 487 (% style="margin-left: 0.0px;" %) 488 488 ((( ... ... @@ -533,24 +533,24 @@ 533 533 |-|binary|{{code}}1 - 1{{/code}}|{{code}}0{{/code}}|Subtraction 534 534 | 535 535 lt 536 -\\ <(<)|binary|539 +\\< (<)|binary| 537 537 {{code}}1 lt 3{{/code}} 538 -\\{{code}}1 & amp;lt; 3{{/code}}|{{code}}true{{/code}}|Less than541 +\\{{code}}1 < 3{{/code}}|{{code}}true{{/code}}|Less than 539 539 | 540 540 le 541 -\\ <=|binary|544 +\\<=|binary| 542 542 {{code}}1 le 3{{/code}} 543 -\\{{code}}1 & amp;lt;= 3{{/code}}|{{code}}true{{/code}}|Less than or equal to546 +\\{{code}}1 <= 3{{/code}}|{{code}}true{{/code}}|Less than or equal to 544 544 | 545 545 gt 546 -\\ >(>)|binary|549 +\\> (>)|binary| 547 547 {{code}}1 gt 3{{/code}} 548 -\\{{code}}1 & amp;gt; 3{{/code}}|{{code}}false{{/code}}|Greater than551 +\\{{code}}1 > 3{{/code}}|{{code}}false{{/code}}|Greater than 549 549 | 550 550 ge 551 -\\ >=|binary|554 +\\>=|binary| 552 552 {{code}}1 ge 3{{/code}} 553 -\\{{code}}1 & amp;gt;= 3{{/code}}|{{code}}false{{/code}}|Greater than or equal to556 +\\{{code}}1 >= 3{{/code}}|{{code}}false{{/code}}|Greater than or equal to 554 554 |((( 555 555 = = 556 556 )))|binary|{{code}}1 + 1 == 2.0{{/code}}|{{code}}true{{/code}}|Equal to ... ... @@ -570,7 +570,7 @@ 570 570 571 571 === Operator precedence rules === 572 572 573 -You can group sub-expressions using parentheses, but if you don ΓÇÖt, the following order of operations is applied, so that 5-1+2*3 == 10 as you would expect. The order is the same as in the table above, but there are operators with the same precedence - these are applied from left to right.576 +You can group sub-expressions using parentheses, but if you don't, the following order of operations is applied, so that 5-1+2*3 == 10 as you would expect. The order is the same as in the table above, but there are operators with the same precedence - these are applied from left to right. 574 574 575 575 * Unary operators: +, -, not, typeof, function-style operators (highest precedence) 576 576 * Power operator: ^ ... ... @@ -588,7 +588,7 @@ 588 588 589 589 When a binary arithmetic operator is used on numbers of different types, they will be converted to a suitable output type. The resulting type depends on whether a unit data type is involved (types that are not plain integers or floats). The following cases may occur: 590 590 591 -* Null and something else: The null value will be interpreted as ΓÇ£0ΓÇ¥of the other type.594 +* Null and something else: The null value will be interpreted as "0" of the other type. 592 592 * Two non-unit integers: The result will be an integer of the largest involved type. 593 593 * Two non-unit numbers, not all integers: The result will be the largest involved float type. 594 594 * Non-unit and unit: The result will be the unit type. ... ... @@ -598,17 +598,17 @@ 598 598 599 599 There is a way to convert a number into a different type manually: You append the corresponding suffix to a sub-expression in parentheses, like this: 600 600 601 -* {{code}}(1 + 1)f{{/code}} Γƒ╣{{code}}2f{{/code}}Γƒ╣{{code}}2.0{{/code}}602 -* {{code}}(1h) m / (180deg) i{{/code}} Γƒ╣{{code}}(3600s) m / (3.14rad) i{{/code}}Γƒ╣{{code}}3600m / 3{{/code}}Γƒ╣{{code}}1200m{{/code}}604 +* {{code}}(1 + 1)f{{/code}} ⟹ {{code}}2f{{/code}} ⟹ {{code}}2.0{{/code}} 605 +* {{code}}(1h) m / (180deg) i{{/code}} ⟹ {{code}}(3600s) m / (3.14rad) i{{/code}} ⟹ {{code}}3600m / 3{{/code}} ⟹ {{code}}1200m{{/code}} 603 603 604 -When converting to a non-default unit type, this means you interpret the number as in the given units: ΓÇ£{{code}}(1km + 500m)h{{/code}}ΓÇ¥means that you interpret 1500m as 1500 hours, so the resulting value will be 1500x3600 seconds. (As stated above, the default unit for a length is metres.)607 +When converting to a non-default unit type, this means you interpret the number as in the given units: "{{code}}(1km + 500m)h{{/code}}" means that you interpret 1500m as 1500 hours, so the resulting value will be 1500x3600 seconds. (As stated above, the default unit for a length is metres.) 605 605 606 606 The division operation will be an integer division (rounding towards zero) if both operands are integers (see the example in the table above). So if you want to get a floating point result, you have to make sure that at least one of the operands is a floating point type. 607 607 608 608 Every data type can be combined with a string with the + operator, and will be converted to a string representation. That way you can also concatenate strings and numbers: 609 609 610 -* {{code}}'One plus one is equal to ' + (1+1) + '.'{{/code}} Γƒ╣{{code}}'One plus one is equal to 2.'{{/code}}611 -* {{code}}'One plus one is not equal to ' + 1 + 1 + '.'{{/code}} Γƒ╣{{code}}'One plus one is not equal to 11.'{{/code}}613 +* {{code}}'One plus one is equal to ' + (1+1) + '.'{{/code}} ⟹ {{code}}'One plus one is equal to 2.'{{/code}} 614 +* {{code}}'One plus one is not equal to ' + 1 + 1 + '.'{{/code}} ⟹ {{code}}'One plus one is not equal to 11.'{{/code}} 612 612 613 613 As you can see, operators of the same precedence (+ in this case) are always evaluated from left to right. 614 614 ... ... @@ -619,12 +619,12 @@ 619 619 Some additional notes on Boolean operators (such as and, or, not, ==): 620 620 621 621 * Of course a Boolean operation always results in true or false (integer 1 or 0). 622 -* Values of any type can be used as Boolean operands, e.g. for ΓÇ£andΓÇ¥. They will be interpreted asΓÇ£trueΓÇ¥if they are **non-zero** or **non-numeric**.625 +* Values of any type can be used as Boolean operands, e.g. for "and". They will be interpreted as "true" if they are **non-zero** or **non-numeric**. 623 623 * != and == can be used with any data types, even non-numeric ones. When comparing two numeric values, they are converted using the rules above. Values of non-numeric types are never equal to null, or to any other numbers. 624 -* ΓÇ£andΓÇ¥andΓÇ£orΓÇ¥use short-circuit semantics: The right side of the operation can be skipped if the left side already determines the outcome of the operation625 -** Example:{{code}} false and $foo{{/code}} Γƒ╣{{code}}false{{/code}} (the value of $foo is not checked at all)627 +* "and" and "or" use short-circuit semantics: The right side of the operation can be skipped if the left side already determines the outcome of the operation 628 +** Example:{{code}} false and $foo{{/code}} ⟹ {{code}}false{{/code}} (the value of $foo is not checked at all) 626 626 * Unlike != and ==, the comparison operators <, <=, >, >= are only supported **for numeric values**, **difficulty levels**, and **attention levels**. Comparing other non-numeric values will result in an error and an undefined result. 627 -* <, <=, >, >= cannot be used in XML directly, so lt, le, gt, ge are provided as alternatives. In some cases you won ΓÇÖt have to use them, though - using [[range checks>>MediaWiki.NULL]] with additional XML attributes can be more readable.630 +* <, <=, >, >= cannot be used in XML directly, so lt, le, gt, ge are provided as alternatives. In some cases you won't have to use them, though - using [[range checks>>MediaWiki.NULL]] with additional XML attributes can be more readable. 628 628 629 629 630 630 ... ... @@ -640,25 +640,25 @@ 640 640 641 641 See also the section about [[value properties>>MediaWiki.NULL]]. 642 642 643 -Instead of ΓÇÿ%1 %2 %3 ΓÇÖ, you can also use ΓÇÿ%s %s %sΓÇÖ, which is also compatible with Lua string formatting in the UI system. However, this should only be used if you are sure that the order is the same in all supported languages. If you want to make translators aware that they can change the order of parameters, you should prefer '%1 %2 %3'.646 +Instead of ΓÇÿ%1 %2 %3', you can also use ΓÇÿ%s %s %s', which is also compatible with Lua string formatting in the UI system. However, this should only be used if you are sure that the order is the same in all supported languages. If you want to make translators aware that they can change the order of parameters, you should prefer '%1 %2 %3'. 644 644 \\To get a percent character in the result string, use '%%' in the format string. 645 645 \\\\\\If you need a more sophisticated method for text substitution, try **<substitute_text>**. See the XML schema documentation for this script action. 646 646 \\**[New as of X Rebirth 4.0]** 647 647 \\ With the formatting syntax above, it is even possible to control how the parameter is formatted, using modifiers between "%" and the parameter specifier ("s" or the parameter number): 648 648 649 -* {{code}}'%,s'.[12345678]{{/code}} Γƒ╣{{code}}'12,345,678'{{/code}} (the "," modifier shows a number with thousands separators, correctly localised)650 -* {{code}}'%.3s'.[123.4]{{/code}} Γƒ╣{{code}}'123.400'{{/code}} (show 3 fractional digits, rounding half away from zero - decimal point correctly localised)651 -* {{code}}'%,.1s'.[12345.67]'{{/code}} Γƒ╣{{code}}'12,345.7'{{/code}} (combination of the above)652 +* {{code}}'%,s'.[12345678]{{/code}} ⟹ {{code}}'12,345,678'{{/code}} (the "," modifier shows a number with thousands separators, correctly localised) 653 +* {{code}}'%.3s'.[123.4]{{/code}} ⟹ {{code}}'123.400'{{/code}} (show 3 fractional digits, rounding half away from zero - decimal point correctly localised) 654 +* {{code}}'%,.1s'.[12345.67]'{{/code}} ⟹ {{code}}'12,345.7'{{/code}} (combination of the above) 652 652 653 653 Additional remarks: 654 654 655 655 * The "," and "." formatting modifiers only apply to numbers. They are ignored if used on values of other types. 656 -* ┬áIf "," is used without "." then any fractional digits are discarded.659 +* If "," is used without "." then any fractional digits are discarded. 657 657 * "." must be followed by a single digit (0-9). In case of ".0" any fractional digits are discarded (rounding towards zero, not half away from zero). 658 658 659 659 660 660 661 -{{info body="There are also special methods to [[NULL|format money values and time values]] using the "formatted"property."/}}664 +{{info body="There are also special methods to [[NULL|format money values and time values]] using the "formatted" property."/}} 662 662 663 663 664 664 ... ... @@ -670,19 +670,19 @@ 670 670 671 671 Another example for a non-numeric value is a list: It is an ordered collection of other arbitrary values (called array or vector in other languages). It can be constructed within an expression using the [[~[~] syntax>>MediaWiki.NULL]]. It may also be generated by special actions and conditions, and there are actions that can [[insert or remove values>>MediaWiki.NULL]]. 672 672 673 -A list can contain values of arbitrary data types, even mixed in the same list - so a list can actually contain other lists. However, some of the things that you can do with lists require that all contained elements are of a certain type. The contents of a list can be accessed via properties, see the section about [[value properties>>MediaWiki.NULL]]. Lists can be empty, these are written as ΓÇ£[ ]ΓÇ¥.676 +A list can contain values of arbitrary data types, even mixed in the same list - so a list can actually contain other lists. However, some of the things that you can do with lists require that all contained elements are of a certain type. The contents of a list can be accessed via properties, see the section about [[value properties>>MediaWiki.NULL]]. Lists can be empty, these are written as "[ ]". 674 674 675 -{{no te body="When accessing a listΓÇÖs elements, the numbering is '''1-based''', so the first element has number 1. This is intuitive but different from 0-based numbering in most programming languages."/}}678 +{{info}}When accessing a list's elements, the numbering is '''1-based''', so the first element has number 1. This is intuitive but different from 0-based numbering in most programming languages."{{/info}} 676 676 677 677 678 678 679 679 Lists are stored in variables as references, so multiple variables can refer to the same **shared list**: If you change a shared list through a variable, e.g. by changing the value of an element, you change it as well for all other variables. However, the operators == and != can also be used on two distinct lists to compare their elements. 680 680 681 -{{no te body="When using<remove_from_list/>, be aware that all elements are checked and potentially removed during the action. Do not provide this action with a index lookup of that list as it may become out of bounds.684 +{{info}}When using <remove_from_list/>, be aware that all elements are checked and potentially removed during the action. Do not provide this action with a index lookup of that list as it may become out of bounds. 682 682 683 -Bad usage attempting to remove the last element of the list: <remove_from_list name="$List"exact="$List.{$List.count}"/>686 +Bad usage attempting to remove the last element of the list: <remove_from_list name="$List" exact="$List.{$List.count}"/> 684 684 685 -If you know the index, simply use <remove_value/>e.g.<remove_value name="$List.{$List.count}"/>"/}}688 +If you know the index, simply use <remove_value/> e.g. <remove_value name="$List.{$List.count}"/>{{/info}} 686 686 687 687 688 688 ... ... @@ -704,15 +704,15 @@ 704 704 705 705 These restrictions only apply to the keys, there are no restrictions for values that you assign to them. For example: 706 706 707 -* {{code}}table[]{{/code}} Γƒ╣creates an empty table708 -* {{code}}table[{0} = null]{{/code}} Γƒ╣creates a table that maps the number 0 to null\\710 +* {{code language="xml"}}table[]{{/code}} ⟹ creates an empty table 711 +* {{code language="xml"}}table[{0} = null]{{/code}} ⟹ creates a table that maps the number 0 to null\\ 709 709 710 710 711 711 712 -* {{code}}table[{'$foo'} = 'bar']{{/code}} Γƒ╣a table that maps the string '$foo' to the string 'bar'713 -* {{code}}table[$foo = 'bar']{{/code}} Γƒ╣exactly the same, just a shorter notation for string keys714 -* {{code}}table[foo = 'bar']{{/code}} Γƒ╣error, 'foo' does not start with a '$'715 -* {{code}}table[{1} = [], {2} = table[]] {{/code}} Γƒ╣a table that maps 1 to an empty list and 2 to an empty table\\715 +* {{code language="xml"}}table[{'$foo'} = 'bar']{{/code}} ⟹ a table that maps the string '$foo' to the string 'bar' 716 +* {{code language="xml"}}table[$foo = 'bar']{{/code}} ⟹ exactly the same, just a shorter notation for string keys 717 +* {{code language="xml"}}table[foo = 'bar']{{/code}} ⟹ error, 'foo' does not start with a '$' 718 +* {{code language="xml"}}table[{1} = [], {2} = table[]] {{/code}} ⟹ a table that maps 1 to an empty list and 2 to an empty table\\ 716 716 717 717 718 718 ... ... @@ -724,33 +724,33 @@ 724 724 725 725 == Value properties == 726 726 727 -Properties are a crucial concept in script expressions. In the previous sections you have seen mostly constant expressions, which are already evaluated when they are parsed at game start. For reading and writing variables and evaluating the game ΓÇÖs state, properties are used.730 +Properties are a crucial concept in script expressions. In the previous sections you have seen mostly constant expressions, which are already evaluated when they are parsed at game start. For reading and writing variables and evaluating the game's state, properties are used. 728 728 729 -Numbers don ΓÇÖt have any properties. Lists, for example, have quite a few of them: You can access the number of elements; and each element is also a property of the list. A ship can have properties like its name, the ship class, its position etc.732 +Numbers don't have any properties. Lists, for example, have quite a few of them: You can access the number of elements; and each element is also a property of the list. A ship can have properties like its name, the ship class, its position etc. 730 730 731 731 You can imagine properties as key/value pairs in an associative mapping: You pass the key, and you get the value as result. For example, the list [42, null, 'text'] has the following mapping: 732 732 733 -* 1 Γƒ╣42734 -* 2 Γƒ╣null735 -* 3 Γƒ╣'text'736 -* 'count' Γƒ╣3736 +* 1 ⟹ 42 737 +* 2 ⟹ null 738 +* 3 ⟹ 'text' 739 +* 'count' ⟹ 3 737 737 738 738 As you can see, a property key can be a number or a string. Actually there is no restriction regarding the data type of the key. 739 739 740 740 You can look up a property by appending a dot and the key in curly braces: 741 741 742 -* {{code}}[100, 200, 300, 400].{1}{{/code}} Γƒ╣100 (reading the first element)743 -* {{code}}[100, 200, ['Hello ', 'world']] .{3}.{2}{{/code}} Γƒ╣'world' (second element of the inner list, which is the third element of the outer list)744 -* {{code}}[].{'count'}{{/code}} Γƒ╣0745 -* {{code}}table[{21} = 42].{21}{{/code}} Γƒ╣42\\745 +* {{code}}[100, 200, 300, 400].{1}{{/code}} ⟹ 100 (reading the first element) 746 +* {{code}}[100, 200, ['Hello ', 'world']] .{3}.{2}{{/code}} ⟹ 'world' (second element of the inner list, which is the third element of the outer list) 747 +* {{code}}[].{'count'}{{/code}} ⟹ 0 748 +* {{code}}table[{21} = 42].{21}{{/code}} ⟹ 42\\ 746 746 747 747 748 748 749 -In most cases the property key is a fixed string, like ΓÇ£nameΓÇ¥orΓÇ£classΓÇ¥. You can write this like above:752 +In most cases the property key is a fixed string, like "name" or "class". You can write this like above: 750 750 751 751 * {{code}}[42].{'count'}{{/code}} 752 752 * {{code}}$ship.{'name'}{{/code}} 753 -* {{code}}$ship.{'class'} ┬á{{/code}}756 +* {{code}}$ship.{'class'}{{/code}} 754 754 * {{code}}table[$foo='bar'].{'$foo'}{{/code}}\\ 755 755 756 756 ... ... @@ -764,7 +764,7 @@ 764 764 765 765 766 766 767 -(In this case, $ship is a variable. All variables start with a ΓÇ£$ΓÇ¥, so they cannot be confused with keywords.)770 +(In this case, $ship is a variable. All variables start with a "$", so they cannot be confused with keywords.) 768 768 769 769 A list has even more properties: 770 770 ... ... @@ -772,19 +772,19 @@ 772 772 773 773 **min'** and '**max'** return the minimum or maximum (all elements have to be numeric) 774 774 775 -* {{code}}[1, 6, 8].min{{/code}} Γƒ╣1778 +* {{code}}[1, 6, 8].min{{/code}} ⟹ 1 776 776 777 777 **average'** returns the average (but all element types have to be compatible) 778 778 779 -* {{code}}[1, 6, 8].average{{/code}} Γƒ╣5782 +* {{code}}[1, 6, 8].average{{/code}} ⟹ 5 780 780 781 -**indexof'** is followed by another property, and the index of the first occurence of that key in the list is returned, or 0 if it ΓÇÖs not in the list784 +**indexof'** is followed by another property, and the index of the first occurence of that key in the list is returned, or 0 if it's not in the list 782 782 783 -* {{code}}[1, 6, 8].indexof.{8}{{/code}} Γƒ╣3786 +* {{code}}[1, 6, 8].indexof.{8}{{/code}} ⟹ 3 784 784 785 785 **clone'** creates a shallow copy of the list (i.e. lists that are contained as elements in the list are not copied, only the reference to them) 786 786 787 -* {{code}}[1, 6, 8].clone{{/code}} Γƒ╣{{code}}[1, 6, 8]{{/code}}790 +* {{code}}[1, 6, 8].clone{{/code}} ⟹ {{code}}[1, 6, 8]{{/code}} 788 788 789 789 A table has different properties: 790 790 ... ... @@ -804,7 +804,7 @@ 804 804 805 805 806 806 807 -{{no te body="The string formatting syntax that you have seen [[NULL|above]] is also based on the property system. You basically pass a list as property key to a string. Braces around the brackets are not required, so 'foo'.[...] is just a convenient alternative notation for 'foo'.{[...]}."/}}810 +{{info}}The string formatting syntax that you have seen [[NULL|above]] is also based on the property system. You basically pass a list as property key to a string. Braces around the brackets are not required, so 'foo'.[...] is just a convenient alternative notation for 'foo'.{[...]}.{{/info}} 808 808 809 809 810 810 ... ... @@ -813,24 +813,24 @@ 813 813 814 814 {{{===}}} 815 815 816 -If you look up a property that does not exist, there will be an error, and the result will be null. To test whether a property exists, you can append a question mark ΓÇ£?ΓÇ¥to the lookup, which yields true or false:819 +If you look up a property that does not exist, there will be an error, and the result will be null. To test whether a property exists, you can append a question mark "?" to the lookup, which yields true or false: 817 817 818 -* {{code}}$list.{5}{{/code}} Γƒ╣The fifth element of a list - however, if $list has less than 5 elements (and if it's also not a table with the key 5), there will be an error819 -* {{code}}$list.{5}?{{/code}} Γƒ╣true if $list exists and has the property 5, false otherwise820 -* {{code}}$table.$key?{{/code}} Γƒ╣Analogously, true if $table exists and has the string property '$key'\\821 +* {{code}}$list.{5}{{/code}} ⟹ The fifth element of a list - however, if $list has less than 5 elements (and if it's also not a table with the key 5), there will be an error 822 +* {{code}}$list.{5}?{{/code}} ⟹ true if $list exists and has the property 5, false otherwise 823 +* {{code}}$table.$key?{{/code}} ⟹ Analogously, true if $table exists and has the string property '$key'\\ 821 821 822 822 823 823 824 824 The question mark can even be applied to variables: 825 825 826 -* {{code}}$list{{/code}} Γƒ╣The value stored under the name $list, or an error if there is no such variable827 -* {{code}}$list?{{/code}} Γƒ╣true if the variable exists, false otherwise829 +* {{code}}$list{{/code}} ⟹ The value stored under the name $list, or an error if there is no such variable 830 +* {{code}}$list?{{/code}} ⟹ true if the variable exists, false otherwise 828 828 829 -To look up the value of a property although it may not exist, you can use the at-sign ΓÇ£@ΓÇ¥as prefix:832 +To look up the value of a property although it may not exist, you can use the at-sign "@" as prefix: 830 830 831 -* {{code}}@$list.{5}{{/code}} Γƒ╣The result of the $list lookup if $list exists and has the property 5, otherwise null (without error message)832 -* {{code}}@$list{{/code}} Γƒ╣The list if this variable exists, null otherwise833 -* {{code}}@$list.{5}.{1}{{/code}} Γƒ╣The first element of the fifth element of $list, if it exists, null otherwise834 +* {{code}}@$list.{5}{{/code}} ⟹ The result of the $list lookup if $list exists and has the property 5, otherwise null (without error message) 835 +* {{code}}@$list{{/code}} ⟹ The list if this variable exists, null otherwise 836 +* {{code}}@$list.{5}.{1}{{/code}} ⟹ The first element of the fifth element of $list, if it exists, null otherwise 834 834 835 835 As you can see, an error is already prevented if any link in the property chain does not exist. But use the @ prefix with care, since error messages are really helpful for detecting problems in your scripts. The @ prefix only suppresses property-related error messages and does not change any in-game behaviour. 836 836 ... ... @@ -840,7 +840,7 @@ 840 840 841 841 === Static lookups === 842 842 843 -There are a few data types which are basically enumerations: They only consist of a set of named values, e.g. the ΓÇ£classΓÇ¥data type, which is used for the component classes that exist in the game. For all these static enumeration classes there is a lookup value of the same name, from which you can get the named values as properties by their name. So for the typeΓÇ£classΓÇ¥, there is a valueΓÇ£classΓÇ¥that can be used to access the classes.846 +There are a few data types which are basically enumerations: They only consist of a set of named values, e.g. the "class" data type, which is used for the component classes that exist in the game. For all these static enumeration classes there is a lookup value of the same name, from which you can get the named values as properties by their name. So for the type "class", there is a value "class" that can be used to access the classes. 844 844 845 845 Here are a few enumeration classes and corresponding example lookup values: 846 846 ... ... @@ -894,15 +894,15 @@ 894 894 \\faction.argongovernment|Factions 895 895 ))) 896 896 897 -{{no te body="[[Category:Broken_macro/anchor]]With the ''typeof'' operator you can get the datatype of any expression and compare it with what you expect, for example:900 +{{info}}With the ''typeof'' operator you can get the datatype of any expression and compare it with what you expect, for example: 898 898 899 899 <code>typeof $value == datatype.faction</code> 900 900 901 -However, you should not compare the type to datatype.string because there are strings that have different data types. To check for a string you should use the datatype's property "'''isstring'''"instead. For example, to check if the variable $value is a string, use the following term:904 +However, you should not compare the type to datatype.string because there are strings that have different data types. To check for a string you should use the datatype's property "'''isstring'''" instead. For example, to check if the variable $value is a string, use the following term: 902 902 903 -<code>(typeof $value).isstring</code>"/}} 906 +<code>(typeof $value).isstring</code>"{{/info}} 904 904 905 -{{info body="There is also the datatypeΓÇ£tagΓÇ¥with the lookup nameΓÇ£tagΓÇ¥- however, this is not an enumeration type. Looking up a value by name never fails, you actually create a tag value for a given name if it does not exist. For example, if you have a typo, likeΓÇ£tag.misionΓÇ¥instead ofΓÇ£tag.missionΓÇ¥, there wonΓÇÖt be an error because any name is valid for a tag, and the tagΓÇ£misionΓÇ¥is created on its first use."/}}908 +{{info}}There is also the datatype "tag" with the lookup name "tag" - however, this is not an enumeration type. Looking up a value by name never fails, you actually create a tag value for a given name if it does not exist. For example, if you have a typo, like "tag.mision" instead of "tag.mission", there won't be an error because any name is valid for a tag, and the tag "mision" is created on its first use."{{/info}} 906 906 907 907 \\ 908 908 ... ... @@ -912,11 +912,11 @@ 912 912 913 913 === Player properties === 914 914 915 -You can access many player-related game properties via the keyword ΓÇ£playerΓÇ¥:918 +You can access many player-related game properties via the keyword "player": 916 916 917 -* player.**name**: The player ΓÇÖs name920 +* player.**name**: The player's name 918 918 * player.**age**: The passed in-game time since game start 919 -* player.**money**: The money in the player ΓÇÖs account922 +* player.**money**: The money in the player's account 920 920 * player.**ship**: The ship the player is currently on (not necessarily the player's ship), or null if the player is on a station\\ 921 921 922 922 ... ... @@ -943,7 +943,7 @@ 943 943 * available 944 944 * isclass.(...) 945 945 946 -These properties will not cause errors when used on ΓÇ£nullΓÇ¥or on a destroyed object (which may still be accessible from scripts in some cases), and produce null or false as results, respectively. (The keywordΓÇ£availableΓÇ¥is used for trades, not for objects. Trades can also become invalid.) However, when using such a property on a different data type like a number, there will still be an error.949 +These properties will not cause errors when used on "null" or on a destroyed object (which may still be accessible from scripts in some cases), and produce null or false as results, respectively. (The keyword "available" is used for trades, not for objects. Trades can also become invalid.) However, when using such a property on a different data type like a number, there will still be an error. 947 947 948 948 (% id="categorybroken_macroanchormoney-and-time-formatting" %)=== Money and time formatting 949 949 ... ... @@ -953,13 +953,13 @@ 953 953 **[New as of X Rebirth 4.0]** 954 954 \\Numbers don't have any properties, except for money and time: They have a "**formatted**" property, which allows you to get a custom string representation with more advanced options than the [[generic formatting method>>MediaWiki.NULL]] for numbers. 955 955 956 -* {{code}}$money.formatted.{'formatstring'} ┬á{{/code}}959 +* {{code}}$money.formatted.{'formatstring'}{{/code}} 957 957 * {{code}}$money.formatted.default{{/code}} (using default format string '%s')\\ 958 958 959 959 960 960 961 961 * {{code}}$time.formatted.{'formatstring'}{{/code}} 962 -* {{code}}$time.formatted.default{{/code}} ┬á(using default format string '%T')965 +* {{code}}$time.formatted.default{{/code}} (using default format string '%T') 963 963 964 964 In scripts, money is stored in cents, not Credits. The formatted representation always shows the value in Credits, including thousands separators. 965 965 ... ... @@ -989,20 +989,20 @@ 989 989 990 990 991 991 992 -* {{code}}(1234Cr).formatted.{'%s'}{{/code}} Γƒ╣{{code}}'1,234'{{/code}}993 -* {{code}}(1234Cr).formatted.default{{/code}} Γƒ╣{{code}}'1,234'{{/code}} (same as {'%s'})994 -* {{code}}(1234Cr).formatted.{'%.s %Cr'}{{/code}} Γƒ╣{{code}}'1,234.00 Cr'{{/code}}995 -* {{code}}(1234Cr).formatted.{'%1s'}{{/code}} Γƒ╣{{code}}'1 k'{{/code}} (rounding towards zero)996 -* {{code}}(1234Cr).formatted.{'%cM'}{{/code}} Γƒ╣{{code}}'0 M'{{/code}}995 +* {{code}}(1234Cr).formatted.{'%s'}{{/code}}⟹{{code}}'1,234'{{/code}} 996 +* {{code}}(1234Cr).formatted.default{{/code}}⟹{{code}}'1,234'{{/code}} (same as {'%s'}) 997 +* {{code}}(1234Cr).formatted.{'%.s %Cr'}{{/code}}⟹{{code}}'1,234.00 Cr'{{/code}} 998 +* {{code}}(1234Cr).formatted.{'%1s'}{{/code}}⟹{{code}}'1 k'{{/code}} (rounding towards zero) 999 +* {{code}}(1234Cr).formatted.{'%cM'}{{/code}}⟹{{code}}'0 M'{{/code}} 997 997 998 998 For documentation of time format strings, see the Lua function ConvertTimeString() in the [[MediaWiki.ARCHIVE.XRWIKIModding_supportUI_Modding_supportLua_function_overview]]. 999 999 1000 1000 Examples: 1001 1001 1002 -* {{code}}(151s).formatted.{'%T'}{{/code}} Γƒ╣{{code}}'00:02:31'{{/code}}1003 -* {{code}}(151s).formatted.default{{/code}} Γƒ╣{{code}}'00:02:31'{{/code}} (same as {'%T'})1004 -* {{code}}(151s).formatted.{'%.3T'}{{/code}} Γƒ╣{{code}}'00:02:31.000'{{/code}}1005 -* {{code}}(151s).formatted.{'%h:%M'}{{/code}} Γƒ╣{{code}}'0:02'{{/code}}1005 +* {{code}}(151s).formatted.{'%T'}{{/code}} ⟹ {{code}}'00:02:31'{{/code}} 1006 +* {{code}}(151s).formatted.default{{/code}} ⟹ {{code}}'00:02:31'{{/code}} (same as {'%T'}) 1007 +* {{code}}(151s).formatted.{'%.3T'}{{/code}} ⟹ {{code}}'00:02:31.000'{{/code}} 1008 +* {{code}}(151s).formatted.{'%h:%M'}{{/code}} ⟹ {{code}}'0:02'{{/code}} 1006 1006 1007 1007 (% id="complete-property-documentation" %) 1008 1008 ... ... @@ -1014,26 +1014,26 @@ 1014 1014 1015 1015 1016 1016 1017 -{{no te body="scriptproperties.html has to load files from different folders, which modern browsers do not allow by default for security reasons. In order to open scriptproperties.html, the following is required:1020 +{{info}}scriptproperties.html has to load files from different folders, which modern browsers do not allow by default for security reasons. In order to open scriptproperties.html, the following is required: 1018 1018 1019 -* Firefox: On the about:config page, the value of "security.fileuri.strict_origin_policy"has to be changed to"false".1020 -* Chrome: The Chrome launcher has to be started with the command-line parameter --allow-file-access-from-files "/}}1022 +* Firefox: On the about:config page, the value of "security.fileuri.strict_origin_policy" has to be changed to "false". 1023 +* Chrome: The Chrome launcher has to be started with the command-line parameter --allow-file-access-from-files{{/info}} 1021 1021 1022 1022 1023 1023 1024 -This provides you with a complete list of all supported ΓÇ£base keywordsΓÇ¥and properties. To filter in this list, you can enter an expression in the text field:1027 +This provides you with a complete list of all supported "base keywords" and properties. To filter in this list, you can enter an expression in the text field: 1025 1025 1026 1026 * Enter the beginning of a base keyword 1027 -* Enter $ followed by the data type you are looking for (e.g. ΓÇ£$shipΓÇ¥), as if it were a variable1028 -* To see the properties of a base keyword or data type, enter a dot ( ΓÇ£.ΓÇ¥)1030 +* Enter $ followed by the data type you are looking for (e.g. "$ship"), as if it were a variable 1031 +* To see the properties of a base keyword or data type, enter a dot (".") 1029 1029 * After the dot, you can enter a property name 1030 -* You can also enter a dot ( ΓÇ£.ΓÇ¥) as first character to search globally for a property1033 +* You can also enter a dot (".") as first character to search globally for a property 1031 1031 1032 1032 \\ 1033 1033 1034 1034 1035 1035 1036 -{{no te body="The documentation contains some data types that are no real script data types, but which are useful for documentation purposes. For example, ships and stations are both of datatypeΓÇ£componentΓÇ¥, but have different properties based on their component class."/}}1039 +{{info}}The documentation contains some data types that are no real script data types, but which are useful for documentation purposes. For example, ships and stations are both of datatype "component", but have different properties based on their component class.{{/info}} 1037 1037 1038 1038 1039 1039 ... ... @@ -1043,7 +1043,7 @@ 1043 1043 1044 1044 = MD refreshing and patching = 1045 1045 1046 -When a saved game is loaded, the saved MD state is restored, but also all MD files are reloaded and changes in them are applied to the MD state. This is called ΓÇ£refreshΓÇ¥. It is also possible to refresh the MD at run-time using the commandΓÇ£refreshmdΓÇ¥on the in-game command line. This is a convenient way to update MD scripts while the game is already running.1049 +When a saved game is loaded, the saved MD state is restored, but also all MD files are reloaded and changes in them are applied to the MD state. This is called "refresh". It is also possible to refresh the MD at run-time using the command "refreshmd" on the in-game command line. This is a convenient way to update MD scripts while the game is already running. 1047 1047 1048 1048 \\ 1049 1049 ... ... @@ -1072,9 +1072,9 @@ 1072 1072 1073 1073 1074 1074 1075 -{{warning body="Be aware that completed instances can be auto-deleted, and so added sub-cues will not become active in such a case."/}}1078 +{{warning}}Be aware that completed instances can be auto-deleted, and so added sub-cues will not become active in such a case.{{/warning}} 1076 1076 1077 -{{warning body="When adding a variable in a new MD script version and using that variable in multiple places, be aware that the variable doesn't exist yet in older savegames. You may have to check the existence of the variable before accessing it, or add some patch logic that initiailses the variable after loading the savegame, if necessary."/}}1080 +{{warning}}When adding a variable in a new MD script version and using that variable in multiple places, be aware that the variable doesn't exist yet in older savegames. You may have to check the existence of the variable before accessing it, or add some patch logic that initiailses the variable after loading the savegame, if necessary.{{/warning}} 1078 1078 1079 1079 1080 1080 ... ... @@ -1086,13 +1086,13 @@ 1086 1086 1087 1087 Cues can have **<patch>** elements with actions that will be performed when an old savegame is loaded. To control which savegames should be affected, you can add a //**version **//attribute to the <cue> node and a //**sinceversion**// attribute in the patch. When a cue is loaded from a savegame that has an older version than //sinceversion//, the <patch> actions will be performed immediately after loading. 1088 1088 1089 -{{code}} <cue┬á[...] version="42">┬á<conditions>[...]</conditions>┬á<actions>[...]</actions>┬á<patch┬ásinceversion="42">┬á┬á┬á[patch actions]┬á</patch></cue>{{/code}}1092 +{{code language="xml"}}<cue [...] version="42"> <conditions> [...] </conditions> <actions> [...] </actions> <patch sinceversion="42"> [patch actions] </patch></cue>{{/code}} 1090 1090 1091 -The patch actions are only performed if the cue is in a certain state, ΓÇ£completeΓÇ¥by default. Use the //**state**// attribute to change this requirement. For more information, see the XML schema documentation of the <patch> element.1094 +The patch actions are only performed if the cue is in a certain state, "complete" by default. Use the //**state**// attribute to change this requirement. For more information, see the XML schema documentation of the <patch> element. 1092 1092 1093 1093 A sequence of multiple <patch> elements is possible. They will be performed in order of appearance, checking the //sinceversion// and //state// attributes in each case. Patches are also applied to all users of a library and to instances. 1094 1094 1095 -{{no te body="The<patch>elements will be ignored when refreshing the MD at run-time. They only affect loaded savegames."/}}1098 +{{info}}The <patch> elements will be ignored when refreshing the MD at run-time. They only affect loaded savegames."{{/info}} 1096 1096 1097 1097 1098 1098 ... ... @@ -1112,41 +1112,38 @@ 1112 1112 1113 1113 There are many conditions and conditional actions that require a value comparison, for example the condition <check_value>: 1114 1114 1115 -{{code}} <check_value┬ávalue="$ware == ware.silicon and $amount != 0"/>{{/code}}1118 +{{code language="xml"}}<check_value value="$ware == ware.silicon and $amount != 0"/>{{/code}} 1116 1116 1117 1117 In the value attribute you specify a boolean expression, and if it is true (that is, not equal to zero), the condition is met. This is a special case: This condition and all other nodes that support a value comparison allows you to specify an upper limit, a lower limit, a number range, or a list of allowed values. Examples: 1118 1118 1119 -{{code}} <check_value┬ávalue="FooCue.state"┬áexact="cuestate.complete"/><check_value┬ávalue="$foo.count"┬ámin="5"/><check_value┬ávalue="$foo"┬ámax="player.age + 1min"/><check_value┬ávalue="player.money"┬ámin="300Cr"max="600Cr"/><check_value┬ávalue="$method"┬álist="[killmethod.hitbymissile, killmethod.collected]"/><check_value┬ávalue="$attention"┬ámin="attention.visible"/>{{/code}}1122 +{{code language="xml"}}<check_value value="FooCue.state" exact="cuestate.complete"/><check_value value="$foo.count" min="5"/><check_value value="$foo" max="player.age + 1min"/><check_value value="player.money" min="300Cr" max="600Cr"/><check_value value="$method" list="[killmethod.hitbymissile, killmethod.collected]"/><check_value value="$attention" min="attention.visible"/>{{/code}} 1120 1120 1121 -{{no te body="Values of most enumeration types cannot be compared via ''min'' or ''max'' (also not via lt, gt, etc.). The only data types that can be used with ''min'' and ''max'' are numbers and the enumeration types ''level'' and ''attention'' (see Boolean operators). The ''exact'' attribute can be used with any type, and is equivalent to using the == operator."/}}1124 +{{info}}Values of most enumeration types cannot be compared via ''min'' or ''max'' (also not via lt, gt, etc.). The only data types that can be used with ''min'' and ''max'' are numbers and the enumeration types ''level'' and ''attention'' (see Boolean operators). The ''exact'' attribute can be used with any type, and is equivalent to using the == operator."{{/info}} 1122 1122 1123 1123 1124 1124 1125 1125 \\ 1126 1126 1127 -(% id="categorybroken_macroanchorrandom-ranges" %) 1128 - 1129 1129 == Random ranges == 1130 1130 1131 1131 If an action requires a value, e.g. when you set a variable to a value, you can have some randomisation. To specify an exact value, e.g. in <set_value>, you can write this: 1132 1132 1133 -{{code}} <set_value┬áname="$race"┬áexact="race.teladi"/>{{/code}}1134 +{{code language="xml"}}<set_value name="$race" exact="race.teladi"/>{{/code}} 1134 1134 1135 1135 To select a random element from a list, this syntax can be used: 1136 1136 1137 -{{code}} <set_value┬áname="$prime"┬álist="[2, 3, 5, 7, 11]"/>{{/code}}1138 +{{code language="xml"}}<set_value name="$prime" list="[2, 3, 5, 7, 11]"/>{{/code}} 1138 1138 1139 1139 To get a random number within a given range, you can use min/max: 1140 1140 1141 -{{code}} <set_value┬áname="$foo"┬ámin="-20"┬ámax="20"/><set_value┬áname="$timeout"┬ámax="20s"/>{{/code}}1142 +{{code language="xml"}}<set_value name="$foo" min="-20" max="20"/><set_value name="$timeout" max="20s"/>{{/code}} 1142 1142 1143 1143 min and max have to be compatible number types. Enumeration types are not allowed, not even level and attention. The min attribute is optional and defaults to 0 (of the number type used in max). 1144 1144 1145 -You can select one of 5 different probability distribution profiles for the random range, ΓÇ£flatΓÇ¥being the default (all values in the range are equally likely). If you select another profile, e.g.ΓÇ£increasingΓÇ¥to make higher numbers more likely, you also have to specify a scale value (integer) that is greater or equal to 2. Higher scale values result in higher peaks in the distribution profiles (probable values become even more probable).1146 +You can select one of 5 different probability distribution profiles for the random range, "flat" being the default (all values in the range are equally likely). If you select another profile, e.g. "increasing" to make higher numbers more likely, you also have to specify a scale value (integer) that is greater or equal to 2. Higher scale values result in higher peaks in the distribution profiles (probable values become even more probable). 1146 1146 1147 -{{code}} <set_value┬áname="$foo"┬ámin="-20"┬ámax="20"profile="profile.increasing"scale="4"/>{{/code}}1148 +{{code language="xml"}}<set_value name="$foo" min="-20" max="20" profile="profile.increasing" scale="4"/>{{/code}} 1148 1148 1149 -(% style="color: rgb(0,0,255);text-decoration: none;" %)┬á 1150 1150 \\(% id="variables-and-namespaces" %) 1151 1151 1152 1152 = Variables and namespaces = ... ... @@ -1153,44 +1153,43 @@ 1153 1153 1154 1154 As you have seen above, you can easily access variables by writing their name (including $ prefix) in an expression. Namespaces define in which cue the variables are actually stored (and from which cue they are read). 1155 1155 1156 - (% style="color: rgb(0,0,255);text-decoration: none;" %)1156 + 1157 1157 \\\\\\(% id="categorybroken_macroanchorcreating-and-removing-variables" %) 1158 1158 1159 1159 == Creating and removing variables == 1160 1160 1161 - {{{You can create variables with certain actions and conditions, such as the<set_value>action:}}}1161 +You can create variables with certain actions and conditions, such as the <set_value> action: 1162 1162 1163 -{{code}} ┬á<set_value┬áname="$foo"┬áexact="$bar + 1"/>{{/code}}1163 +{{code language="xml"}}<set_value name="$foo" exact="$bar + 1" />{{/code}} 1164 1164 1165 -<set_value> also exists as a ΓÇ£conditionΓÇ¥, which can be useful if you want to pass information about the conditions to the actions, that would otherwise be lost - like in a complex <check_any> event condition, where you want to create a variable only if you are in a certain check branch. (Other pseudo-conditions are <remove_value> and <debug_text>.)1165 +<set_value> also exists as a "condition", which can be useful if you want to pass information about the conditions to the actions, that would otherwise be lost - like in a complex <check_any> event condition, where you want to create a variable only if you are in a certain check branch. (Other pseudo-conditions are <remove_value> and <debug_text>.) 1166 1166 1167 -The default operation of <set_value> is ΓÇ£**set**ΓÇ¥, but there are more:ΓÇ£**add**ΓÇ¥,ΓÇ£**subtract**ΓÇ¥, andΓÇ£**insert**ΓÇ¥. //add// and //subtract// change the value of an existing variable, which is created as 0 if it didnΓÇÖt exist before. If neither //min//, //max// nor //exact// attribute is provided, an exact value of 1 is assumed.1167 +The default operation of <set_value> is "**set**", but there are more: "**add**", "**subtract**", and "**insert**". //add// and //subtract// change the value of an existing variable, which is created as 0 if it didn't exist before. If neither //min//, //max// nor //exact// attribute is provided, an exact value of 1 is assumed. 1168 1168 1169 -{{code}} <set_value┬áname="$foo"┬áoperation="add"/>{{/code}}1169 +{{code language="xml"}}<set_value name="$foo" operation="add" />{{/code}} 1170 1170 1171 1171 The trick is that <set_value> not only works on variables, but also on list elements and table keys: 1172 1172 1173 -{{code}} <set_value┬áname="$list.{1}"┬áexact="42"/><set_value┬áname="$table.$foo"┬áexact="42"/>{{/code}}\\1173 +{{code language="xml"}}<set_value name="$list.{1}" exact="42" /><set_value name="$table.$foo" exact="42" />{{/code}}\\ 1174 1174 1175 1175 The operation //insert// is special, and it only works on lists. It inserts the value at the specified position (note that the position beyond the last element is also valid here): 1176 1176 1177 -{{code}} <set_value┬áname="$list.{1}"┬áexact="42"┬áoperation="insert"/>{{/code}}1177 +{{code language="xml"}}<set_value name="$list.{1}" exact="42" operation="insert" />{{/code}} 1178 1178 1179 1179 This shifts the positions of all following elements up by one. If min/max/exact are missing, the default value is null for insertions, not 1 like in other cases. 1180 1180 1181 1181 Appending is easier than that. The following actions are equivalent: 1182 1182 1183 -{{code}} <set_value┬áname="$list.{$list.count + 1}"┬áexact="42"┬áoperation="insert"/><append_to_list┬áname="$list"┬áexact="42"/>{{/code}}1183 +{{code language="xml"}}<set_value name="$list.{$list.count + 1}" exact="42" operation="insert" /><append_to_list name="$list" exact="42" />{{/code}} 1184 1184 1185 1185 Inserting at a position below 1 or above $list.count + 1 is not possible. 1186 1186 1187 1187 To remove variables or list/table entries, use <remove_value>: 1188 1188 1189 -{{code}} <remove_value┬áname="$foo"/><remove_value┬áname="$list.{1}"/><remove_value┬áname="$table.$foo"/>{{/code}}\\1189 +{{code language="xml"}}<remove_value name="$foo" /><remove_value name="$list.{1}" /><remove_value name="$table.$foo" />{{/code}}\\ 1190 1190 1191 1191 Removing an entry from a list shifts all following elements down by one. If you want to clear an entry without removing it from the list, just use <set_value> instead. 1192 1192 1193 -(% style="color: rgb(0,0,255);text-decoration: none;" %) 1194 1194 \\\\\\(% id="accessing-remote-variables" %) 1195 1195 1196 1196 == Accessing remote variables == ... ... @@ -1197,40 +1197,37 @@ 1197 1197 1198 1198 You can also read and write variables in other cues by using the variable name as property key: 1199 1199 1200 -{{code}} <set_value┬áname="OtherCue.$foo"┬ámin="0.0"┬ámax="1.0"/><set_value┬áname="md.OtherScript.YetAnotherCue.$bar"┬áexact="OtherCue.$foo"/>{{/code}}1199 +{{code language="xml"}}<set_value name="OtherCue.$foo" min="0.0" max="1.0" /><set_value name="md.OtherScript.YetAnotherCue.$bar" exact="OtherCue.$foo" />{{/code}} 1201 1201 1202 1202 Instead of referencing a cue by name, you could also reference it via a keyword or another variable: 1203 1203 1204 -{{code}} <set_value┬áname="static.$counter"┬áoperation="add"/><set_value┬áname="parent.$foo"┬áexact="42"/><set_value┬áname="this.$bar"┬áexact="parent"/><set_value┬áname="$baz"┬áexact="this.$bar.$foo"/>{{/code}}1203 +{{code language="xml"}}<set_value name="static.$counter" operation="add" /><set_value name="parent.$foo" exact="42" /><set_value name="this.$bar" exact="parent" /><set_value name="$baz" exact="this.$bar.$foo" />{{/code}} 1205 1205 1206 -(% style="color: rgb(0,0,255);text-decoration: none;" %) 1207 1207 \\\\\\(% id="namespaces" %) 1208 1208 1209 1209 == Namespaces == 1210 1210 1211 -In the examples above, a variable was written to and read from the ΓÇ£thisΓÇ¥cue. This can be necessary: the expressionΓÇ£$fooΓÇ¥may be different from the expressionΓÇ£this.$fooΓÇ¥. The reason for that are namespaces.1209 +In the examples above, a variable was written to and read from the "this" cue. This can be necessary: the expression "$foo" may be different from the expression "this.$foo". The reason for that are namespaces. 1212 1212 1213 1213 Consider this case: 1214 1214 1215 -{{code}} <cue┬áname="Root">┬á<actions>┬á┬á<set_value┬áname="$foo"/>┬á</actions>┬á<cues>┬á┬á<cue┬áname="SubCue">[...]┬á┬á</cue>┬á</cues></cue>{{/code}}1213 +{{code language="xml"}}<cue name="Root"> <actions> <set_value name="$foo" /> </actions> <cues> <cue name="SubCue"> [...] </cue> </cues></cue>{{/code}} 1216 1216 1217 -When the root cue creates $foo, the variable is stored in the Root cue directly. But SubCue and its descendants will also need access to $foo. Of course they could write ΓÇ£parent.$fooΓÇ¥orΓÇ£Root.$fooΓÇ¥, but since itΓÇÖs very common to have a single location for most variables in the whole cue tree, the easy solution is to write justΓÇ£$fooΓÇ¥- because variable names are looked up in the **namespace cue**, which is the root by default. Also newly created variables end up in the namespace, and not inΓÇ£thisΓÇ¥cue.1215 +When the root cue creates $foo, the variable is stored in the Root cue directly. But SubCue and its descendants will also need access to $foo. Of course they could write "parent.$foo" or "Root.$foo", but since it's very common to have a single location for most variables in the whole cue tree, the easy solution is to write just "$foo" - because variable names are looked up in the **namespace cue**, which is the root by default. Also newly created variables end up in the namespace, and not in "this" cue. 1218 1218 1219 -You can also use the keyword ΓÇ£**namespace**ΓÇ¥in expressions to get the namespace cue.1217 +You can also use the keyword "**namespace**" in expressions to get the namespace cue. 1220 1220 1221 1221 (% id="defining-a-cues-namespace" %) 1222 1222 1223 -=== Defining a cue ΓÇÖs namespace ===1221 +=== Defining a cue's namespace === 1224 1224 1225 1225 When writing a cue, you can specify what the namespace of the cue should be, by adding the //**namespace**// attribute. The following values are possible: 1226 1226 1227 -* **this**: Use ΓÇ£thisΓÇ¥cue as namespace, even for instances: $foo == this.$foo1228 -* **static**: Same as ΓÇ£thisΓÇ¥, but when instantiated, use the static cue: $foo == static.$foo1229 -* **default**: The namespace is inherited from the parent cue. The default for root cues and for libraries is the same as ΓÇ£staticΓÇ¥.1225 +* **this**: Use "this" cue as namespace, even for instances: $foo == this.$foo 1226 +* **static**: Same as "this", but when instantiated, use the static cue: $foo == static.$foo 1227 +* **default**: The namespace is inherited from the parent cue. The default for root cues and for libraries is the same as "static". 1230 1230 1231 -(% style="color: rgb(0,0,255);text-decoration: none;" %) 1232 1232 1230 +{{warning}}Although in general the expression "$foo == namespace.$foo" is true, there is one exception: When library parameters are evaluated in the referencing cue, variables are resolved using the parent's namespace. However, the referencing cue creates a new namespace, so the namespace keyword already points to the library, not to the parent's namespace. Example: 1233 1233 1234 -{{warning body="Although in general the expression ΓÇ£$foo == namespace.$fooΓÇ¥ is true, there is one exception: When library parameters are evaluated in the referencing cue, variables are resolved using the parentΓÇÖs namespace. However, the referencing cue creates a new namespace, so the namespace keyword already points to the library, not to the parentΓÇÖs namespace. Example: 1235 - 1236 -<code><cue┬áname="LibRef"┬áref="Lib">┬á <param┬áname="Param1"┬ávalue="$foo" /> <!-- $foo from parent namespace -->┬á <param┬áname="Param2"┬ávalue="namespace.$foo" /> <!-- LibRef.$foo (error) --></cue></code>"/}} 1232 +<code language="xml"><cue name="LibRef" ref="Lib"> <param name="Param1" value="$foo" /> <!-- $foo from parent namespace --> <param name="Param2" value="namespace.$foo" /> <!-- LibRef.$foo (error) --></cue></code>{{/warning}}