1 of 100

Yarn Spinner 2.1

Start Here

Learn what you need to to get started with Yarn Spinner

Welcome to Yarn Spinner!

is the friendly tool for writing dialogue in games. It's easy for writers to use, and has powerful features for programmers.

Yarn Spinner is a dialogue system that lets you write interactive conversations in a simple, screenplay-like format, which can be loaded into your game and run.

When a conversation is running, Yarn Spinner sends your game lines of dialogue to show, options to let the player choose from, and commands to make things happen in your scene.

Yarn Spinner has been used in a number of critically acclaimed games, including , , , and many more.

It's free to download and use for free and commercial games, and is open source under the terms of the .

Yarn Spinner 2.1 is our latest release!

This documentation is still in active development. If you see an issue, please .

Yarn Spinner is made up of two things:

Yarn files that contain the script for your game, and;
The Yarn Spinner framework for your chosen game engine or method of delivery.

This documentation is for Yarn Spinner 2.1. You can find the old Yarn Spinner 1.0 documentation , if you still need it.

To use Yarn Spinner, you will need:

An editor to write and edit .yarn scripts with. We recommend using the official Yarn Spinner Visual Studio Code extension, together with Visual Studio Code.
- You can find details on installing VS Code and the official Yarn Spinner Visual Studio Code Extension here:
A copy of Yarn Spinner for your game engine of choice. Currently, Yarn Spinner supports Unity, so you'll need Yarn Spinner Unity.
- You can learn more about Yarn Spinner Unity here:
A .yarn script (or a few of them). These will be the narrative, or bits of narrative, that Yarn Spinner uses to display and deliver your dialogue.
- You can learn more about writing in Yarn here:

Yarn Spinner currently only officially supports Unity. There are community projects for other game engines, and we're officially working on more. Stay tuned for updates.

You can also learn more about the various , as well as here, if you'd like.

If you'd like to join the wider Yarn Spinner community, we also have a .

Writing Your Dialogue

Editing with VS Code

Learn about writing with the Yarn Spinner Visual Studio Code Extension.

The preferred way of writing your Yarn Spinner code is with the official Yarn Spinner Visual Studio Code Extension.

The official extension adds syntax highlight to VS Code's text editor, as well as a graph view that displays the nodes, and relationships between the nodes.

If you've never used to Visual Studio Code before, head to their official website and install it for your operating system and platform, and then continue to Installing the Extension.

Visual Studio Code is a powerful, flexible, open source code editor for Windows, macOS, and Linux. It supports extensions, which allow it to perform a wide range of useful tasks. The Yarn Spinner Extension is one of these.

Installing the Extension

If you're already familiar with VS Code and VS Code extensions, you can just install the extension secretlab.yarn-spinner and you'll be ready to go.

Once you've got Visual Studio Code (often abbreviated to "VS Code", or "Code") installed on your system, you'll want to install the Yarn Spinner extension. To install the Yarn Spinner Extension:

Launch Visual Studio Code.
Open the Extensions view. To do this, select the blocks symbol from the left-hand sidebar, or press Command+Shift+K on macOS, or Control+Shift+X on Windows or Linux.
Search for the Yarn Spinner Extension. With the Extensions view open, type "Yarn Spinner" into the search field.
Install the Extension. Once the results have loaded, click "Install" next to the Secret Lab-provided Yarn Spinner Extension.

That's all you need to do to install the extension! You're ready to write and edit Yarn scripts with Visual Studio Code.

Writing Yarn in VS Code

With the Yarn Spinner Visual Studio Code Extension installed, you can make new Yarn files, and edit existing ones, right inside the VS Code editor.

Making a new .yarn file

You can use the File menu -> New file command to make a new empty file. Simply save the file with a .yarn extension to activate the Yarn Spinner Extension features.

Opening an existing .yarn file

You can open any existing .yarn file, or collection of .yarn files, using VS Code:

With a .yarn file open, you can edit it in the text editor. The chosen .yarn file(s) will open, and you'll be able to work with them, edit them, and save them as needed:

You can show and hide the Graph View. If you click the "Show Graph" button, in the top right-hand corner, the Graph View will appear:

You can use the "Add Node" button to add new nodes. New nodes will appear in the Graph View, and in the text editor:

Links (for example, using the jump commands) between nodes will be visualised in the Graph View. You can use the edit button on a node in the Graph View to jump to the appropriate location in the text editor, and you can rearrange the nodes visually in the Graph View for ease of understanding the relationships between areas of your script:

You can also use the "Jump to Node" button to move to a specific node in the Graph View. This allows you to easily move between areas of your text script. Nodes in the graph view can be rearranged for convenience; this won't impact the text version of the yarn script other than updating the position (below the node title).

Writing in Yarn

Yarn Spinner is a tool for writers. In this section, you'll the syntax of Yarn, how to write Yarn scripts for use in your game. You'll also learn how to use the various tools that are available for creating your content.

You'll need an editor before you can write Yarn scripts, so we recommend checking out Editing with VS Code before going too far.

Flow Control

`if` statements

In addition to storing information, variables are useful for controlling what's shown to the player. To do this, you use if statements.

An if statement allows you to control whether a collection of content is shown or not. When you write an if statement, you provide an expression, which is checked; if that expression evaluates to a "true" value, then all of the content in between the <<if>> and <<endif>> statements are run.

For example, consider the following code:

This example will set a variable, $gold_amount, to 5. It will then show the line "I'd like to buy a pie!", and before it continues, it will check to see if $gold_amount is less than 10. If that's the case (which it will be!), the line "Well, you can't afford one!" will run.

`elseif` and `else`

You can use the elseif and else statements to handle different situations in an if statement.

An elseif statement has an expression that gets checked if the if statement, or any previous elseif statements, don't run.

An else statement doesn't have an expression, and runs

For example:

This script will show different lines depending on the value of $gold_amount. The checks are done from top to bottom, which means that in order for an elseif or else to run, all of the checks above it have to have failed.

If it's less than 10, the line "Well, you can't afford one!" will run.
Otherwise, if it's less than 15, the line "You can almost afford one!" will run.
Otherwise, the line "Here you go!" will run.

The expression used in an if and elseif statement must result in a boolean value (that is, true or false.) For exame,<<if 1>> isn't allowed, but <<if 1 == 1>> is.

Conditional Options

When presenting options to the player, you may want to make some options not available. You can do this by adding a condition to the option.

For example, if you have a variable that tracks your player's "reputation points", called $reputation, you might want to make certain options only available if the value of $reputation is high enough.

Conditions on options are done by adding an if statement to the end of the option. They look like this:

When Yarn Spinner runs this collection of options, it will check the expression inside the if statement. If the expression is false, then the option will be marked as unavailable.

Yarn Spinner always delivers every option in an option group to the game; it's up to the game to decide what to do with options that are marked as unavailable.

For example, an unavailable option might be shown to the user, but not selectable, so that the user can see that they could have been able to say that if circumstances had been different.

Now that you know how to work with , , and , there's one last part of the Yarn language to learn about: commands.

Commands

In Yarn Spinner, you can send instructions to your game through commands. Commands look like this:

Commands are sent to your game's , just like lines and options are. Commands are not shown to the player directly; instead, they're used for things like stage directions.

Yarn Spinner comes with some built-in commands; however, to get the most usefulness out of them, you'll want to that make your game do what you need to.

Built-in Commands

There are two built-in commands in Yarn Spinner: wait, and stop.

`wait`

The wait command pauses the dialogue for a specified number of seconds, and then resumes. You can use integers (whole numbers), or decimals.

`stop`

The stop command immediately ends the dialogue, as though the game had reached the end of a node. Use this if you need to leave a conversation in the middle of an if statement, or a shortcut option.

Making Your Own Commands

You can create your own commands, so that your scripts can . For more information on how to create them in Unity games, see .

Upgrading Yarn Scripts

Upgrading your Yarn Spinner 1.x scripts to Yarn Spinner 2.x is easy.

The Yarn Spinner Console (ysc) can upgrade your older .yarn scripts to the latest syntax.

The Yarn Spinner Console (ysc) is in heavy development, and is likely to have its own complete section here, in the documentation, before long. Until then, find further initial documentation via .

To upgrade your scripts:

Install the version of Yarn Spinner Console that matches your version of Yarn Spinner. You can do this via the . Choose Releases in the sidebar, and download the appropriate binary for your platform. If you just want the latest release, you can find it .

Run the upgrader on your scripts. To upgrade, you must run ysc on your command-line/terminal with the upgrade parameter and a path to a yarn file:

You can also run the upgrade on multiple scripts at once. To do this, you can pass in as many .yarn files as you want:

By default, ysc will replace the existing .yarn files you've passed in, as part of the upgrade. If you don't want it to do this, either make sure you have a backup, or pass in the --output-directory option, after the upgrade parameter. For example:

Working With Unity

Overview

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

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

Yarn Spinner for Unity works with Unity version 2019.4 and later.

Quick Start

Quickly get started with a simple scene.

Want to use Yarn Spinner in a new scene right away? Follow these steps.

Setting Up A Demo Scene

Create a new empty Unity project, by following .
Install Yarn Spinner into the project, by following the instructions in .
Add the Dialogue System prefab to the scene:
1. In the Project pane, scroll down to the Yarn Spinner folder. You'll find it in the Packages section.
2. Inside the Yarn Spinner folder, open the Prefabs folder, and locate the Dialogue System prefab.
3. Drag the Dialogue System into your scene.
Create a new , by opening the Assets menu and choosing Create -> Yarn Spinner -> Yarn Script. Name the new file HelloYarn.
Open the new Yarn script by double-clicking it.
1. Select all of the text in the file, and delete it.
2. Copy the text below, and paste it into the file.

You can learn about our recommended editor, Visual Studio Code with the official Yarn Spinner Extension at: .

Save the file and return to Unity.
Create a new that uses this script, by selecting the HelloYarn file, and clicking the Create New Yarn Project button in the Inspector. This will create a new Yarn Project called Project.
Attach the Yarn Project to the Dialogue Runner, by selecting the Dialogue Runner in the Hierarchy, and dragging the Project into the Yarn Project field.
Play the game by clicking the Play button at the top of the window. Your dialogue will appear!

Importing Yarn Files

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

Yarn Scripts are files that contain your written dialogue.
Yarn Projects are files that link all of your scripts together, and are used by the Dialogue Runner.

Yarn Scripts

Learn about Yarn scripts, which are the assets that contain the dialogue you write.

A Yarn script is a text file containing your dialogue.

Yarn scripts need to be added to a Yarn Project in order to be used in your game.

Creating a New File

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

Open the Assets menu, and choose Yarn Spinner -> Yarn Script.
Unity will create a new file. Type in a name for the file, and press return.

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

Creating a Yarn Script in Unity is exactly the same as creating a .yarn file externally (i.e. in macOS Finder or Windows Explorer), and dragging it into the Assets folder of your Unity project, or directly into the Project pane (where the new Yarn Script we created through the process above appeared) in Unity.

Editing Yarn Scripts

To edit a Yarn script, double-click it in Unity. The file will open in your editor. When you save your changes and return to Unity, it will be re-compiled.

You can learn about our recommended editor, Visual Studio Code with the official Yarn Spinner Extension at: Editing with VS Code.

Components

Learn about the Unity components that you use when working with Yarn Spinner for Unity.

Yarn Spinner for Unity is made up of a number of components. The most important of these are the Dialogue Runner, which loads and runs your scripts, and the Dialogue Views that show content to your player.

In this section, you'll learn about how to work with each of these.

Dialogue Views

Learn about Dialogue Views, which present dialogue content to the user.

A Dialogue View is a kind of component that receives content from a Dialogue Runner, and presents it to the player. Dialogue Views 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 Views. For example, you might have one Dialogue View that's designed to display lines of dialogue, and another that's in charge of displaying options to the player.

Because every game's needs are different, a Dialogue View is designed to be extremely customisable, and you can create your own custom dialogue views to suit the needs of your game.

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

Line View is a Dialogue View 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.
Option List View is a Dialogue View that displays a collection of options in a list.

Options List View

Learn about Options List View, a Dialogue View that displays a list dialogue options.

Options List View is a that presents a list of options in a list.

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

Options List View only displays options, and doesn't display lines. You can use an additional Dialogue View to handle these, like a or a custom Dialogue View of your own.

Inspector

Property

Description

Option View

Learn about Options View, a component used to display an option in an Options List View.

An Option View is an object that the Options List View uses when presenting options. When the Dialogue Runner delivers options to your game, Options List View will create an Option View for each option that could be selected.

When the Option View is pressed, the Options List View will notify the Dialogue Runner of the user's selection.

Inspector

Property

Description

Text

A TextMeshPro text object that will display the text of the line.

Show Character Name

If this is turned on, the Text component will show any character name present in the option. If this is turned off, the character name will not be included.

Variable Storage

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 have a game save system, you can use the component. This is a simple Variable Storage component that's built into Yarn Spinner.

The In-Memory Variable Storage stores everything in memory; when the game ends, all variables that have been stored are erased.

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.

In-Memory Variable Storage

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.

The In-Memory Variable Storage component is intended to be a useful tool for getting started, and to be replaced with a custom variable storage that meets your game's needs.

However, if your game has no need to save and restore game state, then this class can be used in your final game, too.

Inspector

Property

Description

Debug Text View

A Unity UI Text object that will display a summary of the variables that have been stored in this component. If this is not set, this property will not be used.

You can use this property to display a debug summary of your variables at run-time in your games.

Debug Variables

This area of the Inspector shows a summary of the variables. This works similarly to the Debug Text View property, but the summary is only ever shown in the Editor, and it doesn't require any setup.

Custom Variable Storage Components

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:

Line Provider

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

When a Yarn script runs, the Dialogue Runne 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 voiceover.)

Yarn Spinner comes with two built-in types of line providers:

is a Line Provider that fetches the text of a line, given a language to use.
is a Line Provider that fetches the text of a line as well as an , given languages to use.

If you don't set up a Line Provider for a Dialogue Runner, it will automatically create a Text Line Provider, and configure it to use the user's current language.

Text Line Provider

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

Inspector

Property

Description

Audio Line Provider

Audio Line Provider is a Line Provider that fetches localized text for a line of dialogue, as well as a localized AudioClip.

Audio Line Provider will automatically use Addressable Assets, if the Addressables package is installed in your Unity project and

Inspector

Property

Description

Text Language Code

The language that the Audio Line Provider should use to fetch localised text for.

Audio Language

The language that the Audio Line Provider should use to fetch localised audio clips for.

Unity Sample Projects

Guides

About

The Team

The Yarn Spinner project was started by Jon Manning, co-founder of .

Yarn Spinner is now maintained by , together with freelance game developer , Secret Lab colleague , and researcher and freelancer , together with a huge community of open source contributors. ❤️

You can .

Yarn Spinner Timeline

v0.9 was the first public release on 9 October 2015
v1.0 was released on 8 January 2020
v2.0 was released on 20 December 2021
v2.1 was released on 17 February 2022

About Secret Lab

is an independent games and creative technology studio located in Hobart, Australia.

We’ve been enthusiastically building video games, apps, and technology to showcase culture, history, arts, and narrative experiences since 2008.

We’re the proud creators of Yarn Spinner, and are currently working on the BAFTA- and IGF-winning Night in the Woods.

You can hire us to build your video games, interactive experiences, fancy apps, or to add features to, or support your integration of Yarn Spinner.

GitHub Repositories

There are several official Yarn Spinner GitHub repositories:

Yarn Spinner Core — YarnSpinnerTool/YarnSpinner
- This is the core of Yarn Spinner, and all other elements depend on this in some way.
Yarn Spinner Unity — YarnSpinnerTool/YarnSpinner-Unity
- This is the components of Yarn Spinner that relate to the Unity integration
Yarn Spinner Console (ysc) — YarynSpinnerTool/YarnSpinner-Console
- The Yarn Spinner command-line tool, for working with .yarn files on the command-line.
Visual Studio Code Extension — YarnSpinnerTool/VSCodeExtension
- This is the VS Code extension for Yarn Spinner.

We also host several other public GitHub repositories related to Yarn Spinner:

Experimental Editor - YarnSpinnerTool/ExperimentalYarnSpinnerEditor
- This is an experimental editor created by a student team. It may, or may not, be maintainted in the future. It targets Yarn Spinner 2.0.
Classic Yarn Editor - YarnSpinnerTool/YarnEditor
- This is the Classic Yarn Editor, and is not supported by Yarn Spinner.

Community Projects

Learn about Yarn Spinner's amazing community projects, by the community, because they're community projects.

Community projects are written by our wonderful community. These are not supported or maintained by the Yarn Spinner team, but you might find them useful.

If you've written a high-quality project that works with Yarn Spinner, please get in touch via or ! We'd love to show it off. ❤️

, by : An implementation of a Language Server for the Yarn Spinner compiler, designed for use with Visual Studio and Visual Studio Code.
, by : A visual editor for writing Yarn script.
, by : An implementation of the Yarn Spinner compiler in GDScript.
, by : An implementation of Yarn Spinner for the game engine, based on GDYarn.
, by : A Visual Studio Code extension that embeds the Yarn Classic editor.

API Documentation

C#

Any

Property in BuiltinTypes

Summary

Gets the type representing any value.

public static IType Any { get; };

Boolean

Property in BuiltinTypes

Summary

Gets the type representing boolean values.

public static IType Boolean { get; };

Number

Property in

Summary

Gets the type representing numbers.

String

Property in BuiltinTypes

Summary

Gets the type representing strings.

public static IType String { get; };

TypeMappings

Property in BuiltinTypes

Summary

Gets a dictionary that maps CLR types to their corresponding Yarn types.

public static IReadOnlyDictionary<System.Type, Yarn.IType> TypeMappings { get; };

Text

Property in Command

Summary

Gets the text of the command.

public string Text { get; private set; }

CommandHandler

Delegate in

Inherits from System.MulticastDelegate

Summary

Represents the method that is called when the Dialogue delivers a .

Parameters

Name

Description

DefaultStartNodeName

Field in Dialogue

Summary

The node that execution will start from.

public const string DefaultStartNodeName = "Start";

Dialogue(Yarn.IVariableStorage)

Constructor in

Summary

Initializes a new instance of the class.

Parameters

Name

Description

AddProgram(Program)

Method in Dialogue

Summary

Loads the nodes from the specified Program , and adds them to the nodes already loaded.

public void AddProgram(Program program)

Remarks

If Yarn.Dialogue.Program is null , this method has the effect as calling SetProgram(Program) .

Parameters

Name

Description

program

The additional program to load.

Continue()

Method in

Summary

Starts, or continues, execution of the current Program.

Remarks

This method repeatedly executes instructions until one of the following conditions is encountered:

The or is called. After calling either of these handlers, the Dialogue will wait until is called. Continue may be called from inside the or , or may be called at any future time.
The is called. When this occurs, the Dialogue is waiting for the user to specify which of the options has been selected, and must be called before is called again.)
The Program reaches its end. When this occurs, must be called before is called again.
An error occurs while executing the Program.

This method has no effect if it is called while the is currently in the process of executing instructions.

ExpandSubstitutions(string,IList<string>)

Method in Dialogue

Summary

Replaces all substitution markers in a text with the given substitution list.

public static string ExpandSubstitutions(string text, IList<string> substitutions)

Remarks

This method replaces substitution markers - for example, {0}

with the corresponding entry in substitutions . If text contains a substitution marker whose index is not present in substitutions , it is ignored.

Parameters

Name

Description

string text

The text containing substitution markers.

System.Collections.Generic.IList<string> substitutions

The list of substitutions.

Returns

text , with the content from substitutions inserted.

GetStringIDForNode(string)

Method in

Summary

Returns the string ID that contains the original, uncompiled source text for a node.

Remarks

A node's source text will only be present in the string table if its tags header contains rawText.

Because the class is designed to be unaware of the contents of the string table, this method does not test to see if the string table contains an entry with the line ID. You will need to test for that yourself.

Parameters

Name

Description

Returns

The string ID.

GetTagsForNode(string)

Method in Dialogue

Summary

Returns the tags for the node nodeName .

public IEnumerable<string> GetTagsForNode(string nodeName)

Remarks

The tags for a node are defined by setting the tags header in the node's source code. This header must be a space-separated list.

Parameters

Name

Description

string nodeName

The name of the node.

Returns

The node's tags, or null if the node is not present in the Program.

NodeExists(string)

Method in Dialogue

Summary

Gets a value indicating whether a specified node exists in the Program.

public bool NodeExists(string nodeName)

Parameters

Name

Description

string nodeName

The name of the node.

Returns

true if a node named nodeName exists in the Program, false otherwise.

ParseMarkup(string)

Method in Dialogue

Summary

Parses a line of text, and produces a MarkupParseResult containing the results.

public MarkupParseResult ParseMarkup(string line)

Remarks

The MarkupParseResult 's Text will have any select , plural or ordinal markers replaced with the appropriate text, following this Dialogue 's LanguageCode .

Parameters

Name

Description

string line

The line of text to parse.

Returns

The results of parsing the markup.

SetNode(string)

Method in Dialogue

Summary

Prepares the Dialogue that the user intends to start running a node.

public void SetNode(string startNode = DefaultStartNodeName)

Remarks

After this method is called, you call Continue() to start executing it.

If PrepareForLinesHandler has been set, it may be called when this method is invoked, as the Dialogue determines which lines may be delivered during the startNode node's execution.

Parameters

Name

Description

string startNode

The name of the node that will be run. The node have been loaded by calling or .

SetProgram(Program)

Method in Dialogue

Summary

Loads all nodes from the provided Program .

public void SetProgram(Program program)

Remarks

This method replaces any existing nodes have been loaded. If you want to load nodes from an additional Program, use the AddProgram(Program) method.

Parameters

Name

Description

program

The to use.

SetSelectedOption(int)

Method in

Summary

Signals to the that the user has selected a specified .

Remarks

After the Dialogue delivers an , this method must be called before is called.

The ID number that should be passed as the parameter to this method should be the field in the that represents the user's selection.

Parameters

Name

Description

Stop()

Method in Dialogue

Summary

Immediately stops the Dialogue .

public void Stop()

Remarks

The DialogueCompleteHandler will not be called if the dialogue is ended by calling Stop() .

UnloadAll()

Method in

Summary

Unloads all nodes from the Dialogue.

CommandHandler

Property in Dialogue

Summary

Gets or sets the CommandHandler that is called when a command is to be delivered to the game.

public CommandHandler CommandHandler
{
            get; set; }

CurrentNode

Property in

Summary

Gets the name of the node that this Dialogue is currently executing.

Remarks

If has never been called, this value will be null .

DialogueCompleteHandler

Property in Dialogue

Summary

Gets or sets the DialogueCompleteHandler that is called when the dialogue reaches its end.

public DialogueCompleteHandler DialogueCompleteHandler
{
            get; set; }

IsActive

Property in

Summary

Gets a value indicating whether the Dialogue is currently executing Yarn instructions.

LanguageCode

Property in

Summary

Gets or sets the 's locale, as an IETF BCP 47 code.

Remarks

This code is used to determine how the plural and ordinal markers determine the plural class of numbers.

For example, the code "en-US" represents the English language as used in the United States.

Library

Property in

Summary

Gets the that this Dialogue uses to locate functions.

Remarks

When the Dialogue is constructed, the Library is initialized with the built-in operators like + , - , and so on.

LineHandler

Property in Dialogue

Summary

Gets or sets the LineHandler that is called when a line is ready to be shown to the user.

public LineHandler LineHandler
{
            get; set; }

LogDebugMessage

Property in

Summary

Invoked when the Dialogue needs to report debugging information.

LogErrorMessage

Property in Dialogue

Summary

Invoked when the Dialogue needs to report an error.

public Logger LogErrorMessage { get; set; }

NodeCompleteHandler

Property in

Summary

Gets or sets the that is called when a node is complete.

NodeNames

Property in

Summary

Gets the names of the nodes in the currently loaded Program.

NodeStartHandler

Property in Dialogue

Summary

Gets or sets the NodeStartHandler that is called when a node is started.

public NodeStartHandler NodeStartHandler
{
            get; set; }

OptionsHandler

Property in

Summary

Gets or sets the that is called when a set of options are ready to be shown to the user.

Remarks

The Options Handler delivers an to the game. Before can be called to resume execution, must be called to indicate which was selected by the user. If is not called, an exception is thrown.

PrepareForLinesHandler

Property in

Summary

Gets or sets the that is called when the dialogue anticipates delivering some lines.

DialogueCompleteHandler

Delegate in

Inherits from System.MulticastDelegate

Summary

Represents the method that is called when the dialogue has reached its end, and no more code remains to be run.

DialogueException

Class in

Inherits from System.Exception

Summary

An exception that is thrown by when there is an error in executing a .

Description

Property in FunctionType

Summary

Gets a more verbose description of this type.

public string Description
{
            get; set; }

Methods

Property in FunctionType

Summary

Gets the collection of methods that are available on this type.

public MethodCollection Methods { get };

Name

Property in

Summary

Gets the name of this type.

Parameters

Property in

Summary

Gets the list of the parameter types that this function is called with.

Remarks

The length of this list also determines the number of parameters this function accepts (also known as the function's arity ).

Parent

Property in

Summary

Gets the parent of this type.

Remarks

All types have as their ultimate parent type (except for itself.)

ReturnType

Property in

Summary

Gets the type of value that this function returns.

IType

Interface in Yarn

Summary

Defines properties that describe a type in the Yarn language.

public interface IType

Properties

Name

Description

Gets a more verbose description of this type.

Gets the collection of methods that are available on this type.

Gets the name of this type.

Gets the parent of this type.

Description

Property in

Summary

Gets a more verbose description of this type.

Methods

Property in IType

Summary

Gets the collection of methods that are available on this type.

MethodCollection Methods { get; }

Name

Property in

Summary

Gets the name of this type.

Markup

Markup allows you to add attributes into your text, like [a]hello[/a]. These attributes can be used by your game to do things like change the formatting of the text, add animations, and more.

When text is parsed, the tags are removed from the text, and you receive information about the range of the plain text that the attributes apply to.

Attributes

Attributes apply to ranges of text:

Yarn Spinner will take this text, and produce two things: the plain text, and a collection of attributes. The plain text is the text without any markers; in this example it will be:

Attributes represent ranges of the plain text that have additional information. They contain a position, a length, and their name, as well as their properties.

In this example, a single attribute will be generated, with a position of 4, a length of 5, and a name of "wave".

Attributes are opened like [this], and closed like [/this].

Overlapping Attributes

Attributes can overlap:

You can put multiple attributes inside each other. For example:

You can close an attribute in any order you like. For example, this has the same meaning as the previous example:

Self-closing Attributes

Attributes can self-close:

A self-closing attribute has a length of zero.

The Close-All Marker

The marker [/] is the close-all marker. It closes all currently open attributes. For example:

Properties

Attributes can have properties:

This attribute 'wave' has a property called 'size', which has an integer value of 2.

Short-hand Properties

Attributes can have short-hand properies, like so:

This is the same as saying this:

This attribute 'wave' has a property called 'wave', which has an integer value of 2. The name of the attribute is taken from the first property.

Property Types

Properties can be any of the following types:

Integers
Floats
'true' or 'false'
Strings

Single words without quote marks are parsed as strings. For example, the two following lines are identical:

Whitespace Trimming

If a self-closing attribute has white-space before it, or it's at the start of the line, then it will trim a single whitespace after it. This means that the following text produces a plain text of "A B":

If you don't want to trim whitespace, add a property trimwhitespace, set to false:

Showing Special Characters to the Player

You may want to show text containing the [ and ] characters to your player. To prevent the markup parser from treating as special characters, you can escape them. Text that has been escaped will be treated as plain text, and will not be interpreted by the parser.

There are two ways to escape your markup: escaping single characters, and using the nomarkup attribute.

Escaping single `[` and `]` characters

If you need to escape a single square bracket character, put a backslash \ in front of it:

This will appear to the player as:

The backslash will not appear in the text.

If you need to show a blackslash in your text, use two blackslashes:

This will appear as:

The `nomarkup` Attribute

If you want to escape a longer run of text, or if you have many square brackets, escaping a single character at a time can be cumbersome. In these cases, you may want to escape an entire region of text, using the nomarkup attribute. This attribute makes the parser ignore any markup characters inside it.

If you want to include characters like [ and ], wrap them in the nomarkup attribute:

This will appear as:

The `character` Attribute

The character attribute is used to mark the part of the line that identifies the character that's speaking.

Yarn Spinner will attempt to add this character for you, by looking for character names in lines that look like this:

The markup parser will mark everything from the start of the line up to the first : (and any trailing whitespace after it) with the character attribute. This attribute has a property, name, which contains the text from the start of the line up to the :. If a : isn't present, or a character attribute has been added in markup, it won't be added.

This means that the example above is treated the same as this:

You can use this to trim out the character names from lines in your game.

Text Replacement Markers

Certain attributes in Yarn Spinner's markup are "replacement" markers, which Yarn Spinner uses to insert or replace text based on the value of a variable. There are three built-in replacement markers:

The select marker uses the value of a variable to choose an outcome.
The plural marker uses the value of a number to decide on the plural class for that number.
The ordinal marker uses the value of a number to decide on the ordinal class for that number.

All three of these markers have a property called value, and use this to decide what text should be used in the line.

`select`

The select marker is the simplest of the built-in replacement markers. It takes the value of the value property, and uses that to choose a replacement.

It's especially useful for when you need to insert a gendered pronoun in a line:

`plural` and `ordinal`

The plural and ordinal markers take a number in its value property, and use that to determine the plural or ordinal number class of that value.

Plurals across different languages

Different languages have different rules for how numbers are pluralised.

In many languages, the term you use to refer to a thing depends on the the number of that thing. This is known as a plural class: in English, you can have one apple, but many apples, and you have have one mouse, but many mice.

However, the rules vary significantly across different languages. English has two: "single", and "other". However, for example, Polish has multiple.

In English, you say "one apple, two apples, five apples".
In Polish, you say "jedno jabłko, dwa jabłka, pięć jabłek".

Notice how the Polish word for "apple", "jabłko", takes multiple forms as the number changes, whereas it takes two forms in English.

In Yarn Spinner, individual lines are replaced depending on the user's locale, but the logic surround them is not. This means that, if you want to be able to translate your game into multiple languages, you can't write Yarn code like this:

If you did it this way, the logic would only work for languages that have the same rules for plurals as English. (There are several of them that do, but far more that don't.)

Complicating this further, there are two main kinds of plural classes: cardinal plural classes, and ordinal plural classes.

Cardinal plural classes are the kind we just saw (for example, "one apple, two apples").
Ordinal plural classes refer to the positioning of a thing; in English, ordinal numbers are things like "1st, 2nd, 3rd."

As with cardinal plural classes, different languages have different ordinal plural classes.

Pluralising with `plural` and `ordinal`

Yarn Spinner is able to take a number and the user's current locale, and determine the correct cardinal or ordinal plural class of that number, for that locale. You can then use the plural class to decide on what text to show.

plural and ordinal have a property called value, just like select. They then have a property for each of the current locale's plural classes. These can be:

one
two
few
many
other

The two markers differ based on what kind of plural class they work with:

plural selects a number's cardinal plural class.
ordinal selects a number's ordinal plural class.

Not every language uses every category; for example, English only uses "one" and "other" for cardinal plural classes.

For each of these properties, you provide the text that should appear.

For example:

You can include the actual value in the resulting text by using the % character. This character will be replaced with the value provided to the value property:

The ordinal marker works similarly, but uses the ordinal plural class:

Creating Custom Dialogue Views

Learn how to create Dialogue Views that are designed for the specific needs of your game.

While the Line View and Options List View are useful for lots of situations, your game might need to display lines and options in specific ways. In these situations, you can write your own custom Dialogue View, and handle the presentation of lines and options in ways that are entirely in your control.

Creating a Dialogue View

To create a Dialogue View, you subclass the class, and add it as a component to a game object in your scene. You can then add this game object to the Dialogue Views list on your scene's Dialogue Runner.

If you just want to skip straight to the sample code, take a look at the in the Yarn Spinner examples repository.

Presenting Lines and Options

On its own, an empty subclass of DialogueViewBase 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 View, it's useful to understand how the works with content.

Yarn Spinner scripts deal in three different kinds of content: lines, options, and commands. Of these, only the first two - lines and options - are content that need to be shown directly to the player.

When the Dialogue Runner encounters lines or options, it first needs to determine the specific content the user needs to see. Once it has this, it sends the content to each of its Dialogue Views.

Your scene can have multiple Dialogue Views, and they can all do different things. It can be useful to create, for example, a Dialogue View that handles lines, and a separate Dialogue View that handles options.

Getting Localized Content

Lines and options are represented in compiled Yarn scripts as line IDs. A line ID is a unique identifier for the text of a line or an option. When Yarn Spinner needs to show a line or option to the user, it asks its to provide it with a object. This object contains the text of the line or option, in the user's current locale.

As discussed in , you can have different kinds of Line Providers; for example, the creates LocalizedLine objects that just contain text, while creates objects that also contain an .

When displaying a collection of options, each individual option has its own LocalizedLine.

Once a LocalizedLine has been created, the Dialogue Runner has everything that it needs to show content to the user. The next steps vary depending on whether it's showing a line or an option.

Presenting Lines

When Yarn Spinner encounters a line of dialogue, it calls the RunLine method on each Dialogue View. This method takes two parameters: the first is the LocalizedLine that the Line Provider created, and the second is a that the Dialogue View should call when the line has finished being presented.

In Dialogue Views, a line is presented when the user has received the entire line, and is ready to move on to the next line. The practical outcome of what this means depends on the Dialogue View itself; for example, a Dialogue View that plays voice-over audio might finish presenting when all of the audio has played, while a Dialogue View that gradually reveals the text of a line might finish presenting when all of the text is visible.

The Dialogue Runner will wait until all Dialogue Views report that they've finished presenting the line. Once this happens, it moves on to the next part of the dialogue.

If you're making a game where you want the dialogue to pause until the user gives a signal to proceed, your Dialogue View can pause the dialogue by not calling the completion handler until it receives the signal. Because the Dialogue Runner will wait until all Dialogue Views report that they're done, the dialogue will wait.

Interrupting Lines

At any point during a line's presentation, a Dialogue View can interrupt the line. It does this by calling the method, which is a delegate that's set by its controlling Dialogue Runner. When this method is called, all Dialogue Views that have not yet finished their presentation receive a call to their method.

InterruptLine is very similar to RunLine, in that it receives a line to present and a completion handler to call when the presentation is complete. However, while RunLine is expected to present the line at its own pace, InterruptLine is a signal to finish the presentation as quickly as possible.

As before, the actual details of this depend on the Line View. To continue the examples from before, a Dialogue View that plays voice-over audio might fade out the audio over a short period of time, or even cut off playback immediately; a Dialogue View that's gradually revealing text might reveal the remaining text all at once, or rapidly reveal the remaining text.

When a Dialogue View receives a call to InterruptLine, it should not call the completion handler that it received from the call to RunLine. Calls to interrupt a line supersede calls to run a line.

Any Dialogue View may request that a line be interrupted. If multiple Dialogue Views request it, only the first request does anything.

Dismissing Lines

When the last Dialogue View reports that its presentation is complete, either because RunLine finished its presentation, or because InterruptLine was called and it quickly finished its presentation, it needs to tell the dialogue views to get rid of the line, and potentially prepare for more content.

The Dialogue Runner does this by calling on all Dialogue Views. As with RunLine and InterruptLine before it, DismissLine receives a completion handler to call when it has finished dismissing the line.

As before, the details of how a line is dismissed vary with what the Dialogue View actually does. A Dialogue View that plays voice-over audio may not need to do anything to dismiss a line, because the playback has already finished; a Dialogue View that shows line text on screen might need to hide the text, possibly with an animation.

When the last Dialogue View reports that it has finished dismissing its line, the Dialogue Runner continues running the script.

Presenting Options

Options are slightly different to lines, in that they rely on receiving some kind of user input before the dialogue can continue: the Dialogue Runner needs to know which option was selected.

To handle options, Dialogue Views implement the method. This method receives an array of objects, each of which represents an option that can be shown to the user, as well as a completion handler.

When this method is called, the Dialogue View uses the information contained within the DialogueOption objects to present the choices to the player, and then awaits user input. Once it knows which option was selected, it calls the completion handler, passing in the of the selected option.

When the Dialogue Runner delivers options to its Dialogue Views, it expects exactly one of them to call the completion handler that RunOptions receives.

If none of them call it, then the Dialogue Runner will never receive the option that was selected (and will wait for it forever.)
If more than one of them call it, the Dialogue Runner will throw an error.

(In most situations, you will generally only have one Dialogue View in your scene that handles options. If you have more than one, then you will need to control which one of them will call their completion handler.)

Using Multiple Dialogue Views

Dialogue Runners can use multiple Dialogue Views. This is actually recommended, because it makes it easier to separate the code for handling lines, from that of running options.

All of the methods in are optional. If you don't implement a method, then the default implementation of that method is used instead; the default implementation either does nothing, or as close to nothing as it can while still working. For example, the default implementation of RunLine immediately signals that presentation is complete.

To create a Dialogue View that shows lines, implement RunLine, InterruptLine and DismissLine.
To create a Dialogue View that shows options, implement RunOptions.
To create a Dialogue View that supports both, implement all four.

Responding to Dialogue Advancement Signals

During gameplay, your user may wish signal that they want to advance the dialogue: that is, they want to proceed to the next line, or they want the current line to be presented more quickly.

To handle this case, subclasses of DialogueViewBase may implement the method , which can be called by other parts of the gam.

In most cases, it is generally appropriate for implementations of UserRequestedViewAdvancement to call the method, which tells the Dialogue Runner to interrupt the line (across all views) and to proceed to the next one. However, a Dialogue View may choose to perform other actions that deliver the line more quickly.

For example, in several text-based RPG games, dialogue is delivered as a text box, one letter at a time; when it's all delivered, the user can press the A button (to choose an arbitrary example) to proceed.

If, however, you press the A button while the text is still appearing, all of the text appears all at once (as though we'd jumped ahead).

Alternatively, if you pressed the B button while the text was still appearing, the line would be skipped, the dialogue would move to the next line.

UserRequestedViewAdvancement can be called by any part of your code. Additionally, you may wish to use , which is a class that listens for user input, and when it receives it, calls UserRequestedViewAdvancement on a view you specify.

Seeing it in Action

To demonstrate how a custom Dialogue View is put together, we've created , which demonstrates the above features and is heavily commented. For more information, see the code on .

Localizations and Assets

Localization is the process of translating and adapting content to a specific language, region or culture.

Yarn scripts are written in human-readable language. This is generally a single language, and (most of the time) will be written in the language that your development team primarily speaks. The language that a Yarn project is written in is called the base language.

However, if you want your dialogue to be understood by people who don't speak this language, you will need to translate it. Yarn Spinner is designed to make it easy to extract the user-facing text of your dialogue into a strings file, which can then be translated into a different language, and then loaded at run-time. You can translate your project into as many languages as you'd like, and Yarn Spinner will handle it for you automatically.

Yarn Spinner is also designed around the idea that a line of dialogue may have assets associated with it. Most commonly, this means an audio file that contains an actor performing the line, so that it can be used in your game as a voice-over. These assets are also localisable.

I just want to add voiceover in a single language. Why do I need to localise, too?

The philosophy of Yarn Spinner's approach to localisation is: if you want your dialogue to be text-only, and in a single language, you don't need to do anything at all. If you want to do anything else, you will need to set up a localisation and manage it using Yarn Spinner's processes.

We've found that most users who want to start using Yarn Spinner want to quickly get dialogue on the screen, and don't want to do lots of work to get the basics going. That's why we make the simple use-case (text only, a single language) as easy to use as we can.

However, if you're building a game that's voice acted, it makes your life significantly easier if you build your systems with localisation in mind from the start. Additionally, if you have the resources to add voice-over to your project, you should also have the resources to translate your game to other languages (even if you only have voice-overs in a single language.)

To that end, we designed it so that voiceover is intimately tied to localisation, so that you have to at least start thinking about localisation at the start of the process.

Localisation Terminology

Localisation: A set of information that describes where to find text and assets for a given language.
Base language: The language that your Yarn script files are written in.
Strings file: A text document that contains translated versions of Yarn lines.
Line ID: A unique code that identifies a line of dialogue or an option in the original source text.
Localised line: The text of a line of dialogue, in a particular locale.
Localised line asset: An asset (for example, an audio clip) that's associated for a particular line, in a particular locale. For example, an audio clip containing the voiceover for the line "Hello there", in German.
Line provider: A component that receives line IDs from the Dialogue Runner, and fetches the localised line and localised line assets (if present) for the player's preferred locale.

Localisation Workflow

In Yarn Spinner, the localisation workflow works like this:

Write your Yarn scripts. This original content is your 'base' localisation.
Add a line ID to each line of dialogue in your script.
Set up localisations in the Yarn Project for each of the languages you wish to support. (This includes your base language.)
For each localisation besides your base language:
1. Export a strings file.
2. Translate its contents into another language.
3. Associate the strings file with the localisation.
If you have assets you want to use with your dialogue, associate the folder that contains those assets with the localisation they belong to, and set up a Line Provider that's able to use those assets (such as an Audio Line Provider.)
During gameplay, set your Line Provider's language to the player's preferred language, and it will fetch the appropriate content for the player to see.

In the following sections, we'll go through each of these steps.

Writing Yarn Scripts

Every Yarn script is associated with a base language. By default, Yarn Spinner sets the base language to that of your current locale. For example, if your computer is set to use Australian English, then Yarn Spinner will use that as the base language.

The base language of a Yarn Script is controlled by the Yarn Project that it's a part of. You can change the language of your base localisation by changing the 'Base Language' setting on a Yarn Project.

Adding Line IDs

In order to match different versions of a line, you need to add a line id to each line of dialogue. A line ID is a tag that appears at the end of a line that uniquely identifies a line of dialogue in your game.

Here's an example of a line of dialogue with a line tag:

Gunther: I wanted orange! They gave me lemon-lime. #line:1a64a5

In this example, the line of dialogue has a line ID of 1a64a5.

Yarn Spinner can add line IDs to your dialogue for you. To do this, select your Yarn Project, and click 'Add Line Tags to Scripts'. Yarn Spinner will re-write all of the script files, adding a line ID to any line that doesn't already have one.

You can't generate a strings file unless all of the lines in all of the scripts in the Yarn Project have a line ID.

Set Up Localisations

When you want to prepare a Yarn Project for an additional language, you add a new Localisation in the Yarn Project.

Localisations are how you tell Yarn Spinner where to find the localised lines, and the localised line assets, for a given language.

To create a new Localisation, open the Localisations list in the Yarn Project's Inspector, and click the + button.

Localisations have the following properties:

Property

Description

Language ID

The language for this localisation.

Strings File

A Text Asset containing the translated lines for this Yarn Project's scripts. See for information on how to create these assets.

Assets Folder

A folder containing the localised assets for this localisation.

You can create a localisation for the base language. When you do this, you can provide localised assets for that language.

Creating a Translation

After you've set up a localisation, you can translate your dialogue into that localisation's language. To do this, you generate a strings file.

A strings file is a text-based spreadsheet, in comma-separated value form, that contains a translated version of your dialogue. Yarn Spinner can generate a strings file for you, based on the line IDs in the dialogue.

You don't need to create a strings file for your base localisation, because Yarn Spinner can generate that for you from your source Yarn scripts. Any localisation whose language ID is the same as your base language will be marked as 'Automatically included'.

To create a strings file, select a Yarn Project, and click the Export Strings as CSV button. Unity will ask where you want to save the file.

A strings file has the following structure:

Column

Description

language

The language code for this line.

When you export a strings file, this will be the Yarn project's base language.

The line ID for this line.

text

The text of the line, in the language indicated by the language column.

file

The file that the line was originally found in.

node

The node that the line was originally found in.

lineNumber

The line number of the file that the line was originally found in.

lock

A unique value that Yarn Spinner uses to detect if the line has been modified since the strings file was generated. Don't modify or delete this value.

comment

A note indicating the intent and tone of the line. This can be useful for translators who may not have the same background or context for how the line should be delivered.

Once you've exported a strings file, you can translate it into another language: for each row in the database, change the language column to the new language you're translating into, and the text column to the translated text of the line.

Only the language and text columns should be modified by the translator. Don't modify the others; in particular, if you modify the value in the id column, Yarn Spinner won't be able to link the translated line to the original version.

Once you have a strings file that's been translated into your target language, you can add it to your Localisation. To do this, drag and drop the translated strings file into the Strings File property of your localisation, and click Apply.

It's possible to update a strings file after you've made changes to your source scripts. For example, you might have added or removed lines, or made changes to the text.

To update a strings file, click the Update Existing Strings Files button at the bottom of the Inspector.

Yarn Spinner will update every strings file that's been added to the Localisations list: new lines will be added, removed lines will be deleted, and lines whose original text has changed since the last time the file was updated will have the text "NEEDS UPDATE" added to the end. This allows you to more easily find which lines need an updated translation.

Adding Localised Assets

Localised line assets are assets that are associated with a particular line, in a particular localisation. The most common example of this is voice-over lines, which are audio assets that are associated with each line.

Line Providers are responsible for fetching the appropriate assets for a given line and language. For example, the Audio Line Provider fetches audio clips, and provides them to voice-over dialogue views.

Selecting a Language at Run-time

The specific localised line, and localised line assets, that a line provider fetches depends on which language they have been configured to fetch.

The Text Line Provider has a single language option, which controls which language the line will appear in.

The Audio Line Provider has two language options: the language of the text, and the language of the audio files that are retrieved. This means that you can configure it to provide text in one language, and audio in another.

If a line provider is asked to retrieve content for a language that it doesn't have any assets for, it will retrieve the base language version instead.

Commands and Functions

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 Unity, there are two ways to add new commands to Yarn Spinner: automatically, via the YarnCommand attribute, or manually, using the DialogueRunner's AddCommandHandler method.

The `YarnCommand` attribute

The YarnCommand attribute lets you expose methods in a MonoBehaviour 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 static, you call it directly. For example:

// Note that we aren't subclassing MonoBehaviour here; 
// static commands can be on any class.
public class FadeCamera {

    [YarnCommand("fade_camera")]
    public static void FadeCamera() {
        Debug.Log("Fading the camera!");
    }
}

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

<<fade_camera>>
// will print "Fading the camera!" in the console

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

For example:

public class CharacterMovement : MonoBehaviour {

    [YarnCommand("jump")]
    public void Jump() {
        Debug.Log($"{name} is jumping!");
    }
}

If you save this in a file called CharacterMovement.cs, create a new game object called MyCharacter, and attach the CharacterMovement script to that game object, you can run this code in your Yarn scripts like this:

<<jump MyCharacter>>
// will print "MyCharacter is jumping!" in the console

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:

Type

Note

string

Passed directly to the function.

int

Parsed as an integer using .

float

Parsed as an integer using .

bool

The strings "true" and "false" are converted to their respective boolean values, true and false. Additionally, the name of the parameter is interpreted as true.

GameObject

Yarn Spinner will search all active scenes for a game object with the given name. If one is found, that game object will be passed as the parameter; otherwise, null will be passed.

Component (or its subclasses)

Yarn Spinner will search all active scenes for a game object with the given name, and then attempt to find a component of the parameter's type on that game object or its children. If one is found, that component will be passed as the parameter; otherwise, null will be passed.

Method parameters may be optional.

For example, consider this method:

[YarnCommand("walk")]
public void Walk(GameObject destination, bool dancing = false) {
    var position = destination.transform.position;

    // If the second parameter is used in the command,
    // and it's "true" or "dancing", use a dance 
    // animation
    if (dancing) {
        // set animation to a dance
    } else {
        // set animation to a regular walk
    }

    // walk the character to 'position'
}

This command could be called like this:

<<walk MyCharacter StageLeft>> // walk to the position of the object named 'StageLeft'

<<walk MyOtherCharacter StageRight dancing>> // walk to StageRight, while dancing

Adding commands through code

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 Unity with the following code:

public class CustomCommands : MonoBehaviour {    

    // Drag and drop your Dialogue Runner into this variable.
    public DialogueRunner dialogueRunner;

    public void Awake() {

        // Create a new command called 'camera_look', which looks at a target. 
        // Note how we're listing 'GameObject' as the parameter type.
        dialogueRunner.AddCommandHandler<GameObject>(
            "camera_look",     // the name of the command
            CameraLookAtTarget // the method to run
        );
    }

    // The method that gets called when '<<camera_look>>' is run.
    private void CameraLookAtTarget(GameObject target) {
        if (target == null) {
            debug.Log("Can't find the target!");
        }
        // Make the main camera look at this target
        Camera.main.transform.LookAt(target.transform);
    }    
}

Add this script to any game object, and it will register the camera_look in the Dialogue Runner you attach.

You can then call this method like this:

<<camera_look LeftMarker>> // make the camera look at an object named LeftMarker

Making Commands Using Coroutines

Coroutines 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 is a coroutine (that is, it returns IEnumerator, and yields objects like WaitForSeconds), 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.)

public class CustomWaitCommand : MonoBehaviour {    

    [YarnCommand("custom_wait")]
    static IEnumerator CustomWait() {

        // Wait for 1 second
        yield return new WaitForSeconds(1.0);
        
        // Because this method returns IEnumerator, it's a coroutine. 
        // Yarn Spinner will wait until onComplete is called.
    }    
}

This new method can be called like this:

<<custom_wait>> // Waits for one second, then continues running

Defining Functions

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

In additon to the built-in functions 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:

Functions must return a value.
Functions are required to be static.

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

public class AdderFunction {
   [YarnFunction("add_numbers")]
   public static int AddNumbers(int first, int second)
   {
       return first + second;
   }
}

When this code has been added to your project, you can use it like this:

One plus one is {add_numbers(1, 1)}

Yarn functions can return the following types of values:

string
int
float
bool

Commands, Functions and Assembly Definitions

Yarn Spinner searches your code for methods that have the YarnCommand and YarnFunction attributes when your game first starts up, as well as when a Dialogue Runner is told to run a Yarn Project.

If the Yarn Project's "Search All Assemblies" option is turned on, every assembly definition is searched; if it's turned off, only the assembly definitions specified in the "Assemblies To Search" option is searched. Code that is not in an assembly definition is always included.

By default, Yarn Spinner searches every assembly definition. If you have a large codebase, putting all of the code that contains commands and functions in an assembly definition can reduce the amount of time Yarn Spinner needs to take to find all of the commands and functions.

If "Search All Assemblies" is turned off on your Yarn Projects, and you're seeing errors that mention that a command hasn't been registered, try turning "Search All Assemblies" on. If the error goes away, it means the code for those commands is in an assembly definition that the Yarn Project wasn't using.

Yarn Variables and Variable Storage

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 Unity, 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:

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.

What makes a Variable Storage?

Like other parts of the Unity API for Yarn Spinner, 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 Unity, 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:

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.
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.
Actually get rid of values when asked to. Your code will still compile if your Clear() method does nothing, but this means that Yarn script progress or state may never be reset correctly.
Actually check if a key already exists. Your code will still compile if your Contains() method always returns false, but this will lead to overwriting existing values the next time someone tries to SetValue() a seemingly unused key that already had a value.

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 call a UnityEvent 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...

Let’s make a custom Variable Storage!

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.

SQL is a domain-specific language and set of related frameworks that allow the creation and manipulation of relational databases. This will not be a guide to SQL, as there are many good ones already out there, but the TL;DR of SQL is: data is stored in tables, each column has a name and a type, each row is an entry, and some entries may reference entries in other tables that hold related information. SQL queries can be used to connect information from across tables, to get the fields of information you want.

To begin, we need to make a custom class for our new Variable Storage, which should inherit from the VariableStorageBehavour 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 Start() 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.

Those familiar with SQL may notice that these tables do not reference each other and thus this is not an ideal use case for SQL. But this is a minimal example for a method that would be more effectively used in larger games with more complex schemas for their data storage or persistence.

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).

To make sure the compiler knows what T is at compile time, results must be cast to object and then back to T (thanks, C#!).

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:

In production, you should always validate and sanitise input before inserting it into SQL, in case our string value itself contains invalid syntax or partial SQL commands. Otherwise, you may leave yourself open to SQL injection attacks.

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 game object 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!

Where to go to learn more

Check out the or ask the community in the !

You can download the full implementation of the script made in this guide . Or you may also like to read through the default implementation of InMemoryVariableStorage .

NPC Dialogue Game

This example project demonstrates making a simple non-linear dialogue-based game when beginning with some pre-existing assets.

Goals

Display Yarn dialogue in a Unity scene
Allow a player to select between options to respond
Allow a player to select among available characters to speak to
Use Yarn Spinner to trigger a command that changes the interactability of characters

Materials

Yarn Spinner installed in Unity
Yarn Spinner set up in a text editor
Starter Asset Package downloaded and unzipped

Instructions

Open a new Unity 3D project. Ensure Yarn Spinner has been added to the project in the Package Manager as per the Installation Instructions.

Drag the provided Asset Package into the Project Window where project files are displayed in Unity to import them into the project.

This package includes the following assets and functionality:

A simple, static environment called Graveyard which also contains four character models.
A C# script that provides simple functions for the character objects.
A Timeline that stores the hovering animation for the Ghost character.
Some Lights that turn on and off to indicate when a Grave character is speaking.

Creating a Runnable Script

The next step is to import the Dialogue System and hook up a Yarn Project and Yarn Script. If you have completed Example Project 1 or Example Project 2 before, you may skip ahead to Filling Out Your Script. Otherwise, let's proceed!

Yarn Spinner for Unity comes with a pre-made UI layer and accompanying utility scripts to handle displaying lines and presenting options from Yarn files. In the Project Window again, navigate to Packages > Yarn Spinner > Prefabs and drag Dialogue System.prefab into the scene.

When the Dialogue System in the scene is selected, the Inspector will display the Yarn Project it is expecting line from. Here, a Yarn Project is a kind of linking file that groups Yarn script files together. To make one, navigate to a sensible place for the file to live (such as Assets > Dialogue) and right-click the Project Window pane to select Create > Yarn Spinner > Yarn Project.

The existence of Yarn Projects allows larger games with multiple dialogue systems (e.g. main story dialogue, barks, storylets) to separate into multiple projects that pass lines to different UI or systems. This allows an extra level of organisation above separate Yarn files which are typically used to separate story scenes or parts.

However, most games will need only a single Yarn Project.

Select the scene's Dialogue System again and drag the new Yarn Project into the labelled slot in the Inspector.

Now the Yarn Project needs one or more Yarn Scripts to get dialogue from. Just like with the Yarn Project, navigate to the desired file location and select Create > Yarn Spinner > Yarn Script. Then, with the Yarn Project selected, drag the newly created script into the Inspector slot labelled Source Scripts. Click Apply.

Filling Out Your Script

By default, a new Yarn Script begins with a single empty node with the name of the file. Open the file, rename the node to Start and put a single line of test dialogue. You may remove the tags field.

title: Start
---
This is a line of test dialogue.
===

Returning to Unity, pressing the ▶️ button results in the test line being displayed in front of the graveyard scene. Pressing Continue will make the UI disappear, as it has reached the end of the script.

It's time to plan a story. In the scene there are four characters—Ghost, LeftGrave (Louise), CenterGrave (Carol), and RightGrave (Ruby)—and the intent of this game is for the player to be able to interact with them in virtually any order to complete the objectives of the game. This game format typically accompanies stories where the player must piece together information from smaller tidbits given to them when they speak to different characters.

For example: neither Witness A nor B knew who stole the cookie from the kitchen, however:

Witness A knew the cookie was taken in the morning.
Witness B knew that Suspects A and B entered the kitchen in the morning and afternoon, respectively.

Together, their clues show that Suspect A must have eaten the cookie.

So, when the game begins, Ghost will present some mystery. Once a brief context-establishing conversation ends, the player will be free to select which character to speak to next. Speaking to each of the Grave characters will present a clue, provided the required prerequisite clues are known. At any time, the player can present their collated clues to Ghost. If their clues are complete, Ghost will tell them they solved the mystery and the game will end.

This short story provides a looping circuit through four paths, and results in the player reaching the ending after an undetermined number of conversations (though there is a hypothetical minimum, there is no maximum). A railroad diagram representation of the story would look as follows:

So it's time for the actual writing part. Here, I've opened my new Yarn Script in Visual Studio Code with the Yarn Spinner Extension installed as per the Installation Instructions. I've written a minimal script that follows the planned story, as a skeleton that can be expanded on later.

In this script, selecting the correct conversation option when speaking to each character will yield a new clue. However, the correct option is only available if the player has the required prerequisite clues. So no matter the order the player speaks to the graves, they must acquire clues in the order A then B then C.

The most notable part about this script is that there are no jump statements in the file at all; each node is completely disconnected from the rest. Instead, we will be requesting and jumping to specific nodes manually from within Unity.

You can find this example script below to copy. Or if you want to make you own version and need a refresher on how to represent it in Yarn, refer to the Syntax and File Structure guide.

GhostyLads.yarn

title: Start
---
<<set $hasClueA to false>>
<<set $hasClueB to false>>
<<set $hasClueC to false>>
Ghost: Welcome to the graveyard! Unfortunately, you're just in time for an unsolved mystery...
Ghost: You'll have to speak to these three to figure out what happened!
===
title: LeftGraveLouise
---
Louise: What do you want to know?
-> Something that will get me no clues?
-> Something that will get me Clue A? <<if not $hasClueA>>
    <<set $hasClueA to true>>
-> Something relating to existing Clue A? <<if $hasClueA>>
-> Something relating to existing Clue B? <<if $hasClueB>>
-> Something relating to existing Clue C? <<if $hasClueC>>
Louise: ~additional dialogue~
Louise: Ok, bye!
===
title: CenterGraveCarol
---
Carol: What do you want to know?
-> Something that will get me no clues?
-> Something that will get me Clue B? <<if $hasClueA and not $hasClueB>>
    <<set $hasClueB to true>>
-> Something relating to existing Clue A? <<if $hasClueA>>
-> Something relating to existing Clue B? <<if $hasClueB>>
-> Something relating to existing Clue C? <<if $hasClueC>>
Carol: ~additional dialogue~
Carol: Ok, bye!
===
title: RightGraveRuby
---
Ruby: What do you want to know?
-> Something that will get me no clues?
-> Something that will get me Clue C? <<if $hasClueB and not $hasClueC>>
    <<set $hasClueC to true>>
-> Something relating to existing Clue A? <<if $hasClueA>>
-> Something relating to existing Clue B? <<if $hasClueB>>
-> Something relating to existing Clue C? <<if $hasClueC>>
Ruby: ~additional dialogue~
Ruby: Ok, bye!
===
title: Ghost
---
Ghost: Are you ready to tell me what happened?
-> Yes
    Ghost: Well, what do you know?
    -> I have no clues.
    -> I have clue A. <<if $hasClueA>>
    -> I have clues A and B. <<if $hasClueB>>
    -> I have clues A, B and C. <<if $hasClueC>>
        <<jump Ending>>
    Ghost: That doesn't sound right...
-> No
Ghost: Go on and speak to those three!
===
title: Ending
---
Ghost: You solved it!
===

Once you've got a basic story, pop back into Unity and check the basics:

Lines display correctly
Pressing Continue advances lines correctly
Selecting different options have the expected outcomes

Note that at this point, there is no way to progress beyond the intro conversation with Ghost. All other nodes cannot be reached with the code we have written so far.

Making Players Interactable

In this game, the player should be able to select an NPC in the scene and have it trigger their repsective conversation. This requires a few things:

Code to begin dialogue from a specific node when a character object is interacted with.
Code to disable scene interaction when any character is already speaking.
Code to disable character interaction when a specific character should not be interactable.

In Assets > Scripts there is a C# script that has code to do these things (see headers below), so we just need to connect it to the appropriate places. But first, let's step through what it does.

// this file is attached to every character in the scene and so will affect only
// the targeted character object when functions are called

// disable scene interaction, activate speaker indicator, and
// run dialogue from {conversationStartNode}
private void StartConversation();

// reverse StartConversation's changes: 
// re-enable scene interaction, deactivate indicator, etc.
private void EndConversation();

// make character not able to be clicked on
public void DisableConversation();

Add the YarnInteractable script to each character in the game: Ghost, LeftGrave, CenterGrave, and RightGrave. Make sure to set their respective conversationStartNode values in the Inspector to match what they are called in the Yarn script.

First up is the code for beginning a conversation. This requires running dialogue from a specific node when a character is interacted with. Running dialogue is a simple matter of telling the DialogueRunner to begin dialogue and passing the name of the node to begin from as a string.

// first we need a handle on the DialogueRunner, so we may as well get it when
// this object is first added to the scene
private DialogueRunner dialogueRunner;

public void Start() {
    dialogueRunner = FindObjectOfType<Yarn.Unity.DialogueRunner>();
}

// then we need a function to tell Yarn Spinner to start from {specifiedNodeName}
public string conversationStartNode;

private void StartConversation() {
    dialogueRunner.StartDialogue(conversationStartNode);
}

To run this when a character is interacted with, simple override the OnMouseDown() function that exists for every GameObject (which this class inherits from). Checking the IsDialogueRunning property of the DialogueRunner is a simple way to ignore interaction whenever starting dialogue would interrupt an existing conversation.

private bool interactable; // whether this character should be enabled right now
// (begins true, but may not always be true)

public void OnMouseDown() {
    // if this character is enabled and no conversation is already running
    if (interactable && !dialogueRunner.IsDialogueRunning) {
        // then run this character's conversation
        StartConversation();
    }
}

This handles beginning a conversation, but what if other changes are needed while a character is speaking? Well, having a function that is triggered when a conversation ends would allow properties to be set in StartConversation that can then be reversed once dialogue has ended.

In a typical game, several changes would be triggered when beginning or ending dialogue, such as changing UI mode and starting and stopping a speaking animation on the relevant character or similar. So it's sensible to have bookend functions that hold all this code, even if we won't be doing anything useful with EndConversation()until later.

To trigger a function when a conversation ends, a listener can be added to the DialogueRunner that will fire a specified function when a certain event occurs. The onDialogueComplete event happens whenever the runner reaches the end of its current conversation path.

// this would go in the Start() function, right after finding the DialogueRunner
// object, so that the listener begins before dialogue does the first time
dialogueRunner.onDialogueComplete.AddListener(EndConversation);

Next, let's define the function it will call. A key consideration here is that every object using this YarnInteractable script will be notified of dialogue completion every time it happens. Each one is registering a listener, and each will have its own EndConversation() function be called.

So to save some work, we can check whether this is the instance that should care about the event. This can be done just by setting a boolean when the conversation begins, that says this is the character that is currently speaking.

private bool isCurrentConversation;

private void StartConversation() {
    isCurrentConversation = true;
    // TODO *begin animation or turn on speaker indicator or whatever* HERE
    dialogueRunner.StartDialogue(conversationStartNode);
}

private void EndConversation() {
    if (isCurrentConversation) { 
        // TODO *stop animation or turn off indicator or whatever* HERE
        isCurrentConversation = false;
    }
}

Returning to Unity, press the ▶️ button and see that this now allows a new conversation to be triggered by interacting with any character after another has finished speaking.

At this point, this may seem done, but there is a critical issue here. Looking back at the earlier goals:

Clicking on a character begins dialogue from their respective node.
Clicking on a character while dialogue is already running does nothing.
Clicking on a character when they should not be interactable does nothing.

Why that third thing? Well, because the current state of the game allows the player to:

Speak to the Ghost to begin the story.
Ask the Graves about the mystery.
Speak to the Ghost once they have collected the necessary clues.
Have Ghost tell them they ✨ solved the mystery ✨ and say goodbye.
Go back and still ask the Graves about the mystery that is already solved(?!)

So there needs to be a way to tell a specific character "no, you are done, don't speak to the player any more". This can be done with a simple Yarn Command.

In YarnInteractable.cs there is a simple function that sets a flag that the OnMouseDown() function checks when deciding whether to start a conversation. Turning this into a command simple requires adding the Yarn Command decorator above the function, with the string that will become the command keyword in any yarn scripts.

[YarnCommand("disable")]
public void DisableConversation() {
    interactable = false;
}

Back in the Yarn script, call disable once for each character when the story ends, to save the player from going back and having a confusion conversation about an already-solved mystery.

title: Ending
---
Ghost: You solved it!
<<disable Ghost>>
<<disable LeftGrave>>
<<disable CenterGrave>>
<<disable RightGrave>>
===

And that's it for the dialogue behaviours! Back in Unity, characters should speak when interacted with—but not when it would interrupt another, or when the story has ended.

Draw the Rest of the Owl

Now that all the behaviours are working and the skeleton story plays through correctly, it's time to replace the skeleton placeholder script with the full story and add some polish. In Assets > Dialogue find the file GhostyLads_FinalVersion.yarn. In the Yarn Project created earlier, replace the script you placed in Source Scripts earlier with this script instead.

Next, let's add an indicator so the player more easily knows which character is currently speaking.

Because I am not an animator, I have used only static objects as characters in this demo game. To indicate who is speaking, I will be using a simple spotlight that turns on and off above the speaker. I will not be taking questions at this time.—Mars, 2022.

In the scene, each grave object also contains a green spotlight which is currently assigned to a variable called lightIndicatorObject in YarnInteractable.cs, so a snippet of code in each of theStartConversation() and EndConversation() functions can quickly turn it on and off for the relevant character.

private void StartConversation() {
    isCurrentConversation = true;
    if (lightIndicatorObject != null) {
        lightIndicatorObject.intensity = defaultIndicatorIntensity;
    }
    dialogueRunner.StartDialogue(conversationStartNode);
}

private void EndConversation() {
    if (isCurrentConversation) {
        if (lightIndicatorObject != null) {
            lightIndicatorObject.intensity = 0;
        }
        isCurrentConversation = false;
    }
}

Now, a light should turn on above any grave who is currently speaking.

Result

A playable whodunnit-like game with multiple characters that can be spoken to in any order to solve a mystery from partial clues available.

An easy way to spice this up is to just try replacing provided assets with ones of your own choosing. There are plenty of publically available asset packs with permissive licenses to play with, and re-theming a starter game and building from there can be easier than starting from scratch.

You could add more characters, or even design a more complex conversation structure that must be navigated to solve the mystery! Yarn Spinner is great at telling complex non-linear stories where player choices matter.

Choose-Your-Path Game with Visuals

This example project demonstrates making a simple dialogue-based game when beginning with some pre-existing assets.

Goals

Display Yarn dialogue in a Unity scene
Allow a player to select between options to respond
Use Yarn Spinner to trigger commands that change the scene, camera and characters

Materials

Yarn Spinner installed in Unity
Yarn Spinner set up in a text editor
Starter Asset Package downloaded and unzipped

Instructions

Open a new Unity 3D project. Ensure Yarn Spinner has been added to the project in the Package Manager as per the Installation Instructions.

Drag the provided Asset Package into the Project Window where project files are displayed in Unity to import them into the project.

To see the Scene containing the imported assets, you'll need to open it. In the Project Window, navigate to Assets > Scenes and select SpaceJourney.unity.

This package includes with the following assets and functionality:

A simple, static environment called Spaceship.
Three Character models that each come with 6 available poses and 5 facial expressions.
UI Layers that appear in front of the camera to present a black screen or title screen.
Location Markers which are named but invisible objects in the scene that can act as anchors to move other objects to predefined positions.
Four C# scripts that are attached to some of the above objects to provide simple functions.

So the Scene looks somewhat like this, except that Locations and the markers within them are invisible. Here, orange diamond 🔶 icons are markers intended for the camera to move to and blue circle 🔵 icons are intended for characters.

You can see these markers yourself in Unity by selecting each marker in Location Markers and allocating them an Icon using the dropdown at the top of the Inspector. The markers named Camera are the camera markers and the ones named like Left or Right are character markers.

Creating a Runnable Script

The next step is to import the Dialogue System and hook up a Yarn Project and Yarn Script. If you have completed Example Project 1 before, you may skip ahead to Filling Out Your Script. Otherwise, let's proceed!

However, most games will need only a single Yarn Project.

Select the scene's Dialogue System again and drag the new Yarn Project into the labelled slot in the Inspector.

Filling Out Your Script

title: Start
---
This is a line of test dialogue.
===

Returning to Unity, pressing the ▶️ button results in the test line being displayed in front of the empty scene world. Pressing Continue will make the UI disappear, as it has reached the end of the script. If you do not see this, read onward for a common fix.

If you only see a black screen, the included fade-to-black layer is turned on and blocking the camera from seeing the scene. Hide this by selecting UI Layers from the Scene Hierarchy and unchecking the box at the top of the Inspector.

It's time to plan a story. In this Asset Package there are three character models called Engineer, Crewmate and Captain.

These low-poly spacefarers live and work on a spaceship with the player. It's a new day on the job in Space Fleet, the player is in the corridor and they must decide which of their three shipmates they're going to speak to. The choices presented are:

The Engineer, who will complain to the player about his job.
The Crewmate, who the player will attempt to convince should give them extra rations.
The Captain, who will try to judge whether the player is ready for action.

After a short conversation with the chosen character, a shipwide alert requests all hands report to the bridge. When the player arrives, the Captain reveals that space pirates are attacking. Then one of two things happens:

If the player chose to speak to the Captain earlier, and succeeded in convincing her that they were ready for action, the player is sent to fight off the pirates and save the day.
If the player either didn't speak to the Captain, or failed to convince her that they were ready for action, the Crewmate is sent instead.

This short story provides an initial choice between three paths, and results in the player achieving one of two endings. A tree representation of the story would look as follows:

You can find this example script below to copy. Or if you want to make you own version and need a refresher on how to represent it in Yarn, refer to the Syntax and File Structure guide.

SpaceJourney.yarn

title: Start
---
Player: Another day in Space Fleet. Might go have a chat...
// pick a person to speak to
-> Go see the Engineer as per orders
    <<jump TalkToEngineer>>
-> Meet up with your friend
    <<jump TalkToCrewmate>>
-> Go and talk to the Captain
    <<jump TalkToCaptain>>
===
title: TalkToEngineer
---
Engineer: Hello! I am the Engineer.
<<jump BridgeEnding>>
===
title: TalkToCrewmate
---
Crewmate: Hello! I am your Crewmate.
<<jump BridgeEnding>>
===
title: TalkToCaptain
---
Captain: Hello! I am the Captain.
Player: I want to talk to go on more missions.
Captain: Do you think you are ready?
-> Yes
    <<set $away_mission_readiness += 1>>
    // if so, ask again
    Captain: Really?
    -> ...yes?
        <<set $away_mission_readiness += 1>>
    -> Actually, no.
-> No
// now go to the ending
<<jump BridgeEnding>>
===
title: BridgeEnding
---
// everyone reports to the bridge
Captain: Pirates!
Player: Oh no!
// now change who goes depending on player actions
<<if $away_mission_readiness < 2>>
    Captain: Crewmate, go deal with those pirates!
    Crewmate: Yes, Captain.
<<else>>
    Captain: Player, you were just telling me how ready for this you are. 
    Captain: Go deal with those pirates!
    Player: Hooray!
<<endif>>
===

Once you've got a basic story, pop back into Unity and check the basics:

Lines display correctly
Pressing Continue advances lines correctly
Selecting different options have the expected outcomes

Adding Commands

Speaking to an empty void is all well and good, but this particular game is going to be more compelling if it makes use of the provided assets to make dynamic visuals. So to empower our Yarn script to invoke changes in Unity, we'll make some Commands. For this project, we'll make commands to:

Move the Camera to preset locations, as if the player is moving.
Turn on and off UI elements, to create nice transitions during Scene changes.
Move Character models to preset locations, as if they are entering and exiting the Scene.
Change Character model animations and textures, as if they are showing different emotions.

The first two will need to exist throughout the Scene, while the next two should attach to specific Character objects so each can be controlled independently. In Assets > Scripts there are four C# scripts that have code to do each of these things (see headers below), so we just need to create commands that make the functionality available to Yarn scripts in the project.

// this file is attached to an empty GameObject in the Scene to make these
// functions available whenever the Scene is running

// moves Main Camera to location {location}>Camera in the scene
private void MoveCamera(Location location);

// fades in from a black screen over {time} seconds
private Coroutine FadeIn(float time = 1f);

// fades out to a black screen over {time} seconds
private Coroutine FadeOut(float time = 1f);

// this file is attached to every Character in the scene and so will affect only
// the targeted Character when functions are called

// moves Character to location {location}>{markerName} in the scene
public void Move(Location location, string markerName);

// tells the Character animator to jump to state {poseName} 
public void SetPose(string poseName);

// sets character expression texture to {expressionName} texture
public void SetExpression(string expressionName);

// YOU WILL NOT HAVE TO CHANGE THIS FILE
// this file is attached to the FadeLayer in the Scene and its functions only
// exist for functions in SceneDirector.cs to call them

// fades CanvasGroup to transparency {alpha} over {time} seconds
public IEnumerator ChangeAlphaOverTime(float alpha, float time);

// YOU WILL NOT HAVE TO CHANGE THIS FILE
// this file is attached to the parent Location object of markers in the Scene 
// and its functions only exist for functions in SceneDirector.cs and Character.cs 
// to call them

// finds marker {markerName} in this Location, if one exists
public Transform GetMarkerWithName(string markerName);

Scene-Wide Commands

Code for the scene-wide commands are included in Assets > Scripts > SceneDirector.cs. To make functions from the script available throughout the project, it is attached to an otherwise empty GameObject in the Scene called Scene Director.

With our first command we want to be able to be able to move the Scene's Main Camera to an invisible marker in the Scene with the given name. The function from SceneDirector.cs that we want to be able to invoke from Yarn is called MoveCamera() and it looks like this:

// moves camera to camera location {location}>Camera in the scene
private void MoveCamera(Location location) {
    Transform destination = location.GetMarkerWithName("Camera");
    Camera.main.transform.position = destination.position;
    Camera.main.transform.rotation = destination.rotation;
}

It takes a Location in the Scene, from the eligible options Title, Corridor and Bridge. **It then finds the location and facing of the marker named Camera in that Location** and sets the camera location and facing to that of the marker.

If the camera moves to the Title location, the Title Layer element will fill the screen and appear as if a splash screen was being shown. If moved to the Corridor or Bridge locations, it acts as the point of view of the player who is then seen to be currently in that location. The default camera location is Title.

Here, we want to make a Yarn command called camera that takes a location name and knows to pass it off to the MoveCamera() function in C# to make it happen. This will mean when the player has to move to the bridge, the Yarn script can just say <<camera Bridge>>.

Making a command that can then be used in Yarn is as simple as registering a Command Handler. A Command Handler tells the Dialogue System that a Yarn command exists with a given name, how many additional pieces of information it needs, and which C# function to pass this information to when it's called. Then, when the game runs, the Dialogue System will handle talking to C# for you.

Command Handlers have two important requirements:

They must be created before the command can ever be called. Usually, this means you want to make it as part of the initial creation of the scene or the object it's attached to.
They must be attached to the Dialogue System's Dialogue Runner object. It's the thing passing lines of dialogue to the scene that has to know to change behaviour if the next line it receives is a command instead of dialogue.

To satisfy the first point, we can register any Command Handlers in a function called Awake() that every Unity object has by default. This function is called when the object is created, and because our empty Scene Director object is always in the Scene this means it gets created as soon as the Scene does. Registering Command Handlers in the Awake() function of this object therefore means they will be registered before anything else happens when the game is run.

To satisfy the second, we need to find the Dialogue Runner in the scene and assign it to a variable in C# that we can then attach Command Handlers to. Because there is only one Dialogue Runner in the Scene, we can find it by asking Unity to give us all the objects in can find in the Scene of type DialogueRunner.

Altogether, this means two simple lines in the Awake() function of SceneDirector.cs:

// find the Dialogue Runner
dialogueRunner = FindObjectOfType<Yarn.Unity.DialogueRunner>();
// register Command Handler for <<camera NAME_OF_LOCATION>>
dialogueRunner.AddCommandHandler<Location>("camera", MoveCamera);

The Dialogue Runner now supports a command called camerathat has a parameter of type Location and will defer to the function MoveCamera() to make it happen.

Return to the Yarn script and add commands of syntax <<camera (location name)>> to the appropriate places:

Add <<camera Corridor>> to the top of the Start node.
Add <<camera Bridge>> to the top of the node where characters should move to the bridge.
To show the title before the game begins, add <<camera Title>> at the top of Start and then a call to the inbuilt <<wait (number of seconds)>> command to hold for a second or two before moving to the Corridor.

If you hid the Title Layer object earlier, be sure to unhide it now by selecting it and re-ticking the box at the top of the Inspector. If necessary, unhide UI Layers and re-hide just the Fade Layer.

These minimal changes to the Yarn script...

title: Start
---
<<camera Title>>
<<wait 2>> // hold for 2 seconds before changing
<<camera Corridor>>
// ... [lines omitted]
===
title: BridgeEnding
---
// everyone reports to the bridge
<<camera Bridge>>
// ... [lines omitted]
===

...should now result in the camera moving around the empty environment in the appropriate points in the script. Returning to Unity, press the ▶️ button and playthrough to check this works correctly.

When Yarn script needs to pass an argument of a project-specific type (like Location is) it simply searches the scene for objects of that type with the given name, so make sure you spell and capitalise Location names exactly as they are in the Scene.

Onto the next command! Smash cuts are fine, but nice transitions are fancier. In the Scene there is a flat black layer called Fade Layer that sits in front of the camera. Changing its opacity can make the camera appear to fade to and from black. Back in SceneDirector.cs there is a line in the Awake() function that finds the objects of type Fade Layer in the Scene (there is only the one) and keeps it in a variable called fadeLayer, similar to how the Dialogue Runner was found earlier.

// find the Fade Layer
fadeLayer = FindObjectOfType<FadeLayer>();

Remember to unhide the Fade Layer if you hid it earlier, otherwise this command won't be able to find it. Re-tick the box at the top of the Inspector.

Then further down the file there are short functions called FadeIn() and FadeOut() that do just that, by changing the opacity of this stored layer over the given number of seconds (or defaulting to 1 second if no argument is provided).

// fades in from a black screen over {time} seconds
private Coroutine FadeIn(float time = 1f) {
    return StartCoroutine(fadeLayer.ChangeAlphaOverTime(0, time));
}

// fades out to a black screen over {time} seconds
private Coroutine FadeOut(float time = 1f) {
    return StartCoroutine(fadeLayer.ChangeAlphaOverTime(1, time));
}

These functions are a little different in that instead of returning nothing like the MoveCamera() function did, these functions return a Coroutine. This gives Yarn Spinner a handle to the process it triggered so that for operations that take time (like fading in a screen over a second or so) it knows not to trigger the next line of dialogue until that process has completed.

Again, the functionality that performs the actual opacity change is contained in a C# script attached to the relevant GameObject. In this case it is a file called FadeLayer.cs attached to the Fade Layer.

Adding commands for fadeIn and fadeOut works just like before. In the Awake() function of SceneDirector.cs by adding Command Handlers to the previously found Dialogue Runner.

// Handlers for <<fadeIn DURATION>> and <<fadeOut DURATION>>
dialogueRunner.AddCommandHandler<float>("fadeIn", FadeIn);
dialogueRunner.AddCommandHandler<float>("fadeOut", FadeOut);

Back in the Yarn script, add a <<fadeOut>> and <<fadeIn>> to either side of each camera or node change to make nice fade-to-black transitions between story parts. Because no argument is provided, this will perform a 1 second fade.

Including transitions between conversation nodes even if they occur in the same Corridor location will hide the characters appearing that will be implemented next.

All this took is a few more additions to the Yarn script:

title: Start
---
<<fadeIn>>
<<camera Title>>
<<wait 2>> // hold for 2 seconds before changing
<<fadeOut>>
<<camera Corridor>>
<<fadeIn>>
// ... [lines omitted]
===
title: TalkToEngineer
---
<<fadeOut>>
<<fadeIn>>
// ... [lines omitted]
===
title: TalkToCrewmate
---
<<fadeOut>>
<<fadeIn>>
// ... [lines omitted]
===
title: TalkToCaptain
---
<<fadeOut>>
<<fadeIn>>
// ... [lines omitted]
===
title: BridgeEnding
---
<<fadeOut>>
// everyone reports to the bridge
<<camera Bridge>>
<<fadeIn>>
// ... [lines omitted]
<<fadeOut>>
===

Character-Specific Commands

The next command will allow character models to be placed in the Scene whenever they are part of the current conversation. We could write these as before in SceneDirector.cs with a function that takes a Character to change and what to change about them, but instead we're going to try out another type of command.

This time, we're going to add commands to the script that's attached to each Character-typed object in the scene, found at Assets > Scripts > Character.cs. This script has three main functions we want to use: Move(), SetPose() and SetExpression().

In our example nobody ever leaves a location while the player is still there so there's no need to implement hide/show-like functionality; we can just cycle Characters between predefined Locations in the Scene.

First up in Character.cs, there is a function called Move() that accepts a Location object and the name of a marker in that Location. It looks very similar to the MoveCamera() function used earlier:

// moves character to location {location}>{markerName} in the scene
public void Move(Location location, string markerName) {
    Transform destination = location.GetMarkerWithName(markerName);
    transform.position = destination.position;
    transform.rotation = destination.rotation;
}

Much like before with MoveCamera(), Yarn Spinner is able to find the Game Object you are trying to command by searching the Scene for one with the right type and name. This is used to find the Location that should be passed as the first function argument, but also to specify the target Character this function should be called on.

So if we want a command like <<place (location) (marker name)>> we need to add an extra argument in between to specify the target Character object: <<place (character) (loc...>>.

But this can't be done like before with a Command Handler registered when the object is created. Because Character.cs is attached to every Character object in the Scene, the Awake() function would be called every time any Character was created. This would result in the Dialogue Runner receiving multiple registrations of command with the same name but that are requested to pass off to different objects. Yarn Spinner won't allow that, so we have to instead annotate the relevant functions using the Yarn Command decorator.

Declaring a Yarn Command is as simple as adding [YarnCommand("command name")] to the declaration of a function. Add the following decorator to just above the Move() function:

// moves character to location {location}>{markerName} in the scene
[YarnCommand("place")]
public void Move(Location location, string markerName) {

Now in the Yarn script, just add commands to move the relevant Character to the desired marker in the current Location by adding <<place (character name) (location) (marker name)>> wherever needed. Placing characters before calling <<fadeIn>> will ensure they are there before the shot appears, so the Character won't seem to pop into existence a fraction later.

Just a handful of additions to the Yarn script:

// ... [lines omitted]
title: TalkToEngineer
---
<<fadeOut>>
<<place Engineer Corridor Left>>
<<fadeIn>>
// ... [lines omitted]
===
title: TalkToCrewmate
---
<<fadeOut>>
<<place Crewmate Corridor Center>>
<<fadeIn>>
// ... [lines omitted]
===
title: TalkToCaptain
---
<<fadeOut>>
<<place Captain Corridor Right>>
<<fadeIn>>
// ... [lines omitted]
===
title: BridgeEnding
---
<<fadeOut>>
// everyone reports to the bridge
<<camera Bridge>>
<<place Engineer Bridge Left>>
<<place Crewmate Bridge Center>>
<<place Captain Bridge Right>>
<<fadeIn>>
// ... [lines omitted]
===

And now our Characters appear in the Scene whenever they're part of the current conversation.

Next, we're going to add some pose and facial expression changes to make Characters respond to the changing mood of the story. Primarily because it's a bit weird that everyone looks so cheerful during a crisis...

The SetPose() function in Character.cs accepts the name of a pose and tells the animator attached to the Character model to move the model to that pose. The available poses for each model are defined by their underlying type seen in Assets > Art > CharacterBaseModels and the Asset Package has come with the following for both male and female models:

neutral
hand-on-hip
arms-out
hand-at-mouth
pointing
hands-on-hips

Mostly these just move their arms into different basic positions. The function looks like this:

// tell the animator to jump to state {poseName} 
public void SetPose(string poseName) {
    animator.Play("Base Layer." + poseName, 0);
}

As with the place command, add a decorator to SetPose() to declare a command called pose.

[YarnCommand("pose")]
public void SetPose(string poseName) {

Now characters can be moved using <<pose (character) (pose name)>> wherever called for in the script. In particular, adding appropriately unhappy-looking poses during the Bridge scene will make Characters seem to respond to the story.

title: BridgeEnding
---
// ... [lines omitted]
<<pose Engineer hands-on-hips>>
<<pose Captain hand-at-mouth>>
<<fadeIn>>
Captain: Pirates!
Player: Oh no!
<<pose Captain pointing>>
// ... [lines omitted]
===

Next, do the exact same thing for expressions. The options included for each character in the Asset Package are:

neutral
happy
angry
smirk
surprised

Facial expressions for the included characters are just a texture applied to the model's face, so changing expression just means asking the texture renderer to change face texture.

// sets character expression texture to {expressionName} texture
public void SetExpression(string expressionName){
    // find the expression with the same name as we are looking for
    Expression expressionToUse = FindExpressionWithName(expressionName);
    SetFaceTexture(expressionToUse.texture);
}

Decorate with [YarnCommand("expression")] and, back in the Yarn script, place calls to <<expression (character) (expression name)>> wherever appropriate.

And that's it for commands! We successfully implemented commads to:

Move the Camera to preset locations, as if the player is moving.
Turn on and off UI elements, to create nice transitions during Scene changes.
Move Character models to preset locations, as if they are entering and exiting the Scene.
Change Character model animations and textures, as if they are showing different emotions.

Draw the Rest of the Owl

Now that all the commands are hooked up and the skeleton story plays through correctly, it's time to replace the skeleton placeholder script with the full story. In Assets > Dialogue find the file SpaceJourney_FinalVersion.yarn. In the Yarn Project created earlier, replace the script you placed in Source Scripts earlier with this script instead.

Result

A playable visual novel-type game with multiple characters and scenes and sensible transitions between them.

Or you could try your hand at C# and create more advanced commands that can be made available to Yarn. Add new Locations, or camera motion. The sky's the limit! Yarn Spinner is perfect for allowing iterative and creative development.

Now, let's move onto an example that uses Yarn Spinner to run different dialogue based on players interacting with different NPCs...

Yarn Spinner 2.1

Start Here

Welcome to Yarn Spinner!

Writing Your Dialogue

Editing with VS Code

Installing the Extension

Writing Yarn in VS Code

Making a new .yarn file

Opening an existing .yarn file

Writing in Yarn

Flow Control

if statements

elseif and else

Conditional Options

Commands

Built-in Commands

wait

stop

Making Your Own Commands

Upgrading Yarn Scripts

Working With Unity

Overview

Quick Start

Setting Up A Demo Scene

Importing Yarn Files

Yarn Scripts

Creating a New File

Editing Yarn Scripts

Components

Dialogue Views

Options List View

Inspector

Option View

Inspector

Variable Storage

In-Memory Variable Storage

Inspector

Custom Variable Storage Components

Line Provider

Text Line Provider

Inspector

Audio Line Provider

Inspector

Unity Sample Projects

Guides

About

The Team

Yarn Spinner Timeline

About Secret Lab

GitHub Repositories

Community Projects

API Documentation

C#

Any

Summary

Boolean

Summary

Number

Summary

String

Summary

TypeMappings

Summary

Text

Summary

CommandHandler

Summary

Parameters

See Also

DefaultStartNodeName

Summary

Dialogue(Yarn.IVariableStorage)

Summary

Parameters

AddProgram(Program)

Summary

Remarks

Parameters

Continue()

Summary

`if` statements

`elseif` and `else`

`wait`

`stop`