Line Tagging

Every line of dialogue that Yarn Spinner works with has a unique identifier, which we call the line ID. Yarn Spinner uses the line ID to look up what specific content to show the player, along with other information like which language the user is using. All lines are given a line ID, even if one isn't specified in the script.

The line ID is an important part of your dialogue production process. When a line of dialogue is written in a Yarn Spinner script, a number of additional assets often need to be produced to support it - for example, voice-over audio, translations of the line into other languages, additional voice-over audio for the translations, animation, and more. Each of these additional assets are often handled by different people, or often different companies. All of these assets for this single line are linked together via the line ID.

Different studios have different preferences and requirements for their line IDs - some teams need them to carry lots of information, like the character's name, the point in the game's story at which the line appears, and so on, while some teams need them to be extremely concise. To support this, Yarn Spinner allows you to configure how line tags are generated.

Adding Line Tags

Every line that Yarn Spinner works with has a line tag. If you don't add one yourself, Yarn Spinner automatically creates an internal line tag. If you're working alone, and you're making a text-only game that only needs to work in a single language, this can be all you need. However, if you're going beyond these bare basics, read on.

Adding Tags Manually

You can manually add line tags to lines by writing them in your Yarn Spinner script. To do this, add a #line: hashtag to your line, followed by the unique line ID.

CharacterA: Here's a line. #line:my-custom-line-id

All line IDs in a Yarn Spinner project must be unique across all of your files. If two lines have the same ID, you'll get an error on both of them.

Adding Tags in Unity

You can add line tags to your files in Unity. To do this, select your Yarn Project asset, and click the Add Line Tags to Yarn Scripts in the Inspector. Yarn Spinner for Unity will add unique tags to every line that doesn't already have them, and then re-import your project.

You can control which tags are added by turning on the Custom Line Tagging in the Inspector. For more information on controlling these tags, see Controlling Tags below.

Adding Tags in Visual Studio Code

You can add line tags to your files in the Visual Studio Code editor. To do this, open the Yarn Spinner sidebar, and find your Yarn Spinner project. Right-click it, and choose Add Line Tags.

Adding line tags in Visual Studio Code is currently available in pre-release.

You can control which tags are added by the extension. For more information on controlling these tags, see Controlling Tags below.

Controlling Tags

There are three ways that Yarn Spinner can generate the line IDs:

• The random tagger creates a short, unique, random, hexadecimal line ID.

• The descriptive tagger creates a longer line ID that includes the node name, a sequence number, and the character name (if present.)

• You can also provide your own custom line tagger to suit your own needs.

If you're adding line tags in Unity, you can control which tagger is used by turning on the Use Custom Line Tagging option in the Inspector for your Yarn Project.

If you're adding line tags in Visual Studio Code, you can control which tagger is used by opening the Yarn Spinner sidebar, and clicking the Settings button. In the Editing section, find the Tag Style dropdown, and select the tagger you want to use.

Visual Studio Code only supports the Random and Descriptive taggers. It doesn't support adding a custom tagger.

The Random Tagger

The random line tagger creates a short hexadecimal line ID. This is the original line tagger that Yarn Spinner has used since the very first release, and it's useful when you need a short ID that doesn't take up much space in your Yarn Spinner scripts.

Here's an example of a random tag:

CharacterA: Here's my line! #line:c792e31a

The Descriptive Tagger

The descriptive line tagger creates a longer line ID that contains information about the line, and its position in your story. The tags generated by the descriptive tagger contain the name of the node, a sequence number, and optionally the character name.

Here's an example of a descriptive tag:

CharacterA: Here's my line! #line:Tutorial_100_CharacterA

Sequence Numbers

The descriptive tagger adds a sequence number after the node name, which can help when sorting the tags alphabetically (such as when looking at a list of audio files). Each node gets its own separate sequence.

The tagger tries to leave gaps between lines, which makes it easier to insert new lines later if you need to. If you add line tags using the descriptive tagger to an otherwise un-tagged line, each of the line tags will be given a sequence number 100 higher than the last line.

For example, the following lines:

Alice: This is me saying a line
Alice: And another line
Bob: And me responding
And finally a line that isn't from a character

Would be given tags like this (assuming that this is all in a node called `Tutorial`):

Alice: This is me saying a line #line:Tutorial_0100_Alice
Alice: And another line #line:Tutorial_0200_Alice
Bob: And me responding #line:Tutorial_0300_Bob
And finally a line that isn't from a character #line:Tutorial_0400

If you insert new lines of dialogue in between lines that already have tags, and then re-run the tagger, the tagger will attempt to fit in new sequence numbers between the lines that have them.

For example, adding a line between Tutorial_0200_Alice and Tutorial_0300_Bob like this:

Alice: This is me saying a line #line:Tutorial_0100_Alice
Alice: And another line #line:Tutorial_0200_Alice
Bob: Here's an inserted line
Bob: And me responding #line:Tutorial_0300_Bob
And finally a line that isn't from a character #line:Tutorial_0400

Would result in a line tag like this:

Alice: This is me saying a line #line:Tutorial_0100_Alice
Alice: And another line #line:Tutorial_0200_Alice
Bob: Here's an inserted line  #line:Tutorial_0250_Bob
Bob: And me responding #line:Tutorial_0300_Bob
And finally a line that isn't from a character #line:Tutorial_0400

Running Out Of Space

If the descriptive tagger can't fit a new line in between two lines (for example, you have a line with the sequence number 0100 and another with the sequence number 0101, so there's nowhere in between to put them), the tagger will start adding suffixes to ensure that they're unique.

For example, if you added a line between lines with sequences like this:

Alice: This is me saying a line #line:Tutorial_0100_Alice
Alice: And saying a bit more
Bob: I have a retort #line:Tutorial_0101_Bob

The tagger would create a tag like this:

Alice: This is me saying a line #line:Tutorial_0100_Alice
Alice: And saying a bit more #line:Tutorial_0101_g1_Bob
Bob: I have a retort #line:Tutorial_0101_Bob

The _g1 in the above example represents the generation of the 0101 indexed line in the node. Each indexed line can have as many generations as necessary. This means if we were to add another line in-between 0100 and 0101, its generation number will be 2, but it could be above or below the line with the first generation.

Custom Taggers

If you want to take complete control over how Yarn Spinner generates custom tags for your lines, you can create a custom tagger.

Custom taggers are currently only available in Yarn Spinner for Unity.

To create a custom tagger in your Yarn Spinner for Unity project, create a new C# script that implements the ILineTagGenerator interface.

Here's a very simple custom line tagger that uses the node name and the index of each line to produce line tags.

using System.Collections.Generic;
using Yarn.Compiler;

public class MyCustomTagger : ILineTagGenerator
{
    public void PrepareForLines(Dictionary<string, List<ILineTagGenerator.LineTagContext>> LineContexts, HashSet<string> excludedIDs)
    {
        // This is your script's opportunity to gather information needed for
        // tagging the lines. The LineContexts dictionary is a dictionary
        // mapping node names to a list of line tag context objects, each of
        // which carries information about the line, including its physical
        // location in the file, the text of the line, and more.

        // In this example, we aren't using this information, but a more complex
        // tagger would find this extremely useful.
    }

    public string GenerateLineTag(string node, int lineIndex)
    {
        // This is called once per line that needs tagging. It returns the new
        // line ID to be used for this line. If you want to generate a line ID
        // that uses information about the line itself, you should store the
        // information received in PrepareForLines and use it again later here.
        // The string that you return must begin with "line:".

        // In this example, we'll generate very simple tags that contain the
        // node name and the line index. (This is deliberately very simple - you
        // almost certainly want to use a more sophisticated tagged like
        // DescriptiveLineTagGenerator instead.)
        return $"line:{node}_{lineIndex}";
    }


}

Once you've created this script, you can use it to tag lines. Select your Yarn Project, turn on custom line tagging, and select your custom tag class. Next, click Add Line Tags, and your tagger will be used to add tags.