Yarn Spinner is the friendly tool for writing dialogue in games. It's easy for writers to use, and has powerful features for programmers.

Yarn Spinner is free and open source and has been used in thousands of amazing games, including Night in the Woods, A Short Hike, Lost in Random, Dredge, Frog Detective, Button City, Escape Academy, Baladins, and Unbeatable.

Yarn Spinner is not just a single project or tool, but is a collection of projects and tools. It consists of a language to write your narratives in—Yarn—and tools to display, and use your Yarn in game engines, like Unity, and tools to translate, localize, and connect voice over to your stories.

To get started, dive into the Beginner's Guide.

While Yarn Spinner for Rust is built to be engine-agnostic, the intended way to use it is through an engine-specific wrapper. The currently only supported engine is Bevy. It is a data-oriented game engine using an ECS, which broadly means that you don't look at your game world through the traditional lens of objects mutating the world and each other, but instead see the game as a collection of data attached to various entities that can be queried and manipulated through systems.

This chapter will assume that you are familiar with the basics of Bevy. If you're not there not, try to come back after you've gone through the Bevy Book.

Installing Yarn Spinner for Rust

Let's create a new Rust project called hello_yarnspinner. Type the following into your terminal:

cargo new hello_yarnspinner
cd hello_yarnspinner

Then, let's add our dependencies:

cargo add bevy bevy_yarnspinner bevy_yarnspinner_example_dialogue_view

Setting up Bevy Yarn Spinner

Plugins

Open up the generated src/main.rs and remove its content. Now let's import our dependencies:

use bevy::prelude::*;
use bevy_yarnspinner::prelude::*;
use bevy_yarnspinner_example_dialogue_view::prelude::*;

Now on to the main function. Let's start by adding all necessary plugins.

fn main() {
    let mut app = App::new();
    app.add_plugins((
        DefaultPlugins,
        YarnSpinnerPlugin::new(),
        ExampleYarnSpinnerDialogueViewPlugin::new(),
    ));
}

DefaultPlugins is necessary for Bevy to do much at all. YarnSpinnerPlugin sets up all functionality of Yarn Spinner except for any actual graphical interface. In order to see anything on screen, you need a Dialogue View. We are using a simple one provided by the ExampleYarnSpinnerDialogueViewPlugin here.

Systems

Now we need the game to actually do something. We will do this by registering some systems and then running the app. Extend your main function with the following code:

app.add_systems(Startup, setup_camera)
    .add_systems(Update, spawn_dialogue_runner.run_if(resource_added::<YarnProject>()))
    .run();

In order to see anything at all, we need a camera in our game world. setup_camera does just that when the game starts:

fn setup_camera(mut commands: Commands) {
    commands.spawn(Camera2dBundle::default());
}

The line added for the Update system set might look a bit confusing, so let's clear it up before defining the spawn_dialogue_runner function.

When the YarnSpinnerPlugin starts, it searches for Yarn files in the assets/dialogue/ directory. Along with any localizations or extra assets it might find, it bundles its findings into a YarnProject representing your work. Once this process is finished, a YarnProject resource is injected into the world.

A DialogueRunner is the component that is responsible for actually running any piece of Yarn dialogue found inside a YarnProject. If you want to start, stop or change a dialog, you need to use it. You can guess that this only works once the YarnProject has actually finished loading. This is why we use .run_if(resource_added::<YarnProject>()); to wait exactly with spawning the DialogueRunner until everything is ready.

With that out of the way, let's look at the definition of spawn_dialogue_runner:

fn spawn_dialogue_runner(mut commands: Commands, project: Res<YarnProject>) {
    let mut dialogue_runner = project.create_dialogue_runner();
    dialogue_runner.start_node("Start");
    commands.spawn(dialogue_runner);
}

This code will not spawn the DialogueRunner, but tells it to immediately run a node called "Start" from a Yarn file.

Creating a Yarn File

Create a file inside assets/dialogue/ called my_story.yarn. Open it and fill it like this:

title: Start
tags:
---
Narrator: Oh, hello!
    -> Hi, where am I?
        Narrator: You're in Bevy!
            -> Oh.
            <<jump Oh>>
            -> How did I get here?
            <<jump Rust>>
===

title: Oh
---
Narrator: Yeah, fun, right?
===

title: Rust
---
Narrator: Someone read the Beginner's Guide!
===

Now you can simply run cargo run in your terminal and enjoy your freshly created dialog:

Troubleshooting

If anything went wrong, make sure that your directories look like this:

Your src/main.rs should look like this:

use bevy::prelude::*;
use bevy_yarnspinner::prelude::*;
use bevy_yarnspinner_example_dialogue_view::prelude::*;

fn main() {
    let mut app = App::new();
    app.add_plugins((
        DefaultPlugins,
        YarnSpinnerPlugin::new(),
        ExampleYarnSpinnerDialogueViewPlugin::new(),
    ));
    app.add_systems(Startup, setup_camera)
    .add_systems(Update, spawn_dialogue_runner.run_if(resource_added::<YarnProject>()))
    .run();
}

fn setup_camera(mut commands: Commands) {
    commands.spawn(Camera2dBundle::default());
}

fn spawn_dialogue_runner(mut commands: Commands, project: Res<YarnProject>) {
    let mut dialogue_runner = project.create_dialogue_runner();
    dialogue_runner.start_node("Start");
    commands.spawn(dialogue_runner);
}

And your Cargo.toml should look like this:

[package]
name = "hello_yarnspinner"
version = "0.1.0"
edition = "2021"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]
bevy = "0.13.0"
bevy_yarnspinner = "0.2.0"
bevy_yarnspinner_example_dialogue_view = "0.2.0"

Next Steps

With that, we've reached the end of our beginner's guide. You're ready go forth and build games with Yarn Spinner! You're also equipped to work with the rest of the documentations here!

Don't forget to join the Discord, to chat with other Yarn Spinner users, the Yarn Spinner team, seek help, and share your work. It might also be worthwhile joining the Bevy Discord (unaffiliated with Yarn Spinner).

The preferred way of writing your Yarn Spinner code is with the official Yarn Spinner Visual Studio Code Extension.

The official extension adds syntax highlight to VS Code's text editor, as well as a graph view that displays the nodes, and relationships between the nodes.

If you've never used to Visual Studio Code before, head to their official website and install it for your operating system and platform, and then continue to Installing the Extension.

For this final step in the beginner's guide, you can choose your preferred engine:

• Yarn Spinner for Unity (2021.3 or newer, Officially Supported)

• Yarn Spinner for Unreal (5.1 or newer, coming Late-2023)

We also provide experimental Yarn Labs support for:

• Yarn Spinner for Godot (C# edition 4.0 or newer).

• Yarn Spinner for Rust using Bevy.

With the Yarn Spinner Visual Studio Code Extension installed, you can make new Yarn files, and edit existing ones, right inside the VS Code editor.

Making or opening a Yarn file

You can use the File menu -> New file command to make a new empty file. Simply save the file with a .yarn extension to activate the Yarn Spinner Extension features.

You can also open any existing .yarn file, or folder of .yarn files, using VS Code.

Writing Yarn in Visual Studio Code

Here, we'll walkthrough the process of using Yarn Spinner for Visual Studio Code to write .yarn stories.

Opening a folder

For this example, we'll start with an existing story (Chat.yarn) in a folder (YSDocsDemos):

If we open VS Code, the default screen will have an Open button right in the middle.

Click this button, or choose the File menu -> Open Folder..., and then open the folder containing your .yarn files:

When the folder opens, you'll see the sidebar of VS Code change to reflect the contents of the folder. You can click on a .yarn file to open it in the text editor:

Working with Yarn in Visual Studio Code

With a .yarn file open in VS Code, you can verify that the Yarn Spinner for Visual Studio Code Extension is active by looking in the bottom right-hand corner of the screen, and locating the words "Yarn Spinner":

You can use the text editing view to work with .yarn, and to write your narratives. The Yarn Spinner for Visual Studio Code extension provides all sorts of features to make this process easier.

For example, if you hold the Command key (on macOS) or the Control key (on Windows or Linux) and hover over names of nodes in, for example, `<<jump>> statements, you'll be able click on them to move the editor view to the Yarn that represents that node:

You'll also be offered autocomplete suggestions based on node names that exist in your project. For example, if you create a new <<jump>> statement, you'll be able to pick from your nodes:

If your Yarn projects also use variables, Yarn Spinner for VS Code will help out as well. For example, when you <<declare>> a new variable, you can add a comment with three / in front of it to provide a description of the variable:

Then, when you use the variable, you can hover over it in VS Code for a reminder of its purpose (and its default value):

Variable names will also autocomplete when you try and use them, and errors will be show if there are type isues. So, if you <<declare>> a variable to be a certain type, for example a boolean:

... and then attempt to use that variable in a way that would produce an error. For example, by attempting to assign a number to it, then Yarn Spinner for Visual Studio Code will show an error:

You'll also be able to see documentation comments from commands defined in your game's C# source code:

Working with nodes

While Yarn is a text based language, our Yarn Spinner for Visual Studio Code extension provides a handy Graph View. You can open the Graph View for whichever .yarn file you're currently working with by clicking the Graph View button in the top right-hand corner:

You might notice that, when you first look at the Graph View for a .yarn file, all the nodes appeared stacked on each other, like this:

To make sense of things, and better understand the <<jump>> use between nodes, you can rearrange the nodes by clicking and dragging to wherever you want them:

The position of the nodes will be stored in each node's header:

You can use the Add Node button, found at the top of the Graph View, to add new nodes. New nodes will appear in the Graph View, and in the text editor:

Double-clicking a node in the Graph View will jump to that node in the Text View:

If you have a lot of nodes, you can use the Jump to Node menu, in the top right-hand corner of the Graph View, to jump the Graph View to a specific node:

At any point you can also click Show in Graph View, found above each node in the Text View to jump the Graph View to it:

Customising the Graph View

You can add some additional metadata to the headers of each node to customise your Graph View, for ease of understanding the relationships between areas of your script. For example, if you add the color field to the header, you can colour-code your nodes:

The color field works like any other header element, and goes below the title and above the ---:

title: NodeName
color: purple
---

===

You can also group your nodes by adding the group field to your node headers. For example, if you add group: Main_Options to the header of the Volcanos, Dogs, and Trees nodes, you'd end up with this:

Using the Command Palette

The VS Code Command Palette has a number of useful Yarn Spinner features as well. Summon the Command Palette by pressing Shift + Command + P (Mac) or Ctrl + Shift + P (Windows/Linux), or choosing the View menu -> Command Palette..., and type "Yarn Spinner" to filter the available commands to those provided by the Yarn Spinner for Visual Studio Code Extension:

From here you can Preview Dialogue, which will allow you to play through your narrative, right inside Visual Studio Code. To learn more about this, read Previewing Your Dialogue.

The Export Dialogue as HTML... option will export a self-contained playable version of your narrative as an HTML file, which is otherwise the same as the experience your get when previewing.

The Export Dialogue as Graph... option will allow you to export a .dot file of your graph. To learn about .dot files, check out the GraphViz documentation: https://graphviz.org/doc/info/lang.html

And finally, the Export Dialogue as Recording Spreadsheet... option will allow you to export a spreadsheet, which can be useful for voice actors recording dialogue.

This step of the beginner's guide helps you move from writing Yarn scripts outside of a game engine, to initial integration steps to turn them into a game with Godot

First, launch Godot 4.2 (C# version) and create a new project.

Installing Yarn Spinner for Godot

Download a copy of the latest version of Yarn Spinner for Godot from the GitHub repository, or clone the repository somewhere.

Locate the addons/ directory in your new local copy of Yarn Spinner for Godot:

Put a copy of this directory into your new Godot project, either by dragging the folder in your file manager (e.g. Finder or Explorer) into the folder of the Godot project, or by dragging from your file manager into the FileSystem dock of your Godot project:

Next, choose the Project menu -> Tools -> C# -> Create C# solution. This will create a C# project for you. We have to do this to trigger the creation of the .csproj file, which is necessary to let Godot know about the Yarn Spinner plugin.

Next, open the project folder in Visual Studio Code. In the sidebar of VS Code, the .csproj file and add the following line to it, inside the <Project> </Project> tags, but not inside an <ItemGroup> or <PropertyGroup>:

  <Import Project="addons\YarnSpinner-Godot\YarnSpinner-Godot.props" />

Your brand new project should look something like this in VSCode:

Save the tweaked .csproj file and return to Godot, everything is almost ready to go. Click the Build button in the very top right-hand corner of the Godot window. This will trigger a build of the C# solution for the project, which is required to make Godot aware of Yarn Spinner for Godot.

Once the build is complete, open the Project menu -> Project Settings, change to the Plugins tab, and tick the enabled box next to the Yarn Spinner for Godot plugin:

With that, you're ready to go!

Using Yarn Spinner for Godot

In your Godot project, click the Instantiate Child Scene button:

And navigate into the addons/YarnSpinner-Godot/Scenes folder of your project, and choose the DefaultDialogueSystem.tscn file as the scene to instantiate:

Your Scene dock will look like this showing a node hierarchy that's entirely based on the DefaultDialogueSystem.tscn scene that you instantiated:

Next, create a new Yarn Project using the menu Tools > YarnSpinner >Create Yarn Project:

Then choose a directory to save your new YarnProject in. For example, you can save it to the root of your project. Name the new Yarn Project FirstProject.yarnproject:

Next, create a new Yarn script (a file with a .yarn extension) by using the menu Tools > YarnSpinner >Create Yarn Script. In the resulting "Create a new Yarn Script" window, set the File name to MyStory.yarn, and click the Save button::

It may take a moment, but Godot will import your new .yarn file, and it will appear in the FileSystem dock. When it's appeared, double-click on the Yarn Project, FirstProject.yarnproject in the FileSystem dock and look to the Inspector, making sure that res://MyStory.yarn is in the list of Source Scripts, which are the Yarn scripts that compromise the new project:

Next, open the MyStory.yarn file in VS Code, and add the following Yarn script to it, before saving it and returning to Godot:

title: Start
tags:
---
Narrator: Oh, hello!
    -> Hi, where am I?
        Narrator: You're in Godot!
            -> Oh.
                <<jump Oh>>
            -> How did I get here?
                <<jump Godot>>
===

title: Oh
---
Narrator: Yeah, fun, right?
===

title: Godot
---
Narrator: Someone read the Beginner's Guide!
===

Select the DialogueRunner node in the Scene dock, and look to the Inspector. Assign the Yarn Project you created to the DialogueRunner by dragging the FirstProject.tres Yarn Project from the FileSystem dock into the Yarn Project slot of the Inspector:

Finally, enter Start as the Start Node, and tick the box next to Starts Automatically:

Save your scene as Demo.tscn, and run the game. At this point, you can play your project, and step through the dialogue in the default Yarn Spinner for Godot Line View and Options List View:

Next steps with Yarn Spinner for Godot

With that, we've reached the end of our beginner's guide. You're ready go forth and build games with Yarn Spinner! You're also equipped to work with the rest of the documentations here! Don't forget to join the Discord to chat with other Yarn Spinner users, the Yarn Spinner team, seek help, and share your work. \

This step of the beginner's guide helps you move from writing Yarn scripts outside of a game engine, to initial integration steps to turn them into a game with Unity.

First, launch the Unity Hub, and create a new project for Unity 2021.3 or newer. Then, download and install Yarn Spinner.

You can download and install Yarn Spinner for Unity in four different ways:

• buy Yarn Spinner for Unity from our Itch.io store, download it, and add the package to your project from the .unitypackage

• buy Yarn Spinner from the Unity Asset Store, download it, and install it via Unity

• install Yarn Spinner for Unity via the Unity Package Manager

• install Yarn Spinner for Unity from GitHub

Install from Itch.io

First, visit the Yarn Spinner Itch.io Store, and click the Buy Now button, and complete the checkout process.

Once you've purchased Yarn Spinner, you'll find a Download button at the top of the page:

The download button will take you the following page, where you can download the Yarn Spinner for Unity .unitypackage:

Once you've downloaded the .unitypackage, with the Unity project you want to use it in open and ready to go, double click it. Unity will then allow you to import the package into your project:

Install from the Unity Asset Store

First, visit the Unity Asset Store page for Yarn Spinner for Unity, and add it to your cart, and complete your purchase while logged into the same Unity account you use to activate Unity.

Once you've purchased Yarn Spinner for Unity, you'll find the Add to Cart button replaced by an Open in Unity button. Click this button to launch Unity, and the Package Manager will locate your purchased package:

Once the Package Manager has located the package, you can use the Download button to fetch it:

Once Yarn Spinner for Unity has downloaded, you can use the Import button to start the process of adding it to your project:

This will trigger the Import Unity Package workflow, where you can use the Import button to add the Yarn Spinner for Unity package to your project:

And with that, you're ready to use Yarn Spinner! You might also want to download and import the Yarn Spinner for Unity Samples as a .unitypackage, from here.

Installing from other sources

If you would prefer to download and install Yarn Spinner for Unity outside of Itch or the Unity Asset Store, we provide the following methods:

Using Yarn Spinner for Unity

Once you've installed Yarn Spinner, you're ready to start using it!

Yarn Spinner for Unity provides a way to get the contents of your Yarn scripts into Unity, which allows you to construct a game around your dialogue. This beginner's guide shows guides you through one simple way of using Yarn Spinner for Unity to do this.

The provided Yarn Spinner views use the Unity package TextMesh Pro to display text. This means you will need to install it before using Yarn Spinner. To do this, open the Window menu and choose -> TextMesh Pro -> Import TMP Essential Resources.

In the empty project that now has the Yarn Spinner for Unity package installed, right click in the Hierarchy and choose Yarn Spinner -> Dialogue Runner. This will add a new Dialogue System prefab to your scene, which we'll be working with in a moment.

The Dialogue Runner that has been added to your scene is a prefab supplied by Yarn Spinner for Unity that acts as a bridge between the dialogue written in your Yarn scripts, and everything that happens in Unity.

Specifically, it works with two different things, which are key concepts when working with Yarn Spinner for Unity:

• a Yarn Project

• a Dialogue View

Creating a Yarn Project

First, we'll look at the Yarn Project. A Yarn Project is a Untiy asset that lives on disk. Create one by right-clicking in the Assets pane and choose Create -> Yarn Spinner -> Yarn Project.

With the new Yarn Project created, name it FirstProject, and then use the same menu to create a Yarn Script. Name the Yarn Script MyStory.

The Yarn Script you've created is actually a .yarn file that's now named MyStory.yarn. Double click it in the Assets pane to open it in Visual Studio Code.

Put the following Yarn script into MyStory.yarn, save the file and return to Unity:

title: Start
tags:
---
Narrator: Oh, hello!
    -> Hi, where am I?
        Narrator: You're in Unity!
            -> Oh.
            <<jump Oh>>
            -> How did I get here?
            <<jump Unity>>
===

title: Oh
---
Narrator: Yeah, fun, right?
===

title: Unity
---
Narrator: Someone read the Beginner's Guide!
===

To connect the Yarn Project you created to the Dialogue Runner that's in the scene, select the Dialogue Runner in the Hierarchy and drag the FirstProject from the Assets pane into the Yarn Project slot, as shown here:

With that done, select the Yarn Project FirstProject in the Assets pane, and look to the Inspector.

You'll see the Source Files field contains **/*.yarn — this tells this specific Yarn Project to look for all .yarn files in the same folder as the Yarn Project asset, and any subfolders. Thus, any .yarn files next to it will be included as part of the project, which means MyStory.yarn will be found.

At this point, you can play your project, and step through the dialogue in the default Yarn Spinner for Unity Line View and Options List View:

What's a Line View and an Options List View?

To understand how this is working, it's important to understand the concept of Yarn Spinner Dialogue Views. Select the Dialogue System in the Hierarchy, and expand the Dialogue Views section:

This section is where you specify which DIalogue Views should be used to display the content coming from the Yarn script(s): in other words, how the lines of dialogue, and choices, should be displayed.

A Dialogue Runner can have multiple Dialogue Views. For example, by default the Dialogue System prefab has one Dialogue View that's designed to display lines of dialogue (Line View), and another that's in charge of displaying options to the player (Options List View).

All Dialogue Views receive all lines and options, and it's up to them to handle them appropriately. So the Line View that we supply will only displays lines that are not options, and the Options List View will only display lines that are options.

Next steps with Yarn Spinner for Unity

With that, we've reached the end of our beginner's guide. You're ready go forth and build games with Yarn Spinner! You're also equipped to work with the rest of the documentations here! Don't forget to join the Discord, to chat with other Yarn Spinner users, the Yarn Spinner team, seek help, and share your work.

Once you've got Visual Studio Code (often abbreviated to "VS Code", or "Code") installed on your system, you'll want to install the Yarn Spinner extension. To install the Yarn Spinner Extension:

1. Launch Visual Studio Code.

2. Open the Extensions view. To do this, select the blocks symbol from the left-hand sidebar, or press Command+Shift+K on macOS, or Control+Shift+X on Windows or Linux.

3. Search for the Yarn Spinner Extension. With the Extensions view open, type "Yarn Spinner" into the search field.

4. Install the Extension. Once the results have loaded, click "Install" next to the Secret Lab-provided Yarn Spinner Extension.

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

Yarn Spinner is a tool for writers. In this section, you'll learn the syntax of Yarn, and learn how to write Yarn scripts for use in your game. You'll also learn how to use the various tools that are available for creating your content.

You'll need an editor before you can write Yarn scripts, so we recommend checking out before going too far.

The Yarn language is a full programming language, which means it has support for writing code that let you control how the dialogue in your game works. In this section, you'll learn how to use variables to control your dialogue.

Variables

Variables store information. Variables can store one of three types of information: numbers, strings, and booleans.

Every variable has a name. In Yarn Spinner, all variable names start with a dollar sign ($).

Declaring Variables

Declaring a variable means telling Yarn Spinner that a variable exists, what it's meant to be used for, and what initial value it has.

To declare a variable, you use the <<declare>> statement:

Setting Variables

You put information into a variable by using the <<set>> command. For example, the following code puts a string, "Hello, Yarn!", into a variable called $greeting:

Variables and Types

Each variable can only store one type of value. Variables can change their value at any time, but they can never change their type.

For example, the following code will work:

This works because while the value of each of the variable changes, the type doesn't. However, the following code will not work:

Variables and Expressions

You can work with the values inside variables. For example, numbers can be multiplied, strings can be added together, and boolean values can have logical operations (like and and or) applied to them. When values are used together like this, it's called an expression.

An expression needs to be a single type. You can't work with values of different types in a single expression. For example, the following code will not work:

Logical operators

Yarn Spinner supports the following logical operators. Most of these have multiple ways being written:

• Equality: eq or is or ==

• Inequality: neq or !

• Greater than: gt or >

• Less than: lt or <

• Less than or equal to: lte or <=

• Greater than or equal to: gte or >=

• Boolean 'or'': or or ||

• Boolean 'xor': xor or ^

• Boolean 'not': not or !

• Boolean 'and': and or &&

Maths operators

• Addition: +

• Subtraction: -

• Multiplication: *

• Division: /

• Truncating Remainder Division: %

• Brackets: ( to open the brackets and ) to close them.

Order of operations

Yarn Spinner follows a fairly standard order of operations, and falls back to using left to right when operators are of equivalent priority.

The order of operations is as follows:

1. Brackets

2. Boolean Negation

3. Multiplication, Division, and Truncating Remainder Division

4. Addition, Subtraction

5. Less than or equals, Greater than or equals, Less than, Greater than

6. Equality, Inequality

7. Boolean AND, Boolean OR, Boolean XOR

Using Variables in Lines

To show the contents of a variable, you put it inside braces ({ }) inside a line. The value of that variable will appear in its place.

For example:

Variables and Storage

Yarn Spinner doesn’t manage the storage of information in variables itself. Instead, your game provides a variable storage object to Yarn Spinner before you start running dialogue.

When Yarn Spinner needs to know the value of a variable, it will ask the variable storage object you’ve given it. When Yarn Spinner wants to set the value of a variable, it will provide the value and the name of the variable. In this way, your game has control over how data is stored.

The primary editing experience for Yarn Spinner is our Yarn Spinner for Visual Studio Code extension. This provides the majority of features that you'd want in order to effectively write .yarn scripts using VSCode.

This guide shows you how to use , together with Yarn Spinner for Visual Studio Code, to collaborate live on your narrative.

Installing Live Share

To install Live Share for Visual Studio Code, and use it with Yarn Spinner:

3. Click the install button!

Inviting collaborators

With your project open, choose Live Share in the Activity Bar on the left side of the screen, and in the resulting view that appears, choose the Share button:

You'll be prompted to sign in to either GitHub or your Microsoft account, and after this a notification will appear in the bottom of the screen letting you know a shareable link to collaborate has been copied to the clipboard:

Joining a shared workspace

When you receive a collaboration link and visit it, you'll be asked how you'd like to join:

If you choose to Continue in Web, you'll be taken to a web version of VS Code, which will not have the Yarn Spinner extension installed. If you click Open in Visual Studio Code, your local copy of VS Code will be installed, complete with extensions.

Once the shared workspace opens in your local copy of VS Code, you'll be in an untrusted state, which means the Yarn Spinner extension will not be providing syntax highlighting, To enable this, click Manage, in the grey bar at the top of the window, then click the Trust button in the view that appears:

Writing together

The person who initially shared the workspace will have full and complete access to the features of the Yarn Spinner for Visual Studio Code extension. Everything, from syntax highlighting to the graph view will work as normal.

Those who are joining the shared session will only have access to the syntax highlighting features of the Yarn Spinner for Visual Studio Code extension, provided they go through the process of trusting the workspace, as noted earlier.

As you edit, you'll be able to see other users in the files, and their work will be briefly highlighted as they write:

For more help

You can run your Yarn script inside the Visual Studio Code extension, without having to import it into a game. This means that you can write content for your game even if the game isn't yet ready to have dialogue added to it. It's also useful for quickly checking to see if your Yarn script works the way that you want it to before testing it in your game.

Showing the Dialogue Preview

To preview your dialogue in Visual Studio Code, open the Command Palette by pressing Command-Shift-P (Control-Shift-P on Windows), and type "Preview Dialogue". Your current Yarn project will open to the side, and you can begin playing through your script.

Preview Features

While playing through your dialogue in preview mode, there are several features that can be useful to test out a script.

• Changing the starting node: By default, the dialogue preview will start playing from a node named "Start", if one is present in your Yarn files. If you want to play from a different node, open the list of nodes and choose the node you want to start from.

• Changing whether lines are shown one at a time, or all at once: By default, the dialogue preview shows each line and command one and a time. You can change this to delivering everything all at once by opening the Settings menu and changing the setting to "Show Lines All At Once".

• Restarting the script: When you click the Restart button, the dialogue preview will restart from the currently selected starting node.

Exporting Your Script

You can export a stand-alone HTML file containing a runnable version of your Yarn script, which you can send to other people for them to play. This can be particularly useful for writers who want to get feedback on their scripts before working with other team members to integrate their content.

To export your script, click the Export button, and choose where to save the file. The file can then be sent anywhere you like, and can be opened in all major web browsers.

In Yarn Spinner, all of your dialogue is stored in .yarn files. Yarn files are just plain text files, which you can edit in any text editor.

Nodes

Yarn Spinner files contain nodes. Nodes are where you put your dialogue. You can have as many nodes as you link in a file. Nodes are used to separate out parts of the story, and make it easier to manage longer stories and branching.

Each node has, at the very minimum, a collection of headers, and a body. All nodes have at least one header, which is the title. The title is the name of the node, and the body contains the Yarn script that contains your game's dialogue.

The title of a node is important, because your game uses node titles to tell Yarn Spinner which node to start running. You also use the title of a node when you want to jump to another node.

Node titles are not shown to the player.

Writing Nodes in Plain Text

If you're using a text editor to write Yarn scripts, you'll need to write the node's header.

The plain-text version of a Yarn node looks like this:

In this example, the node's title is Node_Title, which is set on the first line in the title header. You can also add any other headers that you want.

The --- marker indicates where the body begins. After this point, you can put all of your Yarn script.

The === marker indicates where the node ends; after this point, you can begin another node.

Node Content

The body of a node is made up of three different kinds of content: lines, commands, and options.

Lines

When you write Yarn Spinner dialogue, just about every line of text that you write in a node is a line. When a node is run, it runs each line, one at a time, and sends it to your game.

A line of dialogue is just the thing you want some entity or character to say, usually beginning with the name of the entity speaking.

For example, consider the following Yarn code from Night in the Woods:

When this code is run in the game, it looks like this:

Yarn Spinner sends each of these lines, one at a time, to the game. The game is responsible for taking the text, and presenting it to the player; in the case of Night in the Woods, this means drawing the speech bubble, animating each letter in, and waiting for the user to press a key to advance to the next line.

Lines of dialogue can contain just about any text, except for some special characters that Yarn Spinner uses to add extra information to a line.

If there is a set of characters without spaces before a colon (:) at the beginning of the line, Yarn Spinner will mark that as the name of the character. This information will then be passed to your game, so that you can change the way that lines are shown based on the character who's saying them. For example:

Options

When you want to let the player decide what to say, you use an option. Options let you show multiple potential lines of dialogue to the player, and let the player select one.

Options are marked with a -> symbol. You write as many options as you'd like the player to see, and the player chooses one of them. The content of the option is like any other line of dialogue.

For example, consider the following code:

In this example, the line "Hi there! What do you feel like doing today?" will run. The player will then be given the choice to say either "I want to go swimming", or "I'd prefer to go hiking".

Options and Lines

Shortcut options can have their own lines, which are run when the option is selected. If a different option is selected, they won't run. To write this, indent the lines that belong to a shortcut option.

In the following code, different lines will run based on which of the two shortcut options are selected.

This script will start with the line, "Hi there! What do you feel like doing today?". The player then has the choice of saying either "I want to go swimming", or "I'd prefer to go hiking". Depending on their choice, either the line "Okay, let's go swimming" or "Cool, we'll go hiking then". Finally, no matter what was selected, the line "Sounds good!" will run.

Nested Options

In addition to containing lines, options can also contain other options.

You can nest options as much as you like. However, this can get a bit challenging to read. It's often a good idea to use the <<jump>> command to jump to a different node:

Separating dialogue segments into nodes can aid in writing neater files that are easier to edit as they grow.

Sometimes it makes sense for the options presented or the outcomes of selecting different options to vary based on other things the player has done or said up until this point. This requires the use of logic and variables, which we'll discuss in the next section.

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:

// Inside an if statement:
<<if dice(6) == 6>>
    You rolled a six!
<<endif>>

// Inside a line:
Gambler: My lucky number is {random_range(1,10)}!

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.

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 define your own custom functions in Yarn Spinner. For more information, see # Defining Commands and Functions .

if statements

In addition to storing information, variables are useful for controlling what's shown to the player. To do this, you 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 code:

<<set $gold_amount to 5>>

Player: I'd like to buy a pie!

<<if $gold_amount < 10>>
    Baker: Well, you can't afford one!
<<endif>>

This example will set a variable, $gold_amount, to 5. It will then show the line "I'd like to buy a pie!", and before it continues, it will check to see if $gold_amount is less than 10. If that's the case (which it will be!), the line "Well, you can't afford one!" will run.

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:

Player: I'd like to buy a pie!

<<if $gold_amount < 10>>
    Baker: Well, you can't afford one!
<<elseif $gold_amount < 15>>
    Baker: You can almost afford one!
<<else>>
    Baker: Here you go!
<<endif>>

This script will show different lines depending on the value of $gold_amount. The checks are done from top to bottom, which means that in order for an elseif or else to run, all of the checks above it have to have failed.

• If it's less than 10, the line "Well, you can't afford one!" will run.

• Otherwise, if it's less than 15, the line "You can almost afford one!" will run.

• Otherwise, the line "Here you go!" will run.

Conditional Options

When presenting options to the player, you may want to make some options not available. You can do this by adding a condition to the 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:

Guard: You're not allowed in!

-> Sure I am! The boss knows me! <<if $reputation > 10>>
-> Please?

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.

Now that you know how to work with nodes, lines, options and variables, there's one last part of the Yarn language to learn about: commands.

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

<<wait 2>>
<<setsprite ShipName happy>>
<<fade_out 1.5>>

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.

// Wait for 2 seconds
<<wait 2>>

// Wait for half a second
<<wait 0.5>>

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.

// Leave the dialogue now
<<stop>>

// Leave the dialogue if we don't have enough money
<<if $money < 50>>
    Shopkeeper: You can't afford my pies!
    <<stop>>
<<endif>>

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.

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:

Oh, [wave]hello[/wave] there!

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:

Oh, hello there!

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:

Oh, [wave]hello [bounce]there![/bounce][/wave]

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

Oh, [wave]hello [bounce]there![/wave][/bounce]

Self-closing Attributes

Attributes can self-close:

[wave/]

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:

[wave][bounce]Hello![/]

Properties

Attributes can have properties:

[wave size=2]Wavy![/wave]

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:

[wave=2]Wavy![/wave]

This is the same as saying this:

[wave wave=2]Wavy![/wave]

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:

[mood=angry]Grr![/mood]
[mood="angry"]Grr![/mood]

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

A [wave/] B

A [wave trimwhitespace=false/] B 
// (produces "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:

Here's some square brackets, just for you: \[ \]

This will appear to the player as:

Here's some square brackets, just for you: [ ]

The backslash will not appear in the text.

Here's a backslash! \\

Here's a backslash! \

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:

[nomarkup]Here's a big ol' [ bunch of ] characters, filled [[]] with square [[] brackets![/nomarkup]

This will appear as:

Here's a big ol' [ bunch of ] characters, filled [[]] with square [[] brackets!

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:

CharacterA: Hello!
CharacterB: Oh, hi!

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:

[character name="CharacterA"]CharacterA: [/character]Hello!
[character name="CharacterB"]CharacterB: [/character]Oh hi!

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

Text Replacement Markers

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.

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:

// In this example, the $gender variable is a string that
// contains either "m", "f", or "nb".

I think [select value={$gender} m="he" f="she" nb="they" /] will be there!

// Depending on the value of $gender, this line can appear
// as one of these possible options:
I think he will be there!

// or:
I think she will be there!

// or:
I think they will be there!

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 $apple_count == 1>>
    You have one apple!
<<else>>
    You have {$apple_count} apples!
<<endif>>

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:

PieMaker: Hey, look! [plural value={$pie_count} one="A pie" other="Some pies" /]!

// This will appear as either:
PieMaker: Hey, look! A pie!

// or: 
PieMaker: Hey, look! Some pies!

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:

PieMaker: I just baked [plural value={$pie_count} one="a pie" other="% pies" /]!

// This will appear as, for example:
PieMaker: I just baked a pie!"

// or:
PieMaker: I just baked 4 pies!"

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

Runner: The race is over! I came in [ordinal value={$race_position} one="%st" two="%nd" few="%rd" other="%th" /] place!

// This will appear as, for example:
Runner: The race is over! I came in 1st place!

// or:
Runner: The race is over! I came in 23rd place!

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:

Homer: Hi, I'd like to order a tire balancing. #tone:sarcastic #duplicate

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:

Hello there.
-> Hi!
-> What's up?

is treated as though it had been written as:

Hello there. #lastline
-> Hi!
-> What's up?

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:

Mechanic: You're in orbit of Jupiter, at a rest station along the main tourism lines. There's a meteorite headed towards here that'll completely destroy this station in three days. #line:4c49c5
Mechanic: And you're a wayfinding robot bolted to the floor of said Jupiter Tourist Station. #line:5b6256
-> Bolted to the floor?! #line:f65d07
	Mechanic: Yeah, like all tourist helper bots. #line:1b159b
-> Three days?! #line:40eaf7
	Mechanic: More or less. I wouldn't make any long-term plans. #line:3a6c94

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:

title: Train_Dialogue
tags: #camera2 background:conductor_cabin
---
Why did you stop the train?
Now we won't arrive in time at the next stop!
===

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:

title: Node_Name
tracking: always
---
I know how many times you've been here.
===

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.

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

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.

The Yarn Spinner Console (ysc) can upgrade your older .yarn scripts to the latest syntax.

To upgrade your scripts:

Install the version of Yarn Spinner Console that matches your version of Yarn Spinner. You can do this via the Yarn Spinner Console GitHub Project. Choose Releases in the sidebar, and download the appropriate binary for your platform. If you just want the latest release, you can find it here.

Run the upgrader on your scripts. To upgrade, you must run ysc on your command-line/terminal with the upgrade parameter and a path to a yarn file:

$ ysc upgrade myOldYarnFile.yarn

You can also run the upgrade on multiple scripts at once. To do this, you can pass in as many .yarn files as you want:

ysc upgrade myOldYarnFile.yarn myOtherOldYarnFile.yarn

ysc upgrade --output-directory ./output myOldYarnFile.yarn

A Yarn Project is a file that links multiple together. Yarn projects are how Dialogue Runners work with your content.

Creating a New Yarn Project

To create a new Yarn Project, follow these steps:

• Open the Assets menu, and choose Yarn Spinner -> Yarn Project.

• Unity will create a new file. Type in a name for the file, and press return.

Adding Yarn scripts to a Yarn Project

On their own, a Yarn Project doesn't do anything. In order to be useful, you need to add Yarn scripts to it.

Yarn Projects include all Yarn Scripts that the project finds in the Source Files directory. By default, that means all Yarn Scripts in the same directory as the Yarn Project, and all of that directory's children.

When you add a Yarn Script to the same folder as a Yarn Project, it will automatically be included in the Yarn Project. When you make changes to the script, the Yarn Project will automatically be re-imported.

You can change the locations that a Yarn Project looks for Yarn Scripts by modifying the Source Files setting. Each entry in the Source Files setting is a search pattern.

You can add as many entries to the Source Files field as you like. If a file is matched by multiple patterns, it will only be included once.

A Yarn script can be included in more than one Yarn Project.

Creating a Project from a Script

You can create a new Yarn Project from a script. To do this, follow these steps:

• Select the Yarn script in the Project pane.

• In the Inspector, click the Create New Yarn Project button.

• Clicking this button does two things:

  • A new Yarn Project will be created next to the Yarn script.

  • The new Yarn Project will include the Yarn script you created it from in its list of source scripts.

Managing Variables

The Inspector will show information about every variable in the project. If you use a declare statement to declare a variable, you can control the initial value of a variable, as well as its description. If you don't declare a variable, Yarn Spinner will attempt to figure the variable's type out based on how it's used, and won't be able to provide a description.

Managing Localisations and Assets

When you write a Yarn script, you write it in a specific human language. This is referred to as the 'base' language of the script. It's called the base language because it's the one you start with, and the one you translate into other languages.

You can set the base language of a Yarn Project in the Inspector by changing the Base Language setting.

Using Yarn Projects with Dialogue Runners

Yarn Projects are used by Dialogue Runners. When a Dialogue Runner is told to start running dialogue, it reads it from the Yarn Project it's been provided.

Inspector

Upgrading Yarn Projects

If you are upgrading your version of Yarn Spinner from version 2.2 or earlier, you will need to upgrade your Yarn Project. To do this, select the Yarn Project, and click Upgrade Yarn Project.

You will also need to either move all of your Yarn Scripts into the same folder as the Yarn Project, or update the Yarn Project's Source Files setting to tell the Yarn Project where to find your scripts.

Watch a video where Yarn Spinner developer Jon Manning walks you through upgrading a Yarn Project:

You can download and install Yarn Spinner for Unity in four different ways:

• , download it, and add the package to your project from the .unitypackage

• , download it, and install it via Unity

• install Yarn Spinner for Unity via the Unity Package Manager

• install Yarn Spinner for Unity from GitHub

Install from Itch.io

First, visit the , and click the Buy Now button, and complete the checkout process.

Once you've purchased Yarn Spinner, you'll find a Download button at the top of the page:

The download button will take you the following page, where you can download the Yarn Spinner for Unity .unitypackage:

Once you've downloaded the .unitypackage, with the Unity project you want to use it in open and ready to go, double click it. Unity will then allow you to import the package into your project:

Install from the Unity Asset Store

Once you've purchased Yarn Spinner for Unity, you'll find the Add to Cart button replaced by an Open in Unity button. Click this button to launch Unity, and the Package Manager will locate your purchased package:

Once the Package Manager has located the package, you can use the Download button to fetch it:

Once Yarn Spinner for Unity has downloaded, you can use the Import button to start the process of adding it to your project:

This will trigger the Import Unity Package workflow, where you can use the Import button to add the Yarn Spinner for Unity package to your project:

And with that, you're ready to use Yarn Spinner! You might also want to download and import the Yarn Spinner for Unity Samples as a .unitypackage, from here.

Installing from other sources

If you would prefer to download and install Yarn Spinner for Unity outside of Itch or the Unity Asset Store, we provide the following methods:

Next Steps

Once you've installed Yarn Spinner, you're ready to start using it!

Want to use Yarn Spinner in a new scene right away? Follow these steps.

Setting Up A Demo Scene

1. Create a new empty Unity project, by following .

2. Install Yarn Spinner into the project, by following the instructions in .

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

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

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

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!

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

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

While the Line View and Options List View are useful for lots of situations, your game might need to display lines and options in specific ways. In these situations, you can write your own custom Dialogue View, and handle the presentation of lines and options in ways that are entirely in your control.

Creating a Dialogue View

To create a Dialogue View, you subclass the DialogueViewBase class, and add it as a component to a game object in your scene. You can then add this game object to the Dialogue Views list on your scene's Dialogue Runner.

Presenting Lines and Options

On its own, an empty subclass of DialogueViewBase will not do anything useful. To make it display lines and options, you'll need to implement certain methods.

To understand how to create a custom Dialogue View, it's useful to understand how the Dialogue Runner works with content.

Yarn Spinner scripts deal in three different kinds of content: lines, options, and commands. Of these, only the first two - lines and options - are content that need to be shown directly to the player.

When the Dialogue Runner encounters lines or options, it first needs to determine the specific content the user needs to see. Once it has this, it sends the content to each of its Dialogue Views.

Getting Localized Content

Lines and options are represented in compiled Yarn scripts as line IDs. A line ID is a unique identifier for the text of a line or an option. When Yarn Spinner needs to show a line or option to the user, it asks its Line Provider to provide it with a LocalizedLine object. This object contains the text of the line or option, in the user's current locale.

As discussed in Line Providers, you can have different kinds of Line Providers; for example, the Text Line Provider creates LocalizedLine objects that just contain text, while Audio Line Provider creates objects that also contain an AudioClip.

Once a LocalizedLine has been created, the Dialogue Runner has everything that it needs to show content to the user. The next steps vary depending on whether it's showing a line or an option.

Presenting Lines

When Yarn Spinner encounters a line of dialogue, it calls the RunLine method on each Dialogue View. This method takes two parameters: the first is the LocalizedLine that the Line Provider created, and the second is a delegate that the Dialogue View should call when the line has finished being presented.

In Dialogue Views, a line is presented when the user has received the entire line, and is ready to move on to the next line. The practical outcome of what this means depends on the Dialogue View itself; for example, a Dialogue View that plays voice-over audio might finish presenting when all of the audio has played, while a Dialogue View that gradually reveals the text of a line might finish presenting when all of the text is visible.

The Dialogue Runner will wait until all Dialogue Views report that they've finished presenting the line. Once this happens, it moves on to the next part of the dialogue.

Interrupting Lines

At any point during a line's presentation, a Dialogue View can interrupt the line. It does this by calling the requestInterrupt method, which is a delegate that's set by its controlling Dialogue Runner. When this method is called, all Dialogue Views that have not yet finished their presentation receive a call to their InterruptLine method.

InterruptLine is very similar to RunLine, in that it receives a line to present and a completion handler to call when the presentation is complete. However, while RunLine is expected to present the line at its own pace, InterruptLine is a signal to finish the presentation as quickly as possible.

As before, the actual details of this depend on the Line View. To continue the examples from before, a Dialogue View that plays voice-over audio might fade out the audio over a short period of time, or even cut off playback immediately; a Dialogue View that's gradually revealing text might reveal the remaining text all at once, or rapidly reveal the remaining text.

Any Dialogue View may request that a line be interrupted. If multiple Dialogue Views request it, only the first request does anything.

Dismissing Lines

When the last Dialogue View reports that its presentation is complete, either because RunLine finished its presentation, or because InterruptLine was called and it quickly finished its presentation, it needs to tell the dialogue views to get rid of the line, and potentially prepare for more content.

The Dialogue Runner does this by calling DismissLine on all Dialogue Views. As with RunLine and InterruptLine before it, DismissLine receives a completion handler to call when it has finished dismissing the line.

As before, the details of how a line is dismissed vary with what the Dialogue View actually does. A Dialogue View that plays voice-over audio may not need to do anything to dismiss a line, because the playback has already finished; a Dialogue View that shows line text on screen might need to hide the text, possibly with an animation.

When the last Dialogue View reports that it has finished dismissing its line, the Dialogue Runner continues running the script.

Presenting Options

Options are slightly different to lines, in that they rely on receiving some kind of user input before the dialogue can continue: the Dialogue Runner needs to know which option was selected.

To handle options, Dialogue Views implement the RunOptions method. This method receives an array of DialogueOption objects, each of which represents an option that can be shown to the user, as well as a completion handler.

When this method is called, the Dialogue View uses the information contained within the DialogueOption objects to present the choices to the player, and then awaits user input. Once it knows which option was selected, it calls the completion handler, passing in the DialogueOptionID of the selected option.

Using Multiple Dialogue Views

Dialogue Runners can use multiple Dialogue Views. This is actually recommended, because it makes it easier to separate the code for handling lines, from that of running options.

All of the methods in DialogueViewBase are optional. If you don't implement a method, then the default implementation of that method is used instead; the default implementation either does nothing, or as close to nothing as it can while still working. For example, the default implementation of RunLine immediately signals that presentation is complete.

• To create a Dialogue View that shows lines, implement RunLine, InterruptLine and DismissLine.

• To create a Dialogue View that shows options, implement RunOptions.

• To create a Dialogue View that supports both, implement all four.

Responding to Dialogue Advancement Signals

During gameplay, your user may wish signal that they want to advance the dialogue: that is, they want to proceed to the next line, or they want the current line to be presented more quickly.

To handle this case, subclasses of DialogueViewBase may implement the method UserRequestedViewAdvancement, which can be called by other parts of the game.

In most cases, it is generally appropriate for implementations of UserRequestedViewAdvancement to call the requestInterrupt method, which tells the Dialogue Runner to interrupt the line (across all views) and to proceed to the next one. However, a Dialogue View may choose to perform other actions that deliver the line more quickly.

UserRequestedViewAdvancement can be called by any part of your code. Additionally, you may wish to use DialogueAdvanceInput, which is a class that listens for user input, and when it receives it, calls UserRequestedViewAdvancement on a view you specify.

Accessing Line Metadata

To access the tags on a line, you use the Metadata property on the LocalizedLine objects you receive. It's up to your code to decide what to do with the tags themselves.

Seeing it in Action

To demonstrate how a custom Dialogue View is put together, we've created an example Dialogue View, which demonstrates the above features and is heavily commented. For more information, see the code on GitHub.

A Dialogue View is a kind of component that receives content from a Dialogue Runner, and presents it to the player. Dialogue Views 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 Views. For example, you might have one Dialogue View that's designed to display lines of dialogue, and another that's in charge of displaying options to the player.

Because every game's needs are different, a Dialogue View is designed to be extremely customisable, and you can create your own custom dialogue views to suit the needs of your game.

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

• Line View is a Dialogue View 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.

• Option List View is a Dialogue View that displays a collection of options in a list.

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

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

The Dialogue Runner is the bridge between the dialogue that you've written in your Yarn scripts and the other components of your game. It's a component that's responsible for loading, running and managing the contents of a Yarn Project, and for delivering the content of your Yarn scripts to the other parts of your game, such as your user interface.

Setting up a Dialogue Runner is the first step in adding dialogue to your game. To use a Dialogue Runner, you add it to a game object in your scene, connect it to Dialogue Views, and provide it with a Yarn Project to run.

When you want to start running the dialogue in your game, you call the Dialogue Runner's StartDialogue method. When you do this, the Dialogue Runner will begin delivering lines, options and commands to its Dialogue Views.

The Dialogue Runner is designed to work with other components of Yarn Spinner for Unity:

• The contents of your dialogue are delivered to your Dialogue Views.

• The values of variables are stored and retrieved using the Dialogue Runner's Variable Storage.

• The content that users should see - that is, the text in their current language, voice over clips, and other assets - are retrieved using the Dialogue Runner's Line Provider.

Inspector

A Yarn script is a text file containing your dialogue.

Creating a New File

To create a new Yarn script in Unity, follow these steps:

• Open the Assets menu, and choose Yarn Spinner -> Yarn Script.

• Unity will create a new file. Type in a name for the file, and press return.

The new file that you've just created will contain a single node, which has the same name as the file.

Editing Yarn Scripts

To edit a Yarn script, double-click it in Unity. The file will open in your editor. When you save your changes and return to Unity, it will be re-compiled.

Options List View is a Dialogue View that presents a list of options in a list.

When this view receives options from the Dialogue Runner, it creates an instance of the Option View prefab you specify in the Option View Prefab property, and adds it as a child of the options list view.

Inspector

Line View is a Dialogue View that displays a single line of dialogue inside a Unity UI canvas. When the Dialogue Runner encounters a line in your Yarn Script, the Line View will display it, wait for the user to indicate they're done reading it, and then dismiss it.

Showing the Character's Name

If a line contains a character's name at the start, Line View can be configured to show the name in a separate text view to the line text itself. If the Character Name Text property is connected to a TextMeshPro Text object, then the character's name will appear in this object.

If you don't attach a Text object to the Character Name Text property, you can choose to either show the character name as part of the line (that is, in the Line Text view), or don't show it all.

Presenting Lines with Visual Effects

Line View can be configured to use visual effects when presenting lines.

• You can choose to have the Line View fade in when a line appears, and fade out when the line is dismissed.

• You can choose to have the text of the line appear, one letter at a time, with a "typewriter" effect.

Continuing to the Next Line

The Dialogue Runner will automatically proceed to the next piece of content once all dialogue views have reported that they've finished with a line.

If the 'Auto Advance' option on a Line View is turned on, then the Line View will signal that it's done with a line as soon as all visual effects have finished.

If 'Auto Advance' is turned off, then the Line View will not signal that it's done when the effects have finished, and the line's delivery will stop. To make the Line View finish up, you can call the UserRequestedViewAdvancement method, which tells the Line View that the user wants to proceed. The built-in Dialogue System prefab comes set up with a 'Continue' button that calls this method. You can also call this method from code, or use the Dialogue Advance Input component to trigger it based on user input.

Inspector

Dialogue Advance Input is a component that receives user input, and uses it to signal to a Dialogue View that the user wants to advance to the next piece of content. Dialogue Advance Input is generally used to implement a 'press spacebar to continue / skip' mechanic.

To use a Dialogue Advance Input, create a new game object, and attach a Dialogue Advance Input component to it using the Add Component button.

You can control what specific input the component is looking for by changing the Continue Action Type setting:

• If you set the Continue Action Type to Key Code, you can select a key on the keyboard that will continue to the next line on press.

• If you set the Continue Action Type to Input Action, you can create an Action from an input device (such as from a keyboard, gamepad, or other method).

• If you set the Continue action Type to Input Action from Asset, you can attach an Action from an Input Actions asset that you've set up elsewhere.

Line Providers are components that are responsible for taking the objects that the produces, and fetches the appropriate localised content for that line. Line Providers produce objects, which are sent to the Dialogue Runner's .

When a Yarn script runs, the Dialogue Runner produces Line objects. These objects contain information about the line, but not the text of the line itself. This is because it's the responsibility of the game to load the user-facing parts of the line, including the text of the line in the player's current language setting, as well as any other assets that may be needed to present the line (such as audio files for voiceover.)

Yarn Spinner comes with three built-in types of line providers:

• is a Line Provider that fetches the text of a line, given a language to use.

• is a Line Provider that fetches the text of a line as well as an , given languages to use.

• is a Line Provider that fetches the text and any localised assets from .

An Option View is an object that the uses when presenting options. When the delivers options to your game, Options List View will create an Option View for each option that could be selected.

When the Option View is pressed, the Options List View will notify the Dialogue Runner of the user's selection.

Inspector

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.

Every game's data storage requirements are different. For this reason, Yarn Spinner is designed to make it straightforward to create your own custom component for managing how Yarn scripts store and load variables in ways that work with the other parts of your game.

Custom Variable Storage components are subclasses of the abstract class VariableStorageBehaviour. To implement your own, you need to implement the following methods:

public bool TryGetValue<T>(string variableName, out T result);
public void SetValue(string variableName, string stringValue);
public void SetValue(string variableName, float floatValue);
public void SetValue(string variableName, bool boolValue);
public void Clear();
public bool Contains(string variableName);

For a complete tutorial on how to build an entirely custom variable storage system, see Yarn Variables and Custom Variable Storage.

Yarn Spinner Projects

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

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

• 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 website you can visit!

⭐️ To learn to use the Core Components, jump into the Beginner's Guide.

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

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

⭐️ To purchase the Add-ons, visit the Yarn Spinner Itch.io Store, or just read the documentation.

Yarn Labs Experiments

These are experimental projects that are likely to eventually be released, 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 working through our three-step Beginner's Guide.

Getting Started

The best way to get started with Yarn Spinner, using the Core Components, is to work through our Beginner's Guide, which is a gentle introduction to:

1. Syntax Basics — Using Try Yarn Spinner to learn the basic syntax for writing Yarn, the language for writing dialogue in Yarn scripts.

2. Writing Narratives — Moving to Yarn Spinner for Visual Studio Code, and learning how to structure narratives and stories using features of the Yarn language.

3. Using a Game Engine — Using Yarn Spinner for Unity, Yarn Spinner for Godot, or Yarn Spinner for Rust, and integrating a Yarn script with what’s happening in the game engine, as well as one simple way of nicely displaying your dialogue in-game.

This beginner's guide complements the rest of the documentation, and provides a starting point that covers all the basics necessary for making the most of the rest of the documentation. We strongly recommend you work your way through this guide.

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

Audio Line Provider is a Line Provider that fetches localized text for a line of dialogue, as well as a localized AudioClip.

Audio 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

Installing Visual Studio Code and Setting Up

To use Yarn Spinner for Visual Studio Code, you’ll need to:

1. Download Visual Studio Code and install it.

2. Click this link to open Visual Studio Code, and jump to the Yarn Spinner Extension.

3. Click the install button!

Using Yarn Spinner for Visual Studio Code

Create a new, empty file in Visual Studio Code (VS Code), and add something like the following to it (it’s just the Party example, from the end of the previous step):

title: Party
---
<<declare $partyHats = 0>>
Partygoer A: We're having a party!
Partygoer B: Yeah, we are!
Partygoer A: Want a party hat?
    -> Yes, please!
        <<set $partyHats = $partyHats + 1>>
        Partygoer A: Here you go!
        Partygoer B: Look over here!
            <<jump OverHere>>
    -> No, thanks. I despise happiness. I relish misery.
        Partygoer A: We see that.
        Partygoer B: Why don't you go over there?
            <<jump OverThere>>
    -> I'd rather go over here...
        <<jump OverThere>>
===

title: OverHere
---
Partygoer C: Oh hi. Can I borrow a party hat? 
Partygoer C: I lost mine.
<<if $partyHats > 0>>
    Partygoer C: Looks like you can spare a hat.
        -> Sure, here you go.
            <<set $partyHats = $partyHats - 1>>
            <<jump OverThere>>
        -> No. Never. Absolutely not.
            <<jump OverThere>>
<<else>>
    Partygoer C: Oh, you don't have any to spare.
    Partygoer C: Cya around, I guess.
    <<jump Party>>
<<endif>>
===

title: OverThere
---
Partygoer D: Hi!
<<if $partyHats > 0 and $partyHats <= 2>>
    Partygoer D: You're definitely fun.
        -> Why?
            Partygoer D: You like party hats.
                -> Thanks! You're fun too.
                    <<jump Party>>
<<elseif $partyHats > 2>>
    Partygoer D: You have too many hats!
    Partygoer D: It really scares me.
        -> Sorry...
            <<jump Party>>
<<else>>
    Partygoer D: You should go party somewhere else in this party.
        -> Oh, bye, then...
            <<jump Party>>
<<endif>>
===

Save the file somewhere sensible as TestYarn1.yarn (the filename is not important, but the .yarn extension is).

With the new file open, look at the bottom right-hand corner of the VSCode window, and verify that the file is recognised as a Yarn Spinner file:

Yarn Spinner for Visual Studio Code allows you to do a whole bunch of useful things in VSCode, including syntax highlighting, viewing your nodes in a graph, and more. Let’s take a look at some of them.

Syntax highlighting

The most obvious immediate feature is that Yarn’s syntax will be appropriately identified and highlighted in the editor. Very useful. You can see this in action in your TestYarn1.yarn file, showing the Party example.

But, so far, this is pretty similar to the features of Try Yarn Spinner. Let’s go deeper.

Graph view

Press the Show Graph button in the top right-hand corner of the window, or open the Command Palette and choose Yarn Spinner: Show Graph. A graph view, showing your nodes from the open yarn script will appear!

Yarn script awareness

Yarn Spinner for Visual Studio code has a few other tricks up its sleeve when it comes to making your Yarn script writing experience better.

For example, if you add a comment using the triple slash /// you can describe what a variable is for, and Yarn Spinner for Visual Studio will display this description whenever you hover over a variable.

So, if you add a /// comment above the declaration of $partyHats, like this:

/// Counts the number of Party Hats that the player has. Starts at 0.
<<declare $partyHats = 0>>

You’ll then be able to hover over $partyHats and see the description, like this:

You can also hold Command (on macOS) or Control (on Windows and Linux) and click on the name of a node (for example inside a <<jump>> statement), and the editor will jump to that node. You can also do this from the Graph View.

You can also use Yarn Spinner for Visual Studio Code to easily find out what references a node, by looking above each node’s header. The amount of references to that node will be shown, as well as a shortcut to jump to that node in the Graph View:

Clicking the references will show you all the references to that node.

Improving the graph view

The Graph View is useful out of the box, but with a few tweaks to your Yarn scripts you can make it even more effective.

For example, you can assign a colour to nodes by adding a color header, like so:

title: Party
color: red
---
// the node's content is here
===

Then, your node will have a colour indicator.

You can also put nodes in groups by adding a group header, like so:

title: Party
color: red
group: main
---
// this node's content is here
===

title: OverHere
color: green
group: other_places
---
// this node's content is here
===

title: OverThere
color: purple
group: other_places
---
// this node's content is here
===

Then, your nodes will be visually grouped in the Graph View:

Neither the colour nor the group will have any impact on your game’s use of the dialogue. It’s just for ease-of-use of the Graph View.

You can also use the tags header, with a space-separated list of tags. This doesn’t impact anything in the editor, but is available to be queried from Yarn Spinner within Unity, for you to do what you want with.

Writing a story

Take what you’ve learned so far, and write a story that makes use of:

• nodes

• jump statements

• variables

• if statements (and elseif)

• setting variables

• options, nested options, and conditional options

• built-in functions

… and is nicely laid out in Yarn Spinner for Visual Studio Code, with groups, colours, and a nicely presented Graph View.

You story should be playable using the Preview feature of Yarn Spinner for Visual Studio Code, accessible via the Command Palette.

This page covers what you need to know to use the internal localisation system built into Yarn Spinner. This supports both the localisation of the text, so the lines themselves, and your assets needed for them.

Watch a video where Yarn Spinner developer Jon Manning walks you through using the Built-In Localisation System:

Set Up Localisations

When you want to prepare a Yarn Project for an additional language, you add a new Localisation in the Yarn Project.

Localisations are how you tell Yarn Spinner where to find the localised lines, and the localised line assets, for a given language.

To create a new Localisation, open the Localisations list in the Yarn Project's Inspector, and click the + button.

Localisations have the following properties:

Creating a Translation

After you've set up a localisation, you can translate your dialogue into that localisation's language. To do this, you generate a strings file.

To create a strings file, select a Yarn Project, and click the "Export Strings and Metadata as CSV" button. Unity will ask where you want to save the strings file (the metadata file will have the same name as the strings file, but with a "-metadata" appended to it).

A strings file has the following structure:

Once you've exported a strings file, you can translate it into another language: for each row in the database, change the language column to the new language you're translating into, and the text column to the translated text of the line.

Once you have a strings file that's been translated into your target language, you can add it to your Localisation. To do this, drag and drop the translated strings file into the Strings File property of your localisation, and click Apply.

Adding Localised Assets

Localised line assets are assets that are associated with a particular line, in a particular localisation. The most common example of this is voice-over lines, which are audio assets that are associated with each line.

Selecting a Language at Run-time

The specific localised line, and localised line assets, that a line provider fetches depends on which language they have been configured to fetch.

The Text Line Provider has a single language option, which controls which language the line will appear in.

The Audio Line Provider has two language options: the language of the text, and the language of the audio files that are retrieved. This means that you can configure it to provide text in one language, and audio in another.

Unity Localised Line Provider is a Line Provider that fetches localized text and assets for a line of dialogue from a String Table and optionally from an Asset Table, based on the project's current localization settings.

Inspector

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.

Text Line Provider is a Line Provider that fetches localized text for a line of dialogue, given the user's language.

Inspector

Localization is the process of translating and adapting content to a specific language, region or culture.

Yarn scripts are written in human-readable language. This is generally a single language, and (most of the time) will be written in the language that your development team primarily speaks. The language that a Yarn project is written in is called the base language.

However, if you want your dialogue to be understood by people who don't speak this language, you will need to translate it. Yarn Spinner is designed to make it easy to extract the user-facing text of your dialogue into a strings file, which can then be translated into a different language, and then loaded at run-time. You can translate your project into as many languages as you'd like, and Yarn Spinner will handle it for you automatically.

Yarn Spinner is also designed around the idea that a line of dialogue may have assets associated with it. Most commonly, this means an audio file that contains an actor performing the line, so that it can be used in your game as a voice-over. These assets are also localisable.

Localisation Terminology

• Localisation: A set of information that describes where to find text and assets for a given language.

• Base language: The language that your Yarn script files are written in.

• Strings file: A text document that contains translated versions of Yarn lines.

• Line ID: A unique code that identifies a line of dialogue or an option in the original source text.

• Localised line: The text of a line of dialogue, in a particular locale.

• Localised line asset: An asset (for example, an audio clip) that's associated for a particular line, in a particular locale. For example, an audio clip containing the voiceover for the line "Hello there", in German.

• Line provider: A that receives line IDs from the Dialogue Runner, and fetches the localised line and localised line assets (if present) for the player's preferred locale.

Workflow

To localise your Yarn scripts, you specify the 'base language' that your scripts are written in. You then add unique line ID tags to each line that identify each line. Finally, the localisation system reads your tagged lines and fills the string table for your base language. You can then add additional translations for your lines to the string tables for other languages.

Writing Yarn Scripts

Every Yarn script is associated with a base language. By default, Yarn Spinner sets the base language to that of your current locale. For example, if your computer is set to use Australian English, then Yarn Spinner will use that as the base language.

Adding Line IDs

In order to match different versions of a line, you need to add a line id to each line of dialogue. A line ID is a tag that appears at the end of a line that uniquely identifies a line of dialogue in your game.

Here's an example of a line of dialogue with a line tag:

In this example, the line of dialogue has a line ID of 1a64a5.

Yarn Spinner can add line IDs to your dialogue for you. To do this, select your Yarn Project, and click 'Add Line Tags to Scripts'. Yarn Spinner will re-write all of the script files, adding a line ID to any line that doesn't already have one.

Using Localised Content in Games

Defining Commands

You can define your own commands, which allow the scripts you write in Yarn Spinner to control parts of the game that you've built.

In Unity, there are two ways to add new commands to Yarn Spinner: automatically, via the YarnCommand attribute, or manually, using the DialogueRunner's AddCommandHandler method.

The YarnCommand attribute

The YarnCommand attribute lets you expose methods on a MonoBehaviour to Yarn Spinner.

When you add the YarnCommand attribute to a method, you specify what name the command should have in Yarn scripts. You can then use that name as a command.

If the method is not static, you call it with the name of the game object you want the command to run on.

For example, if you have a script called CharacterMovement that has a method Leap, you can add a YarnCommand attribute to it to make it available to your Yarn scripts:

If you save this in a file called CharacterMovement.cs, create a new game object called MyCharacter, and attach the CharacterMovement script to that game object, you can run this code in your Yarn scripts like this:

If the method is static, you call it directly, without providing a game object name. For example:

If you save this in a file called FadeCamera.cs, you can run this code in your Yarn scripts like this:

You can also use methods that take parameters. Yarn Spinner will take the parameters that you provide, and convert them to the appropriate type.

Methods that are used with YarnCommand may take the following kinds of parameters:

Method parameters may be optional.

For example, consider this method:

This command could be called like this:

Finding Yarn Commands in your Project

You can see a list of commands that you've registered with the YarnCommand attribute by opening the Window menu and choosing Yarn Spinner -> Commands.

This will show a list of every command that you can call in your Yarn script, what parameters they take, and which parameters are optional.

Adding commands through code

You can also add new commands directly to a Dialogue Runner, using the AddCommandHandler method.

AddCommandHandler takes two parameters: the name of the command as it should be used in Yarn Spinner, and a method to call when the function is run.

If you want to add a command using AddCommandHandler that takes parameters, you must list the types of those parameters.

For example, to create a command that makes the main camera look at an object, create a new C# script in Unity with the following code:

Add this script to any game object, and it will register the camera_look in the Dialogue Runner you attach.

You can then call this method like this:

YarnCommand vs AddCommandHandler

We provide two different means of handling commands in Yarn Spinner: the AddCommandHandler method and the YarnCommand attribute. Both of these provide effectively the same functionality, and under-the-hood the YarnCommand attribute is even a wrapper around the AddCommandHandler call. So if there are two different ways to achieve the same thing when should you use each one?

• The YarnCommand attribute allows you to tag specific methods as being a command, Yarn Spinner will then automatically handle the binding and connection of the the command in text to the method call in C#.

• AddCommandHandler method allows you to manually connect a method in C# to a command in Yarn, letting you set the name of the command and which method it connect to, giving you the control over the binding.

Most of the time, we feel that the YarnCommand attribute is the better option, because it is easier to use, and maps well to how we find most people use commands - that is, calling specific methods on specific GameObjects.

This convenience, however, does come at a cost of flexibility, because your YarnCommands either need to be on static methods, or follow specific calling conventions, which may not be what you need or want.

The YarnCommand attribute works best in our opinion when your commands are calling into specific GameObjects in your scene, which means that it works very well for moving, animating, or changing characters and items in a scene.

For larger gameplay changing moments, such as loading new scenes, moving between dialogue and the rest of your game, or for more global events like saving the game or unlocking an achievement, the AddCommandHandler method is better.

Making Commands Using Coroutines

For example, here's how you'd write your own custom implementation of <<wait>>. (You don't have to do this in your own games, because <<wait>> is already added for you, but this example shows you how you'd do it yourself.)

This new method can be called like this:

Defining Functions

To create a function, you use the YarnFunction attribute, or the AddFunction method on a Dialogue Runner. These work very similarly to commands, but with two important distinctions:

1. Functions must return a value.

2. Functions are required to be static.

For example, here's a custom function that adds two numbers together:

When this code has been added to your project, you can use it in any expression, like an if statement, or inside a line:

Yarn functions can return the following types of values:

• string

• int

• float

• bool

Writing Yarn with Try Yarn Spinner

When you first start learning Yarn, the best tool to work with is , so fire up your web browser—no installation necessary!

Open your web browser, and navigate to Try Yarn Spinner at

In Yarn, everything you write is text. Yarn files are just plain text files with a .yarn extension.

Everything inside a Yarn file is structured around nodes and lines.

In Try Yarn Spinner, the first node to run is always called Start, so we’ll write that now.

Copy and paste, or write, the above Yarn script into Try Yarn Spinner!

The title of a node is important, because your game uses node titles to tell Yarn Spinner which node to start running. You also use the title of a node when you want to jump to another node.

So this node is titled “Start”.

Node titles are not shown to the player and must start with a letter, and can contain any letters, numbers and underscores, but cannot contain a period or other symbols.

Node headers can actually contain any number of lines with the structure key: value. This can be used to store additional information, such as the in-game location the conversation is taking place.

If you put the above Yarn, or something very similar, into and click the Test button, you’ll see the dialogue appear in the right side of the screen.

Getting a bit more complex

Let’s make it a bit more complex. Update the Yarn to look like the following:

Update the script in Try Yarn Spinner to the above Yarn and try running it.

In this node, there are the following elements:

• the header, with the node’s title

• the --- marker, which indicates where the body of a node begins

• some lines, representing a Narrator speaking…

• and the === marker, which indicates the end of a node