Replacement Markup

This sample uses markup to change a line’s text before the Line Presenter shows it. Some of it is a Markup Palette and a TextMeshPro style, which need no code of their own. The rest is three marker processors written for the sample: one hides part of a line, one colours people’s names, and one adds an icon from a sprite sheet.

When you run it, there are four characters in the arena, and each one shows something different:

Running it

In the Project window, open the Replacement Markup sample’s folder, open the Replacement Markers scene, and press Play.

• Move with W, A, S and D, or the arrow keys.
• Walk up to a character and press Space to talk to them.
• Press Space, or click the continue button, to continue.

How it works

The scene uses the Dialogue System prefab. The sample adds its own marker processors to the prefab’s Markup Processors GameObject, next to the two that are already there.

Each marker processor is a ReplacementMarkupHandler, a component you set up in the Inspector. When the scene starts, each one finds the Dialogue Runner’s Line Provider and registers itself for the tags it handles. The Line Provider then calls it whenever a line has one of those tags, before the line goes to the Presenters.

Alice, Liz and Bob each end with a [link] to the script for their markup, and Anika links to the Demo Tags Markup Palette. The Link Markup Handler opens them in the Unity Editor when they’re clicked.

Anika: a palette and a style

Anika’s lines use tags from the Markup Palette:

Anika: or [b][i]wombo[u]combo[/i] them[/u] together[/b] even.
Player: that's awesome.
Anika: you can even define [custom]custom[/custom] markers for [fancy]fancy[/fancy] looks.

The Markup Palette is Demo Tags. Its Basic Markers have a tag for each of b, i, u and s, which make the text bold, italic, underlined or struck through. It adds two tags of its own:

• custom is a basic marker that makes the text green, bold and underlined.
• fancy is in Custom Markers. It makes the text yellow and twice the size, and puts it in square brackets.

Then Anika uses the h2 style:

Anika: If you have a defined [style=h2]style[/style] in a stylesheet we can pass it through to TMP.

The Style Marker Processor wraps the text in a TextMeshPro <style="h2"> tag. H2 is one of the styles in TextMeshPro’s Default Style Sheet, which makes the text bold, blue, and one and a half times the size of the rest of the line.

See Markup for how Markup Palettes and styles work.

Alice: names

Alice’s lines wrap people’s names in [name]:

Alice: Hey there [name]Player[/name].
Player: Hey there [name]Alice[/name], what up?
Alice: I show off how you can use markup to flag important elements based on contents.
Player: oh?
Alice: yes, so for example I am just wondering what [name]Bob[/name] is up to.
Bob: Why are [name=alice]you[/name] wondering what [name=bob]I[/name] am up to?

EntityColourer works out who each tag is about, and colours them:

public override ReplacementMarkerResult ProcessReplacementMarker(MarkupAttribute marker, StringBuilder childBuilder, List<MarkupAttribute> childAttributes, string localeCode)
{
    string nameText = string.Empty;
    if (marker.TryGetProperty("name", out string? value))
    {
        nameText = value.ToLower();
    }

    if (nameText == string.Empty)
    {
        nameText = childBuilder.ToString().ToLower();
    }

    int invisibleCharactersAdded = 0;

    foreach (var entity in entities)
    {
        if (entity.name.ToLower() == nameText)
        {
            var prefix = $"<color=#{UnityEngine.ColorUtility.ToHtmlStringRGBA(entity.colour)}><b>";
            var suffix = "</b></color>";
            childBuilder.Insert(0, prefix);
            childBuilder.Append(suffix);
            invisibleCharactersAdded += prefix.Length + suffix.Length;
        }
    }

    return new ReplacementMarkerResult(invisibleCharactersAdded);
}

protected void Start()
{
    var lineProvider = (LineProviderBehaviour)GameObject.FindAnyObjectByType<DialogueRunner>().LineProvider;
    lineProvider.RegisterMarkerProcessor("name", this);
}

Entities on the Entity Colourer has a colour for Player, Alice and Bob.

Liz: icons

Liz’s lines use one of four sprite tags, depending on which item the player asks about:

-> My Sword
    Liz: sure, it deals additional [lightning]zap damage[/lightning].
-> My Sunglasses
    Liz: sure, it makes you [ice]look cool[/ice].
-> My pet lizard
    Liz: sure, it provides [heart]companionship[/heart].
-> My flamethrower
    Liz: well it is called a [fire]flame[/fire]thrower so I think you can work that one out yourself.

SpriteReplacementMarkerProcessor puts an icon from the effects TextMeshPro sprite asset in front of the text, and wraps both in bold square brackets. The sprite asset is in the sample’s Resources/Sprite Assets folder, which is where TextMeshPro looks for sprite assets by name. [ice] and [heart] use the Buff colour, blue, as good effects, and [lightning] and [fire] use the Debuff colour, orange, as harmful ones.

public override ReplacementMarkerResult ProcessReplacementMarker(MarkupAttribute marker, StringBuilder childBuilder, List<MarkupAttribute> childAttributes, string localeCode)
{
    var start = "<b>[<color=#{0}><sprite=\"effects\" name=\"{1}\">";
    var end = "</color>]</b>";

    string prefix;

    int invisibleCharactersAdded = 0;

    switch (marker.Name.ToLower())
    {
        case "lightning":
            prefix = string.Format(start, ColorUtility.ToHtmlStringRGB(debuff), "lightning");
            break;

        case "ice":
            prefix = string.Format(start, ColorUtility.ToHtmlStringRGB(buff), "water");
            break;

        case "heart":
            prefix = string.Format(start, ColorUtility.ToHtmlStringRGB(buff), "heart");
            break;

        case "fire":
            prefix = string.Format(start, ColorUtility.ToHtmlStringRGB(debuff), "fire");
            break;

        default:
            var diagnostic = new LineParser.MarkupDiagnostic($"was unable to find a matching sprite for {marker.Name}");
            return new ReplacementMarkerResult(new List<LineParser.MarkupDiagnostic>() { diagnostic }, 0);
    }

    childBuilder.Insert(0, prefix);
    childBuilder.Append(end);

    invisibleCharactersAdded += (prefix.Length - 1) + (end.Length - 1);

    for (int i = 0; i < childAttributes.Count; i++)
    {
        childAttributes[i] = childAttributes[i].Shift(2);
    }

    return new ReplacementMarkerResult(invisibleCharactersAdded);
}

Bob: text that gets clearer

Bob’s line is wrapped in [obscurity], with the value of $obscurity:

title: Bob
---
<<declare $obscurity = 0>>

Bob: [obscurity = {$obscurity}]Why hello there, it's nice to meet you friend.[/obscurity]

=> Alice: yeah sorry about Bob, he's hard to understand. <<if $obscurity < 3>>
    Alice: stick with it, you'll get it though.
    <<set $obscurity += 1>>
=> Player: Hey Bob, nice to meet you <<if $obscurity > 2>>
    Alice: See, practice makes perfect!
    Bob: Check out the [link="b79d53f5035d040a1a5118b71586ab5d"]Dynamic Replacement[/link] replacement processor to see how this was done.

===

ObscurityMarkupProcessor reads the tag’s value, and hides part of the text inside it:

public override ReplacementMarkerResult ProcessReplacementMarker(MarkupAttribute marker, StringBuilder childBuilder, List<MarkupAttribute> childAttributes, string localeCode)
{
    if (!marker.TryGetProperty("obscurity", out int value))
    {
        var diagnostic = new LineParser.MarkupDiagnostic("Missing the obscurity property, we cannot continue without it.");
        return new ReplacementMarkerResult(new List<LineParser.MarkupDiagnostic>() { diagnostic }, 0);
    }

    switch (value)
    {
        case 0:
            {
                Obscure(childBuilder, 1);
                break;
            }
        case 1:
            {
                Obscure(childBuilder, 0.67f);

                break;
            }
        case 2:
            {
                Obscure(childBuilder, 0.25f);
                break;
            }
    }

    return new ReplacementMarkerResult(0);
}

Obscure() picks characters at random, and swaps each one for a symbol, like ?, # or @. Spaces are never hidden, so the words keep their shape. Matched Replacement is off in the scene, so each hidden character gets a random symbol. With it on, the same character always gets the same symbol.

See Markup for more about marker processors.

Things to try

• Open the Demo Tags Markup Palette, and change the colour of the custom tag. Then talk to Anika again.
• In DynamicReplacement.yarn, change <<declare $obscurity = 0>> to 1. The first time you talk to Bob, only some of his line is hidden.
• Select Markup Processors and turn on Matched Replacement on the Obscurity Markup Processor.
• Add an entry for Anika to Entities on the Entity Colourer, and use [name]Anika[/name] in one of Alice’s lines.