Learn about the terminology and assets used to work with Yarn Spinner Scripts in Unity.
Yarn Spinner Scripts are just like any other kind of asset you might work with in your Unity Projects: they live in your Assets/ folder.
When you're building a project in Unity that use Yarn Spinner, there are two main kinds of files (which become Assets, in Unity terminology) you'll use when working with Yarn Spinner for Unity:
Yarn Scripts—.yarn files that contain your written dialogue.
Yarn Projects—a special file that groups a set of Yarn Scripts together.
In this document, we'll learn how these pieces fit together in Unity.
A Yarn Spinner Script is a text file containing your dialogue. You spent a lot of time writing .yarn files, which are Yarn Spinner Scripts, using Yarn Spinner for Visual Studio Code in the section of the documentation.
There are two main methods of getting your Yarn Spinner Scripts into your Unity project:
you can move the .yarn Yarn Scripts into the Assets/ folder of your project, using your computer's file manager or terminal;
you can can create new .yarn Yarn Scripts inside Unity.
To create a new Yarn script in Unity, follow these steps:
Open the Assets menu, and choose Yarn Spinner -> Yarn Script.
Unity will create a new file. Type in a name for the file, and press return.
The new file that you've just created will contain a single , which has the same name as the file.
To edit a Yarn script, double-click it in Unity. The file will open in your editor. When you save your changes and return to Unity, it will be re-compiled. Learn about editing Yarn Spinner Scripts using the .
A Yarn Project is a file that links multiple Yarn Spinner Scripts together.
To create a new Yarn Project, follow these steps:
Open the Assets menu, and choose Yarn Spinner -> Yarn Project.
Unity will create a new file. Type in a name for the file, and press return.
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.
You can create a new Yarn Project from a script. To do this, follow these steps:
Select the Yarn script in the Project pane.
In the Inspector, click the Create New Yarn Project button.
Clicking this button does two things:
A new Yarn Project will be created next to the Yarn script.
The new Yarn Project will include the Yarn script you created it from in its list of source scripts.
A Yarn Project's inspector shows information about every that are used in the Yarn scripts. This section of the Inspector shows the name, type, description, and default value of each variable.
The Inspector will show information about every variable in the project. If you use a declare statement to declare a variable, you can control the initial value of a variable, as well as its description.
If you don't declare a variable, Yarn Spinner will attempt to figure the variable's type out based on how it's used, and won't be able to provide a description.
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, or if you want to associate each line with assets (like voice over audio clips), you create a new Localisation. To learn about this process, see .
Yarn Projects are used by Dialogue Runners. When a Dialogue Runner is told to start running dialogue, it reads it from the Yarn Project it's been provided.
*
any filename
"*.yarn" will find "One.yarn" and "Two.yarn".
**/*
any path, including subdirectories
Source Scripts
The list of places that this Yarn Project looks for Yarn Scripts.
Base Language
The language that the Yarn Scripts are written in.
Localisations
"**/*.yarn" will find "One.yarn" and "Subfolder/Two.yarn".
..
the parent folder
"../*.yarn" will find "One.yarn" in the parent folder.
A mapping of languages to string tables and associated assets.
This list will only appear if the project is not using the Unity Localisation system. See Adding Localizations and Assets to Projects for more information.
Use Addressable Assets
If this is turned on, the Yarn Project will be set up to tell other parts of the game that localised assets like audio files should be fetched using the Addressable Assets system.
This checkbox will only appear if the Addressable Assets package is installed in your project, and if the project is not using the Unity Localisation System.
Use Unity Localisation System
If this is turned on, the Yarn Project will use the Unity Localisation System to store line data in.
This checkbox will only appear if the Localisation package is installed in your project.
Unity Localisation String Table
The String Table Collection that the Yarn Project uses. When the project is imported or reimported, this String Table will be filled with line content that comes from the project's Yarn Scripts.
This field will only appear if project is using the Unity Localisation system.
Export Strings as CSV
When you click this button, all of the lines in the Yarn Scripts that this project uses will be written to a .csv file, which can be translated to other languages. See Adding Localizations and Assets to Projects for more information.
Update Existing Strings Files
When you click this button, all .csv strings files that are configured in the Languages to Source Assets list will be updated with any lines that have been added, modified or deleted since the strings file was created.
This checkbox will only appear if the project is not usin the Unity Localisation system. See Adding Localizations and Assets to Projects for more information.
Use custom line tagging
When this open is turned on, you can configure which approach Yarn Spinner takes for automatically tagging lines. See Line Tagging for more information.
Custom line tagger
The custom line tagger to use. This dropdown appears when 'Use custom line tagging' is enabled. See Line Tagging for more information.
Add Line Tags to Scripts
When you click this button, any line of dialogue in the Source Scripts list that doesn't have a #line: tag will have one added. See Adding Localizations and Assets to Projects for more information.
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.
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:
In the Unity Editor, open the Assets menu -> Yarn Spinner -> and choose Yarn Project
Name your new Yarn Project file (e.g., MyGame)
The Yarn Project will appear in your Assets folder
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.
You can take a look at the Inspector of your Yarn Spinner Project to get a better understanding of what it's looking for:
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.
Writing Dialogue in Yarn Scripts
Now, let's create a Yarn Script to write your dialogue:
Open the Assets menu -> Yarn Spinner > and choose Yarn Script
Name your script (e.g., Introduction). This will create a file named Introduction.yarn
Setting Up the Dialogue System in Unity
To use your dialogue in-game, you need to add a Dialogue System to your scene:
In your scene hierarchy, right-click and choose Yarn Spinner -> Dialogue System
With the Dialogue System selected in the Hierarchy, locate its Dialogue Runner component in the Inspector.
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:
This default Line Presenter has some configuration options, including:
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 Guide.
Testing Your Dialogue
To test your dialogue system:
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:
Add a Dialogue System to the scene, and assign the Yarn Project
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
Ensure the Line Presenter component is properly configured
Check that the Canvas Group and Text components are correctly assigned
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
Double-click the script to open it in the editor
Here's a simple example of dialogue written in Yarn:
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
Drag your Yarn Project from the Assets view into the "Yarn Project" field in the Dialogue Runner:
If you want dialogue to start automatically, check "Start Automatically" and set your starting node (often titled Start , by convention).
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 .
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:
And then looking at its 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:
Selecting your Line Presenter in the hierarchy
Finding the associated Line Advancer component
Configuring the input method (keycode, button, etc.)
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:
Also set the the Dialogue Runner to Start Automatically, and run the appropriate Yarn node:
Press Play in the Unity Editor. Dialogue should begin!
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:
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!
===
