Changes for page Mission Director Guide

Last modified by Klaus Meyer on 2025/03/31 16:39

From 31068.1 to 31070.1 From 31191.1 to 32205.1

From version 31070.1

edited by Daniel Turner
on 2023/04/14 17:02

Change comment: There is no comment for this version

To version 31191.1

edited by Daniel Turner
on 2023/04/25 11:20

Change comment: There is no comment for this version

Raw
Rendered

Summary

Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

@@ -1,12 +10,3 @@
--{{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."/}}
--
--
--
--(% style="color: rgb(0,0,0);text-decoration: none;" %)
--
--
  (% 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.
@@ -80,13 +80,26 @@
  (% style="color: rgb(0,0,0);text-decoration: none;" %)The XML root node of an MD file is called ΓÇ£mdscriptΓÇ¥ and looks like this:
--{{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}}
++{{code language="xml"}}
++<?xml version="1.0" encoding="utf-8"?>
++<mdscript name="ScriptName" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="md.xsd">
++{{/code}}
  (% 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.
  (% 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:
--{{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}}
++{{code language="xml"}}
++<?xml version="1.0" encoding="utf-8"?>
++<mdscript name="ScriptName" ...>
++  <cues>
++    <cue name="RootCue1"> [...]
++    </cue>
++    <cue name="RootCue2"> [...]
++    </cue>
++  </cues>
++</mdscript>
++{{/code}}
  (% style="color: rgb(0,0,0);text-decoration: none;" %)┬á
@@ -147,15 +147,35 @@
  (% style="color: rgb(0,0,0);text-decoration: none;" %)Example for an event condition:
--{{code}}&lt;conditions&gt;┬á &lt;event_object_destroyed┬áobject=&quot;$target&quot;/&gt;&lt;/conditions&gt;{{/code}}
++{{code language="xml"}}
++<conditions>
++  <event_object_destroyed object="$target"/>
++</conditions>
++{{/code}}
  (% style="color: rgb(0,0,0);text-decoration: none;" %)Example for an event condition with an additional (non-event) check:
--{{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}}
++{{code language="xml"}}
++<conditions>
++  <event_player_killed_object/>
++  <check_value value="event.param.isclass.turret"/>
++</conditions>
++{{/code}}
  (% style="color: rgb(0,0,0);text-decoration: none;" %)Example for an event condition with two alternative events and a common additional check:
--{{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}}
++{{code language="xml"}}
++<conditions>
++  <check_any>
++    <event_cue_completed cue="Cue1"/>
++    <check_all>
++      <event_player_killed_object/>
++      <check_value value="event.param.isclass.turret"/>
++    </check_all>
++  </check_any>
++  <check_age min="$starttime"/>
++</conditions>
++{{/code}}
  (% style="color: rgb(0,0,0);text-decoration: none;" %)For more information about expressions and event parameters, see below.
@@ -173,11 +173,21 @@
  (% style="color: rgb(0,0,0);text-decoration: none;" %)Check conditions every 5 seconds, but start checking only 1 hour after game start.
--{{code}}&lt;cue┬áname=&quot;Foo&quot;┬áchecktime=&quot;1h&quot;┬ácheckinterval=&quot;5s&quot;&gt;┬á &lt;conditions&gt;┬á [...]&lt;/cue&gt;{{/code}}
++{{code language="xml"}}
++<cue name="Foo" checktime="1h" checkinterval="5s">
++  <conditions>
++  [...]
++</cue>
++{{/code}}
  (% 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.
--{{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}}
++{{code language="xml"}}
++<cue name="Foo" checktime="player.age + 3s" onfail="cancel">
++  <conditions>
++  [...]
++</cue>
++{{/code}}
  (% 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.
@@ -197,11 +197,15 @@
  (% 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>:
--{{code}}&lt;delay┬ámin=&quot;10s&quot;┬ámax=&quot;30s&quot;/&gt;{{/code}}
++{{code language="xml"}}
++<delay min="10s" max="30s"/>
++{{/code}}
  (% 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:
--{{code}}&lt;event_cue_completed┬ácue=&quot;parent&quot;/&gt;{{/code}}
++{{code language="xml"}}
++<event_cue_completed cue="parent"/>
++{{/code}}
  (% 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.
@@ -209,8 +209,18 @@
  (% style="color: rgb(0,0,0);text-decoration: none;" %)Example, which selects one of the three texts randomly:
--{{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}}
++{{code language="xml"}}
++<actions>
++ <do_any>
++   <debug_text text="'Hello world'"/>
++   <debug_text text="'Welcome to the MD'"/>
++   <debug_text text="'And now for something completely different'"/>
++ </do_any>
++<actions>
++{{/code}}
++
++
  {{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>"/}}
@@ -240,17 +240,26 @@
  (% 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:
--{{code}}&lt;library┬áname=&quot;LibFoo&quot;┬áchecktime=&quot;1h&quot;┬ácheckinterval=&quot;5s&quot;&gt;┬á &lt;conditions&gt;┬á [...]&lt;/library&gt;{{/code}}
++{{code language="xml"}}
++<library name="LibFoo" checktime="1h" checkinterval="5s">
++  <conditions>
++  [...]
++</library>
++{{/code}}
  (% 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.
  (% style="color: rgb(0,0,0);text-decoration: none;" %)To use a library, use the attribute ref:
--{{code}}&lt;cue┬áname=&quot;Foo&quot;┬áref=&quot;LibFoo&quot;/&gt;{{/code}}
++{{code language="xml"}}
++<cue name="Foo" ref="LibFoo"/>
++{{/code}}
  (% 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:
--{{code}}&lt;cue┬áname=&quot;Foo&quot;┬áref=&quot;md.ScriptName.LibFoo&quot;/&gt;{{/code}}
++{{code language="xml"}}
++<cue name="Foo" ref="md.ScriptName.LibFoo"/>
++{{/code}}
  (% 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.(%%))
@@ -258,8 +258,28 @@
  (% 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:
--{{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}}
++{{code language="xml"}}
++<cue name="Foo" ref="LibFoo"/>
++<cue name="Bar" ref="LibFoo"/>
++<library name="LibFoo">
++  <actions>
++    <cancel_cue cue="this"/>
++    <cancel_cue cue="LibFoo"/>
++    <cancel_cue cue="Foo"/>
++    <cancel_cue cue="Baz"/>
++    <cancel_cue cue="md.Script.Foo"/>
++    <cancel_cue cue="md.Script.LibFoo"/>
++    <cancel_cue cue="md.Script.Baz"/>
++  </actions>
++  <cues>
++    <cue name="Baz"> [...]
++  </cues>
++</library>
++{{/code}}
++
++
++
  {{warning body="These examples are definitely <u>not</u> examples of good scripting style."/}}
@@ -280,15 +280,38 @@
  (% style="color: rgb(0,0,0);text-decoration: none;" %)Parameters are defined like this:
--{{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}}
++{{code language="xml"}}
++<library name="Lib" onfail="cancel">
++  <params>
++    <param name="foo"/>
++    <param name="bar" default="42"/>
++    <param name="baz" default="player.age"/>
++  </params>
++  [...]
++</library>
++{{/code}}
  (% 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:
--{{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}}
++{{code language="xml"}}
++<cue name="Foo" ref="Lib">
++ <param name="foo" value="race.argon"/>
++ <param name="bar" value="0"/>
++</cue>
++{{/code}}
  (% 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.
--{{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}}
++{{code language="xml"}}
++<library name="Lib">
++  <params>
++    <param name="foo"/>
++  </params>
++  <actions>
++    <debug_text text="$foo"/>
++  </actions>
++</library>
++{{/code}}
  (% 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.

Changes for page Mission Director Guide

Summary

Details

Navigation

Applications