libtwee

A C# library for creating and parsing current and historic Twine file formats.

Table of Contents

1. Installation
2. Quick Start
3. Story Compilation
4. Format Support
5. Support Functionality
6. Contributing
7. License

Installation

NuGet Package Manager

Install-Package Videlais.libtwee

.NET CLI

dotnet add package Videlais.libtwee

Package Reference

<PackageReference Include="Videlais.libtwee" Version="1.0.0" />

Quick Start

using libtwee;

// Parse a Twee 3 file
var story = Twee.Parse(tweeContent);

// Convert to Twine 2 HTML
var html = story.ToTwine2HTML();

// Generate a new IFID
var ifid = Babel.GenerateTwineIFID();

Documentation

📚 Complete Documentation - Comprehensive guides and API reference

• Getting Started Guide - Installation and basic usage
• Examples - Practical code examples
• API Reference - Complete API documentation
• File Formats Guide - Understanding Twine formats

Building Documentation Locally

# Install DocFX (if not already installed)
dotnet tool install -g docfx

# Build documentation
./build-docs.sh

# Or manually:
cd docs && docfx docfx.json

Requirements

• .NET 9.0 or higher

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). The result is then presented as links or other visual, interactive elements for another party to interact with to see its content.

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 JavaScript code (generally a "story format") with story HTML data.

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

• Twine 2 HTML
• Twine 1 HTML

More human-readable formats include:

• Twee 3²
• Twine 2 JSON³

From 2009 to 2015, Twine 1 supported a now historical format named TWS. libtwee does not support this.

Twine 2 supports exporting a collection of stories (known as a library) in the Twine 2 Archive HTML format.

Format Support

Format	Input	Output
Twine 1 HTML (2006 - 2015)	Yes	Partial support.
Twine 1 TWS (2009 - 2015)	Not supported	Not supported.
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.

(back to top)

Support Functionality

Multiple Twine formats support using an IFID to identify one work from another.

The Babel class contains methods for verifying and generating a Twine-compatible IFID:

// Generate a new IFID
string ifid = Babel.GenerateIFID();

// Validate an existing IFID
bool isValid = Babel.ValidateIFID("12345678-1234-1234-1234-123456789ABC");

(back to top)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

1. Clone the repository
2. Ensure you have .NET 9.0 SDK installed
3. Run dotnet restore to install dependencies
4. Run dotnet build to build the project
5. Run dotnet test to run the test suite

Code Coverage

This project maintains high code coverage standards. Run the following to generate a coverage report:

./coverage.sh

(back to top)

License

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

(back to top)

Footnotes

1. Story formats 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. ↩