nick says

I spent this week learning everything there is to know about Twine!

twinejs

Twine is a piece of software which allows writers to author their interactive fictions using a nifty GUI. It looks like this:

In this image, each square is a passage, and the arrows connecting the different passages are links (like hypertext). The window shown contains exactly one twine story, which is a collection of passages under a unique ID. A story may have its own stylesheet and scripts, but they are edited in a different window. A passage does not necessarily need to be connected to another passage: for example, the hal.tracks passage in this window merely holds some information about the soundtrack of the story being edited.

When a story is compiled from the Twine app using the "publish to file" command, the story file, which exists in local program storage, is compiled to a single *.html file for easy hosting. This file includes the CSS/Javascript required to make the page work, some of which is Twine boilerplate. However, the actual source code of a twine file is represented using Twee. Well, kind of.

In Twine2, the developers moved away from allowing users to import and export twee files and instead expect users to only import and export html files. When a twine story is saved on your local machine, even before you've published it, it exists as an html file. When you're actively editing the file, the twine code is actually manipulating a story object which contains several parameters (story format, start state, story ID) and immediately exports to html whenever you change your story. This copy is different from the proofing copy, in that the proofing copy exists only temporarily and has some debug features built in...essentially works like a localhost testing server. So, the underlying mechanism in twine2 is not based on any Twee code, but twine has preserved the twee method of making links like "[[word->destination]]"but not much else.

From what I can see, the first version of Twine was completely Twee source code underneath. But now, according to the developers of Twee:

Twee is a text format for marking up the source code of Twine stories. It is the equivalent of Twine HTML files, which contain story and passage data, but in a more human-readable format. Twee notation was the original way to write and compile Twine stories—via the original, and now obsolete, compiler of the same name. Later, when Twine 1 was introduced, it was used alongside Twine 1's native format as an import/export option. With the introduction of Twine 2, Twee was separated from Twine. In time, other compilers were written to take advantage of the format to generate Twine compatible HTML files. Over several years, multiple extensions to Twee and its possible options were created and used by different software. This specification seeks to unify these options into a single document that best represents existing community practices and properly encapsulates the data stored within the and elements of Twine 2-style HTML files.

so, in effect, the source code of any twine story is javascript, JSON, and HTML, with some help provided from story formats. I believe this decision was made to appeal to writers who preferred to jump in with limited capability as long as it allowed them to author an interactive story using a GUI, which Twine 2.* prioritizes.

twee

The first version of Twee was created before Twine, back in 2006. Twee was then considered the source code for Twine 1.* projects, with easy importing and exporting being a feature of the Twine 1.* application.

Twee2 was released unofficially by a fan of the original language after Twine 2.* was introduced...not quite in protest, but to fulfil the wants of authors who preferred the modular writing approach, which twee allows and twine does not. Now, largely abandonware, Twee2 has fallen out of favor and has been replaced with a more official version, Twee3.

Twee3 is now in active development (with a stable release) and Tweego is the most commonly used compiler for twee3 code. Twee3 code, without the help of story formats, looks something like this:

:: A passage with no tags
Content of the "A passage with no tags" passage.


:: A tagged passage with three tags [alfa bravo charlie]
Content of the "A tagged passage with three tags" passage.
The three tags are: alfa, bravo, charlie.

As mentioned, there is no use of story formats in this excerpt, but the same story formats used with Twine2 may be used with Twee3 code.

story formats

story formats are (mostly) macro-based languages/small engines used to manipulate elements of a twine story. In the past (Twine v1), the choice of story format was primarily a choice of formatting preference. Now, the capabilities of each format are different. From Chris Klimas' blog,

a story format is essentially a runtime engine for works built in Twine. It takes the passages created in Twine and displays them in a Web browser. I intended the name ‘story format’ to a bit friendlier than ‘engine,’ and formats in Twine 1 were indeed more about formatting than behavior. In Twine 2, the situation has become a bit more complex, and thus the term ‘story format’ a bit dicier. Instead of choosing colors and whether clicking a link causes the story to expand or instead replace the existing text with new text, changing story formats in Twine 2 changes the entire approach an author takes to interactivity.

The main work of writing a story format seems to involve: providing useful macros, and the HTML/CSS compile at the end.

The three most common ones are Harlowe, SugarCube, and Snowman, but others exist...however, they are not in great use. The three listed are built-in to twine2, but Harlowe is the true "default" if you start working without changing any settings.

I've decided to test these using Twee3 source code rather than Twine2, as I think it'll be more informative to actually write the source code and see how it feels to write these stories as code rather than focusing on the language in the GUI (which now seems more difficult to work with compared to Twee). All of these examples were compiled using Tweego

harlowe

Harlowe is the default story format included with Twine2. It was designed as an good introductory story format for those both new to Twine and digital writing in general.

test story

The test story is here.

pros & cons

• Harlowe DOES NOT allow users to define their own macros.
• Some of the "functionality" of Harlowe compared to sugarcube is actually the functionality of HTML...
• Harlowe is easy to use for beginners, and can be directly extended with javascript and css, but I doubt power users would want to stick with it (I certainly won't).
• Hooks and replace macros are a cool concept, but I'd rather just be able to change the value of a variable the old fashioned way.

sugarcube

Sugarcube is a Twine/Twee story format which is pitched on the basis that it is essential syntactic sugar for Javascript, with syntax that makes Javascript more accessible for beginners.

Sugarcube documentation can be found here.

test story

The test story is here

pros & cons

• Sugarcube has its own macro for including images, but when you compile a sugarcube story you still have to have an external file system where your images are stored. No single HTML file with everything in it with this one, either.
• also a macro for including audio, general "media" passages allowed. In harlowe you have to finagle this with Javascript/HTML directly, which is fine but can be a pain.
• more clear syntax than Harlowe macros. Rather than (using)[hooks], macros are <<opened>> and <</closed>> like HTML tags.
• More macros than Harlowe in general
• can define new macros easily using javascript function definitions, but would be nice if you could define macros using other macros.
• has include macro, so text can be written in other places and reused easily.

snowman

about

Snowman was designed by Chris Klimas and is now maintianed by Dan Cox. It is unlike the previously mentioned formats in that it does not have any macros. Rather, Snowman allows twine users to directly modify the window.story and window.passage objects which make up the backbone of Twine2 style stories. These objects are the ones which replaced Twee source code in Twine2.

Snowman includes JQuery and Underscore.js functionality, which is also used explicitly without macros.

While Snowman doesn't use macros, it does allow clever use of inline javascript. For example, to do an if/then statement, you would type

You are currently carrying: 
<% if (s.inventory.length === 0) { %>
nothing.
<% } else { %>
<%= s.inventory.join(', ') + '.' %>
<% } %>

here, the <% %> tags are just used to contain javascript, and anything outside of these tags is parsed as HTML. In this way, snowman users can use javascript within passages pretty simply.

test story

The test story lives here.

thoughts

I originally thought Snowman would be a pain to work with, but the templating system provided by underscore.js actually makes it pretty simple. I also appreciate how clean the *.html output is compared to Harlowe and SugarCube. In a way, snowman is actually a pretty powerful web development tool. It was also the easiest of the three for figuring out how to define my own functions. (Harlowe doesn't allow it, and SugarCube has so many macros that defining one seems pointless, and you cannot define macros using builtin macros anyway, so unless you know javascript, defining macros is useless in sugarcube.)

general thoughts

It seems like the kind of thing I would be interested in, I could create using a story format framework. I have a couple good examples here of story formats which all have different functions, and different syntaxes. It seems, for the most part, that:

• beginners love Harlowe
• power users love SugarCube (and people from the Twine 1 days)
• programmers love Snowman (it's basically a templating engine...)

I think it might be interesting to do some sort of \TeX inspired story format, as the concept of a "passage" here reminds me a lot of sections in a document, and the "story" reminds me a lot of the overlying document. There are some formatting things which aren't built in to the other three which I would like to prioritize. For example: for each of the three story formats above, you'd have to write something extra in order to make sure that, if you write poetry rather than prose, that your line breaks are consistent-- this would normally be using HTML/CSS, but the story formats above generate their own CSS, so it's a bit frustrating that the one feature I need isn't included. Harumph.

I also think the syntax of \TeX is familiar to some writers, as it's been a typesetting tool for a while, and the concept of a macro exists in \TeX already, so mirroring the syntax with Twine-related macros would make sense.

While I enjoyed the flexibility of Snowman, I do think Twine specific macros are useful, as, at a certain point, if you remove those features you're basically working with a limited web framework rather than a story writing tool.

I'd also prefer to change some of the Twee3 syntax to \TeX alternatives (\begin{passage}[Start] instead of ::Start) so I don't know if my final product will fit the Twee3 specification...more like "Twee and TeX inspired."

attachments