The Pieces of Yarn Spinner
Yarn Spinner has six parts:
- 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| runnerYarn 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.
A Yarn Script describes a conversation: what’s said, what the player can choose, and when something should happen. Putting that on screen and acting on it is left to your game, which Yarn has no access to.
The Yarn language is the same in every version of Yarn Spinner, including the ones for Unity and Unreal. 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 the one program your game runs.
The project is compiled again automatically whenever 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.
It looks up the text of each line and hands it to your Presenters. A set of options goes to the Presenters too, and the Dialogue Runner waits for the player to choose. For a command, it calls the matching method in your game code. For a variable or a condition, it reads or writes the value in its Variable Storage.
Showing lines and options to the player 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.
The Line Presenter moves on to the next line when the player presses its Continue Action, ui_accept by default. For separate controls, like one button to finish typing a line and another to skip it, add a Line Advancer.
If the built-in Presenters don’t suit your game, write your own. A Presenter can show lines as chat bubbles or as speech above characters’ heads.
See Showing Dialogue.
Commands and Functions
Commands and Functions connect your Yarn Scripts to your game code.
With a Command, a Yarn Script tells your game to do something. <<wave Rosa>> calls a method you’ve written, and if that method takes time, like playing an animation, the dialogue can wait until it’s finished.
A Function asks your game a question, like how much gold the player has, and the Yarn Script uses the answer in a condition or a line.
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:
- The Dialogue Runner starts the
Lighthousenode. - The Line Presenter types out Rosa’s first line, and the Dialogue Runner waits until the player continues.
- The two options appear as buttons in the Options Presenter until the player picks one.
- If the player picks the first option, the Dialogue Runner sets
$knows_about_lampin its Variable Storage, then shows Rosa’s reply. - At
<<wave Rosa>>, it calls yourwavecommand, which makes Rosa’s character wave. - The node ends, and so does the dialogue.