Yarn Spinner in Unity Scenes

Learn the various components and assets used in getting Yarn Spinner up and running Unity scenes.

This guide will walk you through setting up Yarn Spinner in your Unity project and getting a basic dialogue system running. It assumes you have created a new Unity project and installed the Yarn Spinner for Unity package.

1

Creating a Yarn Project

To organise your dialogue, you'll need to create a Yarn Project.

A Yarn Project is a special file that groups related Yarn Scripts together. It's essential for using dialogue in your game.

To create a Yarn Project:

1. In the Unity Editor, open the Assets menu -> Yarn Spinner -> and choose Yarn Project

2. Name your new Yarn Project file (e.g., MyGame)

3. The Yarn Project will appear in your Assets folder

Creating a new Yarn project

Yarn Projects include all Yarn Scripts in the same directory by default. You can modify the Source Files setting to include scripts from different locations.

Our recommended best practice is to create a Dialogue folder inside your assets, and store your Yarn Spinner Project(s) and Script(s) in it. The name of the folder is not significant, it's just useful to group your Yarn Spinner Script(s) and Project(s) together.

You can take a look at the Inspector of your Yarn Spinner Project to get a better understanding of what it's looking for:

The Inspector for a Yarn Spinner Project asset.

You'll notice that it's including all .yarn scripts in the same folder as it, or in folders below/inside it. You can change this, or add specific Yarn Spinner Scripts if you'd like. You can also use this Inspector to change the default language for your Yarn Spinner Project, add additional localisations, and export your strings for translation.

For now, you don't need to touch anything here.

2

Writing Dialogue in Yarn Scripts

Now, let's create a Yarn Script to write your dialogue:

1. Open the Assets menu -> Yarn Spinner > and choose Yarn Script

2. Name your script (e.g., Introduction). This will create a file named Introduction.yarn

3. Double-click the script to open it in the editor

Here's a simple example of dialogue written in Yarn:

title: Start
---
Player: Hello there!
NPC: Oh, hello! How can I help you today?
-> I need information.
    NPC: What would you like to know?
-> I'm just browsing.
    NPC: Feel free to look around!
-> Actually, I should go.
    NPC: No problem. Come back anytime!
    <<jump End>>
===

title: End
---
Player: Thanks for your help!
NPC: You're welcome! Have a nice day!
===

Save your changes. The script will be automatically included in your Yarn Project if it's in the same folder.

When writing dialogue, remember:

• Each node begins with title: followed by the node name

• The node's content starts after --- and ends with ===

• Options are created using -> at the start of a line

• Commands use <<command>> syntax

3

Setting Up the Dialogue System in Unity

To use your dialogue in-game, you need to add a Dialogue System to your scene:

1. In your scene hierarchy, right-click and choose Yarn Spinner -> Dialogue System

2. With the Dialogue System selected in the Hierarchy, locate its Dialogue Runner component in the Inspector.

1. Drag your Yarn Project from the Assets view into the "Yarn Project" field in the Dialogue Runner:

The Yarn Project asset assigned to the correct field.

1. If you want dialogue to start automatically, check "Start Automatically" and set your starting node (often titled Start , by convention).

Setting the Yarn Spinner DIalogue Runner to start automatically and run the node titled Start.

The Dialogue System prefab comes with several components:

• Dialogue Runner: The core component that runs your dialogue

• Line Presenter: Displays text dialogue to the player

• Options Presenter: Shows choices for the player to select

• Line Advancer: Allows the player to progress through dialogue

• Markup Processor: Handles replacement markup.

4

Understanding Dialogue Presenters

Dialogue Presenters are components that display dialogue content to the player. There are a few different varieties. You can have multiple Dialogue Presenters in your scene, each handling different aspects of dialogue presentation. You'll often have a Line Presenter, to show regular lines, and an Options Presenter, to show options.

Line Presenter

A Line Presenter shows lines of dialogue. The default Line Presenter looks like this:

The default Line Presenter.

This default Line Presenter has some configuration options, including:

• Text appearance and positioning

• Character name display

• Typewriter effect speed

• Fading effects

• Auto-advance settings

You can learn about them by selecting the Line Presenter in the Hierarchy:

The Line Presenter, selected in the Hierarchy.

And then looking at its Inspector:

The Line Presenter's Inspector.

Options Presenter

The Options Presenter displays options for the player to select. The default Options Presenter looks like this:

You can configure:

• Option appearance and positioning

• List layout

• Whether to show unavailable options

Line Advancer

The Line Advancer allows players to progress dialogue using input. You can configure it by:

1. Selecting your Line Presenter in the hierarchy

2. Finding the associated Line Advancer component

3. Configuring the input method (keycode, button, etc.)

Configuring the Line Advancer.

5

Variable Storage and Line Providers

Variable Storage

Variable Storage components keep track of variables in your dialogue:

• By default, Yarn Spinner uses In-Memory Variable Storage (variables are lost when the game ends)

• For persistent variables, create a custom Variable Storage that connects to your game's save system. You can learn to do this in our Variable Storage Guide.

To debug variables during development, use the Debug Text View property of the In-Memory Variable Storage component. By creating a TextMeshPro Text Component in your Hierarchy, and assigning it to the Debut Text View field of the In Memory Variable Storage component attached to the Dialogue System, you can monitor variables in your game view for debug purposes:

The In Memory Variable Storage component.

Line Providers

Line Providers fetch the content for each line of dialogue:

• Text Line Provider: Provides just the text of dialogue lines

• Audio Line Provider: Provides text and associated audio clips

• Unity Localised Line Provider: Works with Unity's Localization system

If you don't set a Line Provider, the system will create a Text Line Provider automatically. These components are all configured in the Dialogue Runner:

6

Testing Your Dialogue

To test your dialogue system:

1. Make sure you have a Yarn Project asset and a Yarn Script asset, and that the Yarn Script is appropriately included with the Yarn Project:

The bottom of the Inspector for a Yarn Project asset, showing the Yarn Scripts it is including.

1. Add a Dialogue System to the scene, and assign the Yarn Project to it in the Inspector for the Dialogue Runner component attached to the Dialogue System:

The Yarn Project asset assigned to the Dialogue Runner.

1. Also set the the Dialogue Runner to Start Automatically, and run the appropriate Yarn node:

Settings for starting automatically, and running a specific node, found on the Dialogue Runner component.

1. Press Play in the Unity Editor. Dialogue should begin!

Dialogue running via Yarn Spinner for Unity and the default Line Presenter and Options Presenter.

If you didn't want dialogue to start automatically, you can trigger it by calling the StartDialogue() method on your Dialogue Runner. For example, you might trigger dialogue when a player presses a button near an NPC.

While testing, use the Unity Console to check for any errors in your Yarn scripts:

The Unity console showing that we forgot to close a Yarn Command on line 11 of the Yarn Script.

Troubleshooting

Dialogue doesn't start

• Check if your Yarn Project is assigned to the Dialogue Runner

• Verify that your Yarn Script contains a node with the name specified in "Start Node"

• Check that you've ticked Start Automatically on the Dialogue Runner

• Make sure there are no compilation errors in your Yarn Scripts

Dialogue text doesn't appear

• Ensure the Line Presenter component is properly configured

• Check that the Canvas Group and Text components are correctly assigned

Variable issues

• For debugging, use the In-Memory Variable Storage's "Debug Text View" to see variable values

• Make sure variables are declared with the correct type