2.2 (Current)
Writing Your Dialogue
Working With Unity
Unity Sample Projects
API Documentation
Nodes, Lines, and Options
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.
Node titles must start with a letter, and can contain letters, numbers and underscores.
So FirstNode, First_Node and Node1 valid, but First Node and 1stNode are not.
Node names cannot contain a
. (period).Node names were able to contain a period in Yarn Spinner 1, and if your Yarn Spinner 1 .yarn scripts have periods in the node names, then the upgrader script will translate them (and all jumps and options related) to use a _ (underscore) instead.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.
If you're using a graphical editor to write Yarn scripts, like Yarn Editor, it will handle this for you, and you can skip this section.
The plain-text version of a Yarn node looks like this:
1
title: Node_Title
2
---
3
Here are some lines!
4
Wow!
5
===
Copied!
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.Node headers can contain any number of lines with the structure
key: value. This can be used to store additional information, such as the location the conversation is taking place.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:
1
Mae: Well, this is great.
2
Mae: I mean I didn't expect a party or anything
3
Mae: but I figured *someone* would be here.
4
Mae: ...
5
Mae: Welcome home, Mae.
Copied!
When this code is run in the game, it looks like this:
Lines of dialogue running in Night in the Woods.
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:
1
This is a line of dialogue, without a character name.
2
Speaker: This is another line of dialogue said by a character called "Speaker".
Copied!
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:
1
Companion: Hi there! What do you feel like doing today?
2
3
-> Player: I want to go swimming.
4
-> Player: I'd prefer to go hiking.
Copied!
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.
1
Companion: Hi there! What do you feel like doing today?
2
3
-> Player: I want to go swimming.
4
Companion: Okay, let's go swimming.
5
-> Player: I'd prefer to go hiking.
6
Companion: Cool, we'll go hiking then.
7
8
Player: Sounds good!
Copied!
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.
1
Companion: Hi there! What do you feel like doing today?
2
3
-> Player: I want to go swimming.
4
Companion: Okay, let's go swimming.
5
Companion: Where do you want to swim?
6
-> Player: The lake!
7
Companion: Nice! It's a great day for it.
8
-> Player: The swimming pool!
9
Companion: Oh, awesome! I heard they installed a new slide.
10
-> Player: I'd prefer to go hiking.
11
Companion: Cool, we'll go hiking then.
12
13
Player: Sounds good!
Copied!
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:Before
After
1
title: Start
2
---
3
Companion: Hi there! What do you feel like doing today?
4
5
-> Player: I want to go swimming.
6
Companion: Okay, let's go swimming.
7
Companion: Where do you want to swim?
8
-> Player: The lake!
9
Companion: Nice! It's a great day for it.
10
-> Player: The swimming pool!
11
Companion: Oh, awesome! I heard they installed a new slide.
12
-> Player: I'd prefer to go hiking.
13
Companion: Cool, we'll go hiking then.
14
15
Player: Sounds good!
16
===
Copied!
1
title: Start
2
---
3
Companion: Hi there! What do you feel like doing today?
4
5
-> Player: I want to go swimming.
6
Companion: Okay, let's go swimming.
7
<<jump Swimming>>
8
-> Player: I'd prefer to go hiking.
9
Companion: Cool, we'll go hiking then.
10
<<jump Hiking>>
11
===
12
title: Swimming
13
---
14
Companion: Where do you want to swim?
15
-> Player: The lake!
16
Companion: Nice! It's a great day for it.
17
-> Player: The swimming pool!
18
Companion: Oh, awesome! I heard they installed a new slide.
19
20
<<jump Done>>
21
===
22
title: Hiking
23
---
24
Companion: Have you got your hiking boots ready?
25
-> Player: Yes.
26
Companion: Great, let's go!
27
-> Player: No.
28
Companion: We can swing by your place and pick them up!
29
30
<<jump Done>>
31
===
32
title: Done
33
---
34
Player: Sounds good!
35
===
Copied!
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.
Last modified 5mo ago
Export as PDF
Copy link
Edit on GitHub