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:

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.

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.

Click on the Tell Me More button.

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.

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.

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.

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

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.

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

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.

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.

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

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

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:

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

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

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.

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.

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.

Click the delete button to delete the passage.

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.

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

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

Now both passages are connected with each other.

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.

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.

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:

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.

You should now see your story in a different perspective.

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.

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.

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.