Parsing Twee: Part 2: Understanding Story Formats

On By Dan CoxIn twine

Parsing Twee

Twee is a human-readable format for saving the “code” of a Twine story. It predates Twine by a few years and has been a format used by many to create Twine-compatible projects for a decade.

Understanding Story Formats

In the last part, Twee was described as a series of passages. Everything in Twee is in a passage, including information about the story itself.

While useful to be able to read and exchange with others, Twee as a format by itself needs something extra to move it from text to HTML. This is where story formats come into the picture.

What is a story format?

Back during Twine 1, the number of story formats was quite small. There were, at most, a handful and usually only two people really cared about. When a story format was used, it took the Twee code and moved it into HTML. The story format part described the layout and other CSS rules. It changed the presentation of the code.

This changed with Twine 2. Now, a story format is not just presentation but also processing. Each story format, if the author of it wants, can introduce its own form of additional code and include things like macro usage. As of this writing, the three major story formats, Harlowe, SugarCube, and Snowman, each have their own programming “language.”

While Twee exists in a more human-readable format than the HTML of Twine, it still depends on story formats.

What do story formats look like?

Story formats come in files called “format.js”. This contains all of the code of the story format in a JSON format that sets the values of a variable called window.storyFormat.

Most of the time, the actual code of a story format is not as important for Twee users and developers as a special sequence of values within the story format.

"source":
"<!DOCTYPE html>\n
<html>\n\t
<head>\n\t\t
<title>{{STORY_NAME}}</title>\n\t\t
<meta charset=\"utf-8\">\n\t\t
<style>…</style>\n\t
</head>\n\t
<body>\n\t\t
<div id=\"main\"></div>\n\t\t
{{STORY_DATA}}\n\t\t
…
view raw format_example.js hosted with ❤ by GitHub

Within the values of the window.storyFormat variable will be an attribute called source. This contains the HTML of the story format and also where the Twee transformed into HTML goes. When handling the compiling of Twee into HTML, this section will contain two important “template” keys that will be replaced during the compilation process.

{{STORY_NAME}}

A story format contains multiple “template” areas where text should go when compiling Twee. The first of these (in order) is STORY_NAME. When compiling a story format into HTML, the name of the story should replace this template key.

{{STORY_DATA}}

STORY_DATA is the most important. When converting the Twee into HTML, this is where it will go in the resulting file. All of the data of the story will replace this.

Parsing Twee

In Extwee, I look for the STORY_NAME and STORY_DATA sequences as part of my HTMLWriter.js object. My code generates all of the HTML and then looks for the special sequences before replacing them and then combining all of the text together.

// Replace the story name in the source file
this.storyFormat.source = this.storyFormat.source.replace("{{STORY_NAME}}", this.story.name);
// Replace the story data
this.storyFormat.source = this.storyFormat.source.replace("{{STORY_DATA}}", this.storyData);
this.outputContents += this.storyFormat.source
// Write the entire contents out
fs.writeFileSync(file, this.outputContents);
view raw HTMLWriter.js hosted with ❤ by GitHub

The final step is to write out the new compiled file.