...
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++).
Table of Contents
Table of Contents exclude Table of Contents
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.
...
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:
...
| Note |
|---|
There can be a delay between the activation and performing the actions if the <delay> tag is used. In this case, sub-cues will be enter the waiting state before the parent's actions are performed. |
This is how a cue node looks like:
<cue name="CueName">
<conditions> [...]
</conditions>
<delay exact="5s" />
<actions> [...]
</actions>
<cues> [...]
</cues>
</cue>
...
<actions>(Side
<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>
| 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.
...
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:
...
<cue name="Foo" ref="LibFoo"/>(Note that these
<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>
| Warning |
|---|
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.
...
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.
Instantiation
One of the possible cue attributes is instantiate. If you set it to true, this changes what happens when a cue's conditions are met. Normally, if a cue is not instantiated, the cue's actions are run (taking a delay node into account) and the cue is marked as completed. But with instantiate, a copy of the cue (and all its sub-cues) is made when the conditions are met, and it is this copy in which the actions are performed and it is the copy whose status is set to complete when they are finished - this means that the original cue (the so-called static cue) remains in the waiting state, and if the conditions are met again then the whole thing happens all over again.
An instantiating cue should only be used with conditions that are only going to be met once (or a fairly limited number of times), or with conditions that include an event condition. Instantiation should not be used in a cue which, say, just depends on the game time being greater than a specific value as this will result in a copy of the cue being made after each check interval, which could increase memory usage a lot. The most common use of an instantiated cue is in responding to events such as the player ship changing sector, to react every time that event happens.
Instances that are created via instantiate are called instantiated cues. But sub-cues of instances are also instances (sub-instances) - they are created when they enter the waiting state. An instance is removed again (thereby freeing its memory) when it is complete or cancelled, and when all its instance sub-cues have been removed before. The simplest case is an instantiating cue with no sub-cues: The instance is created, the actions are performed, and the instance is removed immediately on completion. A pitfall could be an instance with a sub-cue that is forever in the waiting state (e.g. waiting for an event from an already destroyed object). It can never be removed, so you should clean up such a cue yourself, e.g. by cancelling it explicitly.
Cleaning up instances explicitly
Cancelling a cue with <cancel_cue> also cancels all its sub-cues, and cancelling a static cue stops it from instantiating more cues - but it does not cancel its instances. Resetting a cue with <reset_cue> resets both sub-cues and instantiated cues, but has the (desired) side effect that condition checks will start again if the parent cue’s state allows it. Even a sub-instance that has been reset can return to the waiting state. Resetting an instantiated cue will stop it forever, because it is not supposed to be in the waiting state (only its static cue is). Resetting will also induce the clean-up reliably, but keep in mind that this is not the case for instance sub-cues.
| Info |
|---|
<cancel_cue> and <reset_cue> only take effect after all remaining actions of the current cue are performed. So you can even safely cancel the cue that you are currently in (keyword “this”) or any ancestor cue, and still perform more actions afterwards. |
Access to instances
| Note |
|---|
This sub-section requires basic knowledge of script expressions, see the section below. |
In case of instances with sub-instances, you will often want to access a related instance from the current one. Like in the non-instance case, you can simply write the cue name in an expression to reference that cue. However, you should be aware of the pitfalls that are accompanied by this.
When you use a cue name from the same script in an expression, it will always be resolved to some cue - usually a static cue, even if it is still in the disabled state, but it can also be an instance, if it is “related” to the current one.
Related means that this cue and the referenced cue have a common ancestor instance, and the referenced cue is a direct (non-instantiated) descendant of that common ancestor.
Example chart:
This chart represents a script of 5 cues: Foo, Bar, SubBar, Baz and SubBaz. Continuous arrows denote parent-child relationship. Foo and Baz are instantiating cues (highlighted with red border). The static cues always exist, although static children of instantiating cues can never become active. Instances only exist as long as they are needed.
Example situations:
In the static tree: Cue names in expressions are always resolved to the static cues.
In the inst-2 tree: “SubBar” in an expression will be resolved to SubBar (inst 2).
In the inst-1 tree: “SubBar” in an expression will be resolved to SubBar (static) (!) because the SubBar child of Bar (inst 1) does not exist yet, or not any more.
In the inst-2a tree: “SubBaz” in an expression will be resolved to SubBaz (inst 2a)
In the inst-2a tree: “Bar” in an expression will be resolved to Bar (inst 2) because Foo (inst 2) is a common ancestor.
In the inst-2 tree: “SubBaz” in an expression will be resolved to SubBaz (static) (!) because SubBaz (inst 2a) is not a direct descendant of the common ancestor Foo (inst 2), instead Baz (inst 2a) has been instantiated.
In expressions, you can use the cue property static to access the static cue that instantiated a cue. This does not work for sub-cues of other cues, and the result is not necessarily a real static cue! In the example above, it would only work for cues with a dotted arrow pointing at them, and is resolved to the source of the arrow. In other cases the result is null.
To get the real static cue that always exists and serves as template for instances, use the property staticbase. This works for all cues, even for the static cues themselves.
In general, to access ancestors of the current cue, you can also use the keyword parent, also recursively as properties of other cues (such as parent.parent.parent).
You can store cue references in variables. But when storing an instance cue in a variable, and later accessing that variable, be aware that the instance may not exist any more. Use the property exists to check if an instance is still alive. (In contrast, non-instance cues always exist, but may be in the disabled or cancelled state.)
Pitfalls
Some additional common pitfalls with respect to instantiation are listed here. There may be more.
Conditions with results: If the instantiating cue has conditions with results, those results are stored in variables - but in the variables of the static cue, not of the instance! So in the <actions> you have to access the variables via the static keyword:
<debug_text text="static.$foo"/>
It may even be necessary to copy the variables over to the instance because the static variables can be overwritten by the next condition check:<set_value name="$foo" exact="static.$foo"/>Resetting completed/cancelled instances: As explained above, sub-instances are only created when needed (when going to the waiting state) and are destroyed when they are not needed any more (when they are completed or cancelled, including all sub-cues). There are cases in which you want to access cues that don’t exist any more - it simply doesn’t work. In some cases you are safe: You can be sure that all your ancestors exist, and instantiating cues won’t be removed until they are cancelled. In some other cases you simply don’t know and have to check if the instance is already (or still) there.
Lifetime of instances: Do not make assumptions about when an instance is removed! Just looking at it in the Debug Manager keeps it alive for the time being. So, sometimes you could still have a completed instance that wouldn’t exist under other circumstances.