Markup

Markup is tags in square brackets that you put in your lines, like [b]this[/b]. The Line Presenter uses them to format the text, change the words, or run your own code as the line types out.

Markup comes in two kinds:

• Markup that changes the text. It’s applied before the line is shown. Formatting like [b], and tags that pick words like [plural], work this way.
• Markup that does something while the line types out. It marks a point in the line, and runs when the typewriter reaches it. [pause/] works this way.

The Line Presenter only formats markup when its Use Markup setting is on, which is the default.

Formatting text

The Line Presenter formats these for you, with no extra code, as long as Use Markup is on. The Options Presenter shows options without formatting. If you build your own Presenter, it needs to turn markup into formatting itself.

Rosa: The lamp is [b]never[/b] supposed to go out.

Rosa: Check the [color=orange]oil level[/color] first.

If a line has markup the Line Presenter doesn’t recognise, like [wave]text[/wave], it shows the text without the tags. The markup is still part of the line, so your own code can use it.

To show square brackets in a line, put a backslash before each one: \[like this\]. To show a whole run of text without treating any of it as markup, wrap it in [nomarkup]:

Rosa: The label says [nomarkup][DO NOT TOUCH][/nomarkup].

Links

[link] turns part of a line into something the player can click. You might use it for a word the player can click to read more about, such as an entry in a journal or glossary.

Rosa: It's all written down in [link="logbook"]the logbook[/link].

The text between the tags, “the logbook”, is what the player sees. The value in quotes, logbook, is how your code tells which link was clicked. A [link] without a value is shown as plain text.

Clicking a link doesn’t do anything by itself. It doesn’t continue the dialogue either, even with the Line Presenter’s Click Anywhere to Continue on. To make a link do something, connect to the text label’s meta_clicked signal. It passes the link’s value as a String:

@onready var line_presenter: YarnLinePresenter = $CanvasLayer/YarnLinePresenter

func _ready():
	line_presenter.text_label.meta_clicked.connect(_on_link_clicked)

func _on_link_clicked(meta):
	if meta == "logbook":
		open_logbook()

To react when the mouse moves over a link, for example to show a tooltip, connect to meta_hover_started and meta_hover_ended in the same way.

Godot underlines links. To turn that off, select the text label and turn off its Meta Underlined property. To colour a link, put [color] inside it:

Rosa: It's all written down in [link="logbook"][color=orange]the logbook[/color][/link].

Some limits on links:

• Links only work with a mouse or touchscreen. Players using a keyboard or gamepad can’t select them, so don’t put anything the player needs behind a link.
• The player can only click a link once its text has typed out.
• Options show their text without markup, so a [link] in an option can’t be clicked.
• Use a name for the link’s value, not a web address. // starts a comment in Yarn, so everything after it in the line is ignored.

Changing the words

These tags are replaced with different words, depending on a value. They’re self-closing: they end in /] and have no closing tag.

[select] picks one of several options by name:

<<declare $mood = "happy">>
Rosa: I'm [select value={$mood} happy="glad" sad="sorry"/] you came.

[plural] picks the right word for a number. % is replaced with the number:

<<declare $coins = 3>>
Rosa: You have [plural value={$coins} one="% coin" other="% coins"/].

[ordinal] does the same for positions, like 1st, 2nd and 3rd:

<<declare $visits = 2>>
Rosa: It's your [ordinal value={$visits} one="%st" two="%nd" few="%rd" other="%th"/] visit.

[plural] and [ordinal] follow the rules of the line’s language, so you only need to give the forms that language uses. English uses one and other for plurals, and one, two, few and other for ordinals.

Pausing partway through a line

[pause/] stops the typewriter for a moment. See Typewriter and Effects.

A self-closing tag removes the space that comes after it. Put the space before the tag instead: then [pause/]I heard, not then[pause/] I heard.

Your own formatting tags

To add your own tags, like [happy], that apply formatting you choose, make a palette. A palette is a list of tag names, each with the formatting it applies.

Put this in a script on any node in your scene:

@export var line_presenter: YarnLinePresenter

func _ready():
	var palette := YarnMarkupPalette.new()
	palette.add_basic_marker("happy", true, Color.GOLD, true)
	var big := "[font_size=64]"
	palette.add_custom_marker("loud", big, "[/font_size]")

	var processor := YarnPaletteMarkerProcessor.new(palette)
	processor.register_with_line_provider(line_presenter)

Rosa: I'm [happy]so pleased[/happy] you're here!

Rosa: [loud]HELLO?[/loud]

Your own styles

To add your own names for [style], register a YarnStyleMarkerProcessor with them:

func _ready():
	var styles := YarnStyleMarkerProcessor.new()
	styles.styles["title"] = {
		"start": "[b][color=#4080ff]",
		"end": "[/color][/b]",
	}
	line_presenter.register_marker_processor("style", styles)

Rosa: Have you read [style=title]The Keeper's Log[/style]?

The built-in styles, like [style=italic], still work.

Writing your own text-changing markup

If a palette can’t do what you need, write a marker processor. It gets the text inside the tag, and can change it however you like. This one turns [whisper]text[/whisper] into grey italics:

class_name WhisperMarkerProcessor
extends YarnAttributeMarkerProcessor

const START := "[color=gray][i]"
const END := "[/i][/color]"


func process_replacement_marker(
		_marker: YarnMarkupAttribute,
		child_builder: Array,
		_child_attributes: Array,
		_locale_code: String
) -> ReplacementMarkerResult:
	var start := YarnMarkupParser.brackets_to_tags(START)
	var end := YarnMarkupParser.brackets_to_tags(END)
	child_builder[0] = start + child_builder[0] + end
	var added := START.length() + END.length()
	return ReplacementMarkerResult.new([], added)

Register it on the Line Presenter, with the tag name it handles:

func _ready():
	var whisper := WhisperMarkerProcessor.new()
	line_presenter.register_marker_processor("whisper", whisper)

Rosa: [whisper]Don't tell the others.[/whisper]

You can register the same processor for more than one tag. The first argument, the tag itself, has its name in name and any values you gave it, such as [whisper volume=2].

Running code partway through a line

Markup can trigger your own code when the typewriter reaches a certain point in a line, like changing a character’s expression, playing a sound, or shaking the screen. To do this, write an event handler and add it to the Line Presenter’s Event Handlers list.

This is the handler from Typewriter and Effects, which shakes the dialogue box wherever a line has [shake_box/]:

extends YarnActionMarkupHandlerNode

@export var panel: Control

var _positions: Array[int] = []


func on_prepare_for_line(
		line: Variant,
		_text_control: Control = null
) -> void:
	_positions.clear()
	for attribute in (line as YarnMarkupParseResult).attributes:
		if attribute.name == "shake_box":
			_positions.append(attribute.position)


func on_character_will_appear(
		character_index: int,
		_line: Variant,
		_token: Variant = null
) -> Signal:
	if character_index in _positions:
		return YarnEffects.shake(panel, 12.0, 0.4)
	return Signal()

To use it:

1. Add a Node to your scene, and attach the script to it.
2. Set its Panel to the Line Presenter’s PanelContainer.
3. Select the Line Presenter, and add the node to its Event Handlers list.

An event handler can define any of these functions. Write only the ones you need:

If the player presses Continue Action while your handler is waiting, token.is_hurry_up_requested becomes true. For anything that takes a while, check it and finish early.

Samples

Two samples show more of this. Open them from the samples browser in the Yarn Spinner tab:

• Replacement Markup uses palettes, styles and marker processors.
• Inline Events uses event handlers to move a character and change their expression partway through a line.