...

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:

• MD scripts and cues are identified by their names. So a script can only be refreshed if it has the same script name as before (file name is irrelevant).

• If there are new script files or new cue nodes (i.e. scripts/cues with new names) they are created and added properly. If you remove script files or cue nodes, the corresponding scripts/cues are removed from the game, including instances.

• As a consequence, you CANNOT rename scripts or cues if you want to refresh them. Doing so would remove the old script or cue and add a new one with the new name.

• You CANNOT change a <cue> to a <library> or vice versa.

• You CANNOT add, remove, or change the "ref" attribute of a cue. But it is possible to remove the whole cue. (If all references to a library are removed you can also remove the library itself.)

• You CANNOT change the cue tree structure, i.e. if you move a cue out of its <cues> node, you also have to change its name (see above). Changing the order of cues within the same <cues> node is possible, however, the order of execution is not reliable anyway.

• You CAN change a library and change/add/remove its sub-cues. This automatically updates all cues that use the library.

• You CAN change library parameters (both in libraries and in referencing cues). However, this does not change the variables of a referencing cue if it is already enabled.

• You CAN change conditions without restrictions. You can even change between event and non-event conditions. If a cue has enabled condition checks, they are aborted and restarted (even if there is no change).

• Adding root cues enables their condition checks immediately (if the module attribute allows it).

• Adding sub-cues to active or complete cues enables their condition checks immediately.

• You CAN change/add/remove <actions>, <force>, <delay>, and all attributes without restrictions, except for the "ref" attribute (see above). You can even change the <delay> while the cue is already active and the timer is running.

• Changing instantiate="false" to "true" turns the cue into "waiting" state if it was active or complete before.

• Changing instantiate="true" to "false" removes all instantiated cues and their descendants.

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.

<cue [...] version="42">
  <conditions> [...] </conditions>
  <actions> [...] </actions>
  <patch sinceversion="42">
    [patch actions]
  </patch>
</cue>

The patch actions are only performed if the cue is in a certain state, “complete” by default. Use the state attribute to change this requirement. For more information, see the XML schema documentation of the <patch> element.

A sequence of multiple <patch> elements is possible. They will be performed in order of appearance, checking the sinceversion and state attributes in each case. Patches are also applied to all users of a library and to instances.