Here's how to quickly jump in to Yarn Spinner, if you're already reasonably comfortable with Unity.
- Download and import the YarnSpinner package into your project.
- Inside the YarnSpinner folder, open the
Examples/Yarn Spinner Basic Examplescene. - Start the game. Play through the dialogue.
Once you've played with it, open the Example Script file in the Yarn editor (it's in the Examples/Demo Assets folder), and make some changes to the script. Once you've done that, take a look at how Code/DialogueRunner.cs, Examples/Demo Scripts/ExampleDialogueUI.cs and Examples/Demo Scripts/ExampleVariableStorage.cs work. You can also add your own functions to Yarn.
Note: This tutorial assumes that you know at least a little bit about Unity. In particular, it assumes that you know how to get around the Unity editor, how to work with game objects, and how to write scripts in C#. If you don't know these things, check out Unity's documentation!
Yarn Spinner is designed to be easy to work with in Unity. It makes no assumptions about how your game presents dialogue to the player, or about how the player chooses their responses.
To use Yarn Spinner, you use three classes:
DialogueRunner, which is responsible for loading and running your dialogue script;- A subclass of
DialogueUIBehaviour, which is reponsible for displaying the lines and dialogue choices to the player; and - A subclass of
VariableStorageBehaviour, which is responsible for storing the state of the conversation.
These three classes exist in the Yarn.Unity namespace. To create your subclasses of DialogueUIBehaviour and VariableStorageBehaviour, you'll need to add the following code to the top of your C# code:
using Yarn.Unity;
Additionally, you store your Yarn files as .json assets in your Unity projects. These can be stored anywhere - you simply provide add them to the DialogueRunner's inspector. You can also call AddScript on the DialogueRunner at runtime; this is useful for cases like spawning a character who comes with some extra dialogue - all that needs to happen is that character just needs to pass their Yarn script to the DialogueRunner.
Yarn conversations are loaded and managed by a DialogueRunner object. This object is responsible for loading and parsing your Yarn .json files. It also runs the script when it's told to - for example, when you walk up to a character in your game and talk to them.
Your game's dialogue needs to be shown to the user. Additionally, you need a way to let the player choose what their reaction is going to be.
Yarn Spinner makes no assumptions about how you want to handle your dialogue's UI. Want to present as simple list of options? That's fine. Want a fancy Mass Effect style radial menu? Totally cool. Want a totally bonkers gesture-based UI with a countdown timer? Oh man that would be sweet.
Yarn Spinner leaves all of the work of actually presenting the conversation up to you; all it's responsible for is delivering the lines that the player should see, and notifying Yarn Spinner about what response the user selected.
Yarn Spinner comes with an example script that uses Unity's UI system. It's a good place to start.
There's one last necessary component. As you play through a conversation, you'll probably want to record the user's choices somewhere. Yarn Spinner doesn't care about the details of how you save your game state; instead, it just expects you to give it an object that conforms to a C# [interface](C# interface), which defines methods like "set variable" and "get value of variable".
The simplest implementation of this is one that just keeps your variables in memory, but it's pretty straightforward to adapt an existing save game system to use it.
In Yarn, you can create commands that tell your game to do something. For example, if you want a character to move to a certain point on the screen, you might have a command that looks like this:
<<move Sally exit>>
For this to work, the game object named "Sally" needs to have a script component attached to it, and one of those scripts needs to have a method that looks like this:
[YarnCommand("move")]
public void MoveCharacter(string destinationName) {
// move to the destination
}
When Yarn encounters a command that contains two or more words, it looks for a game object with the same name as the second word ("Sally", in the above example), and then searches that object's scripts for any method that has a YarnCommand with the same name as the first word (in this case, "move").
Any further words in the command are passed as string parameters to the method ("exit", in this case, which is used as the destinationName parameter)
Note that all parameters must be strings. DialogueRunner will throw an error if it finds a method that has parameters of any other type. It's up to your method to convert the strings into other types, like numbers.