Changes for page Mission Director Guide

Last modified by Klaus Meyer on 2025/03/31 16:39

From 32956.1 to 32955.1 From 32963.1 to 32962.1

From version 32962.1

edited by Daniel Turner
on 2023/08/24 10:04

Change comment: There is no comment for this version

To version 32956.1

edited by Daniel Turner
on 2023/08/22 19:05

Change comment: There is no comment for this version

Raw
Rendered

Summary

Page properties (1 modified, 0 added, 0 removed)
Attachments (0 modified, 0 added, 1 removed)
- Mission Director Guide - Instantiation.png

Details

Page properties

Content

@@ -1,13 +1,12 @@
--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.
++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.\\
  An introduction to the original MD can be found in the [[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.
  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++).
--{{info}}
--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.
--{{/info}}
++{{info}}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.{{/info}}
++(% id="md-scripts" %)
  {{toc/}}
@@ -17,12 +17,12 @@
  MD files are XML files located in the game folder **md**. 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.
--To edit MD scripts, an XML editing tool is needed. Microsoft Visual Studio (if available) or [[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.
++To edit MD scripts, an XML editing tool is needed. Microsoft Visual Studio (if available) or [[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.
  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.
  {{info}}
--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 [[Conditions>>doc:||anchor="HConditions" style="outline-width: 0px !important; user-select: auto !important;"]]).
++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]]).
  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."
  {{/info}}
@@ -33,19 +33,15 @@
  To collect all messages in a file, start the game with the following parameters on the command line:
--{{code language="xml"}}
---logfile debuglog.txt
--{{/code}}
++{{code language="xml"}}-logfile debuglog.txt{{/code}}
  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:
--{{code language="xml"}}
---debug scripts
--{{/code}}
++{{code language="xml"}}-debug scripts{{/code}}
--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.
++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.\\
--The script action <debug_text> can be used to print debug messages from within a script.
++The script action <debug_text> can be used to print debug messages from within a script.\\
  = MD script structure =
@@ -82,15 +82,17 @@
  * **Disabled**: The parent cue has not become active yet, so this cue is basically non-existing.
  * **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.
--* **Active**: The cue is about to perform the actions. Child cues have entered the waiting state.
++* **Active**: The cue is about to perform the actions. Child cues have entered the waiting state.\\
++
++
  * **Complete**: The cue has finished performing its actions.
  * **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.
--{{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}}
++\\
++{{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}}
++
  This is how a cue node looks like:
  {{code language="xml"}}
@@ -153,8 +153,10 @@
  If a cue has a <conditions> node without any event, it must have one of the attributes //**onfail**// or //**checkinterval**//.
--* 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).
++* 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).\\
++
++
  * 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.
  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).
@@ -181,10 +181,11 @@
  The attributes //onfail//, //checkinterval//, //checktime// are not allowed for cues with event conditions.
++
++
  {{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}}
++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}}
  == Actions ==
@@ -216,12 +216,12 @@
  <actions>
  {{/code}}
--{{info}}
--Messages printed with <debug_text> are usually only visible when the "scripts" debug filter is enabled, see [[Script debug output>>doc:||anchor="HScriptdebugoutput"]]
--{{/info}}
--Script debug output
++{{info}}Messages printed with <debug_text> are usually only visible when the "scripts" debug filter is enabled, see Script debug output{{/info}}
++
++
++
  Each child action in a <do_any> node can have a //**weight**// attribute, which can be used to control the random selection of an action node. The default weight of a child node is 1.
  Also available is **<do_if>**, which completes the enclosed action(s) only if one provided value is non-null or matches another. Directly after a <do_if> node, you can add one or more **<do_elseif>** nodes to perform additional checks only in case the previous conditions were not met. The node **<do_else>** can be used directly after a <do_if> or a <do_elseif>. It is executed only if none of the conditions are met.
@@ -234,11 +234,10 @@
  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.
--{{info}}
--The syntax of libraries is considerably different from the syntax in the MD of X3TC.
--{{/info}}
++{{info}}The syntax of libraries is considerably different from the syntax in the MD of X3TC.{{/info}}
++
  Library cues are written like normal cues, they are also defined in a <cues> node, just with the difference that the XML tag is called library instead of cue:
  {{code language="xml"}}
@@ -288,10 +288,11 @@
  </library>
  {{/code}}
--{{warning}}
--These examples are definitely **__not__ **examples of good scripting style.
--{{/warning}}
++{{warning}}These examples are definitely <u>not</u> examples of good scripting style.{{/warning}}
++
++
++
  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.
  Notes:
@@ -298,7 +298,7 @@
  * 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).
  * You //can// access variables in the library root but generally this should be avoided in favor of parameterizing the library!
--** there are some cases where you do want to access these variables directly, for example for maintaining savegame compatibility when patching.
++** there are some cases where you do want to access these variables directly, for example for maintaining savegame compatibility when patching.(% id="library-parameters" %)
  == Library Parameters ==
@@ -343,7 +343,7 @@
  = Instantiation =
--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.**
++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.**
  \\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.
  \\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.
@@ -351,16 +351,16 @@
  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.
--{{info}}
--<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.
--{{/info}}
++{{info}}<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.{{/info}}
  == Access to instances ==
--{{info}}
--This sub-section requires basic knowledge of script expressions.
--{{/info}}
++
++{{info}}This sub-section requires basic knowledge of script expressions.{{/info}}
++
++
++
  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.
  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.
@@ -369,7 +369,7 @@
  Example chart:
--[[~[~[image:Mission Director Guide - Instantiation.png~|~|width="800px"~]~]>>attach:ARCHIVE_XRWIKI_Modding_support_Mission_Director_GuideMission_Director_Guide_-_Instantiation.png]]
++[[~[~[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]]\\
  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.
@@ -394,11 +394,15 @@
  Some additional common pitfalls with respect to instantiation are listed here. There may be more.
--* **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:
++* **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:\\
--{{code language="xml"}}<debug_text text="static.$foo"/>{{/code}}
++{{code language="xml"}}
++  <debug_text text="static.$foo"/>
++{{/code}}
  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:
--{{code language="xml"}}<set_value name="$foo" exact="static.$foo"/>{{/code}}
++{{code language="xml"}}
++<set_value name="$foo" exact="static.$foo"/>
++{{/code}}
  * **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.
  * **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.
@@ -413,12 +413,12 @@
  * {{code language="xml"}}5e12{{/code}} (float in exponent notation, "times ten to the power of")
  * {{code language="xml"}}0xCAFE{{/code}} (hexadecimal integer number)
--{{info}}
--Since octal numbers are hardly ever used (usually unknowingly), the parser is will produce a warning if an octal number is encountered."
--{{/info}}
++{{info}}Since octal numbers are hardly ever used (usually unknowingly), the parser is will produce a warning if an octal number is encountered."{{/info}}
++
++
  You can write string literals by putting the string in single quotes:
  * {{code language="xml"}}'Hello world'{{/code}}
@@ -425,11 +425,10 @@
  * {{code language="xml"}}''{{/code}} (empty string)
  * {{code language="xml"}}'String with a line break\n'{{/code}}
--{{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 '''&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.
--{{/info}}
++
++{{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 '''&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.{{/info}}
++
  == Numeric data types and suffixes ==
  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:
@@ -480,9 +480,7 @@
  \\24h|Time in milliseconds, seconds, minutes, or hours, respectively. A time value is always stored in seconds.
  )))
--{{info}}
--All unit data types are floating point types, except for money, which is an integer data type.
--{{/info}}
++{{info}}All unit data types are floating point types, except for money, which is an integer data type.{{/info}}
  == Operators ==
@@ -496,10 +496,10 @@
  |true|constant|{{code language="xml"}}null == 0{{/code}}|{{code language="xml"}}true{{/code}}|Integer value 1, useful in Boolean expressions
  |pi|constant|{{code language="xml"}}2 * pi{{/code}}|{{code language="xml"}}6.2831853rad{{/code}}|╧Ç as an angle (same as 180deg)
  |()|delimiter|{{code language="xml"}}(2 + 4) * (6 + 1){{/code}}|{{code language="xml"}}42{{/code}}|Parentheses for arithmetic grouping
--|[]|delimiter|{{code language="xml"}}[1, 2, 2+1, 'string']{{/code}}|{{code language="xml"}}[1, 2, 3, 'string']{{/code}}|[[List>>doc:||anchor="HLists" style="outline-width: 0px !important; user-select: auto !important;"]] of values
--|table[]|delimiter|{{code language="xml"}}table[$foo='bar', {1+1}=40+2]{{/code}}|{{code language="xml"}}table[$foo='bar', {2}=42]{{/code}}|[[Table>>doc:||anchor="HTables" style="outline-width: 0px !important; user-select: auto !important;"]] of values
++|[]|delimiter|{{code language="xml"}}[1, 2, 2+1, 'string']{{/code}}|{{code language="xml"}}[1, 2, 3, 'string']{{/code}}|[[List>>MediaWiki.NULL]] of values
++|table[]|delimiter|{{code language="xml"}}table[$foo='bar', {1+1}=40+2]{{/code}}|{{code language="xml"}}table[$foo='bar', {2}=42]{{/code}}|[[Table>>MediaWiki.NULL]] of values
  |{}|delimiter|{{code language="xml"}}{101, 3}{{/code}}|{{code language="xml"}}'Some text'{{/code}}|Text lookup (page ID and text ID) from TextDB
--\\(Note: Braces are also used for [[property lookups>>doc:||anchor="HValueproperties" style="outline-width: 0px !important; user-select: auto !important;"]])
++\\(Note: Braces are also used for [[property lookups>>MediaWiki.NULL]])
  |+|unary|{{code language="xml"}}+21 * (+2){{/code}}|{{code language="xml"}}42{{/code}}|Denotes positive number (no effect)
  |-|unary|{{code language="xml"}}-(21 * -2){{/code}}|{{code language="xml"}}42{{/code}}|Negates the following number
  |not|unary|{{code language="xml"}}not (21 == 42){{/code}}|{{code language="xml"}}true{{/code}}|Yields true if the following expression is false (equal to zero), false otherwise
@@ -556,7 +556,7 @@
  {{code language="xml"}}1 ge 3{{/code}}
  \\{{code language="xml"}}1 <= 3{{/code}}|{{code language="xml"}}false{{/code}}|Greater than or equal to
  |(((
--
++=  =
  )))|binary|{{code language="xml"}}1 + 1 == 2.0{{/code}}|{{code language="xml"}}true{{/code}}|Equal to
  |~!=|binary|{{code language="xml"}}1 + 1 != 2.0{{/code}}|{{code language="xml"}}false{{/code}}|Not equal to
  |and|binary|{{code language="xml"}}true and false{{/code}}|{{code language="xml"}}false{{/code}}|Logical AND (short-circuit semantics)
@@ -568,8 +568,10 @@
  \\{{code language="xml"}}if 1 == 2 then 'F' else 'T'{{/code}}|
  {{code language="xml"}}null{{/code}}
  \\{{code language="xml"}}'T'{{/code}}|Conditional operator ("inline if")
--)))
++)))(% id="operator-precedence-rules" %)
++(%%)
++
  === Operator precedence rules ===
  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.
@@ -584,6 +584,8 @@
  * or
  * if/then/else (lowest precedence)
++(% id="type-conversion" %)
++
  === Type conversion ===
  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:
@@ -612,6 +612,7 @@
  As you can see, operators of the same precedence (+ in this case) are always evaluated from left to right.
++(% id="boolean-operators" %)
  === Boolean operators ===
@@ -625,9 +625,11 @@
  * 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.
  * <, <=, >, >= 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.
--(% id="categorybroken_macroanchorstrings-and-formatting" %)== Strings and formatting==
++(% id="categorybroken_macroanchorstrings-and-formatting" %)== Strings and formatting==
++(% id="categorybroken_macroanchorstrings-and-formatting" %)
++
  {{{==}}}
  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:
@@ -653,10 +653,16 @@
  *  If "," is used without "." then any fractional digits are discarded.
  * "." 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).
--{{info}}
--There are also special methods to [[NULL|format money values and time values]] using the "formatted" property.
--{{/info}}
++
++{{info}}There are also special methods to [[NULL|format money values and time values]] using the "formatted" property.{{/info}}
++
++
++
++\\
++
++(% id="categorybroken_macroanchorlists" %)
++
  == Lists ==
  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]].
@@ -663,43 +663,56 @@
  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 "[ ]".
--{{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}}
++{{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}}
++
++
  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.
--{{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.
++{{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.
  Bad usage attempting to remove the last element of the list: <remove_from_list name="$List" exact="$List.{$List.count}"/>
--If you know the index, simply use <remove_value/> e.g. <remove_value name="$List.{$List.count}"/>
--{{/info}}
++If you know the index, simply use <remove_value/> e.g. <remove_value name="$List.{$List.count}"/>{{/info}}
++
++
++\\
++
  (% id="categorybroken_macroanchortables" %)
++
  == Tables ==
--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.
++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.\\
  Almost all values are allowed as table keys, but there are a few exceptions:
  * Strings must start with '$', like variables
  * null cannot be used as table key (but the number 0 is valid)
--* Lists, tables, groups and buildplans cannot be used as table keys
++* Lists, tables, groups and buildplans cannot be used as table keys\\
++
++
  These restrictions only apply to the keys, there are no restrictions for values that you assign to them. For example:
  * {{code language="xml"}}table[]{{/code}} ⟹ creates an empty table
--* {{code language="xml"}}table[{0} = null]{{/code}} ⟹ creates a table that maps the number 0 to null
++* {{code language="xml"}}table[{0} = null]{{/code}} ⟹ creates a table that maps the number 0 to null\\
++
++
  * {{code language="xml"}}table[{'$foo'} = 'bar']{{/code}} ⟹ a table that maps the string '$foo' to the string 'bar'
  * {{code language="xml"}}table[$foo = 'bar']{{/code}} ⟹ exactly the same, just a shorter notation for string keys
  * {{code language="xml"}}table[foo = 'bar']{{/code}} ⟹ error, 'foo' does not start with a '$'
--* {{code language="xml"}}table[{1} = [], {2} = table[]] {{/code}} ⟹ a table that maps 1 to an empty list and 2 to an empty table
++* {{code language="xml"}}table[{1} = [], {2} = table[]] {{/code}} ⟹ a table that maps 1 to an empty list and 2 to an empty table\\
--Just like lists, tables are stored as references, so it's possible that multiple variables reference the same table (see above).
++
++Just like lists, tables are stored as references, so it's possible that multiple variables reference the same table (see above).\\
++
++\\
++
++(% id="categorybroken_macroanchorvalue-properties" %)
++
  == Value properties ==
  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.
@@ -720,22 +720,28 @@
  * {{code language="xml"}}[100, 200, 300, 400].{1}{{/code}} ⟹ 100 (reading the first element)
  * {{code language="xml"}}[100, 200, ['Hello ', 'world']] .{3}.{2}{{/code}} ⟹ 'world' (second element of the inner list, which is the third element of the outer list)
  * {{code language="xml"}}[].{'count'}{{/code}} ⟹ 0
--* {{code language="xml"}}table[{21} = 42].{21}{{/code}} ⟹ 42
++* {{code language="xml"}}table[{21} = 42].{21}{{/code}} ⟹ 42\\
++
++
  In most cases the property key is a fixed string, like "name" or "class". You can write this like above:
  * {{code language="xml"}}[42].{'count'}{{/code}}
  * {{code language="xml"}}$ship.{'name'}{{/code}}
  * {{code language="xml"}}$ship.{'class'}{{/code}}
--* {{code language="xml"}}table[$foo='bar'].{'$foo'}{{/code}}
++* {{code language="xml"}}table[$foo='bar'].{'$foo'}{{/code}}\\
++
++
  But it is easier just to write the property key without braces, which is equivalent:
  * {{code language="xml"}}[0].count{{/code}}
  * {{code language="xml"}}$ship.name{{/code}}
  * {{code language="xml"}}$ship.class{{/code}}
--* {{code language="xml"}}table[$foo='bar'].$foo{{/code}}
++* {{code language="xml"}}table[$foo='bar'].$foo{{/code}}\\
++
++
  (In this case, $ship is a variable. All variables start with a "$", so they cannot be confused with keywords.)
  A list has even more properties:
@@ -763,27 +763,36 @@
  * '**clone'** creates a shallow copy of the table
  * '**keys'** allows you to access data about the table's keys
--However, 'keys' alone will not give you a result. 'keys' must be followed by another keyword to retrieve the desired information, for example:
++However, 'keys' alone will not give you a result. 'keys' must be followed by another keyword to retrieve the desired information, for example:\\
--* {{code language="xml"}}$table.keys.list{{/code}}: Yields a list of all keys in the table (reliably sorted by key if all keys are numeric)
++* {{code language="xml"}}$table.keys.list{{/code}}: Yields a list of all keys in the table (reliably sorted by key if all keys are numeric)\\
++
++
  * {{code language="xml"}}$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)
  * {{code language="xml"}}$table.keys.random{{/code}}: A randomly chosen key (which requires that the table is non-empty)
--{{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}}
--=== (% id="lookup-tests-and-suppressing-errors" %)Lookup tests and suppressing errors(%%) ===
++{{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}}
++
++
++
++(% id="lookup-tests-and-suppressing-errors" %)=== Lookup tests and suppressing errors
++
++
++{{{===}}}
++
  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:
  * {{code language="xml"}}$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
  * {{code language="xml"}}$list.{5}?{{/code}} ⟹ true if $list exists and has the property 5, false otherwise
--* {{code language="xml"}}$table.$key?{{/code}} ⟹ Analogously, true if $table exists and has the string property '$key'
++* {{code language="xml"}}$table.$key?{{/code}} ⟹ Analogously, true if $table exists and has the string property '$key'\\
++
++
  The question mark can even be applied to variables:
  * {{code language="xml"}}$list{{/code}} ⟹ The value stored under the name $list, or an error if there is no such variable
@@ -797,6 +797,10 @@
  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.
++\\
++
++(% id="static-lookups" %)
++
  === Static lookups ===
  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.
@@ -805,6 +805,10 @@
  (% style="margin-left: 0.0px;" %)
  (((
++\\
++
++
++
  |Data type (= value name)|Examples|Description
  |class|
  class.ship
@@ -849,21 +849,22 @@
  \\faction.argongovernment|Factions
  )))
--{{id name="typeof" /}}
--{{info}}
--With the ''typeof'' operator you can get the datatype of any expression and compare it with what you expect, for example:
++{{info}}With the ''typeof'' operator you can get the datatype of any expression and compare it with what you expect, for example:
  <code>typeof $value == datatype.faction</code>
  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:
--<code>(typeof $value).isstring</code>"
--{{/info}}
++<code>(typeof $value).isstring</code>"{{/info}}
--{{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}}
++{{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}}
++\\
++
++
++
++(% id="player-properties" %)
++
  === Player properties ===
  You can access many player-related game properties via the keyword "player":
@@ -871,15 +871,20 @@
  * player.**name**: The player's name
  * player.**age**: The passed in-game time since game start
  * player.**money**: The money in the player's account
--* player.**ship**: The ship the player is currently on (not necessarily the player's ship), or null if the player is on a station
++* player.**ship**: The ship the player is currently on (not necessarily the player's ship), or null if the player is on a station\\
++
++
  * player.**primaryship**: The player's own ship (but the player is not necessarily on board)
--* player.**entity**: The actual player object
++* player.**entity**: The actual player object\\
++
++
  * player.**zone**, player.**sector**, player.**cluster**, player.**galaxy**: Location of the player entity
  * player.**copilot**: The co-pilot NPC
  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.
++\\(% id="safe-properties" %)
  === Safe properties ===
@@ -894,21 +894,28 @@
  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.
--=== (% id="categorybroken_macroanchormoney-and-time-formatting" %)Money and time formatting(%%) ===
++(% id="categorybroken_macroanchormoney-and-time-formatting" %)=== Money and time formatting
++
++{{{===}}}
++
  **[New as of X Rebirth 4.0]**
  \\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.
  * {{code language="xml"}}$money.formatted.{'formatstring'}{{/code}}
--* {{code language="xml"}}$money.formatted.default{{/code}} (using default format string '%s')
++* {{code language="xml"}}$money.formatted.default{{/code}} (using default format string '%s')\\
++
++
  * {{code language="xml"}}$time.formatted.{'formatstring'}{{/code}}
  * {{code language="xml"}}$time.formatted.default{{/code}} (using default format string '%T')
  In scripts, money is stored in cents, not Credits. The formatted representation always shows the value in Credits, including thousands separators.
--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:
++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:\\
++
++
  |1-9|Truncation|To enable truncation, specify the number of relevant digits that should be displayed. If the money string is too long, it can be truncated and a metric unit prefix (e.g. k = kilo) is appended. (All digits are shown unless truncation is enabled.)
  |c|Colouring|If truncation is enabled, the metric unit prefixes (e.g. k, M, G) can be coloured when displayed on the screen, using the escape sequence '\033C'.
  |.|Cents|Usually money values have no cent part, since cents are not used in accounts or trades. However, single ware prices can have a non-zero cent part. (Cents are not displayed if money is truncated)
@@ -923,10 +923,14 @@
  * %G: Credits (truncated) in Giga format
  * %T: Credits (truncated) in Tera format
  * %Cr: Localised "Cr" string
--* %%: A % sign
++* %%: A % sign\\
--Examples:
++
++Examples:\\
++
++
++
  * {{code language="xml"}}(1234Cr).formatted.{'%s'}{{/code}}⟹{{code language="xml"}}'1,234'{{/code}}
  * {{code language="xml"}}(1234Cr).formatted.default{{/code}}⟹{{code language="xml"}}'1,234'{{/code}} (same as {'%s'})
  * {{code language="xml"}}(1234Cr).formatted.{'%.s %Cr'}{{/code}}⟹{{code language="xml"}}'1,234.00 Cr'{{/code}}
@@ -942,19 +942,23 @@
  * {{code language="xml"}}(151s).formatted.{'%.3T'}{{/code}} ⟹ {{code language="xml"}}'00:02:31.000'{{/code}}
  * {{code language="xml"}}(151s).formatted.{'%h:%M'}{{/code}} ⟹ {{code language="xml"}}'0:02'{{/code}}
++(% id="complete-property-documentation" %)
++
  === Complete property documentation ===
  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.
--The raw documentation data is located in libraries/scriptproperties.xml, but it is recommended to open scriptproperties.html in a browser.
++The raw documentation data is located in libraries/scriptproperties.xml, but it is recommended to open scriptproperties.html in a browser.\\
--{{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:
++
++{{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:
++
  * Firefox: On the about:config page, the value of "security.fileuri.strict_origin_policy" has to be changed to "false".
--* Chrome: The Chrome launcher has to be started with the command-line parameter --allow-file-access-from-files--
--{{/info}}
++* Chrome: The Chrome launcher has to be started with the command-line parameter --allow-file-access-from-files{{/info}}
++
++
  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:
  * Enter the beginning of a base keyword
@@ -963,14 +963,26 @@
  * After the dot, you can enter a property name
  * You can also enter a dot (".") as first character to search globally for a property
--{{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}}
++\\
++
++
++{{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}}
++
++
++
++\\
++
++(% id="md-refreshing-and-patching" %)
++
  = MD refreshing and patching =
  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.
++\\
++
++(% id="details-and-restrictions" %)
++
  == Details and restrictions ==
  Here are some noteworthy facts about refreshing scripts and cues, and the restrictions:
@@ -990,14 +990,20 @@
  * Changing instantiate="false" to "true" turns the cue into "waiting" state if it was active or complete before.
  * Changing instantiate="true" to "false" removes all instantiated cues and their descendants.
--{{warning}}
--Be aware that completed instances can be auto-deleted, and so added sub-cues will not become active in such a case.
--{{/warning}}
++\\
--{{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}}
++
++{{warning}}Be aware that completed instances can be auto-deleted, and so added sub-cues will not become active in such a case.{{/warning}}
++
++{{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}}
++
++
++
++\\
++
++(% id="patching" %)
++
  == Patching ==
  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.
@@ -1016,14 +1016,22 @@
  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.
--{{info}}
--The <patch> elements will be ignored when refreshing the MD at run-time. They only affect loaded savegames."
--{{/info}}
++{{info}}The <patch> elements will be ignored when refreshing the MD at run-time. They only affect loaded savegames."{{/info}}
++
++
++\\
++
++(% id="common-attribute-groups" %)
++
  = Common attribute groups =
  There are many commonly used actions and conditions which share groups of attributes. The most important ones are explained here.
++\\
++
++(% id="categorybroken_macroanchorvalue-comparisons" %)
++
  == Value comparisons ==
  There are many conditions and conditional actions that require a value comparison, for example the condition <check_value>:
@@ -1043,10 +1043,12 @@
    <check_value value="$attention" min="attention.visible"/>
  {{/code}}
--{{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}}
++{{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}}
++
++
++\\
++
  == Random ranges ==
  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:
@@ -1076,11 +1076,15 @@
    <set_value name="$foo" min="-20" max="20" profile="profile.increasing" scale="4"/>
  {{/code}}
++\\(% id="variables-and-namespaces" %)
  = Variables and namespaces =
  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).
++
++\\\\\\(% id="categorybroken_macroanchorcreating-and-removing-variables" %)
++
  == Creating and removing variables ==
  You can create variables with certain actions and conditions, such as the <set_value> action:
@@ -1131,6 +1131,7 @@
  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.
++(% id="accessing-remote-variables" %)
  == Accessing remote variables ==
@@ -1150,6 +1150,8 @@
    <set_value name="$baz" exact="this.$bar.$foo" />
  {{/code}}
++\\\\\\(% id="namespaces" %)
++
  == Namespaces ==
  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.
@@ -1172,6 +1172,8 @@
  You can also use the keyword "**namespace**" in expressions to get the namespace cue.
++(% id="defining-a-cues-namespace" %)
++
  === Defining a cue's namespace ===
  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:
@@ -1180,13 +1180,13 @@
  * **static**: Same as "this", but when instantiated, use the static cue: $foo == static.$foo
  * **default**: The namespace is inherited from the parent cue. The default for root cues and for libraries is the same as "static".
--{{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:
++{{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:
++
  {{code language="xml"}}
  <cue name="LibRef" ref="Lib">
--  <cke:param name="Param1" value="$foo" ></cke:param> <!-- $foo from parent namespace -->
--  <cke:param name="Param2" value="namespace.$foo" ></cke:param> <!-- LibRef.$foo (error) -->
++  <param name="Param1" value="$foo" /> <!-- $foo from parent namespace -->
++  <param name="Param2" value="namespace.$foo" /> <!-- LibRef.$foo (error) -->
  </cue>
--{{/code}}
++{{/code }}
  {{/warning}}

Mission Director Guide - Instantiation.png

Author

...	...	@@ -1,1 +1,0 @@
1		-xwiki:XWiki.Daniel

Size

...	...	@@ -1,1 +1,0 @@
1		-47.0 KB

Content

Changes for page Mission Director Guide

Summary

Details

Navigation

Applications