4. Sequences: interruptible and atomic functions

Interruptible vs Atomic

The core functions described in the previous section can be atomic (i.e. their execution is immediate and indivisible) or interruptible (i.e. their execution is asynchronous and can require some time to be completed). You can distinguish between the two types of function by the presence of the callback parameter in the signature.

When you want to execute two or more functions in sequence, you must consider asynchronicity: if you want to execute a function g only after the interruptible function f has been executed completely, you must pass g as a callback function to f.

This might lead to multiple levels of function nesting while you write your scripts. For this reason, there is a method available that can help you write proper sequences in a more readable way.

Sequence

Sequence(Array body): each element of the body array must be an Object as the following:

_{ f : "function_name", params: [ param_1, param_2, ..., param_n ] }

Supposing you want the character identified by the ID "Guybrush_Threepwood" to say two lines, one after another, you may do something like:

Sequence([
   { f : "sayLine", params : [ "Guybrush_Threepwood", "My name's Guybrush Threepwood..." ] },
   { f : "sayLine", params : [ "Guybrush_Threepwood", "...and I want to be a pirate!" ] }
]);

Of course you may also want to go for classic nested callbacks:

sayLine("Guybrush_Threepwood", "My name's Guybrush Threepwood...", null, function()
    {
        sayLine("Guybrush_Threepwood", "...and I want to be a pirate!");
    });

In the next section, you will also see that the Sequence method is important for Dialogs. In fact, you won't need to manually close a dialog or to change a dialog branch if you call for Sequence in dialog mode.