For this final step in the beginner's guide, you can choose your preferred engine:

• Yarn Spinner for Unity (2021.3 or newer, Officially Supported)

• Yarn Spinner for Unreal (5.1 or newer, coming Late-2023)

We also provide experimental Yarn Labs support for:

• Yarn Spinner for Godot (C# edition 4.0 or newer).

This step of the beginner's guide helps you move from writing Yarn scripts outside of a game engien, to initial integration steps to turn them into a game with Unity.

First, launch the Unity Hub, and create a new project for Unity 2021.3 or newer.

Installing Yarn Spinner for Unity

In the new empty project, open the Edit menu -> Project Settings..., and choose the Package Manager section in the left column of the Project Settings window that appears.

In the middle area of the window, add an entry named OpenUPM, with the URL set to https://package.openupm.com, and the Scopes set to dev.yarnspinner. Then, click Save.

This process adds the OpenUPM Package Registry, which is one of the ways we distribute the offical Yarn Spinner for Unity package.

With the OpenUPM Package Registry added to the project, you can close the Project Settings window and open the Window menu -> Package Manager. In the Package Manager window that appears, choose the Packages dropdown, and change the view to Packages: My Registries.

This will show the packages available from the registry (and scope) that you just added, which is likely to only be Yarn Spinner at this point. Select the Yarn Spinner package from the column on the left of the Package Manager window, and click the Install button found on the bottom right. Yarn Spinner for Unity will be downloaded and installed inside your project.

Using Yarn Spinner for Unity

Yarn Spinner for Unity provides a way to get the contents of your Yarn scripts into Unity, which allows you to construct a game around your dialogue. This beginner's guide shows guides you through one simple way of using Yarn Spinner for Unity to do this.

The provided Yarn Spinner views use the Unity package TextMesh Pro to display text. This means you will need to install it before using Yarn Spinner. To do this, open the Window menu and choose -> TextMesh Pro -> Import TMP Essential Resources.

In the empty project that now has the Yarn Spinner for Unity package installed, right click in the Hierarchy and choose Yarn Spinner -> Dialogue Runner. This will add a new Dialogue System prefab to your scene, which we'll be working with in a moment.

The Dialogue Runner that has been added to your scene is a prefab supplied by Yarn Spinner for Unity that acts as a bridge between the dialogue written in your Yarn scripts, and everything that happens in Unity.

Specifically, it works with two different things, which are key concepts when working with Yarn Spinner for Unity:

• a Yarn Project

• a Dialogue View

Creating a Yarn Project

First, we'll look at the Yarn Project. A Yarn Project is a Untiy asset that lives on disk. Create one by right-clicking in the Assets pane and choose Create -> Yarn Spinner -> Yarn Project.

With the new Yarn Project created, name it FirstProject, and then use the same menu to create a Yarn Script. Name the Yarn Script MyStory.

The Yarn Script you've created is actually a .yarn file that's now named MyStory.yarn. Double click it in the Assets pane to open it in Visual Studio Code.

Put the following Yarn script into MyStory.yarn, save the file and return to Unity:

title: Start
tags:
---
Narrator: Oh, hello!
    -> Hi, where am I?
        Narrator: You're in Unity!
            -> Oh.
            <<jump Oh>>
            -> How did I get here?
            <<jump Unity>>
===

title: Oh
---
Narrator: Yeah, fun, right?
===

title: Unity
---
Narrator: Someone read the Beginner's Guide!
===

To connect the Yarn Project you created to the Dialogue Runner that's in the scene, select the Dialogue Runner in the Hierarchy and drag the FirstProject from the Assets pane into the Yarn Project slot, as shown here:

With that done, select the Yarn Project FirstProject in the Assets pane, and look to the Inspector.

You'll see the Source Files field contains **/*.yarn — this tells this specific Yarn Project to look for all .yarn files in the same folder as the Yarn Project asset, and any subfolders. Thus, any .yarn files next to it will be included as part of the project, which means MyStory.yarn will be found.

At this point, you can play your project, and step through the dialogue in the default Yarn Spinner for Unity Line View and Options List View:

What's a Line View and an Options List View?

To understand how this is working, it's important to understand the concept of Yarn Spinner Dialogue Views. Select the Dialogue System in the Hierarchy, and expand the Dialogue Views section:

This section is where you specify which DIalogue Views should be used to display the content coming from the Yarn script(s): in other words, how the lines of dialogue, and choices, should be displayed.

A Dialogue Runner can have multiple Dialogue Views. For example, by default the Dialogue System prefab has one Dialogue View that's designed to display lines of dialogue (Line View), and another that's in charge of displaying options to the player (Options List View).

All Dialogue Views receive all lines and options, and it's up to them to handle them appropriately. So the Line View that we supply will only displays lines that are not options, and the Options List View will only display lines that are options.

Next steps with Yarn Spinner for Unity

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 join the Discord, to chat with other Yarn Spinner users, the Yarn Spinner team, seek help, and share your work.

This step of the beginner's guide helps you move from writing Yarn scripts outside of a game engine, to initial integration steps to turn them into a game with Godot

First, launch Godot 4.1 (C# version) and create a new project.

Installing Yarn Spinner 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!

Using Yarn Spinner for Godot

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:

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 by right-clicking in the FileSystem dock, and choosing Resource...:

Then filter to the YarnProject resource type, and click the Create button:

Name the new Yarn Project FirstProject.tres.

Next, create a new Yarn script (a file with a .yarn extension) by right-clicking in the FileSystem dock, and choosing New TextFile:

In the resulting New Text File... window, select All Files (*) from the dropdown in the corner, 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.tres 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 the DialogueRunner node in the Scene dock, and look to the Inspector. 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 View and Options List View:

Next steps with Yarn Spinner for Godot