Yarn Spinner is a set of friendly tools for writing interactive narratives and games.

Yarn Spinner is easy for writers to use, but also has powerful features for programmers, game designers, narrative directors, producers, and more.

Yarn Spinner is used in thousands of amazing games, including Rift of the Necrodancer, Night in the Woods, A Short Hike, Lost in Random, Dredge, Frog Detective, Button City, Escape Academy, Baladins, and Unbeatable.

What to do next

Yarn Spinner powers amazing games, including:

... use it to power your game too!

Yarn Spinner 3 is out! It's the culmination of 10 years of Yarn Spinner development, taking inspiration from how people use Yarn Spinner in wildly successful and amazing games like DREDGE, Lil' Guardsman, A Short Hike, and Demonschool.

For the development of Yarn Spinner 3, stewardship of Yarn Spinner moved from our original game development studio, Secret Lab, to a whole new entity focused solely on Yarn Spinner development. It's now our primary job!

Yarn Spinner is developed in the open on GitHub, and can be purchased from the Yarn Spinner Itch.io Store or the Unity Asset Store.

Yarn Spinner 3 introduces so many improvements and new things, and makes writing complex interactive narratives easier than ever.

Get started with Yarn Spinner 3 via the Beginner's Guide!

Yarn Spinner powers amazing games, including:

... use it to power your game too!

Yarn Spinner is built by Yarn Spinner Pty. Ltd., an Australian company based in beautiful Lutruwita/Tasmania, Palawa/Tasmanian Aboriginal country, in Australia.

Yarn Spinner Pty. Ltd. was founded by the team that created Yarn Spinner—Jon Manning, Tim Nugent, and Paris Buttfield-Addison—all colleagues and contributors at Secret Lab, a game development studio, known for Night in the Woods, I Feel Fine, Leonardo's Moon Ship, the Australian ABC Play School games, and more.

Yarn Spinner is now maintained by the Yarn Spinner Pty. Ltd. team, including:

• Jon Manning

• Tim Nugent

• Paris Buttfield-Addison

• Mars Buttfield-Addison

You can find Yarn Spinner on Bluesky too!

Yarn Spinner Timeline

• v0.9 was released in October 2015, the first public release;

• v1.0 was released in January 2020;

• v2.0 was released in December 2021;

• v2.1 was released in February 2022;

• v2.2 was released in April 2022;

• v2.3 was released in July 2023;

• v2.4 was released in November 2023;

• v2.5 was released in December 2024.

• v3.0 was released in May 2025.

About Yarn Spinner Pty. Ltd.

Yarn Spinner Pty. Ltd. is a tools development company located in Hobart, Australia. Yarn Spinner designs and builds the open source Yarn Spinner project, and offers consulting, integration, and development services for custom Yarn Spinner integrations, features, and more.

Yarn Spinner's core team are also the founders and long-term team collaborators of Secret Lab Pty. Ltd.

About Secret Lab Pty. Ltd.

Secret Lab Pty. Ltd. is an independent games and creative technology studio located in Hobart, Australia.

Secret Lab has been enthusiastically building video games, apps, and technology to showcase culture, history, arts, and narrative experiences since 2008, and is the longest running games studio in Tasmania.

Secret Lab is proud to be the original creators of Yarn Spinner, and is best known for the BAFTA- and IGF-winning Night in the Woods, and is currently working on the interactive narrative game, I Feel Fine (written by Ryan North), and the adventure-puzzle game, Leonardo's Moon Ship (written by writer of Pixar's Ratatouille, Jim Capobianco).

You can hire Secret Lab to build your video games, interactive experiences, fancy apps, and more.

If you're here, you've worked through the , and setup the , and you're ready to dive into the details of writing dialogue with Yarn Spinner.

This section of the documentation will take you through the scripting fundamentals:

• combining Nodes, Lines, Options, and Jumps for simple interactive narratives

• using Detours, Variables, and Yarn Spinner's Flow Control features for more complex interactions

• the basics of Commands and Functions in Yarn Spinner

• running options Once, and Line Groups for flexibility and control

Once you've completed it, you can move to .

In Yarn Spinner Scripts, shadow lines let you reuse the same line in multiple places, without having to create duplicate copies.

Shadow lines are marked using the #shadow: hashtag. When you use the #shadow: tag, you specify the line ID of another line, which is called the source line. The source line must have an explicit #line: hashtag to identify it.

Here’s a simple example of using shadow lines:

The script contains six lines, but only 5 string table entries will be created, because the line “I should go” is shadowed.

Shadow lines are required to have the same text in the Yarn script as their source line, but are allowed to have different hashtags (in addition to the #shadow: and #line: hashtags).

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

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

• are files that contain your written dialogue.

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

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

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

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

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

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

Welcome to Yarn Spinner! We're thrilled you're here.

This section will equip you with all the knowledge you need to write Yarn Spinner Scripts. Work through the following steps, one-by-one:

Once you've finished here in the Writing Yarn Scripts section, you will progress to the First Steps of using Yarn Spinner for Game Engines.

If you're here, you've worked through the Beginner's Guide, setup the Yarn Spinner Editor, and learned the Scripting Fundamentals of Yarn Spinner.

Now it's time to look at some more advanced features, including:

• Node Groups, Storylets, and Saliency, for complex, responsive storytelling with Yarn Spinner

• Tags and Metadata, to give you flexibility on how your lines are handled in a game engine

• Markup, for providing hints on how narrative text should be displayed, as well as running commands in a game engine within lines

• Shadow Lines, for marking when a line is an identical duplicate of another line

• Writing Together, using the Live Share Extension for Visual Studio Code.

Once you've completed it, you're ready to use Yarn Spinner with a game engine, such as 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.

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

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

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

Storylets and Saliency are a new feature of Yarn Spinner 3 that has quite a few different pieces to making it work. Because of this we have multiple samples dedicated to demonstrating these.

The samples are not about the concept of storylets and saliency, if you are new to this and wondering what this all means, then we highly recommend our Storylets and Saliency Primer.

The samples assume you are comfortable now with both the concepts of storylets and salient content and writing them in Yarn Spinner.

There are three samples around using storylets and saliency in Yarn Spinner for Unity:

• Basic Storylets and Saliency goes over the basics of using storylets in your games

• Custom Saliency Strategies looks at how you can create custom saliency strategies

• Advanced Saliency demonstrates using storylets and interpolation together to build entire dynamic stories and events.

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:

public bool TryGetValue<T>(string variableName, out T result);
public void SetValue(string variableName, string stringValue);
public void SetValue(string variableName, float floatValue);
public void SetValue(string variableName, bool boolValue);
public void Clear();
public bool Contains(string variableName);

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

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

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

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

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

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

In Yarn Spinner, enums let you create variables whose value is constrained to a pre-defined list of possibilities.

To define an enum you must provide a name, and some cases for it. Here's a new enum called Food with the cases Apple, Orange, and Pear:

<<enum Food>>
  <<case Apple>>
  <<case Orange>>
  <<case Pear>>
<<endenum>>

Once you've created an enum, you can use it just like any other variable:

// Declare a new variable with the default value Food.Apple
<<declare $favouriteFood = Food.Apple>>

// You can set $favouriteFood to the 'apple', 'orange' or 'pear'
// cases, but nothing else!
<<set $favouriteFood to Food.Orange>>

// You can use enums in if statements, like any other type of value:
<<if $favouriteFood == Food.Apple>>
  I love apples!
<<endif>>

// You can even skip the name of the enum if Yarn Spinner can 
// figure it out from context!
<<set $favouriteFood = .Pear>>

Unity Localised Line Provider is a Line Provider that fetches localized text and assets for a line of dialogue from a String Table and optionally from an Asset Table, based on the project's current localization settings.

Inspector

A Yarn script is a text file containing your dialogue.

Creating a New File

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

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

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

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

Editing Yarn Scripts

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

Writing Yarn with Try Yarn Spinner

When you first start learning Yarn, you can use , our introductory, browser- based tool for writing Yarn Spinner Scripts. No installation necessary!

What did we just do?

We just wrote a simple Yarn Spinner script consisting of one node (titled Start), with one line inside that node, delivering a greeting from a narrator.

Then we added two more nodes, a jump command, and some options, with jumps occuring depending on the option chosen.

And that's the very basics of Yarn Spinner Scripting! Dive into the of Writing Yarn Scripts next.

Back in the , you learned the basics of Yarn Spinner Scripting by using our online tool, Try Yarn Spinner.

While Try Yarn Spinner is great for the basics, and for experimenting, when you start creating more complex narratives, you need a great editor! It's time to meet Yarn Spinner for Visual Studio Code.

Yarn Spinner for Visual Studio Code

Yarn Spinner for Visual Studio Code is an extension for the free text editor, Visual Studio Code ("VS Code").

Yarn Spinner for Visual Studio Code gives you syntax highlighting for Yarn Spinner Scripts, as well as a graph view that displays the nodes, and relationships between the nodes, and a whole bunch of other useful features that we'll be exploring as we learn the to write Yarn Spinner Scripts using Visual Studio Code.

If you've never used to VS Code before, for your operating system and platform before continuing.

Don't be too alarmed by the AI-powered nonsense Microsoft will try and sell you. You can disable most of the AI "features" via the Command Palette by pressing Shift + Command + P (Mac) or Ctrl + Shift + P (Windows/Linux), or choosing the View menu -> Command Palette..., and typing Chat: Hide Copilot and hitting Return/Enter:

Installing Yarn Spinner for Visual Studio Code

Once you've got VS Code installed on your system, you'll need to install Yarn Spinner for Visual Studio Code. To do this:

That's all you need to do to install the extension! You're ready to .

You can run your Yarn Spinner Scripts inside the Visual Studio Code extension, without having to import it into a game or run it via a game engine.

This means that you can write content for your game even if the game isn't yet ready to have dialogue added to it. It's also useful for quickly checking to see if your Yarn script works the way that you want it to before testing it in your game.

Showing the Dialogue Preview

To preview your dialogue in Visual Studio Code, open the Command Palette by pressing Command-Shift-P (Control-Shift-P on Windows), and type "Preview Dialogue". Your current Yarn project will open to the side, and you can begin playing through your script.

Preview Features

While playing through your dialogue in preview mode, there are several features that can be useful to test out a script.

• Changing the starting node: By default, the dialogue preview will start playing from a node named "Start", if one is present in your Yarn files. If you want to play from a different node, open the list of nodes and choose the node you want to start from.

• Changing whether lines are shown one at a time, or all at once: By default, the dialogue preview shows each line and command one and a time. You can change this to delivering everything all at once by opening the Settings menu and changing the setting to "Show Lines All At Once".

• Showing the contents of variables: You can see the current contents of all in your script by opening the Settings menu and choosing "Show Variables". A list of variables will appear, and as you play through your script, they'll update when your script changes their contents.

• Changing whether 'unavailable' lines are shown: Options can be depending on whether or not a test has passed. By default, options that fail this test are not shown in the dialogue preview at all; to change this to showing all options (including ones that the user can't choose), open the Settings menu and choose "Show Unavailable Options".

• Restarting the script: When you click the Restart button, the dialogue preview will restart from the currently selected starting node.

Exporting Your Script

You can export a stand-alone HTML file containing a runnable version of your Yarn script, which you can send to other people for them to play. This can be particularly useful for writers who want to get feedback on their scripts before working with other team members to integrate their content.

To export your script, click the Export button, and choose where to save the file. The file can then be sent anywhere you like, and can be opened in all major web browsers.

In addition to using the to move between nodes, you can also use a detour command.

A detour command looks very simlar to jump: it takes a single parameter with the title of the node you want to move to, but unlike the jump command the detour command will return to the node that called it afterwards.

Using the Detour Command

The detour command works much like the jump command, except it will return to the node it detoured from after that node is done. Here’s an example of it in action:

If the player replies No? to the guard’s question, Yarn Spinner will detour to the node titled Guard_Backstory and run its contents.

When the end of the Guard_Backstory node is reached, Yarn Spinner will return to the node titled Guard, and resume from just after the detour statement.

Using Detour with the Return Command

When you detour into a node, Yarn Spinner runs the content from that node just as if you’d used a jump statement. When you reach the end of the node, or reach a return command, Yarn Spinner will return to just after the detour command. A return command looks like <<return>>. There are no parameters.

You can return early from a detoured node by using the return command. Doing so will return to just after the detour command as though the end of the node had been reached, for example:

When you detour into a node, that node can itself detour into other nodes. If a detoured node uses a jump command to run another node, the return stack is cleared. If you detour into a node, and that node jumps to another node, Yarn Spinner won’t return to your original detour site.

When you use <<detour>> command, they'll be shown in the Graph View in Yarn Spinner for Visual Studio Code as an line with an arrow at each end, from the node that's being detoured to the node that's being detoured to:

Write some Detour Commands

Next up, learn about in Yarn Spinner Scripts.

Sometimes it's useful to create lines of dialogue that can only ever be displayed once.

In Yarn Spinner Scripts, you can use a once statement to denote content that can only be run one single time. When the script reaches a once statement, it checks to see if it’s run before. If it has, it skips over it! Magic.

There are two main ways you can use a once statement, which we'll explore below.

You can wrap some lines in <<once>> and <<endonce>>:

You can also use an <<else>> clause within the <<once>> statement, which will be run if the relevant <<once>> content has already been seen:

You can also add an if to the once to run content a single time, but only when a certain condition is true. In all other cases, it will be skipped (or the else content will be run, if there is any):

You can add <<once>> to a line, or options:

If you add once (or once if) to a line, that line will only appear once, and will be skipped over every other time it’s encountered:

Similarly, if you add it to an option, that option will only be selectable once, and will be marked as unavailable after it’s been selected.

once statements are really useful when you want to show long, detailed content the first time it’s encountered, but you don’t want to show it every time. This means that players don’t need to mash the ‘skip line’ button over and over when they realise that they’re starting to see a long run of lines they’ve already seen:

In Yarn Spinner, you can also create node groups. A node group is collection of nodes that share the same name that Yarn Spinner will choose from.

To create a node group, you create multiple nodes that all share the same name, and ensure that each of the nodes have at least one when: header.

The when:header tells Yarn Spinner about the conditions that must be met in order to run the node:

Node groups are combined into a single node that performs the appropriate checks and then runs one of the node group’s members. You start dialogue with a node group using its name. You can also use the jump or detour statements to run a node group from somewhere else in your Yarn scripts.

Node groups will be visualised in a box of their own in the Graph View of Yarn Spinner for Visual Studio Code:

You can add as many when: headers to a node as you want.

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.

If you're here to get started, continue by diving into the page.

You can purchase Speech Bubbles for Yarn Spinner from the or the .

Once you've purchased it, download the package from the store. It will be in the form of a .unitypackage file. To install the package, open the Unity project that you want to add it to, and open the the Assets menu -> Import Package -> Custom Package...

You'll then be able to select the .unitypackage file for Speech Bubbles for Yarn Spinner on your file system, and click Open. This will present the Import Unity Package window:

Click the Import button, and Speech Bubbles for Yarn Spinner will be imported into your project.

The Speech Bubbles add-on comes has two packages inside the unitypackage, one for the speech bubbles themselves, and one for the Yarn Spinner Samples. The samples contain necessary resources for the two speech bubble examples but if you already have the you do not need to add them again.

To give your dialogue more life and variety, you can also provide lines in a line group. When lines are in a line group, Yarn Spinner will choose one of them for you.

Line groups are collections of lines that begin with a => symbol:

In this example, the Captain will say "Navigator, fire the glitter torpedoes! That'll confuse the enemy ships!", and then Yarn Spinner will choose one of the subsequent lines to respond with.

You can attach conditions to lines in a line group, to ensure that they only run when it’s appropriate to do so. Conditions can be any true or false expression, and can also be combined with the once keyword to ensure that a line can only run once:

A line in a line group can also have additional lines belonging to it, which will run if the item is selected.

A Dialogue Presenter is a 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 Presenters. For example, in most situations, you'll have a Dialogue Presenter that's designed to display lines of dialogue:

...and another that's in charge of displaying options to the player:

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

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

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

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

Speech Bubbles for Yarn Spinner ships with two example scenes, showcasing the flexibility of the Speech Bubbles.

2D Sidescroller

The 2D Sidescroller Example showcases the flexibility of the Speech Bubble in a variety of contexts, including both the Formal Bubble, and the Casual Bubble. Once you've installed the package, find this example in Speech Bubbles for Yarn Spinner/Examples/2D Sidescroller.

3D Top-Down

The 3D Top-Down Example showcases the Speech Bubbles in a 3D environment, with a variety of small customisations. Once you've installed the package, find this example in Speech Bubbles for Yarn Spinner/Examples/3D Top-Down.

📦 Installation for Godot

Download a from the , or clone the repository somewhere.

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

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

Next, choose the Project menu -> Tools -> C# -> Create C# solution. This will create a C# project for you. We have to do this to trigger the creation of the .csproj file, which is necessary to let Godot know about the Yarn Spinner plugin.

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

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

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

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

With that, you're ready to go!

Dialogue Wheel for Yarn Spinner ships with two example scenes, showcasing the flexibiltiy of the Dialogue Wheel.

Automatic-Layout Dialogue Wheel Example

This example shows off the Automatic-Layout Dialogue Wheel, with an ever-increasing number of options being displayed. Once you've installed the package, find this example in Dialogue Wheel for Yarn Spinner/Examples/Automatic Layout Example.

Image Dialogue Wheel Example

This example shows the Image Wheel in action, with a very simple third-person sci-fi game. Once you've installed the package, find this example in Dialogue Wheel for Yarn Spinner/Examples/Image Wheel Example.

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.

Inspector

Yarn Spinner Timeline

• v0.9 was released in October 2015, the first public release;

• v1.0 was released in January 2020;

• v2.0 was released in December 2021;

• v2.1 was released in February 2022;

• v2.2 was released in April 2022;

• v2.3 was released in July 2023;

• v2.4 was released in November 2023;

• v2.5 was released in December 2024.

• v3.0 was released in May 2025.

Yarn Spinner 3

Yarn Spinner 3 came out in May 2025, adding new features to run content only once, enumerations, smart variables, and storylets and saliency!

Yarn Spinner 2

Yarn Spinner 2 debuted in July 2020, adding markup support, dialogue views, and lots lots more!

Yarn Spinner 1

After being developed for Night in the Woods, and staying in early-release for several years, Yarn Spinner 1 was released in January 2020!

Smart variables in Yarn Spinner are a powerful way to improve your dialogue and narrative flows. Unlike regular variables that only change when explicitly set, smart variables recalculate their value every time they're accessed, based on the expression that defines them.

Why Use Smart Variables?

1. Code Readability: They make your dialogue scripts more readable by using meaningful names instead of complex conditions.

2. Centralised Logic: Define a condition once and use it throughout your game.

3. Maintenance: When game mechanics change, you only need to update the smart variable declaration, not every place it's used.

4. Abstraction: They hide complex game state checks behind simple, descriptive names.

Practical Examples

Creating a smart variable in Yarn Spinner is straightforward: <<declare>> command followed by a variable name (with the $ prefix) and assign it an rather than a static value. The expression can use , or even reference other variables.

For example: <<declare $is_powerful = $strength > 50 && $magic_ability >= 20>>.

This smart variable will automatically update whenever the values of $strength or $magic_ability change, making your dialogue able to dynamically respond to the player's stats without additional code.

Example 1: Character Relationships

Example 2: Item Availability

Example 3: Time-Based Events

Benefits in Complex Games

Smart variables shine when you have conditions that you check frequently or that combine multiple factors. They're especially useful for:

• Tracking complex character states

• Monitoring game world conditions

• Representing player achievements or quest status

• Creating dynamic dialogue that responds to multiple game systems

By using smart variables, you make your dialogue scripts more intuitive and maintainable while keeping your game logic organised.

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.

Inspector

The Built-in Localised Line Provider is a Line Provider that fetches localized text or audio assets (AudioClip) for a line of dialogue, given the user's language.

The Built-in Localised Line Provider will automatically use Addressable Assets, if the Addressables package is installed in your Unity project and the is configured to use Addressable Assets.

Inspector

You can purchase Dialogue Wheel for Yarn Spinner from the or the .

Once you've purchased it, download the package from the store. It will be in the form of a .unitypackage file. To install the package, open the Unity project that you want to add it to, and open the the Assets menu -> Import Package -> Custom Package...

You'll then be able to select the .unitypackage file for Dialogue Wheel for Yarn Spinner on your file system, and click Open. This will present the Import Unity Package window:

Click the Import button, and Dialogue Wheel for Yarn Spinner will be imported into your project.

The Dialogue Wheel add-on comes has two packages inside the unitypackage, one for the wheels themselves, and one for the Yarn Spinner Samples. The samples contain necessary resources for the two wheel examples but if you already have the you do not need to add them again.

Next, check out the guides on , or .

This Unity package provides two prefabs: Formal Bubble and Casual Bubble. The package requires Yarn Spinner for Unity.

This add-on is not part of the open source Yarn Spinner package, and can be or via the .

Speech Bubbles for Yarn Spinner provides a Casual Bubble and a Formal Bubble prefab. Both are customisable, powerful, and extremely flexible:

• customise fonts, colours, and styles of bubbles

• optional character nameplate

• flexible anchor point for bubble stem

• lock bubbles to camera, or not, your choice

• works for 2D or 3D games

This guide provides documentation on using the bubbles and both prefabs.

Speech Bubble Architecture

The design of the Speech Bubbles are slightly different to how most custom dialogue presenters, or even the default presenters, work. At first glance it might not be obvious as to what each piece does, that is what this section is for.

Bubble Dialogue View

The Bubble Dialogue View is the subclass and is what talks to the for the relevant events in the story. The Bubble Dialogue View manages all the various bubbles that will need to be shown on screen, in particular it controls when to create and destroy them and gives them the content they need to show. The Bubble Dialogue View is a essentially a middle-man between the actual game objects shown on screen and Yarn Spinner.

Bubbles and Bubble Content

The Bubble and Bubble Content are the two classes that control where and what is shown on the screen. The Bubble manages positioning information, determining where to best place the canvas rectangle. What a Bubble appears like, so it's shape, text, colours, and so on are determined by it's Bubble Content.

The Bubble Content represents a single piece of content. So each line that needs to be shown is a piece of content, the collection of options is another piece of content. The Bubble then shows this piece of content, and when a new piece of content comes in removes the old and shows the new. The Bubble gets given this Bubble Content to show by it's Bubble Dialogue View. The specific information contained within a Bubble Content changes depending on what needs to be shown to the player, the most common information is the line.

The reason for this split is because the way a bubble determines where to place itself is not significantly impacted by it's content. Only the size of the text inside the content changes this, the rest is the same no matter what. This means a great deal of code could be extracted and kept generic from the rest of the presentation. This means making visually unique bubbles is now easier by subclassing the Bubble Content, all the positioning code can be reused for every visually different bubble.

Bubble Input

The last class that operates in a different manner from the Yarn Spinner norm is the Bubble Input. When the user wants to hurry up or skip lines in Yarn Spinner this is handled by the , Speech Bubbles however are a bit different in this respect. Because they can only show a single option at a time they need to have a way to also support changing between which option is currently being shown by the bubble, this is what the Bubble Input does.

The Line Advancer is still a part of the equation, as hurrying up lines is still something people will want to do with Speech Bubbles, however it is no longer directly configured by you in the editor. Instead Bubble Input has a reference to the Line Advancer and it will set the appropriate values. This is just to avoid having to change two objects at once, however if you do want to have this behaviour the Bubble Input has a toggle called Independent Advancer Configuration where if set means the Bubble Input won't attempt to change the configuration of the Line Advancer.

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

<<wait 2>>
<<setsprite ShipName happy>>
<<fade_out 1.5>>

Commands are sent to your game's Dialogue Runner, 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 define your own custom commands 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.

// Wait for 2 seconds
<<wait 2>>

// Wait for half a second
<<wait 0.5>>

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.

// Leave the dialogue now
<<stop>>

// Leave the dialogue if we don't have enough money
<<if $money < 50>>
    Shopkeeper: You can't afford my pies!
    <<stop>>
<<endif>>

Making Your Own Commands

You can create your own commands, so that your scripts can send directions to your game. For more information on how to create them in Unity games, see Creating Commands and Functions, in the Yarn Spinner for Unity section of the documentation, and equivalents for other engines.

Yarn Spinner is always free and open source. To help offset the costs of designing, building, and supporting Yarn Spinner, we provide a number of add-ons as paid extras to make implementing Yarn Spinner in your games easier for you.

At the moment, these include:

• Dialogue Wheel for Yarn Spinner

• Speech Bubbles for Yarn Spinner

You can purchase both of these on the Yarn Spinner Itch.io Store or via the Unity Asset Store.

This section of the Yarn Spinner documentation provides guides for the available add-ons.

Yarn Spinner 3 introduced a new system for selecting which content should be presented next, called Saliency Strategies. Whenever it's time to select the next piece of salient content from node groups or line groups, Yarn Spinner consults its saliency strategy to determine which piece should be chosen.

This guide explores an implementation provided in our Custom Saliency Strategies Sample.

While we provide several built-in saliency strategies that cover common scenarios, we can't anticipate every possible need. That's where custom strategies come in, which is the focus of this sample. We'll demonstrate how to create a new custom saliency strategy to meet specific requirements.

What we'll be covering

• Creating new saliency strategies through the IContentSaliencyStrategy interface

• Reading line metadata

• Reading node headers

IContentSaliencyStrategy

The IContentSaliencyStrategy interface requires implementing just two methods: QueryBestContent and ContentWasSelected.

• QueryBestContent: Called when Yarn Spinner asks, "If I were to run this block of content, what would be selected?"

• ContentWasSelected: Called when Yarn Spinner informs the strategy, "This specific piece has been chosen"

When Yarn Spinner needs to select a piece of salient content, it first asks its strategy what content would be selected (QueryBestContent) and then selects it and informs the strategy of this selection (ContentWasSelected).

You might wonder why this functionality is split into two methods, especially when the first call is often immediately followed by the second. For many saliency strategies, it won't matter - querying and selecting can effectively be the same operation, with the only required state being the list of content to analyze.

However, other strategies require maintaining state that would be affected if selection and querying were combined. For example, the built-in "Best Least Recently Viewed" strategy tracks which content it has shown previously to avoid showing the same piece of content twice in a row. Each time it selects content, it marks it as seen, which deprioritizes that specific content for future selections.

This design creates a clear separation: QueryBestContent is non-mutating, while ContentWasSelected can modify state. The alternative would be to prevent querying available content altogether, but this would be too limiting - it would prevent you from checking whether content is available, which might be useful for showing indicators that an NPC has something to say.

Weighted Saliency

The sample includes a custom saliency strategy in WeightedSaliencySelector.cs. This strategy assigns a custom weight to each storylet, as specified by the writer, and uses these weights to determine the probability of each storylet being shown.

Each piece of salient content is given a range proportional to its weight, and then one is chosen randomly from the combined range of all weights. In practical terms, given the following line group:

=> I am line A #weight:2
=> I am line B #weight:1

"I am line A" will be shown approximately two-thirds of the time, while "I am line B" will appear approximately one-third of the time.

When asked for the best content, the strategy first filters out any content with failing conditions. After this filtering, we're left with content where all conditions (line conditions or when headers) have evaluated to true. The next step is to determine the weighting for each piece of content.

Our weighted saliency strategy supports both line groups and node groups, which require slightly different approaches:

For node groups, we look for the weight header in the node headers:

weightString = runner.Dialogue.GetHeaderValue(element.ContentID, WeightKey)

For line groups, we look for the weight tag in the metadata:

var lineKey = WeightKey + ':';
foreach (var metadata in runner.YarnProject.lineMetadata.GetMetadata(element.ContentID))
{
    if (metadata.StartsWith(lineKey))
    {
        weightString = metadata.Substring(lineKey.Length).Trim();
        break;
    }
}

Once we have the string values for weights, we convert them to integers. If the conversion fails, or if there isn't a weight value in the headers or metadata, we assign a default weight of one.

With the weights established, we build a list of ranges representing those weights. Finally, we generate a random number within the combined size of all ranges and use that to select which content to present.

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

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

Inspector

Basic Yarn Spinner for Unity Usage

1. Install Unity 2022.3 or newer.

2. Create a new empty Unity project, by following the instructions in the Unity manual.

3. Install Yarn Spinner into the project, by following the instructions in Installation for Unity.

4. Add a Dialogue System to the scene:, by opening the GameObject menu and choosing Yarn Spinner -> Dialogue System.

5. Create a new Yarn Spinner Script, by opening the Assets menu and choosing Create -> Yarn Spinner -> Yarn Script. Name the new file HelloYarn.

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

title: Start
---
Wow!
My first ever Yarn script in Unity!

-> Gosh!
-> Incredible!
-> I'm amazed!

Anyway, time to get writing!
===

1. Save the file and return to Unity.

2. Create a new Yarn Project 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. Projects are collections of Yarn scripts that get compiled together, and can be used with a Dialogue Runner.

3. Make the Dialogue Runner use the Project by dragging the Project you just made into the Dialogue Runner's Yarn Project field.

4. Play the game by clicking the Play button at the top of the window. Your dialogue will appear!

A Line Advancer listens for user input and sends requests to a Dialogue Runner to advance the presentation of the current line, either by asking a dialogue runner to hurry up its delivery, advance to the next line, or cancel the entire dialogue session.

A Line Advancer is generally used to implement a 'press spacebar to continue/skip' mechanic.

To use a Line Advancer, create a new game object, and attach a Line Advancer component to it using the Add Component button.

You can control what specific input the component is looking for by changing the Continue Action Type setting:

• If you set the Input Mode to Key Code, you can select a key on the keyboard that will continue to the next line on press, or hurry up.

• If you set the Input Mode to Input Actions, you can create an Action from an input device (such as from a keyboard, gamepad, or other method).

Yarn Spinner version 3 introduces a powerful new way to trigger events during dialogue presentation. While previous versions required custom implementations for in-line actions, v3 provides the IActionMarkupHandler interface. This system notifies handlers about key line presentation events, enabling you to respond at specific moments.

This approach offers tremendous flexibility for creating various inline events. Our sample demonstrates two practical applications: character movement and facial expression changes during dialogue presentation.

This guide explores the contents of the Inline Events Sample.

What we'll be covering

• The new IActionMarkupHandler interface

• The new ActionMarkupHandler class

• Using these with the Line Presenter to trigger events

• Two implementations: character movement and animation changes

The Action Markup Handler

The IActionMarkupHandler interface provides a structured approach to handling in-line actions during dialogue presentation. At its core, the system works by having the Line Presenter display dialogue one character at a time, notifying handlers throughout the process. This creates multiple opportunities to trigger events at precise moments.

The interface defines methods corresponding to different stages of the line presentation lifecycle:

1. Initial Preparation (OnPrepareForLine): Called immediately after the line is received but before any UI elements appear.

2. Display Start (OnLineDisplayBegin): Called just before characters begin appearing, but after UI elements are visible.

3. Character Display (OnCharacterWillAppear): Called each time a character in the line is about to be displayed.

4. Display Completion (OnLineDisplayComplete): Called after all characters in the line have been shown.

5. Dismissal (OnLineWillDismiss): Called just before the line will be dismissed.

Notably, OnCharacterWillAppear is an asynchronous method. The line presentation system will await each Action Markup Handler's completion before continuing, allowing events of any duration to occur at any point in the dialogue.

Yarn Spinner also provides ActionMarkupHandler, a MonoBehaviour implementation of this interface, for situations where you need component-based functionality. The Line Presenter includes a serialized field for directly connecting ActionMarkupHandler subclasses, as demonstrated in our sample.

The Sample

Our sample showcases two types of action markup: moving the player character and changing NPC facial expressions. Both are implemented as ActionMarkupHandler subclasses and connected to the Line Presenter through its Event Processors field.

Movement

The movement implementation resides in the MoveEvent.cs file as an ActionMarkupHandler subclass. Most of the functionality is contained in the OnPrepareForLine method.

This method scans all markup in the current line, searching specifically for the move markup tag. When found, it extracts the name property from the marker and uses it to locate a corresponding in-scene marker with the same name. The target location and the marker position within the text are stored in a dictionary for later use.

During line presentation, the OnCharacterWillAppear method checks if the current character position corresponds to a stored location. If so, it moves the player character to that position before continuing.

This allows for dialogue lines such as: Player: So what, just part way through I stop talking... [move name="far" /] ...and move on over?

When presentation reaches position 49, it will pause, the player character will move to the GameObject named "far", and then the dialogue will resume.

Emotion

The facial expression system is implemented in EmotionEvent.cs as another ActionMarkupHandler subclass. The primary logic is also in the OnPrepareForLine method.

This implementation first uses the character name from the dialogue line to find a corresponding GameObject. It then retrieves the SimpleCharacter component (a sample-specific type, not part of Yarn Spinner core) from this GameObject. After these preparations, it processes all markup in the line, looking specifically for emotion tags. The emotion property value is extracted and stored for later use.

During presentation, OnCharacterWillAppear checks if there's a cached emotion corresponding to the current position. If found, it uses this value to change the character's facial expression animation. Unlike the movement example, this change happens instantly without pausing dialogue progression.

This enables dialogue lines like: Alice: Yes... which I would have shown [emotion="angry" /] had you not interrupted me.

When presentation reaches position 32, the facial expression of the "Alice" GameObject will instantly change to whatever animation corresponds to "angry" while the dialogue continues uninterrupted.

You can download and install Yarn Spinner for Unity in a variety different ways.

Yarn Spinner is developed in the open, and the best ways to download and install Yarn Spinner for Unity, and the ones that support us to continue developing it the most are via the and the .

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

Yarn Spinner 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.

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.

Working with Localisation

Yarn Spinner makes it easy to add multiple languages to your game. The gist is:

1. Select your Yarn Project in the Assets panel

2. Click "Export Strings as CSV" in the Inspector

3. Translate the exported CSV file

4. Import the translations back into your project

You can use either:

• Built-in Localisation System: Manage translations directly through Yarn Spinner

• Unity Localisation System: Integrate with Unity's Localisation package

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 Files: 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.

Workflow

To localise your Yarn scripts, you specify the 'base language' that your scripts are written in. You then add unique line ID tags to each line that identify each line. Finally, the localisation system reads your tagged lines and fills the string table for your base language. You can then add additional translations for your lines to the string tables for other languages.

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

Using Localised Content in Games

Once you've added line IDs to your Yarn scripts, they're ready to be used in your game's localisation system. You can choose between using the Unity-provided Localization package, in which case Yarn Spinner can prepare your string tables and fetch content from those tables at run-time, or our Built Yarn Spinner localisation system.

Yarn Spinner 3 introduces primarily additive changes to its language. Significant modifications have been made to Yarn Spinner for Unity to support these new features, resulting in some breaking changes.

This guide assists in migrating Yarn Spinner for Unity 2 projects to Yarn Spinner 3. While we provide compatibility layers to automatically manage many of the changes, some manual adjustments will be necessary. Here we'll look at the steps to ensure existing Yarn Spinner 2 games function with Yarn Spinner for Unity 3, and outline how to transition to the newer systems.

YarnCommand and YarnFunction Attributes

The functionality of [YarnCommand] and [YarnFunction] attributes is unchanged. However, they have been moved to a new namespace. To use these attributes, add using Yarn.Unity.Attributes; to the relevant C# files.

New flow for Interrupting Dialogue

The system for managing dialogue interruption (hurrying, advancing, cancelling) has been redesigned.

When Presenters receive dialogue events, such as requests to show lines or options, they are provided with a cancellation token. The state of this token can be checked to determine if an advance has been requested. This design centralises presentation, cancellation, and cleanup logic, which was previously distributed across multiple methods.

The Line Advancer sample demonstrates a practical implementation of line advancement using this cancellation token approach.

DialogueViewBase is now DialoguePresenter

Yarn Spinner 3 replaces the callback-based DialogueViewBase with an asynchronous DialoguePresenter. This is the new standard for handling dialogue events in your code.

While Presenters and Views have functional similarities, Presenters utilize a different API and are not directly compatible with older Views. It is highly recommended to refactor existing Views to the new Presenter model.

Converting a Dialogue View to a Dialogue Presenter

Previously, Dialogue Views used callbacks to coordinate with the dialogue runner. Dialogue Presenters employ asynchronous functions, signalling completion by returning from the method. This simplifies logic for both the dialogue runner and custom Dialogue Presenter implementations.

While the APIs of the old Dialogue View and the new Dialogue Presenter may appear similar, their operational mechanics differ significantly.

The conversion process will vary depending on the specific functionality of your View, but the general steps are:

1. Change the Subclass.

2. Convert to the New Methods.

3. Delete Unnecessary Methods.

4. Remove the Interrupt Action.

1. Change the Subclass

Replace DialogueViewBase with DialoguePresenterBase as the base class. Since DialogueViewBase is a subclass of DialoguePresenterBase (for compatibility), its connection to the Dialogue Runner in Unity should generally remain intact. However, it is crucial to verify this connection after completing the conversion.

2. Convert to the New Methods

While not a direct one-to-one mapping, several Presenter methods correspond to View methods in terms of the dialogue events they handle:

3. Delete Unnecessary Methods

The old DialogueView used callbacks and specific methods for user interruption and line completion. This functionality is now handled by cancellation tokens within the Presenter.

The following methods are no longer needed and can be removed:

• InterruptLine

• DismissLine

• UserRequestedViewAdvancement

4. Remove the Interrupt Action

The requestInterrupt action is obsolete and can be deleted.

Final Steps

The remaining task is to replicate the original behaviour of your Dialogue View within the new Dialogue Presenter structure. Several Samples are available, showcasing various custom Dialogue Presenters, which can provide guidance and practical examples for this process.

Upgrading Yarn Projects

Any new Yarn Projects you create will be already configured correctly but if you have any existing v2 Yarn Projects these will need to be updated. This is a single change that needs to be done on each Yarn Project. If you open your Yarn Projects inside any text editor there will be a line inside that says "projectFileVersion": 2,, replace this with "projectFileVersion": 3, and save the file. When you go back to Unity this change will be detected and the project will be automatically reimported at which stage you can now use v3 features in that project.

Thank you for using Yarn Spinner! 💚 This page contains information on how to use the Yarn Spinner name and logo in projects that make use of Yarn Spinner, or in media coverage of Yarn Spinner.

The core of Yarn Spinner is provided to you under the terms of the MIT License. This means that if you use Yarn Spinner in a game, software, or any other work, you are required to include a copy of the MIT license in that work.

You can find a copy of Yarn Spinner's MIT license here:

The MIT License (MIT)

Copyright (c) Yarn Spinner Pty. Ltd., Secret Lab Pty. Ltd., and Yarn Spinner contributors.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

You are required to include a copy of this with your game. There's no firm rules as to how you do this. We have some suggestions, though:

• on a screen in your game, along with other software licenses

• in a file that lists all licenses related to your game

• in an accompanying PDF, or similar, electronic manual or documentation

Basically, as long as a copy of Yarn Spinner's version of the MIT license is distributed with your game, you're good to go.

In addition to including a copy of the Yarn Spinner's MIT license in your game, please include Yarn Spinner in your game's credits, such as the initial splash screen, or in your end-game credits, or somewhere else of your choosing.

To credit Yarn Spinner, we give you permission to use our logo, which is available for download below.

You may also choose to credit us in text. We suggest the following:

Dialogue powered by Yarn Spinner — https://yarnspinner.dev

You can reword this however you'd like, but we'd prefer if you kept the name 'Yarn Spinner', and the link to the website.

Yarn Spinner® is a trademark of Secret Lab Pty. Ltd., the original creators, and is licensed to Yarn Spinner Pty. Ltd, which is a spinoff company to look after the project.

For the purposes of crediting Yarn Spinner, acknowledging that you're using Yarn Spinner, or discussing, teaching, or tutorialising Yarn Spinner and other simlar uses, we give you permission to use the Yarn Spinner name and logo on packaging, promotional/advertising materials, splash screens, in publications, seminars, conference talks, and web sites, and anything else in relation to your Yarn Spinner-powered software.

Rules for building products with Yarn Spinner support

Please adhere to the following if you build a non-game product or tool that supports Yarn Spinner:

1. The "Yarn Spinner" trademark or the word "Yarn" cannot be part of a product name (e.g. "Big Talk for Yarn Spinner") unless we have given you written permission (you would have had to email us for that).

2. The Yarn Spinner trademark can be used in a referential manner or alongside a referential phrase (e.g. "SimOptometrist is built with Yarn Spinner", "Aunty Edna's Grand Adventure uses Yarn Spinner", "Big Talk is compatible with Yarn Spinner", "Bobby Yarner teaches Yarn Spinner", "Learn Yarn Spinner with Dr Eyeballs");

3. The game, or project that you're including the Yarn Spinner trademark must, in fact, work with, use, or relate to Yarn Spinner in some way;

4. The use of the Yarn Spinner trademark cannot imply endorsement, sponsorship, or an inaccurate representation of the relationship between you, your game/project, and the Yarn Spinner project, team, Yarn Spinner Pty. Ltd., or Secret Lab Pty Ltd;

5. The use of the Yarn Spinner trademark should not show Yarn Spinner, the Yarn Spinner team, Yarn Spinner Pty. Ltd., Secret Lab Pty Ltd, or any related group or entity in an false or derogatory manner, or in association with any hate speech, or criminal or illegal activities.

6. If you make a product that suports Yarn Spinner, please direct your users to install Yarn Spinner via the Unity Asset Store or Itch.io in the first instance. Do not automatically install Yarn Spinner via OpenUPM or as a Unity Package from GitHub through your product or tool unless we have given you written permission to do so.

If you have any questons on this, ask the Yarn Spinner team in the Discord, tweet at us, or email us at legal AT yarnspinner.dev — we're friendly, and really just want to help.

Yarn Spinner logos

When you use the Yarn Spinner trademark, logo, or brand to credit Yarn Spinner in your game (or other work), you should try your best to conform your use to our brand guidelines.

You may not edit, modify, distort, recolour, or change the Yarn Spinner logo unless you show us what you've done (and receive our approval), or ask our permission. We're happy for you to totally diverge from our colours and branding, if we talk about it with you, so please email us at legal AT yarnspinner.dev to chat — we're friendly, we promise!

You can download a copy of the Yarn Spinner logo for inclusion in your credits below. We explicitly give you permission to use these logos to credit Yarn Spinner in your games, in accordance with the guidelines on this page:

In Yarn Spinner, saliency lets you control how line groups and node groups select which content to run.

When a line group or node group needs to run content, it needs to make a decision about which item in the group to choose. The method for making this decision is called a saliency strategy.

Saliency strategies are provided with the following information about each item:

• How many of its conditions passed (that is, the when: clauses on a node group, or the single condition on a line group)

• How many of its conditions failed

• The total complexity of all of its conditions:

  • The always condition has a complexity of zero.

  • Otherwise, the following values are added together:

    • If the condition is a once condition, add 1.

    • If the condition has an expression, add the the total number of boolean operators (and, or, not, xor) present, plus 1.

• A unique key that identifies the content.

You can either use one of Yarn Spinner's built-in saliency strategies, or create your own custom saliency strategy.

Yarn Spinner has several built-in saliency strategies.

• First: The first item in the group that has not failed any of its conditions is selected.

  • If the items of a node group are all in the same file, the ordering of the group is the order in which they appear in the file. If a node group’s nodes are split up across more than one file, the ordering of the nodes is not defined. the node that is considered ‘first’ is not defined.

• Best: The items that have not failed any conditions are sorted by their total complexity score, and the first item that has the highest score is selected.

• Best Least Recently Viewed: The items that have not failed any conditions are sorted by score, and then by how many times they have been selected by this strategy. If there is more than one best item remaining, the first of these is selected.

• Random Best Least Recently Viewed: The items that have not failed any conditions are sorted by score, and then by how many times they have been selected by this strategy. If there is more than one best item remaining, a random one of these is selected.

If you don't set the saliency strategy anywhere yourself, the default will be Random Best Least Recently Viewed.

A saliency strategy is given a collection of possible options, and returns either one of them that should be run, or null to indicate that none of them should run.

Changing the active saliency strategy in Try Yarn Spinner

When using Try Yarn Spinner, you can set the saliency strategy by calling one of the following built-in commands:

<<set_saliency first>>
<<set_saliency random>>
<<set_saliency best>>
<<set_saliency best_least_recent>>
<<set_saliency random_best_least_recent>>

Changing the active saliency strategy in Yarn Spinner for Visual Studio Code

When using Visual Studio Code to Preview your dialouge, you can change the active saliency strategy in the drop-down menu at the top of the Preview view:

Creating Custom Saliency Strategies

Your C# code can create custom saliency strategies. To do so, create a type that implements the IContentSaliencyStrategy interface, and assign it to your Dialogue object’s ContentSaliencyStrategy property.

IContentSaliencyStrategy has two required methods.

• ContentSaliencyOption? QueryBestContent(IEnumerable<ContentSaliencyOption> content) determines which of a collection of options, if any, should run. It should return the best content from the available options, or null if none of them should run. This is the main method in which you write the specific logic for your custom strategy.

  • Calling this method does not indicate that the content has been selected; rather, it is a query to determine what should be selected. Your implementation of this method should not change any state, and should be read-only. The content returned by this method is not guaranteed to actually be run.

• void ContentWasSelected(ContentSaliencyOption content) is called to indicate that a specific piece of content returned by a previous call to QueryBestContent has been selected. This method should update any appropriate state to represent this fact, such as by updating the total number of times the content has been selected.

Querying If Any Content Can Run

You can use a node group to check to see if any of its items can run, This can be useful when determining whether to show if a character should be marked as ready to talk, or whether any of its nodes have a special tag (for example, if a character has important information to discuss, as opposed to more general conversation.)

When you want to let the player decide what to say, you use an option. Options let you show multiple potential lines of dialogue to the player, and let the player select one.

Options are lines prefixed with a ->. You write as many options as you'd like the player to see, and the player chooses one of them. The content of the option is like any other line of dialogue.

For example, consider the following code:

title: Start
---
Navigator: The quantum fluctuations are intensifying. We need to jump now.
Captain: But the calculations aren't complete. We could end up anywhere.
Navigator: The wormhole is collapsing. It's now or never.
Captain: Fine. Initiate jump sequence.
Navigator: Something's wrong. We're being pulled backward...
Captain: That's impossible. Unless...
Navigator: We're arriving before we left. We've become our own rescue mission.
-> Captain: Let's alter our trajectory and break this temporal loop!
-> Captain: We must complete the cycle. Our past selves depend on it.
===

In this example, the line Navigator: We're arriving before we left. We've become our own rescue mission. will run.

The player will then be given the choice for the Captain to say either Let's alter our trajectory and break this temporal loop!, or We must complete the cycle. Our past selves depend on it.

Options that are grouped together are delivered together, for example, consider the following updated script:

title: Start
---
Navigator: The quantum fluctuations are intensifying. We need to jump now.
Captain: But the calculations aren't complete. We could end up anywhere.
Navigator: The wormhole is collapsing. It's now or never.
Captain: Fine. Initiate jump sequence.
Navigator: Something's wrong. We're being pulled backward...
Captain: That's impossible. Unless...
Navigator: We're arriving before we left. We've become our own rescue mission.
-> Captain: Let's alter our trajectory and break this temporal loop!
-> Captain: We must complete the cycle. Our past selves depend on it.
Navigator: Ayee! We're all going to die!
-> Captain: Nonsense! Keep yourself together!
-> Captain: AHHHH! We're all going to die!
===

In this example script these two options will be delivered together:

-> Captain: Let's alter our trajectory and break this temporal loop!
-> Captain: We must complete the cycle. Our past selves depend on it.

As will these, separately:

-> Captain: Nonsense! Keep yourself together!
-> Captain: AHHHH! We're all going to die!

Options and Lines

Options can have their own lines, which are run when the option is selected. If a different option is selected, they won't run. To write this, indent the lines that belong to an option.

In the following code, different lines will run based on which of the two shortcut options are selected.

title: Start
---
Navigator: The quantum fluctuations are intensifying. We need to jump now.
Captain: But the calculations aren't complete. We could end up anywhere.
Navigator: The wormhole is collapsing. It's now or never.
Captain: Fine. Initiate jump sequence.
Navigator: Something's wrong. We're being pulled backward...
Captain: That's impossible. Unless...
Navigator: We're arriving before we left. We've become our own rescue mission.
-> Captain: Let's alter our trajectory and break this temporal loop!
    Navigator: Risky, Captain. We'd be writing ourselves out of existence.
-> Captain: We must complete the cycle. Our past selves depend on it.
    Navigator: Then we're doomed to repeat this moment... forever.
===

When the player has the choice of saying either "Let's alter our trajectory and break this temporal loop!", or "We must complete the cycle. Our past selves depend on it."

Depending on their choice, the Navigator will say "Risky, Captain. We'd be writing ourselves out of existence." or "Then we're doomed to repeat this moment... forever.". Finally, no matter what was selected, the line "Sounds good!" will run.

Options within Options

You can also nest options below other options. For example, consider the following snippet of Yarn Spinner Script:

title: Start
---
Navigator: The quantum fluctuations are intensifying. We need to jump now.
Captain: But the calculations aren't complete. We could end up anywhere.
Navigator: The wormhole is collapsing. It's now or never.
Captain: Fine. Initiate jump sequence.
Navigator: Something's wrong. We're being pulled backward...
Captain: That's impossible. Unless...
Navigator: We're arriving before we left. We've become our own rescue mission.
-> Captain: Let's alter our trajectory and break this temporal loop!
    Navigator: Risky, Captain. We'd be writing ourselves out of existence.
    -> Captain: Damnit, Navigator! Nothing can stop me existing!
        Navigator: *sigh* Very well, Captain.
    -> Captain: By gods! You're right!
        Navigator: But it's only solution, I fear.
-> Captain: We must complete the cycle. Our past selves depend on it.
    Navigator: Then we're doomed to repeat this moment... forever.
    -> Captain: If we're doomed, at least we'll be remembered as heroes.
        Navigator: .. if anyone remembers us at all
    -> Captain: Forever... forever... forever...
        Navigator: Sir?
    -> Captain: We must do it!
            Navigator: As always, sir, you're right.
===

In this example script, the following options will be delivered together:

-> Captain: Let's alter our trajectory and break this temporal loop!
-> Captain: We must complete the cycle. Our past selves depend on it.

And then, depending on which one was chosen, another set of options will be delivered together.

For example, if the player chooses Captain: Let's alter our trajectory and break this temporal loop! , then the line from the Navigator will be delivered (Navigator: Risky, Captain. We'd be writing ourselves out of existence. ) and then two options for the Captain will be provided:

-> Captain: Damnit, Navigator! Nothing can stop me existing!
-> Captain: By gods! You're right!

And if the player chooses Captain: We must complete the cycle. Our past selves depend on it. , then the line from the Navigator will be delivered (Navigator: Then we're doomed to repeat this moment... forever.) and then three options for the Captain will be provided:

-> Captain: If we're doomed, at least we'll be remembered as heroes.
-> Captain: Forever... forever... forever...
-> Captain: We must do it!

Testing out Options

The <<jump>> command lets you move the dialogue between nodes. It is used by writing << then the word jump, a space, and then the full title of the node you want to jump the narrative to, then another >>.

To jump to a node with the title Rescue_the_Kitten , for example, you would write the line <<jump Rescue_the_Kitten>>.

Jump commands should always be placed on their own line, indented as appropriate.

Using the Jump Command

For example, consider the following conversation, which could be structured inside one node, using nested options, or split over several nodes using options and jump commands. The before version is inside a single node, and works fine, but the after version is structured across multiple nodes, and is a lot easier to make sense of.

title: Start
---
Navigator: Where to, Captain?

-> Captain: I want to go back to earth!
    Navigator: Earth it is sir. 
    Navigator: This jump will take us 10 hours.
    Navigator: Permission to jump, sir?
    -> Captain: Granted, let's go!
        Navigator: On it, sir.
    -> Captain: Not yet. Just wait a moment.
        Navigator: Standing by, sir.
-> Captain: Second star to the left!
    Navigator: Can you be more specific?
    -> Captain: I cannot, no.
        Navigator: Right away, sir.
    -> Captain: ... that one *gestures*
        Navigator: Very good, sir.

Navigator: Being a Navigator sure is hard work!
===

title: Start
---
Navigator: Where to, Captain?

-> Captain: I want to go back to earth!
    <<jump Earth>>
-> Captain: Second star to the left!
    <<jump SecondStar>>
    

Navigator: Being a Navigator sure is hard work!
===

title: Earth
---
Navigator: Earth it is sir. 
    Navigator: This jump will take us 10 hours.
    Navigator: Permission to jump, sir?
    -> Captain: Granted, let's go!
        Navigator: On it, sir.
    -> Captain: Not yet. Just wait a moment.
        Navigator: Standing by, sir.
<<jump Done>>
===

title: SecondStar
---
Navigator: Can you be more specific?
    -> Captain: I cannot, no.
        Navigator: Right away, sir.
    -> Captain: ... that one *gestures*
        Navigator: Very good, sir.
<<jump Done>>
===

title: Done
---
Navigator: Being a Navigator sure is hard work!
===

Separating dialogue segments into nodes can aid in writing neater files that are easier to edit as they grow.

When you use <<jump>> command, they'll be shown in the Graph View in Yarn Spinner for Visual Studio Code as an line with an arrow leading to the node that's being jumped to:

If you use the <<jump>> command to jump to a node that's in a different .yarn file, it will be visualised as a line leading to a small circle:

Write some Jump Commands

Next up, learn about the Jump Command's close relative, the Detour Command.

The primary editing experience for Yarn Spinner Scripts is our Yarn Spinner for Visual Studio Code extension. This provides the majority of features that you'd want in order to effectively write .yarn scripts using VSCode.

This page shows you how to use Microsoft's free Live Share extension for Visual Studio Code, together with Yarn Spinner for Visual Studio Code, to collaborate live on your narrative.

Installing Live Share

To install Live Share for Visual Studio Code, and use it with Yarn Spinner:

1. Setup Yarn Spinner for Visual Studio Code.

2. Click this link to open Visual Studio Code, and jump to the Live Share Extension.

3. Click the install button!

Inviting collaborators

Open your Yarn Spinner project in Visual Studio code. For example, here's I Feel Fine:

With your project open, choose Live Share in the Activity Bar on the left side of the screen, and in the resulting view that appears, choose the Share button:

You'll be prompted to sign in to either GitHub or your Microsoft account, and after this a notification will appear in the bottom of the screen letting you know a shareable link to collaborate has been copied to the clipboard:

Joining a shared workspace

When you receive a collaboration link and visit it, you'll be asked how you'd like to join:

If you choose to Continue in Web, you'll be taken to a web version of VS Code, which will not have the Yarn Spinner extension installed. If you click Open in Visual Studio Code, your local copy of VS Code will be installed, complete with extensions.

Once the shared workspace opens in your local copy of VS Code, you'll be in an untrusted state, which means the Yarn Spinner extension will not be providing syntax highlighting, To enable this, click Manage, in the grey bar at the top of the window, then click the Trust button in the view that appears:

Writing together

The person who initially shared the workspace will have full and complete access to the features of the Yarn Spinner for Visual Studio Code extension. Everything, from syntax highlighting to the graph view will work as normal.

Those who are joining the shared session will only have access to the syntax highlighting features of the Yarn Spinner for Visual Studio Code extension, provided they go through the process of trusting the workspace, as noted earlier.

As you edit, you'll be able to see other users in the files, and their work will be briefly highlighted as they write:

For more help

For more guidance using the Live Share extension, check out the extension's official page, as well as the Live Share extension's documentation.

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

Showing the Character's Name

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

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

Presenting Lines with Visual Effects

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

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

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

Continuing to the Next Line

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

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

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

Inspector

One of the best ways to make a game's world come alive is to have characters engage in conversations with each other, not just with the player character. The Background Chatter sample demonstrates how you can use Yarn Spinner to create and manage these ambient conversations.

Running Multiple Dialogue Runners

The Dialogue Runner is the core component that manages dialogue interactions in your scene. When a node runs, the Dialogue Runner sends lines and options to its Dialogue Presenters.

The Line View and Option View presenters in the built-in prefab are designed to be modal - they take center stage, assuming they have the player's full attention. During these conversations, the player is typically not moving around or performing other actions.

Background conversations, however, are non-modal: they happen while the player continues to explore and interact with the world. The player doesn't participate in these conversations, which proceed independently.

The most effective approach for implementing background conversations in Yarn Spinner is to create separate Dialogue Runners for each conversation. This approach offers several advantages:

• Each background Dialogue Runner can have dedicated Dialogue Presenters designed specifically for ambient conversations

• Background Dialogue Runners operate independently from the main "primary" Dialogue Runner

• You can manage multiple simultaneous background conversations as needed

All Dialogue Runners in your scene can share the same Yarn Project and Variable Storage, maintaining a consistent dialogue state.

Designing Line Presenters for Background Conversations

Line Presenters for background conversations have different requirements than those used for primary player interactions. These presenters should:

• Make it clear that dialogue is taking place

• Remain unobtrusive enough to avoid interfering with the player's focus

• Usually avoid presenting options, since background conversations don't assume active player participation

Since your game might feature multiple simultaneous conversations, we recommend creating one Dialogue Runner for each conversation in your scene, allowing them to run in parallel.

The BackgroundChatter Sample

The BackgroundChatter sample demonstrates how to create an environment where the player can move freely while hearing ambient conversations in the background.

To play the sample, open the BackgroundChatter/Main.unity scene and press play. Use the WASD keys to move around and the Space key to initiate conversations with characters.

The sample features a sequence of background conversations, each demonstrating different aspects of this system. Explanation characters (identifiable by their ties and coffee cups) stand near each demonstration. Speaking with them provides details about what each conversation demonstrates.

Chatter Groups and ChatterGroupManager

In this sample, each background conversation is represented by a "Chatter Group" - a spherical volume in the game world that can trigger a specific dialogue node when the player enters it. Each Chatter Group contains:

• A Canvas with custom Line Presenters

• Text elements that float above speaking characters

• Player position tracking that cancels dialogue when the player leaves the volume

The Chatter Group Manager runs each Chatter Group on a timer, so that while the player remains within a group's volume, that group can potentially initiate dialogue.

Basic Background Conversation

The basic background conversation demonstrates a simple exchange between two characters. This conversation runs normally and cannot be interrupted by player actions.

Procedural Conversation

The procedural conversation demonstrates using two line groups to create a dynamic back-and-forth between characters. The first line group contains only questions, while the second contains generic replies that work with any question. This approach allows you to create numerous possible conversation combinations with minimal writing effort.

Interruptable Conversation

The interruptable conversation demonstrates how players can interrupt characters engaged in a background conversation. While these characters participate in their ambient dialogue, they remain interactable. When the player initiates interaction, the background conversation pauses to prevent overlap with the primary dialogue. After the player's conversation concludes, the background conversation resumes.

Player-Participating Conversation

This example shows how players can participate in what begins as a background conversation. When the player approaches the character, a conversation starts with the player as a participant. If the player leaves the Chatter Group's volume, the conversation ends and triggers an additional dialogue node. This allows the player character to deliver a parting line rather than abruptly ending the conversation.

Ongoing Conversation

This example demonstrates how background conversations can access variable storage and other Yarn Spinner features. When the player passes by these characters repeatedly, they progress through different parts of an ongoing conversation. This continuity is achieved by using a variable that updates each time the conversation runs.

Marketplace Scene

The marketplace scene showcases background conversations in a more gameplay-oriented scenario. As you explore this area, you'll encounter various types of background conversations demonstrated elsewhere in the sample.

A function is a block of code that provides a value to your Yarn scripts, which you can use in , or store in .

In Yarn Spinner scripts, functions perform two main kinds of task:

• Functions let you get values that change over time, or that depend on other values. For example, the random function returns a different random number every time you call it.

• Functions let you get data from your game back into your scripts.

You call a function inside an expression. For example:

Built-In Functions

Yarn Spinner comes with several built-in functions for you to use.

visited(string node_name)

visited returns a boolean value of true if the node with the title of node_name has been entered and exited at least once before, otherwise returns false. Will return false if node_name doesn't match a node in project.

visited_count(string node_name)

visted_count returns a number value of the number of times the node with the title of node_name has been entered and exited, otherwise returns 0. Will return 0 if node_name doesn't match a node in project.

format_invariant(number n)

format_invariant returns a string representation of n, formatted using the invariant culture. This is useful for embedding numbers in commands, where the command expects the number to be formatted using the invariant culture. For example, <<give_gold {$gold}>>, which might end up as give_gold 4,51 in German, but give_gold 4.51 in English, can now be <<give_gold {format_invariant($gold)}>>, which will always be give_gold 4.51.

random()

random returns a random number between 0 and 1 each time you call it.

random_range(number a, number b)

random_range returns a random number between a and b, inclusive.

dice(number sides)

dice returns a random integer between 1 and sides, inclusive.

For example, dice(6) returns a number between 1 and 6, just like rolling a six-sided die.

min(number a, number b)

min compares a and b, and returns the smaller of the two.

max(number a, number b)

max compares a and b, and returns the larger of the two.

round(number n)

round rounds n to the nearest integer.

round_places(number n, number places)

round_places rounds n to the nearest number with places decimal points.

floor(number n)

floor rounds n down to the nearest integer, towards negative infinity.

ceil(number n)

ceil rounds n up to the nearest integer, towards positive infinity.

inc(number n)

inc rounds n up to the nearest integer. If n is already an integer, inc returns n+1.

dec(number n)

dec rounds n down to the nearest integer. If n is already an integer, dec returns n-1.

decimal(number n)

decimal returns the decimal portion of n. This will always be a number between 0 and 1. For example, decimal(4.51) will return 0.51.

int(number n)

int rounds n down to the nearest integer, towards zero.

Custom Functions

You can create your own commands, so that your scripts can send directions to your game. For more information on how to create them in Unity games, see , in the Yarn Spinner for Unity section of the documentation, and equivalents for other engines.

Yarn Spinner Scripts are built up out of nodes. Nodes are where you put your dialogue. You can have as many nodes as you want in a file.

Each node has, at the very minimum, a collection of headers, and a body. All nodes have at least one header, which is the title. The title is the name of the node, and the body contains the Yarn script that contains your game's dialogue.

Nodes are used to separate out parts of the story, and make it easier to manage longer stories and branching.

The title of a node is important, because your game uses node titles to tell Yarn Spinner which node to start running. You also use the title of a node when you want to jump to another node. Node titles are not shown to the player.

The --- marker indicates where the body begins. After this point, you can put all of your Yarn script.

The === marker indicates where the node ends; after this point, you can begin another node.

Inside a Node

The body of a node (that is, the content between the node start marker --- and the node end marker ===) is made up of three different kinds of content: lines, commands, and options.

Lines

When you write Yarn Spinner dialogue, just about every line of text that you write in a node is a line. When a node is run, it runs each line, one at a time, and sends it to your game.

A line of dialogue is just the thing you want some entity or character to say, usually beginning with the name of the entity speaking.

For example, consider the following Yarn Spinner script snippet from Night in the Woods:

When this code is run in the game, it looks like this:

Yarn Spinner sends each of these lines, one at a time, to the game. The game is responsible for taking the text, and presenting it to the player; in the case of Night in the Woods, this means drawing the speech bubble, animating each letter in, and waiting for the user to press a key to advance to the next line.

Lines of dialogue can contain just about any text, except for some special characters that Yarn Spinner uses to add extra information to a line.

If there is a set of characters without spaces before a colon (:) at the beginning of the line, Yarn Spinner will mark that as the name of the character. This information will then be passed to your game, so that you can change the way that lines are shown based on the character who's saying them. For example:

Nodes can also have a color: and a group: in their header, which specifies what colour the bar at the top a node is shown in, and the group they're gathered in, in the Graph View of the :

You can also set nodes to be Sticky Notes by adding style: note to the node header. This will render the nodes differently in the Graph View of the . The color: of the node will be respected too, if one is set, otherwise the Sticky Note will default to yellow:

You can learn more about in the section.

Write a simple story

A Line Presenter is a that displays a single line of dialogue inside a Unity UI canvas. When the Dialogue Runner encounters a line in your Yarn Script, the Line Presenter will display it, wait for the user to indicate they're done reading it, and then dismiss it.

Showing the Character's Name

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

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

Presenting Lines with Visual Effects

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

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

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

Continuing to the Next Line

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

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

If 'Auto Advance' is turned off, then the Line Presenter will not signal that it's done when the effects have finished, and the line's delivery will stop.

To make the Line Presenter finish up, you can call RequestHurryUpLine on the Dialogue Runner. This will not end the current line, but will send a signal to all Line Presenters that it should finish displaying its content quickly. To move onto the next line, you can call the method RequestNextLine on the Dialogue Runner.

The supplied Line Presenter has an arrow button at the bottom. Clicking this will call RequestNextLine on the Dialogue Runner:

Inspector

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

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

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

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

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

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

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

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

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

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

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

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

Next steps with Yarn Spinner for Godot

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

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

Creating a New Yarn Project

To create a new Yarn Project, follow these steps:

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

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

Adding Yarn scripts to a Yarn Project

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

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

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

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

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

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

Managing Localizations and Assets

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

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

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

Using Yarn Projects with Dialogue Runners

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

Inspector

A tag is a piece of information that you can add to content in Yarn Spinner that adds additional context or detail about that content.

There are two places you can add tags in Yarn scripts: you can add them to nodes, and you can add them to lines.

Tags aren't shown to the user; instead, they're used by your game, or by Yarn Spinner itself.

Tags in lines

Tags can be added to the end of lines and options. Tags on lines start with a hash symbol (#), and cannot contain spaces. You can add as many tags as you like to line, but they must all be on the same line in the script.

Here's an example of a line with two tags:

Accessing tags

Tags that you add to a line can be accessed from your game. The way that you access them depends on your game engine. For example, to access them in a Unity game, you use the LocalizedLine.Metadata property.

Some tags are used by Yarn Spinner itself, while all others are used by your own code, so it's up to you what content they should have, and how to handle them.

Special tags

Certain tags are used internally by Yarn Spinner, or are added for you if they don't exist.

#lastline

The Yarn Spinner compiler adds a #lastline tag to every line that comes just before a set of options.

For example, the following excerpt:

is treated as though it had been written as:

In a Unity game, you can use this tag in a custom to be notified ahead of time when the player is about to be shown options.

#line

The #line tag uniquely identifies a single line or option across all of your game's dialogue. This is used to identify lines for localisation. Every line's #line tag must be unique. If a line or option doesn't have a #line tag, it will be automatically added for you.

Here's an example of some Yarn script with #line tags:

For more details (including what the tag should look like), see .

Tags in nodes

Nodes can also have tags, which you can use to add labels that describe the node.

Node tags they work a bit differently than line tags: they are defined in the header with the tags key, and they don't have to begin with a hash symbol (#).

Here's an example of a node with two tags:

You can access the tags on a node via the Dialogue object's method.

Other metadata

The metadata of a line is only composed of tags. Because of this, you may find that the Yarn Spinner code and documentation refer to line tags and line metadata interchangeably.

Nodes can have other metadata in their headers. This metadata isn't exposed through the API, which means it's mostly used to store additional information for whoever is writing the Yarn dialogue or for editors to make use of.

However, currently there is one header that defines specific behavior within the Yarn Spinner compiler: the tracking header.

The tracking header

Nodes can track whether they have already been visited during the game. For this to work, the Yarn Spinner compiler needs to add some special code to the node. To avoid creating this code for nodes that don't need it, the compiler only adds this code if it finds a call to the visited() function with the node name in it.

In some cases, you may need the compiler to add this special code to a node even if no corresponding visited() call exists. To direct the compiler to do this, include the tracking header with the value of always:

Additionally, using a value of never instructs the compiler to never add this special code to the node. If you use the visited function with a node set to never use tracking, it will always return false.

For more information on visit tracking, see the documentation for .

Use cases

Tags and metadata may seem very complicated at first, and their uses may not be clear. The following example use cases explain how they can be used in your game. Keep in mind that this is not an exhaustive list of use cases.

Controlling attributes for an entire line

Yarn provides to let you change attributes for specific parts of a line. In case most of your attributes apply to entire lines (for example, the color of a line), it may be easier to just use tags instead.

Displaying the last line of dialogue along with options

The #lastline tag can be used to display the last line of dialogue along with any options. This is handled within your code by checking if a line has the #lastline tag, and if it does, storing it before continuing with the execution of the Yarn dialogue.

Internal workflows

Since metadata isn't shown directly to the player, you can use metadata for any internal workflows or tooling. For example, instead of tracking lines that need to be revised outside the Yarn files (which could lead to syncing problems), you could add line tags (such as #needsrevision) to the appropriate lines directly in the Yarn files, and process these lines as part of an internal tool or workflow. The Unity integration automatically generates a CSV file with all lines that contain metadata, making this super easy!

Localisation

As referenced before, the Yarn Spinner integration for Unity uses line tags to link localised dialogue lines. This is better explained in the section, when using Yarn Spinner for Unity.

Aside from that, every piece of metadata can be used by translators and adapters to help them understand how the text is being used, thus leading to better localised text.

Showing specific lines of dialogue outside a dialogue window

Some games may require that certain lines of dialogue are displayed somewhere other than the dialogue window (for example, as flavor text for an item description, or in an item that acts as a log). Instead of manually duplicating these lines (which adds overhead during development and localisation), tags can be used along with code that checks for the tags and duplicates the lines while the game is running.

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

Creating a Dialogue Presenter

To make a Dialogue Presenter, you first create a subclass of the DialoguePresenterBase class. Then, you add this subclass as a component to a game object in your scene. After that, you can add this game object to the Dialogue Presenters list on your scene's Dialogue Runner.

Presenting Lines and Options

By itself, an empty subclass of DialoguePresenterBase won't do much. You need to implement specific methods to make it show lines and options.

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

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

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

Getting Localised Content

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

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

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

Presenting Lines

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

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

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

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

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

Hurrying and Advancing Lines

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

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

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

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

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

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

Presenting Options

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

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

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

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

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

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

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

Accessing Line Metadata

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

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

Creating a Dialogue Presenter

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

Presenting Lines and Options

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

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

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

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

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

Getting Localised Content

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

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

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

Presenting Lines

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

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

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

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

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

Hurrying and Advancing Lines

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

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

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

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

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

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

Presenting Options

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

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

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

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

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

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

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

Accessing Line Metadata

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

Modifying the Example Dialogue Systems

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

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

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

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

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

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

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

So far, you've learned how to use Nodes and Lines, Options, the Jump Command, the Detour Command, and Variables to write Yarn Spinner Scripts.

Because it's actually a full programming language of its own, Yarn Spinner also supports flow control.

Flow control takes several forms, including if statements, and conditional options.

if statements

In addition to storing information, variables are useful for controlling what's lines of dialogue are presented to the player. To do this, you can 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 Yarn Spinner Script:

<<set $gold_amount to 5>>

Player: I'd like to buy a pie!

<<if $gold_amount < 10>>
    Baker: Well, you can't afford one!
<<endif>>

This script will:

• set a variable, $gold_amount, to 5;

• show the line Player: I'd like to buy a pie!

• use an if statement to see if $gold_amount is less than 10, and if that is the case, which it will be in this example, show the line Baker: Well, you can't afford one!

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 if the if and any elseif don't run.

For example, consider the following Yarn Spinner Script:

<<set $gold_amount to 5>>
Player: I'd like to buy a pie!

<<if $gold_amount < 10>>
    Baker: Well, you can't afford one!
<<elseif $gold_amount < 15>>
    Baker: You can almost afford one!
<<else>>
    Baker: You can afford a pie!
<<endif>>

This script will:

• set a variable, $gold_amount, to 5;

• show the line Player: I'd like to buy a pie!

• use an if statement to see if $gold_amount is less than 10, and if that is the case, show the line Baker: Well, you can't afford one!

  • otherwise use a elseif statement to see if $gold_amount is less than 15, and if that is the case, show the line Baker: You can almost afford one!

  • otherwise use a else statement to provide a fallback, which will show the line Baker: You can afford a pie!

• end the if statement block with an endif statement.

You can have as many elseif statements as you want inside an if statement block, and you can use whatever you want inside, for example:

<<set $gold_amount to 5>>
<<set $reputation to 10>>
<<if $gold_amount >= 5 and $reputation >= 8>>
    // The player is both rich and popular
    Merchant: You're rich enough and popular enough for me to serve you!
<<elseif $gold_amount >= 10 or $reputation >= 10>>
    // The player is either rich enough or popular enough to serve
    Merchant: I wouldn't normally, but I'll serve you!
<<else>>
    // The player is dirt
    Merchant: You're neither rich enough nor important enough for me to serve!
<<endif>>

In this example:

• there are two variables, $gold_amount for tracking the player's currency, and $reputation for their reputation in town

• an if statement first checks if their $gold_amount is greater than or equal to 5 and whether their reputation is greater than or equal to 8, if both of these are true, then the line Merchant: You're rich enough and popular enough for me to serve you! is shown

  • otherwise the elseif statement checks if their $gold_amount is greater than or equal to 10 (making them very rich), or their $reputation is greater than or equal to 10 (making them very well regarded), and if either of these are true the line Merchant: I wouldn't normally, but I'll serve you! is shown

• if neither set of conditions is true, then the else statement means the line Merchant: You're neither rich enough nor important enough for me to serve! will be shown

Conditional Options

When presenting options to the player using the -> syntax, you may want to make some options not available. You can do this by adding a condition to the option, making it a conditional 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:

Guard: You're not allowed in!
-> Sure I am! The boss knows me! <<if $reputation > 10>>
-> Please?
-> I'll come back later.

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.

In addition to Yarn Spinner's own built-in localisation system, your game can also use the Unity Localization package.

Both the Unity Localization and Built-In Localisation approaches are very similar to one another, but there are some caveats and extra steps to make them play together.

Watch a video where Yarn Spinner developer Jon Manning walks you through using Yarn Spinner with Unity's Localisation package:

Getting Started

Before doing anything with Yarn Spinner, you will need to set up your Unity project to use the Unity Localization system. To install and set up Unity Localization, follow the instructions on the Unity Localization package's documentation.

For Unity Localization

1. Install the Localisation package

2. Create a new Localization Settings in the Project Settings - Localization screen:

1. Create at lease one Locale in the Project Settings - Localization view.

2. Create a String Table Collection via Window menu -> Asset Management -> Localization Tables.

3. Check "Use Unity Localisation System" in your Yarn Project, and assign the String Table, and click Apply.

1. Verify that the String Table (viewable by Window menu -> Asset Management -> Localization Tables) contains your Yarn Spinner Script's lines.

2. In the Inspector for your Dialogue Runner, click the "Add Unity Localized Line Provider" button:

1. This will add a component to your GameObject. Find it, and assign your String Table Collection to the Strings Table field:

For Built-in Yarn Spinner Localization

Once you have followed these instructions, your project should now:

1. Have the Unity Localization package installed

2. Created and configured one or more Locales for your project

3. Created a string table collection.

With these done you should now have your project set up correctly, and have a string table collection for your locales with no entries inside. Yarn Spinner will fill this string table with content that it extracts from your Yarn Scripts.

Importing Default Strings

To fill a string table with content from a Yarn project, follow these steps:

1. Select the Yarn Project, and go to its Inspector.

2. Enable the Use Unity Localisation System setting.

3. Set the Base Language to your desired language. This must be ensure its one of the locales that you have configured for your project.

4. In the String Table Collection field, add the String Table Collection that you want to populate with line content.

5. Click Apply.

You can check that the string table has been filled with content by opening the Window menu, and choosing Asset Management -> Localization Tables. You can then view the contents of your string table. The Key of each string will be the #line ID from the Yarn files.

String Table Locale Fallback

When the Yarn Project importer adds your lines into the string table, it uses the Base language field you set in the Inspector to determine which locale in your String Table Collection should have the lines added into.

If your project doesn't have a Locale which matches your Base Language, Yarn Spinner will attempt to find an appropriate Locale to use. To ensure that the importer uses the correct Locale, be sure to specify it in the Inspector.

Using the Strings

When a Yarn script is run, the Dialogue Runner receives line IDs from the Yarn Project, and must determine what localised content should be shown to the player, using a line provider. In order for the Dialogue Runner to fetch localised data from the Unity string table, you use a Unity Localised Line Provider.

To configure it, all that needs to be done is hook your string table collection up to the Strings field of the Unity Localised Line Provider.

During gameplay, the Unity Localised Line Provider will fetch content from your string table depending on the game's current locale setting. You can control this at run-time by using the locale selector at the top-right corner of your Game View.

Localising Assets

In addition to localising the strings that make up your lines, you can also localise assets that go with each line, such as voice-over audio, or custom objects that store other localised data.

To localise assets in Unity Localisation, you create and populate an Asset Table. Yarn Spinner doesn't automatically populate Asset Tables for you like it does String Tables, because Yarn Spinner doesn't manage your assets like it does with your lines.

Instead, you can create an Asset Table that contains assets with the same key as your lines. For example, if you have a line in your Yarn script that has the line ID "line:tom-1", then the string table will have an entry with the key line:tom-1. To create a voice-over asset to go with this line, you can create an asset table that also contains an entry with the key line:tom-1, and maps to an audio file.

The Unity Localised Line Provider will automatically match String Table entries and Asset Table entries if they have the same key, and then deliver them to your Dialogue Views for use. To do this, ensure that your Unity Localised Line Provider has an Asset Table configured in the Inspector.

Potential Trip-ups and Caveats

Because both Yarn Spinner and Unity use the same marker for their string interpolation and manipulation ({ and }). You can't use the Unity Localization smart strings in Yarn Spinner content.

The Speech Bubbles Add-On provides a flexible speech bubble system with a variety of possible customisations. Here, you'll learn how to implement it in a Unity project by looking at a basic little 3D game. We'll be using prefabs and assets from the Yarn Spinner Samples package to speed this up, but nothing we are using from there is necessary, it's just faster than building all the infrastructure out ourself.

Setting up for Speech Bubbles