Dialogue Runner

The Dialogue Runner (Yarn 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 Dialogue Runner is a component, so it goes on an Actor. You can add it to an Actor in your Level, or to an Actor Blueprint.

1. Select the Actor, click Add in the Components panel, and search for Yarn Dialogue Runner.
2. Select the new YarnDialogueRunner component. In the Details panel, under Yarn Spinner, set Yarn Project to the Yarn Project asset you imported from your .yarnproject.
3. If you want the dialogue to start on its own, turn on Auto Start, under Behaviour, and type the name of the node to start from in Start Node. It defaults to Start, and you can only edit it while Auto Start is on.

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.

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. Add them, and a Line Advancer, to the same Actor as the Dialogue Runner:

The Dialogue Runner only talks to Presenters in its Dialogue Presenters list. It doesn’t look through its Actor’s components for them, so a Presenter that isn’t in the list is never used.

To add a Presenter to the list, select the YarnDialogueRunner component, and click + next to Dialogue Presenters, under Yarn Spinner in the Details panel. Each entry picks a component: choose the Actor it’s on, then the component. The Presenters can be on the Dialogue Runner’s own Actor or on any other Actor in the Level.

The Dialogue Runner reads this list when the game starts, during its own Begin Play.

DialogueRunner->DialoguePresenters.Add(LinePresenter);
DialogueRunner->DialoguePresenters.Add(OptionsPresenter);
DialogueRunner->DialoguePresenters.Add(LineAdvancer);

Line Presenter and Options Presenter explain how to connect each Presenter to your widgets, change how text appears, and style the option buttons.

The Dialogue Runner’s settings

The Dialogue Runner’s settings are under Yarn Spinner in the Details panel.

The Events are described below.

Starting and stopping dialogue

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

Otherwise, start it yourself, for example when the player talks to a character.

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "Rosa.generated.h"

class UYarnDialogueRunner;

UCLASS()
class ARosa : public AActor
{
	GENERATED_BODY()

public:
	ARosa();

	UFUNCTION(BlueprintCallable)
	void TalkToRosa();

protected:
	virtual void BeginPlay() override;

	UFUNCTION()
	void HandleDialogueStart();

	UFUNCTION()
	void HandleDialogueComplete();

	UPROPERTY(VisibleAnywhere)
	TObjectPtr<UYarnDialogueRunner> DialogueRunner;
};

#include "Rosa.h"
#include "YarnDialogueRunner.h"

ARosa::ARosa()
{
	DialogueRunner = CreateDefaultSubobject<UYarnDialogueRunner>(TEXT("YarnDialogueRunner"));
}

void ARosa::TalkToRosa()
{
	DialogueRunner->StartDialogue(TEXT("Lighthouse"));
}

These are the Dialogue Runner’s Blueprint nodes for starting and stopping dialogue. In C++, they’re StartDialogue(), StartDialogueFromStart(), StartDialogueFromReference(), StopDialogue() and IsDialogueRunning().

• Start Dialogue starts from the node you name in Node Name. If there’s no node with that name, it logs an error and doesn’t start.
• Start Dialogue from Start starts from Start Node, whether or not Auto Start is on.
• Start Dialogue from Reference takes a Yarn Node Reference, which you set in the Details panel by choosing a Yarn Project and then picking one of its nodes from a dropdown. If the node is in a different Yarn Project from the one the Dialogue Runner has, the Dialogue Runner switches to that project first.
• Stop Dialogue ends the dialogue immediately. The Presenters are told the dialogue is over, and On Dialogue Complete is called.
• Is Dialogue Running is true while dialogue is running. Use it to stop the player walking off mid-conversation.

Events

The Dialogue Runner calls these events as the dialogue runs. In the Blueprint editor, select the YarnDialogueRunner component and click + next to an event in the Events section of the Details panel to add it to your Event Graph. In C++, bind to them with AddDynamic().

For example, to stop the player moving while they’re in a conversation, connect On Dialogue Start to a Set Ignore Move Input node with New Move Input turned on, and On Dialogue Complete to one with it turned off. Both nodes target the Player Controller, from Get Player Controller.

void ARosa::BeginPlay()
{
	Super::BeginPlay();

	DialogueRunner->OnDialogueStart.AddDynamic(this, &ARosa::HandleDialogueStart);
	DialogueRunner->OnDialogueComplete.AddDynamic(this, &ARosa::HandleDialogueComplete);
}

void ARosa::HandleDialogueStart()
{
	if (APlayerController* PlayerController = GetWorld()->GetFirstPlayerController())
	{
		PlayerController->SetIgnoreMoveInput(true);
	}
}

void ARosa::HandleDialogueComplete()
{
	if (APlayerController* PlayerController = GetWorld()->GetFirstPlayerController())
	{
		PlayerController->SetIgnoreMoveInput(false);
	}
}

When a Command doesn’t match anything you’ve registered, the Dialogue Runner logs an error and calls On Unhandled Command. With Continue on Unhandled Command on, which is the default, the dialogue then carries on. Turn it off to make the dialogue wait until you call Continue on the Dialogue Runner, for example once your own code has handled the Command.

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 key. If you’re building your own controls, call these on the Dialogue Runner yourself:

• Request Hurry Up asks the current line to finish appearing at once, such as by skipping the typing effect. The line stays on screen.
• Request Next Line asks the Presenters to finish with the current line and move on.
• Request Hurry Up Option asks the options to finish appearing at once.

Options

These settings, under Behaviour, change how options work.

Changing the Yarn Project while the game runs

To make a Dialogue Runner use a different Yarn Project while the game runs, such as when the player moves to a new Level, call Set Yarn Project on it with the new Yarn Project asset. In C++, call SetYarnProject().

If dialogue is running, it stops first. Your variables are kept, and variables you haven’t set yet take their starting values from the new project. Call Start Dialogue afterwards to run a node from the new project.

Saving and loading

Yarn Spinner can save your Yarn variables to a save game slot, using Unreal’s save game system, and load them back. In Blueprints, use Save Variables to Slot and Load Variables from Slot, under Yarn Spinner > Persistence. Each takes the Dialogue Runner, a Slot Name, which defaults to YarnVariables, and a User Index, which defaults to 0.

#include "YarnBlueprintLibrary.h"

UYarnBlueprintLibrary::SaveVariablesToSlot(DialogueRunner, TEXT("YarnVariables"), 0);
UYarnBlueprintLibrary::LoadVariablesFromSlot(DialogueRunner, TEXT("YarnVariables"), 0);

Both return true if they worked. Loading replaces every variable in the Dialogue Runner’s Variable Storage with the saved ones. Use a different slot name for each save slot, such as YarnSave_Slot1 and YarnSave_Slot2. Does Variable Slot Exist tells you whether a slot has been saved, and Delete Variable Slot deletes one.

See Variables and Storage for other ways to save your variables along with the rest of your game.