Yarn Spinner in Unity Scenes

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

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:

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

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:

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

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.

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:

• 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:

1. Selecting your Line Presenter in the hierarchy

2. Finding the associated Line Advancer component

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

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:

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:

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:

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:

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

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