...

The attributes onfail, checkinterval, checktime are not allowed for cues with event conditions.

...

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

...

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!

...

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.

Notes:

• It is not possible to directly call a cue which is 'inside' the library from 'outside' of the library, but it is possible to signal the library ref itself (possibly with parameters) and have a sub-cue inside the library listen to the signal on the library ref (possibly checking the parameters).
• You can access variables in the library root but generally this should be avoided in favor of parameterizing the library!
  • there are some cases where you do want to access these variables directly, for example for maintaining savegame compatibility when patching.

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.

...

Here is the complete list of numeric data types and corresponding unit suffixes:

Anchor
operators operators

Operators

You can build expressions by combining sub-expressions with operators. For Boolean operations, expressions are considered “false” if they are equal to zero, “true” otherwise. The following operators, delimiters, and constants are supported:

Operator precedence rules

...

Lists are stored in variables as references, so multiple variables can refer to the same shared list: If you change a shared list through a variable, e.g. by changing the value of an element, you change it as well for all other variables. However, the operators == and != can also be used on two distinct lists to compare their elements.

...

Anchor
tables tables

Tables

Tables are associative arrays - they are like lists, but you can assign values to (almost) arbitrary keys, not just to index numbers. A table is constructed within an expression using the table[] syntax. See the section about value properties for how to access the contents of a table. Creating and removing entries works similarly to lists, but instead of inserting, you simply assign a value to a table key. If the key does not exist yet, it will be created.

...

• $table.keys.list: Yields a list of all keys in the table (reliably sorted by key if all keys are numeric)
  
• $table.keys.sorted: Yields a sorted list of all keys in the table, sorted by their associated values (which requires that all keys values are numeric)
• $table.keys.random: A randomly chosen key (which requires that the table is non-empty)

...

As you can see, an error is already prevented if any link in the property chain does not exist. But use the @ prefix with care, since error messages are really helpful for detecting problems in your scripts. The @ prefix only suppresses property-related error messages and does not change any in-game behaviour. 

Static lookups

There are a few data types which are basically enumerations: They only consist of a set of named values, e.g. the “class” data type, which is used for the component classes that exist in the game. For all these static enumeration classes there is a lookup value of the same name, from which you can get the named values as properties by their name. So for the type “class”, there is a value “class” that can be used to access the classes.

Here are a few enumeration classes and corresponding example lookup values:

...

You can access many player-related game properties via the keyword “player”, for example:

• player.name: The player’s name

• player.age: The passed in-game time since game start

• player.money: The money in the player’s account

• player.ship: The ship the player is currently on (not necessarily the player's ship), or null if the player is on a station
  

• player.primaryship (X Rebirth only): The player's own ship (but the player is not necessarily on board)
• player.occupiedship (X4 only): The ship that the player is currently piloting, or null if the player is not piloting
• player.entity: The actual player object
  

• player.zone, player.sector, player.cluster, player.galaxy: Location of the player entity

• player.copilot (X Rebirth only): The co-pilot NPC
  

The game consists of objects of different classes (zones, ships, stations, NPCs). They have the common datatype "component", however, they have different properties, e.g. NPCs have the property "race", but ships don't.

...

When formatting the money value, any specifier (such as '%s') in the format string is replaced by the money value, so usually the format string only consists of this one specifier. The following modifiers can be used between '%' and the specifier character, to enable formatting options:

By default, these options are disabled.

...

• (151s).formatted.{'%T'} ⟹ '00:02:31'
• (151s).formatted.default ⟹ '00:02:31' (same as {'%T'})
• (151s).formatted.{'%.3T'} ⟹ '00:02:31.000'
• (151s).formatted.{'%h:%M'} ⟹ '0:02'

...

Complete property documentation

...

documentation

To access the script property documentation that is included in the game, you can extract the required files from the game's catalog files using the X Catalog Tool. Extract the HTML file scriptproperties.html in the game's root folder, and all files in the "libraries" sub-folder. For resolving text references in the browser automatically, also extract 0001-L044.xml in the "t" sub-folder.

The raw documentation data is located in libraries/scriptproperties.xml, but it is recommended to open scriptproperties.html in a browser.

This provides you with a complete list of all supported “base keywords” and properties. To filter in this list, you can enter an expression in the text field:

...

...

MD refreshing and patching

When a saved game is loaded, the saved MD state is restored, but also all MD files are reloaded and changes in them are applied to the MD state. This is called “refresh”. It is also possible to refresh the MD at run-time using the command “refreshmd” on the in-game command line. This is a convenient way to update MD scripts while the game is already running. 

Details and restrictions

Here are some noteworthy facts about refreshing scripts and cues, and the restrictions:

...

Patching

Cues can have <patch> elements with actions that will be performed when an old savegame is loaded. To control which savegames should be affected, you can add a version attribute to the <cue> node and a sinceversion attribute in the patch. When a cue is loaded from a savegame that has an older version than sinceversion, the <patch> actions will be performed immediately after loading.

...

...

Common attribute groups

There are many commonly used actions and conditions which share groups of attributes. The most important ones are explained here.

Anchor
valuecomparisons valuecomparisons

Value comparisons

...

...

Anchor
randomranges randomranges

Random ranges

...