-
Notifications
You must be signed in to change notification settings - Fork 1
Stepwise XML Reference
Stepwise content is delivered in the Stepwise XML format.
<stepwise> is the root element of a Stepwise XML document. Basic metadata about the content is defined using the <title>, <description>, <primarycredits>, <secondarycredits>, and <version> elements.
<stepwise>
<title>My Story</title>
<description>A wonderful tale.</description>
<primarycredits>by My Self</primarycredits>
<secondarycredits>with You Too</secondarycredits>
<version>1.0</version>
</stepwise> The optional <pulse> element sets the meter of the story, which is only relevant for stories that include delayed steps (steps which play automatically in response to user input, but after a predefined delay).
The beatsperminute attribute sets the overall tempo, while the pulsesperbeat attribute determines the unit duration to be used for delayed steps. For example, if beatsperminute is set to 120, and pulsesperbeat is set to 4, then a step with a delay of 1 will be played 60 / 120 / 4 = .125 seconds after the user's input.
The swing attribute sets a multiplier value that is applied to any delay.
<pulse beatsperminute="120" pulsesperbeat="4" swing=".8"/>Attributed actions in a Stepwise story must be linked to the characters that perform them. Each character is declared using a <character> element, and must have a unique id attribute. The contents of the firstname and lastname attributes will be concatenated when the name of the character is displayed (for example, when the useCharacterNames option is set to true in an Effect).
<character id="johnCarpenter" firstname="John" lastname="Carpenter"/> To prevent a character's actions from being displayed visually, set its hidden attribute to true. This might be desirable in the case of a character which is serving as a musical instrument—if that character's speech acts are visible, note names might literally be displayed on the screen.
<character id="piano" firstname="Piano" hidden="true"/>The <setlocation> action requires a reference to a predefined location. Locations are declared using the <location> element, and must have a unique id attribute. The text of the element comprises the name of the location as it will be displayed to users. Use the optional lat and lon attributes to geolocate the location.
<location id="amsterdam" lat="52.3702" lon="4.8952">Amsterdam</location>Sequences are lists of steps, and every Stepwise story must have at least one. The sequence which occurs first in a Stepwise XML document will always be the first one played. Sequences are declared using the <sequence> element, and must have a unique id attribute.
<sequence id="introduction">
... steps go here ...
</sequence>When a sequence is active, each user input will cause the sequence to return each of its steps in succession, until all steps are exhausted. You can use the repeat attribute to determine the number of times a sequence will repeat its steps:
<sequence id="introduction" repeat="5">
... this sequence of steps will be repeated five times ...
</sequence>Or, use a value of + to signify that the sequence should repeat forever.
<sequence id="introduction" repeat="+">
... this sequence of steps will be repeated infinitely ...
</sequence>To cause a sequence to deliver its steps in random order (non-repeating until all steps have been exhausted), use the shuffle attribute:
<sequence id="introduction" shuffle="true">
... steps in this sequence will be triggered in random order forever ...
</sequence>A step is the basic unit of a Stepwise story. Each of the commands listed below can be used as a step within a Stepwise sequence.
A speech act which doesn't need to be attributed to a character. Can be used for actual narration or in simple stories in which no characters need be defined.
<narrate>Hello world.</narrate>Learn about setting the tone of speech acts.
An empty step.
<nothing/>Resets the sequence with the given id back to its initial state.
<reset>denouement</reset>Sets the background color for a story. This is a generic visual setting that can be interpreted in different ways by different clients; it is intended to allow story authors to have a general visual impact on the clients in which their story is played. It's up to the client to determine how to support specific color values, but matching the CSS spec is recommended.
<setbackcolor>#303a5b</setbackcolor>Sets the date and time at which the story is currently taking place. It's up to the client to determine how to support specific date values, but matching the string input capabilities of the JavaScript date object is recommended (this is what the Stepwise jQuery plugin uses).
<setdate>5/17/90</setdate>
<setdate>October 13, 2014 11:13:00</setdate>Sets the foreground color for a story. This is a generic visual setting that can be interpreted in different ways by different clients; it is intended to allow story authors to have a general visual impact on the clients in which their story is played. It's up to the client to determine how to support specific color values, but matching the CSS spec is recommended.
<setforecolor>#d0e4f2</setforecolor>Sets the location where the story is currently taking place, referencing the id of a previously declared location.
<setlocation>amsterdam</setlocation>Sets a mid-range color for a story. This is a generic visual setting that can be interpreted in different ways by different clients; it is intended to allow story authors to have a general visual impact on the clients in which their story is played. It's up to the client to determine how to support specific color values, but matching the CSS spec is recommended.
<setmidcolor>#85a5cc</setmidcolor>Changes the currently active sequence. The new sequence is referenced by its id. To cause the new sequence to play its first step automatically, set the autostart attribute to true.
<setsequence autostart="true">denouement</setsequence>Sets the temperature of the place where the story is occurring. You can specify the temperature units with the units attribute.
<settemperature units="fahrenheit">98.6</settemperature>Sets the date and time at which the story is currently taking place. Effectively the same as <setdate>.
Sets the current weather conditions of the story, referencing a set of predefined constants adapted from http://openweathermap.org/weather-conditions.
<setweather>heavyrain</setweather>Supported weather values:
| Weather condition | Value |
|---|---|
| Clear | clear |
| Drizzle | drizzle |
| Light rain | lightrain |
| Rain | rain |
| Heavy rain | heavyrain |
| Thunderstorm | thunderstorm |
| Snow | snow |
| Atmosphere | atmosphere |
| Clouds | clouds |
| Extreme | extreme |
| Additional | additional |
A speech act which is sung by the attributed character. It's up to the client to determine how to intepret this action.
<sing character="ellaFitzgerald">A tisket, a tasket,</sing>Learn about setting the tone of speech acts.
A speech act performed by the attributed character. It's up to the client to determine how to intepret this action.
<speak character="motherSister">Mother Sister always watches!</speak>Learn about setting the tone of speech acts.
An act of thought performed by the attributed character. Considered an inwardly directed speech act. It's up to the client to determine how to intepret this action.
<think character="homerSimpson">Mmmm... donuts.</think>Learn about setting the tone of speech acts.
Triggers the next step from the sequence specified by id in the content, without navigating to that sequence.
<sample>singRandomNote</sample>An interactive option offered by the attributed character. Typically represented as a button displaying the content of the step. The type attribute determines the kind of action to be taken when the option is selected, and the destination attribute identifies the end point of the action.
| Type | Action | Destination |
|---|---|---|
| sequence | Jumps to the specified sequence | Sequence id |
| sample | Samples the specified sequence | Sequence id |
| step | Jumps to the specified step | Step id |
| url | Opens the specified URL | URL |
<option character="alJarreau" type="sequence" destination="rainbowSequence">Look to the rainbow</option>A collection of steps can be triggered simultaneously using the <group> element, which treats multiple steps as if they were one. A group can be used anywhere a step can, and can be nested.
<group>
<narrator>Ta</narrator>
<narrator delay="1" append="true">da!</narrator>
<speak character="piano">C5</speak>
<speak character="piano" delay="1">C5</speak>
</group>Speech acts have tonality, represented by the tone attribute.
<speak character="motherSister" tone="shout">Mother Sister always watches!</speak>To set the tone of a speech act to something other than the default normal setting, use one of these values:
| Tone | Value |
|---|---|
| Whisper | whisper |
| Murmur | murmur |
| Normal | normal (default) |
| Shout | shout |
| Scream | scream |
It's up to the client to determine how to intepret the tone of speech acts.
For steps which result in visible effects, clients generally assume that the content of the current step replaces that of previous steps. The append property, however, allows an author to indicate that the content of a step should be added to that which is already visible. This is useful for example, in breaking words into syllables which "stack up" as they are shown.
<narrate>In</narrate>
<narrate append="true">du</narrate>
<narrate append="true">bi</narrate>
<narrate append="true">ta</narrate>
<narrate append="true">bly.</narrate>Complex rhythmic, animated, and musical effects can be achieved using the delay property, which indicates the number of rhythmic units to wait after a step is triggered before it is executed. The duration of a rhythmic unit is determined by the story's <pulse> element. In musical terms, the <pulse> element's pulsesperbeat value determines the type of note signified by a delay value of 1.
| Pulses per beat | Note duration |
|---|---|
| 1 | Quarter note |
| 2 | Eighth note |
| 4 | Sixteenth note |
The value of the delay attribute can be a decimal, for fine-grained timing.
This example plays the theme from Close Encounters of the Third Kind on quarter notes in response to a single user input:
<pulse beatsperminute="120" pulsesperbeat="1"/>
...
<sequence id="ce3k" repeat="+">
<group>
<speak character="piano">D5</speak>
<speak character="piano" delay="1">E5</speak>
<speak character="piano" delay="2">C5</speak>
<speak character="piano" delay="4">C4</speak>
<speak character="piano" delay="5">G4</speak>
</group>
</sequence>