Skip to Content

Changes for page Mission Director Guide

Last modified by Klaus Meyer on 2025/03/31 16:39
From version 32939.1
edited by Daniel Turner
on 2023/08/22 16:50
Change comment: There is no comment for this version
To version 32936.1
edited by Daniel Turner
on 2023/08/22 16:40
Change comment: There is no comment for this version

Summary

Details

Page properties
Tags
... ... @@ -1,1 +1,1 @@
1 -Broken_macro/anchor|Broken macro/anchor
1 +Broken_macro/anchor
Content
... ... @@ -1,12 +1,11 @@
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.\\
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[[ (% style="color:#000099; 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  
7 7  {{{The general MD scripting system is the same in XR and X4, so this guide applies to both games. However, each game has its own set of supported script features (i.e. actions, conditions and properties), so in general scripts from different games are not compatible.}}}
8 8  
9 -(% id="md-scripts" %)
10 10  
11 11  {{toc/}}
12 12  
... ... @@ -16,15 +16,13 @@
16 16  
17 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.
18 +To edit MD scripts, an XML editing tool is needed. Microsoft Visual Studio (if available) or [[(% style="color:#000099; 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  
23 -{{note}}
24 -Even if your script is free of XSD errors, that does not mean that the script syntax is correct. For example, there are XML elements that require at least one of multiple attributes, but this requirement cannot be reflected in a schema (apart from documentation text). Please notice the XSD documentation of the elements and attributes, e.g. displayed via tooltips in Visual Studio / Visual Web Developer. Please also note additional requirements for MD cue attributes in this guide (see [[NULL|Conditions]]).
22 +{{note body="Even if your script is free of XSD errors, that does not mean that the script syntax is correct. For example, there are XML elements that require at least one of multiple attributes, but this requirement cannot be reflected in a schema (apart from documentation text). Please notice the XSD documentation of the elements and attributes, e.g. displayed via tooltips in Visual Studio / Visual Web Developer. Please also note additional requirements for MD cue attributes in this guide (see [[NULL|Conditions]]).
25 25  
26 -To check for errors, please pay attention to in-game error messages that are produced while your script is imported, and run-time errors while the script runs. The XSD files can help you a lot, but you should not rely on the absence of XSD errors."
27 -{{/note}}
24 +To check for errors, please pay attention to in-game error messages that are produced while your script is imported, and run-time errors while the script runs. The XSD files can help you a lot, but you should not rely on the absence of XSD errors."/}}
28 28  
29 29  == Script debug output ==
30 30  
... ... @@ -32,33 +32,37 @@
32 32  
33 33  To collect all messages in a file, start the game with the following parameters on the command line:
34 34  
35 -{{code}}-logfile debuglog.txt{{/code}}
32 +{{code}}
33 +-logfile debuglog.txt
34 +{{/code}}
36 36  
37 37  All messages, including enabled non-error messages, will be written into the log file. You can find it in your personal folder, where your save folder is located. To enable scripting-specific debug messages, add the following to the command line:
38 38  
39 -{{code}}-debug scripts{{/code}}
38 +{{code}}
39 +-debug scripts
40 +{{/code}}
40 40  
41 -Other debug filters other than "scripts" can be enabled by repeating the -debug command for each filter name, but that is rarely needed for scripting.\\
42 +Other debug filters other than "scripts" can be enabled by repeating the -debug command for each filter name, but that is rarely needed for scripting.
42 42  
43 -The script action <debug_text> can be used to print debug messages from within a script.\\
44 +The script action <debug_text> can be used to print debug messages from within a script.
44 44  
45 45  = MD script structure =
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:
50 +The XML root node of an MD file is called mdscript and looks like this:
50 50  
51 51  {{code language="xml"}}
52 -<?xml version="1.0" encoding="utf-8"?>
53 +
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.
57 +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  
60 60  {{code language="xml"}}
61 -<?xml version="1.0" encoding="utf-8"?>
62 +
62 62  <mdscript name="ScriptName" ...>
63 63   <cues>
64 64   <cue name="RootCue1"> [...]
... ... @@ -77,14 +77,12 @@
77 77  
78 78  * **Disabled**: The parent cue has not become active yet, so this cue is basically non-existing.
79 79  * **Waiting**: Either this is a root cue, or the parent has become active. The cue is checking its conditions and will become active when they are met.
80 -* **Active**: The cue is about to perform the actions. Child cues have entered the waiting state.\\
81 +* **Active**: The cue is about to perform the actions. Child cues have entered the waiting state.
81 81  
82 82  
83 -
84 84  * **Complete**: The cue has finished performing its actions.
85 85  * **Cancelled**: The cue has been cancelled. This state cannot normally be reached but only if a cue actively cancels itself or another cue. No condition checks or actions are performed in this cue or any sub-(sub-)cue.
86 86  
87 -\\
88 88  
89 89  {{note body="There can be a delay between the activation and performing the actions if the &lt;delay&gt; tag is used. In this case, sub-cues will be enter the waiting state before the parent's actions are performed.<br />"/}}
90 90  
... ... @@ -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.
112 +**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,10 +150,9 @@
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).\\
152 +* 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 -
157 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).
... ... @@ -216,7 +216,7 @@
216 216  
217 217  
218 218  
219 -{{note body="Messages printed with &lt;debug_text&gt; are usually only visible when the ΓÇ£scriptsΓÇ¥ debug filter is enabled, see [[NULL|Script debug output]]."/}}
217 +{{note body="Messages printed with &lt;debug_text&gt; are usually only visible when the scripts debug filter is enabled, see [[NULL|Script debug output]]."/}}
220 220  
221 221  
222 222  
... ... @@ -297,7 +297,7 @@
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).
299 299  * You //can// access variables in the library root but generally this should be avoided in favor of parameterizing the library!
300 -** there are some cases where you do want to access these variables directly, for example for maintaining savegame compatibility when patching.(% id="library-parameters" %)
298 +** there are some cases where you do want to access these variables directly, for example for maintaining savegame compatibility when patching.
301 301  
302 302  == Library Parameters ==
303 303  
... ... @@ -342,8 +342,8 @@
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.
343 +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:#000000; 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.**
344 +\\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,7 +350,7 @@
350 350  
351 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.
352 352  
353 -{{info body="&lt;cancel_cue&gt; and &lt;reset_cue&gt; 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."/}}
351 +{{info body="&lt;cancel_cue&gt; and &lt;reset_cue&gt; 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  
... ... @@ -362,13 +362,13 @@
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.
363 +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  
369 369  Example chart:
370 370  
371 -[[~[~[image:ARCHIVE_XRWIKI_Modding_support_Mission_Director_GuideMission_Director_Guide_-_Instantiation.png~|~|width="800px"~]~]>>attach:ARCHIVE_XRWIKI_Modding_support_Mission_Director_GuideMission_Director_Guide_-_Instantiation.png]]\\
369 +[[~[~[image:ARCHIVE_XRWIKI_Modding_support_Mission_Director_GuideMission_Director_Guide_-_Instantiation.png~|~|width="800px"~]~]>>attach:ARCHIVE_XRWIKI_Modding_support_Mission_Director_GuideMission_Director_Guide_-_Instantiation.png]]
372 372  
373 373  This chart represents a script of 5 cues: Foo, Bar, SubBar, Baz and SubBaz. Continuous arrows denote parent-child relationship. Foo and Baz are instantiating cues (highlighted with red border). The static cues always exist, although static children of instantiating cues can never become active. Instances only exist as long as they are needed.
374 374  
... ... @@ -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.
376 +* In the inst-2 tree: SubBar in an expression will be resolved to SubBar (inst 2).
377 +* 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.
378 +* In the inst-2a tree: SubBaz in an expression will be resolved to SubBaz (inst 2a)
379 +* In the inst-2a tree: Bar in an expression will be resolved to Bar (inst 2) because Foo (inst 2) is a common ancestor.
380 +* 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  
... ... @@ -393,11 +393,11 @@
393 393  
394 394  Some additional common pitfalls with respect to instantiation are listed here. There may be more.
395 395  
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:\\
394 +* **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}}&lt;debug_text text=&quot;static.$foo&quot;/&gt;{{/code}}(% style="color: rgb(0,0,255);text-decoration: none;" %)
396 +(% style="color:#0000ff; text-decoration:none" %){{code}}&lt;debug_text text=&quot;static.$foo&quot;/&gt;{{/code}}
399 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}}&lt;set_value name=&quot;$foo&quot; exact=&quot;static.$foo&quot;/&gt;{{/code}}
398 +\\{{code}}&lt;set_value name=&quot;$foo&quot; exact=&quot;static.$foo&quot;/&gt;{{/code}}
401 401  
402 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 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.
... ... @@ -409,11 +409,10 @@
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ΓÇ¥)
410 +* {{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 -
417 417  {{note body="Since octal numbers are hardly ever used (usually unknowingly), the parser is will produce a warning if an octal number is encountered."/}}
418 418  
419 419  
... ... @@ -425,12 +425,11 @@
425 425  * {{code}}'String with a line break\n'{{/code}}
426 426  
427 427  
428 -
429 429  {{note 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 '''&lt; &gt; &quot; &amp;''' in an expression string (or anywhere else in an XML attribute value), youΓÇÖll have to escape them as '''&amp;lt; &amp;gt; &amp;quot; &amp;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."/}}
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:
429 +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)
... ... @@ -482,7 +482,7 @@
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 supported
481 +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  (((
... ... @@ -552,7 +552,7 @@
552 552  {{code}}1 ge 3{{/code}}
553 553  \\{{code}}1 &amp;gt;= 3{{/code}}|{{code}}false{{/code}}|Greater than or equal to
554 554  |(((
555 -= =
551 += =
556 556  )))|binary|{{code}}1 + 1 == 2.0{{/code}}|{{code}}true{{/code}}|Equal to
557 557  |~!=|binary|{{code}}1 + 1 != 2.0{{/code}}|{{code}}false{{/code}}|Not equal to
558 558  |and|binary|{{code}}true and false{{/code}}|{{code}}false{{/code}}|Logical AND (short-circuit semantics)
... ... @@ -564,9 +564,8 @@
564 564  \\{{code}}if 1 == 2 then 'F' else 'T'{{/code}}|
565 565  {{code}}null{{/code}}
566 566  \\{{code}}'T'{{/code}}|Conditional operator ("inline if")
563 +)))
567 567  
568 -)))(% id="operator-precedence-rules" %)
569 -(%%)
570 570  
571 571  === Operator precedence rules ===
572 572  
... ... @@ -582,13 +582,12 @@
582 582  * or
583 583  * if/then/else (lowest precedence)
584 584  
585 -(% id="type-conversion" %)
586 586  
587 587  === Type conversion ===
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.
585 +* 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.
... ... @@ -601,7 +601,7 @@
601 601  * {{code}}(1 + 1)f{{/code}} Γƒ╣ {{code}}2f{{/code}} Γƒ╣ {{code}}2.0{{/code}}
602 602  * {{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.)
598 +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  
... ... @@ -612,7 +612,6 @@
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  
615 -(% id="boolean-operators" %)
616 616  
617 617  === Boolean operators ===
618 618  
... ... @@ -619,20 +619,16 @@
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**.
615 +* 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 operation
617 +* 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
625 625  ** 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 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.
628 628  
629 629  
623 +== Strings and formatting ==
630 630  
631 -(% id="categorybroken_macroanchorstrings-and-formatting" %)== Strings and formatting==
632 -(% id="categorybroken_macroanchorstrings-and-formatting" %)
633 -
634 -{{{==}}}
635 -
636 636  You can concatenate string literals using the + operator, but there is also a printf-like formatting syntax, which is easier to use than concatenating lots of small pieces:
637 637  
638 638  * {{code}}'The %1 %2 %3 jumps over the %5 %4'.['quick', 'brown', 'fox', 'dog', 'lazy']{{/code}}
... ... @@ -653,24 +653,22 @@
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.
645 +* 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 -
661 661  {{info body="There are also special methods to [[NULL|format money values and time values]] using the &quot;formatted&quot; property."/}}
662 662  
663 663  
664 664  
665 -\\
666 666  
667 -(% id="categorybroken_macroanchorlists" %)
668 668  
655 +
669 669  == Lists ==
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 ΓÇ£[ ]ΓÇ¥.
660 +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 675  {{note 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."/}}
676 676  
... ... @@ -686,42 +686,37 @@
686 686  
687 687  
688 688  
689 -\\
690 690  
691 -(% id="categorybroken_macroanchortables" %)
692 692  
678 +
693 693  == Tables ==
694 694  
695 -Tables are associative arrays - they are like lists, but you can assign values to (almost) arbitrary keys, not just to index numbers. A table is constructed within an expression using the [[table~[~] syntax>>MediaWiki.NULL]]. See the section about [[value properties>>MediaWiki.NULL]] for how to access the contents of a table. [[Creating and removing entries>>MediaWiki.NULL]] works similarly to lists, but instead of inserting, you simply assign a value to a table key. If the key does not exist yet, it will be created.\\
681 +Tables are associative arrays - they are like lists, but you can assign values to (almost) arbitrary keys, not just to index numbers. A table is constructed within an expression using the [[table~[~] syntax>>MediaWiki.NULL]]. See the section about [[value properties>>MediaWiki.NULL]] for how to access the contents of a table. [[Creating and removing entries>>MediaWiki.NULL]] works similarly to lists, but instead of inserting, you simply assign a value to a table key. If the key does not exist yet, it will be created.
696 696  
697 697  Almost all values are allowed as table keys, but there are a few exceptions:
698 698  
699 699  * Strings must start with '$', like variables
700 700  * null cannot be used as table key (but the number 0 is valid)
701 -* Lists, tables, groups and buildplans cannot be used as table keys\\
687 +* Lists, tables, groups and buildplans cannot be used as table keys
702 702  
703 703  
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 707  * {{code}}table[]{{/code}} Γƒ╣ creates an empty table
708 -* {{code}}table[{0} = null]{{/code}} ⟹ creates a table that maps the number 0 to null\\
693 +* {{code}}table[{0} = null]{{/code}} ⟹ creates a table that maps the number 0 to null
709 709  
710 710  
711 -
712 712  * {{code}}table[{'$foo'} = 'bar']{{/code}} Γƒ╣ a table that maps the string '$foo' to the string 'bar'
713 713  * {{code}}table[$foo = 'bar']{{/code}} Γƒ╣ exactly the same, just a shorter notation for string keys
714 714  * {{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\\
699 +* {{code}}table[{1} = [], {2} = table[]] {{/code}} ⟹ a table that maps 1 to an empty list and 2 to an empty table
716 716  
717 717  
702 +Just like lists, tables are stored as references, so it's possible that multiple variables reference the same table (see above).
703 +
718 718  
719 -Just like lists, tables are stored as references, so it's possible that multiple variables reference the same table (see above).\\
720 720  
721 -\\
722 722  
723 -(% id="categorybroken_macroanchorvalue-properties" %)
724 -
725 725  == Value properties ==
726 726  
727 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.
... ... @@ -742,30 +742,27 @@
742 742  * {{code}}[100, 200, 300, 400].{1}{{/code}} Γƒ╣ 100 (reading the first element)
743 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 744  * {{code}}[].{'count'}{{/code}} Γƒ╣ 0
745 -* {{code}}table[{21} = 42].{21}{{/code}} ⟹ 42\\
727 +* {{code}}table[{21} = 42].{21}{{/code}} ⟹ 42
746 746  
747 747  
730 +In most cases the property key is a fixed string, like name or class. You can write this like above:
748 748  
749 -In most cases the property key is a fixed string, like ΓÇ£nameΓÇ¥ or ΓÇ£classΓÇ¥. You can write this like above:
750 -
751 751  * {{code}}[42].{'count'}{{/code}}
752 752  * {{code}}$ship.{'name'}{{/code}}
753 -* {{code}}$ship.{'class'} {{/code}}
754 -* {{code}}table[$foo='bar'].{'$foo'}{{/code}}\\
734 +* {{code}}$ship.{'class'} {{/code}}
735 +* {{code}}table[$foo='bar'].{'$foo'}{{/code}}
755 755  
756 756  
757 -
758 758  But it is easier just to write the property key without braces, which is equivalent:
759 759  
760 760  * {{code}}[0].count{{/code}}
761 761  * {{code}}$ship.name{{/code}}
762 762  * {{code}}$ship.class{{/code}}
763 -* {{code}}table[$foo='bar'].$foo{{/code}}\\
743 +* {{code}}table[$foo='bar'].$foo{{/code}}
764 764  
765 765  
746 +(In this case, $ship is a variable. All variables start with a $, so they cannot be confused with keywords.)
766 766  
767 -(In this case, $ship is a variable. All variables start with a ΓÇ£$ΓÇ¥, so they cannot be confused with keywords.)
768 -
769 769  A list has even more properties:
770 770  
771 771  **random'** returns a randomly chosen element (which requires that the list is non-empty)
... ... @@ -791,42 +791,36 @@
791 791  * '**clone'** creates a shallow copy of the table
792 792  * '**keys'** allows you to access data about the table's keys
793 793  
794 -However, 'keys' alone will not give you a result. 'keys' must be followed by another keyword to retrieve the desired information, for example:\\
773 +However, 'keys' alone will not give you a result. 'keys' must be followed by another keyword to retrieve the desired information, for example:
795 795  
796 796  
797 797  
798 -* {{code}}$table.keys.list{{/code}}: Yields a list of all keys in the table (reliably sorted by key if all keys are numeric)\\
777 +* {{code}}$table.keys.list{{/code}}: Yields a list of all keys in the table (reliably sorted by key if all keys are numeric)
799 799  
800 800  
801 -
802 802  * {{code}}$table.keys.sorted{{/code}}: Yields a list of all keys in the table, sorted by their associated values (which requires that all values are numeric)
803 803  * {{code}}$table.keys.random{{/code}}: A randomly chosen key (which requires that the table is non-empty)
804 804  
805 805  
806 -
807 807  {{note 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'.{[...]}."/}}
808 808  
809 809  
810 810  
811 -(% id="lookup-tests-and-suppressing-errors" %)=== Lookup tests and suppressing errors
788 +=== Lookup tests and suppressing errors ===
812 812  
790 +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:
813 813  
814 -{{{===}}}
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:
817 -
818 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 error
819 819  * {{code}}$list.{5}?{{/code}} Γƒ╣ true if $list exists and has the property 5, false otherwise
820 -* {{code}}$table.$key?{{/code}} ⟹ Analogously, true if $table exists and has the string property '$key'\\
794 +* {{code}}$table.$key?{{/code}} ⟹ Analogously, true if $table exists and has the string property '$key'
821 821  
822 822  
823 -
824 824  The question mark can even be applied to variables:
825 825  
826 826  * {{code}}$list{{/code}} Γƒ╣ The value stored under the name $list, or an error if there is no such variable
827 827  * {{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:
802 +To look up the value of a property although it may not exist, you can use the at-sign @ as prefix:
830 830  
831 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 832  * {{code}}@$list{{/code}} Γƒ╣ The list if this variable exists, null otherwise
... ... @@ -834,19 +834,17 @@
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  
837 -\\
838 838  
839 -(% id="static-lookups" %)
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.
814 +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  
847 847  (% style="margin-left: 0.0px;" %)
848 848  (((
849 -\\
820 +
850 850  
851 851  
852 852  
... ... @@ -902,35 +902,31 @@
902 902  
903 903  <code>(typeof $value).isstring</code>"/}}
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."/}}
876 +{{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."/}}
906 906  
907 -\\
908 908  
909 909  
910 910  
911 -(% id="player-properties" %)
912 912  
913 913  === Player properties ===
914 914  
915 -You can access many player-related game properties via the keyword ΓÇ£playerΓÇ¥:
884 +You can access many player-related game properties via the keyword player:
916 916  
917 917  * player.**name**: The playerΓÇÖs name
918 918  * player.**age**: The passed in-game time since game start
919 919  * player.**money**: The money in the playerΓÇÖs account
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\\
889 +* 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  
923 -
924 924  * player.**primaryship**: The player's own ship (but the player is not necessarily on board)
925 -* player.**entity**: The actual player object\\
893 +* player.**entity**: The actual player object
926 926  
927 927  
928 -
929 929  * player.**zone**, player.**sector**, player.**cluster**, player.**galaxy**: Location of the player entity
930 930  * player.**copilot**: The co-pilot NPC
931 931  
932 932  The game consists of objects of different classes (zones, ships, stations, NPCs). They have the common datatype "component", however, they have different properties, e.g. NPCs have the property "race", but ships don't.
933 -\\(% id="safe-properties" %)
900 +
934 934  
935 935  === Safe properties ===
936 936  
... ... @@ -943,27 +943,24 @@
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.
913 +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 -(% id="categorybroken_macroanchormoney-and-time-formatting" %)=== Money and time formatting
949 949  
916 +=== Money and time formatting ===
950 950  
951 -{{{===}}}
952 -
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}}
957 -* {{code}}$money.formatted.default{{/code}} (using default format string '%s')\\
921 +* {{code}}$money.formatted.{'formatstring'} {{/code}}
922 +* {{code}}$money.formatted.default{{/code}} (using default format string '%s')
958 958  
959 959  
960 -
961 961  * {{code}}$time.formatted.{'formatstring'}{{/code}}
962 -* {{code}}$time.formatted.default{{/code}}  (using default format string '%T')
926 +* {{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  
966 -When formatting the money value, any specifier (such as '%s') in the format string is replaced by the money value, so usually the format string only consists of this one specifier. The following modifiers can be used between '%' and the specifier character, to enable formatting options:\\
930 +When formatting the money value, any specifier (such as '%s') in the format string is replaced by the money value, so usually the format string only consists of this one specifier. The following modifiers can be used between '%' and the specifier character, to enable formatting options:
967 967  
968 968  
969 969  
... ... @@ -981,14 +981,13 @@
981 981  * %G: Credits (truncated) in Giga format
982 982  * %T: Credits (truncated) in Tera format
983 983  * %Cr: Localised "Cr" string
984 -* %%: A % sign\\
948 +* %%: A % sign
985 985  
986 986  
951 +Examples:
987 987  
988 -Examples:\\
989 989  
990 990  
991 -
992 992  * {{code}}(1234Cr).formatted.{'%s'}{{/code}}Γƒ╣{{code}}'1,234'{{/code}}
993 993  * {{code}}(1234Cr).formatted.default{{/code}}Γƒ╣{{code}}'1,234'{{/code}} (same as {'%s'})
994 994  * {{code}}(1234Cr).formatted.{'%.s %Cr'}{{/code}}Γƒ╣{{code}}'1,234.00 Cr'{{/code}}
... ... @@ -1004,13 +1004,12 @@
1004 1004  * {{code}}(151s).formatted.{'%.3T'}{{/code}} Γƒ╣ {{code}}'00:02:31.000'{{/code}}
1005 1005  * {{code}}(151s).formatted.{'%h:%M'}{{/code}} Γƒ╣ {{code}}'0:02'{{/code}}
1006 1006  
1007 -(% id="complete-property-documentation" %)
1008 1008  
1009 1009  === Complete property documentation ===
1010 1010  
1011 1011  To access the script property documentation that is included in the game, you can extract the required files from the game's catalog files using the [[X Catalog Tool>>url:https://forum.egosoft.com/viewtopic.php?t=363625]]. Extract the HTML file __scriptproperties.html__ in the game's root folder, and all files in the "libraries" sub-folder. For resolving text references in the browser automatically, also extract 0001-L044.xml in the "t" sub-folder.
1012 1012  
1013 -The raw documentation data is located in libraries/scriptproperties.xml, but it is recommended to open scriptproperties.html in a browser.\\
975 +The raw documentation data is located in libraries/scriptproperties.xml, but it is recommended to open scriptproperties.html in a browser.
1014 1014  
1015 1015  
1016 1016  
... ... @@ -1021,33 +1021,28 @@
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:
986 +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 variable
1028 -* To see the properties of a base keyword or data type, enter a dot (ΓÇ£.ΓÇ¥)
989 +* Enter $ followed by the data type you are looking for (e.g. $ship), as if it were a variable
990 +* 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 property
992 +* You can also enter a dot (.) as first character to search globally for a property
1031 1031  
1032 -\\
1033 1033  
1034 1034  
1035 1035  
1036 -{{note 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."/}}
997 +{{note 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."/}}
1037 1037  
1038 1038  
1039 1039  
1040 -\\
1041 1041  
1042 -(% id="md-refreshing-and-patching" %)
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.
1005 +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 -\\
1049 1049  
1050 -(% id="details-and-restrictions" %)
1051 1051  
1052 1052  == Details and restrictions ==
1053 1053  
... ... @@ -1068,7 +1068,6 @@
1068 1068  * Changing instantiate="false" to "true" turns the cue into "waiting" state if it was active or complete before.
1069 1069  * Changing instantiate="true" to "false" removes all instantiated cues and their descendants.
1070 1070  
1071 -\\
1072 1072  
1073 1073  
1074 1074  
... ... @@ -1078,17 +1078,17 @@
1078 1078  
1079 1079  
1080 1080  
1081 -\\
1082 1082  
1083 -(% id="patching" %)
1084 1084  
1085 1085  == Patching ==
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}}&lt;cue [...] version=&quot;42&quot;&gt;  &lt;conditions&gt; [...] &lt;/conditions&gt;  &lt;actions&gt; [...] &lt;/actions&gt;  &lt;patch sinceversion=&quot;42&quot;&gt;    [patch actions]  &lt;/patch&gt;&lt;/cue&gt;{{/code}}
1043 +{{code}}
1044 +&lt;cue [...] version=&quot;42&quot;&gt; &lt;conditions&gt; [...] &lt;/conditions&gt; &lt;actions&gt; [...] &lt;/actions&gt; &lt;patch sinceversion=&quot;42&quot;&gt; [patch actions] &lt;/patch&gt;&lt;/cue&gt;
1045 +{{/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.
1047 +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  
... ... @@ -1096,58 +1096,64 @@
1096 1096  
1097 1097  
1098 1098  
1099 -\\
1100 1100  
1101 -(% id="common-attribute-groups" %)
1102 1102  
1103 1103  = Common attribute groups =
1104 1104  
1105 1105  There are many commonly used actions and conditions which share groups of attributes. The most important ones are explained here.
1106 1106  
1107 -\\
1108 1108  
1109 -(% id="categorybroken_macroanchorvalue-comparisons" %)
1110 1110  
1111 1111  == Value comparisons ==
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}}&lt;check_value value=&quot;$ware == ware.silicon and $amount != 0&quot;/&gt;{{/code}}
1067 +{{code}}
1068 +&lt;check_value value=&quot;$ware == ware.silicon and $amount != 0&quot;/&gt;
1069 +{{/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}}&lt;check_value value=&quot;FooCue.state&quot; exact=&quot;cuestate.complete&quot;/&gt;&lt;check_value value=&quot;$foo.count&quot; min=&quot;5&quot;/&gt;&lt;check_value value=&quot;$foo&quot; max=&quot;player.age + 1min&quot;/&gt;&lt;check_value value=&quot;player.money&quot; min=&quot;300Cr&quot; max=&quot;600Cr&quot;/&gt;&lt;check_value value=&quot;$method&quot; list=&quot;[killmethod.hitbymissile, killmethod.collected]&quot;/&gt;&lt;check_value value=&quot;$attention&quot; min=&quot;attention.visible&quot;/&gt;{{/code}}
1073 +{{code}}
1074 +&lt;check_value value=&quot;FooCue.state&quot; exact=&quot;cuestate.complete&quot;/&gt;&lt;check_value value=&quot;$foo.count&quot; min=&quot;5&quot;/&gt;&lt;check_value value=&quot;$foo&quot; max=&quot;player.age + 1min&quot;/&gt;&lt;check_value value=&quot;player.money&quot; min=&quot;300Cr&quot; max=&quot;600Cr&quot;/&gt;&lt;check_value value=&quot;$method&quot; list=&quot;[killmethod.hitbymissile, killmethod.collected]&quot;/&gt;&lt;check_value value=&quot;$attention&quot; min=&quot;attention.visible&quot;/&gt;
1075 +{{/code}}
1120 1120  
1121 1121  {{note 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."/}}
1122 1122  
1123 1123  
1124 1124  
1125 -\\
1126 1126  
1127 -(% id="categorybroken_macroanchorrandom-ranges" %)
1128 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}}&lt;set_value name=&quot;$race&quot; exact=&quot;race.teladi&quot;/&gt;{{/code}}
1087 +{{code}}
1088 +&lt;set_value name=&quot;$race&quot; exact=&quot;race.teladi&quot;/&gt;
1089 +{{/code}}
1134 1134  
1135 1135  To select a random element from a list, this syntax can be used:
1136 1136  
1137 -{{code}}&lt;set_value name=&quot;$prime&quot; list=&quot;[2, 3, 5, 7, 11]&quot;/&gt;{{/code}}
1093 +{{code}}
1094 +&lt;set_value name=&quot;$prime&quot; list=&quot;[2, 3, 5, 7, 11]&quot;/&gt;
1095 +{{/code}}
1138 1138  
1139 1139  To get a random number within a given range, you can use min/max:
1140 1140  
1141 -{{code}}&lt;set_value name=&quot;$foo&quot; min=&quot;-20&quot; max=&quot;20&quot;/&gt;&lt;set_value name=&quot;$timeout&quot; max=&quot;20s&quot;/&gt;{{/code}}
1099 +{{code}}
1100 +&lt;set_value name=&quot;$foo&quot; min=&quot;-20&quot; max=&quot;20&quot;/&gt;&lt;set_value name=&quot;$timeout&quot; max=&quot;20s&quot;/&gt;
1101 +{{/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).
1105 +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}}&lt;set_value name=&quot;$foo&quot; min=&quot;-20&quot; max=&quot;20&quot; profile=&quot;profile.increasing&quot; scale=&quot;4&quot;/&gt;{{/code}}
1107 +{{code}}
1108 +&lt;set_value name=&quot;$foo&quot; min=&quot;-20&quot; max=&quot;20&quot; profile=&quot;profile.increasing&quot; scale=&quot;4&quot;/&gt;
1109 +{{/code}}
1148 1148  
1149 -(% style="color: rgb(0,0,255);text-decoration: none;" %) 
1150 -\\(% id="variables-and-namespaces" %)
1111 +(% style="color:#0000ff; text-decoration:none" %) (%%)
1112 +
1151 1151  
1152 1152  = Variables and namespaces =
1153 1153  
... ... @@ -1154,83 +1154,102 @@
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 1156  (% style="color: rgb(0,0,255);text-decoration: none;" %)
1157 -\\\\\\(% id="categorybroken_macroanchorcreating-and-removing-variables" %)
1158 1158  
1120 +\\
1121 +
1159 1159  == Creating and removing variables ==
1160 1160  
1161 1161  {{{You can create variables with certain actions and conditions, such as the &lt;set_value&gt; action:}}}
1162 1162  
1163 -{{code}} &lt;set_value name=&quot;$foo&quot; exact=&quot;$bar + 1&quot; /&gt;{{/code}}
1126 +{{code}}
1127 + &lt;set_value name=&quot;$foo&quot; exact=&quot;$bar + 1&quot; /&gt;
1128 +{{/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>.)
1130 +<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.
1132 +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}}&lt;set_value name=&quot;$foo&quot; operation=&quot;add&quot; /&gt;{{/code}}
1134 +{{code}}
1135 +&lt;set_value name=&quot;$foo&quot; operation=&quot;add&quot; /&gt;
1136 +{{/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}}&lt;set_value name=&quot;$list.{1}&quot; exact=&quot;42&quot; /&gt;&lt;set_value name=&quot;$table.$foo&quot; exact=&quot;42&quot; /&gt;{{/code}}\\
1140 +{{code}}
1141 +&lt;set_value name=&quot;$list.{1}&quot; exact=&quot;42&quot; /&gt;&lt;set_value name=&quot;$table.$foo&quot; exact=&quot;42&quot; /&gt;
1142 +{{/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}}&lt;set_value name=&quot;$list.{1}&quot; exact=&quot;42&quot; operation=&quot;insert&quot; /&gt;{{/code}}
1146 +{{code}}
1147 +&lt;set_value name=&quot;$list.{1}&quot; exact=&quot;42&quot; operation=&quot;insert&quot; /&gt;
1148 +{{/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}}&lt;set_value name=&quot;$list.{$list.count + 1}&quot; exact=&quot;42&quot; operation=&quot;insert&quot; /&gt;&lt;append_to_list name=&quot;$list&quot; exact=&quot;42&quot; /&gt;{{/code}}
1154 +{{code}}
1155 +&lt;set_value name=&quot;$list.{$list.count + 1}&quot; exact=&quot;42&quot; operation=&quot;insert&quot; /&gt;&lt;append_to_list name=&quot;$list&quot; exact=&quot;42&quot; /&gt;
1156 +{{/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}}&lt;remove_value name=&quot;$foo&quot; /&gt;&lt;remove_value name=&quot;$list.{1}&quot; /&gt;&lt;remove_value name=&quot;$table.$foo&quot; /&gt;{{/code}}\\
1162 +{{code}}
1163 +&lt;remove_value name=&quot;$foo&quot; /&gt;&lt;remove_value name=&quot;$list.{1}&quot; /&gt;&lt;remove_value name=&quot;$table.$foo&quot; /&gt;
1164 +{{/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 1193  (% style="color: rgb(0,0,255);text-decoration: none;" %)
1194 -\\\\\\(% id="accessing-remote-variables" %)
1195 1195  
1170 +\\
1171 +
1196 1196  == Accessing remote variables ==
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}}&lt;set_value name=&quot;OtherCue.$foo&quot; min=&quot;0.0&quot; max=&quot;1.0&quot; /&gt;&lt;set_value name=&quot;md.OtherScript.YetAnotherCue.$bar&quot; exact=&quot;OtherCue.$foo&quot; /&gt;{{/code}}
1176 +{{code}}
1177 +&lt;set_value name=&quot;OtherCue.$foo&quot; min=&quot;0.0&quot; max=&quot;1.0&quot; /&gt;&lt;set_value name=&quot;md.OtherScript.YetAnotherCue.$bar&quot; exact=&quot;OtherCue.$foo&quot; /&gt;
1178 +{{/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}}&lt;set_value name=&quot;static.$counter&quot; operation=&quot;add&quot; /&gt;&lt;set_value name=&quot;parent.$foo&quot; exact=&quot;42&quot; /&gt;&lt;set_value name=&quot;this.$bar&quot; exact=&quot;parent&quot; /&gt;&lt;set_value name=&quot;$baz&quot; exact=&quot;this.$bar.$foo&quot; /&gt;{{/code}}
1182 +{{code}}
1183 +&lt;set_value name=&quot;static.$counter&quot; operation=&quot;add&quot; /&gt;&lt;set_value name=&quot;parent.$foo&quot; exact=&quot;42&quot; /&gt;&lt;set_value name=&quot;this.$bar&quot; exact=&quot;parent&quot; /&gt;&lt;set_value name=&quot;$baz&quot; exact=&quot;this.$bar.$foo&quot; /&gt;
1184 +{{/code}}
1205 1205  
1206 1206  (% style="color: rgb(0,0,255);text-decoration: none;" %)
1207 -\\\\\\(% id="namespaces" %)
1208 1208  
1188 +\\
1189 +
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.
1192 +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}}&lt;cue name=&quot;Root&quot;&gt;  &lt;actions&gt;    &lt;set_value name=&quot;$foo&quot; /&gt;  &lt;/actions&gt;  &lt;cues&gt;    &lt;cue name=&quot;SubCue&quot;&gt; [...]    &lt;/cue&gt;  &lt;/cues&gt;&lt;/cue&gt;{{/code}}
1196 +{{code}}
1197 +&lt;cue name=&quot;Root&quot;&gt; &lt;actions&gt; &lt;set_value name=&quot;$foo&quot; /&gt; &lt;/actions&gt; &lt;cues&gt; &lt;cue name=&quot;SubCue&quot;&gt; [...] &lt;/cue&gt; &lt;/cues&gt;&lt;/cue&gt;
1198 +{{/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.
1200 +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.
1202 +You can also use the keyword **namespace** in expressions to get the namespace cue.
1220 1220  
1221 -(% id="defining-a-cues-namespace" %)
1222 1222  
1223 1223  === 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.$foo
1228 -* **static**: Same as ΓÇ£thisΓÇ¥, but when instantiated, use the static cue: $foo == static.$foo
1229 -* **default**: The namespace is inherited from the parent cue. The default for root cues and for libraries is the same as ΓÇ£staticΓÇ¥.
1209 +* **this**: Use this cue as namespace, even for instances: $foo == this.$foo
1210 +* **static**: Same as this, but when instantiated, use the static cue: $foo == static.$foo
1211 +* **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  
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:
1215 +{{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 1235  
1236 -<code>&lt;cue name=&quot;LibRef&quot; ref=&quot;Lib&quot;&gt;  &lt;param name=&quot;Param1&quot; value=&quot;$foo&quot; /&gt; &lt;!-- $foo from parent namespace --&gt;  &lt;param name=&quot;Param2&quot; value=&quot;namespace.$foo&quot; /&gt; &lt;!-- LibRef.$foo (error) --&gt;&lt;/cue&gt;</code>"/}}
1217 +<code>&lt;cue name=&quot;LibRef&quot; ref=&quot;Lib&quot;&gt; &lt;param name=&quot;Param1&quot; value=&quot;$foo&quot; /&gt; &lt;!-- $foo from parent namespace --&gt; &lt;param name=&quot;Param2&quot; value=&quot;namespace.$foo&quot; /&gt; &lt;!-- LibRef.$foo (error) --&gt;&lt;/cue&gt;</code>"/}}