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.

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

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 .

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

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

We also provide experimental Yarn Labs support for:

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.

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 preferred way of writing your Yarn Spinner code is with the official Yarn Spinner Visual Studio Code Extension.

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

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

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:

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

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

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

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

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

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

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

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

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

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

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

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

Next steps with Yarn Spinner for Unity

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

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 copy of the latest version of Yarn Spinner for Godot from the GitHub repository, or clone the repository somewhere.

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

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

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

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

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

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

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

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

With that, you're ready to go!

Using Yarn Spinner for Godot

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

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

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

Next, create a new Yarn Project 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:

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

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

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

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

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

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

Next steps with Yarn Spinner for Godot

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

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:

/// The name of the player.
<<declare $playerName = "Player">>

/// The number of gold pieces that the player has.
<<declare $gold = 0>>

/// Is the door to the dungeon unlocked?
<<declare $doorUnlocked = false>>

/// What day number it is. Starts on day 0, ends on day 3.
<<declare $day = 0 as number>>

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:

<<set $greeting to "Hello, Yarn!">>

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:

// Set some initial values in some variables
<<set $myCoolNumber to 7>>
<<set $myFantasticString to "wow, text!">>

// Now change them!
<<set $myCoolNumber to 8>>
<<set $myFantasticString to "incredible!">>

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

// Set some initial values in some variables
<<set $myCoolNumber to 7>>
<<set $myFantasticString to "wow, text!">>

// This will NOT work, because you can't change types!
<<set $myCoolNumber to "8">>
<<set $myFantasticString to 42>>

<<set $variableName to "a string value">>

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.

<<set $numberOfSidesInATriangle = 2 + 1>>

<<set $numberOfSidesInASquare = $numberOfSidesInATriangle + 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:

// This will NOT work, because you can't add a string and a number:
<<set $broken = "hello" + 1>>

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:

<<set $variableName to "a string value">>
The value of variableName is {$variableName}.

The value of variableName is a string value.

Variables and Storage

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

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

The specifics of how variables need to be stored will vary depending on what game engine you're using Yarn Spinner in. To learn more about variable storage in Unity, see Variable Storage.

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

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!

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

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

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

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

You call a function inside an expression. For example:

Built-In Functions

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

visited(string node_name)

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

visited_count(string node_name)

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

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

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

There are two places you can add tags in Yarn scripts: you can add them to nodes, and you can add them to lines. Tags aren't shown to the user; instead, they're used by your game, or by Yarn Spinner itself.

Tags in lines

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

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

Accessing tags

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

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

Special tags

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

#lastline

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

For example, the following excerpt:

is treated as though it had been written as:

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

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:

Other metadata

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

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

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

The tracking header

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

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

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

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

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

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:

Commands are sent to your game's , 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 that make your game do what you need to.

Built-in Commands

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

wait

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

stop

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

Making Your Own Commands

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

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

Attributes

Attributes apply to ranges of text:

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

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

Oh, hello there!

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

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

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

Overlapping Attributes

Attributes can overlap:

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

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

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

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

Self-closing Attributes

Attributes can self-close:

[wave/]

A self-closing attribute has a length of zero.

The Close-All Marker

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

[wave][bounce]Hello![/]

Properties

Attributes can have properties:

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

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

Short-hand Properties

Attributes can have short-hand properies, like so:

[wave=2]Wavy![/wave]

This is the same as saying this:

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

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

Property Types

Properties can be any of the following types:

• Integers

• Floats

• 'true' or 'false'

• Strings

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

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

Whitespace Trimming

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

A [wave/] B

A [wave trimwhitespace=false/] B 
// (produces "A  B")

Showing Special Characters to the Player

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

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

Escaping single [ and ] characters

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

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

This will appear to the player as:

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

The backslash will not appear in the text.

Here's a backslash! \\

Here's a backslash! \

The nomarkup Attribute

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

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

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

This will appear as:

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

The character Attribute

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

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

CharacterA: Hello!
CharacterB: Oh, hi!

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

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

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

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

Text Replacement Markers

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

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

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

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

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

select

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

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

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

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

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

// or:
I think she will be there!

// or:
I think they will be there!

plural and ordinal

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

Plurals across different languages

Different languages have different rules for how numbers are pluralised.

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

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

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

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

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

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

<<if $apple_count == 1>>
    You have one apple!
<<else>>
    You have {$apple_count} apples!
<<endif>>

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

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

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

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

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

Pluralising with plural and ordinal

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

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

• one

• two

• few

• many

• other

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

• plural selects a number's cardinal plural class.

• ordinal selects a number's ordinal plural class.

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

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

For example:

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

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

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

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

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

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

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

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

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

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

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

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

A Dialogue Runner can have multiple Dialogue Views. For example, you might have one Dialogue View that's designed to display lines of dialogue, and another that's in charge of displaying options to the player.

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

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

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

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

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.

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

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

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

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

• Yarn Scripts are files that contain your written dialogue.

A Yarn Project is a file that links multiple Yarn scripts 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

A Yarn Project's inspector shows information about every variable that are used in the Yarn scripts. This section of the Inspector shows the name, type, description, and default value of each variable.

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.

If you want to translate your scripts into another language, or if you want to associate each line with assets (like voice over audio clips), you create a new Localisation. To learn about this process, see Adding Localizations and Assets to Projects.

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.

After upgrading your Yarn Project, you will need to set up any localisations you had previously configured on your project. Follow the instructions in Built-In Localisation System or Unity Localisation, depending on what your game is using.

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:

A Yarn script is a text file containing your dialogue.

Creating a New File

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

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

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

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

Editing Yarn Scripts

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

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 OpenUPM registry. 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!

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

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

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

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

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

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

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

Inspector

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

Showing the Character's Name

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

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

Presenting Lines with Visual Effects

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

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

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

Continuing to the Next Line

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

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

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

Inspector

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Text

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

Yarn Spinner doesn't do text rendering, you have to use existing Unity systems like TextMeshPro. Fortunately, TMP supports HTML-like rich text tags. See the TextMeshPro: Rich Text docs.

Alice: This text is <b>bold!</b>
Bob: This text is <color=red>red!</color>

// NOTE: '#' is a special character in Yarn, used for line tags.
// To use a HTML color hex code, you must "escape" the "#" character with a "\"
Carol: Wow I'm <color=\#ff00ff>purple</color>!

However, this bespoke approach is impractical for longer scripts or bigger projects. We recommend using TextMeshPro's Style Sheets, which make it much easier to write consistently styled text. See the TextMeshPro: Style Sheets docs.

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

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

How do I use Yarn Markup?

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

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

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

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

Variables

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

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

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

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

To read Yarn variables from C#, use VariableStorageBehaviour.TryGetValue<T>(). To write Yarn variables from C#, use VariableStorageBehaviour.SetValue().

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

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

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

static int myNumber = 10;

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

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

Then call the functions and commands in Yarn:

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

How do I 'sync' variables between Yarn and C#?

See the previous answers on working with variables. But we recommend avoiding any "sync" pattern, because then you'll have to track and maintain the same data in two different places. Programmers usually prefer a "single source of truth". Data should live in only one place. Variables should either live in Yarn or live in C#, and not in both.

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

To save the current node, save the value of DialogueRunner.CurrentNodeName somewhere, e.g. to Unity's PlayerPrefs. Then to restore it, call DialogueRunner.StartDialogue() and pass in the saved node name.

To save variables, see DialogueRunner.SaveStateToPlayerPrefs(). Then to load variables, call DialogueRunner.LoadStateFromPlayerPrefs(). These methods use Unity's built-in JSON utility to serialize a dictionary of variables to Unity's PlayerPrefs.

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

It is not currently possible to save or restore the specific line that the dialogue is running.

Control flow

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

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

To jump to a node with C#, just call DialogueRunner.StartDialogue(), even if there's already dialogue running.

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

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

Interaction / UI

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

In most cases, use the Dialogue Advance Input.

For more control, call UserRequestedViewAdvancement() on a Dialogue View, or OnContinuedClicked() on a Line View. See Creating Custom Dialogue Views.

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

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

How do I show the character name / portrait? How do I customize dialogue display?

To display anything in Yarn Spinner, use a Dialogue View component. Line View for dialogue, Options List View for choices.

Most projects will need custom views. We recommend a modular architecture where each UI element has its own LineView component. For example, a nameplate bubble has a Dialogue Character Name View that displays LocalizedLine.CharacterName, while the dialogue text window is another Line View that displays LocalizedLine.TextWithoutCharacterName. See Creating Custom Dialogue Views.

For a working example, see the "Visual Novel" sample. (In Unity, go to Window > Package Manager, and select Yarn Spinner package. Expand the "Samples" dropdown and select "Visual Novel" and import it.) Specifically, see VNManager.cs which inherits from DialogueViewBase, and changes the character name window background color (among other effects) based on the character name.

How do I make the Line View's Typewriter effect pause on punctuation?

Create a custom dialogue view with a custom effect based on Typewriter() (see Effects.cs) to detect the next text character and pause accordingly.

// in your custom Typewriter effect, replace the "while (accumulator >= secondsPerLetter)..." block with this one:
while (accumulator >= secondsPerLetter) {
   text.maxVisibleCharacters += 1;
   onCharacterTyped?.Invoke();
   accumulator -= secondsPerLetter;

   // Don't pause on the last character
   if (text.maxVisibleCharacters >= characterCount) continue;

   // Extra pause on punctuation
   var nextChar = text.text[text.maxVisibleCharacters - 1];
   if (nextChar.Equals('.') || nextChar.Equals(',') || nextChar.Equals('?') || nextChar.Equals('!')) {
       yield return new WaitForSeconds(0.3f);
   }

   accumulator += Time.deltaTime;
   yield return null;
}

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

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

The example tutorial NPC Dialogue Game can walk you through this step-by-step.

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

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

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

For a working example, see the "Space" sample. (In Unity, go to Window > Package Manager, and select Yarn Spinner package. Expand the "Samples" dropdown and select "Space" and import it.) Specifically, see PlayerCharacter.cs for how to search for nearby NPCs from a list.

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

The math / code is a little complicated. Calculate the NPC's on-screen position, then convert this screen position to UI canvas space, and reposition the dialogue bubble.

For a working example, see the "3D" sample. (In Unity, go to Window > Package Manager, and select Yarn Spinner package. Expand the "Samples" dropdown and select "3D" and import it.) Specfically, see YarnCharacterView.cs which has a method WorldToAnchoredPosition() that does a lot of this UI positioning math.

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

This is more about Unity UI rather than Yarn Spinner. For a working example, see the "Phone Chat" sample. (In Unity, go to Window > Package Manager, and select Yarn Spinner package. Expand the "Samples" dropdown and select "Phone Chat" and import it.)

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

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

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

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

System

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

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

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

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

• Simplicity. Putting everything into one big script file or one big project file is simpler sometimes.

• Ease of writing. Writers may prefer to think in terms of one file per scene, one file per chapter.

• Localization. 1 Yarn Project = 1 CSV spreadsheet per language. When translating, it is usually easier to work with fewer files, rather than fragmenting the translation across many files. As a workaround for games that need multiple Yarn Projects, you may prefer to create a single editor-only Yarn Project that's just for generating string files and translations. See Localizations and Assets.

I'm seeing crashes on startup in my WebGL / iOS / Android / IL2CPP project.

A crash bug exists in versions of Yarn Spinner earlier than 2.3 for these platforms. If you're able to upgrade your version of Yarn Spinner, the best fix is to upgrade to the most recent version of Yarn Spinner.

If you can't upgrade your version of Yarn Spinner, a workaround for this issue is to open the Build Settings window in Unity, and set the "IL2CPP Code Generation" setting to "Faster (smaller) builds."

Localization

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

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

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

Other

How do I credit Yarn Spinner in my game?

Please visit the Crediting Yarn Spinner page for more information. Thanks for thinking of us!

Community projects are written by our wonderful community. These are not supported or maintained by the Yarn Spinner team, but you might find them useful.

Many of these projects target an older version of Yarn Spinner, or are unmaintained:

• Yarn Slinger, by Jan Hohenheim: A Rust implementation of Yarn.

• YarnRunner-Python, by Relay Pro: A Python runner for Yarn.

• Crochet, by FaultyFunctions: A visual editor for writing Yarn script.

• GDYarn, by Kyperbelt: An implementation of the Yarn Spinner compiler in GDScript.

• Wol, by Bram Dingelstad: An implementation of Yarn Spinner for the Godot game engine, based on GDYarn.

• Yarn Loom, by TranquilMarmot: A Visual Studio Code extension that embeds the Yarn Classic editor.

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

There are two parts to crediting Yarn Spinner: what you're required to do if you use Yarn Spinner, and, optionally, what we'd appreciate you doing.

This page outlines the requirements, the things we'd appreciate you doing, and provides downloads of the Yarn Spinner logo.

What You're Required To Do

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

You can find a copy of Yarn Spinner's license on GitHub. It's also included in the packaged versions of Yarn Spinner (such as via the Unity Package Manager, and reproduced here:

The MIT License (MIT)

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

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

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

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

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

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

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

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

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

What We'd Appreciate You Doing

In addition to including a copy of the Yarn Spinner's MIT license in your game, we'd very much appreciate it if you include Yarn Spinner in your game's credits, such as the initial splash screen, or in your end-game credits, or somewhere else of your choosing. Yarn Spinner is freely released, under a permissive open source license, and we appreciate you telling people that Yarn Spinner helped make your game.

If you credit Yarn Spinner, you can use the logo, which are available below, a text credit, or both. If you use a text credit, we suggest the following:

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

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

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

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

When using the Yarn Spinner name and logo, please do your best adhere to the following general guidelines:

1. The Yarn Spinner trademark can only be part of a product name (e.g. "Big Talk for Yarn Spinner") if it's a true reflection (i.e. the product works with Yarn Spinner).

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

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

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

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

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

Yarn Spinner logos

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

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

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