Extwee is a Twee compiler supporting Twine 2-style formats using the Twee 3 specification.
It will read both Twee 2 (Twee2) and Twee 3 formatted files, but does not understand or currently support Twee 1 (Twine 1.4.2) or Twee2 special passages for Twine 1.X formatting.
Extwee does not support Twine 1.X story formats.
Compiled versions for Windows, MacOS X, and Linux can be found under Releases
Starting with Extwee 1.5, the latest versions of Harlowe (1.X, 2.X, and 3.X), SugarCube (1.X and 2.X) and Snowman (1.X) are now packaged with binary builds.
Compatibility With Other Tools
- Does not parse StorySettings
- Does not parse
- Does not parse StoryIncludes
- Does not handle [haml]; will not parse HAML
- Does not handle [twee2] special passages
When working with the binary builds of Extwee, the operating system is part of the file name. In Windows, for examples, the build is called
Extwee supports the following command-line arguments:
i: Input Twee file
v: Version of Extwee
f: Path to the Story Format's
d: HTML file to decompile into Twee code
o: Output file
r: Path of directory to read
w: Enable directory watching mode
Using the command-line arguments, Extwee operates in four "modes":
- Twee to HTML
For simple, single-file compiling of Twee code into HTML, the arguments
f are used. These specify the input Twee file, the output HTML file, and the story format to use.
extwee-[OS] -i source.twee -o output.html -f path/format.js
- HTML to Twee
For simple, single-file decompiling of HTML into Twee code, the arguments
o are used. They specify the HTML file to read and the Twee file to create.
extwee-[OS] -d file.html -o source.twee
- Directory Reading
For more complex, multiple file usage, the argument
r can be used to read a directory. This is used with the
f options to specify what output file and which story format to use.
When operating in directory reading mode, all CSS files will be processed using CleanCSS using the Level-2 minification. All JS files are first processed using Babel to transpile any ES6 code into ES5. Additional post-processing is done using UglifyJS.
extwee-[OS] -r path/ -o output.html -f path/format.js
- Directory Watching
For more complex, multiple file usage, the argument
w can be used to "watch" a directory for any new files or changes. While in this mode, Extwee will re-use the Directory Reading mode when it detects any additional files or changes. The specified output file will be re-build fresh each time.
extwee-[OS] -w path/ -o output.html -f path/format.js
When watching a directory, Extwee will look for
twee3 files. All other modes will accept any text files as input.
Extwee will attempt to escape the metacharacters of
] when moving to and from Twee notation. However, even with this support, it highly recommended to avoid these characters in passage name and tags to avoid confusion and potential issues.
Extwee can be used via NPM.
npm i extwee
As a NPM package, Extwee's objects can also be used independent of the binary builds as part of other projects. It exposes the following objects and their properties and functions.
FileReader wraps fs.existsSync and fs.readFileSync. It accepts the path to a file and will throw an error if the file cannot be found or read.
let fr = new FileReader("path");
- contents: The textual content of the read file.
TweeParser accepts Twee textual content and saves an internal Story object populated with any passages found.
let tp = new TweeParser("tweeContent");
- story: The internal Story object created and populated during parsing.
TweeWriter accepts a Story and path to file the Twee file.
let tw = new TweeWriter(Story, "path/");
StoryFormat accepts a JS object (and will throw an error if not).
It is uncommon for StoryFormat to be used directly.
- name: Name of the story format.
- version: Version of the story format.
- description: Description of the story format.
- author: Author of the story format.
- image: Logo image URL
- url: URL of story format
- license: License of the story format
- proofing: If story format is a proofing story format or not
- source: The JS source of the story format
Passage represents a single passage in a Twine story. It accepts
metadata (JS Object),
text (String), and
It is uncommon for Passage to be used directly.
- name: Name of passage.
- tags: Array of any tags.
- metadata: Object holding any passage metadata
- text: Text of the passage.
- pid: Passage Identification Number (PID)
The Story object holds all information about a Twine story including its metadata, passages, and name.
let s = new Story();
- name: Name of the story. (Defaults to "Unknown").
- metadata: Story metadata represented by
StoryDatapassage in Twee 3
- passages: Array of Passage objects.
- creator: Set to
package.jsonname (i.e. Exwee).
- creatorVersion: Set to
- getStylePassages(): Returns an array of any passages with the tag "stylesheet".
- getScriptPassages(): Returns an array of any passages with the tag "script".
- deleteAllByTag(tag): Deletes any passages with the tag
- getStartingPassage(): Returns the PID of the starting passage (either
startoverride, if found).
StoryFormatParser accepts the path to a story format's
format.js file. Upon successful parsing, it keeps an internal StoryFormat object.
let sfp = new StoryFormatParser("path/format.js");
- storyFormat: Either
null(upon failure to parse) or a StoryFormat object
HTMLParser accepts HTML content to parse. Upon successful parsing, it stores an internal Story object.
- story: Upon successful parsing, this object will hold the story and all passages found.
HTMLWriter accepts the path to an output file, a Story object, a StoryFormat object, and optional extra CSS and JS content.
let hw = new HTMLWriter("path/", Story, StoryFormat, extraCSS, extraJS)
Common API Usage Patterns
Reading and Parsing a Twee file
const Extwee = require("extwee"); let file = new Extwee.FileReader("tweefile.twee"); let tp = new Extwee.TweeParser(file.contents); // tp.story will hold the parsed story and passages
Reading and Parsing a Twine 2 HTML file
const Extwee = require("extwee"); let file = new Extwee.FileReader("twine2.html"); let hp = new Extwee.HTMLParser(file.contents); // hp.story will hold the parsed story and passages