Programming games in (mostly) plain English: Intro to Twine

I gave a talk at BarCamp Tampa Bay 2017 titled Programming Games in (Mostly) Plain English. I my talk, I presented the audience with a couple of tools that would allow them to build interactive fiction or “Choose Your Own Adventure” games with minimal programming or a programming language that looks a lot like plain English.

To find out more about BarCamp and its history, see my article on the topic on the Sourcetoad blog.

One of the tools that I showed the audience was Twine, a tool whose developers describe it as “an open-source tool for telling interactive, nonlinear stories.” You can use it to create “Choose Your Own Adventure”-style games without any programming. If you’re willing and able to do some programming — and it’s nothing terribly fancy or complex — you can throw in some additional sophistication to your Twine-based interactive creations.

In this article, I’ll walk you through the Twine “story” — that’s what the interactive stories or games that you create with Twine are called — that I presented at BarCamp Tampa Bay. You can follow along and try out Twine either by downloading the MacOS, Windows, or Linux desktop versions, or by using the online version (which is pretty close to the desktop versions).

An Aunt’s Story is a simple “choose your own adventure” tale starring an oft-overlooked character from a film that you may or may have not heard of. She lived on a desert planet a long time ago in a galaxy far, far away with two characters that I’ll call Grumpy Husband and Whiny Nephew, and she was plotted to free herself and live a better life. This story is told from her point of view.

The adventure begins

Let’s start by creating a new story. Click the + Story button on Twine’s home screen:

You’ll be asked to give the story a name. Enter An Aunt’s Story:

After you click the Add button, you’ll be taken to Twine’s storyboard, which shows a single passage, which represents a “page” in a story:

It has the default title of Untitled Passage. The  icon beside the title marks the passage as the one that the story will begin with.

Let’s try editing the passage. Double-click on the passage. You should see something like this:

Do the following:

  1. Change the title of the passage from Untitled Passage to kitchen.
  2. Double-click on the passage text and change it to:

You could [[try talking to Grumpy Husband]] or perhaps it might be better to [[see what your Whiny Nephew is up to]].

What you just entered is the text that will appear on the page that corresponds to the passage. The text in [[double square brackets]] does a couple of things:

  • It links to another passage, whose name is the text in the brackets. For example, [[try talking to Grumpy Husband]] links to another passage named try talking to Grumpy Husband.
  • If the other passage that it links to doesn’t already exist, it creates that passage. Since the try talking to Grumpy Husband passage didn’t already exist, Twine creates it.

The passage editing window should look like this:

Click the X in the upper right-hand corner to exit the passage editing window. You’ll return to the storyboard, which will now look like this:

Note that there are two newly-created passages: try talking to Grumpy Husband and see what your Whiny Nephew is up to. Twine inferred that you’d need them because the kitchen passage links to them, and they didn’t exist yet.

To make the story a little more complete, do the following:

  • Edit the try talking to Grumpy Husband passage so that its text is “This is the Grumpy Husband passage.”
  • Edit the see what your Whiny Nephew is up to passage so that its text is “This is the Whiny Nephew passage.”

The storyboard should now look like this:

Now we have enough of a story to play. Press the  Play button to play the story. You should see this:

If you click on the try talking to Grumpy Husband link, you get taken to this passage:

And if you click on the see what your Whiny Nephew is up to link, you get taken to this passage:

Congratulations — not only have you written your first twine interactive story, but you also now know enough to write basic “Choose Your Own Adventure” stories!

Separating link text from passage titles

With simple links in Twine, a link called [[link text]] links the text “link text” to a passage whose title is link text. If you’ve done wiki or Markdown links, you’re probably wondering if there’s a way to make links whose text is different from the title of the passage that it should link to.

Such a way exists, and the format is like this:

[[link text|name of passage to link to]]

For example, to link the text try talking to Grumpy Husband to a passage titled talk to owen, you would format the link like this:

[[try talking to Grumpy Husband|talk to owen]]

This format of link lets you link long passages of text to passages with shorter names that might be more meaningful to you as a story author. Let’s take advantage of these links by doing the following:

  • Change the title of the try talking to Grumpy Husband passage to talk to owen.
  • Change the title of the see what your Whiny Nephew is up to passage to talk to luke.
  • Open the kitchen passage. You’ll see that Twine has changed the text in the links:

You could [[talk to owen]] or perhaps it might be better to [[talk to luke]].

  • Edit the kitchen passage so that it looks like this:

You could [[try talking to Grumpy Husband|talk to owen]] or perhaps it might be better to [[see what your Whiny Nephew is up to|talk to luke]].

The storyboard should now look something like this:

Now that we’ve got a way to give passages short titles that are useful to the author and link to them with long strings of text that are meaningful to the reader, we can now craft our story.

Let’s make a story!

Now that you know the basic mechanics of working with Twine, let’s make a story.

An Aunt’s Story is based on Star Wars: A New Hope, a.k.a. Episode IV, a.k.a. the first film, and is told from Aunt Beru’s point of view.

In this interpretation of the story, Beru’s fed up with her life— she’s as a moisture farmer on a desert planet who’s married to a guy who seems never to be anything other than grumpy and stuck with a whiny nephew.

Your best way to get a feel for the game is to play it online. Go and try out all the options — there are only 9 passages in the story, so I shouldn’t take you too long to see them all.

1. Edit “kitchen”

We’ll start by setting the editing the starting passage, kitchen, to give it a more complete text:

<h1>An Aunt’s Story</h1>
Wiping away the last of the blue milk from the table, you realize that the chores are done. You sigh as once again, the men in the house have failed to help clean up and stuck you with all the work.

Perhaps it’s time to talk to them.

You could [[try talking to Grumpy Husband|talk to owen]] or perhaps it might be better [[to see what your Whiny Nephew is up to|talk to luke]].

Note that there’s an <h1> tag in the text. HTML tags work in Twine in the same way they work on web pages. Here’s how the passage will look:

2. Edit “talk to owen”

Change the text in the talk to owen passage to this:

Grumpy Husband did what he always does does after dinner: slouched into the living room sofa, flipped on the holoprojector, and put on the pod races. He’s mesmerized by the action, taking occasional sips from his beer. He’s halfway through the 12-pack as you enter.

“Don’t bother me, woman,” he slurs, his eyes not moving from the race.

Looking at him, it becomes clear to you that [[going ahead with your big plan to change everything|proceed with plan – owen]] is the right way to go. But there’s a part of you — the part that always tells you to “stay in your lane” — that tells you that sometimes he’s nice, that he’s a good provider, and hey, what other prospects do I have living on this rock? Maybe I should just [[accept things as they are|accept fate]].

Since this text includes links to passages that don’t yet exist, Twine automatically creates them: proceed with plan – owen and accept fate. The storyboard will look like this:

3. Edit “accept fate”

Edit the accept fate passage so that it has this text:

The movie continues as scripted, which is good for Whiny Nephew; not so good for you.


Note that there are no links in accept fate. That’s because it’s one of the story endings. In a more fully-produced story, you might want to provide a link that allows the reader to start over from the beginning.

4. Edit “talk to luke”

Edit the talk to luke passage so that it has this text:

You walk into the garage, where Whiny Nephew spends what little time he has when he’s not helping Grumpy Husband on the farm, eking the scant moisture from Tattooine’s arid atmosphere.

He’s sitting at his tool table doing what he does best: moping and bellyaching. So what else is new? At least he has those droids to keep him busy.

Whiny Nephew turns to you. “Aunt Beru,” he says, “I think these droids are stolen.”

Oh, great, you think to yourself. That throws a wrench in my plans.

“I think you should report this,” says Whiny Nephew, who’s always been a bit too much of a goody two-shoes for his own good. You wonder if his dad was this much of a crybaby, and what his mom saw in the guy.

You could [[get the cops involved|call cops]], or simply [[proceed with your original plan|proceed with plan – luke]].

once again, you’ve provided text that includes links to passages that don’t yet exist, Twine automatically creates them: proceed with plan – luke and call cops. The storyboard will look like this:

At this point, you might want to drag the passages around so that it’s easier to follow and the arrows don’t overlap. Twine will preserve the connections between passages, so don’t feel leery about moving those boxes around.

Here’s how I rearranged the passages:

5. Edit “call cops”

This is one of the story’s endings. Edit this passage’s text so that it looks like this:

You slip into your room and quietly call up the local constabulary on your comlink. In a matter of minutes, a couple of nice friendly stormtroopers arrive.

The ’troopers put your Grumpy Husband and Whiny Nephew under arrest, slapping binders on their hands behind their backs. You allow a slight smirk to cross your face as they are led away, never to be seen again.

They put restraining bolts on the stolen droids. Now immobilized, it’s very easy for them to use laser cutters to slice into the R2 unit, from which they retrieve some kind of data tape (this movie was made the 1970s, so yes, data is stored on tapes).

“You’ve done a great service to the Empire, ma’am,” says the commanding officer. “There’s a 250,000-credit reward for these droids.”

“Oh dear,” are the last words you hear the protocol droid say before it and the now-headless R2 unit are taken away for scrap.

After all this fuss, it’s time for a nice vacation. With a quarter million credits in your account, you can go anywhere and do anything you like! Hours later, you’re flying first class to a place you’ve always wanted to visit: the lush, beautiful, fantastic vacation desination of Alderaan.


6. Edit “proceed with plan – luke”

Edit the proceed with plan – luke passage so that it has this text:

“Don’t worry,” you reassure Whiny Nephew, giving him a gentle kiss on his forehead. “There aren’t my first stolen droids. I’ve got a bulk eraser in the closet, and we can wipe their memories clean tomorrow. I’ll also show you how to file off their serial numbers.”

Whiny Nephew looks at you with big bantha eyes and nods. You send him off to bed. The protocol droid shuts down for the night. That leaves the R2 unit.

[[Looking at the R2 unit, you get an idea|deal with R2]].

This text includes a links to passage that doesn’t yet exist, so Twine automatically creates it: deal with R2. The storyboard will look like this:

7. Edit “proceed with plan – owen”

Edit the proceed with plan – owen passage so that it has this text:

Your plan to deal with Grumpy Husband requires no witnesses. You need to get Whiny Nephew away from the house for a few hours tomorrow morning.

You get an idea. Later that night, after you’re sure that everyone has fallen asleep, you [[sneak into the garage to check up on the droids|deal with R2]].

Note that the link in this text is to a passage that already exists, so Twine simply makes the connection:

8. Edit “deal with R2”

Edit the proceed with plan – owen passage so that it has this text:

Looking at the R2 unit’s head, you see that it’s got some kind of data tape inserted into it. You press the “eject” button below its eye, and out pops the tape.

You recognize the tape’s case and markings not just as Imperial data storage, but highly secure Imperial data storage. This droid’s way too hot, but it gives you an idea.

You reinsert the tape back into the R2 unit, boot it up, and tell it that you know where to find the master it’s been beeping and booping about since its arrival.

“Of course your master is the crazy old hermit who lives on the far side of Beggar’s Canyon. EVERYBODY knows that old BEN Kenobi is OBI-WAN Kenobi. That has got to be the DUMBEST witness protection program name.”

You pull the restraining bolt from the R2 unit. It lets out a quiet “squeeee!” of delight, and wheels away. (Once outside of the camera’s field of vision, it pops little rockets out of its sides and FLIES to Beggar’s Canyon.)

Now it’s time to [[deal with Grumpy Husband|deal with owen]].

This text includes a links to passage that doesn’t yet exist, so Twine automatically creates it: deal with owen. The storyboard will look like this:

9. Edit “deal with owen”

This is the last passage in the story, and it’s also one of its endings. Edit the deal with owen passage so that it has this text:

In the morning, Whiny Nephew realizes that the R2 unit has broken free of its restraining bolt. He and the protocol droid hop into the landspeeder in the direction of Beggar’s Canyon.

With all witnesses out of the way, you take something from a hidden panel in the pantry and walk into the living room, where Grumpy Husband passed out last night. He slowly wakes as you walk in, staring dumbly at you, a single drop of spittle dangling from his lips.

“Owen,” you say as you level the blaster at him, “it’s over.”

One shot would’ve been sufficient, but you wanted to be sure. You fire repeatedly until the blaster becomes too hot to hold.

Hours later, you’re at Mos Eisley spaceport, flying off into a brand new life. You left a fake corpse beside Grumpy Husband’s ruins; Whiny Nephew’s not all the bright and will simply assume that you and Grumpy Husband were killed by itinerant Tuskens, meandering Jawas, or who-know-what-else.

Much later, you find out that Whiny Nephew made the news. He’s a terrorist now!


The storyboard will end up looking like this:

You now have a Twine story with 9 passages and 3 endings!

Publishing the story

When you have a complete story, you may want other people to play it. You do this by publishing it to a file.

To publish your story, go back to Twine’s home page by clicking on the  Home icon at the lower left-hand corner of the storyboard screen. You should see the icon for your story:

Click on the  Settings icon. This menu will appear:

Select Publish to File from the menu. You’ll be asked for a location to save the file to. The end result is a self-contained HTML file that you can load in your browser, or even publish on your site!

Want the source?

If you want the source file for this story, get it here, then use Twine’s Import From File command to load it.