...

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.

...

Common attribute groups

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

Value comparisons

There are many conditions and conditional actions that require a value comparison, for example the condition <check_value>:

<check_value value="$ware == ware.silicon and $amount != 0"/>

In the value attribute you specify a boolean expression, and if it is true (that is, not equal to zero), the condition is met. This is a special case: This condition and all other nodes that support a value comparison allows you to specify an upper limit, a lower limit, a number range, or a list of allowed values. Examples:

<check_value value="FooCue.state" exact="cuestate.complete"/>
<check_value value="$foo.count" min="5"/>
<check_value value="$foo" max="player.age + 1min"/>
<check_value value="player.money" min="300Cr" max="600Cr"/>
<check_value value="$method" list="[killmethod.hitbymissile, killmethod.collected]"/>
<check_value value="$attention" min="attention.visible"/>

Random ranges

If an action requires a value, e.g. when you set a variable to a value, you can have some randomisation. To specify an exact value, e.g. in <set_value>, you can write this:

<set_value name="$race" exact="race.teladi"/>

To select a random element from a list, this syntax can be used:

<set_value name="$prime" list="[2, 3, 5, 7, 11]"/>

To get a random number within a given range, you can use min/max:

<set_value name="$foo" min="-20" max="20"/>
<set_value name="$timeout" max="20s"/>

min and max have to be compatible number types. Enumeration types are not allowed, not even level and attention. The min attribute is optional and defaults to 0 (of the number type used in max).

You can select one of 5 different probability distribution profiles for the random range, “flat” being the default (all values in the range are equally likely). If you select another profile, e.g. “increasing” to make higher numbers more likely, you also have to specify a scale value (integer) that is greater or equal to 2. Higher scale values result in higher peaks in the distribution profiles (probable values become even more probable).

<set_value name="$foo" min="-20" max="20" profile="profile.increasing" scale="4"/>

Variables and namespaces

As you have seen above, you can easily access variables by writing their name (including $ prefix) in an expression. Namespaces define in which cue the variables are actually stored (and from which cue they are read).

Creating and removing variables

You can create variables with certain actions and conditions, such as the <set_value> action:

 <set_value name="$foo" exact="$bar + 1" />

<set_value> also exists as a “condition”, which can be useful if you want to pass information about the conditions to the actions, that would otherwise be lost - like in a complex <check_any> event condition, where you want to create a variable only if you are in a certain check branch. (Other pseudo-conditions are <remove_value> and <debug_text>.)

The default operation of <set_value> is “set”, but there are more: “add”, “subtract”, and “insert”. add and subtract change the value of an existing variable, which is created as 0 if it didn’t exist before. If neither min, max nor exact attribute is provided, an exact value of 1 is assumed.

<set_value name="$foo" operation="add" />

The trick is that <set_value> not only works on variables, but also on list elements:

<set_value name="$list.{1}" exact="42" />

The operation insert is special, and it only works on lists. It inserts the value at the specified position (note that the position beyond the last element is also valid here):

<set_value name="$list.{1}" exact="42" operation="insert" />

This shifts the positions of all following elements up by one. If min/max/exact are missing, the default value is null for insertions, not 1 like in other cases.

Appending is easier than that. The following actions are equivalent:

<set_value name="$list.{$list.count + 1}" exact="42" operation="insert" />
<append_to_list name="$list" exact="42" />

Inserting at a position below 1 or above $list.count + 1 is not possible.

To remove variables or list entries, use <remove_value>:

<remove_value name="$foo" />
<remove_value name="$list.{1}" />

Removing an entry from a list shifts all following elements down by one. If you want to clear an entry without removing it from the list, just use <set_value> instead.

Accessing remote variables

You can also read and write variables in other cues by using the variable name as property key:

<set_value name="OtherCue.$foo" min="0.0" max="1.0" />
<set_value name="md.OtherScript.YetAnotherCue.$bar" exact="OtherCue.$foo" />

Instead of referencing a cue by name, you could also reference it via a keyword or another variable:

<set_value name="static.$counter" operation="add" />
<set_value name="parent.$foo" exact="42" />
<set_value name="this.$bar" exact="parent" />
<set_value name="$baz" exact="this.$bar.$foo" />

Namespaces

In the examples above, a variable was written to and read from the “this” cue. This can be necessary: the expression “$foo” may be different from the expression “this.$foo”. The reason for that are namespaces.

Consider this case:

<cue name="Root">
  <actions>
    <set_value name="$foo" />
  </actions>
  <cues>
    <cue name="SubCue"> [...]
    </cue>
  </cues>
</cue>

When the root cue creates $foo, the variable is stored in the Root cue directly. But SubCue and its descendants will also need access to $foo. Of course they could write “parent.$foo” or “Root.$foo”, but since it’s very common to have a single location for most variables in the whole cue tree, the easy solution is to write just “$foo” - because variable names are looked up in the namespace cue, which is the root by default. Also newly created variables end up in the namespace, and not in “this” cue.

You can also use the keyword “namespace” in expressions to get the namespace cue.

Defining a cue’s namespace

When writing a cue, you can specify what the namespace of the cue should be, by adding the namespace attribute. The following values are possible:

• this: Use “this” cue as namespace, even for instances: $foo == this.$foo

• static: Same as “this”, but when instantiated, use the static cue: $foo == static.$foo

• default: The namespace is inherited from the parent cue. The default for root cues and for libraries is the same as “static”.