Line and Asset Providers

The Dialogue Runner has two helpers for getting lines ready:

• The Line Provider gets each line’s text, in the right language, ready to show.
• The Asset Provider finds assets that go with each line, like voice clips, and loads them before they’re needed.

If the Dialogue Runner doesn’t have them when play begins, it makes a Yarn Builtin Line Provider and a Yarn Project Asset Provider. They’re in its Line Provider and Asset Provider properties. Both are objects the Dialogue Runner makes while the game runs, so you set them up from Blueprints or C++, not in the Details panel.

The Line Provider

When a line runs, the Dialogue Runner gives the Line Provider the line’s ID, and gets back a line that’s ready for the Presenters:

flowchart TB
  id["Line ID: line:a1b2c3d"]
  presenters["Presenters"]
  id -->|"1. find the text"| text["Rosa: You've got {0} coins."]
  text -->|"2. fill in values"| subs["Rosa: You've got 15 coins."]
  subs -->|"3. read markup"| presenters

1. It finds the text in the current language. See Localising Your Game.
2. It fills in values, like {$coins} or {days_since_lamp_lit()}, which the dialogue has already worked out.
3. It reads the markup, like [b] or [wave], so the Presenters know what to show. [select], [plural] and [ordinal] are replaced with their words here. See Markup.

The Dialogue Runner does this for every line, and for every option. The result is a Yarn Localized Line, FYarnLocalizedLine in C++, which the Dialogue Runner gives to each of its Dialogue Presenters:

In a translation, each value is written as a number in braces, like {0}. Translators should keep these, and can move them to wherever they belong in their language:

id,text,...
line:c3d4e5f,Rosa: Du hast {0} Münzen.,...

To get the Line Provider from a Blueprint, get the Yarn Dialogue Runner’s Line Provider. From C++, it’s the Dialogue Runner’s LineProvider property.

The Line Providers that come with the plugin

The Yarn Builtin Line Provider’s settings are in When a line isn’t translated. The two String Table Line Providers are in Using Unreal’s String Tables.

Shadow lines

Sometimes the same line appears in more than one place, like a greeting that can come up in several nodes. A shadow line is a copy of another line that shares its translations and voice clip, so it only needs translating and recording once.

Give the copy a #shadow: tag with the ID of the line it copies, instead of a #line: tag:

title: Morning
---
Rosa: Hello again. #line:a1b2c3d #audio:/Game/Dialogue/Voice/HelloAgain
===

title: Evening
---
Rosa: Hello again. #shadow:a1b2c3d
===

A shadow line must have exactly the same text as the line it copies. If it doesn’t, the Yarn Project won’t compile, and you’ll see “Shadow lines must have the same text as their source”. All the Line Providers that come with the plugin support shadow lines. See Shadow Lines.

The Asset Provider

The Asset Provider finds an asset for a line. The Yarn Project Asset Provider, which the Dialogue Runner makes if it doesn’t have one, finds it from a tag on the line. The tag is #audio: followed by the asset’s path in the Content Browser, without Content:

Rosa: Hello again. #line:a1b2c3d #audio:/Game/Dialogue/Voice/HelloAgain

Whoever asks for the asset says what kind it should be. The Voice Over Presenter asks for a Sound Base, so it plays the line’s clip if the tag names a sound, and nothing if it names something else. See Voice-Over.

For a shadow line without an #audio: tag of its own, the Asset Provider uses the tag on the line it copies.

The Yarn Project Asset Provider has one setting. Metadata Prefix is the tag it reads, without the colon. It’s audio to start with. A line can name one asset this way.

Getting a line’s asset in your own Presenter

To get a line’s asset in a Presenter of your own, ask the Dialogue Runner’s Asset Provider for it:

UYarnDialogueRunner* Runner = GetDialogueRunner();
UObject* AssetProvider = Runner ? Runner->AssetProvider.GetObject() : nullptr;
UTexture2D* Texture = AssetProvider
	? Cast<UTexture2D>(IYarnAssetProvider::Execute_GetAssetForLine(AssetProvider, Line, UTexture2D::StaticClass()))
	: nullptr;

Loading assets before they’re needed

Each time a node starts, the Dialogue Runner calls the Line Provider’s Prepare For Lines, and each Presenter’s On Prepare For Lines, with the IDs of the lines in the node.

The Voice Over Presenter then calls the Asset Provider’s Prepare Assets For Lines. The Yarn Project Asset Provider starts loading the assets named in those lines’ tags in the background, so they’ve usually loaded by the time each line runs. To do the same in your own Presenter, override On Prepare For Lines and call Prepare Assets For Lines with the line IDs and your kind of asset.

Choosing assets with your own tag

Naming an asset’s path in each line means the paths have to stay the same, and a line can only name one asset with #audio:. If you’d rather pick a line’s asset yourself, give the line a tag of your own, like #picture:lamp, and read it in your Presenter. A line’s tags are in the Yarn Localized Line’s Metadata, without the #. Get Metadata Value finds the tag that starts with a key, like picture, and gives you the rest of it, like lamp.

#pragma once

#include "CoreMinimal.h"
#include "YarnDialoguePresenter.h"
#include "YarnLineMetadata.h"
#include "Components/Image.h"
#include "Engine/Texture2D.h"
#include "PicturePresenter.generated.h"

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

public:
	UPROPERTY(BlueprintReadWrite, Category = "Dialogue")
	TObjectPtr<UImage> Picture;

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Dialogue")
	TMap<FString, TObjectPtr<UTexture2D>> Pictures;

	virtual void RunLine_Implementation(const FYarnLocalizedLine& Line, bool bCanHurry) override
	{
		UTexture2D* Texture = PictureFor(Line);

		if (Picture)
		{
			Picture->SetBrushFromTexture(Texture);
			Picture->SetVisibility(Texture ? ESlateVisibility::Visible : ESlateVisibility::Hidden);
		}

		OnLinePresentationComplete();
	}

	virtual void OnDialogueComplete_Implementation() override
	{
		if (Picture)
		{
			Picture->SetVisibility(ESlateVisibility::Hidden);
		}
	}

protected:
	virtual bool CanHandleOptions() const override
	{
		return false;
	}

private:
	UTexture2D* PictureFor(const FYarnLocalizedLine& Line) const
	{
		FString PictureName;
		if (!UYarnLineMetadataLibrary::GetMetadataValue(Line.Metadata, TEXT("picture"), PictureName))
		{
			return nullptr;
		}

		const TObjectPtr<UTexture2D>* Found = Pictures.Find(PictureName);
		return Found ? Found->Get() : nullptr;
	}
};

title: Pictures
---
Rosa: This is the old lamp from the tower. #picture:lamp
Rosa: Here's the key to get in. #picture:key
Rosa: Good luck up there.
===

Add the Presenter to the same Actor as your Yarn Dialogue Runner, and add it to the Yarn Dialogue Runner’s Dialogue Presenters list, next to your Line Presenter:

The lines keep their own line tags, so you can still tag them with ysc tag, and the line’s other tags stay in its Metadata.

Writing your own Asset Provider

To find assets another way, write an Asset Provider of your own. It’s any object that implements the Yarn Asset Provider interface, which has two functions:

#pragma once

#include "CoreMinimal.h"
#include "YarnAssetProvider.h"
#include "Engine/AssetManager.h"
#include "LanguageFolderAssetProvider.generated.h"

UCLASS(BlueprintType)
class ULanguageFolderAssetProvider : public UObject, public IYarnAssetProvider
{
	GENERATED_BODY()

public:
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Dialogue")
	FString RootPath = TEXT("/Game/Dialogue/Voice");

	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Dialogue")
	FString LocaleCode = TEXT("en");

	virtual UObject* GetAssetForLine_Implementation(const FYarnLocalizedLine& Line, UClass* AssetClass) override
	{
		const FString LineID = Line.ShadowSourceLineID.IsEmpty() ? Line.RawLine.LineID : Line.ShadowSourceLineID;
		return StaticLoadObject(AssetClass, nullptr, *MakePath(LineID), nullptr, LOAD_NoWarn | LOAD_Quiet);
	}

	virtual void PrepareAssetsForLines_Implementation(const TArray<FString>& LineIDs, UClass* AssetClass) override
	{
		TArray<FSoftObjectPath> Paths;
		for (const FString& LineID : LineIDs)
		{
			Paths.Add(FSoftObjectPath(MakePath(LineID)));
		}
		PreloadHandle = UAssetManager::GetStreamableManager().RequestAsyncLoad(Paths);
	}

private:
	TSharedPtr<FStreamableHandle> PreloadHandle;

	FString MakePath(const FString& LineID) const
	{
		FString AssetName = LineID;
		AssetName.RemoveFromStart(TEXT("line:"));
		return FString::Printf(TEXT("%s/%s/%s.%s"), *RootPath, *LocaleCode, *AssetName, *AssetName);
	}
};

ULanguageFolderAssetProvider* AssetProvider = NewObject<ULanguageFolderAssetProvider>(this);
AssetProvider->LocaleCode = TEXT("de");
DialogueRunner->AssetProvider = AssetProvider;

The Voice Over Presenter uses the Dialogue Runner’s Asset Provider, whichever one it is, so it plays the clips this one finds.

Writing your own Line Provider

To get text from somewhere else, write a Line Provider of your own. Make a class that inherits from Yarn Line Provider, or from one of the Line Providers that come with the plugin, and override Get Localized Line. Give it to the Dialogue Runner the same way as a String Table Line Provider. See Giving the Dialogue Runner a String Table Line Provider.

#pragma once

#include "CoreMinimal.h"
#include "YarnLocalization.h"
#include "Internationalization/StringTable.h"
#include "Internationalization/StringTableCore.h"
#include "Internationalization/Internationalization.h"
#include "Internationalization/Culture.h"
#include "LocalisedStringTableLineProvider.generated.h"

UCLASS(BlueprintType, Blueprintable)
class ULocalisedStringTableLineProvider : public UYarnLineProvider
{
	GENERATED_BODY()

public:
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Dialogue")
	TObjectPtr<UStringTable> StringTable;

	virtual FYarnLocalizedLine GetLocalizedLine_Implementation(const FYarnLine& Line) override
	{
		const FString LineID = ResolveShadowLineID(Line.LineID);
		const FString Key = UYarnLocalizationLibrary::LineIDToStringTableKey(LineID);

		if (!StringTable || !StringTable->GetStringTable()->FindEntry(Key).IsValid())
		{
			return Super::GetLocalizedLine_Implementation(Line);
		}

		const FText Text = FText::FromStringTable(StringTable->GetStringTableId(), Key);
		const FString Language = FInternationalization::Get().GetCurrentLanguage()->GetName();

		FYarnLocalizedLine LocalizedLine;
		LocalizedLine.RawLine = Line;
		FinalizeLocalizedLine(LocalizedLine, Line, LineID, Text.ToString(), Language);
		return LocalizedLine;
	}
};

To get assets ready before they’re needed, override Prepare For Lines as well. The Dialogue Runner calls it with the IDs of the lines that might run, each time a node starts. By default, it does nothing.

Presenters and other code register their own markup processors with the Line Provider’s Register Marker Processor. Those are kept by the Yarn Line Provider, and FinalizeLocalizedLine() uses them, so a Line Provider of your own doesn’t need to do anything to support them.