Understanding Yarn Spinner

Yarn Spinner is a collection of things that work together to get dialogue from your writing into your game:

• Yarn Scripts, where you write your dialogue in the Yarn language.
• Yarn Projects, which group your Yarn Scripts and are compiled when Godot imports them.
• The Dialogue Runner, a node in your scene that plays your dialogue.
• Dialogue Presenters, such as the Line Presenter and Options Presenter, which show that dialogue to the player.
• Commands and Functions, which connect your dialogue to your game code.
• Variable Storage, which keeps track of your Yarn variables.

flowchart LR
  scripts["Yarn Scripts<br>.yarn files"] --> project["Yarn Project<br>compiled on import"]
  project --> runner["Dialogue Runner"]
  runner -->|lines and options| presenters["Dialogue Presenters<br>Line, Options, Voice-Over"]
  presenters --> player(("Player"))
  runner <-->|reads and writes| storage["Variable Storage"]
  runner -->|Commands| game["Your game code"]
  game -->|Function results| runner

Yarn Scripts

You write dialogue in .yarn files, using the Yarn language. A Yarn Script is made of nodes, and each node holds a piece of conversation:

title: Lighthouse
---
Rosa: Are you here about the lamp?
-> Yes, I heard it went out.
    <<set $knows_about_lamp to true>>
    Rosa: Nobody's been up there in weeks.
-> Just passing through.
    Rosa: Mind the stairs.
<<wave Rosa>>
===

A node can contain:

• Lines that a character says.
• Options for the player to choose between.
• Variables, like $knows_about_lamp, that store values between conversations.
• Conditions that show a line or option only when something is true.
• Jumps to other nodes.
• Commands, like <<wave Rosa>>, that tell your game to do something.

Yarn doesn’t draw anything, and has no access to your game. It describes what’s said, what the player can choose, and when something should happen. Your game decides how that looks and what it does.

The Yarn language is the same in every version of Yarn Spinner, so what you learn here applies in Unity and Unreal too. To learn the language itself, see Learn the Yarn Language.

Yarn Projects

Your .yarn files are grouped by a Yarn Project, a .yarnproject file that lists which Yarn Scripts belong together. When Godot imports the project, it compiles all of its scripts into one program. That program is what your game runs.

The project is compiled again automatically when ever you save a script. Compiling gives every line an ID, which is used to look up the line’s text later, including in other languages.

See Setting Up Your Godot Project.

Dialogue Runner

The Dialogue Runner is a node in your scene, YarnDialogueRunner. You give it a Yarn Project and tell it which node to start from. It then steps through your dialogue one piece at a time:

• When it reaches a line, it looks up the line’s text and hands it to your Presenters.
• When it reaches a set of options, it hands them to your Presenters and waits for the player to choose.
• When it reaches a command, it calls the matching method in your game code.
• When it reaches a variable or a condition, it reads or writes the value in its Variable Storage.

The Dialogue Runner never shows anything itself. Showing things is the Presenters’ job.

Dialogue Presenters

A Dialogue Presenter is a node that shows dialogue to the player. The addon includes Presenters for the common cases:

• A Line Presenter shows each line as text, with the speaker’s name, typing out letter by letter.
• An Options Presenter shows each option as a button.
• A Voice-Over Presenter plays a recorded clip for each line.

You can use several at once. The Dialogue Runner gives each line to every Presenter at the same time, and waits until they’ve all finished before moving on. With a Line Presenter and a Voice-Over Presenter together, the text stays on screen until the clip has played.

If the built-in Presenters don’t suit your game, write your own. A Presenter can show lines as chat bubbles, as speech above characters’ heads, or as anything else your game needs.

See Showing Dialogue.

Commands and Functions

Commands and Functions connect your Yarn Scripts to your game code.

• A Command lets a Yarn Script tell your game to do something. <<wave Rosa>> calls a method you’ve written. If that method takes time, like playing an animation, the dialogue can wait until it’s finished.
• A Function lets a Yarn Script ask your game a question, like how much gold the player has, and use the answer in a condition or a line.

See Connecting to Your Game.

Variable Storage

Yarn variables, like $knows_about_lamp, are kept in a Variable Storage. By default, the Dialogue Runner creates one that keeps them in memory. Your game code can read and change the same variables, and save and load them with your save game.

Putting it together

When the example above runs:

1. The Dialogue Runner starts the Lighthouse node.
2. At Rosa’s first line, it looks up the text and gives it to your Presenters. The Line Presenter types it out. The Dialogue Runner waits until the player continues.
3. The two options go to your Presenters next. The Options Presenter shows two buttons. The Dialogue Runner waits until the player picks one.
4. If the player picks the first option, the Dialogue Runner sets $knows_about_lamp in its Variable Storage, then shows Rosa’s reply.
5. At <<wave Rosa>>, it calls your wave command, which makes Rosa’s character wave.
6. The node ends, and so does the dialogue.