Building Your Own Presenter

The Line Presenter and Options Presenter cover most games. If you want dialogue to look or behave differently, like speech bubbles over characters’ heads, you can write your own Presenter.

A Presenter is a component whose class is a subclass of Yarn Dialogue Presenter. You can make one as a Blueprint, or as a C++ class that extends UYarnDialoguePresenter. The Dialogue Runner gives it each line and each set of options, and it decides how to show them.

How the Dialogue Runner uses Presenters

For each line, the Dialogue Runner calls Run Line on every Presenter in its Dialogue Presenters list, all at the same time. Each Presenter calls On Line Presentation Complete when it’s finished with the line. The Dialogue Runner moves on to the next line once every one of them has.

For each set of options, it calls Run Options on every Presenter. The first one to call On Option Selected with an option’s index decides which option was picked. The Dialogue Runner then tells the others to stop, through their tokens.

sequenceDiagram
  participant R as Dialogue Runner
  participant L as Line Presenter
  participant O as Options Presenter
  R->>L: Run Line
  R->>O: Run Line
  O-->>R: On Line Presentation Complete, straight away
  L-->>R: On Line Presentation Complete, once the player continues
  Note over R: Both have finished,<br>so the options start
  R->>L: Run Options
  R->>O: Run Options
  Note over L: Doesn't show options
  O-->>R: On Option Selected (1)
  Note over R: The dialogue carries on<br>after option 1

A Presenter has two jobs:

• in Run Line, show the line, wait for as long as it needs to, then tidy up and call On Line Presentation Complete,
• in Run Options, show the options, wait for the player to pick one, then call On Option Selected with its index.

Run Line and Run Options start the work, and return straight away. Your Presenter finishes later, by calling On Line Presentation Complete or On Option Selected.

A simple Presenter

This Presenter shows each line in a Text Block, and each set of options as buttons. The player presses Space to move on to the next line, and clicks a button to pick an option.

First, make the Widget Blueprint it shows:

1. In the Content Browser, click Add, and choose User Interface›Widget Blueprint. Pick User Widget, and name it WBP_SimpleDialogue.
2. Add a Vertical Box. Inside it, add a Text Block (Text in the Palette) named LineText, and another Vertical Box named OptionsBox.

#pragma once

#include "CoreMinimal.h"
#include "Components/Button.h"
#include "YarnDialoguePresenter.h"
#include "SimplePresenter.generated.h"

class UTextBlock;
class UUserWidget;
class UVerticalBox;

UCLASS()
class USimpleOptionButton : public UButton
{
	GENERATED_BODY()

public:
	int32 OptionIndex = INDEX_NONE;

	TFunction<void(int32)> OnPicked;

	UFUNCTION()
	void HandleClicked();
};

UCLASS(ClassGroup = (Custom), meta = (BlueprintSpawnableComponent))
class USimplePresenter : public UYarnDialoguePresenter
{
	GENERATED_BODY()

public:
	USimplePresenter();

	UPROPERTY(EditAnywhere, Category = "Simple Presenter")
	TSubclassOf<UUserWidget> WidgetClass;

	virtual void TickComponent(float DeltaTime, ELevelTick TickType, FActorComponentTickFunction* ThisTickFunction) override;

	virtual void OnDialogueStarted_Implementation() override;
	virtual void OnDialogueComplete_Implementation() override;
	virtual void RunLine_Implementation(const FYarnLocalizedLine& Line, bool bCanHurry) override;
	virtual void OnNextLineRequested_Implementation() override;
	virtual void RunOptions_Implementation(const FYarnOptionSet& Options) override;

private:
	UPROPERTY(Transient)
	TObjectPtr<UUserWidget> Widget;

	UPROPERTY(Transient)
	TObjectPtr<UTextBlock> LineText;

	UPROPERTY(Transient)
	TObjectPtr<UVerticalBox> OptionsBox;

	void FinishLine();
	void PickOption(int32 Index);
};

#include "SimplePresenter.h"

#include "Blueprint/UserWidget.h"
#include "Blueprint/WidgetTree.h"
#include "Components/TextBlock.h"
#include "Components/VerticalBox.h"
#include "GameFramework/PlayerController.h"
#include "YarnDialogueRunner.h"

void USimpleOptionButton::HandleClicked()
{
	if (OnPicked)
	{
		OnPicked(OptionIndex);
	}
}

USimplePresenter::USimplePresenter()
{
	PrimaryComponentTick.bCanEverTick = true;
}

void USimplePresenter::OnDialogueStarted_Implementation()
{
	APlayerController* Player = GetWorld()->GetFirstPlayerController();
	Widget = CreateWidget<UUserWidget>(Player, WidgetClass);
	LineText = Cast<UTextBlock>(Widget->GetWidgetFromName(TEXT("LineText")));
	OptionsBox = Cast<UVerticalBox>(Widget->GetWidgetFromName(TEXT("OptionsBox")));
	Widget->AddToViewport();
	Player->SetShowMouseCursor(true);
	Player->SetInputMode(FInputModeGameAndUI());
}

void USimplePresenter::OnDialogueComplete_Implementation()
{
	APlayerController* Player = GetWorld()->GetFirstPlayerController();
	Widget->RemoveFromParent();
	Player->SetShowMouseCursor(false);
	Player->SetInputMode(FInputModeGameOnly());
}

void USimplePresenter::TickComponent(float DeltaTime, ELevelTick TickType, FActorComponentTickFunction* ThisTickFunction)
{
	Super::TickComponent(DeltaTime, TickType, ThisTickFunction);

	if (bIsPresentingOptions && IsOptionNextContentRequested())
	{
		OptionsBox->ClearChildren();
		bIsPresentingOptions = false;
	}

	if (!bIsPresentingLine)
	{
		return;
	}

	if (IsNextContentRequested())
	{
		FinishLine();
		return;
	}

	APlayerController* Player = GetWorld()->GetFirstPlayerController();
	if (Player && Player->WasInputKeyJustPressed(EKeys::SpaceBar))
	{
		GetDialogueRunner()->RequestNextLine();
	}
}

void USimplePresenter::RunLine_Implementation(const FYarnLocalizedLine& Line, bool bCanHurry)
{
	LineText->SetText(Line.Text);
}

void USimplePresenter::OnNextLineRequested_Implementation()
{
	if (bIsPresentingLine)
	{
		FinishLine();
	}
}

void USimplePresenter::FinishLine()
{
	LineText->SetText(FText::GetEmpty());
	OnLinePresentationComplete();
}

void USimplePresenter::RunOptions_Implementation(const FYarnOptionSet& Options)
{
	for (int32 i = 0; i < Options.Options.Num(); i++)
	{
		const FYarnOption& Option = Options.Options[i];
		if (!Option.bIsAvailable)
		{
			continue;
		}

		UTextBlock* Label = Widget->WidgetTree->ConstructWidget<UTextBlock>();
		Label->SetText(Option.Line.TextWithoutCharacterName);

		USimpleOptionButton* Button = Widget->WidgetTree->ConstructWidget<USimpleOptionButton>();
		Button->AddChild(Label);
		Button->OptionIndex = i;
		Button->OnPicked = [this](int32 Index) { PickOption(Index); };
		Button->OnClicked.AddDynamic(Button, &USimpleOptionButton::HandleClicked);
		OptionsBox->AddChild(Button);
	}
}

void USimplePresenter::PickOption(int32 Index)
{
	OptionsBox->ClearChildren();
	OnOptionSelected(Index);
}

Showing lines

Run Line gets the line as a Yarn Localized Line, and Can Hurry, which is always true for lines from the Dialogue Runner. The parts of the line you’ll use most:

The line is also in the Presenter’s Current Line variable until the Presenter finishes with it.

The text has already been through any marker processors, so if you’ve registered one that turns tags into Rich Text Block tags, show the text in a Rich Text Block to see the formatting. To find assets for a line, such as a portrait, ask the Dialogue Runner’s Asset Provider. See Line and Asset Providers.

Yarn Spinner adds a lastline tag to the Metadata of any line that comes right before a set of options. Check for it if your Presenter needs to behave differently when options are about to appear.

Follow these rules in Run Line:

• Wait for whatever takes time before you call On Line Presentation Complete: typing, an animation, audio, or the player.
• Call On Line Presentation Complete as soon as you can once the dialogue is moving on. The Dialogue Runner can’t move on until you do.
• Call On Line Presentation Complete once for each line. A second call can count towards the next line, and end it early.
• If your Presenter has nothing to show for a line, don’t override Run Line. The one it inherits calls On Line Presentation Complete straight away.

If your Presenter’s timing decides when the line ends, like a cutscene that ends the line when it finishes, call On Line Presentation Complete And End Line instead. It finishes the line for your Presenter, and asks for the line to end. The other Presenters see that through Is Next Content Requested. The Voice Over Presenter does this when a clip finishes.

Hurrying and moving on

While a line is showing, the player or your game can ask for two things:

• Hurry up: the player wants the line to finish showing now. Skip to the end of any typing or animation, but keep the line on screen.
• Next line: the dialogue is moving on. Tidy up and call On Line Presentation Complete.

Your Presenter finds out about these in two ways. These events are called when the request comes through the Dialogue Runner:

If you override On Next Line Requested, call On Line Presentation Complete yourself, or call the parent version. Don’t do both.

These functions tell you where things stand at any moment:

The events are only called when the request comes through the Dialogue Runner, like this:

• the Line Advancer gets the player’s input,
• your own code calls Request Hurry Up, Request Next Line or Request Hurry Up Option on the Dialogue Runner, or Request Continue on a Presenter.

When the line ends for any other reason, the functions change but no event is called. That happens when:

• a Voice Over Presenter’s clip finishes, with End Line When Voice Over Complete on,
• another Presenter calls On Line Presentation Complete And End Line,
• another Presenter’s option is picked.

To catch these, check Is Next Content Requested and Is Option Next Content Requested while your Presenter is waiting, as the simple Presenter above does in its tick.

The token in C++

In C++, the line and options each come with a FYarnLineCancellationToken, in CurrentLineCancellationToken and CurrentOptionsCancellationToken. The functions above read them. You can also use them directly:

Pass the token to anything that should finish early when the player hurries, such as the effects on Typewriter and Effects. In Blueprints, get the same token with Get Current Cancellation Token on the Dialogue Runner.

The Dialogue Runner makes a new token for each line and each set of options, and the Presenter clears its own when it calls On Line Presentation Complete or On Option Selected. Don’t keep one to use later.

A Presenter that passes lines on to other Presenters can override Internal_RunLine and Internal_RunOptions, which receive the token and the function to call when it’s done. To stop its own Presenters without ending the line for everyone, it can make a token source of its own with UYarnCancellationTokenSource::CreateLinkedTokenSource, linked to the token it was given.

Showing options

Run Options gets a Yarn Option Set. Its Options array holds a Yarn Option for each option. Each has Line, the option’s text as a Yarn Localized Line, and Is Available, which is false when the option’s condition failed.

Call On Option Selected with the index in the array of the option the player picked. To carry on without a choice, pass -1. The Options Presenter does this when every option is unavailable.

If your Presenter doesn’t show options, don’t override Run Options. The one it inherits does nothing. In C++, also override CanHandleOptions to return false. The Dialogue Runner uses it to tell whether any Presenter can show options. If none can, what happens depends on its Allow Option Fallthrough setting. See Dialogue Runner.

Other events you can use

Every Presenter also has the Auto Advance settings, for lines that move on by themselves after enough time to read them. Turn on Auto Advance Enabled, and call Start Auto Advance Timer when your line has finished appearing. When the timer runs out, the Presenter calls On Line Presentation Complete And End Line. The time is Auto Advance Min Delay, 2 seconds by default, plus Auto Advance Time Per Character, 0.05 by default, for each character in the line, up to Auto Advance Max Delay, 10 seconds by default. Cancel Auto Advance Timer stops it.

To fade your Presenter’s widgets in or out, use the Yarn Fade Widget In and Yarn Fade Widget Out nodes. See Typewriter and Effects.