Pardon our dust! Docs for Yarn Spinner for Unity 3.2 and Yarn Spinner for Godot C# are on docs.yarnspinner.dev (the old docs site). Docs for Yarn Spinner for Unity 3.3, Yarn Spinner for Godot GDScript and Yarn Spinner for Unreal Engine (work in progress) are on /docs/ (the new docs site).

The Pieces of Yarn Spinner

Yarn Spinner has six parts:

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
How the parts of Yarn Spinner connect.

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 called Lighthouse, with lines, options and a variable.

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.

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. The Line Presenter types out Rosa’s first line, and the Dialogue Runner waits until the player continues.
  3. The two options appear as buttons in the Options Presenter 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.
Next step Setting Up Your Godot Project Add your Yarn Project and Yarn Scripts to Godot, and see what the editor gives you once they're in.