Changes for page Mission Director Guide

Summary

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

Details

Page properties

Title

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

Parent

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

Content

...	...	@@ -1,6 +1,6 @@
1	1	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.\\
2	2
3		-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.
	3	+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.
4	4
5	5	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++).
6	6
...	...	@@ -16,7 +16,7 @@
16	16
17	17	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.
18	18
19		-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.
	19	+To edit MD scripts, an XML editing tool is needed. Microsoft Visual Studio (if available) or [[(% &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.
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
...	...	@@ -341,8 +341,8 @@
341	341
342	342	= Instantiation =
343	343
344		-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.**
345		-\\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.
	344	+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.**
	345	+\\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.
346	346	\\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.
347	347
348	348	== Cleaning up instances explicitly ==
...	...	@@ -394,7 +394,7 @@
394	394
395	395	* **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:\\
396	396
397		-{{code}}<debug_text text="static.$foo"/>{{/code}}(% style="color: rgb(0,0,255);text-decoration: none;" %)
	397	+{{code}}<debug_text text="static.$foo"/>{{/code}}
398	398	\\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:
399	399	\\{{code}}<set_value name="$foo" exact="static.$foo"/>{{/code}}
400	400
...	...	@@ -1123,8 +1123,6 @@
1123	1123
1124	1124	\\
1125	1125
1126		-(% id="categorybroken_macroanchorrandom-ranges" %)
1127		-
1128	1128	== Random ranges ==
1129	1129
1130	1130	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:
...	...	@@ -1145,7 +1145,6 @@
1145	1145
1146	1146	{{code}}<set_value name="$foo" min="-20" max="20" profile="profile.increasing" scale="4"/>{{/code}}
1147	1147
1148		-(% style="color: rgb(0,0,255);text-decoration: none;" %)
1149	1149	\\(% id="variables-and-namespaces" %)
1150	1150
1151	1151	= Variables and namespaces =
...	...	@@ -1152,7 +1152,7 @@
1152	1152
1153	1153	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).
1154	1154
1155		-(% style="color: rgb(0,0,255);text-decoration: none;" %)
	1152	+
1156	1156	\\\\\\(% id="categorybroken_macroanchorcreating-and-removing-variables" %)
1157	1157
1158	1158	== Creating and removing variables ==
...	...	@@ -1189,7 +1189,6 @@
1189	1189
1190	1190	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.
1191	1191
1192		-(% style="color: rgb(0,0,255);text-decoration: none;" %)
1193	1193	\\\\\\(% id="accessing-remote-variables" %)
1194	1194
1195	1195	== Accessing remote variables ==
...	...	@@ -1202,7 +1202,6 @@
1202	1202
1203	1203	{{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}}
1204	1204
1205		-(% style="color: rgb(0,0,255);text-decoration: none;" %)
1206	1206	\\\\\\(% id="namespaces" %)
1207	1207
1208	1208	== Namespaces ==
...	...	@@ -1227,9 +1227,7 @@
1227	1227	* **static**: Same as "this", but when instantiated, use the static cue: $foo == static.$foo
1228	1228	* **default**: The namespace is inherited from the parent cue. The default for root cues and for libraries is the same as "static".
1229	1229
1230		-(% style="color: rgb(0,0,255);text-decoration: none;" %)
1231	1231
1232		-
1233	1233	{{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:
1234	1234
1235	1235	<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}}