The Pieces of 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 Unity imports them.
• The Dialogue Runner, a component in your scene that plays your dialogue.
• Dialogue Presenters, such as the Line Presenter and Options Presenter, which show that dialogue to the player.
• The Line Advancer, which lets the player move the dialogue on.
• Commands and Functions, which connect your dialogue to your C# 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"))
  player -->|input| advancer["Line Advancer"]
  advancer -->|next line| runner
  runner <-->|reads and writes| storage["Variable Storage"]
  runner -->|Commands| game["Your C# 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 Godot 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 asset that lists which Yarn Scripts belong together. When Unity 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 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 Unity Project.

Dialogue Runner

The Dialogue Runner is a component on a GameObject in your scene. 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 C# 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.

The quickest way to get a Dialogue Runner is the Dialogue System prefab. Open the GameObject menu, and choose Yarn Spinner › Dialogue System. It comes with a Dialogue Runner, a Line Presenter, an Options Presenter and a Line Advancer, already connected to each other.

Dialogue Presenters

A Dialogue Presenter is a component that shows dialogue to the player. Yarn Spinner for Unity 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.

Line Advancer

The Line Presenter shows a line, but doesn’t listen for the player’s input. A Line Advancer does. When the player presses a button, it tells the Presenters to finish typing the current line, or to move on to the next one. It can also make the options appear straight away, or end the dialogue.

The Line Advancer works with Unity’s Input System, or with the older Input Manager. The Dialogue System prefab includes one, set up to use the keyboard.

See Line Presenter.

Commands and Functions

Commands and Functions connect your Yarn Scripts to your C# code.

• A Command lets a Yarn Script tell your game to do something. <<wave Rosa>> calls a method you’ve marked with the [YarnCommand("wave")] attribute, on the GameObject named Rosa. 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. If the Dialogue Runner doesn’t have one, it adds an In Memory Variable Storage, which keeps them in memory. Your C# code can read and change the same variables, and save and load them with your save game.

Line Providers

When the Dialogue Runner reaches a line, it asks a Line Provider for the line’s text, and for any assets that go with it, like a voice-over clip. There are two:

• The Built-in Localised Line Provider uses the text and assets in your Yarn Project. The Dialogue Runner adds one if it doesn’t have a Line Provider.
• The Unity Localised Line Provider uses Unity’s Localization package instead.

See Localisation and Assets.

Putting it together

When the example above runs:

1. The Dialogue Runner starts the Lighthouse node.
2. At Rosa’s first line, it gets the text from the Line Provider and gives it to your Presenters. The Line Presenter types it out. The Dialogue Runner waits until the player presses a button, and the Line Advancer tells it to continue.
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 the wave command on the GameObject named Rosa, which makes Rosa’s character wave.
6. The node ends, and so does the dialogue.