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.
...	...	@@ -24,6 +24,10 @@
24	24
25	25	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."/}}
26	26
	37	+
	38	+
	39	+(% id="categorybroken_macroanchorscript-debug-output" %)
	40	+
27	27	== Script debug output ==
28	28
29	29	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]].
...	...	@@ -40,6 +40,10 @@
40	40
41	41	The script action <debug_text> can be used to print debug messages from within a script.\\
42	42
	57	+\\
	58	+
	59	+(% id="md-script-structure" %)
	60	+
43	43	= MD script structure =
44	44
45	45	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.
...	...	@@ -67,6 +67,10 @@
67	67	</mdscript>
68	68	{{/code}}
69	69
	88	+ 
	89	+
	90	+(% id="categorybroken_macroanchorcues" %)
	91	+
70	70	== Cues ==
71	71
72	72	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.
...	...	@@ -84,8 +84,14 @@
84	84
85	85	\\
86	86
	109	+
	110	+
87	87	{{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 />"/}}
88	88
	113	+
	114	+
	115	+\\
	116	+
89	89	This is how a cue node looks like:
90	90
91	91	{{code language="xml"}}
...	...	@@ -102,6 +102,10 @@
102	102
103	103	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.
104	104
	133	+\\
	134	+
	135	+(% id="categorybroken_macroanchorconditions" %)
	136	+
105	105	== Conditions ==
106	106
107	107	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.
...	...	@@ -178,10 +178,18 @@
178	178
179	179	The attributes //onfail//, //checkinterval//, //checktime// are not allowed for cues with event conditions.
180	180
	213	+\\
181	181
182	182
	216	+
183	183	{{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."/}}
184	184
	219	+
	220	+
	221	+\\
	222	+
	223	+(% id="actions" %)
	224	+
185	185	== Actions ==
186	186
187	187	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>:
...	...	@@ -226,6 +226,12 @@
226	226
227	227	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.
228	228
	269	+\\
	270	+
	271	+ 
	272	+
	273	+(% id="libraries" %)
	274	+
229	229	= Libraries =
230	230
231	231	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.
...	...	@@ -295,8 +295,10 @@
295	295
296	296	* 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).
297	297	* You //can// access variables in the library root but generally this should be avoided in favor of parameterizing the library!
298		-** 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.
299	299
	346	+(% id="library-parameters" %)
	347	+
300	300	== Library Parameters ==
301	301
302	302	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.
...	...	@@ -338,11 +338,18 @@
338	338
339	339	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.
340	340
	389	+\\
	390	+
	391	+ 
	392	+
	393	+(% id="instantiation" %)
	394	+
341	341	= Instantiation =
342	342
343	343	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.**
344	344	\\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.
345	345	\\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" %)
346	346
347	347	== Cleaning up instances explicitly ==
348	348
...	...	@@ -350,6 +350,10 @@
350	350
351	351	{{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."/}}
352	352
	408	+
	409	+
	410	+(% id="access-to-instances" %)
	411	+
353	353	== Access to instances ==
354	354
355	355
...	...	@@ -387,6 +387,10 @@
387	387
388	388	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.)
389	389
	449	+\\
	450	+
	451	+(% id="pitfalls" %)
	452	+
390	390	== Pitfalls ==
391	391
392	392	Some additional common pitfalls with respect to instantiation are listed here. There may be more.
...	...	@@ -400,10 +400,16 @@
400	400	* **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.
401	401	* **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.
402	402
	466	+ 
	467	+
	468	+(% id="categorybroken_macroanchorexpressions" %)
	469	+
403	403	= Expressions =
404	404
405		-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:**\\
406	406
	474	+
	475	+
407	407	* {{code}}0{{/code}} (integer number)
408	408	* {{code}}0772{{/code}} (leading 0 means octal integer number)
409	409	* {{code}}3.14159{{/code}} (floating point number)
...	...	@@ -426,6 +426,12 @@
426	426
427	427	{{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."/}}
428	428
	498	+
	499	+
	500	+\\
	501	+
	502	+(% id="numeric-data-types-and-suffixes" %)
	503	+
429	429	== Numeric data types and suffixes ==
430	430
431	431	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:
...	...	@@ -441,8 +441,14 @@
441	441
442	442	Here is the complete list of numeric data types and corresponding unit suffixes:
443	443
	519	+\\
	520	+
444	444	(% style="margin-left: 0.0px;" %)
445	445	(((
	523	+\\
	524	+
	525	+
	526	+
446	446	|Data type|Suffix|Examples|Description
447	447	|null|(none)|null|Converted to non-null data type of value 0 when needed.
448	448	|integer|i|42|32-bit signed integer. Default for integer literals, so the suffix is not required for them.
...	...	@@ -478,12 +478,24 @@
478	478
479	479	{{note body="All unit data types are floating point types, except for money, which is an integer data type."/}}
480	480
	562	+\\
	563	+
	564	+
	565	+
	566	+(% id="categorybroken_macroanchoroperators" %)
	567	+
481	481	== Operators ==
482	482
483		-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:
484	484
	572	+\\
	573	+
485	485	(% style="margin-left: 0.0px;" %)
486	486	(((
	576	+\\
	577	+
	578	+
	579	+
487	487	|Operator / Delimiter / Constant|Type|Example|Result of example|Description
488	488	|null|constant|{{code}}null + 1{{/code}}|{{code}}1{{/code}}|Null value, see above
489	489	|false|constant|{{code}}1 == 0{{/code}}|{{code}}false{{/code}}|Integer value 0, useful in Boolean expressions
...	...	@@ -563,13 +563,20 @@
563	563	{{code}}null{{/code}}
564	564	\\{{code}}'T'{{/code}}|Conditional operator ("inline if")
565	565
566		-)))(% id="operator-precedence-rules" %)
567		-(%%)
568	568
	660	+\\
	661	+
	662	+
	663	+)))
	664	+
	665	+(% id="operator-precedence-rules" %)
	666	+
569	569	=== Operator precedence rules ===
570	570
571		-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.\\
572	572
	671	+
	672	+
573	573	* Unary operators: +, -, not, typeof, function-style operators (highest precedence)
574	574	* Power operator: ^
575	575	* Multiplicative: *, /, %
...	...	@@ -614,8 +614,10 @@
614	614
615	615	=== Boolean operators ===
616	616
617		-Some additional notes on Boolean operators (such as and, or, not, ==):
	717	+Some additional notes on Boolean operators (such as and, or, not, ==):\\
618	618
	719	+
	720	+
619	619	* Of course a Boolean operation always results in true or false (integer 1 or 0).
620	620	* 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**.
621	621	* != 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.
...	...	@@ -624,10 +624,10 @@
624	624	* 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.
625	625	* <, <=, >, >= 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.
626	626
	729	+\\
627	627
	731	+(% id="categorybroken_macroanchorstrings-and-formatting" %)== Strings and formatting
628	628
629		-(% id="categorybroken_macroanchorstrings-and-formatting" %)== Strings and formatting==
630		-(% id="categorybroken_macroanchorstrings-and-formatting" %)
631	631
632	632	{{{==}}}
633	633