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.

The Basics

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.

Nodes

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 --- (three - symbols on a line by themselves). The node is terminated by === (three = 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:

key:value

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

Required headers

All nodes must have a title and tags header.

Title

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

Tags

Tags use the tags key. You can put whatever information you like in the tags header. Unlike the title metadata, the values don't have to be unique.

Body

The body, which are the parts of the node in-between the --- and === lines, are where the bulk of your time will be spent and is where all of your dialogue will go.

Dialogue

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

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.

Jumps

A jump tells Yarn Spinner to start running a different node. They're not shown to the player.

[[NodeName]]

When Yarn Spinner encounters this line, it will immediately start running the contents of the NodeName node.

Shortcut Options

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 North, South, East, West.

Shortcut scope

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:

The indentation must be kept consistent, or else Yarn Spinner won't be able to work out your intent.

Shortcut conditionals

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 $hasKey is true. If $hasKey is false only the four directions will appear.

Variables

You can store information inside variables.

Variable names are any combination of letters and numbers preceded by the $ symbol. Variable names are case sensitive, so $varName and $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.

Values

Variables can hold numbers, text, true and false, or null.

Setting values

You can set and update values inside of variables using the set operation:

<<set $var to 1>>

The 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

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

Text

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.

True and False

Variables can be set to be true or false using the keywords true or TRUE, and false and FALSE. These are case sensitive, so <<set $var to true>> will work, <<set $var to True>> will not work.

Conditionals

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

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 $money was 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, elseif, else and endif

The 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 elseif, an else, or an endif, is shown if the expression is ultimately true.

elseif

An elseif is an optional part of the conditional and works similar to the if but instead uses the elseif keyword. Each 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

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

<<else>>

endif

The <<endif>> finishes the conditional statement and is required. It is needed so Yarn Spinner knows when the conditional has concluded.

Expression

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

Logical operators

Yarn Spinner supports the following logical operators and most have multiple ways being written:

Maths operators

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:

  1. Brackets
  2. Boolean Negation
  3. Multiplication, Division, and Truncating Remainder Division
  4. Addition, Subtraction
  5. Less than or equals, Greater than or equals, Less than, Greater than
  6. Equality, Inequality
  7. Boolean AND, Boolean OR, Boolean XOR

Commands

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

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.

#line:a8e70c

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