Getting Started

In this section:


Why Spreadsheets?

Stepworks stories are built in an open source format called Stepwise XML. Since XML is a common file format, this means that your stories can go lots of places. But XML isn’t the most fun to write, so to make it easier for you to create your stories, you can use Google Sheets spreadsheets, which Stepworks will convert to Stepwise XML behind the scenes.

Wait, what? Who would want to write stories in a spreadsheet? Well, as it turns out, the rigid rows and columns of the spreadsheet are a great way to organize stories with one or more characters that unfold in discrete steps—which is what Stepworks is all about.

Rows and Columns

Here’s how it works: every character in your story gets their own column, with their name at the top. Then, everything that character does is dropped into that column, row by row, in the order in which it’s supposed to occur in the story.

Here’s an example of a simple two character dialogue:

Alisha Charles
Hey Charles!
Hi Alisha!
How are you today?
I’m great, thanks.

Go ahead and open Google Sheets, create a new document, and either recreate this dialogue or make one of your own.

Publishing Your Story

In order for Stepworks to be able to access your story, you need to publish it first. Go to the File menu in Google Sheets, select “Publish to the web…” and then click the “Publish” button.

In many of the sample Stepworks spreadsheets, there’s a pink-colored cell that you can click on to open Stepworks and load your story automatically. If your spreadsheet doesn’t have that cell, or if you just want to know how to load a story manually, read on.

To load a story manually, you’ll need to copy the URL from the location bar of your browser—and ONLY from the location bar. You might have noticed a URL featured prominently in the dialog box that appeared when you published your document, but this is a red herring! It won’t work. Go for the location bar URL instead.

Picking a Stage

In a new browser tab, open Stepworks and click “Stages”. You’ll see a selection of different templates you can use to load your story—click “Text Messages”. This stage takes any story and makes it look like it’s taking place in a text message chain.

The Text Messages stage will initially load with a demo story. Click the big pink “Key, click, or tap to begin” button to try it out. Every time you click or press a key (pressing keys will probably be easier on your fingers—and more fun—once you start working with your own stories), you’ll advance one step in the story.

Loading Your Story

OK, time for the moment of truth. To load your story, click the Load button at the bottom of the window. A dialog box will open up, showing recently loaded Google Sheets stories. Click “Enter URL” and then paste in the URL to your story—the one you copied from the location bar. Click “Done” and you should see the story load (the big pink button will reappear once it’s ready to play).

Click the button, and then start performing your story, either with clicks or keypresses. Notice how the stage keeps track of who is saying what and displays each message the way you would see it in a real text chain. This is what stages do—they “stage” your story in a way that enhances some aspect of its meaning.

Making Changes

Now that your story is loaded into a stage, as long as you keep its window open you can go back to the spreadsheet, make changes, and then return to the stage and click the “Refresh” button at the bottom to reload your story. You can do this as often as you like as you fine-tune your creation.

Naming Your Story

You might have noticed that when you loaded your story, the title of the stage changed from “Text Messages” to “Sheet1”. This is because Stepworks looks at the name of the top-most sheet within the spreadsheet to get the title of your story, no matter what title you give the document as a whole. All of your stories will end up with the name “Sheet1” if you don’t change this! To enter a new title, double-click the name of the in the lower left corner of the spreadsheet window and type it in. Then, return to the stage and click “Refresh” to see the new title.

An added benefit of naming your story in this way is that Stepworks remembers the names of the most recently loaded stories so you can get back to them quickly. You can access this list of recent stories by clicking the “Load” button and selecting “Recent sheets” in the “Google Sheets” tab.

Working With Multiple Drafts

A Google Sheets document can contain multiple sheets, but Stepworks only looks at the first (the one with the left-most tab at the bottom). This means that you can include multiple drafts of the same story in different sheets and try them out just by dragging their bottom tabs around and then clicking the “Refresh” button on the stage. Handy!

Restaging Your Story

One of the cool things about Stepworks stories is that they can be “restaged” in radically different ways, much like a traditional play. This is because the underlying content of your story is stored in the Stepwise XML format, separate from its look and feel (which is handled by the stage).

To see this in action, return to your Stepworks stage and click “Stages”. Pick the “Vocal Grid” stage, click “Load” at the bottom and pick your story from the “Recent sheets” section of the “Google Sheets” tab. Try your story out. Notice how in this stage, each character is assigned a different section of the screen where their words appear—that’s why this stage is called Vocal Grid.

You can load any Stepworks story into any stage on the website. You’ll probably find that some stages will show off your story better than others. Sometimes you’ll discover new facets of your story just by viewing it in a different stage.

Even better, work is underway to get other apps, games, and software to support Stepwise XML so that they, too, can load your stories—resulting in entirely new experiences driven by the same narrative you crafted in your humble spreadsheet.

Interested in an easy route to adding user generated stories to your app? Consider supporting Stepwise XML—it may be easier than you think. Get in touch and I can help.

Appending Content

The Text Messages stage shows everything said by every character in a scrolling list, just like a real text chain. Not all Stepworks stages work this way, however—as we saw in the Vocal Grid stage, many will simply replace whatever the current character said then with what they’re saying now.

This might not be what you want, however. If you’re building a sentence word by word, or a word syllable by syllable, you probably want each new bit of text to be added to the last, instead of replacing it.

Ampersand to the rescue. If you want the next bit of text to be appended to the text that’s already been shown, just put an “&” in front of it, like this:

Alisha Charles
Hey Charles!
Hi Alisha!
& How are you today?
& I’m great, thanks.

Go ahead and add some ampersands to your story, return to the Vocal Grid stage, load your story and try it out.