All About Sequences

In this section:

• Sequences
• Sampling Sequences
• Switching Sequences
• Which Sequence is First

---

By default, the steps in a Stepworks spreadsheet are executed from top to bottom, looping back to the top once the bottom-most step is completed. If you want to make use of more complex behavior in your script, like randomization or flow control, then you need to learn how to create sequences.

A sequence is simply a group of steps, and you’ve actually already been using them—in your tutorial story, Stepworks was creating one big sequence behind the scenes that contains all the script’s steps. Honest—here’s the Stepwise XML for that first story to prove it:

<stepwise>
    <title>Sheet1</title>
    <description></description>
    <primarycredits>erikcloyer</primarycredits>
    <secondarycredits></secondarycredits>
    <version>1</version>
    <sequence id="global" repeat="+">
        <group>
            <speak character="alisha">Hey Charles!</speak>
            <nothing character="charles"></nothing>
        </group>
        <group>
            <nothing character="alisha"></nothing>
            <speak character="charles">Hi Alisha!</speak>
        </group>
        <group>
            <speak character="alisha">How are you today?</speak>
            <nothing character="charles"></nothing>
        </group>
        <group>
            <nothing character="alisha"></nothing>
            <speak character="charles">I'm great, thanks.</speak>
        </group>
    </sequence>
    <character id="alisha" firstname="alisha"></character>
    <character id="charles" firstname="charles"></character>  
</stepwise>

Side note: whenever Stepworks loads a story, it logs the Stepwise XML code for the story to the console.

Now, you’ll learn how to create sequences more explicitly, which gives you more control.

To define a sequence, you need to use a command. Commands are special formulas which Stepworks recognizes and executes, instead of treating them like content spoken by a character. You can recognize Stepworks commands in a script because they all begin with a dollar sign “$”.

To define a sequence put this command in its own cell:

$sequence: id:[id], repeat:[number of repeats]

So, for example, $sequence: id:intro, repeat:5 will create a sequence named “intro” that will repeat five times. To repeat a sequence infinitely, use a “+” instead of a number—for example: $sequence: id:intro, repeat:+.

To randomize a sequence, use the keyword “shuffle” instead of “repeat”. So, for example: $sequence: id:intro, shuffle will create a sequence named “intro” that will play its steps randomly. Randomized sequences will exhaust all of the steps they contain before repeating a step.

You can group a sequences into rhythmic patterns using the “grouping” keyword. For example, $sequence: id:intro, grouping:xxxx will assemble steps in the sequence into groups of four, with each step delayed in time by one pulse (see Delays, Timing, and Tempo to learn how to define a pulse). You can use the & character instead of x to indicate that a step should be appended to the previous step, instead of replacing it outright.

You can have as many sequences as you want in a given column—just add a new $sequence command wherever you want a new one to begin.

In general, Stepworks looks for the first empty step to determine where a column’s bottom-most sequence ends. Sometimes that’s not what you want, however, so if you want to explicitly end a sequence, just add an $end command in the cell below its last step.

The power of sequences really comes into focus with sampling. Sampling is a way of saying “for the current step, do whatever sequence X would do next,” where X could be any sequence in the story. For example, maybe you want to write a story consisting of a character describing their favorite foods, where the names of the foods and the verbs for “eat” are randomized, like so:

I love to eat ice cream
I love to consume candy
I love to devour doughnuts

Since each sentence includes two random elements, this would be laborious to accomplish with a single randomized sequence (you would need to include every possible combination in the sequence). With sampling, however, this becomes much easier. First, you’ll need to create the “root” sequence that will be doing the sampling, like so:

Narrator
$sequence: id:root, repeat:+
I love to $sample:verbs $sample:foods

This one step sequence will display the words “I love to “ followed by whatever the next step of the “verbs” sequence is, and whatever the next step of the “foods” sequence is. The ampersands are a special character indicating that the rest of the content in the line should be appended to whatever is already being displayed—this is what prevents each component of the sentence from instantly replacing the prior ones.

Now, let’s add those additional sequences:

Narrator
$sequence: id:root, repeat:+
I love to $sample:verbs $sample:foods
$sequence: id:verbs, shuffle
& eat
& consume
& devour
$sequence: id:foods, shuffle
& ice cream
& candy
& doughnuts

Now, try running this story (see Getting Started if you’re fuzzy on how). Cool! Try adding your own verbs and foods.

You can change the currently playing sequence by using this command:

$setsequence:[id]

So for example, $setsequence:story will make the sequence called “story” the current sequence. Note that changing to a new sequence does not immediately trigger a new step from that sequence, so if all a given step does is switch sequences, nothing will appear to happen for the user. Adding the optional autostart:true parameter causes the new sequence to immediately play its first step, like this:

$setsequence:story, autostart:true

In Stepworks, only one sequence can be playing at a time. If you haven’t defined any sequences yourself, all steps are automatically compiled into a single global sequence with the id “global”, which is automatically triggered when the story loads.

Once you start defining your own sequences, the rule is: the top-most of your sequences in the left-most column will be the one that’s triggered first. The global sequence will not be triggered unless you sample or switch to it deliberately.

Because of this, once you start creating more complex stories, it’s helpful to create a “root” character in the left-most column, with an “init” sequence at its top that does any one-time initialization you need, and which then switches to a second “program” sequence that manages the story as a whole, sampling other sequences as needed. You can add multiple sequences of this type (“programA”, “programB”, etc.) to manage different sections of the story, and switch between them using the $setsequence command.

Here’s the basic pattern:

Root
$sequence: id:init
[initialize stuff]
$setsequence:program
$sequence: id:program, repeat:+
[do the story]