Yarn Spinner: the engine-agnostic dialogue compiler behind Night in the Woods
The core compiler and engine-agnostic components for Yarn Spinner, the friendly dialogue tool.
At a glance
- What is it?
- Yarn Spinner is a C# dialogue system that compiles screenplay-like scripts into a format your game runs. This article covers what the core repository contains, how to get it, and where it stops being the right choice.
- Who is it for?
- Adopt the core Yarn Spinner repository if you write dialogue in a screenplay-like format and want the compiler plus runtime separated from any single engine, and if you are willing to build the engine bindings yourself. Do not adopt it if you need a working dialogue runtime in a non-Unity engine today: the README lists Yarn Spinner for Unity as the only officially supported package, so Godot, Unreal and custom engines have no first-party path documented here.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 15 days ago.
- What is it written in?
- Mainly C#, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 24, 2026, and from our analysis. They are not legal advice.
Editorial analysis
What Yarn Spinner's core repository actually contains
The README is explicit that this repository is not the thing most people want. It says: "This repo contains the core source code for the Yarn Spinner compiler. If you want to use it in a game, you should get the appropriate package for your game engine." That single sentence defines the audience. You are in the right place if you are building an integration, porting the runtime to an engine the team has not covered, or working on the compiler itself. You are in the wrong place if you just want dialogue in your Unity game.
The repository layout backs this up. YarnSpinner.Compiler/ holds the compiler, YarnSpinner/ holds the engine-agnostic runtime components, YarnSpinner.Diagnostics/ holds diagnostics, and Tests/ plus YarnSpinner.Tests/ hold test projects. There is a YarnSpinner.sln solution file at the top level, plus shell scripts named antlr.sh, get-version.sh and sync-yarnspinner-dlls.sh. The presence of an ANTLR script is a useful signal about how the language is parsed, and the sync script suggests compiled assemblies are copied into other repositories rather than consumed as NuGet packages. The README does not describe a NuGet publishing step, so treat the DLL sync script as the distribution mechanism until you find evidence otherwise.
Licensing is MIT. The README also points at paid storefronts for the Unity package, which is a separate product from this repository. Those two facts are not in conflict, but they do mean the free path and the supported path diverge.
Lines, options and commands: the runtime contract
The mechanism is a small vocabulary. According to the README, when a conversation is running, Yarn Spinner sends your game three kinds of thing: lines of dialogue to show, options for the player to choose from, and commands that make something happen in your scene. Everything else in the system exists to produce and deliver those three signals.
That design is why the core can stay engine-agnostic. The compiler does not know what a sprite is, what a scene graph looks like, or how your UI renders text. It parses Yarn scripts and produces a program. Your game supplies a dialogue runner that feeds that program forward, and when the program reaches a line, an option set or a command, your code decides what to do with it. Commands are the escape hatch: they are how a writer says "play this animation" or "give the player this item" without the compiler needing to understand either.
The trade-off is real. You get portability across engines, but you also own the presentation layer. Text reveal speed, typewriter effects, voice-over sync, option button styling, and save and resume behaviour are all yours to build. The core repository gives you the parse and the execution model, not the UI. Teams that expect a drop-in dialogue box will be disappointed by this repository and should look at the engine-specific package instead.
Getting Yarn Spinner's core and a first compile
The README does not give step-by-step installation commands. It directs readers to the Yarn Spinner documentation to "install from Git", and points at the Unity Asset Store and Itch.io for the paid Unity package. The documentation site is therefore the place to start, and the repository layout is the only other guide to what the source tree expects.
What the layout tells you is that this is a C# solution: YarnSpinner.sln sits at the top level, alongside YarnSpinner.Compiler/, YarnSpinner/, YarnSpinner.Diagnostics/, Tests/ and YarnSpinner.Tests/. There are also shell scripts named antlr.sh, get-version.sh and sync-yarnspinner-dlls.sh. The ANTLR script relates to generating the parser from the grammar, and the sync script suggests compiled assemblies are copied into other repositories. On Windows you will need a POSIX shell or Git Bash to run those; the README does not document a Windows equivalent.
Because the README documents no build invocation, no compiler CLI and no package identifier, there is no command to reproduce here. The honest next step is to open the documentation site the README links to, follow its install-from-Git instructions, and then read the public types in YarnSpinner.Compiler to find the compile entry point. Do not guess at a CLI: the README does not describe one, and the test projects under YarnSpinner.Tests/ and Tests/ are the only worked examples in the repository of the compiler being driven.
Where the core repository leaves you on your own
The clearest limitation is support surface. The README's Official Packages section lists exactly one entry: Yarn Spinner for Unity, for 2021.3 or later. There is no official Godot package, no official Unreal package, and no official package for custom engines listed there. If you are working outside Unity, you are building the integration yourself, and the README does not promise that the runtime components are sufficient to do so without additional work.
A second constraint is the distribution model. The paid Unity package and the free MIT core are different things with different support expectations. Buying the Unity package supports the team and gets you the supported integration; cloning this repository gets you the compiler and the engine-agnostic pieces under MIT. If your plan is to ship a commercial game in Unity, the repository alone is not the product you want.
A third is documentation scope. The README repeatedly defers to docs.yarnspinner.dev rather than describing behaviour inline. That is fine for a landing page, but it means this repository's README will not tell you how to handle a specific runtime edge case, and it will not tell you what happens when a script fails to compile mid-conversation. Budget time for reading the documentation site and the test projects, because those are where the answers live.
Yarn Spinner versus Ink and Twine
The obvious comparison is Ink, the narrative scripting language from inkle. Both compile a writer-facing script into a program a game runs, and both keep the authoring format separate from the presentation layer. The difference in approach is in the execution model. Yarn Spinner's README describes a runner that emits lines, options and commands, which maps cleanly onto a scene that reacts to events. Ink's model is built around a story object that you step through and query for content, with a heavier emphasis on state you inspect yourself. If your dialogue needs to trigger things in a scene constantly, Yarn Spinner's command vocabulary is the more direct fit; if your priority is a branching narrative graph you query and render at your own pace, Ink's shape may suit you better. The README does not make this comparison, so treat it as a structural observation rather than a claim from the project.
Twine is a different category. It is an authoring tool that produces a playable hypertext, not a compiler you embed in a game engine. If you want a finished interactive story you can publish, Twine gets you there faster. If you want dialogue inside a 3D game with animations and inventory, Twine is not the tool, and Yarn Spinner's compiler-and-runtime split is the reason it can be.
The honest framing: Yarn Spinner is the choice when writers and programmers need a shared format and the game engine needs to stay in control of presentation. It is the wrong choice when you want the narrative tool to also be the game.
Maintenance, releases and what the MIT licence covers
The repository is not archived, and the last push was on 2026-09-16, which is recent. Releases are tagged and the most recent listed are v3.2.1 on 2026-05-05, v3.2.0 on 2026-03-27, and v3.1.0 on 2025-12-02. That cadence suggests steady work on the compiler and runtime rather than a dormant project. The CHANGELOG.md at the top level is where version-to-version changes are recorded; the README does not summarise them, so read the changelog before upgrading a pinned version.
Upgrade cost depends on how you consume the code. If you build from the solution, a version bump means rebuilding and re-running the tests against the new tag, then re-checking any code that touches the compiler or runtime public API. The sync-yarnspinner-dlls.sh script implies some consumers copy compiled assemblies into another repository, which turns every upgrade into a manual copy and a re-test in the consuming project. That is a maintenance burden worth knowing about before you adopt.
On licensing: this repository is MIT, which is permissive and does not require you to open your game's source. The Unity package sold on Itch.io and the Asset Store is a separate purchase with its own terms, and the README does not describe those terms. If you plan to ship commercially, read the licence that ships with the package you actually buy, not just LICENSE.md in this repository. Nothing here is legal advice.
Editorial conclusion
Adopt the core Yarn Spinner repository if you write dialogue in a screenplay-like format and want the compiler plus runtime separated from any single engine, and if you are willing to build the engine bindings yourself. Do not adopt it if you need a working dialogue runtime in a non-Unity engine today: the README lists Yarn Spinner for Unity as the only officially supported package, so Godot, Unreal and custom engines have no first-party path documented here. Before committing, verify three things: that your engine can consume the compiler output, that your build can restore the C# projects in YarnSpinner.sln, and whether the paid Unity package is acceptable to your budget. The core repository is MIT-licensed, so the compiler itself carries no purchase requirement.
Frequently asked questions
What is Yarn Spinner?
Yarn Spinner is a dialogue system that lets you write interactive conversations in a screenplay-like format, which can then be loaded into a game and run. This repository holds the core compiler and the engine-agnostic components; engine-specific packages are distributed separately.
Is Yarn Spinner free?
The core repository is MIT-licensed, so the compiler and engine-agnostic components are free to use. The README separately points to paid copies of the Unity package on Itch.io and the Unity Asset Store, which support the team behind the project.
How to install Yarn Spinner?
The README directs readers to the Yarn Spinner documentation to install from Git, or to the Unity Asset Store and Itch.io for the paid Unity package. This repository itself is a C# solution, so working with the core means cloning it and building YarnSpinner.sln with the .NET SDK.
How to use Yarn Spinner?
You write conversations in a screenplay-like format, compile them, and run them in your game. While a conversation runs, Yarn Spinner sends your game lines to show, options for the player to choose from, and commands that make things happen in your scene.
How to use Yarn Spinner with Unity?
The README lists Yarn Spinner for Unity as the officially supported package, targeting Unity 2021.3 or later, and points to the Unity Asset Store and Itch.io to buy it. The core repository in this article is the compiler, not the Unity integration.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/yarnspinnertool-yarnspinner)