Dialogue Runner

The Dialogue Runner is the component that runs your dialogue. You give it a Yarn Project, and it steps through your Yarn Scripts one line at a time. It hands each line and set of options to your Dialogue Presenters, calls your Commands, and keeps track of your variables.

The Dialogue Runner doesn’t show anything on screen. The Presenters do that.

Adding a Dialogue Runner

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, Presenters and a Line Advancer, already connected. See Showing Dialogue.

To add a Dialogue Runner to a GameObject of your own instead, click Add Component in the Inspector and search for Dialogue Runner.

1. Select the Dialogue Runner, and set Yarn Project to your .yarnproject, by dragging it in from the Project window.
2. If you want the dialogue to start on its own, turn on Start Automatically, and choose which node to start from in Start Node. It’s a dropdown of the nodes in your Yarn Project, and defaults to Start.

Most games need one Dialogue Runner. It runs one conversation at a time, so if you need two conversations running at once, such as background chatter while the player talks to someone, use a second Dialogue Runner. The Background Chatter sample does this.

Adding Presenters

The Dialogue Runner can’t show anything until it has Presenters. Most games start with two: a Line Presenter for lines, and an Options Presenter for options. The Dialogue System prefab has both, along with a Line Advancer:

The Dialogue Runner only talks to Presenters in its Dialogue Presenters list. It doesn’t look through its children for them, so a Presenter that isn’t in the list is never used. In the Dialogue System prefab, the list holds the Line Presenter, the Options Presenter and the Line Advancer.

To add a Presenter of your own, click + under the list, and drag the GameObject with the Presenter on it into the new row. From code, set the Dialogue Runner’s DialoguePresenters property to a new list.

Line Presenter and Options Presenter explain how to set up each Presenter, change how text appears, and style the option buttons.

The Dialogue Runner’s settings

The settings for options, and the Events section, are described below.

Starting and stopping dialogue

Turn on Start Automatically and the dialogue starts on its own when the scene starts, from the node set in Start Node.

Otherwise, start it from your own code, for example when the player talks to a character:

using UnityEngine;
using Yarn.Unity;

public class Rosa : MonoBehaviour
{
    [SerializeField] DialogueRunner dialogueRunner;

    public void TalkToRosa()
    {
        dialogueRunner.StartDialogue("Lighthouse");
    }
}

• StartDialogue(nodeName) starts from the node you name. You always have to name a node; Start Node is only used by Start Automatically.
• Stop() ends the dialogue. The Presenters finish up, and On Dialogue Complete is invoked.
• IsDialogueRunning is true while dialogue is running. Use it to stop the player walking off mid-conversation.

StartDialogue() and Stop() are async, so you can await them. StartDialogue() finishes once the dialogue has started, and Stop() once the Presenters have finished with it. To wait until a whole conversation has ended, await the Dialogue Runner’s DialogueTask.

Events

The Dialogue Runner invokes these events as the dialogue runs. You’ll find them in the Events section at the bottom of the Inspector, which starts folded up. Connect them to your own methods there, or from code.

For example, to stop the player moving while they’re in a conversation:

void Start()
{
    dialogueRunner.onDialogueStart.AddListener(() => player.canMove = false);
    dialogueRunner.onDialogueComplete.AddListener(() => player.canMove = true);
}

How it works with Presenters

When the Dialogue Runner reaches a line, it gives the line to every Presenter in its list at the same time. It waits until all of them have finished with it, then moves on. A Line Presenter and a Voice Over Presenter can work on the same line, and the Dialogue Runner continues only once the text has been dismissed and the clip has finished.

When it reaches a set of options, it gives them to every Presenter in the same way, and uses the first option any of them picks.

The Line Advancer tells the Dialogue Runner to move on when the player presses a button. If you’re building your own controls, call these yourself:

• RequestHurryUpLine() asks the current line to finish appearing at once, such as by skipping the typing effect. The line stays on screen.
• RequestNextLine() asks the Presenters to finish with the current line and move on.
• RequestHurryUpOption() asks the options to finish appearing at once.

Options

These settings change how options work.

Saving and loading

The Dialogue Runner can save your Yarn variables to a file in Unity’s persistent data path, and load them back:

dialogueRunner.SaveStateToPersistentStorage("dialogue_save.json");
dialogueRunner.LoadStateFromPersistentStorage("dialogue_save.json");

Both return true if they worked. They save and load the variables in the Dialogue Runner’s Variable Storage. See Variables and Storage for other ways to save your variables along with the rest of your game.