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.

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

Browser Twine can be installed as a progressive web application (PWA). For information on how to do this, please check your browser's documentation. Using Twine as a PWA means that it will be available even when you don't have an network connection, but you should still keep regular backups, as PWAs are still subject to having their data being erased when clearing browsing data.

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.

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

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.

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.

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.

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 when 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 structure¹, 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.

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:

Choose Import from the Library top toolbar tab.
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.
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.
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.
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 published¹. 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.

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.

Colors for story tags are a local personalization. They are not included in builds or archive files to prevent accidentally overriding colors and organization in another library.

Changing the Library's Location

This page only applies to app Twine. In browser Twine, your story library is stored invisibly in your browser's storage.

You can change the folder of your story library by choosing Set Story Library Folder... from the Twine menu. The folder you choose here will take effect the next time you launch Twine.

If Twine isn't able to read files in the story library folder you've set when it's starting up, it will show a dialog box where you can choose to either use the default folder location or quit the application.

You can also change the story library location using a command-line switch.

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

The Story Start

The story's start passage is drawn in the map with a green rocket icon connected to it.¹ 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.

Broken Links

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

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.

The idea behind the icon is that it represents where the story 'lifts off.'

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.

Automatically-Created Links

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.

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.

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.

Renaming Links

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.

Image-Based Links

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 from the application. 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. The file name you choose doesn't affect the name of your story in its published form. In other words, if you publish a story named "My Best Story" in your library to a file named my-worst-story.html, the story will still show its title as "My Best Story" in a web browser. If you'd like to change the name of your story in its published form, rename it before publishing.

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.

The Scratch Folder

This page only applies to app Twine.

When you choose to test, play, or proof a Twine story, app Twine creates a file and opens it in your web browser. This file is created in your scratch folder. By default, this is a folder named Scratch inside your Twine folder.

When you quit app Twine, it cleans up your scratch folder, deleting files that are more than three days old. (This delay is so that you can continue to view your work after quitting Twine, and in an emergency, potentially recover your work.) However, you can delete files in the scratch folder on your own. Files in the scratch folder are only meant to be used for viewing your work in a browser. Twine will never put anything in the scratch folder that isn't meant to be short-lived.

Twine's Scratch folder behavior can customized using command-line switches.

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.

Command-Line Switches

This page only applies to app Twine.

In addition to preferences you set through Twine's user interface, you can customize app Twine's behavior through command-line switches. These change Twine's behavior in only the session you launch with these switches. They don't change preferences you have set using other methods.

Setting Command-Line Switches

The way you set command-line switches depends on what operating system you use.

Linux

These are set in the command that launches Twine. If you are launching Twine via a terminal session, you'd add them to that command. If you are launching it using a desktop environment like Gnome or KDE, check to documentation for your desktop environment for directions.

macOS

There are two ways to accomplish this:

Launch Twine using the Terminal application and add the switches to the end of the command launching Twine. You will need to invoke the Twine executable directly, like this:

/Applications/Twine.app/Contents/MacOS/Twine --switch --switch2

Create an AppleScript that runs the command for you. See this StackOverflow post for details.

Windows

There are two ways to do this:

Launch Twine using the Command Prompt or Console application. Add switches to the end of the command launching Twine, like this:

C:\Program Files\Twine\Twine.exe --switch --switch2

Edit the shortcut that you use to launch Twine, or create a new one. Add command-line switches to the end of the Target field of the shortcut dialog, following the example above.

Although some applications on Windows use / to start command-line switches, Twine doesn't. It uses --, the same as on other operating systems.

A Reminder About Spaces and Pathnames

Many command line switches used by Twine set pathnames for folders. If a folder in the path you want to set contains a space, you must put quotation marks around the entire path, like so:

‑‑scratchFolderPath="C:\Users\Jane Doe\twine-scratch"

Backup Folder Switches

`--backupFolderPath=[path]`

Example: ‑‑backupFolderPath=/Users/janedoe/twine-backups/

This sets the full pathname of the backup folder to use. Twine will create this folder if it doesn't already exist. If Twine isn't able to do this, or isn't able to read the files in this folder, it will show an error message whenever it tries to save a backup of your story library.

Never set your backup folder to a folder that has files created by other applications in it. Twine can't distinguish between backups it created and any other files, and will delete them permanently when they become too old.

Graphics Switches

`--disableHardwareAcceleration=[true or false]`

Example: ‑‑disableHardwareAcceleration=true

This disables hardware accelerated graphics in Twine. This should only be needed if you experience visual glitches in Twine. Disabling hardware acceleration will likely make Twine less performant in general.

Story Library Folder Switches

`--storyLibraryFolderPath=[path]`

Example: ‑‑storyLibraryFolderPath=/Users/janedoe/twine-stories/

This sets the full pathname of the story library. For example, ‑‑storyLibraryFolderPath=/Users/janedoe/twine-stories. Twine will create this folder if it doesn't already exist. If Twine isn't able to do this, or it isn't able to read the files in this folder, it will show a dialog box where you can choose to either use the default folder instead, or to quit the app.

Scratch Folder Switches

You can use a different location as your scratch folder, or change the length of time Twine keeps files around for in the scratch folder. For example, if your main storage volume is a solid state drive and you'd like to avoid writing to it, you can use a different volume.

`--scratchFolderPath=[path]`

Example: ‑‑scratchFolderPath=/tmp/twine-scratch

This sets the full pathname of the scratch folder to use. If this folder doesn't already exist, Twine will try to create it. If Twine is unable to create the folder at the path you've set, it will show an error message when you play, test, or proof a story.

Never set your scratch folder to a folder that has files created by other applications in it. Twine can't distinguish between files it created and any other files, and will delete them permanently when they become too old.

`--scratchFileCleanupAge=[number]`

Example: ‑‑scratchFileCleanupAge=60

This sets how old a file must be before Twine deletes it from the scratch folder, in minutes. Twine considers the last time the file was modified, not when it was created, when deciding whether to keep the file. To have Twine delete all files from the scratch folder every time you quit it, set ‑‑scratchFileCleanupAge=0.

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. By default, 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.

The location of your backup folder can be set using a command-line switch.

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 creates files in the scratch folder. Files in this folder are created when you play, test, or proof a story. You may be able to recover your work from files here.

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

This page only applies to app Twine.

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:

Reset your preferences.
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.
Reinstall Twine.

Getting More Detail on Startup Problems

Twine logs information as it starts up and works that is not normally visible. If you're having problems, though, these logs might tell you more about the source of the problem. To see them, you'll need to start Twine from the command line. Once you've started Twine from the command line, you'll see Twine's logs in that window.

Linux

How to do this depends on the distribution of Linux you use. In a desktop environment, you will need to start a terminal session. Gnome and KDE have apps (called "Gnome Terminal" and "Konsole") to do this.

Once you've started a terminal session, you'll need to run Twine from wherever it was installed. Unfortunately, this varies by distribution as well.

MacOS

Open your Applications folder, then the Utilities folder. Open Terminal in this folder, then type the following into the window that appears and press the Enter key:

/Applications/Twine.app/Contents/MacOS/Twine

Windows

Open the Start menu, then run the Command Prompt application. This will open a window. After it's opened, open the Start menu again and locate Twine, but right-click on it instead of opening the entry. Choose the Open file location option from the context menu. This will open a folder containing the Twine icon. Right-click this icon and choose Copy as path from the context menu.

Finally, go back to the Command Prompt window and right-click inside the window. This will paste the location of Twine into the window. If you've copied the path correctly, what you have pasted should end with Twine.exe. Don't edit what was pasted; only press the Enter key to launch 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 Twine doesn't help, you'll probably need to restore a backup version of your story.

If You See Visual Glitches in Twine

This page only applies to app Twine.

If you see visual glitches often in Twine, turning off hardware accleration may help. You should only do this if you are seeing a problem. As the name implies, using hardware acceleration speeds up Twine's display.

To do this, go to Troubleshooting under the Help menu, then choose Disable Hardware Acceleration. This item will be checked when hardware acceleration is disabled, but changing the setting will only take effect the next time you launch Twine.

You can also disable hardware acceleration with a command-line switch.

Release Notes

Over its lifetime, Twine has seen many updates. This section collects the descriptions of the published updates, called "release notes," on nearly every version.

2.9 versions

2.9.2

Release Date: July 28, 2024

Bugs Fixed

Browser Twine works in HTTP (e.g. nonsecure) contexts again. 2.9.1 introduced a change that broke this.
The layout of the preferences dialog is a little nicer.

Story Format Updates

Chapbook has been updated to version 2.2.0.
SugarCube has been updated to version 2.37.3.

2.9.1

Release Date: July 21, 2024

Bugs Fixed

Importing a story in browser Twine that replaces an existing one no longer creates duplicate stories.

Behind the Scenes

Many libraries used by Twine have been updated, and some which have been superceded by built-in browser functionality have been removed.

Story Format Updates

SugarCube has been updated to version 2.37.0.

2.9.0

Release Date: June 16, 2024

New Features Added

Browser Twine can now be installed as a progressive web application (PWA). This is an early feature and bugs may exist with it. Please bear in mind that although PWAs allow for use offline, backups are still important to keep, as their data may be deleted when clearing browsing data.
A data-tag attribute is added to passage cards in the story map, which can be targeted using custom CSS. It otherwise doesn't have any effect in the story map.

Bugs Fixed

The story library now sorts correctly by date.
An error in the Italian localization has been fixed.

Story Format Updates

Chapbook has been updated to version 2.1.0.
Harlowe has been updated to version 3.3.9.

Twine 2.8.1

Release Date: January 3, 2024

Bugs Fixed

Duplicating a story in browser Twine correctly copies passages. (Previously, passages were moved to the duplicate story.) This bug only occurred in browser Twine.
A typo in the French localization was corrected (thanks Flavien Robert).

Story Format Updates

Harlowe has been updated to version 3.3.8.

Documentation

Release notes for Twine are now part of the reference, where you're hopefully reading them now! The reference includes all known release notes for Twine, going all the way back to 2009. Thanks to the Twine Cookbook editors and Dan Cox in particular.

Twine 2.8.0

Release Date: November 27, 2023

New Features Added

In App Twine only:
- The location of the story library can be changed. It can be done either using a menu item preference or command-line switch.
- Hardware accelerated graphics can be disabled. It can be done either using a menu item preference or command-line switch.
- The location of story library backups can be changed. This can only be done using a command-line switch. Please read the documentation carefully before using this option.
- Instead of using the system-wide temporary directory, Twine now uses a dedicated scratch folder and prunes old files from it automatically. The location of this folder can be changed using a command-line switch only. Please read the documentation carefully before using this option.
A Korean localization has been added.

Bugs Fixed

An issue where clicking rapidly on a passage and then dragging it would cause the passage to move incorrectly has been fixed.
An issue where closing a passage editor while the find dialog was open caused a crash has been fixed.
A typo in the Finnish localization has been fixed.

Behind the Scenes

The app now uses Vite for bundling instead of create-react-app.
The underlying Electron framework for the desktop app has been updated to version 26.

Twine 2.7.1

Release Date: August 27, 2023

Bugs Fixed

Fixed a bug where maximizing a passage editor made it disappear.

Story Format Updates

Harlowe has been updated to version 3.3.7.

Twine 2.7.0

Release Date: July 8, 2023

New Features Added

Passage edit dialogs now show leading and trailing whitespace in passage names as `␣`` symbols, to help tracking down accidental spaces.
The app version of Twine now supports customizing its UI via a user.css file. More info on how this works is in the reference.
The zoom controls in the story map have been moved into the top toolbar, so that the amount of space in the story map is increased.

Bugs Fixed

JavaScript and CSS edit dialogs receive the right amount of vertical space when open in conjunction with passage editors.

Story Format Updates

Harlowe has been updated to version 3.3.6.

Twine 2.6.2

Release Date: February 26, 2023

New Features Added

The "Start Story Here" checkbox in passage edit dialogs has been replaced with "Test from Here".

Story Format Updates

Chapbook has been updated to version 1.2.3.
Harlowe has been updated to version 3.3.5.

Twine 2.6.1

Release Notes: February 5, 2023

New Features Added

The Dutch translation has been updated.

Bugs Fixed

Fixed a bug where passages would appear empty on the map when they weren't.
The Go To Passage dialog now receives mouse events properly.
Matches in the Find and Replace dialog should no longer flicker when other changes occur in a story.
The macOS app is now both signed and notarized, and should not require a right-click to open 🤞 .
Fixed a bug in Twee import where leading or trailing spaces in a passage name were not preserved.

Twine 2.6.0

Release Date: January 8, 2023

This is likely to be the last app version of Twine for 32-bit Linux. Electron 18, which this release is based on, appears to be the last version of Electron to support 32-bit Linux, and it reached end-of-support in September 2022. Support for 64-bit Linux should not change.

New Features and Improvements

When a second passage edit dialog is opened after one is already open, the new dialog appears on top of the existing one, forming a stack. A passage edit dialog can be brought to the front by clicking its title bar. There is a maximum of 5 passage edit dialogs in the background; opening more will cause the lowest to be closed.
Twine can now import and export Twee files. Twee is a plain-text format used by many other tools in the Twine community, and has a tech spec. Twine exports to Twee 3 format and can import either Twee 3 or older versions.
Added a Go To button to the story map toolbar, which allows moving to a passage by name.
If there are no conflicts when importing a file, then Twine now automatically completes the import without asking for further confirmation.
If a dialog is already open when it would have normally been opened (like choosing to open Preferences twice), the existing dialog will animate to draw attention to itself, instead of nothing happening.
Added a Ukrainian localization, and updated the Chinese, German, and Turkish localizations.
The Mac app is now signed, thanks to the Interactive Fiction Technology Foundation. This means that running Twine on Macs no longer should require right-clicking it and choosing Open the first time it's downloaded.
- The relationship between Twine and IFTF has not changed. Although IFTF provides support for the Twine community, Twine itself is an entity independent of the IFTF.

Bugs Fixed

Fixed a problem where dragging the story map and moving the cursor outside the Twine window would cause inappropriate scrolling.
Fixed a broken link explaining what a story format is.
Fixed a bug with importing stories that were missing some attributes. collapsed.
Fixed the appearance of passage edit dialogs that had been maximized, but also

Story Format Updates

Harlowe has been updated to version 3.3.4.

Twine 2.5.0

Release Date: August 27, 2022

New Features and Improvements

Passages considered "empty" now show with a translucent background. To be considered empty, a passage must satisfy all of the criteria below:
- Has no text, not even just whitespace
- Has no tags
- Is the default size (small)
- Is not the start passage of the story
If the last link to an empty passage is removed, an empty passage will be deleted.
- This behavior is somewhat provisional, and constructive feedback is appreciated. The goal of this change is to address issues where typing links could create many extraneous passages, and to generally help keep stories from being cluttered with unused passages.
Dialogs may now be maximized.
The width of dialogs can now be customized in the Preferences dialog.
If playing, testing, or publishing a story to file fails, an error message is now shown. Previously, it failed silently.
The Delete Passages button now disables if the start passage in the story is selected.
Portuguese and French translations have been improved (thanks @albuquezi and @Kln95130).

Features Removed

Middle-clicking the story map no longer creates a passage. It falls back to the default behavior instead, usually allowing the user to scroll around the story map.

Bugs Fixed

Entering an invalid regular expression in the Find and Replace text no longer crashes Twine. It now reports no matches.
Replacing a story during an import now correctly links passages to their parent story. This bug manifested as an inability to select passages, edit them in some cases, and other similar problems.
Padding on the story map has been adjusted so that dialogs no longer overlap passages on the right.
If the list of story tags or stories to import is too long to fit the window height, the list scrolls properly.
Portuguese and Chinese localizations now load correctly.
If an incorrect story format URL is entered when adding a new story format, an error is shown correctly. Previously, it showed placeholder text.
The Mac app is now ad hoc signed, so users on Apple Silicon should not see repeated permissions prompts when the app launches--only one, the first time it runs.
The app icon on Windows has been enlarged.

Story Format Updates

Harlowe has been updated to 3.3.2.

Twine 2.4.1

Release Date: July 13, 2022

New Features and Improvements

The German localization has been improved (thanks @JimB16). Updated the version of Electron used for app Twine to the latest v17 release.

Bugs Fixed

Fixed a bug related to updating stories' story formats. This showed up in 2.4.0 as a crash message the first time a story was edited.

Browser Twine now uses the Storage Manager API to determine how much space is left for Twine to use. You may see a change in the value reported from previous versions, which estimated it by trying to save increasingly large amounts of data until it failed. This should fix error messages seen in 2.4.0 like Failed to execute 'setItem' on 'Storage': Setting the value of 'twine-passages-abcdef-ghijklmn' exceeded the quota.

Backups work properly in app Twine.

Documentation

A section on how to switch to an older version of Twine has been added.
Small proofreading corrections (thanks @ChapelR).

Story Formats

Harlowe is updated to 3.3.1. (changelog)

Known Issues

Editing passage links, especially if you type [[and]] and then write a passage name, can create extraneous passages as you type, depending on how fast you type. An improvement on this behavior should come in the next feature release (there may be further bugfix releases before then).

Twine 2.4.0

Release Date: July 5, 2022

General UI Updates

There's now a toolbar that appears at the top of the screen for all actions. The toolbar's separated into tabs, similar to a menu bar, and has a back button allowing navigation between screens.

The system font is used instead of a custom one. This is mostly an aesthetic change, but it also helps with non-Latin text.

Some actions, like changing preferences or editing story formats, are available regardless of where you are in the app.

The desktop app now has an ARM Linux build, and the macOS app is universal, running on both Intel and Apple Silicon processors natively.

The desktop app has a new icon.

The Story List

You now select a story from the list and then take an action on it using the toolbar instead of using a gear menu. Double-clicking a story will edit it.

Stories can now be tagged, and the story list can be filtered to show only certain tags. Just like passage tags, story tags can have colors associated with them.

Story previews have been updated to look hopefully nicer.

The Story Format List

By default, only the most up-to-date version of a story format is shown in the list. You can see all installed formats using the View top toolbar tab.

The Story Map

You can now undo and redo changes.

You can now edit multiple passages at one time.

You can rename a passage without editing it.

You can now delete more than one passage at a time.

All detail dialogs, like the find & replace text dialog, are now modeless, meaning that you can do other work in your story while they're open.

You can customize the font used in passage editors and disable cursor blinking.

Story formats now have an official way to extend the editor. (The Harlowe story format used undocumented methods to do this in the past.) Story formats can add syntax highlighting to passage editors, a toolbar of actions to passage editors, and add additional connections between passages in the map.

Right now, Harlowe and Chapbook have extensions but other story formats may add them in the future.
You can disable story format extensions if they are causing trouble or you prefer not to use them.
If you're a story format developer, learn how extensions work here. Editing larger stories is faster.

Story Formats

Harlowe 3.3.0 is included, and release notes are here.

Chapbook 1.2.2 is also included. It's the same as the last version, 1.2.1, except for the addition of editor extensions.

Twine 2.3.16

Release Date: January 9, 2022

This is a maintenance release for Twine 2.3.

Features added

Updated SugarCube to 2.36.1.

Twine 2.3.15

Release Date: October 21, 2021

This is a maintenance release for Twine 2.3.

Features added

Updated Harlowe to 3.2.3.

Twine 2.3.14

Release Date: May 11, 2021

This is a maintenance release for Twine 2.3.

Features added

Updated Harlowe to 3.2.2.

Bugs fixed

Removed a conflict between JavaScript polyfills provided by core-js and Harlowe.

Twine 2.3.13

Release Date: February 15, 2021

This is a maintenance release for Twine 2.3.

Features added

Includes a corrected version of Chapbook 1.2.1 that includes testing functionality.

Twine 2.3.12

Release Date: January 24, 2021

This is a maintenance release for Twine 2.3.

Features added

Updated SugarCube to version 2.34.1.
Removed the "Reload" menu item in desktop app versions which could cause data loss.

Twine 2.3.11

Release Date: January 17, 2021

This is a maintenance release for Twine 2.3.

Features added

Updates Harlowe to version 3.2.1.
Updates Chapbook to version 1.2.1.

Twine 2.3.11

Release Date: January 17, 2021

This is a maintenance release for Twine 2.3.

Features added

Updates Harlowe to version 3.2.1.
Updates Chapbook to version 1.2.1.

Twine 2.3.10

Release Date: January 3, 2021

This is a maintenance release for Twine 2.3.

Features added

Updated Harlowe to version 3.2.0.

Twine 2.3.9

Release Date: July 12, 2020

This is a maintenance release for Twine 2.3.

Features added

Fixed a bug with story renaming in the app version.
Updated Chapbook to version 1.2.0.
Fixed a bug with story color selection in the story list.

Twine 2.3.8

Release Date: May 10, 2020

This is a maintenance release for Twine 2.3.

Features added

The colors used for syntax coloring in the CSS and JavaScript editors now have an improved contrast ratio.
On iOS, Twine now prompts to be added to the home screen, which will prevent story data from being automatically deleted after 7 days of inactivity.
Updated Chapbook to the latest version, 1.1.0.

Twine 2.3.7

Release Date: April 12, 2020

This is a maintenance release for Twine 2.3.

Features added

Updated version of SugarCube story format, 2.31.1.

Twine 2.3.6

Release Date: March 30, 2020

This release is only for the web based version. It adds a warning for users of Safari 13.1 and beyond that their story library is at risk, and they should use a different platform. See this Webkit blog post under the "7-Day Cap on All Script-Writeable Storage" heading for technical details.

Twine 2.3.5

Release Date: October 7, 2019

This is a maintenance release for Twine 2.3.

Features added

The built-in version of SugarCube has been upgraded to 2.30.0.
Added Slovenian and Japanese localizations.

Bugs fixed

A bug where extra blank lines were added to story JavaScript and CSS when importing a story has been fixed.
A bug where story formats would load incorrectly in the format dialog or story format chooser has been fixed.

Twine 2.3.4

Release Date: September 22, 2019

This is a maintenance release for Twine 2.3.

Features added

Added Chapbook 1.0.0, a new story format.
Upgraded Harlowe to 3.1.0.
Upgraded Snowman to 1.4.0 and 2.0.0 respectively.
Upgraded SugarCube to 2.29.0.
Added Ukrainian localization (thanks to uk123ua).

Twine 2.3.3

Release Date: July 22, 2019

Bugs fixed

Proofing stories, broken in 2.3.2, is working again.
In previous versions, pressing control- or command-Z immediately after opening a text editor (passage, JavaScript, or stylesheet) would cause all text to be erased. This behavior no longer occurs.
The German localization has been improved (thanks to Kai Brueckers).

Features added

Added a Catalan localization (thanks to Jordi Mallach).
Added a Norwegian localization (thanks to sinwes).

Twine 2.3.2

Release Date: June 10, 2019

Bugs fixed

Various issues related to playing and testing stories within Twine have been resolved. Twine now opens playable versions of stories in your default browser instead of inside Twine.
An error where the editor UI became unresponsive after adding a new passage has been fixed.
Story formats with additional build information in their version number (e.g. "1.0.0-beta1") are now correctly handled.
Extraneous story saving, occurring when a passage was clicked but otherwise not moved or edited, has been removed.
The link to report a bug has been corrected to point to GitHub instead of the previous repository.

Features added

Twine supports dark mode in macOS at a basic level. The window frame will change to match the system appearance, but you must still use the toggle in the story list to change theme. This may happen automatically in a future release.

Twine 2.3.1

Release Date: April 21, 2019

Bugs fixed

In the desktop app, file saving is done in a safer manner so that if a problem occurs, any file that would have been overwritten should stay intact.
The desktop app now keeps short-term backups of your story library in case a bug occurs that affects the data on disk. It saves a backup copy of your library to a Backups folder in the main Twine folder when you first start it up, and every 20 minutes while Twine is running. It only keeps 10 backups at most, deleting older ones as needed, so this is not a full-fledged backup solution (and is not intended to be). It is intended as a way to restore data in the event of a crash or bug that overwrites data saved on disk.
The Chinese localization that should have appeared in 2.3.0 is in this version.

Features added

Harlowe has been updated to version 3.0.2.

Twine 2.3.0

Release Date: April 14, 2019

Features added

The desktop app now uses Electron instead of NW.js. This should resolve many crash issues, and also bring improved performance, as saving changes is now done on a separate processing thread than the main user interface.
The files in the story directory are now published as full-fledged stories, where possible.
Bahasa Malaysia and Russian have been added as locale choices.
Harlowe has been updated to 3.0.1.
SugarCube has been updated to 2.28.2.

Bugs fixed

Issues with passages being placed in strange places after being dragged while Snap to Grid is turned on have been fixed.
If you have a test or play version of a story already open when you choose to test or play it again, the window or tab should update with the current version.
The welcome screen now scrolls properly when the Next button is used.

Twine 2.2.1

Release Date: December 20, 2017

Bugfixes

Last modified dates on stories in the desktop app are maintained correctly.
Publishing stories with colored tags now works correctly.
Publishing stories correctly prefers an HTML version of the story, instead of a ZIP archive (used with iOS only).

Twine 2.2.0

Release Date: December 14, 2017

Features

Passages can now be wide, tall, or just plain large.
Tags can be assigned colors, which show up as a vertical stripe on a passage in the story map. Every tag doesn't need to have a color.
You can now press the plus and minus keys to change the zoom level of the story map.
A Turkish localization has been added thanks to H. Utku Maden.
A number of extraneous libraries have been removed, so the overall file size of the app has been decreased, and it should load faster.
The built-in SugarCube story format has been updated to 2.21.0.
The built-in Harlowe story format has been updated to 2.1.0.

Bugfixes

When you zoom in and out, Twine does a better job of keeping the window centered where you were looking.
The zoom level you last set for a story is now remembered by Twine.
If for some reason a story format can't be loaded, you can still delete it.
The desktop app is more tolerant of story files that it has trouble importing at startup -- it keeps going, so you at least can get to the story list.
If the desktop app does run into problems on startup, it shows the error message it should; previously, it would show a blank white page.

Twine 2.1.3

Release Date: May 1, 2017

Bugfixes

An issue causing passages to disappear, be positioned incorrectly, or otherwise become corrupted has been fixed.
Problems causing the search and replace dialog to not work correctly have been fixed.

Twine 2.1.2

Release Date: April 29, 2017

If you are upgrading and using a non-English localization, this will cause your stories to be saved to a slightly different folder than before. Instead of Twine -> Stories, they will now be saved to Twine -> [the word "Stories" as translated to your language]. You will probably need to move your existing stories into this new folder.

Features

Increased the display density of passages at the medium zoom level.
The story list can now be sorted in reverse chronological and alphabetical order (thanks Thomas Michael Edwards).
Mac users can now create passages in the story editor with force touch (thanks Michael Savich).
You can now widen the passage, JavaScript, and stylesheet editor windows.
Revised syntax colors in the JavaScript and stylesheet editors to be more readable.
Includes SugarCube 2.16.0.
Includes Harlowe 1.2.4 and 2.0.1.

Bugfixes

When a new story format is added, stories that used an older version are automatically brought up-to-date. This bug would manifest as having no format initially selected in the Story Format dialog.
You cannot remove the default story format anymore. (Choose another one as default first.)
Issues with non-English localizations where stories would not save correctly, or would not save to the correct folder, have been fixed.
External links now do not cause a broken-link arrow to be drawn in the story editor.
Special characters (that have meaning in regular expressions) now are handled correctly when searching and replacing.
Fixed a bug where publishing a story from the story list wouldn't work.
Fixed a bug where clicking the modal dialog background would not save passage title changes.
Fixed a bug where clicking the modal dialog background would be treated as a confirmation in deletion modal dialogs.
It's now not possible to scroll the main window when a modal dialog is open.

Twine 2.1.1

Release Date: March 1, 2017

Features added

Added Czech, German, Italian, and Portuguese localizations.
Updated SugarCube to version 2.14.0.
Outdated story formats are now removed automatically.

Bugfixes

Improved numerous issues with touch-based devices and Internet Explorer 11 in the story editor.
Fixed issues with the quick search field in the story editor.
Fixed a bug where sometimes text would disappear in the desktop application.
Fixed a bug where the story directory sometimes would not be unlocked when quitting the desktop application.

Twine 2.1.0

Release Date: January 31, 2017

Upgrade Notes

This is a significant update from the 2.0 series. If you're upgrading, please read the notes below before beginning.

If you are upgrading, then making a backup copy of your stories folder is recommended. To do this, launch Twine 2.0 and choose Show Library from the Twine menu. Quit Twine, then make a copy of the folder that was revealed. (If you are using Linux and Show Library doesn't work, your stories folder is located in ~/Documents/Twine.

If you had added custom story formats previously, you'll need to re-add them after updating to this version. The process works exactly the same as before. Sorry for the inconvenience -- you will only need to do this once.

If you do not see any stories after upgrading, double-check your Twine directory by choosing Show Library from the Twine menu. Go up one level from here. You may see two directories: one called "Stories," and another named Stories in another language (hopefully your preferred, non-English one). Move the story files from Stories to the folder with the localized name and they should be back once you re-launch Twine.

If you would like to continue using 2.0.11 online, it is still available at https://twinery.org/2.0.11.

Features added

Streamlined look and feel.
The starting passage now shows a green rocket icon in the passage instead of being slightly bolder.
Passages with broken links now show an arrow ending in an X instead of an icon in the passage.
Added dark theme for late-night hypertexting.
Loading large stories is considerably faster.
It's now possible to have multiple versions of story formats installed.
Harlowe 2.0.0 is now available.
SugarCube 2.1.12 is now available.
You can now use the Chromium web debugger on stories you test inside Twine by right-clicking the window and choosing Inspect from the contextual menu.
You can now directly drag a story file onto the story list to import it.
The story format version is now recorded in a published story file.
You can now drag the story map by holding down the middle button of the mouse instead of the space bar.
You can zoom into the story map with the mouse wheel.
When dragging passages when snap-to-grid is turned on, the passages will reflect this.
If you import a story with the same name as an existing one, then Twine will prompt you if you'd like to replace it.
Danish, Italian, and Portuguese localizations have been added.

Bugfixes

Passages that link to themselves display a clearer arrow in the story map.
The gauge showing the remaining local storage space in the online version now works correctly.
It's no longer possible for passages to get pushed offscreen.
Renaming a story in the desktop app no longer creates duplicate files.
A typo in the German localization has been corrected.

Twine 2.0.11

Release Date: February 27, 2016

Features added

Includes new localizations for German and Finnish.
Updates the included version of Harlowe to 1.2.2.
Updates the included version of Snowman to 1.3.0.
Updates the included version of SugarCube to 1.3.4.

Bugfixes

Resolves several problems in 2.0.10 with Linux.
Improves link drawing of certain setter links.

Twine 2.0.10

Release Date: November 20, 2015

Editor

Twine 2.0.10 has the same changelog as 2.0.9, but it includes Harlowe 1.2.1, which fixes a problem with (else:) invocations.

Twine 2.0.9

Release Date: November 17, 2015

Editor

Features

Includes new localizations for Brazilian Portuguese, Danish, Dutch, French, and Russian.
Updates to CodeMirror 5.4.

Bugfixes

A bug where dragging multiple passages would cause them to jump around after the drag completed has been fixed.
A visual glitch where passage, JavaScript, and stylesheet editors appeared to have two scrollbars has been fixed.
The quick search highlight now updates properly after editing a passage.
Global variables set by the editor are now cleaned up, so that they won't interfere with story previews.
The passage editor now uses tabs consistently to indent, as opposed to a mix of spaces and tabs.
A bug where gray areas would be visible after changing the zoom level of a story map has been fixed.
When you change the start passage for a story, link connectors will correctly update based on its new width.
The OS X desktop app is now usable for all users, not just the one who installs it.
The Windows desktop app is better at finding the user's Documents folder.
Desktop apps should no longer complain about running out of space.
Handles importing story files that have no IFID gracefully.

Story Formats

Updates the included version of Harlowe to 1.2.
Updates the included version of Snowman to 1.2.
Updates the included version of SugarCube to 1.0.32.

Twine 2.0.8

Release Date: July 6, 2015

Features added

Fixes bug where < and > characters would be garbled in stories in the native app version has been fixed.
Updates Harlowe to version 1.1.1.

Twine 2.0.7

Release Date: July 4, 2015

Editor

Features

Twine is now internationalized, and includes a Spanish localization.
Importing files has been sped up, as well as the startup time of the local app.

Bugfixes

Fixes a bug where clicking links in a story generated from the Test and Play buttons would not work.
The local application now works properly on Windows 7 Enterprise.

Story Formats

Updates the included version of Harlowe to 1.1.
Updates the included version of Snowman to 1.1.

Twine 2.0.6

Release Date: May 31, 2015

Editor

Bugfixes

Properly includes SugarCube in local app versions.
Fixes a bug in 2.0.5 where clicking links in testing/play versions of stories did not work.

Known Bugs

When testing or playing a SugarCube story in an app version, sidebar links do not work.

Story Formats

Updates the remote URL of SugarCube to the latest.
Updates the included version of SugarCube in local app versions to 1.0.23.
Updates the included version of Snowman to 1.0.2.

Twine 2.0.5

Release Date: May 26, 2015

Editor

This is the first release in the 2.x series to offer native apps for desktop OSes.

There is a known bug with the version of SugarCube bundled with this release. As a workaround, use the Formats option on the right side of the story list and choose Add a New Format at the top.

Enter this address:

http://www.motoslave.net/sugarcube/1/twine2/format.js

This format should be called just "SugarCube", and is identical functionally to what is normally bundled.

Bugfixes

Fixed a bug where dragging a group of passages caused them to jump to odd locations after the drag.
Fixed a bug where passages would jump around after moving from the editor to the story list.
The first passage added to a story is always set as its starting point.
Better handling is done to recover gracefully when a story format fails to load.
In native app builds, the filenames for stories are stripped of any characters that might cause problems (i.e. slashes or colons).
New passages are now properly centered, regardless of zoom level.
A story with no starting point set now archives properly.

Features

New visual previews of stories in the list.
You can now rename, test, and duplicate a story from the list instead of having to edit it first.
When a passage is renamed, the editor makes its best effort to change links accordingly. This doesn't yet work if the passage is mentioned in a macro.
Added rudimentary autocomplete when typing links in the passage editor. This only works right now for links, not macro mentions; this may change in the future.
Deleting a passage now prompts the user that they're sure; holding the Shift key while clicking the delete icon bypasses this warning.
The grid snap has been made coarser.
Pressing Control-Shift-Alt-(or Option)-D in a native app build will open a debugger console.

Twine 2.0.4

Release Date: April 12, 2015

Editor

Bugfixes

The app no longer mistakenly reports an updated version is available immediately after updating.
If an error occurs within the library used to save stories, a notification is now shown to the user. Previously, notifications were only shown when an error happened within the Twine app itself.

Features

The tooltip for the story menu now shows the most recent date/time the story was saved.
The Story Statistics dialog is back, and now includes the IFID for a story.
Added experimental native app builds saving stories to the Documents folder, under Twine Stories.

Built-In Story Formats

Updated Snowman to version 1.0.1.

Twine 2.0.3

Release Date: February 13, 2015

Editor

Bugfixes

Trying to save a passage with a name that another one already has now shows an error message instead of losing work.
Newly-created passages now are numbered properly ("Untitled Passage 1", "Untitled Passage 2", etc.) This bug would also cause data loss.
Fix a bug with displaying search results when searching for text including \< and \>.
Using Enter to add tags works as many times as you like while editing a passage.
Publishing stories now works on Safari.
Fix problems with the story stylesheet and story JavaScript editor putting typed text far away from where the cursor appeared.
At medium zoom level, passage titles now use the entire space of the box instead of a single line.
Fix intermittent problems where link arrows or broken-link status of a passage would not update after editing.

Features

If you try to play a story but haven't set a starting point yet, you are now prompted to do so.
Window titles have been changed slightly to better distinguish editing a story from playing or testing it.
A warning appears if you try to navigate away from editing a passage (i.e. while changes may not have been saved yet).
New animations between the story list and editor.

Built-In Story Formats

No changes.

Twine 2.0.2

Release Notes: January 14, 2015

Editor

Bugfixes

The storage quota bar on the story list no longer causes slowdown on Chrome.
A progress spinner is shown while importing from a file.
After an import, the story list automatically updates.
Passages are prevented from being moved offscreen.
If a story is published to an already-existing window or tab, then a notification appears letting the user know that they should look over there for the updated output.
Story formats now timeout on loading at 10 seconds instead of 2.
User-added story formats may now be deleted.
[[]] is no longer considered a link (previously, a passage with an empty name would be created).
Date sorting in the story list now works properly.
If publishing a story fails, then an error notification is shown to the user (previously, this would die silently).
Clicking a button automatically hides any tooltips for it, to prevent it from blocking any popups from view.
Passage connectors now take border width into account (i.e. links drawn from the start passage show properly).

Features

Passage connector drawing during a drag has been sped up.
SugarCube has been added as a built-in format.
The browser's window title changes to match what the user is currently working on.

Built-In Story Formats

No changes.

Twine 2.0.1

Release date: December 31, 2014

Editor

Bugfixes

Story formats are now preserved during import (thanks Thomas Michael Edwards).
$$ and other esoteric-ish characters in passages are no longer inappropriately transformed during the publishing process (thanks Thomas Michael Edwards).
A bug where passage connections would sometimes not update with zoom level changes has been fixed.
A cosmetic issue with popup balloons is fixed.
The link to the Twine forum on the welcome page is fixed.

Features

The editor now checks for an updated version against http://twinery.org/latestversion/2.json once a day and informs users accordingly.
Passage connections are now drawn using SVG for improved performance.

Built-In Story Formats

Harlowe

Snowman

Now properly uses user-created stylesheets and JavaScript.

About Twine 1

Twine 1 was available only as a desktop app for Mac and Windows, and was written in Python (instead of JavaScript, which the current version is written in). As such, it doesn't have much in common with the 2.x release series.

Twine 1.4.3

Release Notes: January 1, 2022

Bugfixes/alterations

Development program

Story Map

Signficantly improved the performance of the story map, with minor improvements to numerous other features. Thanks to Richard Lake and Maarten ter Huurne for this.
Potentially fixed a crash involving dragging passages.
Fixed a bug where pasting passages would sometimes place them in incorrect positions.

Menus

Added an "Update StoryIncludes Links" menu option, allowing StoryIncludes passage availability to be manually refreshed. This menu item will be disabled if StoryIncludes isn't present.
Added Option-Command-F as an alternative 'exit fullscreen' key command.

StoryIncludes

Now, closing StorySettings will refresh the StoryIncludes links automatically.
Now, you can include a .tws which itself contains a StoryIncludes passage.

Passage editor

Pressing control-A while typing in the passage title box should now correctly select the title text.
If you highlight a link with separate link text and passage title (such as [[link text|passage]]) then press control-L, a new passage named "passage" (instead of "link text|passage") is created.
In the "create passages" prompt given when you close a passage containing red links, the 'cancel' button now correctly cancels closing the passage.

Importing

Fixed a bug where you couldn't import Twine HTML files which had tags written in uppercase.
Fixed a bug where Twine HTML files with storeArea <div>s with the attribute "hidden" couldn't be imported.
Changed the MIME-type of imported TTF font files from "application/x-font-ttf" to "application/font-sfnt", and added "format(truetype)" to the generated @font-face CSS, and made similar changes for OTF fonts.

Story formats

Now, Twine will continue instead of crashing if, during startup, the last opened story's format isn't available. Also, it will properly error and quit if zero story formats are available (which should be unlikely).
Changed the naming of custom story formats' Python files from [story format name]/[story format name].py to [story format name]/header.py, in order to fix the issue where if a user renames the story format's directory, the custom Header file will no longer be found. However, old story formats which still use [story format name].py should continue to work correctly.

Game engine

General

Fixed a missing Y in the "got itself in a mess" error message.
The storeArea's passage is now read using textContent instead of innerText, fixing a number of minor bugs involving consecutive whitespace in passages being truncated.

Syntax

Fixed a bug where the image syntax didn't work with images at external URLs.

Macros/Functions

Fixed a bug where variables saved via «remember» were unwittingly shared over all Twine stories accessed from the same website.
Fixed a bug in Jonah where certain internal link

Twine 1.4.2

Release date: June 2, 2014

Bugfixes

Development program

Fatal errors

Now, building games in non-English locales should no longer get an encoding error caused by the built file's timestamp. Thanks to mth for assistance and Cab for the report.

StoryIncludes

The Story___ passages are no longer forbidden from being included via StoryIncludes.
The StoryIncludes passage is no longer broken on OS X.

Importing

Fixed buggy HTML importing for passages that have > symbols in their titles.
It is now possible to import from HTML files that use the SugarCube custom header.
Fixed imported images having the wrong MIME-type if their filename extensions were in all-caps (such as "tree.JPG").
Altered the MIME-type of imported fonts in ttf and otf format to "application/x-font-..." instead of "application/font-...". Also, unrecognised files are now "application/octet-stream". This shouldn't really change anything, but may improve browser support.

Story Map

The position of passages created by right-clicking and selecting "New Passage Here" should be fixed.
Fixed passage names with full stops no longer failing to have incoming link arrows.
Selecting "New Passage" when a Start passage is missing no longer creates the "Start" passage, since it could be irritating for "partial .tws files" that are being used in a large StoryIncludes project.

Passage editor

Passages with very long names no longer have the left half of their name scrolled out of the title text box when you initially edit them.
The passage editor now has a uniform tab width (set to 4 spaces).
Fixed a bug where HTML wouldn't be highlighted if its tag names or attribute names contained hyphens (e.g. <div data-tags="...">)

Game engine

General

Built HTML files now have a UTF-8 byte-order mark. This should cause Dropbox to correctly transmit them with UTF-8 encoding instead of ASCII. Hooray!!
Fixed certain page elements (such as StoryTitle and StoryAuthor) not being drawn at the start of a test play build that begins at a non-Start passage.
Fixed the image preloader code, which didn't detect whitespace correctly, and thus prevented preloading images in HTML <img> tags that had a space between "src" and "=".

Syntax

You should now be able to put a ] character inside the link syntax (e.g. [[<<$obj[0].x>>|Passage name]]) and put a quoted ">>" inside the macro syntax (e.g. <<print "<<--cool-->>" >> ).
Shorthand [<<display>>](<>): variable default was causing $vars provided as arguments to mess up horridly. This should fix this.
Raw HTML entities (such as or < or somesuch) are now correctly preserved, rather than being converted to their symbols during the build process.

Macros/Functions

Using Passage() instead of passage() in your code will no longer silently fail instead of producing an error message.
<<choice>>, <<button>> and <<textinput>> no longer incorrectly convert Twine operators in the text of the provided link to Javascript operators (e.g. <<choice [[not]]>> becoming <<choice [[!]]>>).
The undocumented clone() function has been updated to hopefully allow certain native objects to be cloned more effectively.
A number of macro error messages are a little clearer - displaying "$" instead of state.history[0].variables." when referring to the macro invocation.
Fixed a bug where certain objects were being passed by reference when used in a setter link - e.g. [[Link][$a = $obj]] caused $a and $obj to point to the same object, with changes to one altering the other.
Fixed a bug where object literals as shorthand <<display>> arguments wouldn't work at all.
Fixed a bug where multi-line string or object literals in <<set>> or <<print>> macros, etc., would not have Twine operators converted by Wikifier.parse() correctly.

History/Back Button

Game history: Added a test for iOS Safari's private browsing mode, which does not disable sessionStorage but does reduce its quota to 0
making it hard to tell if it's actually usable. This causes the "couldn't save the state" alert to not pop up if you're playing in private mode.
The story state serialisation functions have been rewritten to allow basic Javascript functions stored in Twine variables to be decompiled and stored. Previously, using the Sugarcane back button or a bookmark would cause function variables to lose their value. (Of course, this relies on function decompilation, so bound functions and native functions' serialisation will silently fail. And, when recompiling them, their original scope is lost.)

Internals/Scripts

Added Array.prototype.forEach(), Object.create() and Array.isArray() polyfills to the engine, allowing IE 8-compliant scripts to use them.
The engine now records the previous value of window.onerror, and restores it once the message has been displayed once.

New features

Development program

General

Added StoryInit, a special passage in which to put Twine macros that you want to run before every play - including Test Plays of specific passages. This is generally a more ideal place to put your initial <<set>> macros instead of the Start passage. Thanks to T. M. Edwards for pioneering this feature.

Error checking

Added a very basic passage code error-checking system. When closing a passage, Twine will now report a few possible errors: not matching an <<if>> macro with an <<endif>>, using "=" instead of "is" in the <<if>> macro, misspelling "http://" in a link, and putting HTML <script> tags in a script passage. (Less obvious errors can only be identified by your browser's Javascript engine, and will, as usual, only be identified at runtime.)
Also, when closing a passage, Twine will now offer to create new passages for each red link in the passage text. This potentially saves you having to create them yourself.
Also, when closing a passage, Twine will now offer to import all images, linked from URLs, into the story, and update the [img] references to match. Importing images is recommended because it saves you the bother of hosting the image files, keeps the story from breaking if your image hosting site is down, and allows you to host the HTML file on sites such as http://philome.la, which only allow single HTML files to be uploaded.
All of the above checks and helpers can be run from the "Verify All Passages" menu item in the Build menu, or the "Verify Passage" item in the passage editor's Passage menu.

StoryIncludes

Twine now tries to keep track of passages that aren't present in the file, but are included via the StoryIncludes feature (henceforth, "included passages"). Links to included passages are now mauve, and passages that link to included passages now have a mauve marker drawn on them in the Story Map.

Story Metadata

Added a "metadata" option to the Story Menu, which lets you edit some data that is included in the final HTML file.
The "identity" specifies a noun to use for game interface dialog boxes (the restart confirmation, the error dialog, etc.) If left blank, then "game" will be used.
The "description" provides text to use for a HTML <meta> description element, which is often used by search engines etc. to provide a summary of the page. I've noticed that often Google will, at a loss to find the game content, display odd bits of the storeArea div as a page description in its search results, which is most definitely not a good look. Maybe this will fix things.

StorySettings

Story Formats

Custom story formats can now supply a Python file, "header.py", which lets various parts of the Twine development program be customised to match the features of the story format. See the base header.py class, which your header.py file should subclass, for details.

Game engine

Syntax

You can now use the inline syntax as a shorthand for the <span class="..."> HTML tag.
@@.robot;This is a robot-class span@@ is equivalent to <span class="robot">This is a robot-class span</span>.
You can also use it alongside style attributes: @@.robot;text-decoration:underline;This is a robot-class span with an underline@@
One bothersome fact about Twine up to now is that there's no real "bridge" between the basic Twine link's functionality and raw HTML. There was no convenient way to make a raw <a> link trigger a passage change. So, I've added a "data-passage" HTML attribute that you can put on HTML <a>, <img>, <map> and <area> tags.
<a data-passage="Distant woods">Some text</a> is equivalent to %%[[Some text|Distant woods]]%%, but allows you to add extra HTML attributes to the link, like "style".
<img data-passage="Trees"> is equivalent to %%[img[Trees]]%% - thus, you can now refer to imported images in HTML. (If you wish to make an image that links to a passage, put the <img> inside an <a> element.)
<area data-passage="Trapdoor" coords="..."> is how you can make an image map area link to a passage.
You can also attach data-passage to any other kind of tag to make it serve as a link, too: <span data-passage="Secret link">This looks like ordinary text</span>.
To simulate setter-links, you can also add a "data-setter" property, too. <span data-passage="Cellar" data-setter="$teeth += 2">Collect teeth</span>. Note that it does nothing without a data-passage attribute as well.
It should now be possible to supply variables to the image syntax, as an image passage name or URL - for instance, [img[$pictureName]].
Removed the quote-by-line [[syntax]], on the basis that a good number of people don't really want indenting that often, and would rather have greater-than signs as bullet points. The rest can rely on the indented block syntax (%%<<<%%) or HTML <blockquote> tags.

Generated HTML

Passage links no longer have ID attributes that reveal the name of the passage they go to, allowing anyone to "cheat" by right clicking them and selecting "Inspect Element". This has been the case for every previous version of Twine, but not anymore!
Jonah: rewind links now have the class "toolbar-rewind" instead of "toolbar-rewind to here".

Default CSS

Mobile Sugarcane layout: I've added a somewhat rudimentary media query to Sugarcane that converts the sidebar to a vertical header, using a minimum of alterations, when viewed on a 640px-width

Twine 1.4.1

Release Date: January 11, 2014

Bugfixes

Bugfixes Development program

Potentially fixed the Windows VC++ runtime problem. If you haven't installed the VC++ 9 redistributable, the Twine installer should now correctly contain it.
Fixed «endnobr» consuming the three characters that come after it.
Fixed external link syntax highlighting.
Fixed syntax highlighting for shorthand «print» macros.
Fixed unmatched «endif» and «endsilently» macros not being syntax-highlighted red.
Removed the "Delete Passage" menu item in the Story menu, due to an identical entry being in the Edit menu.
External links and variable links are no longer considered broken links in the IDE.
Fixed annotation passages being drawn too dark in smooth drawing mode.
Fixed the monospace font using the normal font's size instead of its own. time. This should make HTML exporting/importing more symmetrical.
Improved speed of HTML importing.
The StorySettings passage is no longer converted to all-lowercase at build
Fixed an error when trying to replace a passage with one from animported file.
Now, the "no Start passage" warning is suppressed if a StoryIncludes passage is present.
Fixed importing from HTML sometimes failing to read passages correctly.

Bugfixes Game engine

Fixed passages with names containing quote marks being unrecognised by links.
Altered Sugarcane's browser state-saving to avoid a crash in Firefox caused by having lots of variables in your story.
Fixed HTML tables in passages not being constructed correctly.
Fixed TiddlyWiki emdashes not being rendered correctly.
Fixed the «nobr» macro inserting zero-width space characters into contained macro tags, thus breaking them.
Fixed bug preventing custom macros from being usable in StoryMenu etc.
Fixed the [img] syntax used in CSS stylesheets inserting a terminating semicolon, preventing further attributes from being used on the same line.
Added "vertical-align:bottom" to images to compensate for a line-height difference between XHTML Transitional and HTML5. Why is there a line-height difference? The person who can answer that is not on this Earth, but in Heaven.
Fixed the «nobr» macro not working if any text follows it.
Fixed «choice». Now, clicking a «choice» disables all .choice links in the passage, not just itself. This returns it to 1.3.5 behaviour.
Fixed variables used as array indexes not being parsed correctly.
Restored the left positioning of the Sugarcane sidebar.
Added support for "javascript:" and "data:" URIs in external links.
You can now use external links in the simple link syntax, such as [[http://example.net]].
Possibly broken pretty-links (as in, links with a separate link text and destination) are now no longer assumed to be external URIs unless they contain a protocol (like "http:"), or the symbols . / \ or #. This should make link debugging a bit easier.
Fixed the shorthand «display» macro tag's title sometimes being incorrectly parsed as its first argument.
Shorthand «display»: Attempting to access a parameter() that wasn't supplied make "variadic passages" (passages that can take multiple optional variables) will no longer throw an error, on the newly considered basis that it would difficult.
Fixed a bug where backslashes would be incorrectly converted to arbitrary letters if passage obfuscation was being used.
«back» now works better when Undo is off in Sugarcane. Previously it would mess up the variable state in cases when link variables were in use.
«back» and «return» now work when restoring a Jonah state via bookmark.
«back» also now works when clicked in a past Jonah passage - previously it would act as if it was in the present passage.
«back» now works in the StoryMenu, StoryAuthor, StoryTitle and StorySubtitle passages.
«choice» now produces an error message if it's used in the StoryMenu, StoryAuthor, StoryTitle and StorySubtitle passage.
Fixed Jonah scrolling in IE 8.
Now, only the StoryTitle passage's text content will be used for the window title, instead of its raw code.
Now, if a story has no StoryTitle, or the StoryTitle has no text content, it will default to the name of the .tws file used to build it, instead of just "Untitled Story".
Fixed a bug where putting "Lookup:" in the StorySettings could potentially crash the game.
Added a sanity check in case a script overrides History.prototype.display() but doesn't pass enough arguments (since in 1.4 it takes 4 arguments instead of 3).
Fixed HTML <table> structures in passages not being rendered correctly.

Additions

Additions to Development program

IDE tag colours now vary between shades of orange based on the hash of the tags, to help differentiate dissimilarly tagged passages from a distance.
Added a Preferences option for showing the faint connector arrows for image and stylesheet passages.
Passages displayed via the shorthand «display» syntax now result in connector arrows being drawn.

Additions to Game engine

The StoryMenu now auto-updates when you change passages!! The code is re-executed and re-rendered into the element. This means you could, say, «print» a variable inside it, and it would update automatically. (This change also applies to StoryAuthor, StoryTitle and StorySubtitle).
Added the tags() function, which takes one or more strings and returns an array of the tags of the given passage (or the current passage if no name is supplied).
Added passage(), which simply holds the name of the current passage (If a passage is being «display»ed by another, passage() is the name of the “topmost” passage.)
Added turns(), which provides the number of turns that have elapsed in the current game.
Added visitedTag(), which returns the number of times passages with the given tag have been visited. Provide multiple tags to only search for passages that contain both.
Added 'header' and 'footer' elements to Jonah's .passage elements, to provide a bit more symmetry with Sugarcane's DOM layout.
The CSS selector “:link” in stylesheets is now converted to [class*=Link] at runtime. This is to provide backwards-compatibility for people who used “a:link” to refer to Twine links (which is no longer usable as internal links no longer have href attributes). It's a mean sight of a hack, but so be it - I shan't be adding back the "javascript:void(0)" href no matter what you say.
Added the "visitedLink" class, which is applied to passage links that link to already visited passages. “:visited” is converted to “.visitedLink” much like the above. This provides a surprising amount of power - you can give .visitedLink “display:none”, for instance, to make links to all visited passages disappear automatically.
Re-implemented «textinput». It creates an <input> text element which, when a <button> element is pressed, sets the variable to its string contents. It may also have an additional parameter, a link expressed in link syntax, which is used to create a <button> next to it. Examples: <<textinput $name>>, <<textinput $name [[Submit|Next passage]]>>.
The previous 1.3.6 «textinput» behaviour of triggering the passage change via pressing the Enter key has been removed for now.
Added «radio». Its arguments are a variable, and a number of strings for each option. When a <button> is pressed, the label of the selected radio button is put into the variable. Example: <<radio $feel "Strongly agree" "Strongly disagree">>. If you have multiple «radio» macros that refer to the same variable, they're treated as part of the same set.
Added «checkbox». It's similar to «radio», having identical syntax - but it sets the variable to an array value containing all of the checked boxes' labels as strings. Example: <<checkbox $weapons "Pistol" "Newspaper" "Letter opener">>.
Added «button», a macro that takes a link as its argument and creates a <button> element. Use it for passages which use «radio» or «checkbox», or a «textinput» set. Example: <<button [[Let's go!|armoury]]>>
As a counterpart to the alert() raised when a script fails to load, window.onerror is now set to issue a one-time alert() signifying that a Javascript error has occurred during play. Feel free to contact me or use the forum if you find the message mystifying.
StoryMenu now honours the 'nobr' passage tag.
Built HTML files are now timestamped.
Upgraded the built-in jQuery module to version 1.11.
Changed Responsive's footer to a sticky footer, like God and all His hideous bat-faced angels originally intended.
Altered Responsive's CSS to make the body background easier to change.
Altered the CSS for all targets to make StoryMenu contents display better.
Individual script or stylesheet passages may request the inclusion of jQuery or Modernizr, overriding the StorySettings options, by including in their code the case-insensitive string "requires jQuery" or "requires Modernizr". This enables jQuery-using scripts or Modernizr-using CSS to be easily pasted into stories without requiring any other modifications to the story.

Twine 1.4.0

Release Date: December 10, 2013

Game engine

Syntax

You can now mix HTML tags and passage syntax in your story, without needing the <html> syntax. (It still remains for backwards-compatibility).
You can now use variables in place of a passage name in the link syntax - [[Exit|$placeName]] now creates a link to the passage whose name is in the $placeName variable. You can also do [[Back|previous()]] to replicate the <<back>> macro.
Also, you can write [[link text|passage name][$var = value]] to make a passage or external link that changes a variable when it's followed! The code section is treated as if it were arguments to a <<set>> macro. This syntax addition should work with <<choice>> macros (but not the [img] syntax). You can set multiple variables by separating them with a semicolon.
As a shorthand for <span style="...">, the TiddlyWiki inline style syntax is available. Type @@, then list CSS style attributes separated and terminated with semicolons, then put the passage text (including any other formatting and macros) ending with another @@. Example: @@font-size:2em; text-decoration: underline; Hello there!@@
Ending a line with \ will cause that line break to be removed from the rendered text. This can be useful when dealing with long chains of <<if>> macros.

Macros

<<remember>> now uses HTML5 Local Storage, which means it can now work even in an offline HTML file. Also, it can remember multiple variables given in a compound statement (like <<remember $a = 1, $b = 2>>).
Added <<forget>>, which undoes the effects of <<remember>>.
<<choice>> can now accept arguments phrased using the link syntax, e.g: <<choice [[a trapdoor?|falling]]>>. This saves the trouble of having to account for its inconsistent argument order.
<<nobr>> and <<endnobr>> remove all the line breaks in the text between them. They should be used instead of <<silently>> to enclose groups of macros.
The <<else if>> macro, which can also be written as <<elseif>>, allows you to essentially have multiple <<if>> macros chained together, without needing to nest each of them within the <<else>> / <<endif>> tag pair of the other.
You can also use variables in place of a passage name in <<display>>. For instance, <<display $name>> is now valid.

Shorthand macros

You can now write a shorthand form of <<print $variable>> like so: <<$variable>>. Note that this only works for printing just variables - not functions or anything else.
You can now write a shorthand form of <<display "Place">> like so: <<Place>>. Note that this only works for passages whose names do NOT contain spaces. Also, it can only be done with specific named passages - not variables or anything else.
You can supply additional arguments to the shorthand <<display>> macro - in effect, you can "call" passages as if they were macros. (Note: you cannot supply arguments to the longhand <<display>> because they will be interpreted as part of the passage name - for instance, <<display Cellar 2>> will try to display "Cellar 2" instead of "Cellar" with an argument of 2.)

Macro syntax/functions

You may now use "to" in macros instead of "=", and "is" instead of "eq". I think we can all agree it's too easy to confuse "=" with "eq", so you can instead write <<set $darts to 4>> for more readable code.
Strings containing 'and', 'or', '$' and other Twine operator symbols can be used inside macros without them changing into Javascript symbols.
Now you can put greater-than signs inside macro tags, such as <<set $arrow to "-->">>
All new variables are now 0 by default, regardless of whether you've <<set>> them or not.
Added either(), a function that randomly picks one of the things given to it.
Added visited(), a function that returns the number of times you've visited the given passage.
Added previous(), a function that returns the name of the previous passage visited.
If this passage is being included by a shorthand <<display>>, the parameter() function returns one of the space-separated terms in the macro invocation, parsed to a value. The function's argument is a zero-based index - parameter() or parameter(0) returns the first parameter, parameter(1) the second, and so forth.

Macro coding

setTransitionCSS() replaces the contents of the #transitionCSS <script> element with the passed string. This allows you to completely override the default transition CSS without it cascading down. I'm offering this as a JS function because many transitions will also require some extra JS, and being able to provide the complete transition code in just a script is desirable.
prerender and postrender are new objects whose function properties are executed every time the passage is rendered. The functions added to them take one argument: the resultant .passage .content element. Their 'this' value is the Passage object being rendered.

Passage tags

An alternative Tag CSS approach! Now, taking a stylesheet passage and adding an extra tag to it (in addition to "stylesheet") will cause that stylesheet to only be applied for passages with that given tag. (This, I feel, is a bit tidier than the old Tag CSS method - the [data-tags] selector need not be repeated dozens of times in a stylesheet, and applying only to the 'body' or '.passage' selectors. Although, it is slightly less flexible w/r/t tag hierarchies - the :not[data-tags] selector can't really be replicated.)
Twine now uses CSS transitions for passages appearing and disappearing. Giving a stylesheet passage the tag "transition" will cause that stylesheet to replace the default "fade-in" transition CSS, letting you define your own transition without having to override the other one's properties.
The special "nobr" passage tag removes line breaks from the whole passage.

StorySettings

The StorySettings passage enables a number of special story options to be set.

Undo: enables the player to "undo moves". In Sugarcane, this means being able to use the Back button in the browser. In Jonah, this means being able to use the "Rewind to here" link, and being able to click links in previous passages.
Bookmark: enables the player to use the "Bookmark" link in Sugarcane and Jonah. On by default.
Obfuscate: obfuscates the story's HTML source to prevent people from spoiling themselves by reading it. Off by default.
jQuery: set this on if you are using custom scripts that rely on the jQuery library. Otherwise, leave off. Note: Twine 1.4 relinquishes control of the "$" variable, so jQuery can now use it without $.noConflict().
Modernizr: set this on if you are using custom scripts that rely on the Modernizr library. Otherwise, leave off.

Jonah

All passages are now added to the bottom, regardless of where you click the link.
Clicking a link that leads to a previously displayed passage will display a new version of the passage at the bottom, instead of scrolling up to the old version.
Clicking a link in a past passage in Jonah now rewinds the game state to that passage before following the link. This gives the author a greater level of control over the game state - it's no longer possible to re-use old links from earlier in the story that no longer make sense in the current context. (Note: Switching off the "Undo" StorySetting disables all links in past passages.)
<<back>> is now usable in Jonah. When used in Jonah, a <<back>> link removes the contained passage, plus any prior passages (as given by the "steps" argument or a passage name argument).

Sugarcane

Removed the "Share" menu.
The "Rewind" menu is only visible if any passage has been tagged with 'bookmark'.
Added a "Bookmark" menu item, which produces a link to the current passage.
HTML5 History is now used to control the browser's Back and Forward buttons, and the <<back>> and <<return>> macros, in Sugarcane. This means that several bugs related to these are now fixed, and they should now work alongside random macros, player-input macros, and other such things.
<<choice>> is now usable in Sugarcane. It now creates a link that can only be clicked once in the whole story.
The sidebar now has position:absolute instead of position:fixed.

CSS / HTML

Added a <noscript> tag to alert the reader that Javascript is off.
Made it so that raw HTML <a> links in stories are styled as if they were proper externalLinks, in case the author unwittingly used the former in ignorance of the latter (a not uncommon occurence).
The passage content element, formerly classed "body" in Jonah and "content" in Sugarcane, now has a class of "body content" to match legacy CSS for both.

Development program

Visual

Special passages (Start, StoryAuthor, stylesheets, etc.) have different-coloured title bars. I've tried to stick with earthy hues in keeping with the colour scheme of the Twine icon, with redder hues used for stylesheet and script passages.
Passage tags are displayed in a peach ribbon along the bottom of the passage box.
Annotation passages are non-playable passages tagged with "annotation" that hold text to display on the story map, to annotate, comment or document the source code of the game. They have a different colour and size to normal passages.
Connection lines representing <<display>> macros are drawn with a bluer tint.
The position of newly created passages is much less arbitrary - passages will be placed closer to the expected area.
Altered the Greeking of zoomed-out passages to reflect the actual passage text length.
Selected passages now have their link arrows thickened to visually offset them.
Passage tooltips now display a preview of the passage's text (up to 840 characters).
Tagged stylesheets have arrows linking them and any passages with the same tag.

Importing/Exporting

Added "Import From Compiled HTML" option, letting the author recover passages from built games.
Importing .twee source code no longer discards all the passage tags in the imported passages.
The "Proofing Copy" export option renders a few more markup styles better.

Building

The "Test Play" menu item builds the game to a temp file, letting you run the story without having to have saved it to a specific filename first.
You can also right-click a passage and select "Test Play From Here" to start playing from that particular passage.
The "StoryIncludes" passage allows the passages inside other .tws or .twee files to be imported into this passage during building. If your game is particularly huge, you can divide it into a bunch of smaller .tws/.twee files, then add the filenames of these partial .tws/.twee files to one "main" file's StoryIncludes passage. All the passages in those files will then be copied into the main story at build time.
Added "Auto Build", a menu option that is only available when used with a StoryIncludes passage. If this is set, then when any one of those smaller .tws/.twee files is modified, the story is automatically rebuilt and can be tested in-browser. This requires both files to be open at the same time, though.

Passage editing

Passage titles must now be unique. The passage title input will turn red to indicate non-uniqueness.
Passage titles may no longer contain the | and ] symbols, due to such names being difficult to link.
Vastly improved the passage syntax highlighter.
Added very basic stylesheet CSS syntax highlighting.

Images and fonts

You can now add image files to the story file. These are stored as 'image passages' which can be included in passages using the image syntax: [img[imageName]] displays the image. Images are also embedded in the final HTML file, and don't need to be hosted elsewhere. Supported image file extensions are GIF, PNG, JPEG, SVG and WebP.
You can now embed font files, which can then be used in stylesheets, or, if you don't know CSS, the <font> element. Fonts are simply imported as stylesheet passages containing the font file in base64 encoding. Supported font file extensions are TTF, WOFF, OTF and SVG.

Twine 1.3.5

Release Date: November 22, 2009

Changes

I've just put out a new release of Twine, which I'm dubbing 1.3.5 because there aren't many new features to this one. Instead it has a number of bug fixes and optimizations -- in particular, you should see a significant speedup when working with large story files. This version also brings compatibility with OS X 10.6. I think it should work with earlier versions of OS X as well, but as always, I only have access to one version of OS X so let me know whether this is actually true.

Twine 1.3.0 / Twee 1.7.0

Release Date: October 10, 2009

Changes

Much faster story map updating, including an option to drop drawing quality for increased speed.
Syntax highlighting for passage editing, including different colors for broken links.
Several bug fixes, including one affecting the <<actions>> macro.

Twee 1.7 is pretty much the same as before, only with macro bugfixes.

Twine 1.2.0

Release Date: September 7, 2009

Changes

Links between passages are now shown as an arrow, with the source pointing to the destination.
Find and replace is now available, both in a passage editor window as well as global find/replace for a story.
The interface, especially for OS X users, has been polished. It now remembers your preferences as far as snapping to a grid and whether to show the toolbar.

It does fix two major bugs: one where Twine would save a story file to where it was last saved, even if you moved it after closing and re-opening Twine, and another where story files could not be opened on a different platform from where they were created. In order to make your story file cross-platform, you must re-save it after opening it in 1.2, and you also need to open it on the other platform in 1.2.

Twine 1.1.0 / Twee 1.6

Release Date: August 21, 2009

Changes

Twine 1.1 is purely a bugfix release; no new features have been added to the editor or to the Sugarcane template. It does include an update look for the Jonah template that brings its appearance more in line with Sugarcane. Twee 1.6 is identical to 1.5.1 except for the updated templates.

Twine 1.0.0

Release Date: June 29, 2009

Description

Twine is a GUI for creating stories with Twee. It allows you to map out your passages visually and see links between them. It also has a simple editor integrated with it that has a fullscreen mode, so you can use it to compose text as well. Finally, you can build to the same Sugarcane and Jonah templates as you have with other, existing tools.

About Tweebox

Tweebox was a predecessor to Twine that worked similarly to Tweego, extwee, and other command-line tools, but used a graphical interface instead. It also included a command-line version called twee. These release notes are archived here for historical reasons.

Tweebox 2.1.1

Release Date: February 17, 2009

Changes

I just put up Tweebox 2.1.1 for Windows, which is a bugfix release. If you ran into problems with 2.1, please give this a shot. An OS X version is also forthcoming.

If you do have Tweebox 2.1 already installed, please uninstall it before running the 2.1.1 installer. I haven't quite figured out how to configure the installer package I'm using for Windows to do updates.

Downloads, as always, are here: http://gimcrackd.com/etc/src/

Tweebox 2.1.0 / Twee 1.5

Release Date: January 11, 2009

Changes

Sugarcane template

I posted about this some time ago, while I was working on it. It's a new template that shows only one passage at a time, per the request of many, many people. You can see an example of a story in this template here: http://gimcrackd.com/etc/src/examplesugarcane.html

Proofing your text

Tweebox now has an option to generate a proofing copy of your story -- e.g. all your passages in RTF format. This makes it easy to give your work to a proofreader to look over; Tweebox now converts your source code to a more readable format. There's also a command-line tool to do this named toward.

Windows installer

The Windows version now has a proper installer/uninstaller.

You can download the new version here: http://gimcrackd.com/etc/src/

I haven't posted an OS X version of Tweebox 2.1 because I don't have access to a Mac right now. If you use a Mac and are comfortable installing wxPython (http://www.wxpython.org/download.php), please drop me an email.

Tweebox 2.0.0

Release Date: June 21, 2008

Changes

A new version of Tweebox has been long overdue, and since I haven't heard too many bug reports about the last pre-release I posted, I went ahead and released Tweebox 2.0. As I guess I mentioned a while back, it is now a desktop application that has both Windows and OS X flavors. It works more or less the same as the old Tweebox, only better (hopefully).

Tweebox 1.2.0

Release Date: January 6, 2008

Changes

Both Tweebox and twee now use Jonah 2, which features a new look, the ability for users to rewind a story to a previous decision point, and intelligent bookmarking. See http://code.google.com/p/twee/wiki/Jonah2Changes for a full explanation of changes.
twee now runs on Python, which means no extra software is required for use on Unix-based systems (e.g. OS X, Linux).

I've also revised and expanded the online help to cover common questions people have posted to the group:

http://gimcrackd.com/etc/doc/

Finally, if you are interested in extending Jonah, the API documentation has found a permanent home at:

http://gimcrackd.com/etc/api/

Tweebox 1.1.0

Release Date: January 15, 2007

Create your own interactive stories with Tweebox, the same tool used to produce the stories on this Web site. Write with your favorite word processor; build and test with a simple desktop application. It's easy and fun.

No Code Required

Tweebox uses a few simple notations to indicate how a story is structured. Two colons set off a new section of a story, and double brackets link them together. If you've ever edited a story on Wikipedia or another wiki, you're way ahead of the game. You don't need any programming skills to put together a story. (Check out an example source file and its playable version in the Jonah and Sugarcane formats.)

Free As In Free

Stories you create with Tweebox can be used however you'd like. Because the final output is a single, small Web page, you can easily email a story to friends, post it on your Web site, or even distribute it on a CD-ROM. (You could use a floppy disk just as easily — stories take up that little space.) You can also use your stories for commercial purposes without restriction.

Tweebox is free to download and use, and you can share it with anyone you like. You can even modify the Tweebox compiler, provided you release your own version under the GNU Public License.

Changes

Simpler, prettier graphical interface. All your project settings are on one page - no more tabs!
The online help has been updated to be easier to navigate.
Jonah has been compressed even more, so its starting code size is now 40k.
Jonah also has two new macros: remember, which stores values acrosspage loads, and silently, which lets you run many macros without having extraneous line breaks appear in your source code.

If you use Internet Explorer and haven't upgraded yet, I'd highly recommend it.

Tweebox 1.0.0

Release Date: December 7, 2006

Tweecode contains three tools: twee, creates HTML from Twee markup; untwee, creates Twee from HTML; and tiddlywiki.php,

The original code in Tweebox, twee, untwee, and tiddlywiki.php, are licensed under the GNU General Public License. The file zip.php comes from the phpMyAdmin project, and is used under the terms of the GPL. There are header files included with the Twee download that are derived from Jeremy Ruston's TiddlyWiki code, and as such fall under the BSD license. And finally, the default readme that comes with the iPod content that Twee produces is covered under the Creative Commons Attribution-ShareAlike 2.5 License.

Twee 1.0.0

Release Date: March 28, 2006

Description

Twee is a simple markup language for TiddlyWiki. It was invented when Chris Klimas accidentally spilled water on his laptop's trackpad, which knocked it out of commission temporarily. He wanted to continue to work on his TiddlyWiki and invented a markup language and command-line tool for this purpose.

Borrowing from TiddlyWiki, each section is named a tiddler. To create these in the Twee markup language, two colons are needed. This is followed by the name of the section and any tags in single opening and closing square brackets.

An example of Twee looks like the following:

:: Title [oneTag otherTag]

This is the title!

There are four required tiddlers:

SiteTitle
SiteSubtitle
DefaultTiddlers
MainMenu

To create a usable HTML file, the tool twee is used to convert the markup language into a playable text.