The Pieces of Yarn Spinner

Yarn Spinner has eight parts:

• Yarn Scripts, where you write your dialogue in the Yarn language.
• Yarn Projects, which group your Yarn Scripts and are compiled when Unreal imports them.
• The Dialogue Runner, a component on an Actor in your Level 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 Blueprints and C++ code.
• Variable Storage, which keeps track of your Yarn variables.
• Line Providers, which find the text for each line.

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 Blueprints<br>and 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 Unity and Godot 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 you drag it into the Content Browser, Unreal runs ysc, the Yarn Spinner compiler, which compiles all of its scripts into one program. The plugin reads the result into a Yarn Project asset. That asset is what your game runs.

The project is compiled again automatically whenever you save a script. Compiling always covers every script in the project, never one file on its own. It gives every line an ID, which is used to look up the line’s text later, including in other languages.

See Setting Up Your Unreal Project.

Dialogue Runner

The Dialogue Runner is a component, Yarn Dialogue Runner, that you add to an Actor. 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 gets the line’s text from its Line Provider 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 function in your Blueprints or 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.

You set up a Dialogue Runner in the Details panel, and control it from Blueprints or C++, with functions like Start Dialogue and Stop Dialogue. It also has events, like On Dialogue Start, On Node Start and On Dialogue Complete, that your Blueprints can bind to.

There’s no ready-made Actor with everything set up. A typical setup puts the Dialogue Runner and its Presenters on the same Actor:

See Dialogue Runner.

Dialogue Presenters

A Dialogue Presenter is a component that shows dialogue to the player. Yarn Spinner for Unreal Engine includes Presenters for the common cases:

• A Line Presenter shows each line as text in a UMG widget, 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 sound for each line.

You tell the Dialogue Runner which Presenters to use by adding them to its Dialogue Presenters list in the Details panel. 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 sound has played.

If the built-in Presenters don’t suit your game, write your own. Make a Blueprint whose parent class is Yarn Dialogue Presenter, and override Run Line and Run Options, or subclass UYarnDialoguePresenter in C++. A Presenter can show lines as chat bubbles or as speech above characters’ heads.

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 key, 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 is a Presenter too, so you add it to the Dialogue Runner’s Dialogue Presenters list, where it can tell when a line or a set of options starts and ends. By default it listens for the space bar. Set its Input Mode to Manual to call its functions from your own input code instead.

See Line Presenter.

Commands and Functions

Commands and Functions connect your Yarn Scripts to your Blueprints and C++ code.

• A Command lets a Yarn Script tell your game to do something. <<wave Rosa>> calls a function named wave. The Dialogue Runner looks for it first on the objects in its Command Handler Objects list, then on the Actor in your Level named Rosa. If that function 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 when the game starts, it adds a Yarn In Memory Variable Storage component to its Actor, which keeps them in memory. Your Blueprints and C++ code can read and change the same variables, and save and load them with Unreal’s save game system.

See Variables and Storage.

Line Providers

When the Dialogue Runner reaches a line, it asks a Line Provider for the line’s text. There are three:

• The Yarn Builtin Line Provider uses the text in your Yarn Project, and any translations listed in it. The Dialogue Runner makes one if it doesn’t have a Line Provider.
• The Yarn String Table Line Provider looks lines up in an Unreal String Table, by line ID.
• The Yarn Culture Aware Line Provider uses a different String Table for each culture, and follows Unreal’s current culture.

Assets that go with a line, like a voice-over sound, come from an Asset Provider. The Dialogue Runner makes one of these too, if it doesn’t have one.

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 key, 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 function on the Actor named Rosa, which makes Rosa’s character wave.
6. The node ends, and so does the dialogue.