Syntax Quick Reference
This is a quick reference guide for the various syntax you can write in your Yarn files. It is not intended to be a tutorial - see here for that! This document is instead a helpful reference if you're wondering how a line of Yarn code needs to be structured to work.
Yarn is a programming language designed for dialogue. This means it has to follow some rules, so a computer can make sense of it.
Yarn files are broken up into nodes. Each node has multiple different statements that make it up. In general, Yarn Spinner treats each new line in the Yarn file as a separate element. it needs to work out what that may be.
Everything in Yarn is a node, and all your dialogue is contained within a node. Your Yarn files might contain multiple nodes or only a single node, but all Yarn has to be part of a node. All nodes have the same basic structure:
header --- body ===
The header is separated from the body by
- symbols on a line by themselves).
The node is terminated by
= symbols on a line by themselves).
If you are using a visual editor, these nodes make up the little boxes you see on the canvas.
The header contains metadata for the node, and can have as many pieces of node metadata as you wish. Metadata is created as key-value pairs. Each metadata piece has the same layout:
Every metadata piece has to go one a line by itself.
An example of this:
myKey:myValue has a key of
myKey and a value of
All nodes must have a
This will look something like
title:nodename, and identifies the name of the particular node.
The name of the node, in this case
nodename, needs to be unique across the entire project, and can be any combination of upper or lower case letters and numbers. Node titles can't have spaces.
The value of this is case sensitive, so
nodename is not the same as
Tags use the
tags key. You can put whatever information you like in the
title metadata, the values don't have to be unique.
The body, which are the parts of the node in-between the
=== lines, are where the bulk of your time will be spent and is where all of your dialogue will go.
The majority of your Yarn files will normally be dialogue - lines spoken by your characters in the game. Each line of dialogue is treated as a new dialogue statement by Yarn Spinner. Almost any text can go inside your dialogue.
Most lines of dialogue are written like the following:
Player: Hey, Sally. Sally: Oh! Hi. Sally: You snuck up on me.
In this case, we have the characters names preceding the text we want them to say. This is optional, and you can just have the dialogue if you prefer:
Hey, Sally. Oh! Hi. You snuck up on me.
If you don't include character names, your game will need some other way of working out which line is for which character, and we leave that up to you.
Options are how you can move between different nodes.
[[Text to show to the user|NodeName]]
Options are broken up into two parts seperated by a vertical bar symbol (
The first part is any text that is to be shown to the user, and the second part after the bar is the name of the node.
The node name must be the name of another node somewhere else in your Yarn files, or else the program will not work.
After the player selects an option the node linked, in this case
NodeName, will be loaded and the story will continue from there.
A jump tells Yarn Spinner to start running a different node. They're not shown to the player.
When Yarn Spinner encounters this line, it will immediately start running the contents of the
Shortcut options let you create simple branching dialogue without needing to create new nodes.
Each shortcut starts with the
-> arrow and then the line of text that should be presented to the player.
Where should we go next? -> North -> South -> East -> West
This would show the line
Where should we go next? and then the options of
Shortcuts allow you add additional statements below the shortcut to run additional lines, and in many cases is used for setting or updating variables. The new statements have to go below the shortcut option they are a part of and need to be indented relative to the shortcut.
-> North It is cold to the north. -> South You've heard that the weather to the south is sunny. -> East You're not sure if the rumours of bandits to the east are true. -> West You continue your journey.
Different lines will be shown to the player depending on what options they select:
- In the above example if the player selected the
Northoption the dialogue line
It is cold to the northwould be shown after and then
You continue your journey.
- If they select
East, they'll see different lines before
You continue your journey
- If they select
West, they'll only see
You continue your journey.
The indentation must be kept consistent, or else Yarn Spinner won't be able to work out your intent.
Shortcuts can also be limited to only be presented if needed.
You do this by adding an
if statement to the end of the shortcut.
-> Locked Trapdoor <<if $hasKey is true>> -> North -> South -> East -> West
In the above example the shortcut
Locked Trapdoor will only appear as an option your players can pick if the variable
false only the four directions will appear.
You can store information inside variables.
Variable names are any combination of letters and numbers preceded by the
Variable names are case sensitive, so
$varname are two different variables as far as Yarn Spinner is concerned.
Variables are global in scope, so they exist across all nodes across all files. This means you can declare a variable in one file and then later use that variable in another file.
Variables can hold numbers, text,
You can set and update values inside of variables using the
<<set $var to 1>>
set operation takes the form of the command opening symbol
<<, followed immediately by the
set keyword, then the variable,
$var in our case, then the
to keyword, and finally the value you want.
You can also use the
= in place of the
to keyword if you wish.
Numbers are always decimals (technically, floating point) regardless of what values you give them.
This means if you give a variable the value of
1 when you get it back out from Yarn Spinner it will be
Text inside variables can be anything you want but must be contained with quotation marks.
This means that while
<<set $var to "hello">> is valid,
<<set $var to hello>> is not valid.
Variables can be set to be true or false using the keywords
These are case sensitive, so
<<set $var to true>> will work,
<<set $var to True>> will not work.
Conditionals are how you can create different branching dialogue and events based on logical statements.
All conditionals take the same basic structure, an
if statement, then zero or more
elseif statements, then zero or one
else statements, and finally the
Yarn Spinner will work its way down the conditional until it meets a piece of it it can run and presents the statements for that piece.
<<if $money > 1>> I would like a horse please. <<set $money to $money - 2>> <<set $hasHorse to true>> <<elseif $money eq 1 >> Just a drink thanks. <<set $money to $money - 1>> <<else>> Drat, I can't afford anything. <<endif>>
Take the above example, if
$money happens to be
1 then the line
Just a drink thanks. will be shown, but if
5 then the line
I would like a horse please. would be shown.
It is recommended to indent lines inside the
if but not required.
if statement opens a conditional and is comprised of the
<< command opening keyword followed immediately by the
if keyword, then goes an expression that controls the
if and finally the command close keyword
Any lines that go between the
if and the next part of the conditional, so either an
else, or an
endif, is shown if the expression is ultimately true.
elseif is an optional part of the conditional and works similar to the
if but instead uses the
elseif is identical to its
if counterpart in structure and you can have as many
elseif's as you want, including none.
<<elseif $money eq 1>>
else is the fallback of the conditional and is run only if the
if and all its
elseif's evaluate to false.
It is optional.
<<endif>> finishes the conditional statement and is required.
It is needed so Yarn Spinner knows when the conditional has concluded.
An expression is a mathematical or logical operation and work and looks like a line of maths. For the expression to be useful in the conditional it needs to eventually evaluate to true or false. If the expression results in true it will be the part of the conditional that gets run.
All expressions follow the same pattern of a subexpression followed by an operator and then another subexpression. The subexpressions can further broken up into other expression if needed:
<<if ($counter + 1) >= ($max - 2)>>
Yarn Spinner supports the following logical operators and most have multiple ways being written:
- Greater than:
- Less than:
- Less than or equal to:
- Greater than or equal to:
- Boolean OR:
- Boolean XOR:
- Boolean Negation:
- Boolean AND:
- Truncating Remainder Division:
(to open the brackets and
)to close them.
Order of operations
Yarn Spinner follows a fairly standard order of operations, and falling back to using left to right when operators are of equivalent priority. The order of operations is as follows:
- Boolean Negation
- Multiplication, Division, and Truncating Remainder Division
- Addition, Subtraction
- Less than or equals, Greater than or equals, Less than, Greater than
- Equality, Inequality
- Boolean AND, Boolean OR, Boolean XOR
Commands are a way of Yarn Spinner communicating back to the game that events have happened that need to be handled. These are often used to trigger achievements and to move characters and cameras around to where thye need to be.
Commands start by having the command opening symbol
<< then any text you want sent over to the game, and finish with the command close symbol
As an example:
<<move camera left>> <<unlockAchievement beganAdventure>>
Commands by themselves do nothing, you need to handle these messages yourself.
Localisation tags are a way of marking lines of dialogue to the localisation system.
If you aren't localising your game you don't need them and will not encounter them.
Each tag starts with a
# symbol and then have a
line keyword and an autogenerated value.
The tags always go on the end of the line and should never be edited or created manually. You will find localisation tags at the end of dialogue lines, shortcuts, and options.
Player: Hey. #line:a8e70c Sally: Oh! Hi. #line:2dc39b [[See you later.|Sally.Exit]] #line:0facf7