Changes for page Mission Director Guide

Summary

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

Details

Page properties

Tags

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

Content

...	...	@@ -6,10 +6,20 @@
6	6
7	7	{{{The general MD scripting system is the same in XR and X4, so this guide applies to both games. However, each game has its own set of supported script features (i.e. actions, conditions and properties), so in general scripts from different games are not compatible.}}}
8	8
9		-(% id="md-scripts" %)
	9	+\\
10	10
	11	+(% id="table-of-contents" %)
	12	+
11	11	{{toc/}}
12	12
	15	+= Table of Contents =
	16	+
	17	+{{{__TOC__ }}}
	18	+
	19	+\\
	20	+
	21	+(% id="md-scripts" %)
	22	+
13	13	= MD scripts =
14	14
15	15	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.
...	...	@@ -20,12 +20,14 @@
20	20
21	21	This functionality is only available if the schema files **md.xsd** and **common.xsd** are in the correct folder. If you are editing the XML in the game folder directly, all is well and the files are loaded from the libraries folder. However, if you are editing in a separate folder, copy those XSD files from the libraries folder directly into the folder where your XML files are located.
22	22
23		-{{note}}
24		-Even if your script is free of XSD errors, that does not mean that the script syntax is correct. For example, there are XML elements that require at least one of multiple attributes, but this requirement cannot be reflected in a schema (apart from documentation text). Please notice the XSD documentation of the elements and attributes, e.g. displayed via tooltips in Visual Studio / Visual Web Developer. Please also note additional requirements for MD cue attributes in this guide (see [[NULL|Conditions]]).
	33	+{{note body="Even if your script is free of XSD errors, that does not mean that the script syntax is correct. For example, there are XML elements that require at least one of multiple attributes, but this requirement cannot be reflected in a schema (apart from documentation text). Please notice the XSD documentation of the elements and attributes, e.g. displayed via tooltips in Visual Studio / Visual Web Developer. Please also note additional requirements for MD cue attributes in this guide (see [[NULL|Conditions]]).
25	25
26		-To check for errors, please pay attention to in-game error messages that are produced while your script is imported, and run-time errors while the script runs. The XSD files can help you a lot, but you should not rely on the absence of XSD errors."
27		-{{/note}}
	35	+To check for errors, please pay attention to in-game error messages that are produced while your script is imported, and run-time errors while the script runs. The XSD files can help you a lot, but you should not rely on the absence of XSD errors."/}}
28	28
	37	+
	38	+
	39	+(% id="categorybroken_macroanchorscript-debug-output" %)
	40	+
29	29	== Script debug output ==
30	30
31	31	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,10 @@
42	42
43	43	The script action <debug_text> can be used to print debug messages from within a script.\\
44	44
	57	+\\
	58	+
	59	+(% id="md-script-structure" %)
	60	+
45	45	= MD script structure =
46	46
47	47	In this section we will look at how to start the whole process by creating a new MD mission file and the basic steps in producing mission content with XML code. There will be a description of the key elements of the mission file.
...	...	@@ -69,6 +69,10 @@
69	69	</mdscript>
70	70	{{/code}}
71	71
	88	+ 
	89	+
	90	+(% id="categorybroken_macroanchorcues" %)
	91	+
72	72	== Cues ==
73	73
74	74	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.
...	...	@@ -86,8 +86,14 @@
86	86
87	87	\\
88	88
	109	+
	110	+
89	89	{{note body="There can be a delay between the activation and performing the actions if the &lt;delay&gt; tag is used. In this case, sub-cues will be enter the waiting state before the parent's actions are performed.<br />"/}}
90	90
	113	+
	114	+
	115	+\\
	116	+
91	91	This is how a cue node looks like:
92	92
93	93	{{code language="xml"}}
...	...	@@ -104,6 +104,10 @@
104	104
105	105	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.
106	106
	133	+\\
	134	+
	135	+(% id="categorybroken_macroanchorconditions" %)
	136	+
107	107	== Conditions ==
108	108
109	109	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 @@
180	180
181	181	The attributes //onfail//, //checkinterval//, //checktime// are not allowed for cues with event conditions.
182	182
	213	+\\
183	183
184	184
	216	+
185	185	{{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."/}}
186	186
	219	+
	220	+
	221	+\\
	222	+
	223	+(% id="actions" %)
	224	+
187	187	== Actions ==
188	188
189	189	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 @@
228	228
229	229	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.
230	230
	269	+\\
	270	+
	271	+ 
	272	+
	273	+(% id="libraries" %)
	274	+
231	231	= Libraries =
232	232
233	233	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 @@
297	297
298	298	* It is //not// possible to directly call a cue which is 'inside' the library from 'outside' of the library, but it is possible to signal the library ref itself (possibly with parameters) and have a sub-cue inside the library listen to the signal on the library ref (possibly checking the parameters).
299	299	* You //can// access variables in the library root but generally this should be avoided in favor of parameterizing the library!
300		-** there are some cases where you do want to access these variables directly, for example for maintaining savegame compatibility when patching.(% id="library-parameters" %)
	344	+** there are some cases where you do want to access these variables directly, for example for maintaining savegame compatibility when patching.
301	301
	346	+(% id="library-parameters" %)
	347	+
302	302	== Library Parameters ==
303	303
304	304	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,18 @@
340	340
341	341	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.
342	342
	389	+\\
	390	+
	391	+ 
	392	+
	393	+(% id="instantiation" %)
	394	+
343	343	= Instantiation =
344	344
345	345	One of the possible cue attributes is //**instantiate**//. If you set it to true, this changes what happens when a cue's conditions are met. Normally, if a cue is (% style="color: rgb(0,0,0);text-decoration: underline;" %)not instantiated, the cue's actions are run (taking a delay node into account) and the cue is marked as completed. But with **instantiate'//, a// **copy of the cue** (and all its sub-cues) is made when the conditions are met, and it is this copy in which the actions are performed and it is the copy whose status is set to complete when they are finished - this means that the original cue (the so-called **static cue**) remains in the //waiting// state, and if the conditions are met again then the whole thing happens all over again.**
346	346	\\An instantiating cue should only be used with conditions that are only going to be met once (or a fairly limited number of times), or with conditions that include an event condition. Instantiation should (% style="color: rgb(0,0,0);text-decoration: underline;" %)not be used in a cue which, say, just depends on the game time being greater than a specific value as this will result in a copy of the cue being made after each check interval, which could increase memory usage a lot. The most common use of an instantiated cue is in responding to events such as the player ship changing sector, to react every time that event happens.
347	347	\\Instances that are created via //instantiate// are called **instantiated cues**. But sub-cues of instances are also instances (**sub-instances**) - they are created when they enter the waiting state. An instance is removed again (thereby freeing its memory) when it is complete or cancelled, and when all its instance sub-cues have been removed before. The simplest case is an instantiating cue with no sub-cues: The instance is created, the actions are performed, and the instance is removed immediately on completion. A pitfall could be an instance with a sub-cue that is forever in the waiting state (e.g. waiting for an event from an already destroyed object). It can never be removed, so you should clean up such a cue yourself, e.g. by cancelling it explicitly.
	400	+\\\\\\\\\\(% id="cleaning-up-instances-explicitly" %)
348	348
349	349	== Cleaning up instances explicitly ==
350	350
...	...	@@ -352,6 +352,10 @@
352	352
353	353	{{info body="&lt;cancel_cue&gt; and &lt;reset_cue&gt; only take effect after all remaining actions of the current cue are performed. So you can even safely cancel the cue that you are currently in (keyword ΓÇ£'''this'''ΓÇ¥) or any ancestor cue, and still perform more actions afterwards."/}}
354	354
	408	+
	409	+
	410	+(% id="access-to-instances" %)
	411	+
355	355	== Access to instances ==
356	356
357	357
...	...	@@ -389,6 +389,10 @@
389	389
390	390	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.)
391	391
	449	+\\
	450	+
	451	+(% id="pitfalls" %)
	452	+
392	392	== Pitfalls ==
393	393
394	394	Some additional common pitfalls with respect to instantiation are listed here. There may be more.
...	...	@@ -402,10 +402,16 @@
402	402	* **Resetting completed/cancelled instances:** As explained above, sub-instances are only created when needed (when going to the //waiting// state) and are destroyed when they are not needed any more (when they are completed or cancelled, including all sub-cues). There are cases in which you want to access cues that donΓÇÖt exist any more - it simply doesnΓÇÖt work. In some cases you are safe: You can be sure that all your ancestors exist, and instantiating cues wonΓÇÖt be removed until they are cancelled. In some other cases you simply donΓÇÖt know and have to check if the instance is already (or still) there.
403	403	* **Lifetime of instances:** Do not make assumptions about when an instance is removed! Just looking at it in the Debug Manager keeps it alive for the time being. So, sometimes you could still have a completed instance that wouldnΓÇÖt exist under other circumstances.
404	404
	466	+ 
	467	+
	468	+(% id="categorybroken_macroanchorexpressions" %)
	469	+
405	405	= Expressions =
406	406
407		-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:**
	472	+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:**\\
408	408
	474	+
	475	+
409	409	* {{code}}0{{/code}} (integer number)
410	410	* {{code}}0772{{/code}} (leading 0 means octal integer number)
411	411	* {{code}}3.14159{{/code}} (floating point number)
...	...	@@ -428,6 +428,12 @@
428	428
429	429	{{note body="Since expressions are written in XML attribute values, you have to use the single quotes inside the double quotes for the actual attribute value. To write characters like '''&lt; &gt; &quot; &amp;''' in an expression string (or anywhere else in an XML attribute value), youΓÇÖll have to escape them as '''&amp;lt; &amp;gt; &amp;quot; &amp;amp;''' respectively. The backslash '''\''' can be used in strings for escape characters like in C/C++. Most important are '''\'''' for a single quote as part of the string, and '''\\''' for the backslash itself."/}}
430	430
	498	+
	499	+
	500	+\\
	501	+
	502	+(% id="numeric-data-types-and-suffixes" %)
	503	+
431	431	== Numeric data types and suffixes ==
432	432
433	433	Numbers can have a suffix that determines their numeric type. There are also numerical data types like ΓÇ£moneyΓÇ¥ or ΓÇ£timeΓÇ¥ which can only be expressed by using an appropriate unit suffix:
...	...	@@ -443,8 +443,14 @@
443	443
444	444	Here is the complete list of numeric data types and corresponding unit suffixes:
445	445
	519	+\\
	520	+
446	446	(% style="margin-left: 0.0px;" %)
447	447	(((
	523	+\\
	524	+
	525	+
	526	+
448	448	|Data type|Suffix|Examples|Description
449	449	|null|(none)|null|Converted to non-null data type of value 0 when needed.
450	450	|integer|i|42|32-bit signed integer. Default for integer literals, so the suffix is not required for them.
...	...	@@ -480,12 +480,24 @@
480	480
481	481	{{note body="All unit data types are floating point types, except for money, which is an integer data type."/}}
482	482
	562	+\\
	563	+
	564	+
	565	+
	566	+(% id="categorybroken_macroanchoroperators" %)
	567	+
483	483	== Operators ==
484	484
485		-You can build expressions by combining sub-expressions with operators. For Boolean operations, expressions are considered ΓÇ£falseΓÇ¥ if they are equal to zero, ΓÇ£trueΓÇ¥ otherwise. The following operators, delimiters, and constants are supported
	570	+You can build expressions by combining sub-expressions with operators. For Boolean operations, expressions are considered ΓÇ£falseΓÇ¥ if they are equal to zero, ΓÇ£trueΓÇ¥ otherwise. The following operators, delimiters, and constants are supported:
486	486
	572	+\\
	573	+
487	487	(% style="margin-left: 0.0px;" %)
488	488	(((
	576	+\\
	577	+
	578	+
	579	+
489	489	|Operator / Delimiter / Constant|Type|Example|Result of example|Description
490	490	|null|constant|{{code}}null + 1{{/code}}|{{code}}1{{/code}}|Null value, see above
491	491	|false|constant|{{code}}1 == 0{{/code}}|{{code}}false{{/code}}|Integer value 0, useful in Boolean expressions
...	...	@@ -565,13 +565,20 @@
565	565	{{code}}null{{/code}}
566	566	\\{{code}}'T'{{/code}}|Conditional operator ("inline if")
567	567
568		-)))(% id="operator-precedence-rules" %)
569		-(%%)
570	570
	660	+\\
	661	+
	662	+
	663	+)))
	664	+
	665	+(% id="operator-precedence-rules" %)
	666	+
571	571	=== Operator precedence rules ===
572	572
573		-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.
	669	+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.\\
574	574
	671	+
	672	+
575	575	* Unary operators: +, -, not, typeof, function-style operators (highest precedence)
576	576	* Power operator: ^
577	577	* Multiplicative: *, /, %
...	...	@@ -616,8 +616,10 @@
616	616
617	617	=== Boolean operators ===
618	618
619		-Some additional notes on Boolean operators (such as and, or, not, ==):
	717	+Some additional notes on Boolean operators (such as and, or, not, ==):\\
620	620
	719	+
	720	+
621	621	* Of course a Boolean operation always results in true or false (integer 1 or 0).
622	622	* Values of any type can be used as Boolean operands, e.g. for ΓÇ£andΓÇ¥. They will be interpreted as ΓÇ£trueΓÇ¥ if they are **non-zero** or **non-numeric**.
623	623	* != and == can be used with any data types, even non-numeric ones. When comparing two numeric values, they are converted using the rules above. Values of non-numeric types are never equal to null, or to any other numbers.
...	...	@@ -626,10 +626,10 @@
626	626	* Unlike != and ==, the comparison operators <, <=, >, >= are only supported **for numeric values**, **difficulty levels**, and **attention levels**. Comparing other non-numeric values will result in an error and an undefined result.
627	627	* <, <=, >, >= cannot be used in XML directly, so lt, le, gt, ge are provided as alternatives. In some cases you wonΓÇÖt have to use them, though - using [[range checks>>MediaWiki.NULL]] with additional XML attributes can be more readable.
628	628
	729	+\\
629	629
	731	+(% id="categorybroken_macroanchorstrings-and-formatting" %)== Strings and formatting
630	630
631		-(% id="categorybroken_macroanchorstrings-and-formatting" %)== Strings and formatting==
632		-(% id="categorybroken_macroanchorstrings-and-formatting" %)
633	633
634	634	{{{==}}}
635	635