Hello!

This is a reference guide for the Twine editor. It describes Twine's user interface and introduces the larger ecosystem that surrounds it. If you've never built anything with Twine before, this will guide through the basics and point you to resources that will help continue to learn.

You don't need any previous programming or game-making experience to be successful with Twine. These elements can be gradually introduced into the things you make as you grow more comfortable with the application.

What Is Twine Good At?

  • Text-based storytelling. Twine is very text-focused, though you can use images, sound, and video.

  • Branching narratives. Twine's user interface is designed to make it easy to visualize the flow through branches of a narrative.

  • Web-based publishing. Twine publishes to HTML files which can be uploaded on any web hosting service or shared privately. People can play the things you make without installing any extra software.

What Is Twine Bad At?

This is especially difficult to define, because authors are so ingenious and constantly push at the boundaries of what is possible. Because Twine is deeply enmeshed with the web platform, anything that can be done in a browser can be done with Twine--but you might be better-served using a different tool.

  • Heavy use of multimedia. It's possible to incorporate images, sound, and video into the things you create with Twine, but the workflow can feel awkward, especially if you are using lots of multimedia assets. You might be happier using a tool like Ren'Py.

  • Online and multiplayer play. There have been experiments with making Twine games that are playable by multiple people simultaneously, but doing so requires a good deal of programming knowledge. There have not been many modern successors to the MUD model, but Seltani is one.

  • Works that involve a world model, or that use interaction models other than clicking links, like a text parser or a graphical world. Inform or Bitsy, for example, might be better fits for these.

See Limitations for more details on some of the above and some possible ways to work around these issues.

See Also...

In order to use Twine most effectively, you should spend some time reading the documentation for the story format you're using. (Wait, what's a story format?)

You might also find the Twine Cookbook useful to read. It contains example code and explanations for things Twine authors often want to do.

Getting Started

This section describes Twine from the ground up: how to start using it and basic concepts that are key to understanding how it works.

Installing Twine

There are two ways to use Twine: in a web browser or by installing it onto a computer. Most people prefer to use it in installed form, but the browser version exists for people in settings which make it difficult to install software, like a classroom.

This documentation calls the version of Twine you use directly in a browser "browser Twine" for short, and the version of Twine you install onto a computer "app Twine."

If you're using a tablet computer, the only way to use Twine is through a web browser. Twine doesn't have an Android or iOS application.

Twine might work, vaguely, on a phone or other device of that size, but it's designed to be used on a larger screen. Because you'll most likely do a lot of typing in Twine, a physical keyboard is ideal, but you probably can use an onscreen one in a pinch.

Using a Web Browser

Go to https://twinery.org and follow the Use Online link to get started.

When you're using browser Twine, it will save your work to that browser and computer1. If you have multiple profiles in your browser, then your work is linked to that profile.

It's critical to understand that if you clear your browser's storage or delete your browser profile, you will lose all of your work in Twine. The exact way this is done varies by browser--for example, in Google Chrome, there is a Clear Browsing Data option in the Tools menu--but generally speaking, these features will say things like "clearing your browsing history" or "clearing web site data."

Keeping backups regularly is a must if you use browser Twine. See Archiving and Exporting Stories for how to do this.

iOS Browsers

If you want to use Twine on iOS, you must add it your Home Screen. If you don't do this, all of your work in Twine will be lost if a week ever passes without you using Twine.

This sounds like an urban myth or a ploy to get people to put Twine on their Home Screens, but it's unfortunately true. Apple places severe restrictions on how browsers work on iOS in the name of protecting users's privacy.

The policy it enforces that if a week passes where you do not visit a web site, Safari will erase all of its storage. This means that if you do not use Twine for a week, everything you create in it will be lost.

The one exception to this policy is if you add a web site to your Home Screen. Sites that are added as Home Screen shortcuts will not have their storage deleted.

It doesn't matter if you use Chrome, Firefox, or another browser app in iOS. The same restrictions apply because (as of this writing, anyway) Apple does not allow alternate browser engines on the iOS platform. Although these browsers might look or act differently than the built-in Safari app, underneath they still use Apple's Safari engine.

Safari on macOS

Do not use Twine in the Safari browser on macOS. The same problems noted in the iOS section above are true of Safari on macOS, except unfortunately there is no way to work around them.

Twine will show a warning about this if you do try to use it on Safari. This warning can't be hidden because the potential for losing all your work is so disastrous.

Installing On Your Computer

Go to https://twinery.org and use the download option for your platform (Linux, macOS, or Windows).

  • On Linux, the downloaded archive will expand to a freestanding directory containing the Twine application. You can place this directory wherever you like. You might find it easier to install Twine using your distribution's package manager, if it has a package for Twine.
  • On macOS, the downloaded archive will expand to an application that should be copied to your Applications folder.
  • On Windows, the downloaded file is an installer application that will put Twine in your Program Files folder and add it to the Start Menu.
1

To be specific, the browser version of Twine uses your browser's local storage. This is detailed more in Viewing Local Storage Directly. Local storage is similar to browser cookies, which you might be more familiar with, but cookies are limited to 4 KB of storage, whereas local storage can hold megabytes of data (the exact number is dependent on the browser).

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

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.

Getting Around in Twine

Some parts of Twine's interface are present no matter what you're doing in Twine.

The Top Toolbar

There's a toolbar that sits at the top of the screen no matter where you are in Twine. It's split into labelled tabs. The active tab has a blue border beneath the label.

In general, when you're using Twine, you'll select items below the top toolbar, then use buttons in the toolbar to perform an action on them.

The Back Button

In most parts of Twine, there is a Back button nestled in one corner of the top toolbar. It's blue to help it stand out. This button works like a back button in a web browser. If you've navigated between different screens in Twine, it will take you back to the screen you were last in.

The Back button isn't present in the Story Library screen because it's Twine's equivalent of a home page.

The Help Button

You'll find a Help button on the opposite side of where the Back button resides. This opens this guide in your web browser.

The Twine Toolbar Tab

No matter where you are in Twine, there will be a tab at the end of the top toolbar labeled Twine. This tab contains actions related to Twine itself.

  • Preferences opens the Preferences dialog, where you can customize how Twine works.
  • Story Formats takes you to the Story Formats screen, where you can manage story formats installed in your version of Twine.
  • About Twine opens a dialog showing the version of Twine you're using and a list of people who have contributed to Twine.
  • Report a Bug takes you to Twine's source code repository, where you can report a bug or suggest an improvement to the application.

Dialogs

Certain actions in Twine will open dialog boxes along one side of the screen with more detail about a particular action. For example, editing a passage will open a dialog box with the passage text.

Dialog boxes have a few controls in their title bar:

  • An x button in their corner that closes the dialog.
  • A chevron (›) button on the opposite side that collapses the dialog so that only its title bar is visible.
  • Some dialogs have a maximize button beside their close button which allows a dialog to fill the available space. To restore a maximized dialog's original size, use the maximize button again. Only one dialog can be maximized at a time.

You can have as many dialogs open as you have room onscreen for. Right now, the order of dialogs can't be changed, nor can their position onscreen be changed. The width of dialogs can be changed in preferences.

Updating Twine

Browser Twine

Browser Twine is updated whenver there's a new release, so there's no work for you to do to stay up-to-date. If you need to use an older version, go to https://twinery.org/[version number]. That is, to use 2.3.13, go to https://twinery.org/2.3.13. These different versions will use the same story library and preferences.

Keep in mind, though, that earlier versions will have bugs the most recent version does not, and there might be strange behavior moving backwards in time, so you should only use an older version if you really need to.

App Twine

To check if a newer version of Twine is available, choose Check for Updates from the menu named Twine in the menu bar (not the top toolbar). Twine will tell you if there's an update available and, if you like, will direct you to where to go to download the new version. Twine doesn't automatically update itself.

Uninstalling Twine

If you're using Twine in a web browser, there's of course nothing to uninstall. If you'd like, you can delete your browser's storage for twinery.org to remove your stories.

If you're using Twine on a computer, how you uninstall varies by the platform you're using.

  • On Linux, delete the directory containing Twine, or use your package manager to uninstall it.
  • On macOS, delete the Twine app from your Applications folder.
  • On Windows, right-click the Twine entry in your Start menu and choose Uninstall.

Using an Older Version of Twine

Switching from a newer version of Twine to an older one can be done, though you may experience odd behavior in the transition. Old versions of Twine of course aren't aware of any new capabilities that the newer version has added.

Twine follows semantic versioning. This means that the first version number of Twine only changes when a backwards-incompatible change is made, either to how it saves stories or how it interacts with story format extensions. This means that going from (using hypothetical versions for the sake of argument) Twine 15.0.0 to Twine 14.3.6 will likely be tricky, but going from Twine 14.3.6 to Twine 14.2.0 will not be.

What exactly you experience will depend on the particulars of the versions you are moving between. You may lose data in the transition. Switching from a newer version of Twine to an older one, generally speaking, is not well-tested.

Before You Switch Versions

Regardless of whether you are using browser Twine or app Twine, you should save an archive of your work. This will ensure that even if the absolute worst happens, you have a safe copy of your work.

Using an Older Browser Twine

Each version of Twine since 2.0 is available by visiting https://twinery.org/[version number] in your browser. For example, you can use Twine 2.1.1 by going to https://twinery.org/2.1.1.

Using an Older App Twine

Older releases are available on the Twine GitHub repository.

After Switching Versions

If you are using a built-in story format (Chapbook, Harlowe, Snowman, or SugarCube), then you will almost certainly need to either install a newer version of the story format separately, or change the story format your work uses.

You may also need to reset your preferences. Although the instructions linked are for the most recent version of Twine, they will probably work with most older versions of Twine as well.

Using the Story Library

When you first open Twine, it'll show you the Story Library screen. This screen lets you create new stories, organize them, and begin working on them.

Viewing Stories

Most of the Story Library screen is taken up by a list of the stories in your library. There will be a card for every story in your library, with a small visual preview of its structure1, how many passages it has, and when it was last changed.

To select a story, click or tap on it. You can only select one story at a time. Once selected, you can take action on the story using the top toolbar.

Sorting Stories

By default, Twine will sort your library by story name, so that a story named "Aardvark Revenge" will appear before "Zebra Brigade." You can instead have it sort your stories so that the most recently-edited ones appear first by choosing Sort By under the View top toolbar tab, then Last Updated. Choosing Name under the same button will change back to sorting by name.

Filtering Stories By Tag

You can tag stories to organize related ones together. Once you've tagged a story, you can filter the Story Library screen to show only stories with certain tags.

To do this, choose Show Tags under the View top toolbar tab. Choosing a particular tag will cause only stories with that tag to be shown. You can select multiple tags from the Show Tags button. In that case, Twine will show any story that has a checked tag name in the list.

To go back to showing all stories in your library, choose Show All Stories from the Show Tags button.

If the Show Tags button is disabled, that's because you haven't tagged any stories yet.

1

The color of your story preview is more-or-less randomly governed by your story's name. There isn't a significance to the colors--they're just there to help you find a particular story faster, and to look pretty.

Creating, Copying and Importing Stories

Creating a New Story

To create a new story, use the New button under the Story top toolbar tab. Twine will ask you what you'd like to call your story, but this is just a starting point. It can be changed at any time. The only limitation is that you can't have two stories with the same name in your library.

Once you've chosen a name for a new story, Twine will take you to the Story Map screen to let you begin editing it.

To change the name of a story once it's created, select it in the Story Library screen and choose Rename from the Story top toolbar tab.

Copying a Story

To make a copy of an existing story, select it and choose Duplicate from the Story top toolbar tab. Twine will create a copy for you with a unique name.

Importing Stories

Twine can import stories in progress, published stories, exported archives, and Twee source code. It cannot, however, import stories from Twine 1.

To import stories or archives, the process is the same:

  1. Choose Import from the Library top toolbar tab.
  2. In the dialog that appears, choose the file corresponding to your story or archive. If the file you want to import is disabled in the file dialog, it's because it's in a format that can't be used by Twine.
  3. If the stories in the file you selected don't have the same name as any story already in your library, Twine will import them immediately.
  4. Otherwise, the dialog will show the story or stories Twine found in your file. Select the ones you want to import; stories that won't overwrite existing stories in your library are checked off for you by default. The dialog'll warn you if a story you're importing has the same name as one already in your library. If you do choose to import it, it will overwrite your existing story completely.
  5. Use the Import Selected Files button in the dialog to import the files you've selected.

If you change your mind about importing midway through the process, close the dialog or choose a different file to restart the process.

Twee Import Limitations

Twine will use the story and passage metadata present in Twee source code, such as passage position or story name. If this metadata is not present, Twine will try to substitute reasonable defaults, but it will not handle all cases perfectly. In particular:

  • If Twee source code does not include passage positions, Twine will place passages in a grid pattern.
  • If a Twee file does not specify what story format and version it uses, Twine will set it to the default story format.

Editing Stories

To start editing a story, you can either double-click/tap a story, or select Edit from the Story tab in the top toolbar.

You can only edit one story at a time in the downloadable version of Twine. On a browser, you can open Twine in multiple tabs and edit a different story in each one, but editing the same story in multiple tabs will almost certainly cause problems. Browsers isolate tabs from each other for security, which means that Twine in one tab can easily overwrite changes made in a second tab on the same story.

Renaming Stories

To rename a story, select it and choose Rename from the Story top toolbar tab. Twine will prevent you from choosing the same name as another story in your library.

You can also rename a story while editing it.

Archiving and Exporting Stories

Archiving Your Library

Archiving your library saves all stories in it to a single file. You can use an archive as a way to back up your work, or to move your library between computers or different web browsers.

To create an archive, choose the Archive button under the Library top toolbar tab. You'll be asked where you'd like to save this file, and by default its name contains the date and time when you created the archive.

Exporting a Story

To export a single story, select it and choose Publish to File from the Build top toolbar tab. You'll be asked where to save this file.

This file can be either opened directly in a web browser to play your story, or imported into Twine.

The other buttons under the Build tab work the same as they do in the Story Map Screen.

Exporting a Story To Twee

You can also export a story to Twee format. Select it and choose Export as Twee from the Build top toolbar tab. You'll be asked where to save this file.

Twine creates Twee files with a .twee file suffix. Your system may not know how to handle them by default, but they are openable in any plain text editor, like Notepad on Windows or TextEdit on macOS.

Deleting Stories

To delete a story, select it and choose Delete from the Story top toolbar tab.

In browser Twine, deletion is permanent. You may want to archive your story before deleting it.

In app Twine, deleted story files are moved to your trash can or recycling bin on macOS and Windows. (On Linux, Twine does its best to move the story to the trash, but what exactly it does depends on your desktop environment). If you change your mind about deleting a story, you can take it out of the trash or recycling bin and re-import the story file.

Tagging Stories

Stories can be tagged to help your organize your library. These tags don't change anything about your stories when they're published1. They're only visible in Twine itself.

A tag always has a name, but it can also have a color if you like from a set of predetermined ones. Tag colors are only used to help distinguish tags from each other visually. It's not possible to create custom tag colors, and a particular tag can only have one color. That is, if you put a red my-tag tag on a story, you can't make that tag be green on a different story.

Another limitation of tags is that their names are not allowed to contain spaces. If you try to enter a space for a tag name, then Twine will convert it to a hyphen for you (i.e. my tag becomes my-tag).

When a tag is added to your story, it will displayed on the story card. It looks like a small sticker.

Once tags are added to your stories, you can filter the Story Library screen so that only stories with certain tags are visible.

Adding a Tag

Select a story, then choose Tag from the Story top toolbar tab. You can either use an existing tag or create a new one.

Removing a Tag

Select the tag sticker that's on a story card, then choose Remove.

Renaming a Tag

Choose Story Tags from the Library top toolbar tab. This will open a dialog showing all tags used in your library. Use the Rename button next to a tag to change it. This will affect all stories in your library with the tag.

Changing a Tag's Color

Select a tag sticker on a story card, then choose the color name from the menu that appears. This will change the color of this tag on all stories in your library. You can also change it using the Story Tags dialog as explained in the Renaming a Tag section above.

1

Story tags are available to story formats, so it's possible that one might change its behavior based on tags applied to stories. But this is discouraged so that authors can freely use tags as they like.

Editing Stories

When you edit a story from the Story Library screen, it will take you to a view of the story called the Story Map screen. You'll probably spend most of your time in Twine here.

Navigating the Story Map

The Story Map screen shows the visual structure of a story. Each passage in it is represented by a card, and links between them are shown as lines with arrows.

Scrolling and Zooming

You can scroll around the Story Map screen using all the usual methods you'd use to scroll around a window: the scrollbars on the side of the window, using scroll gestures on a trackpad, and so on. If you're using a mouse, you can also use the right mouse button to grab the view and move it.

In one corner of the Story Map, you'll see three buttons showing squares of different sizes. These let you zoom in and out of the map, showing different levels of detail in your passages.

Jumping to a Passage by Name or Text

To move to a particular passage in the Story Map screen, choose Go To from the Passage top toolbar tab, or press the P key any time your cursor is not in a text field.

This will open a dialog with a search field. Enter either the name of a passage or some text it contains, and a list of matching passages will appear. Twine uses fuzzy matching, so you don't have to enter the passage name exactly, and it will find close matches if you make a typo. When deciding which pasages match what you've typed, it slightly prefers matches in a passage name to what's in passage text.

Click a passage in the list or press the Return key to select the one which has two chevrons (») beside it to move your view so that the passage you've chosen is centered. The chosen passage will also be selected. Use the up and down arrow keys on your keyboard to move the chevrons in the list to another passage in the list of matches.

Empty Passages

An empty passage is one you haven't written any text in (usually). These show up in the Story Map as translucent cards with a dotted border. Twine automatically creates and deletes empty passages when you edit links in passages.

Tags

If you have assigned colors to passage tags, passages with those tags will have a small stripe of that color at their top. Tags that do not have colors assigned will not show a stripe.

The Story Start

The story's start passage is drawn in the map with a green rocket icon connected to it.1 To change this, select a different passage and choose Start Story Here from the Passage top toolbar tab. This button is also present in a passage edit dialog.

If there is a link in a passage that Twine can't find a passage for, it will instead show a red line ending in a 'no entry' symbol. Edit the passage to correct the problem.

References

A story format can extend Twine so that it displays references. A reference is a connection between passages, but how exactly they relate is up to the story format to define. One common example of a reference is when one passage embeds another inside itself.2

If a story format finds references in your passages, they will be displayed as dashed lines with arrows, rather than solid lines.

References in the story map can be turned off by disabling story format extensions.

1

The idea behind the icon is that it represents where the story 'lifts off.' 2: Again, embedding passages is functionality that a story format provides, because it governs what happens when a story is played. It isn't something Twine does in and of itself.

Undoing and Redoing

In the top corner of the Story Map top toolbar, there are buttons that undo and redo actions you take. Undo reverses the last action you took; redo redoes actions you undid. Twine tracks all actions you take editing a story, so you can undo multiple actions in a row.

The undo and redo buttons in the top toolbar don't affect text changes you make in an individual passages. There are separate undo and redo buttons in each passage editing dialog that manage your editing history there.

When you leave the Story Map screen, either going to a different screen in Twine or closing the application entirely, your undo history is discarded.

If the undo or redo button is disabled, that's because there's nothing to undo or redo yet.

Selecting and Moving Passages

Selecting Passages

Click or tap a single passage cardto select it. You can select multiple passage cards by holding the Shift or Control key while selecting a particular passage. To deselect while keeping the rest of your selection intact, Shift- or Control-click it.

If you are using a mouse, you can drag with the left mouse button beginning in an empty part of the map to create a rectangular selection. Hold down the Shift or Control key while doing so to add passages to an existing selection.

To select all passages, choose Select All from the Passage top toolbar tab.

To deselect all passages, click in an empty part of the map.

Moving Passages

To move passage cards you've selected, drag them to a new place using the left mouse button or finger.

By default, Twine will snap passage cards to the gridlines of the story map. If you'd like to disable this behavior, choose Details from the Story top toolbar tab and uncheck the Snap to Grid checkbox. This setting is specific to each story in your library, so one story can use grid snapping while another doesn't.

Grid snapping only affects passage cards when you move them. It doesn't affect the existing position of cards.

Editing Passages

To edit a passage, select it and choose Edit from the Passage top toolbar tab. If you're using a mouse, you can also double-click a passage to edit it. This will open a dialog where you can make changes to the passage.

Most of the passage edit dialog is taken up by a text area where you can enter text that the player will see when playing your story. To be more precise, the text you enter will be rendered by the story format when your story is played. For instance, you might enter code into your passage to set variables or conditionally display some text.

The font and size of the text can be customized in Twine's preferences. This doesn't change what the passage looks like when played; it just lets you make the text editor more comfortable to use.

Story formats can extend Twine to add syntax formatting to the passage text editor. For example, links might appear in a blue color. You'll need to consult the documentation for your story format as to what these colors mean. You can also disable syntax coloring by disabling story format extensions.

Twine automatically saves your changes to a passage after you stop typing for a moment.

Leading and Trailing Space in Passage Names

If a passage has leading or trailing spaces in its name (like " Hello" or "Goodbye "), then Twine will show placeholder symbols in the passage edit dialog name that look like ␣. These symbols are shown so that you can distinguish between passages that have these spaces and those that don't. In other words, Twine treats a passage named "Hello" and one named "Hello " as two unrelated passages. (And usually, you will want to give your passages names that don't differ by just spaces.)

These symbols are only visible in Twine, not when your story is played.

Editing Multiple Passages

If you edit a passage while another is open for editing, the new edit dialog will appear on top of the existing one. Twine will keep up to five passage edit dialogs open below the most recent one. If you open more than that, Twine will close the oldest passage edit dialog for you.

Click or tap a passage edit dialog in the background to bring it to the front, or select the close button in the dialog to close it.

If you have more than three passage edit dialogs open, Twine will overlap the oldest to save screen space. Point or tap on the overlapped dialogs to reveal them, and move your mouse away or tap elsewhere to restore them to their previous state.

As you enter text in a passage, Twine will detect when you've added new links. If the destination passage doesn't already exist, it will create an empty passage for you. Deleting the link will delete this empty passage.

Twine won't delete an empty passage while editing if any of the criteria below are true:

  • It is linked to from another passage
  • It has any tags
  • It has a different size than the default
  • It is the story start

Text Formatting, Code, Images, Sound, Video... Basically Everything Cool

You should consult the documentation of the story format you are using for how to include things like text formatting, code, or multimedia in your passages. All these things are possible, but the way you handle each one varies by story format.

The Passage Toolbar

At the top of the passage edit dialog is a toolbar that lets you make changes to other aspects of passage than its text.

  • Undo and Redo undo and redo changes you've made in the text editor only. Other kinds of changes can be undone using the top toolbar undo and redo buttons.
  • Tag adds tags to a passage.
  • Size changes the size of the passage's card in the map. A story format could change how your passage is displayed based on its size, but usually, this doesn't have any effect on the experience of playing the story.
  • Rename changes the name of the passage.
  • Start Story Here makes this passage the start passage for the story. If this button is disabled, it's because the passage is already the start passage.

The Tag Toolbar

Below the passage toolbar, any tags associated with the the passage are displayed. Each one appears like a sticker. Selecting a tag lets you either remove it or change its color. Changing a tag color will change it for all passages with that tag.

You can rename tags using the Passage Tags dialog.

Story Format Toolbars

Story formats can extend Twine's passage edit dialog to include a toolbar with functionality specific to the format. You should check the documentation for your story format for details on how it works.

If something goes wrong with a story format toolbar, Twine will hide it so that you can continue editing. Closing the dialog and re-opening it should bring back the format toolbar--assuming the problem was a transitory one.

Story format toolbars can be turned off permanently by disabling story format extensions.

Linking Passages

Because links are a fundamental part of Twine stories, the way they are written is shared across all story formats. In short, you create a link by placing two square brackets around text in a passage.

  • Writing [[A passage]] makes a link to a passage named "A passage".

  • Writing [[A label->A passage]] also makes a link to a passage named "A passage", but the text that is displayed onscreen is "A label".

  • You can also reverse the arrow direction and write [[A passage<-A label]], which has the same exact effect as the previous example.

Passage links are case-sensitive. That is, a link to a passage named "A passage" will be treated differently from a link to a passage named "A PASSAGE".

Passage links are represented with a solid line ending in an arrow in the story map. A passage that links to itself shows a circular arrow. Story formats can extend Twine to add references. You should check your story format's documentation to find out how they work. You can also disable story format extensions to prevent these lines from being drawn.

When you create a new link while writing in the passage edit dialog, Twine will automatically create a passage for you with the correct name after a short delay, if it doesn't already exist in your story.

Twine also tries to detect when you're starting to write a link and opens a list of possible completions. To accept a passage name in the completion list, click or tap it. If the suggestions don't include what you want, or if you're creating a link to a new passage, keep typing and the completions list will disappear.

If you change your mind about a passage name, you don't need to manually edit links in other passages. When you rename a passage, Twine will update links to passages for you. It won't, however, update any references to a passage that use story format-specific functionality, like code.

It's possible to use more than plain text as the trigger for a link, but how this works is dependent on the story format you are using. It's often possible, for example, to enter an HTML <img> tag in the label part of a link. But this may or may not be supported by the story format you are using.

Deleting Passages

To delete passages, select them in the map and choose Delete from the Passage top toolbar tab. You can also press the Backspace or Delete key as a shortcut.

Deleting passages can be undone using the buttons in the corner of the top toolbar. (So can almost all actions in the Story Map screen, but because deleting stories is permanent, it's worth calling out here.)

Tagging Passages

Passages can be tagged just like stories, and in a similar fashion, passage tags mostly exist to help you organize your story. Passage tags don't typically change a passage's behavior when played, but often story formats make tags accessible to code you write. As example, you could change the appearance of your story when the player reaches a passage tagged night. You should consult your story format's documentation for details on how this works.

If a tag is assigned a color, a stripe of that color will appear at the top of each passage card that has that tag. Tags will also be listed in a passage edit dialog regardless of color.

Adding Tags

To add a tag to a passage, edit it and choose the Tag button.

Renaming Tags and Changing the Color of Tags

To rename a passage tag, choose Passage Tags from the Story top toolbar tab. In this dialog, you can rename a tag or change its color.

The color of an an individual tag can also be changed in the passage edit dialog of a passage that has that tag.

Removing Tags

To remove a tag from a passage, edit it, then select the tag you want to remove. Finally, choose Remove from the

Finding and Replacing Text

Searching for and replacing passage text is done through the Find and Replace dialog, which you can open by choosing Find and Replace from the Story top toolbar tab.

When you enter text into the Find text field, Twine will highlight the cards of passages containing that text. You'll also see a numeric count of matching passages in the corner of the Find and Replace dialog.

To replace text you're searching for, enter the replacement in the Replace field and select Replace In All Passages.

Focusing Searches

The Include Passage Names checkbox controls both whether text matches are highlighted for passage names, and whether text replacements are done in passage names.

The Match Case checkbox controls whether text matches are case-sensitive. When it's on, text must be the exact case of what you enter in the Find field for it to be considered a match.

The Use Regular Expressions checkbox controls whether Twine uses the JavaScript regular expression parser to both find and replace text. Regular expressions are a way to specify text patterns. For example, the regular expression .and matches both 'hand' and 'band'.

Regular expressions have a detailed syntax all their own. Mozilla Developer Network has a good introduction to the topic.

If you use regular expressions in your search, the Replace field can also contain backreferences. For example, if you enter (.)and in the Find field and $1--- in the Replace field, the text Sand band will be replaced to S--- b---.

Renaming a Story

To rename a story from the Story Map screen, choose Rename from the Story top toolbar. The only restriction on story names is that they must be unique among your library.

You can also rename a story in the Story Library screen.

Changing the Story Format

To change a story's story format, choose Details from the Story top toolbar tab. There's a menu in the dialog that opens that allows you to set a different format.

Story formats must be installed in Twine before they appear in this menu.

Viewing Story Statistics

To see statistics Twine collects about your story, choose Details from the Story top toolbar tab. This shows:

  • The number of characters and words in all of your passage text.
  • The number of passages in your story.
  • The number of links and broken links in your story.
  • When you story was last changed.
  • The IFID of your story.

IFIDs are akin to ISBNs for books. They help catalog Twine stories alongside other forms of interactive fiction. You can learn more about IFIDs at the Interactive Fiction Database.

Editing Story JavaScript and CSS

Twine allows you to add both JavaScript and CSS (short for Cascading Stylesheets) to your stories. This code allows you to customize the behavior and appearance of your story when it's played, but the exact details of how to do this depend on which story format you're using. You should read your story format's documentation for more information on how this works.

JS and CSS are both web standards, and accordingly there are many online resources that can teach you how to use them. The Mozilla Developer Network, for example, has CSS and JS learning areas which contain gentle tutorials on both these technologies.

To edit a story's CSS, choose Stylesheet from the Story top toolbar tab. To edit a story's JavaScript, choose JavaScript from the Story top toolbar tab. Like passage edit dialogs, these dialogs automatically save changes a moment after you stop typing.

Publishing Your Work

Although it is possible to play a story from inside Twine, most of the time you'll want to publish it in a standalone form. This section describes how to prepare a story so that it can be shared with a broader audience.

Testing a Story

While you're editing a story, you can see a preview of what it will look like in published form by testing it. When testing a story, many story formats will show additional information to help you debug problems. You should look at the documentation for the story format you're using for more information on what is available during testing mode.

Testing a story in browser Twine will open a new browser tab with the story. App Twine will open the story in your default web browser. You can test a story multiple times at once.

Testing a Story From the Beginning

You can test a story from its start passage from either the Story Library or Story Map screen.

  • In the Story Library screen, select the story, then choose Test from the Build top toolbar tab.
  • In the Story Map screen, choose Test from the Build top toolbar tab.

Testing a Story From a Specific Passage

You can temporarily override a story's start passage to fine-tune a specific part of your story. But keep in mind that this makes your story act as though the passage you've chosen is truly its first. If there is setup work done in your story's start passage, your story may not behave correctly if you test from a later point.

You can only test from a specific passage in the Story Map screen. Select a passage card, then choose Test From Here from the Passage top toolbar tab.

Proofing a Story

Proofing a story uses a special story format that is designed to make proofreading and copyediting the text of your passages easier. You can proof a story from both the Story Library and Story Map screens.

  • In the Story Library screen, select the story, then choose Proof from the Build top toolbar tab.
  • In the Story Map screen, choose Proof from the Build top toolbar tab.

The story format that's used for proofing is set in Twine's Story Format screen.

Playing a Story

Twine allows you to play a story . This can be helpful if you'd like someone to play your story on your own computer before publishing it, or to see exactly what people will see when playing your story once it's published.

You can play a story from both the Story Library and Story Map screens.

  • In the Story Library screen, select the story, then choose Play from the Build top toolbar tab.
  • In the Story Map screen, choose Play from the Build top toolbar tab.

The address you see in your web browser while playing a game launched from Twine will only work for you and your computer. It will not work for other people. To share your story with other people, you will need to publish it.

Publishing a Story

Publishing a story creates an HTML file that can opened in a web browser.

You can publish a story from both the Story Library and Story Map screens.

  • In the Story Library screen, select the story, then choose Publish to File from the Build top toolbar tab.
  • In the Story Map screen, choose Publish to File from the Build top toolbar tab.

Twine will then ask you to choose a file name and location to save your published file.

Some versions of the Safari web browser may instead open a browser tab with an address that begins with blob://. If this happens, choose Save As from Safari's File menu to save your story to a file.

Now That I Have a Published File, What Do I Do?

The short answer is that you can publish your story anywhere an HTML file can be published. You could send this directly to people using email or publish it to a web site. Some cloud file hosting services might allow you to publish your file in a web-accessible form, but many limit this functionality so that a story can only be downloaded by viewers, not directly played in a brwoser.

Two services that offer Twine-specific hosting are Borogove and Itch.io. Itch is more of a marketplace, while Borogove is more closely aligned with the interactive fiction community.

Managing Story Formats

Although Twine comes with several story formats, it's also possible to add others that people have published themselves, and to customize which format you'd like to use for new projects.

Viewing Story Formats

To view a list of story formats installed in your version of Twine, choose Story Formats from the Twine top toolbar tab. By default, the Story Formats screen will show you the newest version of every story format you have installed. Each card in the Story Formats screen represents a single format that's installed. This list shows both regular story formats and proofing ones together, and is sorted alphabetically by name.

Story formats that come installed with Twine have a sticker on them labeled "Built In." The default story format has a sticker on it labeled "Used as Default," and the format that's used for proofing stories has a "Used for Proofing" sticker.

If Twine isn't able to load a story format, it will show an error symbol on its card with a short explanation of the error it encountered.

To view only story formats you've added yourself, choose User-Added Story Formats from the View top toolbar tab.

To view all formats, including older versions of story formats, choose All Story Formats from the View top toolbar tab.

Changing the Default Story Format

To change the default story format, select its card in the Story Formats screen and choose Use as Default Format from the Story Format top toolbar tab. A "Used as Default" sticker will appear on the card to confirm the change. If the Use As Default button is disabled, the format you've selected is already the default format, or the format you've selected is for proofing. (In that case, you probably want to set it as your proofing format instead.)

Changing the default story format doesn't affect stories you've already created, only new ones you create in the future. You can change the story format for existing stories in the Story Map screen.

Changing the Proofing Format

To change the proofing format, select its card in the Story Formats screen and choose Use to Proof Stories from the Story Format top toolbar tab. A "Used for Proofing" sticker will appear on the card to confirm the change. If the Use to Proof Stories button is disabled, the format you've selected is already the proofing format, or the format you've selected is not a proofing format. (In that case, you probably want to set it as your default format instead.)

Adding a Story Format

To add a story format, you'll need to know its address. A story format should include this in its documentation. A story format address must be a URL, with a prefix like https:// in front of it.

Once you know your story format's address, choose Add from the Story Format top toolbar tab and enter it in the dialog that appears. If Twine is able to load the story format from the address you've entered, it will show a preview of the format name and version you're adding. Choose Add in the dialog to add it. It'll appear in the list of story format cards immediately. You can now either set it as the default story format or change individual stories to use it, if you like.

Removing a Story Format

To remove a story format, select its card in the Story Format screen and choose Remove from the Story Format top toolbar tab. If this button is disabled, you've selected a format that is built-in, or is currently your default or proofing story format.

If a story uses a story format you've removed, you'll need to change it to another format. Twine will also notice this problem the next time you start it and repair your story so that it uses the closest story format version available.

Disabling Story Format Extensions

Story formats can extend Twine by adding:

  • References between passages, which appear as dotted lines connecting passages in the Story Map screen
  • A toolbar in passage edit dialogs
  • Syntax coloring in passage edit dialogs

If these extensions are buggy or you just prefer not to use them, you can disable them. Select the story format card in the Story Format screen and choose Disable Editor Extensions from the Story Format top toolbar tab. To reverse this change, select the same card and choose Enable Editor Extensions from the Story Format top toolbar tab.

Disabling extensions disables all extensions for a format. You can't disable just the toolbar, for example, but not a format's references or syntax coloring.

How Twine Manages Story Format Versions

Generally, how Twine manages multiple versions of a story format isn't something most users need to be concerned with. But it can affect people who are developing story formats or those using an older version of a story format.

Twine expects story formats to follow semantic versioning. Semantic versioning assigns meanings to a series of three numbers separated by periods. What this means in the context of a story format is that:

  • The first number increases when the story format changes in any way that's not compatible with existing stories that use it.
  • The second number increases when the story format adds features in a way that is compatible with existing stories.
  • The third number increases when the story format fixes bugs in a way that is compatible with existing stories.

This has two effects that take place every time you start a session with Twine, either by opening the application or visiting the online version.

  • Twine removes versions of story formats that it considers outdated. That is, if both versions 2.1.0 and 2.0.0 of a format exist, it removes 2.0.0. If 3.0.0, 2.1.0, and 2.0.0 exist, it removes only 2.0.0.
  • Twine upgrades stories to the most up-to-date version of a story format that does not contain breaking changes. If a story uses version 2.0.0 of a format and 2.1.0 exists, it will change the story to use 2.1.0. If it uses 2.0.0 and both 3.0.0 and 2.1.0 exist, it will only upgrade the story to version 2.1.0. Changing the story from version 2.1.0 to 3.0.0 must be done manually.

Twine does both of these things to lessen the impact of story format updates, so that as upgrades are available, you don't need to take any action to be up-to-date. It's not possible to change or override this behavior.

Customizing Twine

This section describes how you can customize Twine to fit your needs.

Setting Preferences

To customize Twine's preferences, choose Preferences from the Twine top toolbar tab. This tab is available throughout Twine. A dialog will appear that lets you change settings. These changes will take effect as soon as you make them, and Twine will remember them between sessions.

Changing Twine's Language

To change the language Twine's user interface, select it from the Language menu in the preferences dialog.

Changing Twine's Theme

To change Twine's theme, select an option from the Theme menu. The Dark and Light settings cause Twine to always use that theme, while the System choice uses the theme that matches your system's theme setting, if Twine can determine it. If Twine can't determine whether your system is using a dark or light theme, it will default to a light theme.

Changing Dialogs

The Dialog Width menu controls the width of dialogs. The placement of dialogs onscreen (e.g. switching them from the right side of the window) cannot be changed.

Changing Edit Dialogs

The Blinking Cursor in Editors checkbox controls whether the cursor blinks in passage edit dialogs, the story JavaScript edit dialog, and the story stylesheet edit dialog. This preference only controls the cursor in the large text fields of these dialogs. Twine uses your system setting for cursor blinking in one-line text fields.

You can change the font and size used in passage edit dialogs and the stylesheet and JavaScript edit dialogs using the controls below the Blinking Cursor in Editors checkbox. (The Code Editor preferences apply to both the stylesheet and JavaScript edit dialogs.)

  • The System font setting uses the same font that your computer uses in the rest of its user interface.
  • The Monospaced font setting uses common monospace fonts across operating systems.
  • The Custom font setting allows you to specify any font that's installed in your computer. You must spell this font name exactly right, including any spaces or other symbols in the font name. Capitalization doesn't matter when setting a custom font.

Advanced Customization

CSS

App Twine allows advanced customization its interface by creating a special file, user.css, in your Twine folder. You'll need to create this file outside of Twine using a text editor.

If user.css exists, then app Twine will add the contents of it to the UI as CSS rules, potentially overriding the default styling. CSS allows changing the appearance of the application--using different fonts, for example, or colors--but does not allow changing Twine's functionality or adding new features.

Here's a sample user.css that replaces the graph paper background of the story map with a plain gray color:

.passage-map {
  background: hsl(0, 0%, 75%) !important;
}

[data-app-theme="dark"] .passage-map {
  background: hsl(0, 0%, 30%) !important;
}

user.css is only available in app Twine. If you'd like to customize browser Twine using CSS, browser extensions like Stylus might help.

Some important things to keep in mind working with user.css:

  • The structure of Twine's UI can and will change on every release, even for patch-level version changes. Because these changes are often numerous, they will not be part of release notes.
  • The file must named exactly user.css--all lowercase. User.css will not work.
  • Changes to user.css will take effect the next time you start Twine.
  • To determine what CSS selectors to use, you can either use developer tools in browser Twine--the DOM structure is identical between browser Twine and app Twine--or open developer tools in Twine itself by going to Troubleshooting under the Help menu, then choosing Show Debug Console.
  • You can use the in-app debug console to test your CSS rules. The rules you set in user.css will be listed as injected stylesheet in the developer console.
  • user.css must be at the same folder level as your Stories and Backups folders, directly below the Twine folder.
  • If there's a problem loading user.css, Twine will load as normal and not apply any customizations. If any of your CSS rules are incorrectly written, they will be ignored. Twine will not show a warning in any of these cases.
  • In order for user.css to win specificity, you might need to add !important to the end of your declarations.

Limitations

Twine, like any piece of software, isn't perfect. In this section, some limitations of Twine are described as well as possible ways to work around them.

Large Stories

Twine doesn't set any hard limit on how big a single story can be, whether on number of passages, amount of text, or number of links.

If you're using browser Twine, you are limited by the amount of storage space your browser allows Twine. You can see the amount of space available as a percentage in the corner of the Story Library screen.

If you're using app Twine, you're limited by the amount of space on your computer, but you're very unlikely to be limited by this in practice.

However, you may notice Twine slowing down while editing a large story. Exactly when this becomes evident depends on many things: how powerful your computer is, how large the Twine window onscreen is (drawing more of the Story Map screen at one time takes more resources, of course), how you've arranged your story, and more. As a result, it's hard to advise specific actions if you notice that Twine is sluggish with your story.

One possibility, though, is to split your story into multiple stories.

Combining Stories

Some authors like to split large stories into smaller, individual stories. However, Twine isn't able to combine these stories into one published file. Other people in the community have created tools to do this, though they require using a command-line interface.

These tools work with both Twine-created HTML files and plain text source code files, using a notation called Twee.

If you want to have multiple, separate story files that communicate with each other in some way--say, for an episodic game--then how you might do that is specific to the story format you are using, so check its documentation for details.

Collaborating on Stories

Twine doesn't offer a way for multiple people to edit a story at once. The most basic way to collaborate is to export a story and have your collaborators import it to work with it themselves.

Another possibility is to use source control to share your stories, but this means learning how to use software like Git. There are separate applications that can make working with these systems easier that might be worth investigating if you're not already familiar with them.

If you're using app Twine, using cloud storage services like Dropbox or Google Drive to sync your story library is not recommended. It is very easy for these services to get confused as to the state of your story files--they often try to merge changes from different sources together on your behalf--and cause your stories to become corrupted.

Using Images and Multimedia

Twine doesn't have facilities for managing images, sound, or video that you might want to include in your stories. To do this, you'll need to publish your story to a file and place that file in a folder with those multimedia files. The exact way to display or play multimedia in your story depends on the story format you're using, but in many cases you will need to use a relative URL to reference these external files.

  • If an image named orange.jpeg is in the same folder as your published story file, the relative URL of the file is just its name, orange.jpeg.
  • If an image named pear.png is in a folder named images at the same level as your published story file, the relative URL of the file is images/pear.png.

Unfortunately, you'll have to re-publish your story each time you want to preview it with the multimedia files.

It is possible to use Base64 encoding to embed multimedia directly into a Twine story, but this isn't recommended as it is difficult to work with and will make your stories much larger in size.

Working With Source Control

Because story files are HTML files, they can be tracked using source control software like Git. If you do track story files in source control, quit Twine before taking any actions that will cause the story files in your library to change, like pulling from a remote or merging branches.

Twine compresses the HTML of story files, which can make reading diffs of stories difficult. Converting your stories to the plain-text Twee format before checking them into a source code repository can help with this. Command-line tools like Tweego, Extwee, and twine-utils can do this for you.

Troubleshooting Problems

Sometimes things go wrong while working with Twine. This section contains advice on how to handle these situations.

Backups

The best way to prevent losing work in Twine is to back up your work regularly.

In App Twine

App Twine makes a backup copy of your work every time you start the application, and every 20 minutes while you are working. It creates a folder called Backups next to the story library folder. That is, if your story library folder is in Home › Documents › Twine › Stories, your backups are in Home › Documents › Twine › Backups.

You can also keep backups of your own by copying your story library folder, or individual stories, to another location.

In Browser Twine

You must keep backups yourself using the Archive feature.

What If I Forgot to Keep Backups And Thing Went Wrong?

You may not be completely out of luck.

In addition to automatic backups, app Twine saves a version of your story to temporary storage every time you test or play it inside the app. You might be able to recover it from there.

The easiest way to locate these temp files is to look in your browser history. Entries that start with file:/// are most likely what you're looking for. But you can also look in your temporary folder directly.

  • In Linux, look in either /tmp or /var/tmp.
  • In macOS, run this command in the Terminal app: open $TMPDIR
  • In Windows, enter %Temp% into the location bar of an Explorer window.

In these directories, look for files ending in .html. They will not have your story name in their title, though. Instead, they have a long string of random characters, like 7fd8be91-a6d1-459a-a955-b8628ee8e2c4.html. The only way to be sure is to open the files in a browser or check their creation date--it will match when the story was played or tested.

Viewing Local Storage Directly

This section only applies to browser Twine. It doesn't apply to the app version.

When things go wrong, it can be useful to get directly at the data Twine has stored in your browser. This data includes your stories, preferences, and installed story formats. You can view this data and even edit it using the developer tools built into most browsers.

The exact way to do it depends on the browser--here are instructions for some common ones:

Be careful when working with local storage, however. Just looking at what's in local storage, or copying and pasting out of it can't cause any harm. But adding even one stray extra character can cause Twine to be unable to read the data.

If An Error Message Appears While Editing

When Twine Can't Save Changes

Twine saves changes to your stories automatically. If it isn't able to save a change, it will show an alert dialog to warn you. If you see this warning, don't panic. Try making another small change to your story, like moving a passage slightly or typing a letter into a passage edit dialog. This will cause Twine to try to save your changes again. If another alert dialog doesn't appear, then you can continue working safely--whatever went wrong was most likely a transitory problem, and Twine was able to save your most recent change.

If you repeatedly see alert dialogs saying Twine wasn't able to save your work, stop working. Try publishing your story to a file using the Build top toolbar tab. If this is successful and has up-to-date content in it, restart Twine (either by quitting the application and re-opening it, or reloading Twine in your browser) and re-import the published story.

One common reason why saving a story fails in app Twine is that permissions are not correct on your story library folder, or individual story files.

  • Check that you are able to add a new file to this folder, like a plain text file. Try opening this file outside of Twine, editing it, and saving changes.
  • You might have accidentally opened a story file in another application which has locked the story file for its own use. Opening story files in web browsers shouldn't cause this problem, though.

When Twine Thinks Another Application Has Changed Your Story

App Twine keeps track of the last time it saved changes to your story. If it detects the file has changed since that time, it shows a warning dialog letting you know. (This warning will never appear in browser Twine.) This warning can happen if:

  • You have your story file open in another application and made changes to it externally.
  • You copy a story file into your story library folder while Twine is open, overwriting an existing one.
  • Some other application, like backup or cloud sync software, changed your story file in the background while you were editing. If you see this warning repeatedly, this is the most likely cause.

Twine offers two options in this situation.

  • Save the changes you made in Twine, overwriting the file in your story library folder. If you don't know why this warning appeared, this is the safest choice to make, and will allow you to continue editing in Twine. If you're concerned you might accidentally overwrite something you need, make a backup copy of the story file outside your story library folder before choosing this option.
  • Keep the file as it is and relaunch Twine. This will cause any pending change that hasn't been saved to be lost, but the change is likely to be very small, since Twine saves changes as you work.

If Twine Won't Start

If Twine shows an error message when first starting and immediately quits, it's most likely because it is having trouble loading either your preferences or stories. Twine tries its best to repair problems it finds in saved files at startup, but sometimes it's not successful.

There are a few steps you can take that may fix this problem:

  1. Reset your preferences.
  2. If you are using app Twine, remove all files from your story library folder. Add them back in one-by-one, launching Twine each time. If Twine won't start when you add back a story, that story is the source of the problem.
  3. Reinstall Twine.

Resetting Preferences in Browser Twine

To reset your preferences, you'll need to edit your browser local storage. Delete all local storage keys that begin with twine-prefs. Don't delete any other local storage keys. Your stories are also stored in local storage, so altering those parts of local storage can cause you to lose them.

Once you've deleted all preference-related keys, reload Twine. Twine will restore your preferences to their defaults and try to continue loading.

Resetting Preferences in App Twine

Your preferences are stored in a file named prefs.json. Its location depends on what operating system you're using.

  • On Linux, it's in ~/.config/Twine.
  • On macOS, it's in /Users/yourusername/Library/Application Support/Twine. The Library folder is normally hidden in the Finder. You can use the Go to Folder... menu item to go there, however.
  • On Windows, it's probably in C:\Users\yourusername\AppData\Roaming\Twine. The AppData folder is also normally hidden, but you can go to it by typing %AppData% into the location bar of an Explorer window.

To reset your preferences, delete the prefs.json file and re-open Twine. It will restore preferences to defaults and try to continue loading.

If Twine Lost Your Story

If All Stories Are Gone

If you are using browser Twine with Safari, one possible explanation is that, unfortunately, your browser may have erased your work if you haven't used Twine in a week.

You may have also accidentally deleted your stories by clearing your browser history or removing a profile from your browser.

To see what is left, open your browser local storage. Any stories will be listed with keys that start with twine-stories. Individual passages will be listed with keys that start with twine-passages. You may be able to recreate your work using this information.

Unfortunately, if you don't see anything in local storage, you will need to restore your work from a backup.

If app Twine doesn't show any stories, check the contents of your story library folder. If you see files there that Twine isn't showing, then there's something wrong with the files that is making Twine think that they are not story files. Try opening them in a plain text editor; if the problem is obvious, you might be able to edit them directly, or you might be able to recreate the story using this file. The underlying structure of these files is documented here.

If Only Some Stories Are Gone

This is most likely caused by Twine having trouble with some aspect of your story, for example if the HTML structure of your story file became damaged. If you see the file in your story library folder, try opening it in a plain text editor. As above, you might be able to edit the files directly and repair them, or recreate your story using them as a guide.

If Your Story Is Damaged

In some cases, a story might be visible in Twine but editing it shows things in a bad state: passages might be missing, put in odd locations, or have garbled text.

In some cases, solving this problem is as easy as quitting and re-opening app Twine or reloading browser Twine. When Twine first starts up, it checks your stories for possible problems and repairs them where it can.

But if restarting Twien doesn't help, you'll probably need to restore a backup version of your story.