Installation

Add the Yarn Spinner plugin to your Unreal project, install the Yarn Spinner compiler, and turn the plugin on.

ESC
↑↓ Navigate ↵ Open esc Close

Installing Yarn Spinner for Unreal Engine

Requires Unreal Engine 5.4 or later For Yarn Spinner 3.3.x
This is a pre-release of Yarn Spinner for Unreal Engine. There will be bugs, we might change the API or features with an update, or something may break. We don’t recommend you use it to ship a game yet. Tell us about anything you find with the feedback form.

Yarn Spinner for Unreal Engine isn’t for sale yet. It’s free on GitHub during the pre-release, and it will always be available there for free.

We rely on your support to keep Yarn Spinner free. To support us during the pre-release, sponsor us on GitHub Sponsors or Patreon. GitHub sponsors of $25 and above, and Patreon members of the “Scribe” tier or above, will receive a licence to the paid version when it’s released.

Installing takes three steps: copy the plugin into your project, install ysc, the Yarn Spinner compiler, and check the plugin is turned on.

Adding the plugin to your project

The plugin is in the YarnSpinner-UnrealEngine repository on GitHub. The whole repository is the plugin: YarnSpinner.uplugin is at the top of it. During the alpha, GitHub is the only way to get Yarn Spinner for Unreal Engine.

  1. Clone or download the repository.
  2. In your Unreal project’s folder, open the Plugins folder. If your project doesn’t have one, make it, next to your .uproject file.
  3. Copy the repository into it as a folder called YarnSpinner.
  4. Open your project in the Unreal Editor. Unreal finds the plugin automatically.

When you’re done, you should have Plugins/YarnSpinner/YarnSpinner.uplugin in your project.

The plugin comes as C++ source code, without prebuilt binaries. The first time you open your project with it, Unreal tells you the YarnSpinner and YarnSpinnerEditor modules are missing, and asks whether to rebuild them. Click Yes. Building needs the same C++ tools Unreal uses for any C++ code: Visual Studio on Windows, or Xcode on macOS.

Installing the compiler

Yarn Spinner compiles your Yarn Scripts when Unreal imports them. It uses ysc, the Yarn Spinner command-line tool, which needs the .NET SDK. Install the version the plugin needs:

dotnet tool install YarnSpinner.Console --global --version 3.2.2
Installing ysc with the .NET SDK.

The plugin looks for ysc in the folder where dotnet tool install puts it, in a few other common places, and on your PATH. If it’s somewhere else, set its location in EditProject Settings, under PluginsYarn Spinner, in Ysc Path. See Project settings.

Turning on the plugin

A plugin in your project’s Plugins folder is turned on when Unreal finds it. To check:

  1. In the Unreal Editor, open EditPlugins.
  2. Search for Yarn Spinner. It’s in the Dialogue category, and marked as experimental.
  3. Check that Enabled is ticked. If you change it, restart the editor.
The Yarn Spinner entry in Unreal's Plugins window, with Enabled ticked, the Experimental label, and Version 3.2.8-alpha9.
Yarn Spinner in the Plugins window, turned on.

Turning on Yarn Spinner adds:

  • importers that compile your .yarnproject files into Yarn Project assets, and bring .yarn files in as Yarn Source File assets.
  • a file watcher that reimports a Yarn Project when you save any of its scripts.
  • components you can add to an Actor, such as Yarn Dialogue Runner, Yarn Line Presenter, Yarn Options Presenter and Yarn Line Advancer.
  • Reimport and Generate YSLS File in the Content Browser’s menu for a Yarn Project.
  • two pages in Project Settings, under Plugins: Yarn Spinner and Yarn Spinner Command Registry.

See Setting Up Your Unreal Project.

Licence

Yarn Spinner for Unreal Engine uses the Yarn Spinner Public License. You’re free to use it in your own projects, commercial or otherwise. The only restrictions are around redistributing it as part of a competing dialogue tool, and using it to train AI models. The full terms are in LICENSE.md, in the plugin’s folder. For a plain-language summary, see the YSPL FAQ.

Updating the plugin

  1. Close the Unreal Editor.
  2. Replace the contents of Plugins/YarnSpinner with the new version of the repository. If you cloned it there, pull the new version instead.
  3. Open your project. Unreal asks to rebuild the plugin, as it did when you first installed it.

Read CHANGELOG.md, in the plugin’s folder, before you update. During the pre-release, it lists what you need to change in your project for each new version.

If a new version needs a different version of ysc, update it with the version number the plugin’s README.md gives:

dotnet tool update YarnSpinner.Console --global --version 3.2.2
Updating ysc to a different version.

If something’s not right

If Yarn Spinner isn’t in the Plugins list, check that YarnSpinner.uplugin is at Plugins/YarnSpinner/YarnSpinner.uplugin. The most common cause is an extra folder in between, for example Plugins/YarnSpinner/YarnSpinner-UnrealEngine/YarnSpinner.uplugin after unzipping a download. Move the files up so the .uplugin file is directly inside Plugins/YarnSpinner.

If dragging a .yarnproject file into the Content Browser doesn’t make a Yarn Project, open the Output Log and look for messages from LogYarnSpinner. Could not find ysc in common locations, trying PATH followed by Failed to launch ysc means Unreal can’t find the compiler. Install it, or set Ysc Path, then import the file again.

Next step Understanding Yarn Spinner What Yarn does, and how the pieces of Yarn Spinner for Unreal Engine fit together.
Next Understanding Yarn Spinner