The Mission Director (MD) is a subsystem of the game and interprets mission scripts, which are written in an XML-based language. The X Rebirth Mission Director is based on the MD in X3: Terran Conflict, with some major changes based on feedback from MD users.
An introduction to the original MD can be found in the Egosoft forums. There is also a PDF guide for the X3 Mission Director, which is partially used as a template for this document.
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++).
MD scripts
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.
MD files are XML files located in the game folder md. 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.
To edit MD scripts, an XML editing tool is needed. Microsoft Visual Studio (if available) or Microsoft Visual Web Developer (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.
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.
MD script structure
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.
The XML root node of an MD file is called “mdscript” and looks like this:
<?xml version="1.0" encoding="utf-8"?>
<mdscript name="ScriptName" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="md.xsd">
“ScriptName” is the name used for this script regardless of the file name. It has to start with an upper case letter and must be unique 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.
The only allowed sub-node of <mdscript> is <cues>, which can only contain <cue> sub-nodes:
<?xml version="1.0" encoding="utf-8"?>
<mdscript name="ScriptName" ...>
<cues>
<cue name="RootCue1"> [...]
</cue>
<cue name="RootCue2"> [...]
</cue>
</cues>
</mdscript>
Cues
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.
A cue can have the following states:
Disabled: The parent cue has not become active yet, so this cue is basically non-existing.
Waiting: Either this is a root cue, or the parent has become active. The cue is checking its conditions and will become active when they are met.
Active: The cue is about to perform the actions. Child cues have entered the waiting state. Note: There can be a delay between the activation and performing the actions if the <delay> tag is used!
Complete: The cue has finished performing its actions.
Cancelled: The cue has been cancelled. This state cannot normally be reached but only if a cue actively cancels itself or another cue. No condition checks or actions are performed in this cue or any sub-(sub-)cue.
This is how a cue node looks like:
<cue name="CueName">
<conditions> [...]
</conditions>
<delay exact="5s" />
<actions> [...]
</actions>
<cues> [...]
</cues>
</cue>
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.
Conditions
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.
Non-event conditions are checked in regular intervals. They may be based on simple values or ranges, such as a particular in-game time having been reached or the player having a certain amount of money. They may also be based on more complex player information, such as what ships they own, whether the player is in a particular area or near a particular object.
Event conditions are triggered when the corresponding event happens, such as the event that a particular object has been targeted, attacked or destroyed. All event nodes have the prefix “event_” so you can easily determine a condition type. Non-event conditions can be used in combination with an event, so they will be checked whenever the event happens. If a condition uses an event, it must be in the first sub-node of the <conditions> node. It is even possible to define multiple alternative events that should activate the cue. The first sub-node should be <check_any> in this case, so only one of its sub-conditions has to be met.
Example for an event condition:
<conditions>
<event_object_destroyed object="$target"/>
</conditions>
Example for an event condition with an additional (non-event) check:
<conditions>
<event_player_killed_object/>
<check_value value="event.param.isclass.turret"/>
</conditions>
Example for an event condition with two alternative events and a common additional check:
<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>
For more information about expressions and event parameters, see below.
<check_all> and <check_any> can be used with non-event conditions as well, but if <check_any> is the first node of an event condition, all its sub-nodes have to define events. In case of <check_all>, only its first node must be an event (or yet another <check_any>), to make sure that exactly one event is required to activate the cue.
If a cue has a <conditions> node without any event, it must have one of the attributes onfail or checkinterval. For onfail, you can use the values “cancel” or “complete”. If the attribute is present, the condition check will happen only once and the cue will be activated on success, or completed/cancelled on failure (without performing the actions). With checkinterval, you can specify a constant time interval between condition checks. The conditions will be checked regularly forever until they are met, unless the cue’s state is changed explicitly by an external event.
Additionally, you can use the attribute checktime to set the time of the first condition check (also possible in combination with onfail). The checktime can be an expression with variables and is evaluated when the cue is enabled (when the condition checks would normally start, i.e. at game start for root cues, or after the parent cue becomes active).
Examples:
Check conditions every 5 seconds, but start checking only 1 hour after game start.
<cue name="Foo" checktime="1h" checkinterval="5s">
<conditions>
[...]
</cue>
Check conditions 3 seconds after the cue is enabled, and cancel the cue in case of failure.
<cue name="Foo" checktime="player.age + 3s" onfail="cancel">
<conditions>
[...]
</cue>
Actions
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>:
<delay min="10s" max="30s"/>
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:
<event_cue_completed cue="parent"/>
<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.
Note that the MD script language is not designed as a programming language. The actions are performed in sequence, although they can be nested to form more complex structures. Loops and conditionals exist to some extent, but not necessarily in the sense that a programmer might expect. Analogously to <check_all> and <check_any>, you can use <do_all> to perform all the contained sub-node actions, and <do_any> to perform only one of them. <do_all> is particularly useful when nested in a <do_any>.
Example, which selects one of the three texts randomly:
<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>
(Side note: Messages printed with <debug_text> are usually only visible when the “scripts” debug filter is enabled.)
Each child action in a <do_any> node can have a weight attribute, which can be used to control the random selection of an action node. The default weight of a child node is 1.
Also available is <do_if>, which completes the enclosed action(s) only if one provided value is non-null or matches another. Directly after a <do_if> node, you can add one or more <do_elseif> nodes to perform additional checks only in case the previous conditions were not met. The node <do_else> can be used directly after a <do_if> or a <do_elseif>. It is executed only if none of the conditions are met.
<do_while> also exists, but should be used carefully, since it is the only action that could cause an infinite loop, which freezes the game without any chance of recovery.
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.