Yarn Spinner isn’t a single project, but is a collection of projects that work together.

For writing

• Yarn, the language you write your dialogue and narrative in: you write Yarn scripts in Yarn. The same Yarn scripts work in every engine Yarn Spinner supports.
• Yarn Spinner for Visual Studio Code, the extension for the free text editor Visual Studio Code, that gives it an understanding of the Yarn language, and helps you write Yarn scripts, with a graph view, a preview, and other features. See Yarn Spinner Editor.
• Try Yarn Spinner, a website where you can write Yarn scripts and play them in your browser. See Try Yarn Spinner.

For running your dialogue in a game

• Yarn Spinner for Unity, for games you build in Unity. See Yarn Spinner for Unity.
• Yarn Spinner for Godot, for games you build in Godot. There are two versions: one written in GDScript, and one written in C#. See Yarn Spinner for Godot.
• Yarn Spinner for Unreal, for games you build in Unreal Engine. It’s in pre-release, with its final release coming very soon. See Yarn Spinner for Unreal.

Add-ons

Add-ons give you ready-made dialogue presenters and other features on top of Yarn Spinner, like Dialogue Wheel and Speech Bubbles for Unity, and Classic RPG and Snaaake for Unity and Godot. Get them from the Yarn Spinner itch.io Store or the Unity Asset Store, or read the documentation.

We make and support Yarn Spinner for three engines:

Your Yarn scripts are the same no matter which engine you use, so everything in Writing Yarn applies to all of them.

There’s also Yarn Spinner for Rust, for the Bevy engine.

Use the version that matches the language your game is written in. If your game uses GDScript, use Yarn Spinner for Godot (GDScript). It works in the standard version of Godot, and doesn’t need .NET. If your game is written in C#, and you use the .NET version of Godot, use Yarn Spinner for Godot (C#).

Yarn Spinner is developed in the open, on GitHub, and there’s always a free version you can install from there.

If you want to use Yarn Spinner for a commercial game, we recommend buying it from our itch.io Store, or for Unity, the Unity Asset Store. Buying Yarn Spinner is the most direct way to support the team that makes it. Yarn Spinner for Unreal is free on GitHub.

Different parts of Yarn Spinner use different licences, and where you got Yarn Spinner can change the licence too. Check the licence files in the version you have. Whichever version you use, please credit Yarn Spinner in your game.

You can also contact us for a custom licence, or hire us to add features especially for you!

No. Yarn Spinner has no generative AI features, and we don’t use code generation tools to build it. We’ve written about why we don’t use AI.

We’ve added a lot of new features, including Once, Detour, Line Groups, Node Groups, and more. Yarn Spinner has a lot of features designed for storylets and saliency, and you can learn about those by reading through the Saliency guides here.

My text is not displaying at all?

You need to install the TextMeshPro Essential Resources. Open the Window menu -> TMP -> and choose Import TMP Essential Resources.

How do I style text? How do I make some words bold, italic, colorful, etc?

Yarn Spinner doesn’t directly do text rendering, we use TextMeshPro to do the final render which has support for rich-text.
However, writing TMP tags across a project is impractical so we have provided various styles and palettes via Yarn Markup Attributes.
These provide a collection of common visual changes as well as offer a common interface
There is a sample showing off using the built in markup to style your text as well as how you can make your own Markup to do more advanced styling on your text.

How do I animate wavy text, like in Night In The Woods?

Yarn Spinner doesn’t handle text rendering. You’ll need a separate wavy text system, like Text Animator.

How do I use Yarn Markup?

Markup lets you mark a range of text (words, phrases) in a generic way, for whatever use. You could use it to style text, add sentence markers, make clickable words, etc.

// Yarn script example of custom "wavy text" markup.
Oh, [wave]hello[/wave] there!

// After compiling, text will look like: "Oh, hello there!"
// And then the resulting markup data will look like:
// - name: "wave"
// - position: 4
// - length: 5

Note that YS only processes the text data. You must still code the actual markup effect yourself. See Markup.

How do I print the value of a variable in dialogue?

Wrap the variable (or any expression) in curly braces ({, }) to evaluate and output it. For more info, see Variables.

<<set $variableName to "a string value">>
The value of variableName is {$variableName}.
// This will appear as "The value of variableName is a string value."

How do I read / write Yarn variables from a C# script?

You can register to be notified when a variable changes. To do this, in C#, call AddChangeListener() on a Line Provider and provide a delegate that should run when the variable changes:

var stringListener = VarStorage.AddChangeListener("$stringVar", (string value) =>
{
    Debug.Log($"$stringVar changed to " + value);
});

When you no longer need to be notified of changes to a variable, you call Dispose() on the listener. If you don’t do this, the variable storage will continue to call this delegate every time the variable changes, which you probably don’t want to do.

stringListener.Dispose();

If you’re implementing your own variable storage system, you must call the NotifyVariableChanged() method every time a variable changes value, in order to notify any change listeners:

public override void SetValue(string variableName, float floatValue)
{
    // (code for updating the variable omitted)
    // Notify the change listeners that this variable changed
    NotifyVariableChanged(variableName, floatValue);
}

Alternatively, to read Yarn variables from C#, use VariableStorageBehaviour.TryGetValue<T>().

To write Yarn variables from C#, use VariableStorageBehaviour.SetValue().

variableStorage = GameObject.FindObjectOfType<InMemoryVariableStorage>();
float testVariable;
variableStorage.TryGetValue("$testVariable", out testVariable);
variableStorage.SetValue("$testVariable", testVariable + 1);

You should also check out our Variables and Storage section.

How do I read / write C# variables from a Yarn script?

To read and write C# variables from Yarn, you must first code Yarn Functions and Commands in C#.

static int myNumber = 10;

// note: all Yarn Functions must be static
[YarnFunction("getMyNumber")]
public static int GetMyNumber() { 
    return myNumber; 
}

// Yarb Commands can be static or non-static
[YarnCommand("setMyNumber")]
public static void SetMyNumber(int newNumber) { 
    myNumber = newNumber;
}

Then call the functions and commands in Yarn:

My number is { getMyNumber() }!
<<setMyNumber 999>>
But now it's { getMyNumber() }!

How do I ‘sync’ variables between Yarn and C#?

See the previous answers on working with variables. But we recommend avoiding any “sync” pattern, because then you’ll have to track and maintain the same data in two different places. Programmers usually prefer a “single source of truth”.

Data should live in only one place. Variables should either live in Yarn or live in C#, and not in both.

How do I load and save data / variables / dialogue state? (Like for a save game system)

To save the current node, save the value of DialogueRunner.CurrentNode somewhere. Then to restore it, call DialogueRunner.StartDialogue() and pass in the saved node name.

To save variables, see DialogueRunner.SaveStateToPersistentStorage(). Then to load variables, call DialogueRunner.LoadStateFromPersistentStorage(). These methods use Unity’s built-in JSON utility to serialize a dictionary of variables to the current platforms persistent data path folder.

For custom save systems, create your own variable storage by subclassing VariableStorageBehaviour and implementing its methods. Study InMemoryVariableStorage.cs as an example. For more info, see Guide: Yarn Variables and Variable Storage.

How do I jump to a specific node? How do I switch nodes while dialogue is running?

To jump to a node from Yarn, use <<jump (nodeName)>>. See Nodes, Lines, and Options.

To jump to a node with C#, just call DialogueRunner.StartDialogue().
While you can jump to another node while dialogue is running we recommond not doing this and calling DialogueRunner.Stop() before starting another piece of dialogue.

How do I jump to a specific line in a node?

Jumping to a specific line in a node is currently not supported. Instead, jump to the start of a node.

How do I continue dialogue with key/button press instead of clicking the continue button?

This is demonstrated by the Line Advancer component, which handles this exact scenario (among others).
We recommend looking at how it handles the different ways of hurrying up or advancing lines as a starting point for your own games.

How do I show the last line of text when options are shown? How do I skip the last line of text before a set of options?

Yarn Spinner automatically adds a #lastline tag to a line when the next step is a set of options. Create a Custom Dialogue Presenter that uses YarnProject.lineMetadata.GetMetadata() to check for “lastline” and perform the behavior you want.

How do I customize dialogue display?

To display anything in Yarn Spinner, use a Dialogue Presenter component.
There are two in-built presenters that demonstrate the basic functionality Line Presenter for lines of dialogue, Options Presenter for dialogue choices.

Most projects will need custom presenters.
We recommend a modular architecture where each presenter handles it’s own specific part of the display.
An example of this is in the built in presenters the Line Presenter only handles showing lines, and the Options Presenter which only handles choices.

How do I make the Line Presenter’s Typewriter pause?

You can pause the typewriter effect by using the built in pause markup:

Player: Sure would be nice if I could take a breather [pause /]  right now.

How do I play a Yarn node when I click / tap on an object?

Write input code to detect clicking / tapping, then call DialogueRunner.StartDialogue().

How do I play a Yarn node when I approach an object and press a button? (RPG-like talking to NPCs)

This implementation will vary for every game, so we purposely do not attempt to design a one-size-fits-all generic NPC system. Here’s some example pseudo-code to make your own:

if (player presses SPACE)
    then find the nearest NPC
    get that NPC's dialogue node name
    call DialogueRunner.StartDialogue() with the NPC's dialogue node
    disable player movement

The samples do have a shared script called the Dialogue Interactible which show off one way to achieve this behaviour.

How do I position a speech bubble above an NPC’s head, like in A Short Hike?

The math / code is a little complicated. Calculate the NPC’s on-screen position, then convert this screen position to UI canvas space, and reposition the dialogue bubble.
We do have a paid add-on that handles all of this (and more) for you if you’d prefer to just have it all working.

How do I implement a resizing dialogue bubble / SMS messaging interface?

This is more about Unity UI rather than Yarn Spinner. For a working example, see the Phone Chat sample.

To make a resizing dialogue bubble that automatically fits text, you will need a complex UI setup. Study the UI game objects and components in the sample scene. For more context about how it works, see this Unity UI Layout Groups explainer by Hallgrim Games.

How do I get text from a Text Input field into my Yarn story?

This mainly involves Unity UI, and assumes that your project already has a system where a player can input text like a TMPro Input Field component. If the player input needs to happen in the middle of dialogue execution then you can trigger it with a Yarn Command and wait for the player input if needed.

Once you have the player input value, you can store it in a C# variable and access it through a Yarn function, or store that value in a Yarn story variable. FAQs for how to access variables in Yarn and YarnSpinner are here.

How do I generate a Yarn Project at runtime? How do I load/compile Yarn scripts at runtime?

The intended workflow is to generate and compile Yarn Projects at editor time, not runtime. See Yarn Projects.

How many Yarn files should I have? Can my entire game be in one project or script? Or one project per scene? Is my project or file too big?

There is no real technical limit on the number of Yarn scripts or the size of Yarn Projects. You decide how to organize your data, and every project has different needs. Some factors to consider:

• Simplicity. Putting everything into one big script file or one big project file is simpler sometimes.
• Ease of writing. Writers may prefer to think in terms of one file per scene, one file per chapter.
• Localization. 1 Yarn Project = 1 CSV spreadsheet per language. When translating, it is usually easier to work with fewer files, rather than fragmenting the translation across many files. As a workaround for games that need multiple Yarn Projects, you may prefer to create a single editor-only Yarn Project that’s just for generating string files and translations. See Localizations and Assets.

How do I fetch any Yarn localized string in C#?

Some devs use YS to manage all in-game localized text, like UI strings. This use isn’t intended, but it’s possible. Manually create a Yarn.Line struct, set the line ID (see Localization), and then pass the struct into GetLocalizedLine().

Yarn.Line targetLine = new Yarn.Line();
targetLine.ID = "line:lineid"; // replace 'lineid' with the actual line ID
LocalizedLine outputLine = LineProvider.GetLocalizedLine(targetLine);
Debug.Log(outputLine.Text.Text);

I installed the samples package and there are no samples in the package manager, what gives?

For some reason when you install the samples package from the Unity Asset Store it has two entries inside the Package Manager.
Only one copy of the samples package is installed, you don’t have duplicates of the assets and scripts, it just appears in the list twice.

The first of these entries, under the Packages - Asset Store section has no samples, or even a samples tab.
The second entry underneath Packages - Yarn Spinner Pty Ltd section has the samples.
We are currently seeing if we can make this better, but for now if you select the second entry it will have the samples tab and you can install samples from there.

How do I credit Yarn Spinner in my game?

Please visit the Crediting Yarn Spinner page for more information.

Are there any examples of Yarn Spinner implementations in Unity?

Yes! We ship a whole collection of Samples.

How do I start dialogue from GDScript?

Call start_dialogue() on your Dialogue Runner, with the name of the node to start from:

dialogue_runner.start_dialogue("Start")

To stop dialogue that’s running, call stop_dialogue(). See Starting and stopping dialogue.

How do I customise how dialogue looks?

Dialogue is shown by Presenters. Start with the built-in Line Presenter and Options Presenter, or build your own Presenter.

How do I make my own Commands and Functions?

Register them with the Dialogue Runner using add_command() and add_function(). See Commands and Functions.

How do I save and load Yarn variables?

The Dialogue Runner can save every variable to a file in Godot’s user:// folder, and load them back:

dialogue_runner.save_state_to_persistent_storage("dialogue_save.json")
dialogue_runner.load_state_from_persistent_storage("dialogue_save.json")

Only the variables are saved, not where the dialogue is up to. To pick a conversation up again, save the name of the node you want to start from, and pass it to start_dialogue() after loading. See Variables and Storage.

Is Yarn Spinner for Unreal ready to ship a game with?

Yes. Yarn Spinner for Unreal is in pre-release now, and we expect to move it to its final release very soon. It’s free on GitHub. See Installation.

Can I use Yarn Spinner for Unreal from Blueprints?

Yes. You can start dialogue, add Commands, and save and load variables from Blueprints or from C++.

How do I start dialogue?

Call StartDialogue() on your Dialogue Runner, or use its Blueprint node, and call StopDialogue() to stop it. See Starting and stopping dialogue.

How do I make my own Commands and Functions?

Use the Register Command Handler node, or AddCommandHandler() in C++. See Commands and Functions.

How do I save and load Yarn variables?

Use the Save Variables To Slot and Load Variables From Slot nodes, or the same functions in UYarnBlueprintLibrary from C++. See Variables and Storage.