Changes for page Mission Director Guide

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

From 32941.1 to 32942.1 From 32943.1 to 32944.1

From version 32942.1

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

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 (1 modified, 0 added, 0 removed)

Details

Page properties

Content

@@ -14,7 +14,7 @@
  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 {{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.
++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 [[(% 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.
@@ -53,7 +53,7 @@
  <mdscript name="ScriptName" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="md.xsd">
  {{/code}}
--"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.
++"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.
  The only allowed sub-node of <mdscript> is <cues>, which can only contain <cue> sub-nodes:
@@ -154,7 +154,7 @@
--* 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.
++* 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).
@@ -198,7 +198,7 @@
  <event_cue_completed cue="parent"/>
  {{/code}}
--<actions> is optional. Leaving it out may be useful if you only want to enable sub-cues after the cueΓÇÖs condition check. The state transition from active to complete will still take the <delay> node into account.
++<actions> is optional. Leaving it out may be useful if you only want to enable sub-cues after the cue's condition check. The state transition from active to complete will still take the <delay> node into account.
  Note that the MD script language is not designed as a programming language. The actions are performed in sequence, although they can be nested to form more complex structures. Loops and conditionals exist to some extent, but not necessarily in the sense that a programmer might expect. Analogously to <check_all> and <check_any>, you can use **<do_all>** to perform all the contained sub-node actions, and **<do_any>** to perform only one of them. <do_all> is particularly useful when nested in a <do_any>.
@@ -216,7 +216,7 @@
--{{info}}Messages printed with <debug_text> are usually only visible when the "scripts" debug filter is enabled, see [[NULL|Script debug output]].{{/info}}
++{{info}}Messages printed with <debug_text> are usually only visible when the "scripts" debug filter is enabled, see Script debug output{{/info}}
@@ -245,7 +245,7 @@
  </library>
  {{/code}}
--Although it is called library, itΓÇÖs basically just a cue that doesnΓÇÖt do anything. You can mix cues and libraries as you want, as root cues or sub-cues - the location within the file is unimportant. All that counts is the library name, which has to be unique within the MD script, like all other cue names.
++Although it is called library, it's basically just a cue that doesn't do anything. You can mix cues and libraries as you want, as root cues or sub-cues - the location within the file is unimportant. All that counts is the library name, which has to be unique within the MD script, like all other cue names.
  To use a library, use the attribute ref:
@@ -290,7 +290,7 @@
--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.
++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:
@@ -315,7 +315,7 @@
  </library>
  {{/code}}
--If a default value is supplied, the parameter is regarded as optional, otherwise itΓÇÖs required. When providing the actual parameters in a referencing cue, note that there is no <params> node:
++If a default value is supplied, the parameter is regarded as optional, otherwise it's required. When providing the actual parameters in a referencing cue, note that there is no <params> node:
  {{code language="xml"}}
  <cue name="Foo" ref="Lib">
@@ -324,7 +324,7 @@
  </cue>
  {{/code}}
--The values (including default values) can be variable expressions and will be evaluated when the cue is enabled, i.e. when it starts checking the conditions. They will be available to the cue as variables, using the parameter name with a ΓÇÿ$ΓÇÖ prefix. In the example above, the variables $foo, $bar, and $baz would be created.
++The values (including default values) can be variable expressions and will be evaluated when the cue is enabled, i.e. when it starts checking the conditions. They will be available to the cue as variables, using the parameter name with a ΓÇÿ$' prefix. In the example above, the variables $foo, $bar, and $baz would be created.
  {{code language="xml"}}
  <library name="Lib">
@@ -347,7 +347,7 @@
  == Cleaning up instances explicitly ==
--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.
++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 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."/}}
@@ -355,7 +355,7 @@
--{{info}}This sub-section requires basic knowledge of [[NULL|script expressions]].{{/info}}
++{{info}}This sub-section requires basic knowledge of script expressions.{{/info}}
@@ -398,8 +398,8 @@
  \\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.
++* **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.
  = Expressions =
@@ -425,7 +425,7 @@
--{{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 '''< > " &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.{{/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 ==
@@ -534,22 +534,22 @@
  lt
  \\< (<)|binary|
  {{code}}1 lt 3{{/code}}
--\\{{code}}1 &amp;lt; 3{{/code}}|{{code}}true{{/code}}|Less than
++\\{{code}}1 &lt; 3{{/code}}|{{code}}true{{/code}}|Less than
  |
  le
  \\<=|binary|
  {{code}}1 le 3{{/code}}
--\\{{code}}1 &amp;lt;= 3{{/code}}|{{code}}true{{/code}}|Less than or equal to
++\\{{code}}1 &lt;= 3{{/code}}|{{code}}true{{/code}}|Less than or equal to
  |
  gt
  \\> (>)|binary|
  {{code}}1 gt 3{{/code}}
--\\{{code}}1 &amp;gt; 3{{/code}}|{{code}}false{{/code}}|Greater than
++\\{{code}}1 &gt; 3{{/code}}|{{code}}false{{/code}}|Greater than
  |
  ge
  \\>=|binary|
  {{code}}1 ge 3{{/code}}
--\\{{code}}1 &amp;gt;= 3{{/code}}|{{code}}false{{/code}}|Greater than or equal to
++\\{{code}}1 &gt;= 3{{/code}}|{{code}}false{{/code}}|Greater than or equal to
  |(((
  =  =
  )))|binary|{{code}}1 + 1 == 2.0{{/code}}|{{code}}true{{/code}}|Equal to
@@ -569,7 +569,7 @@
  === 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.
++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.
  * Unary operators: +, -, not, typeof, function-style operators (highest precedence)
  * Power operator: ^
@@ -623,7 +623,7 @@
  * "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
  ** Example:{{code}} false and $foo{{/code}} ⟹ {{code}}false{{/code}} (the value of $foo is not checked at all)
  * 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.
++* <, <=, >, >= 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.
@@ -639,7 +639,7 @@
  See also the section about [[value properties>>MediaWiki.NULL]].
--Instead of ΓÇÿ%1 %2 %3ΓÇÖ, you can also use ΓÇÿ%s %s %sΓÇÖ, which is also compatible with Lua string formatting in the UI system. However, this should only be used if you are sure that the order is the same in all supported languages. If you want to make translators aware that they can change the order of parameters, you should prefer '%1 %2 %3'.
++Instead of ΓÇÿ%1 %2 %3', you can also use ΓÇÿ%s %s %s', which is also compatible with Lua string formatting in the UI system. However, this should only be used if you are sure that the order is the same in all supported languages. If you want to make translators aware that they can change the order of parameters, you should prefer '%1 %2 %3'.
  \\To get a percent character in the result string, use '%%' in the format string.
  \\\\\\If you need a more sophisticated method for text substitution, try **<substitute_text>**. See the XML schema documentation for this script action.
  \\**[New as of X Rebirth 4.0]**
@@ -671,7 +671,7 @@
  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}}
@@ -723,9 +723,9 @@
  == 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.
++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.
--Numbers donΓÇÖt have any properties. Lists, for example, have quite a few of them: You can access the number of elements; and each element is also a property of the list. A ship can have properties like its name, the ship class, its position etc.
++Numbers don't have any properties. Lists, for example, have quite a few of them: You can access the number of elements; and each element is also a property of the list. A ship can have properties like its name, the ship class, its position etc.
  You can imagine properties as key/value pairs in an associative mapping: You pass the key, and you get the value as result. For example, the list [42, null, 'text'] has the following mapping:
@@ -777,7 +777,7 @@
  * {{code}}[1, 6, 8].average{{/code}} ⟹ 5
--**indexof'** is followed by another property, and the index of the first occurence of that key in the list is returned, or 0 if itΓÇÖs not in the list
++**indexof'** is followed by another property, and the index of the first occurence of that key in the list is returned, or 0 if it's not in the list
  * {{code}}[1, 6, 8].indexof.{8}{{/code}} ⟹ 3
@@ -901,7 +901,7 @@
  <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}}
  \\
@@ -913,9 +913,9 @@
  You can access many player-related game properties via the keyword "player":
--* player.**name**: The playerΓÇÖs name
++* 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.**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\\
@@ -1163,7 +1163,7 @@
  <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.
++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}}<set_value name="$foo" operation="add" />{{/code}}
@@ -1213,13 +1213,13 @@
  {{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.
++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.
  You can also use the keyword "**namespace**" in expressions to get the namespace cue.
  (% id="defining-a-cues-namespace" %)
--=== Defining a cueΓÇÖs 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:
@@ -1230,6 +1230,6 @@
  (% 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:
++{{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><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