Yarn Spinner 1

Table of Contents

• Overview
  • Yarn Importer Window
  • Yarn Importer Window Fields
• Sequencer Commands
• Implementing Custom Yarn Commands
  • Step 1 - Subclass YarnCustomCommands
  • Step 2 - Register and Unregister the Command

Use these instructions to import Yarn 1.x stories into the Dialogue System. If you're using Yarn 2.x, see Yarn Spinner 2.

Video Tutorial: Yarn Import

Overview

Note: These instructions are for the Dialogue System's importer for Yarn Spinner 1.2.7.

If you're familiar with Yarn, Unity, and the Dialogue System, importing Yarn stories is fairly straightforward.

One difference to be aware of is that Yarn doesn't explicitly specify actors, but the Dialogue System does. In the Yarn Importer window, you will be able to specify how to interpret your Yarn stories to appropriately assign actors to lines of dialogue.

Yarn Importer Window

Yarn Importer Window

Before enabling the Dialogue System's Yarn importer, make sure the Yarn Spinner package is installed in your project:

https://yarnspinner.dev/docs/unity/installing/

Note that the current Yarn importer works with Yarn 1.x. Install Yarn 1.x:

To begin the import process, select menu item Tools → Pixel Crushers → Dialogue System → Import → Yarn. If you haven't already enabled Yarn import functionality in the Dialogue System's Welcome Window, the first time you select this menu item it will ask if you want to enable it. Click OK. Then allow the project to recompile, and select the menu item again.

The Yarn Importer window looks like this:

Yarn Importer Window Fields

• Player Name: Sets the name of the Player actor. There is only one player actor and leaving this empty uses the default name “Player”.
• Actor Regex : A regular expression used to pull actor names out of a Yarn project. This regex is matched against each line of dialogue, if a match is found the contents of its capture group is used to create new actors. Here is an example regular expression that matches and captures from the start of the string up to but not including the first colon: ^(.+?)\:
  The dialogue line: “Sally: Hello!” will extract the actor name “Sally” using the regex above.
• Line Prefix Regex: A regular expression used to truncate the start of lines in a Yarn project. Usually used in combination with the Actor Regex, when this matches against the start of a line of dialogue, the entire match is stripped out. For example this regular expression: ^.+?\:\s*
  Truncates this line: “Sally: Hello!” to “Hello!”
• Custom Commands File: Specifies the path for the Yarn custom commands file. This file is generated every time a Yarn project is imported, and is required for the newly imported Yarn project to function properly in the Dialogue System.
  • The default value is: Assets/Scripts/YarnCustomCommands.cs
  • The import process performs a destructive write to that file, so make sure this path does not conflict with any other existing files.
  • If your Yarn stories contain any custom commands, you must make a subclass of the YarnCustomCommands class contained in this file to implement your custom commands. See Implementing Custom Yarn Commands for details.
• Yarn Source Files: Add all Yarn source files in your project to this list.
• Localized String Files: Add all Yarn localized string files in your project to this list. It is expected that these filenames will end in “.csv”, and that the locale will be part of the filename. An example filename is: “Sally (de).csv”. Files that do not match this pattern will not be recognized by the importer.
  • These localized dialogue lines are processed in the same way as the default dialogue by the Actor and Line Prefix regular expressions.
• Debug: Ticking this outputs verbose logging to the Console window.
• Output Folder: The folder where the newly created dialogue database will be placed.
• Database Filename: The filename of the newly created dialogue database.
• Encoding: Specifies the text encoding type of the Yarn files. In most cases, you can leave this set to the default value.
• Overwrite: Checking this will overwrite any file that exists at the specified database path (Output Folder / Database Filename).
• Merge: Checking this will not destroy the contents of a dialogue database that is being overwritten, any new data will be added to what is already there.

After setting the fields shown above, click Import to read the Yarn files and create a dialogue database.

Sequencer Commands

To add Cutscene Sequences to your dialogue, use <<seq sequence>> where sequence is one or more sequencer commands such as:

<<seq Audio(Music); AnimatorPlay(Dance, Player)>>

Implementing Custom Yarn Commands

If your Yarn stories contain any custom commands, use these steps to implement them in Unity:

• Create a subclass of the YarnCustomCommands script. Refer to the original YarnCustomCommands script to know which commands to register and implement. Add the script to your Dialogue Manager GameObject.
• In your subclass, use Lua.RegisterFunction() and Lua.UnregisterFunction() to register and unregister each command with the Dialogue System.
• Implement the command by overriding the empty stub that's defined in YarnCustomCommands.

Step 1 - Subclass YarnCustomCommands

The Custom Commands File field is where this class is located. The class will always be named YarnCustomCommands. Subclass this and override its RegisterFunctions() and UnregisterFunctions() methods, making sure to call back to the base class’ RegisterFunctions() and UnregisterFunctions() in your methods.

Add the script to your Dialogue Manager GameObject.

Step 2 - Register and Unregister the Command

Commands are registered by associating the command name with a function that implements it. Commands in Yarn are specified like this:

<<my_command arg1 arg2 arg3>>

where “my_command” is in the place of your command’s actual name. The next thing to do is write the method that will implement your command’s functionality. In this example, we will write a C# method that prints out all arguments passed to it, and call it MyCustomCommand.

public void MyCustomCommand(string arg1, float arg2, bool arg3) 
{
    Debug.Log($"MyCmd('{arg1}', {arg2}, {arg3}) - SUCCESS");
}

Next enter this line in the RegisterFunctions() method of your YarnCustomCommands subclass, substituting your command name for “my_command”, and your method name for MyCustomCommand:

Lua.RegisterFunction("my_command", this, SymbolExtensions.GetMethodInfo(() => MyCustomCommand("", 0f, false)));

Finally, the command needs to be unregistered when the YarnCustomCommands classes are unloaded. Enter this line in the UnregisterFunctions() method of your YarnCustomCommands subclass, again substituting your command name for “my_command”:

Lua.UnregisterFunction("my_command");

Your YarnCustomCommands subclass should now look like this:

using UnityEngine;
using PixelCrushers.DialogueSystem.Yarn;
 
public class YarnCustomCommandExtensions : YarnCustomCommands
{
 
    public override void RegisterFunctions()
    {
        // This MUST be called here:
        base.RegisterFunctions();
 
        Lua.RegisterFunction("my_command", this, SymbolExtensions.GetMethodInfo(() => MyCustomCommand("", 0f, false)));
    }
 
    public override void UnregisterFunctions()
    {
        // This MUST be called here:
        base.UnregisterFunctions();
 
        Lua.UnregisterFunction("my_command");
    }
 
 
    public void MyCustomCommand(string arg1, float arg2, bool arg3) 
    {
        Debug.Log($"MyCustomCommand('{arg1}', {arg2}, {arg3}) - SUCCESS");
    }
}

---

<< Import & Export