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

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.

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

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

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

Welcome to Yarn Spinner 2.0!

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 a dialogue system that lets you write interactive conversations in a simple, screenplay-like format, which can be loaded into your game and run.

When a conversation is running, Yarn Spinner sends your game lines of dialogue to show, options to let the player choose from, and commands to make things happen in your scene.

Yarn Spinner has been used in a number of critically acclaimed games, including , , , and many more.

It's free to download and use for free and commercial games, and is open source under the terms of the .

Yarn Spinner 2.0 is our latest release!

Yarn Spinner is made up of two things:

1. Yarn files that contain the script for your game, and;

2. The Yarn Spinner framework for your chosen game engine or method of delivery.

To use Yarn Spinner 2.0, you will need:

1. An editor to write and edit .yarn scripts with. We recommend using the official Yarn Spinner Visual Studio Code extension, together with Visual Studio Code.
2. A copy of Yarn Spinner for your game engine of choice. Currently, Yarn Spinner supports Unity, so you'll need Yarn Spinner Unity.
3. A .yarn script (or a few of them). These will be the narrative, or bits of narrative, that Yarn Spinner uses to display and deliver your dialogue.

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

1. Launch Visual Studio Code.

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

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

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

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

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

Variables

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

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

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

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.

if statements

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

An if statement allows you to control whether a collection of content is shown or not. When you write an if statement, you provide an expression, which is checked; if that expression evaluates to a "true" value, then all of the content in between the <<if>> and <<endif>> statements are run.

For example, consider the following code:

<<set $gold_amount to 5>>

Player: I'd like to buy a pie!

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

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

elseif and else

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

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

An else statement doesn't have an expression, and runs

For example:

Player: I'd like to buy a pie!

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

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

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

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

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

Conditional Options

When presenting options to the player, you may want to make some options not available. You can do this by adding a condition to the option.

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

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

Guard: You're not allowed in!

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

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

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

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

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

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

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

Built-in Commands

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

wait

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

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

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

stop

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

// Leave the dialogue now
<<stop>>

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

Making Your Own Commands

You can create your own commands, so that your scripts can . For more information on how to create them in Unity games, see Creating Commands and Functions.

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

To upgrade your scripts:

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

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

$ ysc upgrade myOldYarnFile.yarn

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

ysc upgrade myOldYarnFile.yarn myOtherOldYarnFile.yarn

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

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

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)

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

Custom Functions

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

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

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

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 the instructions in the Unity manual.

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

3. Add the Dialogue System prefab to the scene:

   1. In the Project pane, scroll down to the Yarn Spinner folder. You'll find it in the Packages section.

   2. Inside the Yarn Spinner folder, open the Prefabs folder, and locate the Dialogue System prefab.

   3. Drag the Dialogue System into your scene.

4. Create a new Yarn script, 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.

title: Start
---
Wow!
My first ever Yarn script in Unity!

-> Gosh!
-> Incredible!
-> I'm amazed!

Anyway, time to get writing!
===

1. Save the file and return to Unity.

2. Create a new Yarn Project that uses this script, by selecting the HelloYarn file, and clicking the Create New Yarn Project button in the Inspector. This will create a new Yarn Project called Project.

3. Attach the Yarn Project to the Dialogue Runner, by selecting the Dialogue Runner in the Hierarchy, and dragging the Project into the Yarn Project field.

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

There are two ways to install Yarn Spinner for Unity: via the Package Manager, and via a .unitypackage file.

Install via the Unity Package Manager (recommended)

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

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

Setting Up the OpenUPM Registry in Your Project

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

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

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

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

1. In the Name field, type OpenUPM.

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

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

4. Click Save.

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

You can now install Yarn Spinner itself.

Installing the Yarn Spinner package

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

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

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

Yarn Spinner will download and install into your project.

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

Install from GitHub

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

To install Yarn Spinner from GitHub, follow these instructions.

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

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

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

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

Install as a file

If you don't want to install Yarn Spinner as a package, you can download it as a .unitypackage file, and extract it into your project.

To download and install the file, follow these steps:

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

2. Locate Text Mesh Pro in the list, and select it.

3. Click the Install button to install Text Mesh Pro. This package is required for Yarn Spinner to work.

5. Download the .unitypackage for that release.

1. Open the .unitypackage. Unity will ask which files you want to add. In almost every case, you'll want to import all files.

1. Click Import.

Next Steps

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

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

• Yarn Scripts are files that contain your written dialogue.

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

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.

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.

This new Yarn Project will be empty, and won't contain any references to other Yarn scripts yet.

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.

To add Yarn scripts to a Yarn Project, follow these steps:

• Select the Yarn Project in the Project Pane.

• In the Inspector, open the Source Scripts property at the top of the pane.

• Drag the Yarn script you want to add into the Source Scripts list.

• Click Apply at the bottom of the pane.

Creating a Project from a Script

As an alternative to creating an empty project and adding scripts to it, 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 be set up to 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.

This information comes from the following locations:

• All variables that have been declared in a Yarn script with a declare statement

• All variables that have been manually added to this Yarn project

• All variables that are used, but don't have a declare statement

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

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

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

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

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

• The contents of your dialogue are delivered to your .

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

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

Inspector

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

This section discusses the pre-built Dialogue Views:

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

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

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

You can control how the player can decide to proceed to the next line.

You can set up a Button, or any other Unity UI control, to call the OnContinueClicked method on this line.

You can also make the Line View continue to the next line when the user performs some input:

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

Inspector

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

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

Inspector

An Option View is an object that the Options List View uses when presenting options. When the Dialogue Runner 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

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

Inspector

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

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

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

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

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

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

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

Inspector

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

Audio Line Provider will automatically use Addressable Assets, if the Addressables package is installed in your Unity project and

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

Defining Commands

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

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

The YarnCommand attribute

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

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

If the method is static, you call it directly. For example:

// Note that we aren't subclassing MonoBehaviour here; 
// static commands can be on any class.
public class FadeCamera {

    [YarnCommand("fade_camera")]
    public static void FadeCamera() {
        Debug.Log("Fading the camera!");
    }
}

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

<<fade_camera>>
// will print "Fading the camera!" in the console

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

For example:

public class CharacterMovement : MonoBehaviour {

    [YarnCommand("jump")]
    public void Jump() {
        Debug.Log($"{name} is jumping!");
    }
}

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

<<jump MyCharacter>>
// will print "MyCharacter is jumping!" in the console

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

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

Method parameters may be optional.

For example, consider this method:

[YarnCommand("walk")]
public void Walk(GameObject destination, bool dancing = false) {
    var position = destination.transform.position;

    // If the second parameter is used in the command,
    // and it's "true" or "dancing", use a dance 
    // animation
    if (dancing) {
        // set animation to a dance
    } else {
        // set animation to a regular walk
    }

    // walk the character to 'position'
}

This command could be called like this:

<<walk MyCharacter StageLeft>> // walk to the position of the object named 'StageLeft'

<<walk MyOtherCharacter StageRight dancing>> // walk to StageRight, while dancing

Adding commands through code

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

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

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

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

public class CustomCommands : MonoBehaviour {    

    // Drag and drop your Dialogue Runner into this variable.
    public DialogueRunner dialogueRunner;

    public void Awake() {

        // Create a new command called 'camera_look', which looks at a target. 
        // Note how we're listing 'GameObject' as the parameter type.
        dialogueRunner.AddCommandHandler<GameObject>(
            "camera_look",     // the name of the command
            CameraLookAtTarget // the method to run
        );
    }

    // The method that gets called when '<<camera_look>>' is run.
    private void CameraLookAtTarget(GameObject target) {
        if (target == null) {
            debug.Log("Can't find the target!");
        }
        // Make the main camera look at this target
        Camera.main.transform.LookAt(target.transform);
    }    
}

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

You can then call this method like this:

<<camera_look LeftMarker>> // make the camera look at an object named LeftMarker

Making Commands Using Coroutines

Coroutines can be commands. If you register a command, either using the YarnCommand attribute, or the AddCommandHandler method, and the method you're using it with is a coroutine (that is, it returns IEnumerator, and yields objects like WaitForSeconds), Yarn Spinner will pause execution of your dialogue when the command is called.

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

public class CustomWaitCommand : MonoBehaviour {    

    [YarnCommand("custom_wait"]
    IEnumerator CustomWait() {

        // Wait for 1 second
        yield return new WaitForSeconds(1.0);
        
        // Because this method returns IEnumerator, t's a coroutine. 
        // Yarn Spinner will wait until onComplete is called.
    }    
}

This new method, once registered with a Dialogue Runner, can be called like this:

<<custom_wait>> // Waits for one second, then continues running

Defining Functions

Functions are units of code that Yarn scripts can call to receive a value.

In additon to the built-in functions that come with Yarn Spinner, you can create your own.

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

1. Functions must return a value.

2. Functions are required to be static.

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

public class AdderFunction {
   [YarnFunction("add_numbers")]
   public static int AddNumbers(int first, int second)
   {
       return first + second;
   }
}

When this code has been added to your project, you can use it like this:

One plus one is {add_numbers(1, 1)}

Yarn functions can return the following types of values:

• string

• int

• float

• bool

Commands, Functions and Assembly Definitions

Yarn Spinner searches your code for methods that have the YarnCommand and YarnFunction attributes when your game first starts up, as well as when a Dialogue Runner is told to run a Yarn Project.

If the Yarn Project's "Search All Assemblies" option is turned on, every assembly definition is searched; if it's turned off, only the assembly definitions specified in the "Assemblies To Search" option is searched. Code that is not in an assembly definition is always included.

By default, Yarn Spinner searches every assembly definition. If you have a large codebase, putting all of the code that contains commands and functions in an assembly definition can reduce the amount of time Yarn Spinner needs to take to find all of the commands and functions.

Goals

1. Display Yarn dialogue in a Unity scene

2. Allow a player to select between options to respond

3. Add some static visuals

Materials

• Yarn Spinner installed in Unity:

• Yarn Spinner set up in a text editor:

Instructions

Open a new Unity 3D project. Ensure Yarn Spinner has been added to the project in the Package Manager as per the .

If the sample empty scene is not visible, you'll need to open it. In the Project Window where project files are displayed, navigate to Assets > Scenes and select SampleScene.unity.

Creating a Runnable Script

Yarn Spinner for Unity comes with a pre-made UI layer and accompanying utility scripts to handle displaying lines and presenting options from Yarn files. In the Project Window again, navigate to Packages > Yarn Spinner > Prefabs and drag Dialogue System.prefab into the scene.

When the Dialogue System in the scene is selected, the Inspector will display the Yarn Project it is expecting line from. Here, a Yarn Project is a kind of linking file that groups Yarn script files together. To make one, navigate to a sensible place for the file to live (such as a new folder Assets > Dialogue) and right-click the Project Window pane to select Create > Yarn Spinner > Yarn Project.

Select the scene's Dialogue System again and drag the new Yarn Project into the labelled slot in the Inspector.

Now the Yarn Project needs one or more Yarn Scripts to get dialogue from. Just like with the Yarn Project, navigate to the desired file location and select Create > Yarn Spinner > Yarn Script. Then, with the Yarn Project selected, drag the newly created script into the Inspector slot labelled Source Scripts. Click Apply.

Filling Out Your Script

By default, a new Yarn Script begins with a single empty node with the name of the file. Open the file, rename the node to Start and put a single line of test dialogue. You may remove the tags field.

Returning to Unity, pressing the ▶️ button results in the test line being displayed in front of the empty scene world. Pressing Continue will make the UI disappear, as it has reached the end of the script.

Once you've got a basic story, pop back into Unity and check the basics:

• Lines display correctly

• Pressing Continue advances lines correctly

• Selecting different options have the expected outcomes

Draw the Rest of the Owl

For the shape example, let's add some "characters" to the scene. Use Menu > GameObject > 3D Object to add a Sphere, a Cube and a Plane to the scene. Scale up the Plane by adjusting the vaues in the Inspector to Scale = 10, 10, 10. To put the Sphere and Cube in front of the camera and make the Plane appear as a floor, they'll need to be moved. The following coordinates are about right, using the default location for the Main Camera:

Looking to the Game view, this should appear as two shapes on a floor with the dialogue UI in front.

All this white makes them difficult to distinguish though, so let's colour each Object. Create basic Materials for each by right-clicking the Project Window in the desired file location and select Create > Material three times. Change the colour of each Material to three distinct colours by modifying the Albedo value in the Inspector.

Add a Material to each Object by selecting the desired object and dragging the Material into the Materials > Element 0 under Mesh Renderer in the Inspector.

Result

A playable branching story game with simple static visuals.

An easy way to spice this up is to just add more dialogue with the same characters. Here is an example script that shows how a simple starter script made for testing can grow to a fuller conversation. And it doesn't stop there! Yarn Spinner is perfect for allowing growing projects to remain functional throughout.

Now, let's move onto an example where Yarn Spinner leverages the power of Unity to change things in the scene as well as running dialogue...

The Yarn Spinner project was started by Jon Manning, co-founder of Secret Lab.

Yarn Spinner is now maintained by Jon, together with freelance game developer Tim Nugent, Secret Lab colleague Paris Buttfield-Addison, and researcher and freelancer Mars Buttfield-Addison, together with a huge community of open source contributors. ❤️

You can support Yarn Spinner on Patreon.

Yarn Spinner Timeline

• v0.9 was the first public release on 9 October 2015

• v1.0 was released on 8 January 2020

• v2.0 was released on 20 December 2021

About Secret Lab

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

We’ve been enthusiastically building video games, apps, and technology to showcase culture, history, arts, and narrative experiences since 2008.

We’re the proud creators of Yarn Spinner, and are currently working on the BAFTA- and IGF-winning Night in the Woods.

You can hire us to build your video games, interactive experiences, fancy apps, or to add features to, or support your integration of Yarn Spinner.

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

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

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

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

Localisation Terminology

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

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

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

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

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

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

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

Localisation Workflow

In Yarn Spinner, the localisation workflow works like this:

1. Write your Yarn scripts. This original content is your 'base' localisation.

2. Add a line ID to each line of dialogue in your script.

3. Set up localisations in the Yarn Project for each of the languages you wish to support. (This includes your base language.)

4. For each localisation besides your base language:

   1. Export a strings file.

   2. Translate its contents into another language.

   3. Associate the strings file with the localisation.

5. If you have assets you want to use with your dialogue, associate the folder that contains those assets with the localisation they belong to, and set up a Line Provider that's able to use those assets (such as an Audio Line Provider.)

6. During gameplay, set your Line Provider's language to the player's preferred language, and it will fetch the appropriate content for the player to see.

In the following sections, we'll go through each of these steps.

Writing Yarn Scripts

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

The base language of a Yarn Script is controlled by the Yarn Project that it's a part of. You can change the language of your base localisation by changing the 'Base Language' setting on a Yarn Project.

Adding Line IDs

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

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

Gunther: I wanted orange! They gave me lemon-lime. #line:1a64a5

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

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

Set Up Localisations

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

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

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

Localisations have the following properties:

Creating a Translation

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

A strings file is a text-based spreadsheet, in comma-separated value form, that contains a translated version of your dialogue. Yarn Spinner can generate a strings file for you, based on the line IDs in the dialogue.

To create a strings file, select a Yarn Project, and click the Export Strings as CSV button. Unity will ask where you want to save the file.

A strings file has the following structure:

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

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

Adding Localised Assets

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

Line Providers are responsible for fetching the appropriate assets for a given line and language. For example, the Audio Line Provider fetches audio clips, and provides them to voice-over dialogue views.

Selecting a Language at Run-time

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

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

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

When writing Yarn scripts, variables come in handy for storing state and user preferences that can persist and impact story dialogue or choices later on. When using Yarn Spinner for Unity, variables from Yarn scripts can be accessed in C# code by using the provided InMemoryVariableStorage, which acts as a simple dictionary to store variable names with their current values.

This looks something like this:

<<set $testVariable = 1>>

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

This allows Yarn types String, Number and Boolean to be stored in memory, and then accessed by this wrapper class that converts them to the C# equivalents string, float and bool, ready for use in your code.

InMemoryVariableStorage is flexible and extensible, and has utilities for things such as initialising with default variables declared, or serialising to and from JSON. But what if you want to add very custom behaviour to how variables are stored? To keep values somewhere other than in memory, or add side effects to certain operations in a way that wouldn’t work by just extending this default variable storage? Well, you can define your own.

What makes a Variable Storage?

Like other parts of the Unity API for Yarn Spinner, Variable Storage is made possible with the use of abstract classes. Abstract classes in C# work a little bit like interfaces or protocols in other languages, in that they define a class that cannot be instantiated but can be used to make others. In this way, an abstract class is like a set of constraints for some hypothetical subclass you will define later: it can declare certain methods which your subclass must implement for it to work, and it can contain implementations or values of its own which act as defaults that you may or may not choose to override.

In Yarn Spinner for Unity, VariableStorageBehaviour is an abstract class that can be inherited from. It specifies the methods which Yarn Spinner may call at runtime, which are expected to be dealt with in your implementation:

Now, Yarn Spinner does not care how your custom VariableStorageBehaviour works beyond that. It simply assumes that you are doing something sensible, and that your subclass will provide the functionality it expects. Some of those expectations cannot be constrained in code, like the required method declarations can, so there is a level of trust here that you (as the implementer of this black box subclass which Yarn Spinner has never seen) will:

1. Actually store values somewhere. Your code will still compile if your SetValue() methods are empty or otherwise throw away the values they are given, but this will mean your TryGetValue() methods will never be able to work.

2. Actually get the right value for the given key. Your code will still compile if your TryGetValue() methods return random values from the aether, but this will make your use of these variables in your Yarn script effectively nonsensical. Likewise if you allow setting of multiple values with the same key.

3. Actually get rid of values when asked to. Your code will still compile if your Clear() method does nothing, but this means that Yarn script progress or state may never be reset correctly.

4. Actually check if a key already exists. Your code will still compile if your Contains() method always returns false, but this will lead to overwriting existing values the next time someone tries to SetValue() a seemingly unused key that already had a value.

So let’s assume you are not some chaos demon and you actually want to make a Variable Storage that works the way the Yarn Spinner runtime expects, so that you get variables that actually work. You need:

• A way to store values of the given types, each associated with a unique key.

• A way to get those values back, as the expected type.

• A way to get rid of all the previously stored values.

If you were some sort of psycho you could write a class whose SetValue() method printed out the given key and value on a piece of paper, Contains() and TryGetValue() methods that took a snapshot with a camera placed above the printer and read the values back, and a Clear() method that pushed the paper from the printer tray into a shredder. Yarn Spinner would not care, because it would still do those three things (though probably unreliably, and with some storage limitations).

Some more typical examples of things that gamemakers have wanted their variable storage to do are:

• Instead of storing variables in memory in a dictionary, store them on disk or in a database.

• Instead of just setting values in the Variable Storage when asked, also update some corresponding variables on the C# side or call a UnityEvent to notify other components that a value has changed.

• Instead of simply getting and setting values, run them via some sanitation or transformation, or even interface with an external API.

So let’s break down how you would go about implementing one of those more sensible ideas...

Let’s make a custom Variable Storage!

In this example, let’s replace the default Variable Storage implementation with one that stores values in a SQL database. The example code shown makes use of the sqlite-net library—an open source .Net API for SQL—for the creation of a database and tables, but uses vanilla SQL query strings in place of the convenience bindings which are specific to that library.

To begin, we need to make a custom class for our new Variable Storage, which should inherit from the VariableStorageBehavour abstract class.

using UnityEngine;
using Yarn.Unity;
using SQLite;

public class SQLVariableStorage : VariableStorageBehaviour {}

If you are following along, your IDE will probably throw a hissy fit at this point, because this empty class does not fulfil the requirements defined by the abstract superclass. To conform, we need at least the six methods listed earlier.

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

So let’s have a think about how each of these would need to work, given a backing of SQL. We need to be able to insert values into tables, check if a value exists in tables with the given key, return the corresponding value for a given key, and remove all entries from tables.

But first, before any values can be set, the database needs to already exist. Set up like this conventionally occurs in the Start() method:

void Start() {
        // pick a place on disk for the database to save to
        string path = Application.persistentDataPath + "/db.sqlite";
        // create a new database connection to speak to it
        db = new SQLiteConnection(path);
        // TODO: create the tables we need ??
        // ...
}

Next, to create the tables we need to store values in, we need to declare a class that represents a single entry. Its class name will becomes the table name by default, and its field names and types will become the column names and types. Because each column can only hold one type, we’ll need one table for each type.

These classes would look something like this:

public class YarnString {
	[PrimaryKey]
	public string key { get; set; }
	public string value { get; set; }
}
public class YarnFloat {
	[PrimaryKey]
	public string key { get; set; }
	public float value { get; set; }
}
public class YarnBool {
	[PrimaryKey]
	public string key { get; set; }
	public bool value { get; set; }
}

The column that will be used to reference or fetch values—and is thus required to be unique within that table—is specified by the [PrimaryKey] decorator.

Then, to create an empty table in the database, we can call the database connector’s CreateTable() method with the class we want to represent.

void Start() {
        // pick a place on disk for the database to save to
        string path = Application.persistentDataPath + "/db.sqlite";
        // create a new database connection to speak to it
        db = new SQLiteConnection(path);
        // create the tables we need
        db.CreateTable<YarnString>();
        db.CreateTable<YarnFloat>();
        db.CreateTable<YarnBool>();
}

Now we can begin filling out our empty method declarations. Beginning with the easiest, Clear() is just a matter of telling each table in the database to remove all its entries. The query for this is DELETE * FROM TableName, where the * means all entries. Executing a query on the database is as simple as calling Execute() on the database connector with a string parameter of the desired query.

public override void Clear() {
    db.Execute("DELETE * FROM YarnString;");
    db.Execute("DELETE * FROM YarnBool;");
    db.Execute("DELETE * FROM YarnFloat;");
}

Now to the fiddliest method, TryGetValue() is the method that needs to figure out whether a value exists for the given key and, if so, return it as the correct type. This requires a little bit of C# generics.

First we need to do some switching of which table we need to look for the value in:

public override bool TryGetValue<T>(string variableName, out T result) {
    if (typeof(T) == typeof(string)) {
        // TODO: search YarnString for variableName
    } else if (typeof(T) == typeof(bool)) {
        // TODO: search YarnBool for variableName
    } else if (typeof(T) == typeof(float)) {
        // TODO: search YarnFloat for variableName
    }
    result = default(T);
    return false;
}

Then, within each, we should look for that key within the corresponding table. To return only the value from any row that matches our variable name we specify Select ColumnName FROM TableName WHERE (conditions to match).

public override bool TryGetValue<T>(string variableName, out T result) {
    string query = "";
    List<object> results = null;
    // try to get a value from the given table, as a generic object
    if (typeof(T) == typeof(string)) {
        query = $"SELECT value FROM YarnString WHERE key = {variableName}";
    } // else if ...
    // (other cases go here)
    
    // if a result was found, convert it to type T and assign it
    results = db.Query<object>(query);
    if (results?.Count > 0) {
        result = (T)results[0];
        return true;
    }
    
    // otherwise TryGetValue has failed
    result = default(T);
    return false;
}

Next, before we can begin inserting values into tables, we first want to make sure a value doesn’t already exist for that key in another table. We can do this by creating a utility method that uses a lookup query to check if a value exists with that key in a specific table. This can take advantage of our TryGetValue() implementation:

private bool Exists(string variableName, System.Type type) {
    if (type == typeof(string)) {
        string stringResult;
        if (TryGetValue<string>(variableName, out stringResult)) {
            return (stringResult != null);
        }
    } else if (type == typeof(bool)) {
        string boolResult;
        if (TryGetValue<string>(variableName, out boolResult)) {
            return (boolResult != null);
        }
    } else if (type == typeof(float)) {
        string floatResult;
        if (TryGetValue<string>(variableName, out floatResult)) {
            return (floatResult != null);
        }
    }
    return false;
}

...which can then also be used as the basis for our Contains() method, by checking them all:

public override bool Contains(string variableName) {
    return Exists(variableName, typeof(string)) || 
        Exists(variableName, typeof(bool)) || 
        Exists(variableName, typeof(float));
}

This utility method then also comes in handy when defining the SetValue() methods, which would each look something like this:

public override void SetValue(string variableName, string stringValue) {
    // check it doesn't exist already in other table
    if (Exists(variableName, typeof(bool))) {
            throw new System.ArgumentException($"{variableName} is a bool.");
    // check if doesn't exist already in other other table
    } else if (Exists(variableName, typeof(float))) {
            throw new System.ArgumentException($"{variableName} is a float.");
    }
    // if not, insert or update row in this table to the given value
    string query = "INSERT OR REPLACE INTO YarnString (key, value)";
    query += $"VALUES ({variableName}, {stringValue})";
    db.Execute(query);
}

And lo! We should now have a fully functioning SQL-backed custom Variable Storage for Yarn Spinner. Simply replace the Variable Storage component on the DialogueRunner game object in your scene to put your custom implementation to work.

As far as Yarn Spinner is concerned, this should behave exactly as the provided InMemoryVariableStorage does at runtime, even though the entire storage model and behaviour has changed.

Using this simple method of overriding methods in the inbuilt VariableStorageBehaviour abstract class, you can make a custom Variable Storage backed by virtually anything to suit your needs!

Where to go to learn more

Check out the documentation on Variable Storage or ask the community in the Yarn Spinner Discord Server!

Goals

1. Display Yarn dialogue in a Unity scene

2. Allow a player to select between options to respond

3. Allow a player to select among available characters to speak to

4. Use Yarn Spinner to trigger a command that changes the interactability of characters

Materials

• Yarn Spinner installed in Unity

• Yarn Spinner set up in a text editor

• Starter Asset Package downloaded and unzipped

Instructions

Open a new Unity 3D project. Ensure Yarn Spinner has been added to the project in the Package Manager as per the Installation Instructions.

Drag the provided Asset Package into the Project Window where project files are displayed in Unity to import them into the project.

This package includes the following assets and functionality:

1. A simple, static environment called Graveyard which also contains four character models.

2. A C# script that provides simple functions for the character objects.

3. A Timeline that stores the hovering animation for the Ghost character.

4. Some Lights that turn on and off to indicate when a Grave character is speaking.

Creating a Runnable Script

Yarn Spinner for Unity comes with a pre-made UI layer and accompanying utility scripts to handle displaying lines and presenting options from Yarn files. In the Project Window again, navigate to Packages > Yarn Spinner > Prefabs and drag Dialogue System.prefab into the scene.

When the Dialogue System in the scene is selected, the Inspector will display the Yarn Project it is expecting line from. Here, a Yarn Project is a kind of linking file that groups Yarn script files together. To make one, navigate to a sensible place for the file to live (such as Assets > Dialogue) and right-click the Project Window pane to select Create > Yarn Spinner > Yarn Project.

Select the scene's Dialogue System again and drag the new Yarn Project into the labelled slot in the Inspector.

Now the Yarn Project needs one or more Yarn Scripts to get dialogue from. Just like with the Yarn Project, navigate to the desired file location and select Create > Yarn Spinner > Yarn Script. Then, with the Yarn Project selected, drag the newly created script into the Inspector slot labelled Source Scripts. Click Apply.

Filling Out Your Script

By default, a new Yarn Script begins with a single empty node with the name of the file. Open the file, rename the node to Start and put a single line of test dialogue. You may remove the tags field.

title: Start
---
This is a line of test dialogue.
===

Returning to Unity, pressing the ▶️ button results in the test line being displayed in front of the graveyard scene. Pressing Continue will make the UI disappear, as it has reached the end of the script.

It's time to plan a story. In the scene there are four characters—Ghost, LeftGrave (Louise), CenterGrave (Carol), and RightGrave (Ruby)—and the intent of this game is for the player to be able to interact with them in virtually any order to complete the objectives of the game. This game format typically accompanies stories where the player must piece together information from smaller tidbits given to them when they speak to different characters.

So, when the game begins, Ghost will present some mystery. Once a brief context-establishing conversation ends, the player will be free to select which character to speak to next. Speaking to each of the Grave characters will present a clue, provided the required prerequisite clues are known. At any time, the player can present their collated clues to Ghost. If their clues are complete, Ghost will tell them they solved the mystery and the game will end.

This short story provides a looping circuit through four paths, and results in the player reaching the ending after an undetermined number of conversations (though there is a hypothetical minimum, there is no maximum). A railroad diagram representation of the story would look as follows:

So it's time for the actual writing part. Here, I've opened my new Yarn Script in Visual Studio Code with the Yarn Spinner Extension installed as per the Installation Instructions. I've written a minimal script that follows the planned story, as a skeleton that can be expanded on later.

In this script, selecting the correct conversation option when speaking to each character will yield a new clue. However, the correct option is only available if the player has the required prerequisite clues. So no matter the order the player speaks to the graves, they must acquire clues in the order A then B then C.

You can find this example script below to copy. Or if you want to make you own version and need a refresher on how to represent it in Yarn, refer to the Syntax and File Structure guide.

title: Start
---
<<set $hasClueA to false>>
<<set $hasClueB to false>>
<<set $hasClueC to false>>
Ghost: Welcome to the graveyard! Unfortunately, you're just in time for an unsolved mystery...
Ghost: You'll have to speak to these three to figure out what happened!
===
title: LeftGraveLouise
---
Louise: What do you want to know?
-> Something that will get me no clues?
-> Something that will get me Clue A? <<if not $hasClueA>>
    <<set $hasClueA to true>>
-> Something relating to existing Clue A? <<if $hasClueA>>
-> Something relating to existing Clue B? <<if $hasClueB>>
-> Something relating to existing Clue C? <<if $hasClueC>>
Louise: ~additional dialogue~
Louise: Ok, bye!
===
title: CenterGraveCarol
---
Carol: What do you want to know?
-> Something that will get me no clues?
-> Something that will get me Clue B? <<if $hasClueA and not $hasClueB>>
    <<set $hasClueB to true>>
-> Something relating to existing Clue A? <<if $hasClueA>>
-> Something relating to existing Clue B? <<if $hasClueB>>
-> Something relating to existing Clue C? <<if $hasClueC>>
Carol: ~additional dialogue~
Carol: Ok, bye!
===
title: RightGraveRuby
---
Ruby: What do you want to know?
-> Something that will get me no clues?
-> Something that will get me Clue C? <<if $hasClueB and not $hasClueC>>
    <<set $hasClueC to true>>
-> Something relating to existing Clue A? <<if $hasClueA>>
-> Something relating to existing Clue B? <<if $hasClueB>>
-> Something relating to existing Clue C? <<if $hasClueC>>
Ruby: ~additional dialogue~
Ruby: Ok, bye!
===
title: Ghost
---
Ghost: Are you ready to tell me what happened?
-> Yes
    Ghost: Well, what do you know?
    -> I have no clues.
    -> I have clue A. <<if $hasClueA>>
    -> I have clues A and B. <<if $hasClueB>>
    -> I have clues A, B and C. <<if $hasClueC>>
        <<jump Ending>>
    Ghost: That doesn't sound right...
-> No
Ghost: Go on and speak to those three!
===
title: Ending
---
Ghost: You solved it!
===

Once you've got a basic story, pop back into Unity and check the basics:

• Lines display correctly

• Pressing Continue advances lines correctly

• Selecting different options have the expected outcomes

Making Players Interactable

In this game, the player should be able to select an NPC in the scene and have it trigger their repsective conversation. This requires a few things:

• Code to begin dialogue from a specific node when a character object is interacted with.

• Code to disable scene interaction when any character is already speaking.

• Code to disable character interaction when a specific character should not be interactable.

In Assets > Scripts there is a C# script that has code to do these things (see headers below), so we just need to connect it to the appropriate places. But first, let's step through what it does.

// this file is attached to every character in the scene and so will affect only
// the targeted character object when functions are called

// disable scene interaction, activate speaker indicator, and
// run dialogue from {conversationStartNode}
private void StartConversation();

// reverse StartConversation's changes: 
// re-enable scene interaction, deactivate indicator, etc.
private void EndConversation();

// make character not able to be clicked on
public void DisableConversation();

Add the YarnInteractable script to each character in the game: Ghost, LeftGrave, CenterGrave, and RightGrave. Make sure to set their respective conversationStartNode values in the Inspector to match what they are called in the Yarn script.

First up is the code for beginning a conversation. This requires running dialogue from a specific node when a character is interacted with. Running dialogue is a simple matter of telling the DialogueRunner to begin dialogue and passing the name of the node to begin from as a string.

// first we need a handle on the DialogueRunner, so we may as well get it when
// this object is first added to the scene
private DialogueRunner dialogueRunner;

public void Start() {
    dialogueRunner = FindObjectOfType<Yarn.Unity.DialogueRunner>();
}

// then we need a function to tell Yarn Spinner to start from {specifiedNodeName}
public string conversationStartNode;

private void StartConversation() {
    dialogueRunner.StartDialogue(conversationStartNode);
}

To run this when a character is interacted with, simple override the OnMouseDown() function that exists for every GameObject (which this class inherits from). Checking the IsDialogueRunning property of the DialogueRunner is a simple way to ignore interaction whenever starting dialogue would interrupt an existing conversation.

private bool interactable; // whether this character should be enabled right now
// (begins true, but may not always be true)

public void OnMouseDown() {
    // if this character is enabled and no conversation is already running
    if (interactable && !dialogueRunner.IsDialogueRunning) {
        // then run this character's conversation
        StartConversation();
    }
}

This handles beginning a conversation, but what if other changes are needed while a character is speaking? Well, having a function that is triggered when a conversation ends would allow properties to be set in StartConversation that can then be reversed once dialogue has ended.

To trigger a function when a conversation ends, a listener can be added to the DialogueRunner that will fire a specified function when a certain event occurs. The onDialogueComplete event happens whenever the runner reaches the end of its current conversation path.

// this would go in the Start() function, right after finding the DialogueRunner
// object, so that the listener begins before dialogue does the first time
dialogueRunner.onDialogueComplete.AddListener(EndConversation);

Next, let's define the function it will call. A key consideration here is that every object using this YarnInteractable script will be notified of dialogue completion every time it happens. Each one is registering a listener, and each will have its own EndConversation() function be called.

So to save some work, we can check whether this is the instance that should care about the event. This can be done just by setting a boolean when the conversation begins, that says this is the character that is currently speaking.

private bool isCurrentConversation;

private void StartConversation() {
    isCurrentConversation = true;
    // TODO *begin animation or turn on speaker indicator or whatever* HERE
    dialogueRunner.StartDialogue(conversationStartNode);
}

private void EndConversation() {
    if (isCurrentConversation) { 
        // TODO *stop animation or turn off indicator or whatever* HERE
        isCurrentConversation = false;
    }
}

Returning to Unity, press the ▶️ button and see that this now allows a new conversation to be triggered by interacting with any character after another has finished speaking.

At this point, this may seem done, but there is a critical issue here. Looking back at the earlier goals:

• Clicking on a character begins dialogue from their respective node.

• Clicking on a character while dialogue is already running does nothing.

• Clicking on a character when they should not be interactable does nothing.

Why that third thing? Well, because the current state of the game allows the player to:

1. Speak to the Ghost to begin the story.

2. Ask the Graves about the mystery.

3. Speak to the Ghost once they have collected the necessary clues.

4. Have Ghost tell them they ✨ solved the mystery ✨ and say goodbye.

5. Go back and still ask the Graves about the mystery that is already solved(?!)

So there needs to be a way to tell a specific character "no, you are done, don't speak to the player any more". This can be done with a simple Yarn Command.

In YarnInteractable.cs there is a simple function that sets a flag that the OnMouseDown() function checks when deciding whether to start a conversation. Turning this into a command simple requires adding the Yarn Command decorator above the function, with the string that will become the command keyword in any yarn scripts.

[YarnCommand("disable")]
public void DisableConversation() {
    interactable = false;
}

Back in the Yarn script, call disable once for each character when the story ends, to save the player from going back and having a confusion conversation about an already-solved mystery.

title: Ending
---
Ghost: You solved it!
<<disable Ghost>>
<<disable LeftGrave>>
<<disable CenterGrave>>
<<disable RightGrave>>
===