Changes for page Mission Director Guide

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

From 32943.1 to 32942.1 From 32950.1 to 32949.1

From version 32949.1

edited by Daniel Turner
on 2023/08/22 18:54

Change comment: There is no comment for this version

To version 32943.1

edited by Daniel Turner
on 2023/08/22 17:26

Change comment: There is no comment for this version

Raw
Rendered

Summary

Page properties (3 modified, 0 added, 0 removed)

Details

Page properties

Title

@@ -1,1 +1,1 @@
--Mission Director Guide
++X4:X4 Documentation/X4 Game Design/0 General/Mission Director Guide

Parent

...	...	@@ -1,1 +1,0 @@
1		-X Rebirth Wiki.Modding support.WebHome

Content

@@ -1,10 +1,10 @@
  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[[(% &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.
++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.
  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}}
++{{{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.}}}
  (% id="md-scripts" %)
@@ -14,9 +14,9 @@
  MD scripts are not necessarily missions. An MD file can contain a part of a mission, multiple missions, or no mission at all, as the MD is used for more than just missions.
--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.
++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.
--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 [[(% 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.
  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.
@@ -182,9 +182,7 @@
--{{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}}
++{{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}}
  == Actions ==
@@ -343,8 +343,8 @@
  = 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.**
--\\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.
++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.**
++\\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.
  \\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.
  == Cleaning up instances explicitly ==
@@ -351,7 +351,7 @@
  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 body="<cancel_cue> and <reset_cue> only take effect after all remaining actions of the current cue are performed. So you can even safely cancel the cue that you are currently in (keyword "'''this'''") or any ancestor cue, and still perform more actions afterwards."/}}
  == Access to instances ==
@@ -396,13 +396,9 @@
  * **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}}
--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}}<debug_text text="static.$foo"/>{{/code}}(% style="color: rgb(0,0,255);text-decoration: none;" %)
++\\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}}<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.
@@ -419,7 +419,7 @@
--{{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}}
@@ -687,7 +687,7 @@
  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}}
@@ -709,15 +709,15 @@
  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}}table[]{{/code}} ⟹ creates an empty table
++* {{code}}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}}table[{'$foo'} = 'bar']{{/code}} ⟹ a table that maps the string '$foo' to the string 'bar'
++* {{code}}table[$foo = 'bar']{{/code}} ⟹ exactly the same, just a shorter notation for string keys
++* {{code}}table[foo = 'bar']{{/code}} ⟹ error, 'foo' does not start with a '$'
++* {{code}}table[{1} = [], {2} = table[]] {{/code}} ⟹ a table that maps 1 to an empty list and 2 to an empty table\\
@@ -1091,7 +1091,7 @@
  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.
--{{code language="xml"}}<cue [...] version="42"> <conditions> [...] </conditions> <actions> [...] </actions> <patch sinceversion="42">    [patch actions] </patch></cue>{{/code}}
++{{code}}<cue [...] version="42"> <conditions> [...] </conditions> <actions> [...] </actions> <patch sinceversion="42">    [patch actions] </patch></cue>{{/code}}
  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.
@@ -1117,11 +1117,11 @@
  There are many conditions and conditional actions that require a value comparison, for example the condition <check_value>:
--{{code language="xml"}}<check_value value="$ware == ware.silicon and $amount != 0"/>{{/code}}
++{{code}}<check_value value="$ware == ware.silicon and $amount != 0"/>{{/code}}
  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:
--{{code language="xml"}}<check_value value="FooCue.state" exact="cuestate.complete"/><check_value value="$foo.count" min="5"/><check_value value="$foo" max="player.age + 1min"/><check_value value="player.money" min="300Cr" max="600Cr"/><check_value value="$method" list="[killmethod.hitbymissile, killmethod.collected]"/><check_value value="$attention" min="attention.visible"/>{{/code}}
++{{code}}<check_value value="FooCue.state" exact="cuestate.complete"/><check_value value="$foo.count" min="5"/><check_value value="$foo" max="player.age + 1min"/><check_value value="player.money" min="300Cr" max="600Cr"/><check_value value="$method" list="[killmethod.hitbymissile, killmethod.collected]"/><check_value value="$attention" min="attention.visible"/>{{/code}}
  {{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}}
@@ -1129,26 +1129,29 @@
  \\
++(% id="categorybroken_macroanchorrandom-ranges" %)
++
  == 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:
--{{code language="xml"}}<set_value name="$race" exact="race.teladi"/>{{/code}}
++{{code}}<set_value name="$race" exact="race.teladi"/>{{/code}}
  To select a random element from a list, this syntax can be used:
--{{code language="xml"}}<set_value name="$prime" list="[2, 3, 5, 7, 11]"/>{{/code}}
++{{code}}<set_value name="$prime" list="[2, 3, 5, 7, 11]"/>{{/code}}
  To get a random number within a given range, you can use min/max:
--{{code language="xml"}}<set_value name="$foo" min="-20" max="20"/><set_value name="$timeout" max="20s"/>{{/code}}
++{{code}}<set_value name="$foo" min="-20" max="20"/><set_value name="$timeout" max="20s"/>{{/code}}
  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).
  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).
--{{code language="xml"}}<set_value name="$foo" min="-20" max="20" profile="profile.increasing" scale="4"/>{{/code}}
++{{code}}<set_value name="$foo" min="-20" max="20" profile="profile.increasing" scale="4"/>{{/code}}
++(% style="color: rgb(0,0,255);text-decoration: none;" %)
  \\(% id="variables-and-namespaces" %)
  = Variables and namespaces =
@@ -1155,43 +1155,44 @@
  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).
--
++(% style="color: rgb(0,0,255);text-decoration: none;" %)
  \\\\\\(% 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:
++{{{You can create variables with certain actions and conditions, such as the <set_value> action:}}}
--{{code language="xml"}}<set_value name="$foo" exact="$bar + 1" />{{/code}}
++{{code}}<set_value name="$foo" exact="$bar + 1" />{{/code}}
  <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>.)
  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.
--{{code language="xml"}}<set_value name="$foo" operation="add" />{{/code}}
++{{code}}<set_value name="$foo" operation="add" />{{/code}}
  The trick is that <set_value> not only works on variables, but also on list elements and table keys:
--{{code language="xml"}}<set_value name="$list.{1}" exact="42" /><set_value name="$table.$foo" exact="42" />{{/code}}\\
++{{code}}<set_value name="$list.{1}" exact="42" /><set_value name="$table.$foo" exact="42" />{{/code}}\\
  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):
--{{code language="xml"}}<set_value name="$list.{1}" exact="42" operation="insert" />{{/code}}
++{{code}}<set_value name="$list.{1}" exact="42" operation="insert" />{{/code}}
  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.
  Appending is easier than that. The following actions are equivalent:
--{{code language="xml"}}<set_value name="$list.{$list.count + 1}" exact="42" operation="insert" /><append_to_list name="$list" exact="42" />{{/code}}
++{{code}}<set_value name="$list.{$list.count + 1}" exact="42" operation="insert" /><append_to_list name="$list" exact="42" />{{/code}}
  Inserting at a position below 1 or above $list.count + 1 is not possible.
  To remove variables or list/table entries, use <remove_value>:
--{{code language="xml"}}<remove_value name="$foo" /><remove_value name="$list.{1}" /><remove_value name="$table.$foo" />{{/code}}\\
++{{code}}<remove_value name="$foo" /><remove_value name="$list.{1}" /><remove_value name="$table.$foo" />{{/code}}\\
  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.
++(% style="color: rgb(0,0,255);text-decoration: none;" %)
  \\\\\\(% id="accessing-remote-variables" %)
  == Accessing remote variables ==
@@ -1198,12 +1198,13 @@
  You can also read and write variables in other cues by using the variable name as property key:
--{{code language="xml"}}<set_value name="OtherCue.$foo" min="0.0" max="1.0" /><set_value name="md.OtherScript.YetAnotherCue.$bar" exact="OtherCue.$foo" />{{/code}}
++{{code}}<set_value name="OtherCue.$foo" min="0.0" max="1.0" /><set_value name="md.OtherScript.YetAnotherCue.$bar" exact="OtherCue.$foo" />{{/code}}
  Instead of referencing a cue by name, you could also reference it via a keyword or another variable:
--{{code language="xml"}}<set_value name="static.$counter" operation="add" /><set_value name="parent.$foo" exact="42" /><set_value name="this.$bar" exact="parent" /><set_value name="$baz" exact="this.$bar.$foo" />{{/code}}
++{{code}}<set_value name="static.$counter" operation="add" /><set_value name="parent.$foo" exact="42" /><set_value name="this.$bar" exact="parent" /><set_value name="$baz" exact="this.$bar.$foo" />{{/code}}
++(% style="color: rgb(0,0,255);text-decoration: none;" %)
  \\\\\\(% id="namespaces" %)
  == Namespaces ==
@@ -1212,7 +1212,7 @@
  Consider this case:
--{{code language="xml"}}<cue name="Root"> <actions>  <set_value name="$foo" /> </actions> <cues>  <cue name="SubCue"> [...]  </cue> </cues></cue>{{/code}}
++{{code}}<cue name="Root"> <actions>  <set_value name="$foo" /> </actions> <cues>  <cue name="SubCue"> [...]  </cue> </cues></cue>{{/code}}
  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.
@@ -1228,7 +1228,9 @@
  * **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".
++(% style="color: rgb(0,0,255);text-decoration: none;" %)
++
  {{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"> <param name="Param1" value="$foo" /> <!-- $foo from parent namespace --> <param name="Param2" value="namespace.$foo" /> <!-- LibRef.$foo (error) --></cue></code>{{/warning}}
++<code><cue name="LibRef" ref="Lib"> <param name="Param1" value="$foo" /> <!-- $foo from parent namespace --> <param name="Param2" value="namespace.$foo" /> <!-- LibRef.$foo (error) --></cue></code>{{/warning}}

Changes for page Mission Director Guide

Summary

Details

Navigation

Applications