Stepwise XML Reference

Erik Loyer edited this page Apr 6, 2017 · 4 revisions

Stepwise content is delivered in the Stepwise XML format.

Root element and metadata

<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>	

Declaring a story’s meter

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"/>

Declaring characters

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"/>

Declaring locations

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

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>

Steps

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.

narrate

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.

nothing

An empty step.

<nothing/>

reset

Resets the sequence with the given id back to its initial state.

<reset>denouement</reset>

setbackcolor

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>

setdate

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>

setforecolor

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>

setlocation

Sets the location where the story is currently taking place, referencing the id of a previously declared location.

<setlocation>amsterdam</setlocation>

setmidcolor

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>

setsequence

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>

settemperature

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>

settime

Sets the date and time at which the story is currently taking place. Effectively the same as <setdate>.

setweather

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

sing

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.

speak

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.

think

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.

Groups

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>

Setting the tone of speech acts

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.

Append vs. replace

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>

Delaying steps

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>
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.