[go: up one dir, main page]
Skip to content

Latest commit

 

History

History

docs

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
examples
examples
 
 
formats
formats
 
 
install
install
 
 
objects
objects
 
 
.nojekyll
.nojekyll
 
 
README.md
README.md
 
 
_sidebar.md
_sidebar.md
 
 
index.html
index.html
 
 

README.md

Extwee

codecov

npm version

License: MIT

NPM Badge

Story Compilation

The process of story compilation converts human-readable content, what is generally called a story, into a playable format such as HyperText Markup Language (HTML) able to be read by another application such as a web browser. The result is then presented as links or other visual, interactive elements to a player or reader, depending on the work created.

The term compilation is used because different parts of code are put together in a specific arrangement to enable later play. As part of Twine-compatible HTML, this means combining story format JavaScript code with story HTML data.

Extwee is not an authoring tool. It cannot be used to create story content. This data must be created using other tools or processes. Extwee can then compile the story with story format code to produce something playable.

Playable formats are the following and require external story formats1 to enable play:

  • Twine 2 HTML
  • Twine 1 HTML

More human-readable formats include:

  • Twee 32
  • Twine 2 JSON3

From 2009 to 2015, Twine 1 supported a now historical format named TWS. This was a binary format used for archival purposes. Extwee can read this format but does not support creating it because no other tools, including current versions of Twine, accept it as valid input.

Twine 2 supports exporting a collection of stories (known as a library) in the Twine 2 Archive HTML format. Extwee can also read and write this format, creating either a collection of stories from the data or writing a collection of internal objects to a file.

Format Support

Extwee is a story compilation tool supporting multiple historical and current Twine-compatible formats.

Format Input Output
Twine 1 HTML (2006 - 2015) Yes Partial support. Twine 1 HTML can be produced, but the StorySettings optional passage introduced in Twine 1.4.0 requires external libraries like jQuery not included with Extwee.
Twine 1 TWS (2009 - 2015) Yes Extwee does not support TWS (Python pickle) output because no current version of Twine or other story compilation tool produces this historical format.
Twine 2 HTML (2015 - Present) Yes Yes
Twine 2 Archive HTML (2015 - Present) Yes Yes
Twee 3 (2021 - Present) Yes Yes
Twine 2 JSON (2023 - Present) Yes Yes

Note: Round-trip translations can present problems because of required fields and properties per format. Some metadata may be added or removed based on the specification being followed.

Node and Web API

The following objects and methods are available in Node.js or browser contexts.

Note: When used in a browser context, all objects and methods are part of the window.Extwee global.

Objects

An object must be created using either the new keyword in JavaScript or as the result of parsing data.

  • StoryFormat
  • Passage
  • Story

Story and Passage objects can generate multiple output formats: toTwee(), toTwine1HTML(), toTwine2HTML(), and toJSON(). Stories cannot be played in a browser without the corresponding compiler combining it with story format data.

Parsers

Translates output formats such as HTML, Twee, JSON, or JSONP into objects.

Note: Twine 1 story formats exist across multiple files (header.html and optional code.js). They cannot be parsed into a StoryFormat object.

  • parseTwee()
  • parseJSON()
  • parseStoryFormat()
  • parseTwine1HTML()
  • parseTwine2HTML()
  • parseTwine2ArchiveHTML()

Compilers

Compiles story, story formats, or other data into an archive or playable format.

  • compileTwine2HTML()
  • compileTwine1HTML()
  • compileTwine2ArchiveHTML()

Note: In order to create playable Twine 1 HTML, an engine.js file must be supplied.

Documentation

Extwee has documentation on individual source files hosted on GitHub Pages.

Command-Line Usage

Extwee supports a command-line interface for four general scenarios:

Compiling Twee 3 + Twine 2 Story Format into Twine 2 HTML

Compile Twee 3 + StoryFormat into Twine 2 HTML:

extwee -c -i <tweeFile> -s <storyFormat> -o <Twine2HTML>

De-compiling Twine 2 HTML into Twee 3

De-compile Twine 2 HTML into Twee 3:

extwee -d -i <twine2HTML> -o <outputTwee>

Compiling Twee 3 into Twine 1 HTML

Enabling Twine 1 mode requires using the -t1 or --twine1 flag.

extwee -t1 -c -i <tweeFile> -o <Twine1HTML> -engine <engineJS> -name <storyFormatName> -codejs <CodeJS> -header <header>

De-compiling Twine 1 HTML into Twee 3

Enabling Twine 1 mode requires using the -t1 or --twine1 flag.

extwee -t1 -d -i <twine1HTML> -o <outputTwee>

Roadmap

Each major version has its own GitHub project:

Tree Shaking Support

For advanced tree shaking patterns, most formats are broke into compile.js and parse.js files exporting associated compile() and parse() functions. When using the API, it is possible to only import a single function or object to produce smaller and potentially faster code in projects dependent on Extwee functionality.

License

Distributed under the MIT License. See LICENSE.txt for more information.

Footnotes

  1. Extwee does not include or publish story formats. These can be found in the Story Format Archive (SFA). ↩

  2. Twee exists in three versions. The first existed between 2006 to 2009 and was part of Twine 1. The move to Twine 2 in 2009 dropped support and the story compilation tools Twee2 and Tweego adopted their own extensions and modifications. Beginning in 2017, work was done to unite the different projects. This resulted in Twee 3 in March 2021. ↩

  3. In October 2023, JavaScript Object Notation (JSON) was added as a supported community format for story compilation tools. Extwee is the first tool to support this format. ↩