FAQ

Yarn Spinner isn't a single project, but is a collection of projects. Conceptually, we think of Yarn Spinner as having Core Components, some Add-ons, and some Yarn Labs Experiments.

Core Components

These are production-ready components, with stable, established, released versions:

• Yarn, the language you write your dialogue and narrative in: you write Yarn Spinner Scripts in Yarn.

• Yarn Spinner for Visual Studio Code, the extension for the popular free text editor, Visual Studio Code, that gives it an understanding of the Yarn language, and helps you to write Yarn scripts, with a graph visualisation tool, and other features.

• Yarn Spinner for Unity, the package you use to import and use your Yarn scripts in games you build in Unity.

• Try Yarn Spinner, an online tool that allows you to write Yarn scripts and Play them in a web browser. It's useful to write basic Yarn, and test things out. It's just a you can visit!

⭐️ To learn to use the Core Components, jump into the .

Add-ons

These are projects that supply additional features to Yarn Spinner, and exist as add-ons to the free, open source projects that comprise the bulk of Yarn Spinner:

• Dialogue Wheel for Yarn Spinner, an add-on package for Yarn Spinner for Unity that provides Mass Effect-style dialogue wheel dialogue presenters.

• Speech Bubbles for Yarn Spinner, an add-on package for Yarn Spinner for Unity that provides customisable speech bubbles as dialogue presenters.

⭐️ To purchase the Add-ons, , or the , or just .

Yarn Labs Experiments

These are experimental projects that are likely to eventually be released into Core, but are currently in early, or experimental stages:

• Yarn Spinner for Unreal, the package you use to import and use your Yarn scripts in games you build in Unreal.

• Yarn Spinner for Godot, the package you use to import and use your Yarn scripts in games you build in Godot.

• Yarn Spinner for Rust, the package that you use to import and use your Yarn scripts in games you build using the Rust-based Bevy engine.

Start learning

If you're new to Yarn Spinner, we recommend that your next step is

Yarn Spinner is developed in the open, as open source software on GitHub. You can also install it from the source on GitHub, for free.

If you want to use Yarn Spinner for a commercial game, we recommend purchasing it from our Itch.io Store or the Unity Asset Store. You can also contact us for a custom license, or to arrange consulting, support, or hire us to add features especially for you!

We've added a lot of new features, including Once, Detour Command, 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 .

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.

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

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.

​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:

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

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

You should also check out our section, and the guide.

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

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

Then call the functions and commands in Yarn:

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 .

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 somewhere. Then to restore it, call and pass in the saved node name.

To save variables, see . Then to load variables, call . These methods use Unity's built-in JSON utility to serialize a dictionary of variables to the current platforms .

For custom save systems, create your own by subclassing VariableStorageBehaviour and implementing its methods. Study as an example. For more info, see .

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 component. There are two in-built presenters that demonstrate the basic functionality for lines of dialogue, 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:

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:

The samples do have a shared script called the 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 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 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 .

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. .

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 .

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.