Basic Concepts

Stories and Passages

Twine calls the things you make with it stories. But of course Twine can be used to create more than just fiction, or even prose, with Twine. People have used Twine to make:

  • Nonfiction essays
  • Role-playing games
  • Poetry
  • Visual novels
  • Procedurally-generated text
  • Interactive graphic novels
  • Dialogue trees for games
  • Complete nonsense

But Twine needs a word for these things, and 'story' made the most sense when Twine was first created more than a decade ago. This reference will call these things 'stories,' but you can substitute 'game' or 'poem' or 'nonsense' and every sentence you read will be just as true.

This reference also calls the people experiencing your work 'players,' but this isn't official terminology by any means. You can call them 'readers' or 'interactors' or just 'people.'

A story is made up of one or more passages. A passage is a piece of content that players will experience at one moment in time as they navigate through a story. Some people call them lexia or nodes. A story usually is made up of many passages, but it could technically contain just one--though you'd probably be better off using a traditional writing app or Web development tool instead in that case.

A story always has one start passage. This is the passage that will be displayed first when someone begins playing it.1

The Story Library

The collection of stories stored in Twine is called the story library, or just library for short.

If you're using browser Twine, the library is stored invisibly in your browser's storage. However, if you're using app Twine, you'll find your library in a folder named Twine in your documents folder. Or use the Show Story Library menu item in the View menu of Twine's main menu bar (not the top toolbar). This location can be changed.

Your library belongs to just you, regardless of whether you're using app or browser Twine. You can't share it directly with other people, but you can import stories, export stories, and archive your entire library.

There is no limit on the number of stories in your library. You're only limited by the storage capacity of where your stories are saved. In browser Twine, this varies by the browser you are using, but 5 megabytes of storage is typical.

Story Formats

Twine is a tool for editing interactive narratives. It isn't a tool for playing interactive narratives. When you share a story with players, it exists as an HTML file that can be opened in any web browser, and doesn't require players to install Twine themselves. Twine helps to edit a story, but what happens once players actually open it in a web browser is the job of story formats.

Story formats handle displaying your story onscreen: displaying text and images, playing sound and video. They provide additional ways for players to interact with your story, like buttons or drop-down menus. And they offer the ability to add conditional logic, variables, and other kinds of programming to your story.

Story formats are like game engines or small programming languages. There is no one best story format to use, just as there is no one best pencil or paintbrush. Like any creative tool, each is suited for some kinds of things and a poor fit for others.

Twine includes four story formats when you download it, and it is possible to add other story formats that people in the community have made.

  • Chapbook is the youngest story format. It's designed to be easy to learn and to make many common tasks people have when creating with Twine as simple as possible.

  • Harlowe is the default story format for Twine. It offers a lightweight but versatile programming language. As the default, it also has a large community of authors who use it.

  • Snowman is a minimal story format designed for people who are familiar with web development technologies like CSS and JavaScript, and prioritize customization.

  • SugarCube is the oldest story format of these, and as a result, has the largest community and resources to draw on. It offers extensive customization possibilities.

Changing the story format you use can be a time-consuming process because they vary so much in their approach. Because of this, the number of story formats to choose from can be daunting. Try browsing through examples on the Twine Cookbook to see what makes the most sense for you.

Proofing Formats

Twine also has special kinds of story formats called proofing formats. A proofing format is different than a story format in that it's meant to help you proofread your stories before you share it with a larger audience.

Twine comes with one proofing format, called Paperthin, but others with more features exist in the Twine community.

Twee

Twee is a plain-text format for Twine stories. Twee files are not playable by themselves, but are easier to edit and view in a text editor than the HTML files that Twine creates. The Twee format is documented here.

You don't need to use Twee to build a story with Twine, but Twine can export stories to Twee format for use with other tools.

1

In Twine version 1, this passage had to be called "Start" (including the capital S). Current versions of Twine allow setting the start passage to any one in a story, regardless of name.