...

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.

...

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.

...

<?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.

...

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.

...

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>

...

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"/>

...

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>

...

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.

Libraries

Libraries are cues which are not created directly but only serve as templates for other cues. This allows for modularisation, so you can re-use library cues in many different missions.

Note: The syntax of libraries is considerably different from the syntax in the MD of X3TC.

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:

<library name="LibFoo" checktime="1h" checkinterval="5s">
  <conditions>
  [...]
</library>

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.

To use a library, use the attribute ref:

<cue name="Foo" ref="LibFoo"/>

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 md prefix:

<cue name="Foo" ref="md.ScriptName.LibFoo"/>

When the ref attribute is provided, all other attributes (except for name) will be ignored and taken from the library cue instead. (By default a library creates its own namespace, as if namespace="static" were specified. See the section about namespaces.)

Also all sub-cues of the library will be created as sub-cues of the cue that uses it. They are defined in the library as <cue>, not as <library>. (Although you can define a library as a sub-cue of another library, the location in the file does not matter, as already stated above.) It is even possible to reference other libraries in sub-cues of a library!

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:

<cue name="Foo" ref="LibFoo"/>
<cue name="Bar" ref="LibFoo"/>

<library name="LibFoo">
  <actions>
    <cancel_cue cue="this"/>             <!-- Cancels the cue referencing LibFoo -->
    <cancel_cue cue="LibFoo"/>           <!-- Cancels the cue referencing LibFoo -->
    <cancel_cue cue="Foo"/>              <!-- Error, Foo not found in library -->
    <cancel_cue cue="Baz"/>              <!-- Cancels Baz in the referencing cue -->
    <cancel_cue cue="md.Script.Foo"/>    <!-- Cancels Foo -->
    <cancel_cue cue="md.Script.LibFoo"/> <!-- Error, trying to cancel library -->
    <cancel_cue cue="md.Script.Baz"/>    <!-- Error, trying to cancel library sub-cue -->
  </actions>
  <cues>
    <cue name="Baz"> [...] <!-- Sub-cue is created in all cues referencing LibFoo -->
  </cues>
</library>

(Note that these examples are definitely not examples of good scripting style.)

So when writing the library, you don’t have to worry about name confusion, just use the names of cues in your library and it will work as expected when the library is used. Names of cues that do not belong to the library will not be available in expressions (see Foo in the example above), however, names of other libraries in the file are available when referencing them in the ref attribute.

Library Parameters

A library can be parametrised, so that it can be adapted to the needs of a missions that uses it. You can define required and/or optional parameters for a library, and it will be validated at load time that the user of the library has provided all required parameters.

Parameters are defined like this:

<library name="Lib" onfail="cancel">
  <params>
    <param name="foo"/>
    <param name="bar" default="42"/>
    <param name="baz" default="player.age"/>
  </params>
  [...]
</library>

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:

<cue name="Foo" ref="Lib">
 <param name="foo" value="race.argon"/>
 <param name="bar" value="0"/>
</cue>

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.

<library name="Lib">
  <params>
    <param name="foo"/>
  </params>
  <actions>
    <debug_text text="$foo"/>
  </actions>
</library>

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.