Beginner's Guide

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

Writing Yarn with Try Yarn Spinner

When you first start learning Yarn, you can use Try Yarn Spinner, our introductory, browser- based tool for writing Yarn Spinner Scripts. No installation necessary!

As you learn to write dialogue and game scripts with Yarn, you'll eventually need to use our editor, which is a Visual Studio Code Extension. Before you get to that stage, the best place to experiment with, and explore Yarn Spinner, is Try Yarn Spinner. We strongly recommend that you learn piece by piece.

1

Visit Try Yarn Spinner at https://try.yarnspinner.dev

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

In Try Yarn Spinner, the first node to run is always called Start, so we’ll write that now.

In your own games or narratives outside of Try Yarn Spinner, the first node can be named whatever you like.

2

Create a Start node with a line of dialogue

Copy and paste, or write, this Yarn Spinner script into Try Yarn Spinner, and hit the Run button in the top-right.

 Hi, I'm the narrator for the documentation!

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

3

Play your Yarn Script

Use the Run button in the top right-hand corner of Try Yarn Spinner to run your Yarn Spinner Script. You can play through it in the right pane. There isn't much to play right now!

4

Add a two more nodes

In the left-hand pane of Try Yarn Spinner, add a new node by copy and pasting, or writing, the following snippet of Yarn Spinner script. Place it below the previous node.

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

title: Cave
---
Narrator: Let's look inside the spooky cave...
===

You may want to Run the Yarn Spinner Script to see what happens. You'll probably notice that nothing has changed!

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

5

Add a Jump Command

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

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

===

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.

So, this particular jump command will jump to the node titled Adventure.

6

Play your Yarn Spinner Script again

Use the Run button in the top right-hand corner of Try Yarn Spinner to run your Yarn Spinner Script again. Your story is now slightly more interesting!

You'll notice that 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 isn't particularly amazing, but we still have another node that's not being used...

7

Introducing Options

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

Update your Adventure node to look like the following:

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

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

All options at the same level, in the same node, are presented at the same time. So 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.

8

Play your Yarn Spinner Script yet again

Use the Run button to once again run your script.

You'll notice that when you choose the line OK! Let's go! the action will jump to the node entitle Cave. Great, right?

What did we just do?

We just 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 occuring depending on the option chosen.

And that's the very basics of Yarn Spinner Scripting! Dive into the Fundamentals of Writing Yarn Scripts next.