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.

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

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

• Speech Bubbles for Yarn Spinner

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.

Start learning

If you're new to Yarn Spinner, we recommend that your next step is working through our three-step Beginner's Guide.

Installing Visual Studio Code

To use Yarn Spinner for Visual Studio Code, you’ll first need to install Visual Studio Code.

First, download Visual Studio Code from the official website: https://code.visualstudio.com

Once it’s downloaded, install it, and open it up. Choose the View menu → Extensions, to open the Extensions Marketplace:

In the Extensions Marketplace, search for “Yarn Spinner”, and install the extension provided by Secret Lab:

Install Yarn Spinner for Visual Studio Code.

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.

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 or Yarn Spinner for Godot, 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.

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:

title: Node_Title
---
Here are some lines!
Wow!
===

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:

Mae: Well, this is great.
Mae: I mean I didn't expect a party or anything
Mae: but I figured *someone* would be here.
Mae: ...
Mae: Welcome home, Mae.

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:

This is a line of dialogue, without a character name.
Speaker: This is another line of dialogue said by a character called "Speaker".

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:

Companion: Hi there! What do you feel like doing today?

-> Player: I want to go swimming.
-> Player: I'd prefer to go hiking.

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.

Companion: Hi there! What do you feel like doing today?

-> Player: I want to go swimming.
    Companion: Okay, let's go swimming.
-> Player: I'd prefer to go hiking.
    Companion: Cool, we'll go hiking then.
    
Player: Sounds good!

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.

Companion: Hi there! What do you feel like doing today?

-> Player: I want to go swimming.
    Companion: Okay, let's go swimming.
    Companion: Where do you want to swim?
    -> Player: The lake!
        Companion: Nice! It's a great day for it.
    -> Player: The swimming pool!
        Companion: Oh, awesome! I heard they installed a new slide.
-> Player: I'd prefer to go hiking.
    Companion: Cool, we'll go hiking then.
    
Player: Sounds good!

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:

title: Start
---
Companion: Hi there! What do you feel like doing today?

-> Player: I want to go swimming.
    Companion: Okay, let's go swimming.
    Companion: Where do you want to swim?
    -> Player: The lake!
        Companion: Nice! It's a great day for it.
    -> Player: The swimming pool!
        Companion: Oh, awesome! I heard they installed a new slide.
-> Player: I'd prefer to go hiking.
    Companion: Cool, we'll go hiking then.
    
Player: Sounds good!
===

title: Start
---
Companion: Hi there! What do you feel like doing today?

-> Player: I want to go swimming.
    Companion: Okay, let's go swimming.
    <<jump Swimming>>
-> Player: I'd prefer to go hiking.
    Companion: Cool, we'll go hiking then.
    <<jump Hiking>>
===
title: Swimming
---
Companion: Where do you want to swim?
-> Player: The lake!
    Companion: Nice! It's a great day for it.
-> Player: The swimming pool!
    Companion: Oh, awesome! I heard they installed a new slide.

<<jump Done>>
===
title: Hiking
---
Companion: Have you got your hiking boots ready?
-> Player: Yes.
    Companion: Great, let's go!
-> Player: No.
    Companion: We can swing by your place and pick them up!

<<jump Done>>
===
title: Done
---
Player: Sounds good!
===

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.

Writing Yarn with Try Yarn Spinner

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

Open your web browser, and navigate to Try Yarn Spinner at https://try.yarnspinner.dev

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.

---
Narrator: Hi, I'm the narrator for this beginner's guide!
===

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 Try Yarn Spinner 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

Let’s chat about lines…

Almost everything is a line 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, Yarn Spinner 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.

Mae: Well, this is great.
Mae: I mean I didn't expect a party or anything
Mae: but I figured *someone* would be here.
Mae: ...
Mae: Welcome home, Mae.

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:

This is a line of dialogue, without a character name.
Speaker: This is another line of dialogue said by a character called "Speaker"

Options provide choices within nodes

After the lines of the Narrator speaking you’ll notice some lines that are indented, and start with a -> interspersed amongst other lines from the Narrator:

title: Start
---
Narrator: Hi, I'm the narrator for this beginner's guide!
Narrator: I'm talking to you with Yarn Spinner!
Narrator: What do you think of all this, then?
    -> It's alright, I guess.
        Narrator: Well, that's not very nice.
        Narrator: I'm trying my best here.
    -> It's great. I love it.
        Narrator: Oh, you're too kind.
        Narrator: I'm just doing my job.
===

These lines are called options, and they are how you let the player decide what to say. Options let you show multiple potential lines of dialogue to the player, who is then able to choose one.

As you might’ve guessed, an option line is denoted by starting the line with a ->

After that, the content of the line is like any other line.

If you put the above, updated Yarn, or something very similar, into Try Yarn Spinner and click the Test button, you’ll see the dialogue appear in the right side of the screen, and as you progress through it, eventually you’ll hit some options, which are presented to the player:

Depending on the choice of option, one set of lines from the Narrator, reacting to the player’s choice, will be displayed.

Nesting options within options

You can also nest options inside other options:

title: Start
---
Narrator: Hi, I'm the narrator for this beginner's guide!
Narrator: I'm talking to you with Yarn Spinner!
Narrator: What do you think of all this, then?
    -> It's alright, I guess.
        Narrator: Well, that's not very nice.
        Narrator: I'm trying my best here.
            -> Are you really? I don't think so.
                Narrator: Well, I never!
                Narrator: I'm going to have to have a word with the writer.
            -> Oh, OK. I'm sorry.
                Narrator: That's better.
                Narrator: I'm glad we could resolve this.
    -> It's great. I love it.
        Narrator: Oh, you're too kind.
        Narrator: I'm just doing my job.
            -> You're doing a great job.
                Narrator: Oh, stop it, you.
                Narrator: You're making me blush.
            -> You're a natural.
                Narrator: Oh, you.
                Narrator: I'm just doing my job.
===

Put the above script in Try Yarn Spinner, and click Test to run it!

The only new thing that’s happening here is that options are inside other options. If you play this, inside Try Yarn Spinner, then you’ll be able to interact with the options based on the choices you make.

Have lots of options can get complex, so it’s often a good opportunity to break your story up into nodes and jump between them. We’ll do that next.

Jumping between nodes

You might have noticed that it’s a bit hard for you, the writer, to follow what’s going on, when you start nesting too many options, have lots and lots of lines of dialogue, or a combination thereof.

When things start to become too much for a single node, you can break things into multiple nodes and use the <<jump>>statement to, you guessed it… jump to another node.

Here’s an example of the <<jump>> statement in action:

title: Start
---
Narrator: Hi, I'm the narrator for this beginner's guide!
Narrator: I'm talking to you with Yarn Spinner!
Narrator: What do you think of all this, then?
    -> It's alright, I guess.
        <<jump Alright>>
    -> It's great. I love it.
        <<jump Love>>
===

title: Alright
---
Narrator: Well, that's not very nice.
Narrator: I'm trying my best here.
    -> Are you really? I don't think so.
        Narrator: Well, I never!
        Narrator: I'm going to have to have a word with the writer.
    -> Oh, OK. I'm sorry.
        Narrator: That's better.
        Narrator: I'm glad we could resolve this.
===

title: Love
---
Narrator: Oh, you're too kind.
Narrator: I'm just doing my job.
    -> You're doing a great job.
        Narrator: Oh, stop it, you.
        Narrator: You're making me blush.
    -> You're a natural.
        Narrator: Oh, you.
        Narrator: I'm but a humble narrator.
===

Put the above script in Try Yarn Spinner, and click Test to run it, and observe how the jumps work.

By now, hopefully, you’re seeing what’s going on here, but let’s go through it to make sure.

In this yarn script there are three nodes: Start, Alright, and Love and, depending on the choice made by the player inside the Start node, the conversation will jump to Alright (if they’re a bit rude) or Love (if they’re somewhat polite).

The jump statement is used to move the narrative to a different node, and takes a single parameter, which is the full title of the node you want to jump to, and you can see it in use in our Start node:

title: Start
---
Narrator: Hi, I'm the narrator for this beginner's guide!
Narrator: I'm talking to you with Yarn Spinner!
Narrator: What do you think of all this, then?
    -> It's alright, I guess.
        <<jump Alright>>
    -> It's great. I love it.
        <<jump Love>>
===

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

Logic and variables

Of course, Yarn is actually a full programming language, which means it has support for writing code that stores information in variables.

Yarn has three types of variables, numbers, strings, and booleans:

Variables can be declared, set, and checked.

Declaring variables

A variable is declared using a declare statement. It looks like this:

<<declare $characterName = "Shadowheart">>

This declare statement declares a new variable named $characterName and stores the value "Shadowheart" inside it. When you first declare a variable, that sets its type.

So this variable, $characterName, will always be of type string, because we declared it with a string, "Shadowheart".

Here’s an example of declaring two more variables, one of type number, and one of type boolean:

<<declare $goldAmount = 100>>
<<declare $hasAmulet = false>>

Every variable you use must have a name; in Yarn, all variable names start with a dollar sign ($).

As with node titles, variable names must not contain spaces. While they can contain a range of different characters the first character must be a letter.

Your variable names will be made up of only letters, numbers and underscores.

Setting variables

Of course, it’s not much use to declare a variable, if you can’t update it later. We call updating the contents of a variable setting. A variable is set using the set statement.

Here’s how we’d update the $characterName variable to a new name:

<<set $characterName to "Karlach">>

Because $characterName was declared as type string, you cannot then set it to a number, or a boolean, so the following will not work:

<<set $characterName to 42>>

A variable must always have a value. There is no concept of null, or an empty variable in Yarn.

Expressions and variables

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:

<<set $hamCounts = 2 + 1>>

<<set $numberOfPets = $numberOfPets + 1>>

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:

<<set $lemons = "hello" + 1>> // this will not work

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

Checking and using variables

Variables by themselves aren’t much good if they cannot have some sort of impact on your narrative. So, of course, they can!

The most straightforward way to use a variable is to show the contents of it in a line. To do this we refer to the variable by name inside a line, and put it inside braces, like this: {$characterName}.

For example:

title: Start
---
<<declare $characterName = "Player">>

Narrator: Hi there!
Narrator: What's your actual name, anyway?
    -> My name is Bruce.
        <<set $characterName to "Bruce">>
    -> My name is not Bruce.
        <<set $characterName to "Notbruce">>
    -> My name doesn't matter...
Narrator: Ah, nice to meet you, {$characterName}!
===

Put the above script in Try Yarn Spinner, and click Test to run it.

Using variables with flow control

In addition to storing information, variables are useful for controlling what's shown to the player. To do this, you use ifstatements, elseif statements, else, endif, statements.

An if statement allows you to control whether a collection of lines is shown or not. When you write an if statement, you provide an expression, which is checked.

The if, elseif, else, and endif statements look much like all the other statements we’ve been using: <<if>>, <<elseif>>, <<else>>, and <<endif>>.

Here’s an example:

title: Start
---
<<declare $charName = "Player">>

Narrator: Hi there!
Narrator: What's your actual name, anyway?
    -> My name is Bruce.
        <<set $charName to "Bruce">>
    -> My name is not Bruce.
        <<set $charName to "Notbruce">>
    -> My name doesn't matter...
Narrator: Ah, nice to meet you, {$charName}!
  <<if $charName is "Bruce">>
    Narrator: I'm Bruce, too!
    Narrator: What a coincidence!
  <<elseif $charName is "Notbruce">>
    Narrator: That seems like a strange name, but I won't judge.
  <<else>> 
    Narrator: That's a lazy name.
    Narrator: You should be ashamed of yourself.
  <<endif>>
Narrator: Well, goodbye, {$charName}!
===

Put the above script in Try Yarn Spinner, and click Test to run it.

In this example, after the Narrator meets the character, and says it’s nice to meet them, greeting them by name, we use <<if $charName is "Bruce">> to check if the variable $charName is set to the value "Bruce".

If it is, then we have some nice lines about the Narrator also being named that, otherwise we use <<elseif $charName is "Notbruce">> to check if the variable $charName is set to the value "Notbruce", and provide some lines from the Narrator if it is.

If $charName is set to neither of those values, then we hit the <<else>> statement, which catches all other possible values, and we provide some lines that say their name—whatever it is—is a lazy one. Then we hit the <<endif>> statement, which ends the entire if statement.

Conditional options

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

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

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

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.

It’s important to remember that Yarn Spinner always delivers _every_** option in an option group to the game**; it's up to the game to decide what to do with options that are marked as unavailable.

For example, an unavailable option might be shown to the user, but not selectable, so that the user can see that they _could_have been able to say that if circumstances had been different.

Update the following example to use a conditional option at some point:

title: Start
---
<<declare $charName = "Player">>

Narrator: Hi there!
Narrator: What's your actual name, anyway?
    -> My name is Bruce.
        <<set $charName to "Bruce">>
    -> My name is not Bruce.
        <<set $charName to "Notbruce">>
    -> My name doesn't matter...
Narrator: Ah, nice to meet you, {$charName}!
  <<if $charName is "Bruce">>  
    Narrator: I'm Bruce, too!
    Narrator: What a coincidence!
  <<elseif $charName is "Notbruce">> 
    Narrator: That seems like a strange name, but I won't judge.
  <<else>>
    Narrator: That's a lazy name.
    Narrator: You should be ashamed of yourself.
  <<endif>>
Narrator: Well, goodbye, {$charName}!
===

title: Start
---
<<declare $charName = "Player">>

Narrator: Hi there!
Narrator: What's your actual name, anyway?
    -> My name is Bruce.
        <<set $charName to "Bruce">>
    -> My name is not Bruce.
        <<set $charName to "Notbruce">>
    -> My name doesn't matter...
Narrator: Ah, nice to meet you, {$charName}!
<<if $charName is "Bruce">>
    Narrator: I'm Bruce, too!
    Narrator: What a coincidence!
<<elseif $charName is "Notbruce">>
    Narrator: That seems like a strange name, but I won't judge.
<<else>>
    Narrator: That's a lazy name.
    Narrator: You should be ashamed of yourself.
<<endif>>
Narrator: Well, goodbye, {$charName}!
	-> Bye, bye!
	**-> Bye, Brucey! <<if $charName is "Bruce">>**
===

Functions

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 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 randomfunction returns a different random number every time you call it.

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

Yarn Spinner provides the following built-in functions:

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

• 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 integer 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, inc 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.

For example, you can use functions inside if statements, and in regular lines, as they largely behave like variables. 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)}!

Write some yarn using functions! We recommend the dice function, the random_range function, and the visited and visited_count functions.

Building narratives with Yarn scripts

So far, you’ve learned that Yarn scripts are plaintext files (stored outside of Try Yarn Spinner, they have the .yarn extension). Let’s do a quick recap…

Yarn scripts are composed of nodes, which must always start with at least a title header followed by a ---, and end with a ===:

title: Party
---

===

Inside each node are lines, which are simple lines of dialogue that are delivered to the player, and often have a character name at the beginning:

title: Party
---
Partygoer A: We're having a party!
Partygoer B: Yeah, we are!
===

Lines can also be options, which provide choices to the player:

title: Party
---
Partygoer: We're having a party!
	-> I don't like parties.
	-> I love parties!
	-> PARTY!
===

These options can be nested:

title: Party
---
Partygoer: We're having a party!
	-> I don't like parties.
		Partygoer: You should.
			-> I don't. But I can pretend.
				Partygoer: Good idea! Let's party!
			-> I prefer to nap.
				Partygoer: (whispers) we all do.
	-> I love parties!
	-> PARTY!
===

You can also have multiple nodes, and jump between them using the jump statement:

title: Party
---
Partygoer A: We're having a party!
Partygoer B: Yeah, we are!
	-> I do enjoy a party.
		<<jump Enjoy>>
	-> I was told to say the password "antiquarian".
		<<jump SecretParty>>
===

title: SecretParty
---
Secret Partygoer: Woohoo! That's the password for the secret, better party!
Secret Partygoer: Welcome!
===

title: Enjoy
---
Partygoer A: We all enjoy a party!
Partygoer B: I'll party until I cannot party anymore!
===

And you can declare variables of three different types—numbers, strings, and booleans—and use them in lines, and for flow control. You’ve also learned about conditional options and built-in functions.

The next example recaps everything you’ve learned so far, so build it up slowly, piece by piece, in a new Try Yarn Spinner tab, so you understand how it’s working. Try to improve it, or make it longer by adding conditional options and use of built-in functions.

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

With that all said, in the next part, we’ll take things further and start using Yarn Spinner for Visual Studio Code.

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

• Showing the contents of variables: You can see the current contents of all variables in your script by opening the Settings menu and choosing "Show Variables". A list of variables will appear, and as you play through your script, they'll update when your script changes their contents.

• Changing whether 'unavailable' lines are shown: Options can be marked as 'unavailable' depending on whether or not a test has passed. By default, options that fail this test are not shown in the dialogue preview at all; to change this to showing all options (including ones that the user can't choose), open the Settings menu and choose "Show Unavailable Options".

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

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.

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.

This step of the beginner's guide helps you move from writing Yarn scripts outside of a game engien, 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.

Installing Yarn Spinner for Unity

In the new empty project, open the Edit menu -> Project Settings..., and choose the Package Manager section in the left column of the Project Settings window that appears.

In the middle area of the window, add an entry named OpenUPM, with the URL set to https://package.openupm.com, and the Scopes set to dev.yarnspinner. Then, click Save.

This process adds the OpenUPM Package Registry, which is one of the ways we distribute the offical Yarn Spinner for Unity package.

With the OpenUPM Package Registry added to the project, you can close the Project Settings window and open the Window menu -> Package Manager. In the Package Manager window that appears, choose the Packages dropdown, and change the view to Packages: My Registries.

This will show the packages available from the registry (and scope) that you just added, which is likely to only be Yarn Spinner at this point. Select the Yarn Spinner package from the column on the left of the Package Manager window, and click the Install button found on the bottom right. Yarn Spinner for Unity will be downloaded and installed inside your project.

Using Yarn Spinner for Unity

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:

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

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, for your operating system and platform, and then continue to .

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.

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.1 (C# version) and create a new project.

Installing Yarn Spinner for Godot

Download a from the , 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>:

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 by right-clicking in the FileSystem dock, and choosing Resource...:

Then filter to the YarnProject resource type, and click the Create button:

Name the new Yarn Project FirstProject.tres.

Next, create a new Yarn script (a file with a .yarn extension) by right-clicking in the FileSystem dock, and choosing New TextFile:

In the resulting New Text File... window, select All Files (*) from the dropdown in the corner, 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.tres 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:

Select the 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 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 a new .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.

Opening an existing .yarn file

You can open any existing .yarn file, or collection of .yarn files, using VS Code:

With a .yarn file open, you can edit it in the text editor. The chosen .yarn file(s) will open, and you'll be able to work with them, edit them, and save them as needed:

You can show and hide the Graph View. If you click the "Show Graph" button, in the top right-hand corner, the Graph View will appear:

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

Links (for example, using the jump commands) between nodes will be visualised in the Graph View. You can use the edit button on a node in the Graph View to jump to the appropriate location in the text editor, and you can rearrange the nodes visually in the Graph View for ease of understanding the relationships between areas of your script:

You can also use the "Jump to Node" button to move to a specific node in the Graph View. This allows you to easily move between areas of your text script. Nodes in the graph view can be rearranged for convenience; this won't impact the text version of the yarn script other than updating the position (below the node title).

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:

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:

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:

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.

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

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.

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.

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

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.

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!

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!

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

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

• are files that contain your written dialogue.

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.

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.

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:

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.

The main way we recommend to install Yarn Spinner for Unity is via the Package Manager.

Install via the Unity Package Manager (recommended)

You can install the Yarn Spinner package into your project using the Package Manager window in Unity.

Yarn Spinner is available via the . This is the simplest way to install Yarn Spinner, and makes it easy to keep it up to date.

Setting Up the OpenUPM Registry in Your Project

Before you can install Yarn Spinner from OpenUPM, you first need to configure your project so that it knows where to get the package from.

1. In Unity, open the Edit menu, and choose Project Settings.

2. In the list of sections at the left hand side of the window, select Package Manager.

This window is where you tell Unity about where to find packages that come from registries besides Unity's built-in one.

1. In the Name field, type OpenUPM.

2. In the URL field, type https://package.openupm.com.

3. In the Scopes field, type dev.yarnspinner.

4. Click Save.

When you're done, the settings window should look like this:

You can now install Yarn Spinner itself.

Installing the Yarn Spinner package

1. Open the Window menu, and choose Package Manager.

2. In the toolbar, click Packages: In Project, and choose My Registries.

1. Yarn Spinner will appear in the list. Select it, and click Install.

Yarn Spinner will download and install into your project.

You can verify that everything is imported succesfully by looking for Yarn Spinner under Packages, in the Project pane.

Install from GitHub

As an alternative to downloading Yarn Spinner from OpenUPM, you can install Yarn Spinner by downloading the package directly from GitHub, where the project's source code is stored.

To install Yarn Spinner from GitHub, follow these instructions.

1. In Unity, open the Window menu, and choose Package Manager.

2. Click the + button, and choose "Add package from git URL".

1. In the text field that appears, enter the following URL: https://github.com/YarnSpinnerTool/YarnSpinner-Unity.git#current.

1. The project will download and install. This might take a moment.

Next Steps

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

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

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

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

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

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

Inspector

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 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 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 to provide it with a object. This object contains the text of the line or option, in the user's current locale.

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

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

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

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.

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.

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.

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

Accessing Line Metadata

Seeing it in Action

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 , and for delivering the content of your 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 , and provide it with a to run.

When you want to start running the dialogue in your game, you call the Dialogue Runner's 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 .

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

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

Inspector

Line View is a 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 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 component to trigger it based on user input.

Inspector

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

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.

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

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 is configured to use Addressable Assets.

Inspector

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