Dialogue Runner
The Dialogue Runner (YarnDialogueRunner) is the node that runs your dialogue. You give it a Yarn Project, and it steps through your Yarn Scripts one line at a time. It hands each line and set of options to your Dialogue Presenters, calls your Commands, and keeps track of your variables.
Showing the dialogue on screen is left to the Presenters.
Adding a Dialogue Runner
- Add a
YarnDialogueRunnernode to your scene. Search for it by name in the Create New Node dialog.

- Select it, and in the Inspector set Yarn Project to your
.yarnproject, either by dragging it in or with the Select Project File… button. - Choose which node to start from in Start Node. It’s a dropdown of the nodes in your Yarn Project, and defaults to
Start.

Most games need one Dialogue Runner. Each one runs one conversation at a time. For two conversations running at once, such as background chatter while the player talks to someone, use a second Dialogue Runner. The Background Chatter sample does this.
Adding Presenters
The Dialogue Runner can’t show anything until it has Presenters. Most games start with two: a Line Presenter for lines, and an Options Presenter for options. Build this tree:
- Add a
CanvasLayer, which draws your dialogue on top of the rest of your scene. - Under it, add a
YarnLinePresenterfrom the Create New Node dialog. Give it aPanelContainerchild, with aVBoxContainerinside, and three labels inside that: aLabelnamedCharacterLabel, aRichTextLabelnamedTextLabel, and aLabelnamedContinueIndicator. GiveContinueIndicatorsome text, such as “Continue”. - Under the same
CanvasLayer, add aYarnOptionsPresenter. Give it one child, aVBoxContainernamedOptionsContainer, and leave that empty. The Options Presenter creates a button in it for each option while the game runs. - Position the
PanelContainerand theOptionsContainerwhere you want them on screen, for example along the bottom, and give them a minimum size so there’s room for the text.

- Select the
YarnDialogueRunner, and add both Presenters to its Presenters list: add two elements, then assign theYarnLinePresenterto one and theYarnOptionsPresenterto the other.

The label names matter. The Line Presenter uses the first RichTextLabel it finds for the line’s text, a Label with “character” in its name for the speaker, and a node with “continue” or “indicator” in its name for the continue prompt. Each Presenter shows and hides the nodes under it, the panel included.
The Dialogue Runner only talks to Presenters in its Presenters list. It doesn’t look through its children for them. From code, you can add and remove Presenters with add_presenter() and remove_presenter().
Line Presenter and Options Presenter explain how to name the labels differently, change how text appears, and style the option buttons.
Run the scene to play the conversation:
Dialogue Setup
| Setting | What it does |
|---|---|
| Yarn Project | The compiled Yarn Project to run. |
| Start Node | The node to start from when you don’t name one. Defaults to Start. |
| Auto Start | Starts dialogue from Start Node as soon as the scene loads. Off by default. |
| Presenters | The Dialogue Presenters that show your dialogue. |
| Variable Storage | Where your Yarn variables are kept. Leave it empty and the Dialogue Runner creates one that keeps them in memory. See Variables and Storage. |
| Line Provider | Looks up the text for each line, including translations. Leave it empty to use the default. See Line and Asset Providers. |
Starting and stopping dialogue
Turn on Auto Start and the dialogue starts on its own when the scene loads, from the node set in Start Node.

Otherwise, start it from your own code, for example when the player talks to a character:
extends Node2D
@onready var dialogue_runner: YarnDialogueRunner = $YarnDialogueRunner
func talk_to_rosa():
dialogue_runner.start_dialogue("Lighthouse")start_dialogue() takes the name of the node to start from. Here that’s the Lighthouse node.start_dialogue(node_name)starts from the node you name. Leave out the name to use Start Node.await dialogue_runner.run_dialogue(node_name)starts from the node, and returns once the whole conversation has ended.stop_dialogue()ends the dialogue immediately.is_running()returns whether dialogue is running. Use it to stop the player walking off mid-conversation.
While dialogue is running, start_dialogue() and run_dialogue() both log an error and do nothing. Call stop_dialogue() first to switch to another node.
Choosing a node from your own scripts
To get the same node dropdown as Start Node on your own scripts, export a String or StringName with the yarn_node hint, and name the property that holds the Dialogue Runner or the Yarn Project:
@export var dialogue_runner: YarnDialogueRunner
@export_custom(PROPERTY_HINT_NONE, "yarn_node:dialogue_runner") var start_at: StringThe named property can hold a Yarn Project, or anything with a yarn_project property, like a Dialogue Runner. Plain "yarn_node" reads a yarn_project property on the same object. The dropdown lists nodes in alphabetical order, and updates when you change the named property in the Inspector.
To list only some nodes, add a filter after a ;:
@export_custom(PROPERTY_HINT_NONE, "yarn_node:dialogue_runner;filter=Shop") var shop_node: String
@export_custom(PROPERTY_HINT_NONE, "yarn_node:dialogue_runner;filter=Intro_;filter_type=starts_with") var intro_node: String
@export_custom(PROPERTY_HINT_NONE, "yarn_node:dialogue_runner;filter=chapter2;header=tags") var chapter_node: String| Setting | What it does |
|---|---|
filter | The text to look for. A - in it is treated as _, except with matches_regex. |
filter_type | contains (the default), starts_with, ends_with, or matches_regex for a regular expression. The first three ignore upper and lower case. matches_regex doesn’t. |
header | Which header to look in. The default is title, the node’s name. Use tags, or any header your nodes have. Nodes without that header are left out. |
Visit counts
The Dialogue Runner can tell you which nodes the player has seen:
has_visited_node(node_name)returns whether the node has been visited.get_visit_count(node_name)returns how many times.reset_visit_tracking()sets every count back to 0.
Yarn Spinner only counts visits to nodes that a visited() or visited_count() call names somewhere in your Yarn Scripts. For other nodes, these always return false and 0. The counts are stored in the Variable Storage, and are saved and loaded with your variables.
Signals
The Dialogue Runner emits these signals as the dialogue runs:
| Signal | When it’s emitted |
|---|---|
dialogue_started | Dialogue has started. |
dialogue_completed | Dialogue has ended, for any reason, except when the Dialogue Runner leaves the scene tree. |
dialogue_cancelled | Dialogue ended before it finished, because it was stopped or hit an error. Emitted immediately before dialogue_completed. |
node_started(node_name) | The Dialogue Runner has entered a node. |
node_completed(node_name) | The Dialogue Runner has left a node. |
command_received(command_name, command_args) | A Command is about to run. |
command_unhandled(command_text) | A Command didn’t match anything you’ve registered. If anything is connected to this signal, the dialogue waits until you call signal_content_complete(). See Commands. |
For example, to stop the player moving while they’re in a conversation:
func _ready():
dialogue_runner.dialogue_started.connect(func(): player.can_move = false)
dialogue_runner.dialogue_completed.connect(func(): player.can_move = true)How it works with Presenters
When the Dialogue Runner reaches a line, it gives the line to every Presenter in its list at the same time. It waits until all of them have finished with it, then moves on. A Line Presenter and a Voice Over Presenter can work on the same line, and the Dialogue Runner continues only once the text has been dismissed and the clip has finished.
When it reaches a set of options, it gives them to every Presenter in the same way, and uses the first option any of them picks.
The Line Presenter tells the Dialogue Runner to move on when the player continues. If you’re building your own controls, call these yourself:
request_hurry_up()asks the current content to finish appearing at once, such as by skipping a line’s typing effect or making options appear straight away. A line stays on screen.request_next_content()asks the Presenters to finish with the current line and move on. It also ends a running Command that takes a token. If options are showing, it cancels them without picking one. The dialogue then carries on after the options when Allow Option Fallthrough is on. When it’s off, the dialogue logs an error and stops there.
Dialogue Behaviour
The settings under Dialogue Behaviour in the Inspector change how options work.
| Setting | Default | What it does |
|---|---|---|
| Allow Option Fallthrough | On | If none of your Presenters picks an option, carry on with the dialogue after the options. |
| Option Timeout | 0 | How many seconds the player has to pick an option. When the time runs out, the dialogue carries on after the options. 0 means no time limit. |
| Show Selected Option as Line | Off | After the player picks an option, show its text as a line of dialogue before continuing. |
Other settings
The Dialogue Runner’s other groups in the Inspector are explained on other pages:
| Group | What it’s for |
|---|---|
| Localisation | Translation Prefix, the prefix used for your lines in Godot’s translation system. See Translation Prefix. |
| Advanced | Verbose Logging prints details of what the Dialogue Runner is doing to the Output panel, for tracking down problems. Saliency Strategy is covered in Saliency and Storylets. |
| Auto-Discovery | How the Dialogue Runner finds your Commands and Functions. See Commands. |
| YSLS Generation | Only used in the editor, for VS Code autocomplete. See The .ysls.json file. |
Saving and loading
The Dialogue Runner can save your Yarn variables to a file in Godot’s user:// folder, and load them back:
dialogue_runner.save_state_to_persistent_storage("dialogue_save.json")
dialogue_runner.load_state_from_persistent_storage("dialogue_save.json")Both return true if they worked. See Variables and Storage for other ways to save your variables along with the rest of your game.