Yarn Spinner for Unity 3.1 contains a number of improvements and useful changes.

Dialogue Runner Is Now More Async

The dialogue runner's StartDialogue and Stop methods are now async, and return a task. When you call StartDialogue, you'll receive a task (either a System.Threading.Tasks task, a UnityEngine.Awaitable, or a UniTask) that will complete after every dialogue presenter has finished running its OnDialogueStartedAsync method. Likewise, the Stop method will finish after every dialogue presenter has finished running its OnDialogueCompleteAsync method. This is really useful for making sure that you don't accidentally make a change to your scene in the middle of your dialogue presenters getting ready.

Dialogue Option Fallthrough

In Yarn Spinner, you can add a condition to the end of an option. If the condition evaluates to false, Yarn Spinner will mark the option as "unavailable". It's up to your game to decide what that means - you might want to make the option visible but unselectable, or you might want to hide the option from the player entirely. However, if every option is unavailable, the player has no option they could select. Previously, this could cause your game to have to soft-lock the player, since they weren't able to proceed.

In Yarn Spinner 3.1, dialogue presenters are now allowed to tell the Dialogue Runner that no option was selected at all. When this happens, Yarn Spinner will skip the options and move on to the next part of the script:

Lines Know Where They Came From

When Yarn Spinner sends a line to your game, it wraps up the line in an object called a LocalizedLine. Previously, if your game has multiple Dialogue Runners that are running at the same time, it wasn't possible to know which runner the line came from. In Yarn Spinner 3.1, the LocalizedLine now has a Source property that tells you where it came from.

Options Can Now Be Hurried Up And Cancelled

Just like how lines have a separate 'hurry up' and 'next' cancellation tokens that act as a signal to move things along, options now have the same 'hurry up' and 'next' tokens. (Previously, they only had a single cancellation token that signalled that option selection was no longer necessary.) This allows your game to signal that you want to hurry up the presentation of your dialogue's options.

New Typewriter System

We've updated the way that typewriters are used in the built-in Line Presenter system, to make it easier to customise. This is useful for when you want to take full control over how the line appears over time, and for when you want to have in-game events occur (like sound effects) as the line appears.

To create a custom typewriter, create a class that implements IAsyncTypewriter. You can find an example of how to write a custom typewriter in the source code for the LetterTypewriter class.

Removed Legacy DialogueView Classes

Yarn Spinner 3.0 introduced a new programming model for presenting dialogue, called Dialogue Presenters. As part of the rollout of this new API, we made the old DialogueView class act as a compatibility layer, and marked it as deprecated. Yarn Spinner 3.1 removes this deprecated code. If you have code that started life as a Yarn Spinner 2.0 project, you will need to migrate your legacy dialogue presentation UI code to use Dialogue Presenters.

Yarn Spinner is built by Yarn Spinner Pty. Ltd., an Australian company based in beautiful Lutruwita/Tasmania, Palawa/Tasmanian Aboriginal country, in Australia.

Yarn Spinner Pty. Ltd. was founded by the team that created Yarn Spinner—Jon Manning, Tim Nugent, and Paris Buttfield-Addison—all colleagues and contributors at Secret Lab, a game development studio, known for Night in the Woods, I Feel Fine, Leonardo's Moon Ship, the Australian ABC Play School games, and more.

Yarn Spinner is now maintained by the Yarn Spinner Pty. Ltd. team, including:

• Jon Manning

• Tim Nugent

• Paris Buttfield-Addison

• Mars Buttfield-Addison

You can find Yarn Spinner on Bluesky too!

Yarn Spinner Timeline

• v0.9 was released in October 2015, the first public release;

• v1.0 was released in January 2020;

• v2.0 was released in December 2021;

• v2.1 was released in February 2022;

• v2.2 was released in April 2022;

• v2.3 was released in July 2023;

• v2.4 was released in November 2023;

• v2.5 was released in December 2024.

• v3.0 was released in May 2025.

About Yarn Spinner Pty. Ltd.

Yarn Spinner Pty. Ltd. is a tools development company located in Hobart, Australia. Yarn Spinner designs and builds the open source Yarn Spinner project, and offers consulting, integration, and development services for custom Yarn Spinner integrations, features, and more.

Yarn Spinner's core team are also the founders and long-term team collaborators of Secret Lab Pty. Ltd.

About Secret Lab Pty. Ltd.

Secret Lab Pty. Ltd. is an independent games and creative technology studio located in Hobart, Australia.

Secret Lab has been enthusiastically building video games, apps, and technology to showcase culture, history, arts, and narrative experiences since 2008, and is the longest running games studio in Tasmania.

Secret Lab is proud to be the original creators of Yarn Spinner, and is best known for the BAFTA- and IGF-winning Night in the Woods, and is currently working on the interactive narrative game, I Feel Fine (written by Ryan North), and the adventure-puzzle game, Leonardo's Moon Ship (written by writer of Pixar's Ratatouille, Jim Capobianco).

You can hire Secret Lab to build your video games, interactive experiences, fancy apps, and more.

Welcome to Yarn Spinner! We're thrilled you're here.

This section will equip you with all the knowledge you need to write Yarn Spinner Scripts. Work through the following steps, one-by-one:

Once you've finished here in the Writing Yarn Scripts section, you will progress to the First Steps of using Yarn Spinner for Game Engines.

A .yarnproject file is a JSON file that tells Yarn Spinner which Yarn scripts to compile, how to find localised content, and other project configuration options.

Yarn Projects are used by the Yarn Spinner VS Code extension, game engines (Unity, Godot, Unreal), and the command line tools to understand how your dialogue files fit together.

Creating a Yarn Project File

You can create a .yarnproject file manually, or use your game engine's tools:

• Unity: Open the Assets menu and choose Yarn Spinner → Yarn Project

• Godot: Open Project → Tools → YarnSpinner → Create Yarn Project

• VS Code / Manual: Create a new file with the .yarnproject extension and add the JSON structure below

File Format

A .yarnproject file is a JSON document with the following structure:

The Yarn Spinner VS Code extension automatically detects .yarnproject files in your workspace. When a project file is present:

• Only files matching sourceFiles patterns (minus excludeFiles exclusions) are compiled

• Error checking and autocompletion use the project's configuration

• Commands and functions from your definitions file appear in autocomplete

If no .yarnproject file exists in your workspace, the VS Code extension will treat all .yarn files in the workspace as a single implicit project.

You can review the schemas for the Yarn Project (and other elements of Yarn Spinner) here: https://schemas.yarnspinner.dev/

Troubleshooting

Duplicate node errors

If you're seeing "More than one node is named..." errors, you likely have duplicate .yarn files being compiled. This can happen when:

• Build output or cache folders contain copies of your Yarn files

• Backup folders contain older versions of files

Solution: Add the duplicate locations to your excludeFiles array:

Files not being found

If your Yarn files aren't being detected:

1. Check that your sourceFiles patterns are correct

2. Verify the paths are relative to the .yarnproject file location

3. Use the ysc list-sources command to see which files match your patterns

If you're here, you've worked through the Beginner's Guide, and setup the Yarn Spinner Editor, and you're ready to dive into the details of writing dialogue with Yarn Spinner.

This section of the documentation will take you through the scripting fundamentals:

• combining Nodes, Lines, Options, and Jumps for simple interactive narratives

• using Detours, Variables, and Yarn Spinner's Flow Control features for more complex interactions

• the basics of Commands and Functions in Yarn Spinner

• running options Once, and Line Groups for flexibility and control

Once you've completed it, you can move to Advanced Scripting.

So far, you've learned how to use Nodes and Lines, Options, the Jump Command, the Detour Command, and Variables to write Yarn Spinner Scripts.

Because it's actually a full programming language of its own, Yarn Spinner also supports flow control.

Flow control takes several forms, including if statements, and conditional options.

if statements

In addition to storing information, variables are useful for controlling what's lines of dialogue are presented to the player. To do this, you can use if statements.

An if statement allows you to control whether a collection of content is shown or not.

When you write an if statement, you provide an expression, which is checked; if that expression evaluates to a true value, then all of the content in between the <<if>> and <<endif>> statements are run.

For example, consider the following Yarn Spinner Script:

This script will:

• set a variable, $gold_amount, to 5;

• show the line Player: I'd like to buy a pie!

• use an if statement to see if $gold_amount is less than 10, and if that is the case, which it will be in this example, show the line Baker: Well, you can't afford one!

elseif and else

You can use the elseif and else statements to handle different situations in an if statement.

An elseif statement has an expression that gets checked if the if statement, or any previous elseif statements, don't run.

An else statement doesn't have an expression, and runs if the if and any elseif don't run.

For example, consider the following Yarn Spinner Script:

This script will:

• set a variable, $gold_amount, to 5;

• show the line Player: I'd like to buy a pie!

• use an if statement to see if $gold_amount is less than 10, and if that is the case, show the line Baker: Well, you can't afford one!

  • otherwise use a elseif statement to see if $gold_amount is less than 15, and if that is the case, show the line Baker: You can almost afford one!

  • otherwise use a else statement to provide a fallback, which will show the line Baker: You can afford a pie!

• end the if statement block with an endif statement.

You can have as many elseif statements as you want inside an if statement block, and you can use whatever Operators you want inside, for example:

In this example:

• there are two variables, $gold_amount for tracking the player's currency, and $reputation for their reputation in town

• an if statement first checks if their $gold_amount is greater than or equal to 5 and whether their reputation is greater than or equal to 8, if both of these are true, then the line Merchant: You're rich enough and popular enough for me to serve you! is shown

  • otherwise the elseif statement checks if their $gold_amount is greater than or equal to 10 (making them very rich), or their $reputation is greater than or equal to 10 (making them very well regarded), and if either of these are true the line Merchant: I wouldn't normally, but I'll serve you! is shown

• if neither set of conditions is true, then the else statement means the line Merchant: You're neither rich enough nor important enough for me to serve! will be shown

Conditional Options

When presenting options to the player using the -> syntax, you may want to make some options not available. You can do this by adding a condition to the option, making it a conditional option.

For example, if you have a variable that tracks your player's reputation points, called $reputation, you might want to make certain options only available if the value of $reputation is high enough.

Conditions on options are done by adding an if statement to the end of the option. They look like this:

When Yarn Spinner runs this collection of options, it will check the expression inside the if statement. If the expression is false, then the option will be marked as unavailable.

Fallback Content in Options

If every option in a group is marked as unavailable, the game is allowed to tell Yarn Spinner that no option was selected. When this happens, Yarn Spinner will skip the options group, and run the next piece of content after the options.

Sometimes it's useful to create lines of dialogue that can only ever be displayed once.

In Yarn Spinner Scripts, you can use a once statement to denote content that can only be run one single time. When the script reaches a once statement, it checks to see if it’s run before. If it has, it skips over it! Magic.

There are two main ways you can use a once statement, which we'll explore below.

You can wrap some lines in <<once>> and <<endonce>>:

You can also use an <<else>> clause within the <<once>> statement, which will be run if the relevant <<once>> content has already been seen:

You can also add an if to the once to run content a single time, but only when a certain condition is true. In all other cases, it will be skipped (or the else content will be run, if there is any):

You can add <<once>> to a line, or options:

If you add once (or once if) to a line, that line will only appear once, and will be skipped over every other time it’s encountered:

Similarly, if you add it to an option, that option will only be selectable once, and will be marked as unavailable after it’s been selected.

once statements are really useful when you want to show long, detailed content the first time it’s encountered, but you don’t want to show it every time. This means that players don’t need to mash the ‘skip line’ button over and over when they realise that they’re starting to see a long run of lines they’ve already seen:

Smart variables in Yarn Spinner are a powerful way to improve your dialogue and narrative flows. Unlike regular variables that only change when explicitly set, smart variables recalculate their value every time they're accessed, based on the expression that defines them.

Why Use Smart Variables?

1. Code Readability: They make your dialogue scripts more readable by using meaningful names instead of complex conditions.

2. Centralised Logic: Define a condition once and use it throughout your game.

3. Maintenance: When game mechanics change, you only need to update the smart variable declaration, not every place it's used.

4. Abstraction: They hide complex game state checks behind simple, descriptive names.

Practical Examples

Creating a smart variable in Yarn Spinner is straightforward: <<declare>> command followed by a variable name (with the $ prefix) and assign it an expression rather than a static value. The expression can use mathematical operations, logical comparisons, or even reference other variables.

For example: <<declare $is_powerful = $strength > 50 && $magic_ability >= 20>>.

This smart variable will automatically update whenever the values of $strength or $magic_ability change, making your dialogue able to dynamically respond to the player's stats without additional code.

Example 1: Character Relationships

Example 2: Item Availability

Example 3: Time-Based Events

Benefits in Complex Games

Smart variables shine when you have conditions that you check frequently or that combine multiple factors. They're especially useful for:

• Tracking complex character states

• Monitoring game world conditions

• Representing player achievements or quest status

• Creating dynamic dialogue that responds to multiple game systems

By using smart variables, you make your dialogue scripts more intuitive and maintainable while keeping your game logic organised.

In Yarn Spinner, you can send instructions to your game through commands. Commands look like this:

Commands are sent to your game's Dialogue Runner, just like lines and options are. Commands are not shown to the player directly; instead, they're used for things like stage directions.

Yarn Spinner comes with some built-in commands; however, to get the most usefulness out of them, you'll want to define your own custom commands that make your game do what you need to.

Built-in Commands

There are two built-in commands in Yarn Spinner: wait, and stop.

wait

The wait command pauses the dialogue for a specified number of seconds, and then resumes. You can use integers (whole numbers), or decimals.

stop

The stop command immediately ends the dialogue, as though the game had reached the end of a node. Use this if you need to leave a conversation in the middle of an if statement, or a shortcut option.

Making Your Own Commands

You can create your own commands, so that your scripts can send directions to your game. For more information on how to create them in Unity games, see Creating Commands and Functions, in the Yarn Spinner for Unity section of the documentation, and equivalents for other engines.

A function is a block of code that provides a value to your Yarn scripts, which you can use in if statements, or store in variables.

In Yarn Spinner scripts, functions perform two main kinds of task:

• Functions let you get values that change over time, or that depend on other values. For example, the random function returns a different random number every time you call it.

• Functions let you get data from your game back into your scripts.

You call a function inside an expression. For example:

Built-In Functions

Yarn Spinner comes with several built-in functions for you to use.

visited(string node_name)

visited returns a boolean value of true if the node with the title of node_name has been entered and exited at least once before, otherwise returns false. Will return false if node_name doesn't match a node in project.

visited_count(string node_name)

visted_count returns a number value of the number of times the node with the title of node_name has been entered and exited, otherwise returns 0. Will return 0 if node_name doesn't match a node in project.

format_invariant(number n)

format_invariant returns a string representation of n, formatted using the invariant culture. This is useful for embedding numbers in commands, where the command expects the number to be formatted using the invariant culture. For example, <<give_gold {$gold}>>, which might end up as give_gold 4,51 in German, but give_gold 4.51 in English, can now be <<give_gold {format_invariant($gold)}>>, which will always be give_gold 4.51.

random()

random returns a random number between 0 and 1 each time you call it.

random_range(number a, number b)

random_range returns a random number between a and b, inclusive.

dice(number sides)

dice returns a random integer between 1 and sides, inclusive.

For example, dice(6) returns a number between 1 and 6, just like rolling a six-sided die.

min(number a, number b)

min compares a and b, and returns the smaller of the two.

max(number a, number b)

max compares a and b, and returns the larger of the two.

round(number n)

round rounds n to the nearest integer.

round_places(number n, number places)

round_places rounds n to the nearest number with places decimal points.

floor(number n)

floor rounds n down to the nearest integer, towards negative infinity.

ceil(number n)

ceil rounds n up to the nearest integer, towards positive infinity.

inc(number n)

inc rounds n up to the nearest integer. If n is already an integer, inc returns n+1.

dec(number n)

dec rounds n down to the nearest integer. If n is already an integer, dec returns n-1.

decimal(number n)

decimal returns the decimal portion of n. This will always be a number between 0 and 1. For example, decimal(4.51) will return 0.51.

int(number n)

int rounds n down to the nearest integer, towards zero.

Custom Functions

You can create your own commands, so that your scripts can send directions to your game. For more information on how to create them in Unity games, see Creating Commands and Functions, in the Yarn Spinner for Unity section of the documentation, and equivalents for other engines.

To give your dialogue more life and variety, you can also provide lines in a line group. When lines are in a line group, Yarn Spinner will choose one of them for you.

Line groups are collections of lines that begin with a => symbol:

title: Start
---
Captain: Navigator, fire the glitter torpedoes! That'll confuse the enemy ships!
=> Navigator: *sighs deeply* Sir, we don't have 'glitter torpedoes.' Those were in your dream last night.
=> Navigator: *eyes roll skyward* Captain, weaponizing craft supplies is not part of standard space combat protocol.
=> Navigator: *Slumps shoulders in defeat* I'll... make a note in the log that you suggested tactical glitter, sir.
===

In this example, the Captain will say "Navigator, fire the glitter torpedoes! That'll confuse the enemy ships!", and then Yarn Spinner will choose one of the subsequent lines to respond with.

=> Guard: Halt!
=> Guard: No entry!
=> Guard: Stop!

You can attach conditions to lines in a line group, to ensure that they only run when it’s appropriate to do so. Conditions can be any true or false expression, and can also be combined with the once keyword to ensure that a line can only run once:

A line in a line group can also have additional lines belonging to it, which will run if the item is selected.

If you're here, you've worked through the Beginner's Guide, setup the Yarn Spinner Editor, and learned the Scripting Fundamentals of Yarn Spinner.

Now it's time to look at some more advanced features, including:

• Node Groups, Storylets, and Saliency, for complex, responsive storytelling with Yarn Spinner

• Tags and Metadata, to give you flexibility on how your lines are handled in a game engine

• Markup, for providing hints on how narrative text should be displayed, as well as running commands in a game engine within lines

• Shadow Lines, for marking when a line is an identical duplicate of another line

• Writing Together, using the Live Share Extension for Visual Studio Code.

Once you've completed it, you're ready to use Yarn Spinner with a game engine, such as Unity

A tag is a piece of information that you can add to content in Yarn Spinner that adds additional context or detail about that content.

There are two places you can add tags in Yarn scripts: you can add them to nodes, and you can add them to lines.

Tags aren't shown to the user; instead, they're used by your game, or by Yarn Spinner itself.

Tags in lines

Tags can be added to the end of lines and options. Tags on lines start with a hash symbol (#), and cannot contain spaces. You can add as many tags as you like to line, but they must all be on the same line in the script.

Here's an example of a line with two tags:

Accessing tags

Tags that you add to a line can be accessed from your game. The way that you access them depends on your game engine. For example, to access them in a Unity game, you use the LocalizedLine.Metadata property.

Some tags are used by Yarn Spinner itself, while all others are used by your own code, so it's up to you what content they should have, and how to handle them.

Special tags

Certain tags are used internally by Yarn Spinner, or are added for you if they don't exist.

#lastline

The Yarn Spinner compiler adds a #lastline tag to every line that comes just before a set of options.

For example, the following excerpt:

is treated as though it had been written as:

In a Unity game, you can use this tag in a custom Dialogue View to be notified ahead of time when the player is about to be shown options.

#line

The #line tag uniquely identifies a single line or option across all of your game's dialogue. This is used to identify lines for localisation. Every line's #line tag must be unique. If a line or option doesn't have a #line tag, it will be automatically added for you.

Here's an example of some Yarn script with #line tags:

For more details (including what the tag should look like), see Adding Line IDs.

Tags in nodes

Nodes can also have tags, which you can use to add labels that describe the node.

Node tags they work a bit differently than line tags: they are defined in the header with the tags key, and they don't have to begin with a hash symbol (#).

Here's an example of a node with two tags:

You can access the tags on a node via the Dialogue object's GetTagsForNode method.

Other metadata

The metadata of a line is only composed of tags. Because of this, you may find that the Yarn Spinner code and documentation refer to line tags and line metadata interchangeably.

Nodes can have other metadata in their headers. This metadata isn't exposed through the API, which means it's mostly used to store additional information for whoever is writing the Yarn dialogue or for editors to make use of.

However, currently there is one header that defines specific behavior within the Yarn Spinner compiler: the tracking header.

The tracking header

Nodes can track whether they have already been visited during the game. For this to work, the Yarn Spinner compiler needs to add some special code to the node. To avoid creating this code for nodes that don't need it, the compiler only adds this code if it finds a call to the visited() function with the node name in it.

In some cases, you may need the compiler to add this special code to a node even if no corresponding visited() call exists. To direct the compiler to do this, include the tracking header with the value of always:

Additionally, using a value of never instructs the compiler to never add this special code to the node. If you use the visited function with a node set to never use tracking, it will always return false.

For more information on visit tracking, see the documentation for Functions.

Use cases

Tags and metadata may seem very complicated at first, and their uses may not be clear. The following example use cases explain how they can be used in your game. Keep in mind that this is not an exhaustive list of use cases.

Controlling attributes for an entire line

Yarn provides markup to let you change attributes for specific parts of a line. In case most of your attributes apply to entire lines (for example, the color of a line), it may be easier to just use tags instead.

Displaying the last line of dialogue along with options

The #lastline tag can be used to display the last line of dialogue along with any options. This is handled within your code by checking if a line has the #lastline tag, and if it does, storing it before continuing with the execution of the Yarn dialogue.

Internal workflows

Since metadata isn't shown directly to the player, you can use metadata for any internal workflows or tooling. For example, instead of tracking lines that need to be revised outside the Yarn files (which could lead to syncing problems), you could add line tags (such as #needsrevision) to the appropriate lines directly in the Yarn files, and process these lines as part of an internal tool or workflow. The Unity integration automatically generates a CSV file with all lines that contain metadata, making this super easy!

Localisation

As referenced before, the Yarn Spinner integration for Unity uses line tags to link localised dialogue lines. This is better explained in the Localization and Assets section, when using Yarn Spinner for Unity.

Aside from that, every piece of metadata can be used by translators and adapters to help them understand how the text is being used, thus leading to better localised text.

Showing specific lines of dialogue outside a dialogue window

Some games may require that certain lines of dialogue are displayed somewhere other than the dialogue window (for example, as flavor text for an item description, or in an item that acts as a log). Instead of manually duplicating these lines (which adds overhead during development and localisation), tags can be used along with code that checks for the tags and duplicates the lines while the game is running.

Markup allows you to add attributes into your text, like [a]hello[/a]. These attributes can be used by your game to do things like change the formatting of the text, add animations, and more.

When text is parsed, the tags are removed from the text, and you receive information about the range of the plain text that the attributes apply to.

Attributes

Attributes apply to ranges of text:

Yarn Spinner will take this text, and produce two things: the plain text, and a collection of attributes. The plain text is the text without any markers; in this example it will be:

Attributes represent ranges of the plain text that have additional information. They contain a position, a length, and their name, as well as their properties.

In this example, a single attribute will be generated, with a position of 4, a length of 5, and a name of "wave".

Attributes are opened like [this], and closed like [/this].

Overlapping Attributes

Attributes can overlap:

You can put multiple attributes inside each other. For example:

You can close an attribute in any order you like. For example, this has the same meaning as the previous example:

Self-closing Attributes

Attributes can self-close:

A self-closing attribute has a length of zero.

The Close-All Marker

The marker [/] is the close-all marker. It closes all currently open attributes. For example:

Properties

Attributes can have properties:

This attribute 'wave' has a property called 'size', which has an integer value of 2.

Short-hand Properties

Attributes can have short-hand properies, like so:

This is the same as saying this:

This attribute 'wave' has a property called 'wave', which has an integer value of 2. The name of the attribute is taken from the first property.

Property Types

Properties can be any of the following types:

• Integers

• Floats

• 'true' or 'false'

• Strings

Single words without quote marks are parsed as strings. For example, the two following lines are identical:

Whitespace Trimming

If a self-closing attribute has white-space before it, or it's at the start of the line, then it will trim a single whitespace after it. This means that the following text produces a plain text of "A B":

Showing Special Characters to the Player

You may want to show text containing the [ and ] characters to your player. To prevent the markup parser from treating as special characters, you can escape them. Text that has been escaped will be treated as plain text, and will not be interpreted by the parser.

There are two ways to escape your markup: escaping single characters, and using the nomarkup attribute.

Escaping single [ and ] characters

If you need to escape a single square bracket character, put a backslash \ in front of it:

This will appear to the player as:

The backslash will not appear in the text.

The nomarkup Attribute

If you want to escape a longer run of text, or if you have many square brackets, escaping a single character at a time can be cumbersome. In these cases, you may want to escape an entire region of text, using the nomarkup attribute. This attribute makes the parser ignore any markup characters inside it.

If you want to include characters like [ and ], wrap them in the nomarkup attribute:

This will appear as:

The character Attribute

The character attribute is used to mark the part of the line that identifies the character that's speaking.

Yarn Spinner will attempt to add this character for you, by looking for character names in lines that look like this:

The markup parser will mark everything from the start of the line up to the first : (and any trailing whitespace after it) with the character attribute. This attribute has a property, name, which contains the text from the start of the line up to the :. If a : isn't present, or a character attribute has been added in markup, it won't be added.

This means that the example above is treated the same as this:

You can use this to trim out the character names from lines in your game.

Text Replacement Markup

Certain attributes in Yarn Spinner's markup are replacement markers, which Yarn Spinner uses to insert or replace text based on the value of a variable.

There are three built-in replacement markers:

• The select marker uses the value of a variable to choose an outcome.

• The plural marker uses the value of a number to decide on the plural class for that number.

• The ordinal marker uses the value of a number to decide on the ordinal class for that number.

All three of these markers have a property called value, and use this to decide what text should be used in the line.

You can also make your own custom replacement markers.

select

The select marker is the simplest of the built-in replacement markers. It takes the value of the value property, and uses that to choose a replacement.

It's especially useful for when you need to insert a gendered pronoun in a line:

plural and ordinal

The plural and ordinal markers take a number in its value property, and use that to determine the plural or ordinal number class of that value.

Plurals across different languages

Different languages have different rules for how numbers are pluralised.

In many languages, the term you use to refer to a thing depends on the the number of that thing. This is known as a plural class: in English, you can have one apple, but many apples, and you have have one mouse, but many mice.

However, the rules vary significantly across different languages. English has two: "single", and "other". However, for example, Polish has multiple.

• In English, you say "one apple, two apples, five apples".

• In Polish, you say "jedno jabłko, dwa jabłka, pięć jabłek".

Notice how the Polish word for "apple", "jabłko", takes multiple forms as the number changes, whereas it takes two forms in English.

In Yarn Spinner, individual lines are replaced depending on the user's locale, but the logic surround them is not. This means that, if you want to be able to translate your game into multiple languages, you can't write Yarn code like this:

If you did it this way, the logic would only work for languages that have the same rules for plurals as English. (There are several of them that do, but far more that don't.)

Complicating this further, there are two main kinds of plural classes: cardinal plural classes, and ordinal plural classes.

• Cardinal plural classes are the kind we just saw (for example, "one apple, two apples").

• Ordinal plural classes refer to the positioning of a thing; in English, ordinal numbers are things like "1st, 2nd, 3rd."

As with cardinal plural classes, different languages have different ordinal plural classes.

Pluralising with plural and ordinal

Yarn Spinner is able to take a number and the user's current locale, and determine the correct cardinal or ordinal plural class of that number, for that locale. You can then use the plural class to decide on what text to show.

plural and ordinal have a property called value, just like select. They then have a property for each of the current locale's plural classes. These can be:

• one

• two

• few

• many

• other

The two markers differ based on what kind of plural class they work with:

• plural selects a number's cardinal plural class.

• ordinal selects a number's ordinal plural class.

Not every language uses every category; for example, English only uses "one" and "other" for cardinal plural classes.

For each of these properties, you provide the text that should appear.

For example:

You can include the actual value in the resulting text by using the % character. This character will be replaced with the value provided to the value property:

The ordinal marker works similarly, but uses the ordinal plural class:

Using makers in your game

You can also use markup to trigger events in your game from Yarn Spinner Scripts. To learn about this, check out the Inline Events Sample Guide.

In Yarn Spinner Scripts, shadow lines let you reuse the same line in multiple places, without having to create duplicate copies.

Shadow lines are marked using the #shadow: hashtag. When you use the #shadow: tag, you specify the line ID of another line, which is called the source line. The source line must have an explicit #line: hashtag to identify it.

Here’s a simple example of using shadow lines:

title: Tavern
---
Ava: Hello, barkeep!  
Guy: Hi there, how can I help? 
Ava: I should go. #line:departure
===

title: Kitchen
---
Ava: Greetings, chef!
Guy: What are you doing back here? 
Ava: I should go. #shadow:departure
===

The script contains six lines, but only 5 string table entries will be created, because the line “I should go” is shadowed.

Shadow lines are required to have the same text in the Yarn script as their source line, but are allowed to have different hashtags (in addition to the #shadow: and #line: hashtags).

Yarn Spinner for Unity is the set of components and scripts that make Yarn Spinner work inside a Unity project.

In this section, you’ll learn how to install, set up, and work with Yarn Spinner for Unity.

If you're here to get started, continue by diving into the Installation for Unity page.

Basic Yarn Spinner for Unity Usage

1. Install Unity 2022.3 or newer.

2. Create a new empty Unity project, by following the instructions in the Unity manual.

3. Install Yarn Spinner into the project, by following the instructions in Installation for Unity.

4. Add a Dialogue System to the scene:, by opening the GameObject menu and choosing Yarn Spinner -> Dialogue System.

5. Create a new Yarn Spinner Script, by opening the Assets menu and choosing Create -> Yarn Spinner -> Yarn Script. Name the new file HelloYarn.

6. Open the new Yarn script by double-clicking it.

   1. Select all of the text in the file, and delete it.

   2. Copy the text below, and paste it into the file.

1. Save the file and return to Unity.

2. Create a new Yarn Project that uses this script, by selecting the HelloYarn file, and clicking the Create New Yarn Project button in the Inspector. This will create a new Yarn Project called Project. Projects are collections of Yarn scripts that get compiled together, and can be used with a Dialogue Runner.

3. Make the Dialogue Runner use the Project by dragging the Project you just made into the Dialogue Runner's Yarn Project field.

4. Play the game by clicking the Play button at the top of the window. Your dialogue will appear!

The Welcome sample is the launching point for the Yarn Spinner samples. It doesn't cover anything in of itself, it is a quick tour of every sample.

Welcome has Capsley standing in front of a projector showing slides of each sample in the package. Each sample is clustered into one of four categories:

• Basic

• Presenters

• Extending

• Advanced

Yarn Spinner version 3 introduces a powerful new way to trigger events during dialogue presentation. While previous versions required custom implementations for in-line actions, v3 provides the IActionMarkupHandler interface. This system notifies handlers about key line presentation events, enabling you to respond at specific moments.

This approach offers tremendous flexibility for creating various inline events. Our sample demonstrates two practical applications: character movement and facial expression changes during dialogue presentation.

This guide explores the contents of the Inline Events Sample.

What we'll be covering

• The new IActionMarkupHandler interface

• The new ActionMarkupHandler class

• Using these with the Line Presenter to trigger events

• Two implementations: character movement and animation changes

The Action Markup Handler

The IActionMarkupHandler interface provides a structured approach to handling in-line actions during dialogue presentation. At its core, the system works by having the Line Presenter display dialogue one character at a time, notifying handlers throughout the process. This creates multiple opportunities to trigger events at precise moments.

The interface defines methods corresponding to different stages of the line presentation lifecycle:

1. Initial Preparation (OnPrepareForLine): Called immediately after the line is received but before any UI elements appear.

2. Display Start (OnLineDisplayBegin): Called just before characters begin appearing, but after UI elements are visible.

3. Character Display (OnCharacterWillAppear): Called each time a character in the line is about to be displayed.

4. Display Completion (OnLineDisplayComplete): Called after all characters in the line have been shown.

5. Dismissal (OnLineWillDismiss): Called just before the line will be dismissed.

Notably, OnCharacterWillAppear is an asynchronous method. The line presentation system will await each Action Markup Handler's completion before continuing, allowing events of any duration to occur at any point in the dialogue.

Yarn Spinner also provides ActionMarkupHandler, a MonoBehaviour implementation of this interface, for situations where you need component-based functionality. The Line Presenter includes a serialized field for directly connecting ActionMarkupHandler subclasses, as demonstrated in our sample.

The Sample

Our sample showcases two types of action markup: moving the player character and changing NPC facial expressions. Both are implemented as ActionMarkupHandler subclasses and connected to the Line Presenter through its Event Processors field.

Movement

The movement implementation resides in the MoveEvent.cs file as an ActionMarkupHandler subclass. Most of the functionality is contained in the OnPrepareForLine method.

This method scans all markup in the current line, searching specifically for the move markup tag. When found, it extracts the name property from the marker and uses it to locate a corresponding in-scene marker with the same name. The target location and the marker position within the text are stored in a dictionary for later use.

During line presentation, the OnCharacterWillAppear method checks if the current character position corresponds to a stored location. If so, it moves the player character to that position before continuing.

This allows for dialogue lines such as: Player: So what, just part way through I stop talking... [move name="far" /] ...and move on over?

When presentation reaches position 49, it will pause, the player character will move to the GameObject named "far", and then the dialogue will resume.

Emotion

The facial expression system is implemented in EmotionEvent.cs as another ActionMarkupHandler subclass. The primary logic is also in the OnPrepareForLine method.

This implementation first uses the character name from the dialogue line to find a corresponding GameObject. It then retrieves the SimpleCharacter component (a sample-specific type, not part of Yarn Spinner core) from this GameObject. After these preparations, it processes all markup in the line, looking specifically for emotion tags. The emotion property value is extracted and stored for later use.

During presentation, OnCharacterWillAppear checks if there's a cached emotion corresponding to the current position. If found, it uses this value to change the character's facial expression animation. Unlike the movement example, this change happens instantly without pausing dialogue progression.

This enables dialogue lines like: Alice: Yes... which I would have shown [emotion="angry" /] had you not interrupted me.

When presentation reaches position 32, the facial expression of the "Alice" GameObject will instantly change to whatever animation corresponds to "angry" while the dialogue continues uninterrupted.

Storylets and Saliency are a new feature of Yarn Spinner 3 that has quite a few different pieces to making it work. Because of this we have multiple samples dedicated to demonstrating these.

The samples are not about the concept of storylets and saliency, if you are new to this and wondering what this all means, then we highly recommend our Storylets and Saliency Primer.

The samples assume you are comfortable now with both the concepts of storylets and salient content and writing them in Yarn Spinner.

There are three samples around using storylets and saliency in Yarn Spinner for Unity:

• Basic Storylets and Saliency goes over the basics of using storylets in your games

• Custom Saliency Strategies looks at how you can create custom saliency strategies

• Advanced Saliency demonstrates using storylets and interpolation together to build entire dynamic stories and events.

Yarn Spinner is always free and open source. To help offset the costs of designing, building, and supporting Yarn Spinner, we provide a number of add-ons as paid extras to make implementing Yarn Spinner in your games easier for you.

At the moment, these include:

• Text Animator for Yarn Spinner

• Dialogue Wheel for Yarn Spinner

• Speech Bubbles for Yarn Spinner

Text Animator for Yarn Spinner is included in the Itch.io and Asset Store versions of Yarn Spinner for Unity. Dialogue Wheel and Speech Bubbles for Yarn Spinner are individual purchases, and can be used with the free version of Yarn Spinner for Unity.

Dialogue Wheel and Speech Bubbles are available as separate purchases on the Yarn Spinner Itch.io Store or via the Unity Asset Store.

This section of the Yarn Spinner documentation provides guides for the available add-ons.

Speech Bubbles for Yarn Spinner ships with two example scenes, showcasing the flexibility of the Speech Bubbles.

2D Sidescroller

The 2D Sidescroller Example showcases the flexibility of the Speech Bubble in a variety of contexts, including both the Formal Bubble, and the Casual Bubble. Once you've installed the package, find this example in Speech Bubbles for Yarn Spinner/Examples/2D Sidescroller.

3D Top-Down

The 3D Top-Down Example showcases the Speech Bubbles in a 3D environment, with a variety of small customisations. Once you've installed the package, find this example in Speech Bubbles for Yarn Spinner/Examples/3D Top-Down.

Yarn Spinner for Unity is made up of a number of components. The most important of these are the Dialogue Runner, which loads and runs your scripts, and the Dialogue Views that show content to your player.

In this section, you'll learn about how to work with each of these.

The Line Presenter and Options Presenter are handy for many situations. But your game might need to show lines and options in a particular way. When that's the case, you can write your own custom Dialogue Presenter. This gives you full control over how lines and options appear.

Creating a Dialogue Presenter

To make a Dialogue Presenter, you first create a subclass of the DialoguePresenterBase class. Then, you add this subclass as a component to a game object in your scene. After that, you can add this game object to the Dialogue Presenters list on your scene's Dialogue Runner.

Presenting Lines and Options

By itself, an empty subclass of DialoguePresenterBase won't do much. You need to implement specific methods to make it show lines and options.

To get how custom Dialogue Presenters work, it helps to understand how the Dialogue Runner handles content. Yarn Spinner scripts use three types of content: lines, options, and commands. Only the first two, lines and options, need to be shown directly to the player.

When the Dialogue Runner finds lines or options, it first figures out the exact content the player needs to see. Once it has this, it sends the content to each of its Dialogue Presenters.

Your scene can have several Dialogue Presenters. And they can all do different things. For instance, you might have one Dialogue Presenter for lines, another for options, and a third for playing voice-over audio.

Getting Localised Content

In compiled Yarn Spinner Scripts, Lines and Options are represented by line IDs. A line ID is a unique code for the text of a line or an option. When Yarn Spinner needs to show a line or option, it asks its Line Provider for a LocalizedLine object. This object holds the text for the line or option in the player's current language.

If you're showing a group of options, each option in that group has its own LocalizedLine.

Once a LocalizedLine is ready, the Dialogue Runner has everything it needs to show content. What happens next depends on whether it's showing a line or an option.

Presenting Lines

When Yarn Spinner comes across a line of dialogue, it calls the RunLineAsync method on every Dialogue Presenter. This method gets two things: first, the LocalizedLine from the Line Provider, and second, a LineCancellationToken. The Dialogue Presenter uses this token to know the line's status. Specifically, it checks if the player wants to speed up the line's display or move to the next line.

In Dialogue Presenters, a line is considered "presented" when the player has seen the whole line and is ready for the next one. What this means in practice varies. For example, a Dialogue Presenter playing voice-over audio might finish when all the audio has played. Another one that shows text gradually might finish when all text is visible and the UI has faded out.

The Dialogue Runner waits until all Dialogue Presenters say they've finished showing the line. Then, it moves to the next bit of dialogue.

The RunLineAsync method is asynchronous. This means a Dialogue Presenter signals it's done and ready for the next line by returning from the method.

If your game needs to pause dialogue until the player does something (like press a button), your Dialogue Presenter can do this. It simply doesn't return from the RunLineAsync method until the line cancellation token signals to advance. Because the Dialogue Runner waits for all presenters, the dialogue will pause until your presenter says to go on.

Hurrying and Advancing Lines

Line presentation usually isn't instant. It typically happens over a short period. So, players might want to speed this up or skip it entirely. Dialogue Presenters need to be ready for the player to ask for a line to hurry up or be skipped at any moment during presentation.

The line's state is held in the LineCancellationToken given during the RunLineAsync method. This token wraps two other Cancellation Tokens: one for advancing to the next line, and one for making the current line hurry. These tokens are linked. So, if the "next line" token is flagged, the "hurry up" token will be too. But it doesn't work the other way around.

Most times, you won't need to access these tokens directly. You can check the line's status using handy properties. IsHurryUpRequested on the token tells your custom Dialogue Presenter if the player wants the display to go faster. And IsNextLineRequested tells you if your Dialogue Presenter should skip the current line completely.

Any part of line presentation that isn't instant should use these properties. This helps decide if they should speed up or be skipped. The same LineCancellationToken is shared by all Dialogue Presenters. So, if the line's status changes, all presenters see it at the same time. Each Dialogue Presenter decides what "hurrying up" means for it; it's a signal to finish the presentation quickly.

For example, a voice-over presenter might fade out audio quickly or cut it off. A text-revealing presenter might show all remaining text at once or very rapidly. Advancing a line is a more direct signal that the player wants the dialogue to move on. You shouldn't ignore IsNextLineRequested when it's true. Presenters should clean up and finish showing the line as soon as possible if the player has asked to advance.

You can change the LineCancellationToken's state using the Dialogue Runner. It has two methods for this. RequestHurryUpLine sets the token so IsHurryUpRequested becomes true. RequestNextLine sets the IsNextLineRequested flag to true. Since the LineCancellationToken wraps two linked tokens, these methods also cancel those internal tokens. Requesting the next line also means requesting the line to hurry up. You can safely request a line advance or hurry up multiple times; it won't cause any issues.

Presenting Options

Options are a bit different from lines. They need some kind of player input before the dialogue can go on. The Dialogue Runner needs to know which option was picked.

To manage options, Dialogue Presenters implement the RunOptionsAsync method. This method gets an array of DialogueOption objects and a cancellation token. Each DialogueOption object is an option that can be shown to the player.

When this method is called, the Dialogue Presenter uses the info in the DialogueOption objects to show choices to the player. Then it waits for player input. Once it knows which option was selected, the method should return that chosen option. The Dialogue Runner then uses this to make the selection.

If your presenter doesn't need to handle options, it can return a null value instead.

The Dialogue Runner will ignore any nulls it gets back from presenters here. The first non-null DialogueOption it receives is treated as the selected one.

When the Dialogue Runner sends options to its Dialogue Presenters, it expects only one of them to return a non-null option. If none of them return an option, the Dialogue Runner will never know what was picked. And it will wait forever, and ever, and ever.

If more than one presenter returns an option, the Dialogue Runner uses the first one it gets and ignores the others. After getting a non-null option, the Dialogue Runner cancels the cancellation token given in the method. This tells any presenters that haven't returned yet that an option has been selected. So, they can stop waiting for a selection.

Accessing Line Metadata

To get the tags on a line, you use the Metadata property on the LocalizedLine objects you receive. Your code decides what to do with these tags.

Variable Storage components are responsible for storing and retrieving the values of variables in your Yarn scripts. When a Yarn script needs to get the value of a variable, it asks the Variable Storage for it; when a Yarn script sets the value of a variable, the Variable Storage is given the value.

Each game has different requirements for how variables are stored, which means that Yarn Spinner doesn't make any assumptions how the information is actually stored on disk. Instead, you can create your own custom Variable Storage script that implements the methods that Yarn Spinner needs.

If you don't connect a Variable Storage to your Dialogue Runner, it will create an In-Memory Variable Storage when the game starts, and use that.

The In-Memory Variable Storage component is a Variable Storage component that stores all variables in memory. These variables are erased when the game stops.

Inspector

The Built-in Localised Line Provider is a Line Provider that fetches localized text or audio assets (AudioClip) for a line of dialogue, given the user's language.

The Built-in Localised Line Provider will automatically use Addressable Assets, if the Addressables package is installed in your Unity project and the Yarn Project is configured to use Addressable Assets.

Inspector

Yarn Spinner 3 transitions from the callbacks and coroutines approach of versions 1 and 2 to an asynchronous programming model. This guide explores what this means for your development, how to use these new features, and important considerations when implementing async code.

What we'll be covering

• Basics of asynchronous programming and async and await keywords

• Supported awaiters

• Creating your own async code

• How to cancel awaited code

• Using completion sources

Async Programming

Asynchronous programming isn't drastically different from traditional approaches. In many ways, it's a refinement of the coroutine pattern with some syntax changes and additional capabilities.

At its core, async programming provides a way to write code that performs operations asynchronously. This means your code doesn't block program execution when encountering long-running tasks (such as those spanning multiple frames).

To illustrate this concept, let's use a simple analogy: imagine you are a computer making a cup of tea. Your process might look like this:

1. Fill the kettle

2. Boil the kettle

3. Add tea to the cup

4. Add the water to the cup

5. Add milk to the cup

6. Drink the tea

In non-async code, each step blocks execution - while waiting for the water to boil, you'd be frozen, unable to respond to other inputs or perform other tasks. In async code, these steps remain non-blocking. You can respond to other events while still monitoring the kettle. You'll still wait for the water to boil before proceeding to the next step (you're not performing tasks in parallel), but you won't block the entire system during that wait.

As a developer, you decide which code segments should be async and which should execute synchronously. Ideally, this distinction shouldn't complicate your code's readability or logical flow. That's the essence of async programming.

async and await keywords

The primary distinction between asynchronous programming and traditional approaches is the introduction of new keywords. The most significant is await, which tells C# to pause execution at that point until the specified asynchronous operation completes, then resume from there.

You can use await with any method flagged as asynchronous or any method returning an awaiter (more on these shortly). This brings us to the async keyword, which must be added to method signatures that contain awaiting calls. Unity will report errors if you try to await code in a method without the async keyword, or if you include async in a method that doesn't await anything.

These keywords represent the main syntactic differences. While there's considerable complexity enabling asynchronicity under the hood, you rarely need to concern yourself with those details. Simply await asynchronous code and add asyncto methods that perform awaiting operations.

This approach brings an additional benefit: it makes asynchronous code easily identifiable. With a quick glance at keywords and method signatures, you can understand which code executes asynchronously and which code awaits other operations, resulting in cleaner, more maintainable code.

Async vs Coroutines

You might wonder, "Can't we accomplish all this with coroutines?" It's a valid question. Coroutines have served Unity developers well for years and are widely understood. However, they have several limitations that make async programming a superior alternative in many cases.

First, coroutines cannot return values. While workarounds exist, they're exactly that - workarounds. Async methods can naturally return values without additional complexity.

Second, coroutines lack cancellation context. To stop a coroutine, you need external management code to maintain references and handle cancellation, which becomes increasingly complex with nested coroutines. Moreover, coroutines receive no notification when cancelled, forcing external code to handle cleanup. Async code addresses this through cancellation tokens, which provide cancellation signals allowing code to clean up after itself and propagate cancellation to other async operations it calls. Similarly, exceptions thrown in coroutines can't be caught by the initiating code, whereas async code enables centralized error handling.

Coroutines are also tied to MonoBehaviours. While often convenient, this can force unnecessary Unity dependencies in code that otherwise wouldn't need them, such as networking components.

Additionally, coroutines run on the main thread. This is typically appropriate, but makes offloading work to other threads cumbersome. Async code supports multi-threading more elegantly (though for heavily threaded operations, the Jobs system remains preferable).

Finally, coroutines don't clearly signal their intent in method signatures and call sites. They return IEnumerator, giving no indication they represent long-running operations. The difference between StartCoroutine(MyCoroutine()) and MyCoroutine() isn't immediately obvious, and editor-mode coroutines require a completely different approach. Async code uses consistent syntax across all contexts with clear signaling of intent.

While coroutines do work and have some minor advantages, their quirks often lead to more complex, harder-to-maintain code compared to async alternatives.

Awaiters

The underlying infrastructure for asynchronous programming extends beyond this guide's scope, but different systems provide the necessary components to support awaiting operations. You can think of these as containers for awaited work that can be queried, cancelled, or ignored. Awaiters notify when their work completes, allowing code execution to continue.

Yarn Spinner supports three types of awaiters:

• Tasks

• Awaitable

• UniTask

We've implemented a system that detects and uses the most appropriate awaiter for your project. We prioritize UniTask if installed, falling back to Awaitables, and finally to Tasks if no other options exist.

This behavior is encapsulated in our YarnTask awaiter. YarnTask wraps one of the above awaiters and provides conversion methods between different awaiter types, making it easier to use Yarn Spinner with your preferred awaiter system. In most cases, you won't need to think about this - simply using await with the appropriate code segments should work seamlessly.

Tasks vs Awaitables vs UniTask

While these three awaiter types are similar, each has distinct characteristics worth noting.

Tasks are part of C# rather than Unity, meaning they lack integration with Unity's run loop and GameObject lifecycle. Without careful management, this can lead to unexpected behaviors like GameObject movement after exiting play mode. Tasks also have the highest memory and performance overhead of the three options (though still relatively modest). However, they offer the most extensive API with numerous convenience methods and flexibility - a trade-off for being the most generic option. Tasks are recommended only as a last resort when better alternatives aren't available.

Awaitables are a relatively recent Unity addition. They provide Task-like functionality for common asynchronous Unity operations with awareness of the run loop and GameObject lifecycle. They're more lightweight but less flexible than Tasks. One important caveat: cancelled Awaitables throw exceptions that must be caught - a necessity of their implementation rather than a design flaw, but still a notable difference from Tasks. We recommend Awaitables over Tasks, and most newer Unity versions support them.

UniTask is a third-party asynchronous library that combines the tight engine integration and lightweight footprint of Awaitables with many quality-of-life features from Tasks. Like Awaitables, UniTask throws exceptions when awaited code is cancelled, requiring exception handling. It's our recommended approach for asynchronous programming in Unity.

As mentioned earlier, we've created a YarnTask wrapper awaiter. This isn't intended to replace any of the above options, but rather to provide a convenience layer supporting as many developers and Unity versions as possible.

Making async code

Let's explore creating basic async code by converting a coroutine to an async approach. We'll use a simple example of moving a cube from one position to another over time.

First, here's how you might implement this as a coroutine:

You would start it like this:

Now, let's convert this to an async implementation:

And to start it:

Cancellation

Next, let's add cancellation support - after all, what good is a moving cube if its movement can't be stopped?

Now we can clean up when cancelled - in this case, jumping to the end position, though cleanup could mean many different things depending on your implementation.

To use this cancellation feature:

Each MonoBehaviour includes a token that's cancelled when the MonoBehaviour receives the Destroy call. However, this isn't particularly useful here, since we're more interested in cancelling movement before destruction. Let's create a new cancellation token linked to the destroy token that we can cancel independently:

Now we have a token we can cancel whenever needed, but because it's linked to the destroy cancellation token, destruction will still cascade cancellation downward. This nesting can be as deep as required, with cancellation propagating through the entire chain with a single call.

We should also handle any exceptions that might be thrown:

To test cancellation, we can trigger it in response to user input:

You can safely call cancel multiple times without negative consequences, as the tokens handle this gracefully. With that, we've created a fully async and cancellable cube movement system!

Returning Values

Moving cubes is useful, but we're still performing tasks without communication. Let's return a value from our async method. Imagine creating a custom dialogue option selector that rolls a die and selects the option corresponding to the result:

Then in our RunOptionsAsync method, we await the roll and use the result to select an option:

Notice we're using a generic form of YarnTask, where the generic type specifies the return type: YarnTask<int> for the dice roller and YarnTask<DialogueOption> for the dialogue option selection. We don't need to explicitly return a YarnTask<T> (though we can) - C# is smart enough to infer the appropriate return type.

Completion Sources

The final major async component is completion sources. These are particularly useful for converting non-asynchronous code, especially UI with callbacks like buttons, to work with async patterns.

A completion source allows external objects to set a completion result, which other code can await like any other async task. For example:

In your custom presenter code, you might use this like:

Now the line will wait for the user to press the button before continuing.

Completion sources can also return values. This is how the default options presenter works - each option item receives the same completion source, and when selected, it sets the completion source with the chosen option:

The selected value is then returned to the dialogue system:

Conclusion

You now have a foundational understanding of async programming and how it's implemented in Yarn Spinner. This knowledge is essential for creating custom dialogue presenters and other interactive components in your Yarn Spinner projects.

Yarn Spinner Timeline

• v0.9 was released in October 2015, the first public release;

• v1.0 was released in January 2020;

• v2.0 was released in December 2021;

• v2.1 was released in February 2022;

• v2.2 was released in April 2022;

• v2.3 was released in July 2023;

• v2.4 was released in November 2023;

• v2.5 was released in December 2024.

• v3.0 was released in May 2025.

• v3.1 was released in November 2025.

Yarn Spinner 3

Yarn Spinner 3 came out in May 2025, adding new features to run content only once, enumerations, smart variables, and storylets and saliency!

Yarn Spinner 2

Yarn Spinner 2 debuted in July 2020, adding markup support, dialogue views, and lots lots more!

Yarn Spinner 1

After being developed for Night in the Woods, and staying in early-release for several years, Yarn Spinner 1 was released in January 2020!

This gets you from zero to running dialogue in about five minutes. It assumes you already know how to write Yarn, and how to use Godot.

Install the Plugin

Grab the plugin from https://github.com/YarnSpinnerTool/YarnSpinner-Godot-GDScript

1. Copy addons/yarn_spinner/ into your Godot project's addons/ directory.

2. Go to Project > Project Settings > Plugins and enable Yarn Spinner.

Add Your Yarn Files

Make sure you have a .yarnproject and your .yarn files, then drop them into your Godot project. The .yarnproject tells the compiler which .yarn files to include.

Automatic compilation

If ysc (the Yarn Spinner Console tool) is on your system PATH, compilation is automatic. Whenever Godot imports or reimports the .yarnproject, the plugin runs ysc compile for all .yarn files in scope. Editing a .yarn file or the .yarnproject itself triggers a reimport, so you never need to compile manually.

Install ysc globally from https://github.com/yarnspinnertool/yarnspinner-console

Manual compilation

If ysc isn't on your PATH, you can compile manually:

You can also set the path to ysc in the import options for the .yarnproject file in the Godot inspector, or in Project Settings > Yarn Spinner > YSC Path.

Set Up the Scene

Here's a minimal scene tree exmple:

1. YarnDialogueRunner -- add a Node, attach the YarnDialogueRunner script. In the inspector, set Yarn Project to your .yarnproject file.

2. LinePresenter -- add a PanelContainer, attach the YarnLinePresenter script. Give it a RichTextLabel child named TextLabel for dialogue text, a Label named CharacterLabel for the speaker name, and optionally a Label named ContinueIndicator.

3. OptionsPresenter -- add a PanelContainer, attach the YarnOptionsPresenter script. Give it a VBoxContainer child named OptionsContainer -- buttons are created automatically at runtime.

Wire It Up

In your game script, connect the presenters to the runner and start dialogue:

That's it. Run the scene and your dialogue plays.

Commands

Commands let Yarn tell your game to do things. The easiest way is the naming convention -- prefix any method with _yarn_command_ and the runner finds it automatically.

Make sure auto_discover_commands is enabled on the dialogue runner (it is by default). The runner scans the scene tree on startup and registers everything it finds.

If a command returns void, dialogue continues immediately. If it returns a Signal, dialogue pauses until that signal fires.

Instance Commands

For commands that target specific nodes (like <<move mae center>>), define the method on the node's class:

Register the class as an instance command source:

Now <<move mae center>> finds the node named "mae", checks it's a Character, and calls _yarn_command_move("center") on it.

Functions

Functions let Yarn read values from your game. Register them with a name and parameter count:

Use them in Yarn expressions:

Or use the naming convention with _yarn_function_ prefix for auto-discovery.

Variables

Yarn variables work automatically. Declare them in your .yarn files and they're stored in an in-memory dictionary:

Access them from GDScript:

The runner creates a YarnInMemoryVariableStorage automatically. If you need persistence, subclass YarnVariableStorage and assign it in the inspector.

Signals

The dialogue runner emits signals for lifecycle events:

Useful Settings

On the YarnDialogueRunner in the inspector:

• Start Node -- which Yarn node to begin from (default: "Start")

• Auto Start -- begin dialogue when the scene loads

• Run Selected Option As Line -- after the player picks an option, show it as a line of dialogue before continuing

• Auto Discover Commands -- scan the scene tree for _yarn_command_* and _yarn_function_* methods

On YarnLinePresenter:

• Typewriter Mode -- INSTANT, LETTER (character by character), or WORD

• Characters Per Second / Words Per Second -- typewriter speed

• Auto Advance -- automatically continue after a delay

• Use Markup -- enable BBCode rendering in the text label

On YarnOptionsPresenter:

• Hide Unavailable -- hide options the player can't pick (vs showing them greyed out)

Custom Presenters

To make your own persenter UI subclass YarnDialoguePresenter:

Register it the same way:

Node Groups and Saliency

If you're using node groups (multiple versions of the same content with when: conditions), set a saliency strategy on the runner:

Available strategies: YarnFirstSaliencyStrategy, YarnBestSaliencyStrategy, YarnRandomSaliencyStrategy, YarnBestLeastRecentlyViewedSaliencyStrategy, YarnRandomBestLeastRecentlyViewedSaliencyStrategy.

This section covers Yarn Spinner for Godot (C#).

Yarn Spinner for Godot is the set of components and scripts that make Yarn Spinner work inside a Godot project.

In this section, you’ll learn how to install, set up, and work with Yarn Spinner for Godot.

Just getting started with Yarn Spinner for Godot? Start with installing the plugin in your project.

There are two important kinds of files you'll use when working with Yarn Spinner for Godot:

• Yarn Projects are files that link your Yarn Scripts together, and are used by the Dialogue Runner.

• Yarn Scripts are files that contain your written dialogue.

A Dialogue Presenter is a component that receives content from a Dialogue Runner, and presents it to the player. Dialogue Presenters are how the player sees your game's lines of dialogue, and how they select choices in the dialogue.

A Dialogue Runner can have multiple Dialogue Presenters. For example, in most situations, you'll have a Dialogue Presenter that's designed to display lines of dialogue and another that's in charge of displaying options to the player.

Every game's needs are different, a Dialogue Presenter is designed to be extremely customisable, and you can create your own Dialogue Presenters to suit the needs of your game.

Because there are common patterns of how games work with dialogue, Yarn Spinner for Unity comes with some pre-built Dialogue Presenters that handle common use cases:

• Line Presenter is a Dialogue Presenter that displays a single line of dialogue in a text box that's inside a canvas, and shows a button that the user can click to proceed.

• Options Presenter is a Dialogue Presenter that displays a collection of options in a list.

Yarn Spinner is a set of friendly tools for writing interactive narratives and games.

Try Yarn Spinner online at try.yarnspinner.dev!

Yarn Spinner is easy for writers to use, but also has powerful features for programmers, game designers, narrative directors, producers, and more.

Try Yarn Spinner online at https://try.yarnspinner.dev

Yarn Spinner is used in thousands of amazing games, including Rift of the Necrodancer, Demonschool, Night in the Woods, A Short Hike, Lost in Random, Dredge, Frog Detective, Button City, Escape Academy, Baladins, and Unbeatable.

New? Start Here!

Scripting Fundamentals

Advanced Scripting

Yarn Spinner for Unity

Unity Add-Ons

Community Discord

Show us your game

Crediting Yarn Spinner

FAQ

Story Solver

Yarn Spinner for Godot

Yarn Spinner for Unreal

What to do next

Yarn Spinner powers amazing games, including:

... use it to power your game too!

Yarn Spinner 3 is out! It's the culmination of 10 years of Yarn Spinner development, taking inspiration from how people use Yarn Spinner in wildly successful and amazing games like DREDGE, Lil' Guardsman, A Short Hike, and Demonschool.

For the development of Yarn Spinner 3, stewardship of Yarn Spinner moved from our original game development studio, Secret Lab, to a whole new entity focused solely on Yarn Spinner development. It's now our primary job!

Yarn Spinner is developed in the open on GitHub, and can be purchased from the Yarn Spinner Itch.io Store or the Unity Asset Store.

Yarn Spinner 3 introduces so many improvements and new things, and makes writing complex interactive narratives easier than ever.

Get started with Yarn Spinner 3 via the Beginner's Guide!

Yarn Spinner powers amazing games, including:

... use it to power your game too!

Writing Yarn with Try Yarn Spinner

When you first start learning Yarn, you can use Try Yarn Spinner, our introductory, browser- based tool for writing Yarn Spinner Scripts. No installation necessary!

What did we just do?

We just wrote a simple Yarn Spinner script consisting of one node (titled Start), with one line inside that node, delivering a greeting from a narrator.

Then we added two more nodes, a jump command, and some options, with jumps occuring depending on the option chosen.

And that's the very basics of Yarn Spinner Scripting! Dive into the Fundamentals of Writing Yarn Scripts next.

Thank you for using Yarn Spinner! 💚 This page contains information on how to use the Yarn Spinner name and logo in projects that make use of Yarn Spinner, or in media coverage of Yarn Spinner.

The core of Yarn Spinner is provided to you under the terms of the MIT License. This means that if you use Yarn Spinner in a game, software, or any other work, you are required to include a copy of the MIT license in that work.

You can find a copy of Yarn Spinner's MIT license here:

The MIT License (MIT)

Copyright (c) Yarn Spinner Pty. Ltd., Secret Lab Pty. Ltd., and Yarn Spinner contributors.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

You are required to include a copy of this with your game. There's no firm rules as to how you do this. We have some suggestions, though:

• on a screen in your game, along with other software licenses

• in a file that lists all licenses related to your game

• in an accompanying PDF, or similar, electronic manual or documentation

Basically, as long as a copy of Yarn Spinner's version of the MIT license is distributed with your game, you're good to go.

In addition to including a copy of the Yarn Spinner's MIT license in your game, please include Yarn Spinner in your game's credits, such as the initial splash screen, or in your end-game credits, or somewhere else of your choosing.

To credit Yarn Spinner, we give you permission to use our logo, which is available for download below.

You may also choose to credit us in text. We suggest the following:

Dialogue powered by Yarn Spinner — https://yarnspinner.dev

You can reword this however you'd like, but we'd prefer if you kept the name 'Yarn Spinner', and the link to the website.

Yarn Spinner® is a trademark of Secret Lab Pty. Ltd., the original creators, and is licensed to Yarn Spinner Pty. Ltd, which is a spinoff company to look after the project.

For the purposes of crediting Yarn Spinner, acknowledging that you're using Yarn Spinner, or discussing, teaching, or tutorialising Yarn Spinner and other simlar uses, we give you permission to use the Yarn Spinner name and logo on packaging, promotional/advertising materials, splash screens, in publications, seminars, conference talks, and web sites, and anything else in relation to your Yarn Spinner-powered software.

Rules for building products with Yarn Spinner support

Please adhere to the following if you build a non-game product or tool that supports Yarn Spinner:

1. The "Yarn Spinner" trademark or the word "Yarn" cannot be part of a product name (e.g. "Big Talk for Yarn Spinner") unless we have given you written permission (you would have had to email us for that).

2. The Yarn Spinner trademark can be used in a referential manner or alongside a referential phrase (e.g. "SimOptometrist is built with Yarn Spinner", "Aunty Edna's Grand Adventure uses Yarn Spinner", "Big Talk is compatible with Yarn Spinner", "Bobby Yarner teaches Yarn Spinner", "Learn Yarn Spinner with Dr Eyeballs");

3. The game, or project that you're including the Yarn Spinner trademark must, in fact, work with, use, or relate to Yarn Spinner in some way;

4. The use of the Yarn Spinner trademark cannot imply endorsement, sponsorship, or an inaccurate representation of the relationship between you, your game/project, and the Yarn Spinner project, team, Yarn Spinner Pty. Ltd., or Secret Lab Pty Ltd;

5. The use of the Yarn Spinner trademark should not show Yarn Spinner, the Yarn Spinner team, Yarn Spinner Pty. Ltd., Secret Lab Pty Ltd, or any related group or entity in an false or derogatory manner, or in association with any hate speech, or criminal or illegal activities.

6. If you make a product that suports Yarn Spinner, please direct your users to install Yarn Spinner via the Unity Asset Store or Itch.io in the first instance. Do not automatically install Yarn Spinner via OpenUPM or as a Unity Package from GitHub through your product or tool unless we have given you written permission to do so.

If you have any questons on this, ask the Yarn Spinner team in the Discord, tweet at us, or email us at legal AT yarnspinner.dev — we're friendly, and really just want to help.

Yarn Spinner logos

When you use the Yarn Spinner trademark, logo, or brand to credit Yarn Spinner in your game (or other work), you should try your best to conform your use to our brand guidelines.

You may not edit, modify, distort, recolour, or change the Yarn Spinner logo unless you show us what you've done (and receive our approval), or ask our permission. We're happy for you to totally diverge from our colours and branding, if we talk about it with you, so please email us at legal AT yarnspinner.dev to chat — we're friendly, we promise!

You can download a copy of the Yarn Spinner logo for inclusion in your credits below. We explicitly give you permission to use these logos to credit Yarn Spinner in your games, in accordance with the guidelines on this page:

FAQ for Yarn Spinner

FAQ for Yarn Spinner Scripts

FAQ for Yarn Spinner for Unity

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

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);

Back in the Beginner's Guide, you learned the basics of Yarn Spinner Scripting by using our online tool, Try Yarn Spinner.

While Try Yarn Spinner is great for the basics, and for experimenting, when you start creating more complex narratives, you need a great editor! It's time to meet Yarn Spinner for Visual Studio Code.

Yarn Spinner for Visual Studio Code

Yarn Spinner for Visual Studio Code is an extension for the free text editor, Visual Studio Code ("VS Code").

Yarn Spinner for Visual Studio Code gives you syntax highlighting for Yarn Spinner Scripts, as well as a graph view that displays the nodes, and relationships between the nodes, and a whole bunch of other useful features that we'll be exploring as we learn the to write Yarn Spinner Scripts using Visual Studio Code.

If you've never used to VS Code before, head to their official website and install it for your operating system and platform before continuing.

Don't be too alarmed by the AI-powered nonsense Microsoft will try and sell you. You can disable most of the AI "features" via the Command Palette by pressing Shift + Command + P (Mac) or Ctrl + Shift + P (Windows/Linux), or choosing the View menu -> Command Palette..., and typing Chat: Hide Copilot and hitting Return/Enter:

Installing Yarn Spinner for Visual Studio Code

Once you've got VS Code installed on your system, you'll need to install Yarn Spinner for Visual Studio Code. To do this:

That's all you need to do to install the extension! You're ready to write and edit Yarn Spinner Scripts in Visual Studio Code.

Now that you've got Visual Studio Code and Yarn Spinner for Visual Studio Code installed, it's time to learn how to use it to write Yarn Spinner Scripts.

Opening a Folder

Open VS Code and click the Open button on the welcome screen, or choose File → Open Folder, and select the folder containing your .yarn and .yarnproject files.

When the folder opens, the Yarn Spinner sidebar will appear showing your projects, their definition files, yarn files, and localisation settings.

You can also open an empty folder and create everything from scratch using the extension.

Creating a New Project

If you don't have a .yarnproject file yet, you can create one in the active folder:

1. Open the Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows/Linux)

2. Type "Yarn Spinner: Create New Yarn File" or use the new file button in the sidebar

3. The extension will create a .yarnproject file and a starter .yarn file for you

The .yarnproject file is the heart of your project. It controls which files are included, your compiler settings, and your editor preferences. You can open it to see and edit your project configuration in a visual editor.

You can also choose to create a new Yarn Spinner project from a template in the sidebar.

If you do this, you can choose from a few pre-made templates:

Verifying the Extension is Active

With a .yarn file open, look at the bottom left corner of VS Code for the words Yarn Spinner and a tick. This confirms the extension is installed and recognises your file.

The Yarn Spinner sidebar (the speech bubbles icon in the activity bar) shows all your projects, their files, and their status, as found in the open folder.

Features of the Extension

Use the text editor to write your .yarn files. The extension provides:

Extension Settings

You can open the Extension Settings from the Yarn Spinner Sidebar:

Syntax Highlighting

Yarn Spinner scripts are colour-coded so you can easily distinguish dialogue lines, commands, options, variables, and comments. The extension includes custom light and dark themes designed specifically for Yarn Spinner.

You can set the theme scope in Extension Settings — choose Whole Editor to always use the Yarn Spinner theme, or Yarn Files Only to automatically switch themes when you move between yarn files and other files.

Autocomplete

The extension offers autocomplete suggestions as you type:

• Node names — when writing <<jump>> or <<detour>> statements, you'll see a list of all nodes in your project

• Variable names — when using variables, previously declared names are suggested

• Commands and functions — if your project has a .ysls.json definitions file, custom commands and functions from your game code are suggested with their parameter types and documentation

Hover Information

Hold Cmd (macOS) or Ctrl (Windows/Linux) and hover over:

• Node names in <<jump>> statements to see a preview, or click to navigate to that node

• Variables to see their type, default value, and documentation comment

• Commands and functions to see their signature, parameters, and documentation from your game code

Variable Documentation

When you <<declare>> a variable, add a documentation comment with /// above it:

/// How many times the player has visited the shop
<<declare $shop_visits = 0>>

This description appears in hover tooltips and autocomplete suggestions whenever the variable is used.

Error Checking

The extension validates your scripts in real time:

• Type errors — assigning the wrong type to a variable (e.g. a number to a boolean)

• Missing nodes — jumping to a node that doesn't exist

• Syntax errors — malformed commands, missing delimiters

• Undeclared variables — using a variable without declaring it (when requireVariableDeclarations is enabled)

Errors and warnings appear as squiggly underlines in the editor and in the Problems panel.

Spell Checking

The extension integrates with VS Code's spell checking. You can configure it per-project in the .yarnproject editor:

• Enable or disable spell checking

• Add custom words (character names, made-up terms, game-specific vocabulary)

The Graph View

While Yarn Spinner is a text-based language, the extension provides a visual Graph View to help you understand the structure of your dialogue.

Opening the Graph View

Click the Show Graph button in the top right corner of the editor when a .yarn file is open, or use the graph view panel in the sidebar.

File View

The default view shows nodes from the currently open .yarn file. Use the toggle in the graph view toolbar to switch modes between the current file and the whole project.

• Drag nodes to rearrange them — positions are saved in the node's position header automatically

• Double-click a node to jump to it in the text editor

• Click "Show in Graph View" above any node in the text editor to find it in the graph

• Arrows show <<jump>> connections between nodes

• Dashed arrows show <<detour>> connections

• Cross-file jumps appear as small stub nodes showing the destination file and node name, with an arrow connecting to them — so you can see where your dialogue leaves the current file

Project View

Switch to Project view using the toggle in the toolbar to see every node across every file in your project at once.

In project view:

• Each .yarn file is shown as a container with its nodes inside

• Cross-file jumps are shown as dashed coloured lines between file containers

• Drag file containers to arrange your project layout — positions are saved in your .yarnproject file

• Colour file containers by selecting one and using the colour picker toolbar that appears

• Align containers using the alignment buttons at the bottom (align left, right, top, bottom)

• Auto-layout the entire project vertically or horizontally

• Double-click an inner node to open that file at that node in the text editor