Yarn Spinner Scripts are built up out of nodes. Nodes are where you put your dialogue. You can have as many nodes as you want in a file.

title: Start
---
Narrator: Hi, I'm the narrator for the documentation!
===

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.

Nodes are used to separate out parts of the story, and make it easier to manage longer stories and branching.

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.

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.

The body of a node (that is, the content between the node start marker --- and the node end marker ===) is made up of three different kinds of content: lines, commands, and options.

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 Spinner script snippet from Night in the Woods:

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

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

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

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

Nodes can also have a color: and a group: in their header, which specifies what colour the bar at the top a node is shown in, and the group they're gathered in, in the Graph View of the :

You can also set nodes to be Sticky Notes by adding style: note to the node header. This will render the nodes differently in the Graph View of the . The color: of the node will be respected too, if one is set, otherwise the Sticky Note will default to yellow:

You can learn more about in the section.

If you're here, you've worked through the , and setup the , and you're ready to dive into the details of writing dialogue with Yarn Spinner.

This section of the documentation will take you through the scripting fundamentals:

• combining Nodes, Lines, Options, and Jumps for simple interactive narratives

• using Detours, Variables, and Yarn Spinner's Flow Control features for more complex interactions

To give your dialogue more life and variety, you can also provide lines in a line group. When lines are in a line group, Yarn Spinner will choose one of them for you.

Line groups are collections of lines that begin with a => symbol:

In this example, the Captain will say "Navigator, fire the glitter torpedoes! That'll confuse the enemy ships!", and then Yarn Spinner will choose one of the subsequent lines to respond with.

You can attach conditions to lines in a line group, to ensure that they only run when it’s appropriate to do so. Conditions can be any true or false expression, and can also be combined with the once keyword to ensure that a line can only run once:

A line in a line group can also have additional lines belonging to it, which will run if the item is selected.

Smart variables in Yarn Spinner are a powerful way to improve your dialogue and narrative flows. Unlike regular variables that only change when explicitly set, smart variables recalculate their value every time they're accessed, based on the expression that defines them.

Why Use Smart Variables?

1. Code Readability: They make your dialogue scripts more readable by using meaningful names instead of complex conditions.

2. Centralised Logic: Define a condition once and use it throughout your game.

3. Maintenance: When game mechanics change, you only need to update the smart variable declaration, not every place it's used.

4. Abstraction: They hide complex game state checks behind simple, descriptive names.

Creating a smart variable in Yarn Spinner is straightforward: <<declare>> command followed by a variable name (with the $ prefix) and assign it an rather than a static value. The expression can use , or even reference other variables.

For example: <<declare $is_powerful = $strength > 50 && $magic_ability >= 20>>.

This smart variable will automatically update whenever the values of $strength or $magic_ability change, making your dialogue able to dynamically respond to the player's stats without additional code.

Smart variables shine when you have conditions that you check frequently or that combine multiple factors. They're especially useful for:

• Tracking complex character states

• Monitoring game world conditions

• Representing player achievements or quest status

• Creating dynamic dialogue that responds to multiple game systems

By using smart variables, you make your dialogue scripts more intuitive and maintainable while keeping your game logic organised.

In Yarn Spinner, enums let you create variables whose value is constrained to a pre-defined list of possibilities.

To define an enum you must provide a name, and some cases for it. Here's a new enum called Food with the cases Apple, Orange, and Pear:

<<enum Food>>
  <<case Apple>>
  <<case Orange>>
  <<case Pear>>
<<endenum>>

Once you've created an enum, you can use it just like any other variable:

// Declare a new variable with the default value Food.Apple
<<declare $favouriteFood = Food.Apple>>

// You can set $favouriteFood to the 'apple', 'orange' or 'pear'
// cases, but nothing else!
<<set $favouriteFood to Food.Orange>>

// You can use enums in if statements, like any other type of value:
<<if $favouriteFood == Food.Apple>>
  I love apples!
<<endif>>

// You can even skip the name of the enum if Yarn Spinner can 
// figure it out from context!
<<set $favouriteFood = .Pear>>

Sometimes it's useful to create lines of dialogue that can only ever be displayed once.

In Yarn Spinner Scripts, you can use a once statement to denote content that can only be run one single time. When the script reaches a once statement, it checks to see if it’s run before. If it has, it skips over it! Magic.

There are two main ways you can use a once statement, which we'll explore below.

You can wrap some lines in <<once>> and <<endonce>>:

<<once>>
  // The guard will introduce herself to the player only once. 
  Guard: Hail, traveller! Well met.
  Guard: I am Alys, the guard!
<<endonce>>

You can also use an <<else>> clause within the <<once>> statement, which will be run if the relevant <<once>> content has already been seen:

You can also add an if to the once to run content a single time, but only when a certain condition is true. In all other cases, it will be skipped (or the else content will be run, if there is any):

If you add once (or once if) to a line, that line will only appear once, and will be skipped over every other time it’s encountered:

Similarly, if you add it to an option, that option will only be selectable once, and will be marked as unavailable after it’s been selected.

once statements are really useful when you want to show long, detailed content the first time it’s encountered, but you don’t want to show it every time. This means that players don’t need to mash the ‘skip line’ button over and over when they realise that they’re starting to see a long run of lines they’ve already seen:

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.

You can create your own commands, so that your scripts can send directions to your game. For more information on how to create them in Unity games, see , in the Yarn Spinner for Unity section of the documentation, and equivalents for other engines.

The <<jump>> command lets you move the dialogue between nodes. It is used by writing << then the word jump, a space, and then the full title of the node you want to jump the narrative to, then another >>.

To jump to a node with the title Rescue_the_Kitten , for example, you would write the line <<jump Rescue_the_Kitten>>.

Jump commands should always be placed on their own line, indented as appropriate.

For example, consider the following conversation, which could be structured inside one node, using nested options, or split over several nodes using options and jump commands. The before version is inside a single node, and works fine, but the after version is structured across multiple nodes, and is a lot easier to make sense of.

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

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

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

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

You call a function inside an expression. For example:

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

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

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

format_invariant returns a string representation of n, formatted using the invariant culture. This is useful for embedding numbers in commands, where the command expects the number to be formatted using the invariant culture. For example, <<give_gold {$gold}>>, which might end up as give_gold 4,51 in German, but give_gold 4.51 in English, can now be <<give_gold {format_invariant($gold)}>>, which will always be give_gold 4.51.

random returns a random number between 0 and 1 each time you call it.

random_range returns a random number between a and b, inclusive.

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.

min compares a and b, and returns the smaller of the two.

max compares a and b, and returns the larger of the two.

round rounds n to the nearest integer.

round_places rounds n to the nearest number with places decimal points.

floor rounds n down to the nearest integer, towards negative infinity.

ceil rounds n up to the nearest integer, towards positive infinity.

inc rounds n up to the nearest integer. If n is already an integer, inc returns n+1.

dec rounds n down to the nearest integer. If n is already an integer, dec returns n-1.

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 rounds n down to the nearest integer, towards zero.

You can create your own commands, so that your scripts can send directions to your game. For more information on how to create them in Unity games, see , in the Yarn Spinner for Unity section of the documentation, and equivalents for other engines.

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 lines prefixed with a ->. You write as many options as you'd like the player to see, and the player chooses one of them. The content of the option is like any other line of dialogue.

For example, consider the following code:

In this example, the line Navigator: We're arriving before we left. We've become our own rescue mission. will run.

The player will then be given the choice for the Captain to say either Let's alter our trajectory and break this temporal loop!, or We must complete the cycle. Our past selves depend on it.

In addition to using the to move between nodes, you can also use a detour command.

A detour command looks very similar to jump: it takes a single parameter with the title of the node you want to move to, but unlike the jump command the detour command will return to the node that called it afterwards.

The detour command works much like the jump command, except it will return to the node it detoured from after that node is done. Here’s an example of it in action:

If the player replies No? to the guard’s question, Yarn Spinner will detour to the node titled Guard_Backstory and run its contents.

When the end of the Guard_Backstory

So far, you've learned how to use Nodes and Lines, Options, the Jump Command, the Detour Command, and Variables to write Yarn Spinner Scripts.

Because it's actually a full programming language of its own, Yarn Spinner also supports flow control.

Flow control takes several forms, including if statements, and conditional options.

if statements

In addition to storing information, variables are useful for controlling what's lines of dialogue are presented to the player. To do this, you can 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 Yarn Spinner Script:

This script will:

• set a variable, $gold_amount, to 5;

• show the line Player: I'd like to buy a pie!

• use an if statement to see if $gold_amount is less than 10, and if that is the case, which it will be in this example, show the line Baker: Well, you can't afford one!

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

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

An else statement doesn't have an expression, and runs if the if and any elseif don't run.

For example, consider the following Yarn Spinner Script:

This script will:

• set a variable, $gold_amount, to 5;

• show the line Player: I'd like to buy a pie!

• use an if statement to see if $gold_amount is less than 10, and if that is the case, show the line Baker: Well, you can't afford one!

You can have as many elseif statements as you want inside an if statement block, and you can use whatever you want inside, for example:

In this example:

• there are two variables, $gold_amount for tracking the player's currency, and $reputation for their reputation in town

• an if statement first checks if their $gold_amount is greater than or equal to 5 and whether their reputation is greater than or equal to 8, if both of these are true, then the line

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

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

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

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.

If every option in a group is marked as unavailable, the game is allowed to tell Yarn Spinner that no option was selected. When this happens, Yarn Spinner will skip the options group, and run the next piece of content after the options.

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

Yarn Spinner Script 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 store information. Variables can store one of three types of information: numbers, strings, and booleans.

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

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

To declare a variable, you use the