Writing stories / dialogue for Unity games with Yarn

I've been using Yarn for a little while, and I've grown to prefer it as my "talking to NPCs" solution for game development. If you're not familiar, Yarn and Yarn Spinner are a pretty powerful Twine-like plugin for Unity (though it could technically work in any C# game engine) that's geared towards writing video game dialogue, and it was most famously used for Night In The Woods.

Yarn is fairly lightweight, extensible, and it basically gets out of your way. Want to make a really big long monologue, or 100 little pieces of dialogue snippets? Yarn works well for both of those use-cases. (If you want something that's more focused on manipulating very long dense passages of text, you might want something more like inkle/ink, the system that powers the huge 750,000 word narrative game 80 Days.)

To try to provide more resources for other Yarn users, or potential Yarn users, here's a write-up with some advice and a short guide to working with Yarn...

an example "flowchart" in the Fungus scene editor, a different storytelling plugin for Unity

The one weakness (or strength, in my opinion) with Yarn / YarnSpinner is that it's not an all-in-one solution that tries to do everything for you. 

Unlike other plugins like Fungus, Yarn won't work without your being or finding an intermediate-level Unity developer who can comfortably modify the example code to integrate into your game. Yarn is much more bare-bones and lightweight. If you don't already know why you'd want something bare-bones and lightweight, then Yarn will probably seem like a worse choice for you.

To try to alleviate some of that strain and push more collaboration with others, especially on my own projects, I've been working on a little tool called Yarn Weaver. It's basically a small window that lets you run your Yarn scripts / playtest them. This gives writers and narrative designers an easy way to iterate on some dialogue or conversations, without needing to know how to use Unity or code in C#.

So assuming you have a little bit of Unity know-how, here is a brief guide to getting started with the Yarn workflow, as well as tips for integrating Yarn into your game:

1. Download the Yarn editor. It's basically like Twine. It's a bit bare bones, and it hasn't been updated for a while, but it will be good enough for now.

2. In the editor, write a short Yarn script. Double-click on the "Start" node and type whatever you want into it. Below is a short sample script that you can copy and paste if you like:

Hello, this is a Yarn test script!
Each line of dialogue will be displayed separately.
You can also prompt the player to select choices like this:
-> Choice 1
    Notice that Choices begin with "->"
    You can indent below a Choice to say stuff in response to that choice
-> Choice 2
    Like, this line only appears if the player selects Choice 2
Anyway, good luck with Yarn!

3. In the editor, save out your file somewhere. Make sure you save it as a "yarn.txt" file, and don't use ".json" format, which is harder to work with.

4. Download Yarn Weaver. It's a standalone app to playtest your Yarn scripts. Feel free to resize the window and make it bigger / smaller, the text and interface will adapt. But for best results, I recommend keeping the window at a 16:9 aspect ratio, though.

example error-checking in Yarn Weaver

5. In Yarn Weaver, click the "Open..." button, and select your .yarn.txt file from step 3 to playtest it. If there are no bugs with the scripting logic, then it will automatically start playing... but if there were bugs, then it will give you an error message, along with a node name and line number where the bug occurred.

(Note: the printed line number won't always give you the exact location of the bug though, it's just a hint where the system finally gave up, and the real cause of the error might actually be way before or way after.)

6. Once you've tested it in Yarn Weaver and the script seems OK, then download the Yarn Spinner integration for Unity, and import the package into your Unity project. All the new files will appear under Assets/Yarn Spinner/ in your project.

7. In Unity, open the "YarnSpinnerBasicExample" scene and play it. Afterwards, look in the hierarchy at the scene structure... the system is made of 3 core parts: a DialogueRunner component handles all the main processing, a DialogueUI displays the conversation, and a VariableStorage remembers your variable data.

8. Try putting your Yarn script into your game. If you haven't already, put your yarn.txt script file somewhere in your Assets/ folder. Then on the DialogueRunner in this demo scene, replace the "SimpleExampleScript" with your own Yarn script. Play and test it. Hopefully it works!

9. Congrats, you just got Yarn dialogue working in your Unity project!

***

And now, some parting info and advice for integrating Yarn Spinner into your game:

• Don't modify DialogueRunner.cs, that's just core processing logic.
• Use the ExampleDialogueUI.cs and ExampleVariableStorage.cs as a base for your own code. Modify ExampleDialogueUI to change text display, buttons, timers, etc. and modify ExampleVariableStorage to save your conversation data to PlayerPrefs or external save game files.
• In the game, Yarn Spinner basically merges all your Yarn scripts into one mega script. That means each node needs a unique name, but it also means you can share variables or transitions across multiple script files.
• Whenever you want to trigger a conversation, you need to do two things:
• Load the Yarn script via yourDialogueRunner.AddScript( TextAsset yarnScriptFile )... e.g. the Yarn Spinner example NPC.cs code does this automatically for its NPCs in Start()
• Start the conversation via yourDialogueRunner.Start( string nameOfStartNode )... the Yarn Spinner example PlayerCharacter.cs code does this when you press [SPACE] near another NPC.
• (you can check if a conversation is already running if yourDialogueRunner.isDialogueRunning is true or false)

If you need any help or info, check out the full Yarn Spinner documentation, and/or come by the Narrative Game Dev Slack which has a special Yarn Spinner help channel. Good luck!