Beginner's Guide

If you're new to Yarn Spinner, this is the place to start.

ESC
↑↓ Navigate ↵ Open esc Close

Welcome to Yarn Spinner

This section of our documentation shows you a small Yarn Spinner Script one piece at a time. Each example on this page can be played on the page: press Run above the code to play it, and choose an option when one appears. You don’t need to install anything.

Beginner’s Guide to Yarn Spinner

Nodes and lines

In Yarn, everything you write is text and structured around nodes and lines.

In this guide, the first node to run is always called Start, so we’ll write that now.

In your own games or narratives, the first node can be named whatever you like.
Create a Start node with a line of dialogue

This is a Start node with a single line of dialogue. Press Run to play it. There isn’t much to play yet.

Yarn 
title: Start
---
Narrator: Hi, I'm the narrator for the documentation!
===
Line 1 This is called a header. This header is the title, and it’s always required in each node.
Line 2 This indicates the start of a node’s content.
Line 3 This is a character name. Character names in Yarn Spinner are optional. If they exist, they’re always at the beginning of a line, and consist of text, followed by a colon. Sometimes they’re used as a key, sometimes they’re the whole name.
Line 4 This indicates the end of a node.
A Start node with one line of dialogue.

This is a node. A node must always start with a header containing a single key and value pair to set the node’s title. The key is title and the value is Start . They are separated by a : . Node titles must start with a letter, and can only contain letters, numbers and underscores.

The header ends with a line containing only --- and the body of the node follows. The body is where the lines are kept.

There is a single line here: Narrator: Hi, I'm the narrator for the documentation! A line can contain whatever you want, and doesn’t have to begin with a character name.

Finally, the node ends with a line containing only ===.

Add two more nodes

Next, we add two more nodes, Adventure and Cave, below the Start node. This is the whole script so far:

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

title: Adventure
---
Narrator: We're going to go on an adventure!
===

title: Cave
---
Narrator: Let's look inside the spooky cave...
===
The Start node, followed by the new Adventure and Cave nodes.

Run the Yarn Spinner Script to see what happens. Nothing has changed.

That’s because there is currently no path to these nodes from the Start node. To add a path, use the jump command.

Add a Jump Command

Update the contents of the Start node, and add a jump command, like this:

Yarn 
title: Start
---
Narrator: Hi, I'm the narrator for the documentation!
<<jump Adventure>>
===

title: Adventure
---
Narrator: We're going to go on an adventure!
===

title: Cave
---
Narrator: Let's look inside the spooky cave...
===
Line 4 This is a jump command. All commands in Yarn Spinner are surrounded by << and >>. The jump command contains the jump keyword, and then the title of the node you want to jump to. This jump command will jump to the node titled Adventure.
The Start node now jumps to the Adventure node.

All commands in Yarn Spinner are surrounded by << and >>. A jump command contains the jump keyword, and then the title of the node you want to jump to.

This jump command will jump to the node titled Adventure.

Run the Yarn Spinner Script again. Your story is now slightly more interesting.

When the line containing the jump command arrives, the story continues in the node that was jumped to, so you’ll now also see the line Narrator: We're going to go on an adventure!

Our story is short, and we still have another node that’s not being used.

Introducing options

We’re going to introduce one final concept in this Beginner’s Guide: Options.

This is the script with the Adventure node updated to have two options:

Yarn 
title: Start
---
Narrator: Hi, I'm the narrator for the documentation!
<<jump Adventure>>
===

title: Adventure
---
Narrator: We're going to go on an adventure!
-> OK! Let's go!
    <<jump Cave>>
-> I don't want to go on an adventure...
    Narrator: Oh, OK then.
===

title: Cave
---
Narrator: Let's look inside the spooky cave...
===
Lines 10–13 Lines that start with -> are options, and these two are presented to the player together. The indented line under each option only runs if that option is chosen.
The Adventure node now offers the player two options.

The lines that start with -> are known as options. Options provide a choice to the player and always begin with a ->.

All options at the same level, in the same node, are presented at the same time. The options we added here will be presented together. Lines indented after an option will only be run if that option is chosen.

Any lines that are not options but occur after options will only be run if one of the options does not jump away to another node.

Run the script once more. When you choose the line OK! Let's go! the action will jump to the node titled Cave.

What we wrote

We wrote a simple Yarn Spinner script consisting of one node (titled Start), with one line inside that node, delivering a greeting from a narrator.

Then we added two more nodes, a jump command, and some options, with jumps occurring depending on the option chosen.

flowchart TD
  start["<b>Start</b><br>Narrator: Hi, I'm the narrator for the documentation!"]
  adventure["<b>Adventure</b><br>Narrator: We're going to go on an adventure!"]
  cave["<b>Cave</b><br>Narrator: Let's look inside the spooky cave..."]
  done(["Narrator: Oh, OK then.<br>The dialogue ends."])
  start -->|"#lt;#lt;jump Adventure#gt;#gt;"| adventure
  adventure -->|"-#gt; OK! Let's go!<br>#lt;#lt;jump Cave#gt;#gt;"| cave
  adventure -->|"-#gt; I don't want to go on an adventure..."| done
The script we wrote. Start jumps to Adventure, and the option the player chooses in Adventure either jumps to Cave or ends the dialogue.

Next, read the Fundamentals of Writing Yarn Scripts.

Writing your own

To write and play your own Yarn Spinner Scripts in your browser, use Try Yarn Spinner. When you’re ready to write dialogue for a game, you’ll use our editor, Yarn Spinner for Visual Studio Code.

Next try.yarnspinner.dev