Changes for page Mission Director Guide

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

From 32933.1 to 32932.1 From 32941.1 to 32940.1

From version 32940.1

edited by Daniel Turner
on 2023/08/22 16:50

Change comment: There is no comment for this version

To version 32933.1

edited by Daniel Turner
on 2023/05/26 13:05

Change comment: There is no comment for this version

Raw
Rendered

Summary

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

Details

Page properties

Tags

@@ -1,1 +1,1 @@
--Broken_macro/anchor|Broken macro/anchor
++Broken_macro/anchor

Content

@@ -20,12 +20,14 @@
  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 [[NULL|Conditions]]).
++{{note body="Even if your script is free of XSD errors, that does not mean that the script syntax is correct. For example, there are XML elements that require at least one of multiple attributes, but this requirement cannot be reflected in a schema (apart from documentation text). Please notice the XSD documentation of the elements and attributes, e.g. displayed via tooltips in Visual Studio / Visual Web Developer. Please also note additional requirements for MD cue attributes in this guide (see [[NULL|Conditions]]).
--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}}
++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."/}}
++
++
++(% id="categorybroken_macroanchorscript-debug-output" %)
++
  == Script debug output ==
  The game can print error messages and, when enabled, also general messages. Error messages can originate from the scripting system, but also from other game sub-systems. They can be viewed in the in-game [[DebugLog>>url:https://forum.egosoft.com/viewtopic.php?t=366654]].
@@ -42,6 +42,8 @@
  The script action <debug_text> can be used to print debug messages from within a script.\\
++(% id="md-script-structure" %)
++
  = MD script structure =
  In this section we will look at how to start the whole process by creating a new MD mission file and the basic steps in producing mission content with XML code. There will be a description of the key elements of the mission file.
@@ -69,6 +69,10 @@
  </mdscript>
  {{/code}}
++┬á
++
++(% id="categorybroken_macroanchorcues" %)
++
  == Cues ==
  Cues are the main ingredient of an MD script. A cue consists of a set of **conditions** and a set of **actions**. When the conditions are met, the cue is activated and the actions are performed. A cue can have child cues, or **sub-cues**: A sub-cue exists only when its parent cue has become active, so the activation of the parent cue initiates the condition checks of its child cues.
@@ -104,6 +104,10 @@
  The rules for naming cues is the same for MD script names: The name **starts with an upper case letter**, and has to be **unique within this file**. So it is actually possible to use the same cue name in different scripts, which is different from the MD in X3.
++\\
++
++(% id="categorybroken_macroanchorconditions" %)
++
  == Conditions ==
  The <conditions> node can contain one or multiple conditions, all of which must be met to activate the cue. If the node is missing, the cue will become active unconditionally. The conditions are checked in sequence, and if a check fails, the following conditions are ignored. There are two types of conditions: Events and non-event conditions.
@@ -180,10 +180,18 @@
  The attributes //onfail//, //checkinterval//, //checktime// are not allowed for cues with event conditions.
++\\
++
  {{note body="Reminder: When using an XSD-capable editor, it's a great help, but you cannot rely on that alone to verify correctness. Please also check the documentation and look for errors in the game debug output. Concretely, the schema cannot tell whether the above cue attributes are used correctly."/}}
++
++
++\\
++
++(% id="actions" %)
++
  == Actions ==
  The <actions> node contains the actions that are performed one after another, without any delay inbetween. You can enforce a delay after activation of the cue and actual action performance, using a <delay> node right before the <actions>:
@@ -228,6 +228,12 @@
  Every action can have a //**chance**// attribute, if you only want it to be performed with that chance, given as percentage. Otherwise it will simply be skipped. If chance is used on a conditional action such as <do_if>, the script will behave as if the condition check failed.
++\\
++
++┬á
++
++(% id="libraries" %)
++
  = Libraries =
  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.
@@ -297,8 +297,10 @@
  * 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.(% id="library-parameters" %)
++** 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 ==
  A library can be parametrised, so that it can be adapted to the needs of a missions that uses it. You can define required and/or optional parameters for a library, and it will be validated at load time that the user of the library has provided all required parameters.
@@ -340,11 +340,16 @@
  If your library is supposed to provide a result to the library user, it is recommended to store a predefined variable in the library cue with a standardised name, e.g. $result. The user will be able to read it via CueName.$result. This variable does not have to be defined as a parameter but should be documented in the library.
++\\
++
++(% id="instantiation" %)
++
  = 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 (% 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.
++\\\\\\\\\\(% id="cleaning-up-instances-explicitly" %)
  == Cleaning up instances explicitly ==
@@ -352,6 +352,10 @@
  {{info body="&lt;cancel_cue&gt; and &lt;reset_cue&gt; only take effect after all remaining actions of the current cue are performed. So you can even safely cancel the cue that you are currently in (keyword ΓÇ£'''this'''ΓÇ¥) or any ancestor cue, and still perform more actions afterwards."/}}
++
++
++(% id="access-to-instances" %)
++
  == Access to instances ==
@@ -389,6 +389,10 @@
  You can store cue references in variables. But when storing an instance cue in a variable, and later accessing that variable, be aware that the instance may not exist any more. Use the property **exists** to check if an instance is still alive. (In contrast, non-instance cues always exist, but may be in the //disabled// or //cancelled// state.)
++\\
++
++(% id="pitfalls" %)
++
  == Pitfalls ==
  Some additional common pitfalls with respect to instantiation are listed here. There may be more.
@@ -402,10 +402,16 @@
  * **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.
++┬á
++
++(% id="categorybroken_macroanchorexpressions" %)
++
  = Expressions =
--Most of the attribute values in actions and conditions are interpreted as script expressions and parsed accordingly. An expression is a phrase that can be evaluated to a single value. The simplest expressions are actual numeric values and strings, so called **literals:**
++Most of the attribute values in actions and conditions are interpreted as script expressions and parsed accordingly. An expression is a phrase that can be evaluated to a single value. The simplest expressions are actual numeric values and strings, so called **literals:**\\
++
++
  * {{code}}0{{/code}} (integer number)
  * {{code}}0772{{/code}} (leading 0 means octal integer number)
  * {{code}}3.14159{{/code}} (floating point number)
@@ -428,6 +428,12 @@
  {{note body="Since expressions are written in XML attribute values, you have to use the single quotes inside the double quotes for the actual attribute value. To write characters like '''&lt; &gt; &quot; &amp;''' in an expression string (or anywhere else in an XML attribute value), youΓÇÖll have to escape them as '''&amp;lt; &amp;gt; &amp;quot; &amp;amp;''' respectively. The backslash '''\''' can be used in strings for escape characters like in C/C++. Most important are '''\'''' for a single quote as part of the string, and '''\\''' for the backslash itself."/}}
++
++
++\\
++
++(% id="numeric-data-types-and-suffixes" %)
++
  == 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:
@@ -443,8 +443,14 @@
  Here is the complete list of numeric data types and corresponding unit suffixes:
++\\
++
  (% style="margin-left: 0.0px;" %)
  (((
++\\
++
++
++
  |Data type|Suffix|Examples|Description
  |null|(none)|null|Converted to non-null data type of value 0 when needed.
  |integer|i|42|32-bit signed integer. Default for integer literals, so the suffix is not required for them.
@@ -480,12 +480,24 @@
  {{note body="All unit data types are floating point types, except for money, which is an integer data type."/}}
++\\
++
++
++
++(% id="categorybroken_macroanchoroperators" %)
++
  == Operators ==
--You can build expressions by combining sub-expressions with operators. For Boolean operations, expressions are considered ΓÇ£falseΓÇ¥ if they are equal to zero, ΓÇ£trueΓÇ¥ otherwise. The following operators, delimiters, and constants are supported
++You can build expressions by combining sub-expressions with operators. For Boolean operations, expressions are considered ΓÇ£falseΓÇ¥ if they are equal to zero, ΓÇ£trueΓÇ¥ otherwise. The following operators, delimiters, and constants are supported:
++\\
++
  (% style="margin-left: 0.0px;" %)
  (((
++\\
++
++
++
  |Operator / Delimiter / Constant|Type|Example|Result of example|Description
  |null|constant|{{code}}null + 1{{/code}}|{{code}}1{{/code}}|Null value, see above
  |false|constant|{{code}}1 == 0{{/code}}|{{code}}false{{/code}}|Integer value 0, useful in Boolean expressions
@@ -565,13 +565,20 @@
  {{code}}null{{/code}}
  \\{{code}}'T'{{/code}}|Conditional operator ("inline if")
--)))(% id="operator-precedence-rules" %)
--(%%)
++\\
++
++
++)))
++
++(% 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.
++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: ^
  * Multiplicative: *, /, %
@@ -616,8 +616,10 @@
  === Boolean operators ===
--Some additional notes on Boolean operators (such as and, or, not, ==):
++Some additional notes on Boolean operators (such as and, or, not, ==):\\
++
++
  * Of course a Boolean operation always results in true or false (integer 1 or 0).
  * Values of any type can be used as Boolean operands, e.g. for ΓÇ£andΓÇ¥. They will be interpreted as ΓÇ£trueΓÇ¥ if they are **non-zero** or **non-numeric**.
  * != and == can be used with any data types, even non-numeric ones. When comparing two numeric values, they are converted using the rules above. Values of non-numeric types are never equal to null, or to any other numbers.
@@ -626,10 +626,10 @@
  * 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" %)
  {{{==}}}

Changes for page Mission Director Guide

Summary

Details

Navigation

Applications