This section covers Yarn Spinner for Godot (C#).

Yarn Spinner for Godot is the set of components and scripts that make Yarn Spinner work inside a Godot project.

In this section, you’ll learn how to install, set up, and work with Yarn Spinner for Godot.

Just getting started with Yarn Spinner for Godot? Start with in your project.

The Line Presenter and Options Presenter are handy for many situations. But your game might need to show lines and options in a particular way. When that's the case, you can write your own custom Dialogue Presenter. This gives you full control over how lines and options appear.

Creating a Dialogue Presenter

To make a Dialogue Presenter, you write a script that implements the DialoguePresenterBase interface, and add your script to a node in your scene. You can then add this node to the Dialogue Presenters list in the inspector of your scene's Dialogue Runner.

Presenting Lines and Options

By itself, an empty script implementing the DialoguePresenterBase interface will not do anything useful. To make it display lines and options, you'll need to implement certain methods.

To understand how to create a custom Dialogue Presenter, it's useful to understand how the Dialogue Runner works with content.

To get how custom Dialogue Presenters work, it helps to understand how the Dialogue Runner handles content. Yarn Spinner scripts use three types of content: lines, options, and commands. Only the first two, lines and options, need to be shown directly to the player.

When the Dialogue Runner finds lines or options, it first figures out the exact content the player needs to see. Once it has this, it sends the content to each of its Dialogue Presenters.

Your scene can have several Dialogue Presenters. And they can all do different things. For instance, you might have one Dialogue Presenter for lines, another for options, and a third for playing voice-over audio.

In compiled Yarn Spinner Scripts, Lines and Options are represented by line IDs. A line ID is a unique code for the text of a line or an option. When Yarn Spinner needs to show a line or option, it asks its Line Provider for a LocalizedLine object. This object holds the text for the line or option in the player's current language.

If you're showing a group of options, each option in that group has its own LocalizedLine.

Once a LocalizedLine is ready, the Dialogue Runner has everything it needs to show content. What happens next depends on whether it's showing a line or an option.

When Yarn Spinner comes across a line of dialogue, it calls the RunLineAsync method on every Dialogue Presenter. This method gets two things: first, the LocalizedLine from the Line Provider, and second, a LineCancellationToken. The Dialogue Presenter uses this token to know the line's status. Specifically, it checks if the player wants to speed up the line's display or move to the next line.

In Dialogue Presenters, a line is considered "presented" when the player has seen the whole line and is ready for the next one. What this means in practice varies. For example, a Dialogue Presenter playing voice-over audio might finish when all the audio has played. Another one that shows text gradually might finish when all text is visible and the UI has faded out.

The Dialogue Runner waits until all Dialogue Presenters say they've finished showing the line. Then, it moves to the next bit of dialogue.

The RunLineAsync method is asynchronous. This means a Dialogue Presenter signals it's done and ready for the next line by returning from the method.

If your game needs to pause dialogue until the player does something (like press a button), your Dialogue Presenter can do this. It simply doesn't return from the RunLineAsync method until the line cancellation token signals to advance. Because the Dialogue Runner waits for all presenters, the dialogue will pause until your presenter says to go on.

Line presentation usually isn't instant. It typically happens over a short period. So, players might want to speed this up or skip it entirely. Dialogue Presenters need to be ready for the player to ask for a line to hurry up or be skipped at any moment during presentation.

The line's state is held in the LineCancellationToken given during the RunLineAsync method. This token wraps two other Cancellation Tokens: one for advancing to the next line, and one for making the current line hurry. These tokens are linked. So, if the "next line" token is flagged, the "hurry up" token will be too. But it doesn't work the other way around.

Most times, you won't need to access these tokens directly. You can check the line's status using handy properties. IsHurryUpRequested on the token tells your custom Dialogue Presenter if the player wants the display to go faster. And IsNextLineRequested tells you if your Dialogue Presenter should skip the current line completely.

Any part of line presentation that isn't instant should use these properties. This helps decide if they should speed up or be skipped. The same LineCancellationToken is shared by all Dialogue Presenters. So, if the line's status changes, all presenters see it at the same time. Each Dialogue Presenter decides what "hurrying up" means for it; it's a signal to finish the presentation quickly.

For example, a voice-over presenter might fade out audio quickly or cut it off. A text-revealing presenter might show all remaining text at once or very rapidly. Advancing a line is a more direct signal that the player wants the dialogue to move on. You shouldn't ignore IsNextLineRequested when it's true. Presenters should clean up and finish showing the line as soon as possible if the player has asked to advance.

You can change the LineCancellationToken's state using the Dialogue Runner. It has two methods for this. RequestHurryUpLine sets the token so IsHurryUpRequested becomes true. RequestNextLine sets the IsNextLineRequested flag to true. Since the LineCancellationToken wraps two linked tokens, these methods also cancel those internal tokens. Requesting the next line also means requesting the line to hurry up. You can safely request a line advance or hurry up multiple times; it won't cause any issues.

Options are a bit different from lines. They need some kind of player input before the dialogue can go on. The Dialogue Runner needs to know which option was picked.

To manage options, Dialogue Presenters implement the RunOptionsAsync method. This method gets an array of DialogueOption objects and a cancellation token. Each DialogueOption object is an option that can be shown to the player.

When this method is called, the Dialogue Presenter uses the info in the DialogueOption objects to show choices to the player. Then it waits for player input. Once it knows which option was selected, the method should return that chosen option. The Dialogue Runner then uses this to make the selection.

If your presenter doesn't need to handle options, it can return a null value instead.

The Dialogue Runner will ignore any nulls it gets back from presenters here. The first non-null DialogueOption it receives is treated as the selected one.

When the Dialogue Runner sends options to its Dialogue Presenters, it expects only one of them to return a non-null option. If none of them return an option, the Dialogue Runner will never know what was picked. And it will wait forever, and ever, and ever.

If more than one presenter returns an option, the Dialogue Runner uses the first one it gets and ignores the others. After getting a non-null option, the Dialogue Runner cancels the cancellation token given in the method. This tells any presenters that haven't returned yet that an option has been selected. So, they can stop waiting for a selection.

To get the tags on a line, you use the Metadata property on the LocalizedLine objects you receive. Your code decides what to do with these tags.

Two example scenes are provided with Yarn Spinner for Godot: addons/YarnSpinner-Godot/Scenes/DefaultDialogueSystem.tscn and addons/YarnSpinner-Godot/Scenes/RoundedDialogueSystem.tscn.

Many projects ultimately end up needing to write their own custom Dialogue Presenter scripts to achieve the desired level of control over line and option presentation, but when first starting to integrate Yarn Spinner with your Godot game, it can be useful to start with the provided example presenters and modify their appearance and layout. These .tscn files provide a pre-configured Line Presenter, DialogueRunner, and Options Presenter.

To create your modified version, start by navigating to the .tscn file that you would like to base your presenters on in addons/YarnSpinner-Godot/Scenes/. In this example, we'll use the RoundedDialogueSystem. Right click RoundedDialogueSystem.tscn and select the option "Move/Duplicate to...". Choose the directory in your project that you would like to save your dialogue system to, then click the 'Copy' button.

You now have a duplicate of the original .tscn file. You can rename it to anything you like. Double click your duplicated file to edit it.

You can now edit the Controls in your new scene to arrange and style them to your liking. The Controls that your scene contains, such as Panels, RichTextLabels, VBoxContainers, and others, are built-in Godot UI components, so you use the same techniques that you would for any other Godot UI component to re-style them.

One way to customize the appearance of your scene is by adding or modifying StyleBox resources on the various components (visible in the inspector for each node under Theme Overrides > Styles). You can also modify the anchor points of the Controls to change their position relative to the screen's edges and center.

It's recommended to become familiar with the fundamentals of working with Godot UI components before attempting to customize your dialogue system.

There are two important kinds of files you'll use when working with Yarn Spinner for Godot:

• are files that link your Yarn Scripts together, and are used by the Dialogue Runner.

• are files that contain your written dialogue.

Dialogue Runners and Systems

The Dialogue Runner is the bridge between the dialogue that you've written in your Yarn Spinner Scripts and the other components of your game. It's a component that's responsible for loading, running and managing the contents of a Yarn Project, and for delivering the content of your Yarn Spinner Scripts to the other parts of your game, such as your user interface.

You can easily add a Dialogue Runner to your scene as part of a prefab that we supply named Dialogue System.

Dialogue Runner

The Dialogue Runner is the bridge between the dialogue that you've written in your Yarn scripts and the other components of your game. It's a component that's responsible for loading, running and managing the contents of a Yarn Project, and for delivering the content of your Yarn scripts to the other parts of your game, such as your user interface.

Setting up a Dialogue Runner is the first step in adding dialogue to your game. To use a Dialogue Runner, you add the DialogueRunner script to a node in your scene, connect it to Dialogue Presenters, and provide it with a Yarn Project to run.

When you want to start running the dialogue in your game, you call the Dialogue Runner's StartDialogue method. When you do this, the Dialogue Runner will begin delivering lines, options and commands to its Dialogue Presenters.

You can also tell it to start automatically by choosing the relevant checkbox in the Inspector.

The Dialogue Runner is designed to work with other components of Yarn Spinner for Godot:

• The contents of your dialogue are delivered to your .

• The values of are stored and retrieved using the Dialogue Presenter's .

• Content that users should see, including the text in their current language, voice over clips, and other assets, are retrieved using the Dialogue Runner's .

An Options Presenter is a Dialogue Presenter that displays options in a list, using Unity UI. When the Dialogue Runner encounters a set of options in your Yarn script, the Options Presenter will display them, wait for the user to select one of them, and then sends that choice back to the Dialogue Runner.

When this view receives options from the Dialogue Runner, it creates an instance of the Option Item you specify in the Option View Prefab property, and adds it as a child.

Inspector

When writing Yarn scripts, variables come in handy for storing state and user preferences that can persist and impact story dialogue or choices later on. When using Yarn Spinner for Godot, variables from Yarn scripts can be accessed in C# code by using the provided InMemoryVariableStorage, which acts as a simple dictionary to store variable names with their current values.

This looks something like this:

<<set $testVariable = 1>>

[Export] InMemoryVariableStorage variableStorage; // assign in the inspector of the node with your script attached.

private void MyMethod(){
    float testVariable;
    variableStorage.TryGetValue("$testVariable", out testVariable);
    variableStorage.SetValue("$testVariable", testVariable + 1);
}

This allows Yarn types String, Number and Boolean to be stored in memory, and then accessed by this wrapper class that converts them to the C# equivalents string, float and bool, ready for use in your code.

InMemoryVariableStorage is flexible and extensible, and has utilities for things such as initialising with default variables declared, or serialising to and from JSON. But what if you want to add very custom behaviour to how variables are stored? To keep values somewhere other than in memory, or add side effects to certain operations in a way that wouldn’t work by just extending this default variable storage? Well, you can define your own.

Variable Storage is made possible with the use of abstract classes. work a little bit like interfaces or protocols in other languages, in that they define a class that cannot be instantiated but can be used to make others. In this way, an abstract class is like a set of constraints for some hypothetical subclass you will define later: it can declare certain methods which your subclass must implement for it to work, and it can contain implementations or values of its own which act as defaults that you may or may not choose to override.

In Yarn Spinner for Godot, VariableStorageBehaviour is an abstract class that can be inherited from. It specifies the methods which Yarn Spinner may call at runtime, which are expected to be dealt with in your implementation:

Now, Yarn Spinner does not care how your custom VariableStorageBehaviour works beyond that. It simply assumes that you are doing something sensible, and that your subclass will provide the functionality it expects. Some of those expectations cannot be constrained in code, like the required method declarations can, so there is a level of trust here that you (as the implementer of this black box subclass which Yarn Spinner has never seen) will:

1. Actually store values somewhere. Your code will still compile if your SetValue() methods are empty or otherwise throw away the values they are given, but this will mean your TryGetValue() methods will never be able to work.

2. Actually get the right value for the given key. Your code will still compile if your TryGetValue() methods return random values from the aether, but this will make your use of these variables in your Yarn script effectively nonsensical. Likewise if you allow setting of multiple values with the same key.

So let’s assume you are not some chaos demon and you actually want to make a Variable Storage that works the way the Yarn Spinner runtime expects, so that you get variables that actually work. You need:

• A way to store values of the given types, each associated with a unique key.

• A way to get those values back, as the expected type.

• A way to get rid of all the previously stored values.

If you were a masochist, you could write a class whose SetValue() method printed out the given key and value on a piece of paper, Contains() and TryGetValue() methods that took a snapshot with a camera placed above the printer and read the values back, and a Clear() method that pushed the paper from the printer tray into a shredder. Yarn Spinner would not care, because it would still do those three things (though probably unreliably, and with some storage limitations).

Some more typical examples of things that gamemakers have wanted their variable storage to do are:

• Instead of storing variables in memory in a dictionary, store them on disk or in a database.

• Instead of just setting values in the Variable Storage when asked, also update some corresponding variables on the C# side or emit a signal to notify other components that a value has changed.

• Instead of simply getting and setting values, run them via some sanitation or transformation, or even interface with an external API.

So let’s break down how you would go about implementing one of those more sensible ideas...

In this example, let’s replace the default Variable Storage implementation with one that stores values in a SQL database. The example code shown makes use of the library—an open source .Net API for SQL—for the creation of a database and tables, but uses vanilla SQL query strings in place of the convenience bindings which are specific to that library.

To begin, we need to make a custom class for our new Variable Storage, which should inherit from the VariableStorageBehaviour abstract class.

If you are following along, your IDE will probably complain at this point, because this empty class does not fulfil the requirements defined by the abstract superclass. To conform, we need at least the six methods listed earlier.

So let’s have a think about how each of these would need to work, given a backing of SQL. We need to be able to insert values into tables, check if a value exists in tables with the given key, return the corresponding value for a given key, and remove all entries from tables.

But first, before any values can be set, the database needs to already exist. Set up like this conventionally occurs in the _Ready() method:

Next, to create the tables we need to store values in, we need to declare a class that represents a single entry. Its class name will becomes the table name by default, and its field names and types will become the column names and types. Because each column can only hold one type, we’ll need one table for each type.

These classes would look something like this:

The column that will be used to reference or fetch values—and is thus required to be unique within that table—is specified by the [PrimaryKey] decorator.

Then, to create an empty table in the database, we can call the database connector’s CreateTable() method with the class we want to represent.

Now we can begin filling out our empty method declarations. Beginning with the easiest, Clear() is just a matter of telling each table in the database to remove all its entries. The query for this is DELETE * FROM TableName, where the * means all entries. Executing a query on the database is as simple as calling Execute() on the database connector with a string parameter of the desired query.

Now to the fiddliest method, TryGetValue() is the method that needs to figure out whether a value exists for the given key and, if so, return it as the correct type. This requires a little bit of .

First we need to do some switching of which table we need to look for the value in:

Then, within each, we should look for that key within the corresponding table. To return only the value from any row that matches our variable name we specify Select ColumnName FROM TableName WHERE (conditions to match).

At runtime, your variable storage will also be called by YarnSpinner with a type of IConvertible for the generic type T. In this case, you will not know the expected type of the variable, so example code is provided below to search all three variable types for the given variable for that cas.e

Next, before we can begin inserting values into tables, we first want to make sure a value doesn’t already exist for that key in another table. We can do this by creating a utility method that uses a lookup query to check if a value exists with that key in a specific table. This can take advantage of our TryGetValue() implementation:

...which can then also be used as the basis for our Contains() method, by checking them all:

This utility method then also comes in handy when defining the SetValue() methods, which would each look something like this:

And lo! We should now have a fully functioning SQL-backed custom Variable Storage for Yarn Spinner. Simply replace the Variable Storage component on the DialogueRunner node in your scene to put your custom implementation to work.

As far as Yarn Spinner is concerned, this should behave exactly as the provided InMemoryVariableStorage does at runtime, even though the entire storage model and behaviour has changed.

Using this simple method of overriding methods in the inbuilt VariableStorageBehaviour abstract class, you can make a custom Variable Storage backed by virtually anything to suit your needs!

Check out the or ask the community in the !

📦 Installation for Godot

Download a copy of the latest version of Yarn Spinner for Godot from the GitHub repository, or clone the repository somewhere.

Locate the addons/ directory in your new local copy of Yarn Spinner for Godot:

Put a copy of this directory into your new Godot project, either by dragging the folder in your file manager (e.g. Finder or Explorer) into the folder of the Godot project, or by dragging from your file manager into the FileSystem dock of your Godot project:

Next, choose the Project menu -> Tools -> C# -> Create C# solution. If the C# option isn't available in the Tools menu, it probably means that you don't have the .NET version of Godot: in that case, install it and reopen the project. Once clicked, it will create a C# project for you. We have to do this to trigger the creation of the .csproj file, which is necessary to let Godot know about the Yarn Spinner plugin.

Next, open the project folder in Visual Studio Code. In the sidebar of VS Code, the .csproj file and add the following line to it, inside the <Project> </Project> tags, but not inside an <ItemGroup> or <PropertyGroup>:

Your brand new project should look something like this in VSCode:

Save the tweaked .csproj file and return to Godot, everything is almost ready to go. Click the Build button in the very top right-hand corner of the Godot window. This will trigger a build of the C# solution for the project, which is required to make Godot aware of Yarn Spinner for Godot.

Once the build is complete, open the Project menu -> Project Settings, change to the Plugins tab, and tick the enabled box next to the Yarn Spinner for Godot plugin:

With that, you're ready to go!

Variable Storage components are responsible for storing and retrieving the values of variables in your Yarn scripts. When a Yarn script needs to get the value of a variable, it asks the Variable Storage for it; when a Yarn script sets the value of a variable, the Variable Storage is given the value.

Each game has different requirements for how variables are stored, which means that Yarn Spinner doesn't make any assumptions how the information is actually stored on disk. Instead, you can create your own custom Variable Storage script that implements the methods that Yarn Spinner needs.

If you don't connect a Variable Storage to your Dialogue Runner, it will create an In-Memory Variable Storage when the game starts, and use that.

Markup Palettes provide a means of lightly theming your lines without requiring any code. Markup palettes use a script called the PaletteMarkerProcessor to replace markup with your desired content. The code for the PaletteMarkerProcessor is a good starting point for more advanced customization for your game.

In Godot, Markup Palettes are implemented as a custom C# Resource.

To get started, create a Markup Palette by selecting the menu item Project > Tools > YarnSpinner > Create Markup Palette.

Select a directory and filename to save your Markup Palette to.

Then, find your new palette in the Filesystem panel and double click it to open the inspector.

Basic Markers

Basic Markers in a markup palette are a shortcut to defining markup tags that change only the style of text within a markup tag, such as changing its color or whether the text is bold. These are stored in the palette in an array of BasicMarker C# resources.

You can add as many BasicMarker instances as you want to the palette's Basic Markers section, and change the Color field on the BasicMarker to assign the color for the tag. You can remove markers by clicking the delete button next to the BasicMarker resource.

The Custom Markers array in the Markup Palette holds CustomMarker resources which define text that will replace the beginning and end of a markup tag. Typically you will use this to insert BBCode into your line text to do things like display images or other effects.

Custom Markers are more flexible than Basic Markers, but they require you to write the replacement content by hand rather than using configured preset options.

You can also specify a marker offset on each CustomMarker instance, which is used to compensate for inserting text into a line's content via replacement markup. If you use a CustomMarker, and other Yarn markup in the line isn't replaced quite as you expect, try setting the Marker Offset based on how many characters you are inserting into the line.

The PaletteMarkerProcessor is a script which takes your Markup Palette resource and uses it to replace any of your custom markup tags with your configured replacements. It reads each tag defined in Basic Markers and Custom Markers and registers replacements with your Line Provider. Since the replacement will be performed before any of your presenters receive the text, this system works with the built in Line Presenter and Options Presenter, as well as any custom presenter you might create.

The replacements produced by the PaletteMarkerProcessor for both Basic Markers and Custom Markers is pre-defined and always the same for a given markup tag. If your markup replacement has to be more dynamic, or otherwise integrate with the rest of your game's code, you can use the PaletteMarkerProcessor as inspiration for how to write your own custom ReplacementMarkupHandler subclass. The Markup sample in the Yarn Spinner for Godot GitHub repository also contains an example of making another custom ReplacementMarkupHandler.

To use your markup palette with these presenters, first add an instance of the PaletteMarkerProcessor node to your scene. Then, drag and drop the markup palette resource into the Palette field of the PaletteMarkerProcessor's inspector, and also set the Line Provider in its inspector to the Line Provider instance in your scene (likely a TextLineProvider unless you have created a custom line provider script).

Then, when you use markup tags in your dialogue that match tags defined in your markup palette, the presenters will automatically replace your markup tags with the text styles and other replacements that you configured.

To see markup palettes in action, try out the in the Yarn Spinner for Godot repository.

This sample highlights:

• Using markup palettes to color text

• Using markup in dialogue

• Using action markup to trigger animations

• Displaying images in your presenter text via BBCode

A Dialogue Presenter is a component that receives content from a Dialogue Runner, and presents it to the player. Dialogue Presenters are how the player sees your game's lines of dialogue, and how they select choices in the dialogue.

A Dialogue Runner can have multiple Dialogue Presenters. For example, in most situations, you'll have a Dialogue Presenter that's designed to display lines of dialogue and another that's in charge of displaying options to the player.

Every game's needs are different, a Dialogue Presenter is designed to be extremely customisable, and you can create your own Dialogue Presenters to suit the needs of your game.

Because there are common patterns of how games work with dialogue, Yarn Spinner for Unity comes with some pre-built Dialogue Presenters that handle common use cases:

• Line Presenter is a Dialogue Presenter that displays a single line of dialogue in a text box that's inside a canvas, and shows a button that the user can click to proceed.

• Options Presenter is a Dialogue Presenter that displays a collection of options in a list.

Line Providers are components that are responsible for taking the Line objects that the produces, and fetches the appropriate localized content for that line. Line Providers produce LocalizedLine objects, which are sent to the Dialogue Runner's .

When a Yarn Spinner Script runs, the Dialogue Runner produces Line objects. These objects contain information about the line, but not the text of the line itself. This is because it's the responsibility of the game to load the user-facing parts of the line, including the text of the line in the player's current language setting, as well as any other assets that may be needed to present the line, such as audio files for voiceove

Yarn Spinner for Godot comes with a built-in which that fetches the text of a line, given a language to use.

The In-Memory Variable Storage component is a Variable Storage component that stores all variables in memory. These variables are erased when the game stops.

A Yarn Project is a file that links multiple Yarn scripts together. Yarn projects are how Dialogue Runners work with your content.

Creating a New Yarn Project

To create a new Yarn Project, follow these steps:

• Open the Project menu, and choose Tools -> YarnSpinner -> Yarn Project.

• Godot will open a dialogue where you can choose the directory your Yarn Project will be saved, and its filename. Choose a name and directory, and press the Save button.

Adding Yarn scripts to a Yarn Project

On their own, a Yarn Project doesn't do anything. In order to be useful, you need to add Yarn scripts to it.

Yarn Projects include all Yarn Scripts that the project finds in the Source Files directory. By default, that means all Yarn Scripts in the same directory as the Yarn Project, and all of that directory's children.

When you add a Yarn Script to the same folder as a Yarn Project, it will automatically be included in the Yarn Project. When you make changes to the script, the Yarn Project will automatically be re-imported.

You can change the locations that a Yarn Project looks for Yarn Scripts by modifying the Source Files setting. Each entry in the Source Files setting is a search pattern.

You can add as many entries to the Source Files field as you like. If a file is matched by multiple patterns, it will only be included once.

A Yarn script can be included in more than one Yarn Project.

When you write a Yarn script, you write it in a specific human language. This is referred to as the 'base' language of the script. It's called the base language because it's the one you start with, and the one you translate into other languages.

You can set the base language of a Yarn Project in the Inspector by changing the Base Language setting.

If you want to translate your scripts into another language, you add a new locale code to your Yarn Project. To learn about this process, see .

Yarn Projects are used by Dialogue Runners. When a Dialogue Runner is told to start running dialogue, it reads it from the Yarn Project it's been provided.

Yarn Spinner Godot provides functionality for running your dialogue in languages other than your base language.

To add a new language to your Yarn Project, open the inspector for the project in godot.

Find the text entry labeled Localization CSVs. Enter the locale code for the language you would like to add, then click the Add button to the right of the text entry.

This will add a new row beneath the text entry that maps the locale code you added to a path where the localization CSV file will be stored. Initially, there will be no value for the path, and the inspector will display (none) next to the new locale.

Click the Browse button next to (none) to browse the file system of your project and enter a directory and file name to save the CSV file to.

Once you have set a path to save your CSV to, from that point on you can click the button labeled "Update Localizations" in your project to create or update the CSV file.

The CSV file follows this format, with fields providing context for each line of dialogue to assist in localization.

By default, the CSV file will be marked as "Keep File (No Import)" in the Import panel of the Godot editor. Make sure to keep this import preset setting, because the CSV format does not match Godot's default localization CSV format due to the additional context columns like original, lineNumber, and file.

To enter the localized content for a line, enter it in the text column of the row in the CSV for that line and language. Whenever you press the "Update Localizations" button, Yarn Spinner for Godot will generate or update a .translation file in the same directory as the CSV file. These are Godot files.

Make sure any .translation files that you want to use in-game are .

Once you have generated .translation files and added them to your project. You can control which language your dialogue will display in by changing the value of the textLanguageCode in the TextLineProvider in your dialogue UI. The provided TextLineProvider script uses the Godot Tr() method to retrieve the localized line text.

If you want to have greater control over which locale code is active, or localize your content by different means and provide that localized text to your DialogueRunner, you can also implement a custom subclass of the LineProviderBehaviour abstract class rather than using the default TextLineProvider.

A Yarn script is a text file containing your dialogue.

Creating a New File

To create a new Yarn script in Godot, follow these steps:

• Open the Project menu, and choose Tools > YarnSpinner -> Yarn Script.

• Choose a directory and filename for the new Yarn script in the dialog that appears.

The new file that you've just created will contain a single node, which has the same name as the file.

Editing Yarn Scripts

You can edit .yarn scripts with the text editor of your choice. To open your editor from within Godot, ensure that you have associated .yarn files on your computer with your desired editor. Then, right click a .yarn script in the Filesystem panel and click Edit in External Program. When you save your changes and return to Godot, it will be re-compiled.

Every game's data storage requirements are different. For this reason, Yarn Spinner is designed to make it straightforward to create your own custom component for managing how Yarn scripts store and load variables in ways that work with the other parts of your game.

Custom Variable Storage components are subclasses of the abstract class VariableStorageBehaviour. To implement your own, you need to implement the following methods:

For a tutorial on how to build an entirely custom variable storage system, see .

Defining Commands

You can define your own commands, which allow the scripts you write in Yarn Spinner to control parts of the game that you've built.

In Godot, there are two ways to add new commands to Yarn Spinner: automatically, via the YarnCommand attribute, or manually, using the DialogueRunner's AddCommandHandler method.

If you are using the Yarn Spinner Extension for Visual Studio Code, commands added with the YarnCommand attribute will automatically be found by the extension. For commands and functions that you add via AddCommandHandler or AddFunction, see here for information about exposing your commands and functions to the extension.

The YarnCommand attribute

The YarnCommand attribute lets you expose methods on a Node to Yarn Spinner.

When you add the YarnCommand attribute to a method, you specify what name the command should have in Yarn scripts. You can then use that name as a command.

If the method is not static, you call it with the name of the node you want the command to run on.

For example, if you have a script called CharacterMovement that has a method Leap, you can add a YarnCommand attribute to it to make it available to your Yarn scripts:

If you save this in a file called CharacterMovement.cs, create a new node called MyCharacter, and add the CharacterMovement script on that node, you can run this code in your Yarn scripts like this:

If the method is static, you call it directly, without providing a node name. For example:

If you save this in a file called FadeCamera.cs, you can run this code in your Yarn scripts like this:

You can also use methods that take parameters. Yarn Spinner will take the parameters that you provide, and convert them to the appropriate type.

Methods that are used with YarnCommand may take the following kinds of parameters:

You can also add new commands directly to a Dialogue Runner, using the AddCommandHandler method.

AddCommandHandler takes two parameters: the name of the command as it should be used in Yarn Spinner, and a method to call when the function is run.

If you want to add a command using AddCommandHandler that takes parameters, you must list the types of those parameters.

For example, to create a command that makes the main camera look at an object, create a new C# script in Godot with the following code:

Add this script to any node, and it will register the free_node in the Dialogue Runner you attach.

You can then call this method like this:

We provide two different means of handling commands in Yarn Spinner: the AddCommandHandler method and the YarnCommand attribute. Both of these provide effectively the same functionality, and under-the-hood the YarnCommand attribute is even a wrapper around the AddCommandHandler call. So if there are two different ways to achieve the same thing when should you use each one?

• The YarnCommand attribute allows you to tag specific methods as being a command, Yarn Spinner will then automatically handle the binding and connection of the command in text to the method call in C#.

• AddCommandHandler method allows you to manually connect a method in C# to a command in Yarn, letting you set the name of the command and which method it connects to, giving you the control over the binding.

Most of the time, we feel that the YarnCommand attribute is the better option, because it is easier to use, and maps well to how we find most people use commands - that is, calling specific methods on specific Nodes.

This convenience, however, does come at a cost of flexibility, because your YarnCommands either need to be on static methods, or follow specific calling conventions, which may not be what you need or want.

The YarnCommand attribute works best in our opinion when your commands are calling into specific Nodes in your scene, which means that it works very well for moving, animating, or changing characters and items in a scene.

For larger gameplay changing moments, such as loading new scenes, moving between dialogue and the rest of your game, or for more global events like saving the game or unlocking an achievement, the AddCommandHandler method is better.

can be commands. If you register a command, either using the YarnCommand attribute, or the AddCommandHandler method, and the method you're using it with returns a Task, Yarn Spinner will pause execution of your dialogue when the command is called.

For example, here's how you'd write your own custom implementation of <<wait>>. (You don't have to do this in your own games, because <<wait>> is already added for you, but this example shows you how you'd do it yourself.)

This new method can be called like this:

are units of code that Yarn scripts can call to receive a value.

In addition to the that come with Yarn Spinner, you can create your own.

To create a function, you use the YarnFunction attribute, or the AddFunction method on a Dialogue Runner. These work very similarly to commands, but with two important distinctions:

1. Functions must return a value.

2. Functions registered via the YarnFunction attribute are required to be static.

For example, here's a custom function that adds two numbers together:

When this code has been added to your project, you can use it in any expression, like an if statement, or inside a line:

Yarn functions can return the following types of values:

• string

• int

• float

After following the instructions to install the plugin, in your Godot project, click the Instantiate Child Scene button:

And navigate into the addons/YarnSpinner-Godot/Scenes folder of your project, and choose the DefaultDialogueSystem.tscn file as the scene to instantiate:

Then, right click the new scene in the Scene dock, and check the "Editable Children" option. This will allow you to view all of the components that make up the default dialogue system, and set options on them in the inspector dock.

Your Scene dock will look like this showing a node hierarchy that's entirely based on the DefaultDialogueSystem.tscn scene that you instantiated:

Next, create a new Yarn Project using the menu Tools > YarnSpinner >Create Yarn Project:

Then choose a directory to save your new YarnProject in. For example, you can save it to the root of your project. Name the new Yarn Project FirstProject.yarnproject:

Next, create a new Yarn script (a file with a .yarn extension) by using the menu Tools > YarnSpinner >Create Yarn Script. In the resulting "Create a new Yarn Script" window, set the File name to MyStory.yarn, and click the Save button::

It may take a moment, but Godot will import your new .yarn file, and it will appear in the FileSystem dock. When it's appeared, double-click on the Yarn Project, FirstProject.yarnproject in the FileSystem dock and look to the Inspector, making sure that res://MyStory.yarn is in the list of Source Scripts, which are the Yarn scripts that compromise the new project:

Next, open the MyStory.yarn file in VS Code, and add the following Yarn script to it, before saving it and returning to Godot:

Select the DialogueRunner node in the Scene dock, and look to the Inspector. Selecting "Editable Children" earlier in the guide is what will allow you to see the DialogueRunner node and edit its options. Assign the Yarn Project you created to the DialogueRunner by dragging the FirstProject.tres Yarn Project from the FileSystem dock into the Yarn Project slot of the Inspector:

Finally, enter Start as the Start Node, and tick the box next to Starts Automatically:

Save your scene as Demo.tscn, and run the game. At this point, you can play your project, and step through the dialogue in the default Yarn Spinner for Godot Line Presenter and Options Presenter:

With that, we've reached the end of our beginner's guide. You're ready go forth and build games with Yarn Spinner! You're also equipped to work with the rest of the documentations here! Don't forget to to chat with other Yarn Spinner users, the Yarn Spinner team, seek help, and share your work.

Text Line Provider is a Line Provider that fetches localized text for a line of dialogue, given the user's language.

Make sure to set the Yarn Project in the inspector

Inspector

Line View is a Dialogue Presenter that displays a single line of dialogue with a set of components parented to a Godot Control. When the Dialogue Runner encounters a line in your Yarn Script, the Line View will display it, wait for the user to indicate they're done reading it, and then dismiss it.

Showing the Character's Name

If a line contains a character's name at the start, Line View can be configured to show the name in a separate text view to the line text itself. If the Character Name Text property is connected to a RichTextLabel, then the character's name will appear in this object.

If you don't attach a RichTextLabel to the Character Name Text property, you can choose to either show the character name as part of the line (that is, in the Line Text view), or don't show it all.

Presenting Lines with Visual Effects

Line View can be configured to use visual effects when presenting lines.

• You can choose to have the Line View fade in when a line appears, and fade out when the line is dismissed.

• You can choose to have the text of the line appear, one letter at a time, with a "typewriter" effect.

The Dialogue Runner will automatically proceed to the next piece of content once all dialogue presenters have reported that they've finished with a line.

If the 'Auto Advance' option on a Line View is turned on, then the Line View will signal that it's done with a line as soon as all visual effects have finished.

If 'Auto Advance' is turned off, then the Line View will not signal that it's done when the effects have finished, and the line's delivery will stop. To make the Line View finish up, you can call the UserRequestedViewAdvancement method, which tells the Line View that the user wants to proceed. The built-in Dialogue System scene comes set up with a 'Continue' button that calls this method. You can also call this method from code.