Skip to Content

Changes for page Mission Director Guide

Last modified by Klaus Meyer on 2025/03/31 16:39
From version 31076.1
edited by Daniel Turner
on 2023/04/14 17:17
Change comment: There is no comment for this version
To version 31068.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..."

Summary

Details

Page properties
Content
... ... @@ -80,26 +80,13 @@
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 language="xml"}}
84 -<?xml version="1.0" encoding="utf-8"?>
85 -<mdscript name="ScriptName" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="md.xsd">
86 -{{/code}}
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}}
87 87  
88 88  (% 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.
89 89  
90 90  (% 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:
91 91  
92 -{{code language="xml"}}
93 -<?xml version="1.0" encoding="utf-8"?>
94 -<mdscript name="ScriptName" ...>
95 - <cues>
96 - <cue name="RootCue1"> [...]
97 - </cue>
98 - <cue name="RootCue2"> [...]
99 - </cue>
100 - </cues>
101 -</mdscript>
102 -{{/code}}
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}}
103 103  
104 104  (% style="color: rgb(0,0,0);text-decoration: none;" %)┬á
105 105  
... ... @@ -131,17 +131,7 @@
131 131  
132 132  (% style="color: rgb(0,0,0);text-decoration: none;" %)This is how a cue node looks like:
133 133  
134 -{{code language="xml"}}
135 -<cue name="CueName">
136 - <conditions> [...]
137 - </conditions>
138 - <delay exact="5s" />
139 - <actions> [...]
140 - </actions>
141 - <cues> [...]
142 - </cues>
143 -</cue>
144 -{{/code}}
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}}
145 145  
146 146  (% 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.
147 147  
... ... @@ -160,35 +160,15 @@
160 160  
161 161  (% style="color: rgb(0,0,0);text-decoration: none;" %)Example for an event condition:
162 162  
163 -{{code language="xml"}}
164 -<conditions>
165 - <event_object_destroyed object="$target"/>
166 -</conditions>
167 -{{/code}}
140 +{{code}}&lt;conditions&gt;  &lt;event_object_destroyed object=&quot;$target&quot;/&gt;&lt;/conditions&gt;{{/code}}
168 168  
169 169  (% style="color: rgb(0,0,0);text-decoration: none;" %)Example for an event condition with an additional (non-event) check:
170 170  
171 -{{code language="xml"}}
172 -<conditions>
173 - <event_player_killed_object/>
174 - <check_value value="event.param.isclass.turret"/>
175 -</conditions>
176 -{{/code}}
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}}
177 177  
178 178  (% style="color: rgb(0,0,0);text-decoration: none;" %)Example for an event condition with two alternative events and a common additional check:
179 179  
180 -{{code language="xml"}}
181 -<conditions>
182 - <check_any>
183 - <event_cue_completed cue="Cue1"/>
184 - <check_all>
185 - <event_player_killed_object/>
186 - <check_value value="event.param.isclass.turret"/>
187 - </check_all>
188 - </check_any>
189 - <check_age min="$starttime"/>
190 -</conditions>
191 -{{/code}}
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}}
192 192  
193 193  (% style="color: rgb(0,0,0);text-decoration: none;" %)For more information about expressions and event parameters, see below.
194 194  
... ... @@ -206,21 +206,11 @@
206 206  
207 207  (% style="color: rgb(0,0,0);text-decoration: none;" %)Check conditions every 5 seconds, but start checking only 1 hour after game start.
208 208  
209 -{{code language="xml"}}
210 -<cue name="Foo" checktime="1h" checkinterval="5s">
211 - <conditions>
212 - [...]
213 -</cue>
214 -{{/code}}
166 +{{code}}&lt;cue name=&quot;Foo&quot; checktime=&quot;1h&quot; checkinterval=&quot;5s&quot;&gt;  &lt;conditions&gt;  [...]&lt;/cue&gt;{{/code}}
215 215  
216 216  (% 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.
217 217  
218 -{{code language="xml"}}
219 -<cue name="Foo" checktime="player.age + 3s" onfail="cancel">
220 - <conditions>
221 - [...]
222 -</cue>
223 -{{/code}}
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}}
224 224  
225 225  (% 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.
226 226  
... ... @@ -240,15 +240,11 @@
240 240  
241 241  (% 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>:
242 242  
243 -{{code language="xml"}}
244 -<delay min="10s" max="30s"/>
245 -{{/code}}
190 +{{code}}&lt;delay min=&quot;10s&quot; max=&quot;30s&quot;/&gt;{{/code}}
246 246  
247 247  (% 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:
248 248  
249 -{{code language="xml"}}
250 -<event_cue_completed cue="parent"/>
251 -{{/code}}
194 +{{code}}&lt;event_cue_completed cue=&quot;parent&quot;/&gt;{{/code}}
252 252  
253 253  (% 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.
254 254  
... ... @@ -256,18 +256,8 @@
256 256  
257 257  (% style="color: rgb(0,0,0);text-decoration: none;" %)Example, which selects one of the three texts randomly:
258 258  
259 -{{code language="xml"}}
260 -<actions>
261 - <do_any>
262 - <debug_text text="'Hello world'"/>
263 - <debug_text text="'Welcome to the MD'"/>
264 - <debug_text text="'And now for something completely different'"/>
265 - </do_any>
266 -<actions>
267 -{{/code}}
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}}
268 268  
269 -
270 -
271 271  {{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>"/}}
272 272  
273 273  
... ... @@ -297,26 +297,17 @@
297 297  
298 298  (% 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:
299 299  
300 -{{code language="xml"}}
301 -<library name="LibFoo" checktime="1h" checkinterval="5s">
302 - <conditions>
303 - [...]
304 -</library>
305 -{{/code}}
233 +{{code}}&lt;library name=&quot;LibFoo&quot; checktime=&quot;1h&quot; checkinterval=&quot;5s&quot;&gt;  &lt;conditions&gt;  [...]&lt;/library&gt;{{/code}}
306 306  
307 307  (% 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.
308 308  
309 309  (% style="color: rgb(0,0,0);text-decoration: none;" %)To use a library, use the attribute ref:
310 310  
311 -{{code language="xml"}}
312 -<cue name="Foo" ref="LibFoo"/>
313 -{{/code}}
239 +{{code}}&lt;cue name=&quot;Foo&quot; ref=&quot;LibFoo&quot;/&gt;{{/code}}
314 314  
315 315  (% 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:
316 316  
317 -{{code language="xml"}}
318 -<cue name="Foo" ref="md.ScriptName.LibFoo"/>
319 -{{/code}}
243 +{{code}}&lt;cue name=&quot;Foo&quot; ref=&quot;md.ScriptName.LibFoo&quot;/&gt;{{/code}}
320 320  
321 321  (% 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.(%%))
322 322  
... ... @@ -324,28 +324,8 @@
324 324  
325 325  (% 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:
326 326  
327 -{{code language="xml"}}
328 -<cue name="Foo" ref="LibFoo"/>
329 -<cue name="Bar" ref="LibFoo"/>
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}}
330 330  
331 -<library name="LibFoo">
332 - <actions>
333 - <cancel_cue cue="this"/>
334 - <cancel_cue cue="LibFoo"/>
335 - <cancel_cue cue="Foo"/>
336 - <cancel_cue cue="Baz"/>
337 - <cancel_cue cue="md.Script.Foo"/>
338 - <cancel_cue cue="md.Script.LibFoo"/>
339 - <cancel_cue cue="md.Script.Baz"/>
340 - </actions>
341 - <cues>
342 - <cue name="Baz"> [...]
343 - </cues>
344 -</library>
345 -{{/code}}
346 -
347 -
348 -
349 349  {{warning body="These examples are definitely <u>not</u> examples of good scripting style."/}}
350 350  
351 351  
... ... @@ -366,38 +366,15 @@
366 366  
367 367  (% style="color: rgb(0,0,0);text-decoration: none;" %)Parameters are defined like this:
368 368  
369 -{{code language="xml"}}
370 -<library name="Lib" onfail="cancel">
371 - <params>
372 - <param name="foo"/>
373 - <param name="bar" default="42"/>
374 - <param name="baz" default="player.age"/>
375 - </params>
376 - [...]
377 -</library>
378 -{{/code}}
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}}
379 379  
380 380  (% 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:
381 381  
382 -{{code language="xml"}}
383 -<cue name="Foo" ref="Lib">
384 - <param name="foo" value="race.argon"/>
385 - <param name="bar" value="0"/>
386 -</cue>
387 -{{/code}}
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}}
388 388  
389 389  (% 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.
390 390  
391 -{{code language="xml"}}
392 -<library name="Lib">
393 - <params>
394 - <param name="foo"/>
395 - </params>
396 - <actions>
397 - <debug_text text="$foo"/>
398 - </actions>
399 -</library>
400 -{{/code}}
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}}
401 401  
402 402  (% 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.
403 403