Twine Makes Branching Scenarios Easier

The free open source tool Twine makes planning, writing, and creating branching scenarios easier. It’s a simple way to create prototypes.

The free open source tool Twine is designed for creating nonlinear stories. That makes it perfect for creating branching scenarios. I use Twine for planning the structure, drafting the content, and building a functional prototype.

Twine makes creating branching scenarios easier.

Updated for Twine 2.5.1 and Harlowe 3.3.3

I originally wrote this post in 2020, using an older version of Twine. Twine (the software) and Harlowe (the default story format) both received significant updates in August 2022. Therefore, this post needs a significant update, including nearly all new screenshots. If you’re curious about the older Twine interface, check the archived version of this post.

Check the Twine reference for additional information.

Getting started with Twine

First, download and install Twine. Make sure you get the right version of the desktop app (Windows or Mac). If your workplace doesn’t allow downloads, try the online version instead.

Note for Windows users: You may see a warning about Twine being an “unrecognized app.” If you see this message, select More info, then select Run anyway to run the installer.

Note for Mac users: You may see a warning that the Twine app wasn’t opened because it’s from an unknown source. Select Open anyway to launch it. If you’re still having trouble, try changing your OS settings to allow unsigned apps.

Create a new story

In the Story menu, click the +New button to create a new story.

Twine Story menu with an arrow pointing to the +New button

Give your story a name, then click Create.

What should your story be named? You can change this later.

Your story will automatically open. You’ll see a single Untitled Passage in the center to start.

A new story in Twine

Double click the Untitled Passage to open it.

A new, untitled passage in Twine

Click Rename to change the title from “Untitled Passage” to “Intro” or whatever you want.

Dialog box for renaming a passage

Enter the introduction to the scenario in the body text section.

Story intro in a passage

Add and link passages to create the branching structure

The power of Twine for branching scenarios is in the simplicity of creating additional passages with links between them. Unlike many other tools, Twine is built for nonlinear structures.

To create a link to a new passage, just type double brackets around the text of the link. In the screenshot below, [[Let’s get started]] is the new link.

When you close the first passage, you’ll see a new passage with an arrow linking it to the first passage. The new passage is transparent and has a dotted outline because it’s currently empty.

Two linked passages in Twine

Repeat this process to add a question with multiple options.

Passage text with three links at the bottom in double brackets

Caption: 3 links to 3 new passages

Adding multiple links creates multiple new passages.

You can continue repeating this process for your entire scenario. You can create the structure first; just add titles and links (plus maybe some brief notes about the content). I usually write the ideal path first, the one showing all of the best possible choices. I write that from start to finish, leaving placeholders for other options. Then, after drafting the ideal path, I go back to fill in the rest of the branches.

Build and test a functional prototype

In addition to the ease of creating links and new passages, the other huge time saver with Twine is that those links are functional. You can preview and test your branching scenario.

Play mode is perfect to just click through your entire scenario. Test mode is better if you are troubleshooting specific issues. Play mode is usually fine for basic branching scenarios and when you’re just getting started.

Play mode

To walk through your entire prototype so far, click Build, then Play.

In Play mode, you will see a passage with text links, like this. By default, Twine uses a dark background and light text. (You can change that formatting later, but it’s good enough for the first prototype.)

Twine passage with white text on a dark background and blue links with insufficient contrast

Test mode

In the Build menu, click Test if you want to use debug mode to view where links go (very useful if the link text is different from the passage name) or are troubleshooting variables, macros, or other advanced features. Test mode will initially look the same as Play, but with additional information on variables and errors in the lower right. In test mode, you can turn on Debug view via a button in the lower right.

Twine debug and test options

Publish and share for review

In my experience, most SMEs have a hard time envisioning how branching scenarios will work unless they have used them before. They just can’t understand a storyboard in Word or PowerPoint, or they get lost trying to jump back and forth following “jump to slide 15” notes. Twine makes review simpler because SMEs can click through and see how everything fits together.

Publish your scenario

To publish your story, click Build, then click Publish to File.

Twine Build menu, arrow pointing to the Publish to File button

Host your story

You can host this html file on a server if you have your own website, or you can use a hosting service Amazon S3 or Google Cloud. Many Twine developers use for hosting Twine games because it’s free and has options to restrict access.

Once it’s hosted on a server, your SMEs and reviewers can play through every path.

You can also share the html file in a shared drive like Google Drive, Dropbox, or Sharepoint. However, the story won’t be playable if it’s shared this way; users will have to download the html file and open it locally.

Proofing formats for review

In the Build menu, another option is to Proof the story. This gives you a proofing copy, usually a copy of the text for the entire scenario. I often copy this to Word and provide this to SMEs in addition to the prototype if they want to make significant text changes. I find it’s easier to track text changes in Word, especially if there are significant text changes.

Twine has some other options for proofing based on proofing formats. These formats have to be installed. One proofing format I use is poof, which provides options to export plain text and PDF versions of your story. Another proofing option is Illume, which has more advanced features for reviewing and tracking changes.

Example prototype

You can see a functional Twine prototype that I built for another scenario. This is just plain text, but all the links work. The scenario is fully functional.

Beyond prototypes

Although I often use it for plain text prototypes (building the final version in another tool like Storyline), you can use Twine as your final product. You can use CSS to format the story or use formatting options in the Harlowe story format. Twine also has macros for coding, so you can do things like tracking a score and providing conditional feedback messages.

Have you tried Twine?

If you have tried Twine yourself, I’d love to hear if it helped you write branching scenarios more efficiently or if you’ve created a cool project.

Originally published 1/21/20. Minor updates 6/16/21 Significant updates 10/28/22.

22 thoughts on “Twine Makes Branching Scenarios Easier

  1. Lindsey — if you have a website, you probably have some space on your web server where you could create a separate directory for your Twine scenario to live. Even if you have a WordPress site or some other CMS that displays at your domain, you should be able to put files in a folder on your webserver *next to* your WordPress files that would display if you navigate to

  2. Hi Christy! What process do you use for making updates to the scenario after you’ve built the scenario in Storyline but then the client requests additional changes in subsequent reviews? If you have to change how the story branches, do you go back to Twine for the structure?

    I’ve used a Word document in the past, and as you know, it gets very hard to keep up with when you’re dealing with complex branching–and it’s hard for SMEs to review. I’m excited to try using Twine instead. I’ve played with it but haven’t actually used it in a project yet.

    Thanks so much for sharing your expertise!

    1. That is a great question, Kayleen. I wish I had a really simple answer! It depends on the situation.

      First, I set the expectations early on that the majority of the changes should happen while we’re in Twine, before I rebuild it in Storyline. I would rather add an additional round of review in Twine than have to go back and change it in Storyline later.

      With my consulting clients, that means my SOW specifies that any of those structural changes happen in Twine. Once they approve it in Twine and development starts, it should only be minor text tweaks, not structural changes. If it’s big structural changes, then it’s out of scope, and they’re going to pay for the additional time.

      In reality, even with setting those expectations, sometimes that happens. It actually happened to me last year with a client I’ve worked with before, but this was their first branching scenario. It was a frustrating process for everyone, and delivery ended up months after the original goal. But, they’re willing to pay for additional rounds of review and revision, so that’s what we did. A scenario that was originally 52 passages in Twine ended up as 75 slides in Storyline–waaay more changes than I had originally hoped. We knew this topic was subject to change though, so I planned a few things to make revisions a little easier.

      In that case, I fortunately used more of a “Short Sims” style approach, like Clark Aldrich’s examples. This scenario had a lot of bottlenecks, which provided pretty easy places to add some additional decisions into the structure. I didn’t go back to Twine for the revisions; I did everything in Storyline at that point.

      That scenario also was text and images only, with no voice over or video. We had deliberately chosen that media because we knew we might need to do more updates later if their content changed. That made the changes in Storyline much faster than if I had also been dealing with audio/video.

      However, if I hadn’t had any bottlenecks, or the changes really fundamentally shifted the structure, I might have backed up in the process and gone back to Twine. I haven’t had to do so yet, but I can envision situations where the stakeholders requested such a fundamental shift in direction that making the changes in Twine would be more efficient.

      The good news is that Twine (or a combo of Twine plus a text export) makes it so much easier to review that the SMEs are much more likely to catch any big structural problems earlier. You can’t eliminate the possibility of big changes, but you can certainly reduce the likelihood.

      1. Thanks so much for the detailed response, Christy! I will have to get Clark Aldrich’s book–that’s one I don’t have yet. It definitely sounds like I need to be using Twine!

  3. Hey Christy! I am excited to use Twine for the first time! I have a functional prototype ready to be published but I am having trouble uploading the html to a server. I have a website I could use, but I am trying to do something quick and easy like Google Drive (In the past, I don’t believe they’ve had hosting capabilities but according to my research, they do now.). Do you have a recommendation for something “easy” where I can drop the published HTML file on a server in a quick manner? Security isn’t a concern. Thanks for your insight.

    1. I don’t think Google Drive will work. I just tested it, and it showed the code rather than the finished product. Maybe Google Sites would be able to do so.

      Amazon AWS is probably not the kind of quick solution you’re looking for, but it is what most folks end up using for their samples when their website is on a builder site like Wix. Check out the instructions here (it’s the same for a Twine published file as for Storyline).

      I haven’t tried this myself, but a quick search online turned up Netlify Drop as an option. It looks like you can just drag and drop a static html file and get a URL. That might be worth trying too.

Leave a Reply