Skip to Content

Changes for page Mission Director Guide

Last modified by Klaus Meyer on 2025/03/31 16:39
From version 31067.1
edited by Daniel Turner
on 2023/04/14 16:47
Change comment: Created page with "{{Info |body = Please note that this is officially-maintained documentation. To ensure that you can rely on the information having been checked by Egosoft, you will not be able to edit this page. }} <span style="color: rgb(0,0,0);text-decoration: none;"><br /> </span> <span style="color: rgb(0,0,0);text-decoration: none;">The Mission Director (MD) is a subsystem of the game and interprets mission scripts, which are written in an XML-based language. The Mission D..."
To version 31191.1
edited by Daniel Turner
on 2023/04/25 11:20
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -1,12 +10,3 @@
1 -{{info body="Please note that this is officially-maintained documentation.
2 -
3 -To ensure that you can rely on the information having been checked by Egosoft, you will not be able to edit this page."/}}
4 -
5 -
6 -
7 -(% style="color: rgb(0,0,0);text-decoration: none;" %)
8 -
9 -
10 10  (% style="color: rgb(0,0,0);text-decoration: none;" %)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.
11 11  
12 12  
... ... @@ -80,13 +80,26 @@
80 80  
81 81  (% style="color: rgb(0,0,0);text-decoration: none;" %)The XML root node of an MD file is called ΓÇ£mdscriptΓÇ¥ and looks like this:
82 82  
83 -{{code}}&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;&lt;mdscript name=&quot;ScriptName&quot; xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot; xsi:noNamespaceSchemaLocation=&quot;md.xsd&quot;&gt;{{/code}}
74 +{{code language="xml"}}
75 +<?xml version="1.0" encoding="utf-8"?>
76 +<mdscript name="ScriptName" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="md.xsd">
77 +{{/code}}
84 84  
85 85  (% style="color: rgb(0,0,0);text-decoration: none;" %)ΓÇ£ScriptNameΓÇ¥ is the name used for this script regardless of the file name. It (%%)**(% style="color: rgb(0,0,0);text-decoration: none;" %)has to start with an upper case letter and must be unique(%%)**(% style="color: rgb(0,0,0);text-decoration: none;" %) 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.
86 86  
87 87  (% style="color: rgb(0,0,0);text-decoration: none;" %)The only allowed sub-node of <mdscript> is <cues>, which can only contain <cue> sub-nodes:
88 88  
89 -{{code}}&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;&lt;mdscript name=&quot;ScriptName&quot; ...&gt;  &lt;cues&gt;    &lt;cue name=&quot;RootCue1&quot;&gt; [...]    &lt;/cue&gt;    &lt;cue name=&quot;RootCue2&quot;&gt; [...]    &lt;/cue&gt;  &lt;/cues&gt;&lt;/mdscript&gt;{{/code}}
83 +{{code language="xml"}}
84 +<?xml version="1.0" encoding="utf-8"?>
85 +<mdscript name="ScriptName" ...>
86 + <cues>
87 + <cue name="RootCue1"> [...]
88 + </cue>
89 + <cue name="RootCue2"> [...]
90 + </cue>
91 + </cues>
92 +</mdscript>
93 +{{/code}}
90 90  
91 91  (% style="color: rgb(0,0,0);text-decoration: none;" %)┬á
92 92  
... ... @@ -118,7 +118,17 @@
118 118  
119 119  (% style="color: rgb(0,0,0);text-decoration: none;" %)This is how a cue node looks like:
120 120  
121 -{{code}}&lt;cue name=&quot;CueName&quot;&gt;  &lt;conditions&gt; [...]  &lt;/conditions&gt;  &lt;delay exact=&quot;5s&quot; /&gt;  &lt;actions&gt; [...]  &lt;/actions&gt;  &lt;cues&gt; [...]  &lt;/cues&gt;&lt;/cue&gt;{{/code}}
125 +{{code language="xml"}}
126 +<cue name="CueName">
127 + <conditions> [...]
128 + </conditions>
129 + <delay exact="5s" />
130 + <actions> [...]
131 + </actions>
132 + <cues> [...]
133 + </cues>
134 +</cue>
135 +{{/code}}
122 122  
123 123  (% style="color: rgb(0,0,0);text-decoration: none;" %)The rules for naming cues is the same for MD script names: The name **starts with an upper case letter**, and has to be (%%)**(% style="color: rgb(0,0,0);text-decoration: none;" %)unique within this file(%%)**(% style="color: rgb(0,0,0);text-decoration: none;" %). So it is actually possible to use the same cue name in different scripts, which is different from the MD in X3.
124 124  
... ... @@ -137,15 +137,35 @@
137 137  
138 138  (% style="color: rgb(0,0,0);text-decoration: none;" %)Example for an event condition:
139 139  
140 -{{code}}&lt;conditions&gt;  &lt;event_object_destroyed object=&quot;$target&quot;/&gt;&lt;/conditions&gt;{{/code}}
154 +{{code language="xml"}}
155 +<conditions>
156 + <event_object_destroyed object="$target"/>
157 +</conditions>
158 +{{/code}}
141 141  
142 142  (% style="color: rgb(0,0,0);text-decoration: none;" %)Example for an event condition with an additional (non-event) check:
143 143  
144 -{{code}}&lt;conditions&gt;  &lt;event_player_killed_object/&gt;  &lt;check_value value=&quot;event.param.isclass.turret&quot;/&gt;&lt;/conditions&gt;{{/code}}
162 +{{code language="xml"}}
163 +<conditions>
164 + <event_player_killed_object/>
165 + <check_value value="event.param.isclass.turret"/>
166 +</conditions>
167 +{{/code}}
145 145  
146 146  (% style="color: rgb(0,0,0);text-decoration: none;" %)Example for an event condition with two alternative events and a common additional check:
147 147  
148 -{{code}}&lt;conditions&gt;  &lt;check_any&gt;    &lt;event_cue_completed cue=&quot;Cue1&quot;/&gt;    &lt;check_all&gt;      &lt;event_player_killed_object/&gt;      &lt;check_value value=&quot;event.param.isclass.turret&quot;/&gt;    &lt;/check_all&gt;  &lt;/check_any&gt;  &lt;check_age min=&quot;$starttime&quot;/&gt;&lt;/conditions&gt;{{/code}}
171 +{{code language="xml"}}
172 +<conditions>
173 + <check_any>
174 + <event_cue_completed cue="Cue1"/>
175 + <check_all>
176 + <event_player_killed_object/>
177 + <check_value value="event.param.isclass.turret"/>
178 + </check_all>
179 + </check_any>
180 + <check_age min="$starttime"/>
181 +</conditions>
182 +{{/code}}
149 149  
150 150  (% style="color: rgb(0,0,0);text-decoration: none;" %)For more information about expressions and event parameters, see below.
151 151  
... ... @@ -163,11 +163,21 @@
163 163  
164 164  (% style="color: rgb(0,0,0);text-decoration: none;" %)Check conditions every 5 seconds, but start checking only 1 hour after game start.
165 165  
166 -{{code}}&lt;cue name=&quot;Foo&quot; checktime=&quot;1h&quot; checkinterval=&quot;5s&quot;&gt;  &lt;conditions&gt;  [...]&lt;/cue&gt;{{/code}}
200 +{{code language="xml"}}
201 +<cue name="Foo" checktime="1h" checkinterval="5s">
202 + <conditions>
203 + [...]
204 +</cue>
205 +{{/code}}
167 167  
168 168  (% style="color: rgb(0,0,0);text-decoration: none;" %)Check conditions 3 seconds after the cue is enabled, and cancel the cue in case of failure.
169 169  
170 -{{code}}&lt;cue name=&quot;Foo&quot; checktime=&quot;player.age + 3s&quot; onfail=&quot;cancel&quot;&gt;  &lt;conditions&gt;  [...]&lt;/cue&gt;{{/code}}
209 +{{code language="xml"}}
210 +<cue name="Foo" checktime="player.age + 3s" onfail="cancel">
211 + <conditions>
212 + [...]
213 +</cue>
214 +{{/code}}
171 171  
172 172  (% style="color: rgb(0,0,0);text-decoration: none;" %)(% style="color: rgb(0,0,0);text-decoration: none;" %)(% style="color: rgb(0,0,0);text-decoration: none;" %)The attributes //onfail//, //checkinterval//, //checktime// are not allowed for cues with event conditions.
173 173  
... ... @@ -187,11 +187,15 @@
187 187  
188 188  (% style="color: rgb(0,0,0);text-decoration: none;" %)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>:
189 189  
190 -{{code}}&lt;delay min=&quot;10s&quot; max=&quot;30s&quot;/&gt;{{/code}}
234 +{{code language="xml"}}
235 +<delay min="10s" max="30s"/>
236 +{{/code}}
191 191  
192 192  (% style="color: rgb(0,0,0);text-decoration: none;" %)Note that during the delay the cue is already in the active state, and the sub-cues have been enabled! If you want to make sure that a sub-cue only becomes active after this cue is complete, there is a useful event condition for that:
193 193  
194 -{{code}}&lt;event_cue_completed cue=&quot;parent&quot;/&gt;{{/code}}
240 +{{code language="xml"}}
241 +<event_cue_completed cue="parent"/>
242 +{{/code}}
195 195  
196 196  (% style="color: rgb(0,0,0);text-decoration: none;" %)<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.
197 197  
... ... @@ -199,8 +199,18 @@
199 199  
200 200  (% style="color: rgb(0,0,0);text-decoration: none;" %)Example, which selects one of the three texts randomly:
201 201  
202 -{{code}}&lt;actions&gt; &lt;do_any&gt;   &lt;debug_text text=&quot;'Hello world'&quot;/&gt;   &lt;debug_text text=&quot;'Welcome to the MD'&quot;/&gt;   &lt;debug_text text=&quot;'And now for something completely different'&quot;/&gt; &lt;/do_any&gt;&lt;actions&gt;{{/code}}
250 +{{code language="xml"}}
251 +<actions>
252 + <do_any>
253 + <debug_text text="'Hello world'"/>
254 + <debug_text text="'Welcome to the MD'"/>
255 + <debug_text text="'And now for something completely different'"/>
256 + </do_any>
257 +<actions>
258 +{{/code}}
203 203  
260 +
261 +
204 204  {{note body="<span style=~"color: rgb(0,0,0);text-decoration: none;~">Messages printed with &lt;debug_text&gt; are usually only visible when the ΓÇ£scriptsΓÇ¥ debug filter is enabled, see [[NULL|Script debug output]].</span>"/}}
205 205  
206 206  
... ... @@ -230,17 +230,26 @@
230 230  
231 231  (% style="color: rgb(0,0,0);text-decoration: none;" %)Library cues are written like normal cues, they are also defined in a <cues> node, just with the difference that the XML tag is called library instead of cue:
232 232  
233 -{{code}}&lt;library name=&quot;LibFoo&quot; checktime=&quot;1h&quot; checkinterval=&quot;5s&quot;&gt;  &lt;conditions&gt;  [...]&lt;/library&gt;{{/code}}
291 +{{code language="xml"}}
292 +<library name="LibFoo" checktime="1h" checkinterval="5s">
293 + <conditions>
294 + [...]
295 +</library>
296 +{{/code}}
234 234  
235 235  (% style="color: rgb(0,0,0);text-decoration: none;" %)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.
236 236  
237 237  (% style="color: rgb(0,0,0);text-decoration: none;" %)To use a library, use the attribute ref:
238 238  
239 -{{code}}&lt;cue name=&quot;Foo&quot; ref=&quot;LibFoo&quot;/&gt;{{/code}}
302 +{{code language="xml"}}
303 +<cue name="Foo" ref="LibFoo"/>
304 +{{/code}}
240 240  
241 241  (% style="color: rgb(0,0,0);text-decoration: none;" %)This will create a cue with the name Foo that behaves just like the library cue LibFoo. In this example, LibFoo has to be a library in the same MD script file. To use a library LibFoo from another script, you have to qualify it with the script name, using the (%%)**(% style="color: rgb(0,0,0);text-decoration: none;" %)md(%%)**(% style="color: rgb(0,0,0);text-decoration: none;" %) prefix:
242 242  
243 -{{code}}&lt;cue name=&quot;Foo&quot; ref=&quot;md.ScriptName.LibFoo&quot;/&gt;{{/code}}
308 +{{code language="xml"}}
309 +<cue name="Foo" ref="md.ScriptName.LibFoo"/>
310 +{{/code}}
244 244  
245 245  (% style="color: rgb(0,0,0);text-decoration: none;" %)When the ref attribute is provided, all other attributes (except for name) will be ignored and taken from the library cue instead. ((% style="color: rgb(0,0,0);text-decoration: none;" %)By default a library creates its own namespace, as if namespace="static" were specified. See the section about namespaces.(%%))
246 246  
... ... @@ -248,8 +248,28 @@
248 248  
249 249  (% style="color: rgb(0,0,0);text-decoration: none;" %)In contrast to X3TC, a cue that references a library also has its own name (Foo in the example above), so other cues can access it in expressions by that name. Sub-cues of Foo cannot be accessed by their name though. Within the library itself, expressions can use all names of cues that belong to the library (the <library> and all sub-cues). They will be translated properly when the library is referenced. Examples:
250 250  
251 -{{code}}&lt;cue name=&quot;Foo&quot; ref=&quot;LibFoo&quot;/&gt;&lt;cue name=&quot;Bar&quot; ref=&quot;LibFoo&quot;/&gt;&lt;library name=&quot;LibFoo&quot;&gt;  &lt;actions&gt;    &lt;cancel_cue cue=&quot;this&quot;/&gt;             &lt;!-- Cancels the cue referencing LibFoo --&gt;    &lt;cancel_cue cue=&quot;LibFoo&quot;/&gt;           &lt;!-- Cancels the cue referencing LibFoo --&gt;    &lt;cancel_cue cue=&quot;Foo&quot;/&gt;              &lt;!-- Error, Foo not found in library --&gt;    &lt;cancel_cue cue=&quot;Baz&quot;/&gt;              &lt;!-- Cancels Baz in the referencing cue --&gt;    &lt;cancel_cue cue=&quot;md.Script.Foo&quot;/&gt;    &lt;!-- Cancels Foo --&gt;    &lt;cancel_cue cue=&quot;md.Script.LibFoo&quot;/&gt; &lt;!-- Error, trying to cancel library --&gt;    &lt;cancel_cue cue=&quot;md.Script.Baz&quot;/&gt;    &lt;!-- Error, trying to cancel library sub-cue --&gt;  &lt;/actions&gt;  &lt;cues&gt;    &lt;cue name=&quot;Baz&quot;&gt; [...] &lt;!-- Sub-cue is created in all cues referencing LibFoo --&gt;  &lt;/cues&gt;&lt;/library&gt;{{/code}}
318 +{{code language="xml"}}
319 +<cue name="Foo" ref="LibFoo"/>
320 +<cue name="Bar" ref="LibFoo"/>
252 252  
322 +<library name="LibFoo">
323 + <actions>
324 + <cancel_cue cue="this"/>
325 + <cancel_cue cue="LibFoo"/>
326 + <cancel_cue cue="Foo"/>
327 + <cancel_cue cue="Baz"/>
328 + <cancel_cue cue="md.Script.Foo"/>
329 + <cancel_cue cue="md.Script.LibFoo"/>
330 + <cancel_cue cue="md.Script.Baz"/>
331 + </actions>
332 + <cues>
333 + <cue name="Baz"> [...]
334 + </cues>
335 +</library>
336 +{{/code}}
337 +
338 +
339 +
253 253  {{warning body="These examples are definitely <u>not</u> examples of good scripting style."/}}
254 254  
255 255  
... ... @@ -270,15 +270,38 @@
270 270  
271 271  (% style="color: rgb(0,0,0);text-decoration: none;" %)Parameters are defined like this:
272 272  
273 -{{code}}&lt;library name=&quot;Lib&quot; onfail=&quot;cancel&quot;&gt;  &lt;params&gt;    &lt;param name=&quot;foo&quot;/&gt;    &lt;param name=&quot;bar&quot; default=&quot;42&quot;/&gt;    &lt;param name=&quot;baz&quot; default=&quot;player.age&quot;/&gt;  &lt;/params&gt;  [...]&lt;/library&gt;{{/code}}
360 +{{code language="xml"}}
361 +<library name="Lib" onfail="cancel">
362 + <params>
363 + <param name="foo"/>
364 + <param name="bar" default="42"/>
365 + <param name="baz" default="player.age"/>
366 + </params>
367 + [...]
368 +</library>
369 +{{/code}}
274 274  
275 275  (% style="color: rgb(0,0,0);text-decoration: none;" %)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:
276 276  
277 -{{code}}&lt;cue name=&quot;Foo&quot; ref=&quot;Lib&quot;&gt; &lt;param name=&quot;foo&quot; value=&quot;race.argon&quot;/&gt; &lt;param name=&quot;bar&quot; value=&quot;0&quot;/&gt;&lt;/cue&gt;{{/code}}
373 +{{code language="xml"}}
374 +<cue name="Foo" ref="Lib">
375 + <param name="foo" value="race.argon"/>
376 + <param name="bar" value="0"/>
377 +</cue>
378 +{{/code}}
278 278  
279 279  (% style="color: rgb(0,0,0);text-decoration: none;" %)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.
280 280  
281 -{{code}}&lt;library name=&quot;Lib&quot;&gt;  &lt;params&gt;    &lt;param name=&quot;foo&quot;/&gt;  &lt;/params&gt;  &lt;actions&gt;    &lt;debug_text text=&quot;$foo&quot;/&gt;  &lt;/actions&gt;&lt;/library&gt;{{/code}}
382 +{{code language="xml"}}
383 +<library name="Lib">
384 + <params>
385 + <param name="foo"/>
386 + </params>
387 + <actions>
388 + <debug_text text="$foo"/>
389 + </actions>
390 +</library>
391 +{{/code}}
282 282  
283 283  (% style="color: rgb(0,0,0);text-decoration: none;" %)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.
284 284