This is a collection of resources and tools for use with Twine, an "open-source tool for telling interactive, nonlinear stories." The name "Twine" can refer to several different things: one of two applications, the type of story or game you make (e.g., a "Twine game"), and it often refers to the entire ecosystem of compilers, story formats, and tools designed to make said stories.
Note
In this guide, when we refer to Twine, we will generally be talking about the entire ecosystem. If we mean the genre of IF that Twine produces, we will use the term "CYOA", and if we are talking about one of the Twine applications, we will say "Twine 1" or "Twine 2."
Tip
If you have or know of resources that you'd like to see in this guide, open an issue or a pull request. Note that this list is curated, so if the maintainers have reservations about a resource or if it does not appear to work, it will not be added.
- Compilers
- Story Formats
- Tooling
- Extensions and Libraries
- Guides, Examples, and References
- Communities
- Publishing Resources
A Twine compiler refers to a program that takes your raw code and metadata: passage names, tags, source code, etc, and compiles it with a story format to generate a Twine game. There are two main types of compilers: GUI compilers and CLI compilers. Most beginners may prefer to use GUI compilers, as they more readily reflect the way most users interact with their computers, but CLI compilers typically offer more options and flexibility. While some CLI compilers can process JavaScript, CSS, HTML, and even published or archived Twine 2 files, you will commonly use Twee notation with these compilers.
There are also two generations of Twine compilers and story formats. First generation Twine compilers typically only work with first generation story formats, and second generation compilers typically only work with second generation formats. However, there is at least one compiler and a handful of story formats that work across both generations.
Note
The term "generation" is, to my knowledge, an invention of this guide, not an official or widely accepted term.
| Generation | Compilers | Story Formats |
|---|---|---|
| 1 | Twine 1, Twee, Tweego | SugarCube, Sugarcane, Jonah, Snowman |
| 2 | Twine 2, Twee2, Extwee, Tweego | SugarCube, Snowman, Harlowe |
*Note: the above table is not exhaustive.
The currently maintained Twine GUI application. The recommended GUI compiler for most users. For second generation formats only.
The old, unmaintained Twine GUI. Only recommended for use with generation 2 formats that also support this compiler (e.g., SugarCube). The old formats that come with Twine 1 should no longer be used, especially for new projects. For first generation formats only.
A CLI compiler. Works with formats from either generation. The recommended CLI compiler for most users.
A node.js-powered CLI compiler made by the creator of Twine 2. For second generation formats only.
Another CLI compiler. Works with Twine 2-style formats. Has slightly better interoperability with Twine 2 thanks to allowing for positional notation in the passage metadata, but its particular brand of Twee notation is not supported by any other compilers or tools. For second generation formats only.
Another CLI compiler designed to work with second generation formats. Adheres to the Twee3 specification. For second generation formats only.
The original CLI compiler for Twee. No longer maintained and not recommended for use by anyone anymore. For first generation formats only.
A story format is the run-time engine for your Twine game. This choice is very important to how you'll approach development, what sort of features your game will have, and the way you'll write your code. A Twine compiler combines your source code, passages, and metadata with a story format to generate a complete, playable game.
The "core" formats are the ones included with the Twine 2 application. These formats are still developed by third parties, but are more widely used, and typically better maintained, than other formats. The core formats are SugarCube, Harlowe, Snowman, and Chapbook. When using any format, you should always use the most recent possible version; older versions of formats are only included for compatibility with on-going projects and are not intended for use with new stories or games.
SugarCube is a feature-rich, extensible, and simple story format. While in a few ways more complicated than Harlowe, SugarCube is still intended for beginners, but also comes with a variety of features and options for more advanced users as well. When choosing a format, SugarCube is hard to go wrong with. It may not always be the best fit, but it can always be adapted to work with whatever you have in mind.
Harlowe is a format designed for novices and is ideal for CYOA games with some dynamic content. If you want to build something more complex, like turn-based combat or inventory systems, Harlowe is generally not recommended. While simpler than SugarCube, Harlowe provides almost no options for extensibility; the core feature-set is largely all you have to work with. Harlowe is ideal for authors who aren't looking to learn a lot about programming and just want to make a game.
Snowman is essentially just a link markup parser, a markdown parser, and a templating engine, with a few nuts-and-bolts APIs built in to handle passages and such. It is aggressively minimal, requiring authors to build almost every bit of functionality they may need in JavaScript. Snowman requires a great deal of knowledge of JavaScript (and general web development) to get anywhere with. Even then, its thin feature set may still make it a poorer choice than the other core formats for many projects, even for developers with the know-how to make it work for them.
Chapbook is designed to be simple to use. Compared to the other formats, it has the smallest feature set and is the most opinionated format. Chapbook has some important limitations to consider, but if you can bend your ideas to fit its mold, it is probably the easiest format to learn. Even if you have relatively large ideas, Chapbook is extensible, and there are ways to circumvent most of its limitations. However, it's simply not ideal for more complex ideas and mechanics.
Twine 2 introduced the concept of "proofing" formats; story formats designed to create more readable copies of your source code for proofreading and editing. "Utility" formats are a related concept that sprung up in the wake of proofing formats--typically these formats output Twine stories to some other useful format--JSON or Twee, for example, but there are many that do other cool things.
The default proofing format is Paperthin; it just shows your Twine file as a simple list of passage names and passage source code. Some community developed proofing formats, like Illume arrived later. Examples of utility formats include Entwee and Enscree.
Many, many story formats exist. A catalogue of formats can be found here, courtesy of M. C. DeMarco. Many of these formats may not work, may be incomplete, or may not have ever been released, however. This list is probably not exhaustive, given that potentially thousands of bespoke and custom formats could exist across the web, just waiting to be discovered, but it is by far the best list of its kind.
The following is a list of some third-party, non-core story formats that have been confirmed to work and are actively maintained.
A Snowman-based story format that features stretch-text--that is, new passages are rendered below the old ones, rather than replacing them. By M. C. DeMarco.
Trialogue is a chat-style Twine Story Format based on Paloma, which is in turn based on Snowman.
Adventures is a custom story format for Twine 2 made by Longelwind that allows writers to add RPG elements such as health, items, golds and more to their story.
This Twine 2 story format allows one to use Twine to create Visual Novels for the Monogatari engine.
Entwee is a one-time-use story format for exporting a Twine 2 story into the old twee format, based on Michael McCollum’s similar story format, Entweedle. By M. C. DeMarco.
Enscree is a one-time-use story format for exporting a Twine 2 story into a MultiMarkdown format used for importing into Scrivener/Scree. By M. C. DeMarco.
DotGraph is a proofing format that uses a JavaScript implementation of Graphviz to automatically lay out a Twine story as a layered graph. By M. C. DeMarco.
Illume is a proofing format for Twine 2 that offers more functionality than a simple text dump. Its primary purpose is to provide an interface for reviewing and editing passages in a workflow that allows an author to easily have another person, even someone who does not use Twine, proofread and provide edits to a story.
Poof is a comment-based proofing format with a variety of utility features, like exports to Twee, PDF, and archive files.
!> DISCLOSURE: This resource was created by the primary author, maintainer, and curator of this guide.
"Tooling" is essentially any program or software that helps you make Twine stories that isn't a requirement (like a format or a compiler) and doesn't go on to become part of your game (like a library or script). A few of these tools are not designed specifically or only for Twine, but work with it all the same.
A suite of tools and software for releasing Twine games (and potentially other HTML-based games) to a variety of platforms and services. By Gritfish.
A tool for turning web applications (including Twine games) into standalone hybrid applications using NW.js.
A tool for turning web applications (including Twine games) into standalone hybrid applications using Electron.
A Windows-only installer that simplifies installing Tweego.
!> DISCLOSURE: This resource was created by the primary author, maintainer, and curator of this guide.
A shell script for installing Tweego on MacOS.
An extension for VSCode by Cyrus Firheir, Goctionni, and MinusGix. Provides syntax highlighting and programmatic language tools for Twee 3, with built-in support for the core Twine 2 story formats.
A boilerplate project and toolchain for creating Tweego projects with Node and Gulp.
!> DISCLOSURE: This resource was created by the primary author, maintainer, and curator of this guide.
A Tweego development boilerplate.
A Tweego development boilerplate featuring webpack.
An adventure game engine based on SugarCube 2 & TweeGo. An opinionated boilerplate for Tweego projects.
TweeFly is a tool for generating complex game systems in SugarCube and Twee2 without having to code them yourself. Available in both free and Patreon versions, the latter of which comes with a few extra bells and whistles.
Gordian Book is a tool to convert Twine/Twee3 stories into traditional Fighting Fantasy-style gamebooks, with randomized numbered paragraphs, "turn to page X"-style links, and textual rules blocks. Outputs games as PDFs, Twine archives, Twee3, JSON, or HTML.
Since a great deal of web libraries can be made to work with Twine story formats (though it may take some doing), and since Snowman essentially requires all functionality to be built by the author (and I'm unaware of any specific libraries designed for it), this list will only include libraries, scripts, and extensions designed to work with either Harlowe or SugarCube, at least for now.
SugarCube is more extensible than Harlowe, so will have more scripts and extensions.
The author of SugarCube maintains several external add-ons on the SugarCube website.
An inventory system by HiEv. Probably the most full-featured inventory extension available for SugarCube.
Macro-sets aimed at DOM manipulation and simplifying 'tedious' procedures, and more. For SugarCube by Cyrus Firheir.
A macro collection by Gwen[Tastic]. Cooldown buttons and radar charts.
A collection of macros, functions, and other code bits for SugarCube by Akjosch.
A collection of macros, functions, and other code bits for SugarCube by Mike Westhad.
A collection of macros, functions, and other code bits for SugarCube by Hogart (Konstantin Kitmanov).
A macro collection to manipulate text, by SjoerdHekking. Simulate dyslexia and create spoilers.
A collection of macros, functions, and other code bits for SugarCube by Chapel.
!> DISCLOSURE: This resource was created by the primary author, maintainer, and curator of this guide.
An inventory system for SugarCube 2.
!> DISCLOSURE: This resource was created by the primary author, maintainer, and curator of this guide.
A GitHub gist with code and examples for switching between two languages / localizations using the Setting API in a SugarCube project.
A forum post by Greyelf providing the CSS for a variety of text effects in SugarCube, mirroring the effects available in Harlowe by default.
A forum post by Greyelf providing code to create and implement a second sidebar on the other side of the screen in SugarCube.
Dynamic Avatar Drawer is a library for creating customizable character graphics. The developer of the library has written an extensive guide and demo for integrating the library into SugarCube. It may be possible to integrate DAD into other formats as well.
A collection of modifiers and inserts to manipulate text, like showing something different every time a passage is shown.
An audio library for Harlowe, designed to give it feature parity (or close to it) with SugarCube's built-in audio subsystems.
!> DISCLOSURE: This resource was created by the primary author, maintainer, and curator of this guide.
A framework for developing custom macros for Harlowe.
!> DISCLOSURE: This resource was created by the primary author, maintainer, and curator of this guide.
A blog post detailing a potential method for implementing a simple, key-based inventory in Harlowe.
A forum post by Greyelf providing a tag-based styles feature to Harlowe v1, with amendments for Harlowe v2+.
Guides for Twine can sometimes be hard to find when you need them, particularly because most guides, by necessity, are format-specific. Here are a few guides from across the web. There are other guides out there too, but many are out-of-date, written for older or defunct versions of Twine or story formats, or are (no disrespect intended to the original authors) simply wrong--so YMMV.
Guides for the Twine application itself, for general Twine development information, or that just cover a lot of different story formats.
A "cookbook" featuring code examples and explanations of common use-cases in several different formats. A great place to start learning Twine.
A place where technical questions about Twine used to be asked. The Q&A has since been shutdown and made read-only, but is is still home to thousands of great answers that you may want to peruse. This site will frequently show up in Google searches as well.
Years upon years of wisdom and answers can be found by searching the old forum archive. Typically, the archive will appear in Google searches, so it's more common to find it there then to comb through the archive itself.
This wiki is useful, but also has a mix of Twine 1 and Twine 2 content, and a mix of content regarding different story formats. This unfortunately can sometimes make it hard to tell what the information you're reading is actually for. Still, the wiki remains an impressive collection of information, and is typically worth exploring when you have questions that aren't specifically about a story format.
Specifications drafted and approved by the Twine committee and other related documentation, primarily for the developers of tools, compilers, and formats.
Videlais (aka, Dan Cox), a member of the Twine Committee and community, has produced many guides, videos, and explanations for all of the core story formats and for Twine in general.
As it says on the tin, a quick guide to using Twine 2. Note that the examples in this guide use the deprecated <<end...>> style closing tags rather than the <</...>> style closing tags that should be used in SugarCube.
A CSS and styling guide for Twine, mostly covering SugarCube and Harlowe, but also featuring general CSS advice and instructions that could be used for any format.
An overview and explanation of typical game structures used in choice-driven games.
A guide to using PhoneGap to convert Twine games (not just those made with Twine 2) into Android APK apps.
The official documentation for SugarCube. While it includes some guides and tips, the documentation is intended as a reference, so may not always explain certain things in the level of detail required by a novice.
A large amount of sample code for SugarCube covering a variety of common and uncommon use-cases. Frequently updated with new samples.
Harlowe's official documentation. Like SugarCube's docs, this is primarily a reference, though it does try to provide a lot of ground-floor explanations and examples to help novices understand.
A fairly wide-ranging beginner-to-intermediate guide to Harlowe 2.
Snowman's official documentation, complete with several usage examples.
Chapbook's official documentation. Reads a bit more like a guide than the documentation for the other formats.
A Narrascope talk streamed on Twitch about using Chapbook. Assumes some basic knowledge of Twine, but otherwise provides a great ground-floor introduction to using the format.
There are several places across the web where you can discuss Twine, get help with it, or find and connect with other Twine users. Here are several of them.
These dedicated communities are all about Twine.
An unofficial subreddit dedicated to Twine and Twine games.
An official Discord server where you can live chat about Twine and Twine games.
These more general communities are places with specific Twine subforums, places where discussion about Twine is fairly common, or places where Twine-users tend to congregate, thought they aren't specifically for Twine.
A forum for interactive fiction with tags/categories for Twine.
A NSFW game development forum with a prominent Twine user base.
A subreddit for general IF discussion, where Twine may also be discussed.
There are several places across the web where you can host your Twine game for free. You can also always share the HTML file itself (or an archive containing the file and its assets) if you don't want to host it.
Warning
You will not be able to host your Twine game though certain providers like Wix or Wordpress, or through most blogging platforms. Most of these services do not allow users to upload arbitrary HTML files (e.g., your Twine game) and many also have specific limitations on how you can use iframes, so even hosting it elsewhere and making it merely playable through your website may not be possible with such services. Some services, like GoDaddy have also been known to break the Twine files they are meant to serve, so some research may be needed even if your preferred service does allow you to upload arbitrary HTML files.
Itch.io is an open marketplace for independent digital creators with a focus on independent video games. It allows you to upload assets with your HTML file, and allows you to make downloadable games.
GitHub pages is great for testing your game, but there are bandwidth limitations, so publishing a game here may have some issues. You can upload assets with your game, and the whole game is structured as a repository on GitHub as well.
Very similar to GitHub pages, but uses BitBucket as a backend.
A free place to host your Twine game, along with any assets it needs. It's limitations are similar to GitHub and BitBucket pages, but you can pay for unlimited bandwidth and other perks.
Allows you to use Google Drive as your website's backend. You can upload assets in addition to your HTML file, as you'd expect. Has potentially stricter limitations than the preceding options.
Newgrounds accepts HTML games, like Twine. You can upload assets with an HTML file in much the same way as on Itch.io.