Working with TinyQBN: Part 3: Working with Twee Code

Working with TinyQBN

TinyQBN is a JavaScript library and set of SugarCube widgets created by Joshua Grams for working with quality-based narrative (QBN) structures in Twine 2.

Part 3: Working with Twee Code

Twee is a plain-text format used for compiling files (.tw and .twee) into Twine 2-compatible HTML. Instead of using Twine directly, Twee files are read by programs such as Tweego to transform a work written in one format into another.

The Twee 3 specification explains the format and some recommendations for how tools (“compilers”) should understand sections of the files. In general, however, there are three rules for authors based on expectations of the format:

StoryData. There should be a StoryData passage with at least one required field, ifid.
StoryTitle. The StoryTitle specifies the name of the story.
Start OR a start field in StoryData: There are two options for specifying where a story should start. There can be a passage named “Start” or there can be a field in the StoryData passage named “start”. If this field exists, it will override any existing Start passage.

Generally, a minimum Twee file will usually look like the following where there are three passages (StoryData, StoryTitle, and Start). The StoryData passage should contain an ifid field and the StoryTitle and Start passages (or using start field) should exist.

:: StoryData
{
    "ifid": "46CA9877-6E18-41E3-8EE4-59B7CE9B3F90"
}

:: StoryTitle

:: Start

Preparing Tools

As Twee is a plain-text format, it is recommended to use VS Code with the Twee 3 Language Tools plugin. This will enable Twee files to be recognized and syntax highlighting to be used for different story formats.

The Twee 3 Language Tools also mentions in its Requirements section the need for the format and format-version fields as part of StoryData. These should be included and specify the story format and its version to be used in the compilation.

:: StoryData
{
    "ifid": "46CA9877-6E18-41E3-8EE4-59B7CE9B3F90",
    "format": "SugarCube",
    "format-version": "2.30.0"
}

:: StoryTitle
Example Story

:: Start
This is the beginning!

Downloading Tweego

Tweego is a command-line tool for compiling Twee files to Twine 2 HTML. Its documentation covers various usage scenarios and possible options. Once downloaded, it can be used directly from its downloaded folder or installed on a folder added to the global PATH for the operating system.

Note: When the format-version field is used with Tweego, it will look for the exact version matching the contents of its storyformats folder.

Note: This post assume a Windows operating system and Tweego will have “.exe” at the end of its filename.

For this post, the command options for Tweego will look the following:

tweego.exe -o output/example.html src

The above command will read a directory, src, and create an output HTML file, example.html, in the output directory. The next section will explain the structure to achieve this.

Creating an Example Project Directory

Tweego is capable of reading the contents of a directory and combining all of the files together. This means additional JavaScript and CSS code can be kept in their individual files (.js) and (.css) and loaded using the name of a directory as part of the command-line options.

Create a new folder named project. Open this in VS Code (File -> Open in MacOS X and File -> Open Folder in Windows).

Create two new folders inside project: src and output.

project
├── src
├── output

In the src folder, create an index.twee file with the following contents:

:: StoryData
{
    "ifid": "46CA9877-6E18-41E3-8EE4-59B7CE9B3F90",
    "format": "SugarCube",
    "format-version": "2.30.0"
}

:: StoryTitle
Example Story

:: Start
This is the beginning!

Adding TinyQBN

TinyQBN is a JavaScript library. It must be added as a separate file to the project.

Download the file from GitHub through visiting this URL. Using right-click and click “Save as…”. Save the file as “story-javascript.min.js” in the src folder created previously.

Once saved, the contents of the project directory will look like the following:

project
├── src
│   ├── index.twee
│   └── story-javascript.min.js
├── output

TinyQBN: Tags and Comments

As covered in Part 2, cards can be added to a story through using the tag “card” in a passage. In Twee, tags are added through using opening and closing square brackets after and on the same line as the name of the passage.

:: Example [card]

On Sep 23, 2020, Josh Grams also added support for single-line comments containing requirements as well.

:: Start
/*QBN card */
This is a card!

Compiling the Example Project

With TinyQBN added to the project and at least one passage using either tags or comments to make it as a card, compile the project.

With the directory structure, open a new terminal in VS Code using Terminal -> New Terminal.

Once it loads, run the following (assuming Tweego is installed globally):

tweego.exe -o output/example.html src

From the project directory, this will read the src directory (including the TinyQBN JavaScript library) and compile everything together. It will output the final HTML in the output directory as example.html.

To make changes to the project, update the index.twee file (or add others!) and re-run the command. Open the new file in a web browser to see the updated file.

Note: Some web browsers cache versions of files. Always close and then re-open test HTML files for the latest version.