...

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.

...

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>

...

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

...

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>

...

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>

...