Twinelike 0.2.0

Twinelike

A C# library for parsing and running Twine/Harlowe interactive fiction, designed to embed inside game engines — Unity, Godot, anything that runs .NET, Mono, or IL2CPP.

It accepts Twine 2 HTML exports and Twee 3 source, parses the full Harlowe markup language, evaluates author-written macros at runtime, and surfaces rendered content through an engine-agnostic IRenderOutput interface — plain text, navigation links, semantic styles, and interactive regions. Implement that interface against your engine's text renderer (TextMeshPro, RichTextLabel, raw HTML, plain console) and you have a working interactive story.

Status: Targets netstandard2.0, so it drops into Unity 2018.1+, Godot 3 & 4, .NET Framework 4.6.1+, .NET 5+, Mono, and Xamarin. Tracks Harlowe 3.3.8.

Quick start

using Harlowe;
using Harlowe.Runtime;
using Harlowe.Twee; // only needed if you're loading Twee 3 source

// Load a Twine 2 HTML export, or use new TweeReader().Read(tweeText) instead.
var story = new Harlowe(File.ReadAllText("story.html"));

// Wrap it in a session — this is the stateful object you drive.
var session = new StorySession(story);

// Render the current passage. Every navigation method returns one of these.
var result = session.Render();

Console.WriteLine(result.Text);
// Output:
//   You stand in a clearing. There is a path north.

// The player clicked a link in your UI; advance.
var next = session.Goto("Forest");

// Or, they clicked an interactive region — pass the id back:
var after = session.DispatchEvent(regionIdFromYourUi);

// Roll back to the previous passage:
if (session.Undo()) {
  session.Render();
}

RenderResult carries the rendered content as both a flat .Text string and a list of typed .Entries (Text, Link, PushStyle, BeginInteractive, …). Pass the entries to your engine's renderer, or use the IRenderOutput interface below to receive them as a stream.

Engine integration

Implement IRenderOutput against whatever your engine uses to display text. The interface is small and stable:

public interface IRenderOutput
{
  // Prose text — already entity-decoded, post-macro evaluation.
  void Text(string content);

  // Raw author-written inline HTML (e.g. <b>hello</b>). Drop, escape,
  // or pass through depending on whether your engine wants HTML at all.
  void Html(string rawHtml);

  // A passage navigation link. Wire your UI's click handler to
  // session.Goto(target).
  void Link(string text, string target);

  // An in-prose error (bad expression, type mismatch, unknown macro).
  // The runtime never throws on the render hot path — errors come
  // through this channel instead.
  void Error(string message);

  // Bracketing semantic styles. StyleSpec carries flags (Bold, Italic,
  // Underline, Strikethrough), value fields (Color, BackgroundColor,
  // BackgroundImage, FontFamily, FontSize, Opacity, Alignment), and a list
  // of named Effects (Mark, Outline, Shadow, Blur, Shudder, Blink, ...).
  // PushStyle is always paired with a matching PopStyle; nesting is
  // well-formed.
  void PushStyle(StyleSpec style);
  void PopStyle();

  // Bracketing interactive regions. region.Id is opaque — pass it back
  // to session.DispatchEvent() when the user interacts. region.Kind is
  // Click / MouseOver / MouseOut.
  void BeginInteractive(InteractiveRegion region);
  void EndInteractive();
}

Mapping to common engines

The bracketing primitives (PushStyle/PopStyle, BeginInteractive/EndInteractive) intentionally line up with how inline-tag rich-text systems already work:

For web/HTML consumers, wrap your output in HtmlRenderOutput and it translates semantic events into HTML tags automatically — no manual mapping.

A complete minimal adapter

public class ConsoleOutput : IRenderOutput
{
  public void Text(string content)             => Console.Write(content);
  public void Html(string rawHtml)             => Console.Write(rawHtml);
  public void Link(string text, string target) => Console.Write($"[{text} -> {target}]");
  public void Error(string message)            => Console.Write($"<<error: {message}>>");

  public void PushStyle(StyleSpec style) {
    if (style.Bold)   Console.Write("\x1b[1m");
    if (style.Italic) Console.Write("\x1b[3m");
  }
  public void PopStyle() => Console.Write("\x1b[0m");

  public void BeginInteractive(InteractiveRegion region) => Console.Write("[");
  public void EndInteractive()                           => Console.Write("]");
}

Supported Harlowe features

✓ shipped · ⚠ partial · ✗ not yet

Language

Macros

Storage

Story writers: a story that uses only ✓ features will play unchanged. ⚠ rows mean the macro is recognised but only a subset of arguments work. ✗ macros produce an in-prose error rather than crashing — surrounding content keeps rendering.

Twee 3 example

A minimal story this library happily parses and runs:

:: StoryTitle
The Clearing

:: StoryData
{
  "ifid": "00000000-0000-0000-0000-000000000001",
  "format": "Harlowe",
  "format-version": "3.3.8",
  "start": "Clearing"
}

:: Clearing
You stand in a |spot>[clearing]. There is a path north.
(click: ?spot)[A breeze stirs the grass.]

[[Go north->Forest]]

:: Forest
The forest is dark and full of |secret>[secrets].
(enchant: ?secret, (text-style: "italic"))

[[Back->Clearing]]

Loaded with:

var story = new TweeReader().Read(File.ReadAllText("clearing.tw"));
var session = new StorySession(story);

Build & test

dotnet build Twinelike.sln
dotnet test  Twinelike.sln

Library targets netstandard2.0. Test project multi-targets net48 + net8.0 (xUnit). Both TFMs exercise the same code; CI runs net8.0 on Linux.

To produce the distributable DLL:

# Release build merges HtmlAgilityPack into twinelike.dll via ILRepack
# (Debug builds skip the merge for fast dev cycles).
dotnet build Twinelike.sln -c Release
# → bin/Release/netstandard2.0/twinelike.dll  (self-contained, ~270 KB)

# Or for a clean publish folder:
dotnet publish Twinelike.csproj -c Release -o ./dist/Twinelike
# → dist/Twinelike/twinelike.dll

# Or for the NuGet package:
dotnet pack Twinelike.csproj -c Release -o ./dist
# → dist/Twinelike.0.2.0.nupkg

Drop the produced twinelike.dll into Unity's Assets/Plugins/ or reference it from any .NET project — no other DLLs required.

Architecture

Two parsing layers, then a runtime. Briefly:

• Layer 1 — host. Either Harlowe(htmlText) (HtmlAgilityPack pulls <tw-storydata> / <tw-passagedata> and HTML-entity-decodes the inner text) or TweeReader().Read(tweeText) (header splits on :: Name [tags] {position} at column 0). Both produce the same Harlowe story object.
• Layer 2 — Harlowe markup. Shared between both front-ends: HarloweTokenizer → HarloweBodyParser (which hands off to HarloweExpressionParser at every macro) → PassageBody AST.
• Runtime. StorySession owns the variable store, macro registry, and render-tree state. BodyRenderer walks an AST into a RenderTreeBuilder (an IRenderOutput-shaped tree-of-nodes); RenderTreeFlusher replays the finished tree as the flat event stream your IRenderOutput receives. Revision macros ((replace:), (append:), (prepend:)) mutate the tree in place; enchantment macros ((change:), (enchant:)) re-wrap matched nodes; interaction macros ((click:) family) wrap targets in InteractiveRegion brackets and register handlers that fire on DispatchEvent.

For implementation depth — file layout, the descriptor-patch changer model, design rationale, conventions — see CLAUDE.md.

Dependencies

None at runtime. The shipped twinelike.dll is a single self-contained assembly — HtmlAgilityPack (used by the Twine 2 HTML loader) is merged into it at build time via ILRepack with its types internalized, so it doesn't propagate as a NuGet dependency and doesn't conflict if your project already references HAP for its own purposes.

Errors are inline, not exceptional

The runtime never throws on the render hot path. A bad expression renders an inline error message at the spot it happened (delivered through IRenderOutput.Error) and the rest of the passage keeps rendering — mirroring Harlowe's authoring model, where one broken macro doesn't take down the whole story. Engine integrations don't need try/catch around every render call.

License

MIT. Use it in commercial games, open-source projects, anything — just keep the copyright notice with the source.