Importing Yarn Files into Unreal

You don’t need to import your .yarn files. The Yarn Project that includes them reads them from disk each time it compiles, and Yarn Spinner watches them for changes.

Compiling happens in the Yarn Project, and errors are reported there. If a script has a mistake, the error shows in the Output Log, not on the .yarn file. See When a script has a mistake.

Adding a script

Unreal doesn’t create Yarn Scripts. Make a new .yarn file in VS Code with the Yarn Spinner extension, or in any text editor.

Put the .yarn file anywhere a Yarn Project’s sourceFiles patterns will match it. With the default pattern, **/*.yarn, that’s the project’s folder or any folder below it. Yarn Spinner notices the new file and reimports your Yarn Projects, and the script is part of the project that matches it.

Yarn Spinner only notices new files in folders it’s already watching: the folder each .yarnproject file is in, and the folders its scripts are in. If you add a script to a new folder, right-click the Yarn Project in the Content Browser and choose Reimport.

To check which scripts a project includes, ask ysc:

ysc list-sources Dialogue.yarnproject

Changing a script

When you save a .yarn file, Yarn Spinner finds every Yarn Project that includes it and reimports them. It does the same when you save a .yarnproject file. If you save several files in quick succession, they’re reimported together, half a second after the last save. Unreal shows a notification for each reimport, and the Output Log has a line saying how many projects were reimported.

Yarn Spinner watches the files on disk, so it doesn’t matter which editor you save from. If Unreal is closed when you save, nothing is reimported when you next open it. Right-click the Yarn Project and choose Reimport.

When a script has a mistake

If a script you’ve saved has an error, the Yarn Project that includes it doesn’t compile, and the reimport fails. The same example appears on the Yarn Projects page.

This script has two nodes with the same title, which isn’t allowed:

title: Start
---
Capsley: Hello!
===

title: Start
---
Capsley: Oh no!
===

When you save it, Unreal shows a notification that the reimport failed, and the Output Log shows one error for each of the nodes:

LogYarnSpinner: Error: C:/MyGame/Dialogue/Dialogue.yarn(0,0): Duplicate node title: 'Start'
LogYarnSpinner: Error: C:/MyGame/Dialogue/Dialogue.yarn(5,0): Duplicate node title: 'Start'

Line numbers in the Output Log count from 0, so (5,0) is the start of line 6.

Rename one of the nodes and save again, and the project compiles. Until it does, the Yarn Project has no compiled dialogue in it.

Opening a script

Unreal doesn’t edit Yarn Scripts itself. Write and edit them in VS Code with the Yarn Spinner extension, or the standalone Yarn Spinner Editor. Both have autocomplete, error checking as you type, and a graph view of your nodes. VS Code can also autocomplete your own Commands and Functions. See The .ysls.json file.

Yarn Source File assets

If you drag a .yarn file into the Content Browser, Unreal imports it as a Yarn Source File asset. It’s there so you can see your scripts in the Content Browser. Dialogue Runners don’t use it, and it doesn’t change what’s in your Yarn Projects.

Double-click a Yarn Source File to see:

Changes you make to Source Text in Unreal aren’t saved to the .yarn file, and are replaced the next time the asset reimports. Yarn Spinner’s file watcher reimports Yarn Projects, not Yarn Source Files. To update a Yarn Source File, right-click it and choose Reimport.

In Blueprints, a Yarn Source File has Get Node Count and Has Node.

Scripts that aren’t in a project

A script that no project includes is never compiled, so none of its nodes can run. Unreal doesn’t warn you about it. To fix it, move the file somewhere a project’s patterns already match, or add a pattern for it to sourceFiles in the .yarnproject file and save it.

If a change doesn’t show up

• Check the Output Log for errors from LogYarnSpinner. If there are any, fix them. See When a script has a mistake.
• Check the script is part of the project, with ysc list-sources.
• If you added the script to a new folder, or edited it while Unreal was closed, right-click the Yarn Project and choose Reimport.
• Check the Output Log for Could not find ysc or Failed to launch ysc. If Yarn Spinner can’t find ysc, the project can’t compile. See Compiling.