> For the complete documentation index, see [llms.txt](https://docs.yarnspinner.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.yarnspinner.dev/yarn-spinner-for-unity/assets-and-localization/line-tagging.md). # 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. ```yarn 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](#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. {% hint style="info" %} Adding line tags in Visual Studio Code is currently available in pre-release. {% endhint %} You can control which tags are added by the extension. For more information on controlling these tags, see [Controlling Tags](#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. {% hint style="info" %} Visual Studio Code only supports the Random and Descriptive taggers. It doesn't support adding a custom tagger. {% endhint %} ## 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: ```yarn 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: ```yarn 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: ```yarn 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\`): ```yarn 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: ```yarn 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: ```yarn 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 ``` {% hint style="info" %} **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: ```yarn 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: ```yarn 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. {% endhint %} ## 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. {% hint style="info" %} Custom taggers are currently only available in Yarn Spinner for Unity. {% endhint %} 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. ```csharp using System.Collections.Generic; using Yarn.Compiler; public class MyCustomTagger : ILineTagGenerator { public void PrepareForLines(Dictionary> LineContexts, HashSet 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.