Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: XR vs X4 compatibility, better debug output documentation

...

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 Mission Director and X4 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++).

The general MD scripting system is the same in XR and X4, so this guide applies to both games. However, each game has its own set of supported script features (i.e. actions, conditions and properties), so in general scripts from different games are not compatible.


Table of Contents

Table of Contents
excludeTable of Contents

...

Note

Even if your script is free of XSD errors, that does not mean that the script syntax is correct. For example, there are XML elements that require at least one of multiple attributes, but this requirement cannot be reflected in a schema (apart from documentation text). Please notice the XSD documentation of the elements and attributes, e.g. displayed via tooltips in Visual Studio / Visual Web Developer. Please also note additional requirements for MD cue attributes in this guide (see Conditions).

To check for errors, please pay attention to in-game error messages that are produced while your script is imported, and run-time errors while the script runs. The XSD files can help you a lot, but you should not rely on the absence of XSD errors.

Anchor
debugoutput
debugoutput
Script debug output

The game can print error messages and, when enabled, also general messages. Error messages can originate from the scripting system, but also from other game sub-systems. They can be viewed in the in-game DebugLog.

To collect all messages in a file, start the game with the following parameters on the command line:

-logfile debuglog.txt

All messages, including enabled non-error messages, will be written into the log file. You can find it in your personal folder, where your save folder is located. To enable scripting-specific debug messages, add the following to the command line:

-debug scripts

Other debug filters other than "scripts" can be enabled by repeating the -debug command for each filter name, but that is rarely needed for scripting.

The script action <debug_text> can be used to print debug messages from within a script.


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.

...

Note

Reminder: When using an XSD-capable editor, it's a great help, but you cannot rely on it that alone to verify correctness. Please also check the documentation and look for errors in the game debug output. Concretely, the schema cannot tell whether the above cue attributes are used correctly.

...

Note

Messages printed with <debug_text> are usually only visible when the “scripts” debug filter is enabled. Launch the game with parameters like this:

-logfile debuglog.txt -debug scripts

Script errors and <debug_text> messages with filter="error" can also be viewed in the in-game DebugLog, see Script debug output.

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.

...