A spaceship firing lasers at asteroids above the earth. This is the box art from Atari's Asteroids game.
Last updated: Oct, 2024


Twine is a Choose Your Own Adventure (CYOA) development environment. This is a tool that allows anyone with a little passion to write a branching story that you can share, sell or read on your own.

Twine is program developed by Chris Klimas. He originally wrote it as a desktop application but with the release of Twine 2, it is now a web app. This means Twine can run on any platform. All that is needed a modern web browser. While Twine has many contributors, Chris is the driving force behind the project. If you enjoy the software, support him on Patreon.

Twine is a free tool and the stories made with it are yours. This is different than say a competing product known as ChoiceScript where you need permission to sell your story.

This tutorial will teach you the basics of Twine to get started. This tutorial is the first in a series of tutorials to provide comprehensive coverage about writing branching narratives using Twine.

Launching Twine

There a many different ways to use Twine. You can access Twine from the official web site. You can download a Twine client and work locally. You can also write your stories outside of Twine and build your story using a tool called Twee2.

NOTE: Twinery has undergone a complete redesign since I started this tutorial series. This means all the screenshots will look different. In time, I’ll get this series up to date but for now, you’ll need to play around with the user interface. Mind you, all the code still works.

To get started working with Twine, head over to https://www.twinery.org. At the time of this update, twinery appears to be having a website certification issue. You may see something like the following:

A warning dialog that reads, "Warning: Potential Security Risk Ahead".

This means the security certificate is having issues. You can ignore this for now and hopefully it will be fixed soon. Twinery doesn’t require any personal information or require an account.

After the introduction text, you’ll notice two buttons. Click the Use in your browser button.

A screenshot of the website with the "Use in your browser" circled. That's the button you should press.
Current Twine homepage as of 2024

Since this is your first time using Twine, you’ll get a notification, asking if you’d like to know some important things about the Twine environment.

A welcome to Twine dialog that says, "Twine is an open-source tool for telling interactive, nonlinear stories."

Click on the Tell Me More button.

The same welcome dialog, except the "Tell Me More" link is circled.

This opens another dialog window with some Twine tips and other resources. Feel free to explore. Otherwise, when you are ready to start, scroll back to the original dialog and click the Skip button.

A welcome to Twine dialog. At the bottom are two links: Tell Me More and Skip. Click the Skip link.

Welcome to Twine!

Saving stories

Before you start writing your very first Twine story, it’s critical for you to understand how your stories are stored in Twine.

In a typical desktop app, you load files from your hard drive and save them back to the hard drive when you are done with them. With Twine, the application lives in your web browser. This means, when you save your story, you save it in the web browser’s data cache.

A saved story in one browser is not accessible in another browser. If you save a story in Chrome, and launch Twine in Firefox, Twine won’t “see” your saved stories. This makes it difficult to test stories in different browsers, but it poses another issue.

Should you clear out your browser data, you will delete all of your stories. There is no way to recover them.

Thankfully, Twine allows you to export your stories locally to your computer. You should always export your story at the end of a working session. Make it a habit.

Twine provides a downloadable version that does not run in a typical browser. You launch Twine from your program files. This application actually uses an embedded browser. This means, you are still at risk at losing your work.

Moral of the story: always export your stories.

Creating a new story

When you start Twine, you’ll be presented with the story list. You can think of this as your Twine desktop. This is where all your stories live.

This is shows a listing of all the stories. Since there are no stories at the moment, it reads "0 Stories".

As you see, my version of Twine is using Dark Mode. Dark Mode helps prevent eye strain. If you prefer Light Mode, click the Twine menu option and select Preferences.

This shows Twine selected in the menubar. In the sub-menubar, the Preferences link is circled. You should click that.

From the Theme option, select the mode that you wish to use.

This shows the Preferences dialog. Next to the Language dropdown is the Theme dropdown. Use that dropdown to select between Light and Dark.

For the purposes of this tutorial series, I will use Light Mode. Close the dialog to re return back to the Twine desktop.

Since you want to create a new story, click the Story menu item and then click the New Story option.

This shows Twine desktop again. The Story link is selected in the menubar. On the sub-menubar, the "+ New" is also selected too. Click that to create a new story.

You’ll be prompted for the story’s name. Call it: Bernie’s Revenge. Then, click the Create button.

This shows the Create Story dialog. In the dialog, it reads "Bernie's Revent". The Create link is circled. Click that to create a new story.

In this story, you’re a lone boy scout trapped in a summer camp. The camp cook, Bernie, stalks the camp with his chili, giving everyone food poisoning. Now, he wants you to try it. You must escape before he gets to you!

This is the story you will write in this series. It provides a lot of cool features with lots of interaction. By following along, you’ll learn about all the cool Twine features.

For your own story, you can make it as simple or as complex as you want. The key goal is to entertain the reader. There is no right way or wrong way to write a Twine story.

Creating Passages

When your story starts, you’ll be presented with the Twine workspace. It contains only one passage. This is the starting point of your story.

This shows a green rocket ship icon next to a single empty passage.

A Twine story is composed of a series of connected passages. A passage represents a block of text or code. It could represent an entire room, a paragraph in an essay or even just a singular word.

Passages connect to each other which allows the user to traverse your story. A passage can connect to any other passages and they are allowed multiple connections. In time, you’ll create a large network of passages that forms your story.

A picture of my story in Twine. It's a network of passages connected together.
This is a series of passages I wrote for my story, “Cold Storage”. The interface is set to dark mode.

You can also create passages without connections or even islands of passages. These passages can sometimes be used by Twine to load in additional settings. You can also embed passages in other passages or send the user to them when they are running the game.

You’ll notice a rocket ship next to the starting passage.

This green icon indicates the starting passage. This is the first passage that is displayed to the reader. Double-click the passage. The following opens:

This shows an editor for the untitled passage. It contains several menubars with icons and a large space for writing and editing text.

This is where you write your story.

The first thing to add is the passage name. The passage name is only for you. It is not shown to the end user. Click the Rename button and name the passage: Camp Entrance

In the passage editor, the rename button is clicked with the rename dialog open. Written in the dialog are the words: Camp Entrance.

Click the OK button. This changes the name of the passage.

This shows the passage dialog changed with the new name, "Camp Entrance".

Now to write some text! Add the following in the passage text area: A dusty dirt-strewn road leads into the darkness of the camp. You see the road disappear between the trees, engulfed in fog. A sign next to the road reads, “To Camp Center”.

Your passage should now look like the following:

This shows the Camp Entrance passage with the text added to it.

Close the dialog by clicking the X button in the corner. You’ll now see the passage name and a preview of the text.

This shows a preview of the first passage with some text written in it.

In this particular story, each passage represents a different location. This doesn’t have to be the case for your story. You could have a passage represent a character description, an inventory screen, or even just a line of text.

Linking passages

It’s time to create a new passage. In the story, you created a passage to indicate the starting point of the camp. A dusty road leads into the camp. It’s time for you to create that dusty road.

With Passage selected in the menubar, click the + New button.

This shows the Passage menubar item selected with the + New showing up underneath it.

This creates a new empty passage. Since your new location is southeast of the Camp Entrance , move it to the southeast of the passage.

When I use passages as map locations, I like to logically position them. That way, I always know where to find my passages. If you are using passages in different ways, spend a little time with your organization so you understand the layout of your story at a glance.

Double-click your new passage. Give it the name: Dusty Road. For the description, add the following: The dusty road is lined with looming trees on both sides of it. Through the gaps in the trees, you see the silhouettes of abandoned tents in the fog like lost souls. The road leads to the entrance of the camp, but also, towards the camp center.

This shows the new Dusty Road passage with the text added to it.

Now that you have two passages, your next task is to link them together. You create your passage links in the text. Links are designated by double brackets: [[ ]]

Links must always contain a passage destination. Double-click the Camp Entrance passage to open it in the editor. At the bottom of the passage, add the following: [[Run Away]]

You’ll notice that once you start typing, you’ll be presented with destination options for the link. Ignore those for now.

Screenshot showing list of passage options from a dropdown

When adding your link, you’ll see a new passage named “Run Away”, connected with an arrow. The arrow indicates the direction of the passage.

This shows all the passages with the new Run Away passage added.

In this case, the player the arrow points from the Camp Entrance passage to the Run Away passage. This means the link is a one-way link. When the user clicks on the Run Away link in the Camp Entrance, they’ll be taken to the Run Away passage. Unfortunately, there’s no link back to the Camp Entrance.

You don’t need this new passage. Click on the Run Away passage. Now you can access the Passage menubar.

This shows the Run Away passage selected with the sub-menubar selected.

Click the delete button to delete the passage.

This shows the Run Away passage selected with the Delete menu item selected.

This deletes the current passage, creating an orphaned link. Twine lets you know about the orphaned link by placing a stop sign over the link.

This shows the Camp Entrance showing a red line that leads to a red stop icon. This indicates a broken link.

Since you won’t be allowing the player to run away, double-click the Camp Entrance passage and remove the [[Run Away]] text. This deletes the broken link.

Connecting your passages

Your task is to link the Camp Entrance passage to the Dusty Road passage. This time, you’ll provide custom for the link.

Double-click the Camp Entrance passage to open it. Replace dusty dirt strewn road with [[dusty dirt strewn road->Dusty Road]]

This shows the Camp Entrance passage with link pointing to the Dusty Road.

This links up the two passages. The ‘dusty dirt road’ is the link text. After which, you private a custom arrow: ->. This arrow points to where the text should go. In this case, it points toward the Dusty Road.

You’ll see that the passages are linked together:

This shows the Camp Entrance passage linked to the Dusty Road passage.

Passage names are case-sensitive, meaning “Dusty Road” is different than “dusty road”. Also, an empty space is considered a character. For example, this code: [[dusty dirt road->Dusty Road ]] links to the “Dusty Road ” passage as opposed to the “Dusty Road” passage.

Passage links also adapt to different languages. If your language is written from right to left, you can reverse the link order by also flipping the arrow. So this [[dusty dirt road->Dusty Road]] is the same as this: [[Dusty Road<-dusty dirt road]]

Now, to link the Dusty Road back to the Camp Entrance. Double-click on the Dusty Road passage. Replace the entrance of the camp with [[entrance of the camp->Camp Entrance]].

This shows the Dusty Road passage with the camp entrance link.

Now both passages are connected with each other.

This shows two passages now linked together with a two way arrow.

Playing your story

Your passages linked. While this isn’t anyway completed, it’s a good time to try it out. From the menu, Build option. Click the play button to run your story.

This shows the Build menu item selected with the Play button.

A new browser window or tab will open with your new Twine story ready to go. Make sure to read your story and click the links.

A screenshot of the browser running the story. It shows the first passage.

Congrats! You’ve created your very first Twine story. The default look and feel of the story are defined by the story format. You are using the Harlowe story format which is the default story format for Twine.

If you were to use the SugarCube story format, your story will look like the following:

A screenshot of the same story running in the browser, except using the Sugarcube format. It includes a few other options such as saves and restart.
Your Twine story viewed using SugarCube

While story formats provide the default look and feel, they also define how you write your story. In fact, choosing a story format is one of the most important choices you’ll make when working with Twine. You’ll learn more about story formats later in this article series.

Proofing and exporting

Your story is complete! Congratulations. There two things you may want to do, proofing and exporting.

Proofing is when you want to review all the text without getting lost in all passages. This means you can print out your story and pass over to an editor or just edit it yourself. Mind you, your linking code is included.

With your story still open, Build menu option and then click the Proof button.

This shows the Build menubar item selected with the Proof menu item underneath it.

You should now see your story in a different perspective.

This shows the proofing view of the story. It lists each passage name with the passage text underneath it.
A proofing copy provides an editor-friendly view of your story.

Once you have proofed your story, you may want to publish your story. When you publish your story, you aren’t publishing it for the world to see, rather you are saving it to a file. You can then upload that file to a game server like itch.io or embed it into a mobile app.

From menu, click Build and then click the Publish to File.

This shows the Build menubar item selected followed by the Publish to File menubar item.

Doing so will produce an HTML file. This is the saved version of your story. You can also play it. To play it, just open it up in any browser.

You can also import this story into Twine whereby you can edit it. To do so, return to the Twine desktop. Click Library from the menu and then click Import.

This shows the menubar with the Library item circled and the Import option circled underneath it.

You then just indicate the file location of your story, and you will import it. Remember to always back up your story so you don’t lose your hard earned work.

Where to Go from Here

Congrats on writing your very first Twine story! In subsequent tutorials, you’ll build on Bernie’s Revenge and add some awesome features to it.

If you got stuck or want to compare your work against the reference story, you can download it here:

Your next task is to build all the passages in the story that compose the campground and link them all together. You’ll do this in the next tutorial.


Discover more from Jezner Blog

Subscribe to get the latest posts sent to your email.

By Brian Moakley

Brian Moakley is a writer and editor who lives amongst the quiet hills in New England. When not reading tales of high adventure, he is often telling such stories to all who will listen.

Related Post

Leave a Reply