Pardon our dust! Docs for Yarn Spinner for Unity 3.2 and Yarn Spinner for Godot C# are on docs.yarnspinner.dev (the old docs site). Docs for Yarn Spinner for Unity 3.3 (pre-release, out ASAP), Yarn Spinner for Godot GDScript and Yarn Spinner for Unreal Engine (work in progress) are on /docs/ (the new docs site).

YarnDialogueRunner

main controller for yarn spinner dialogue. manages the virtual machine, presenters, and dialogue flow.
class_name YarnDialogueRunner
extends Node

Inherits from Node

#Nested Types

#Constants

#MAX_CONTINUES_PER_FRAME

const MAX_CONTINUES_PER_FRAME = 100

#STALL_WARNING_SECONDS

Once next content has been requested, a presenter that still hasn't finished this many seconds later gets named in a warning, since the dialogue is waiting on it.
const STALL_WARNING_SECONDS = 5.0

#Properties

#allow_option_fallthrough

Continue dialogue if no presenter selects an option.
var allow_option_fallthrough: bool = true

Type bool

#auto_discover_commands

RUNTIME setting. Scan the running scene for _yarn_command_* and _yarn_function_* methods at startup and register them so Yarn can call them. This is what determines whether a command/function actually works at play time. (Contrast with YSLS Scan Path below, which only affects the editor's .ysls.json and has no effect on what runs.)
var auto_discover_commands: bool = true

Type bool

#auto_start

var auto_start: bool = false

Type bool

#discovery_root

RUNTIME setting. Root node whose subtree is scanned for _yarn_command_* / _yarn_function_* methods (empty = the current scene root). A method only registers if a node carrying its script sits under this root when the scan runs. If a command/function errors at runtime, this is the setting to check (or register it explicitly with add_command()/add_function()).
var discovery_root: NodePath = NodePath("")

Type NodePath

#line_provider

var line_provider: YarnLineProvider

Type YarnLineProvider

#option_timeout

Seconds before option fallthrough triggers (0 = no timeout).
var option_timeout: float = 0.0

Type float

#presenters

The presenters this runner drives. List them here in the inspector, or add them at runtime with add_presenter. Child nodes are NOT discovered automatically.
var presenters: Array[YarnDialoguePresenter] = []

Type Array[YarnDialoguePresenter]

#saliency_strategy

var saliency_strategy: int = 0

Type int

#show_selected_option_as_line

Show the selected option's text as a dialogue line before continuing.
var show_selected_option_as_line: bool = false

Type bool

#start_node

var start_node: String = "Start"

Type String

#translation_prefix

Prefix for Godot TranslationServer keys (e.g., "YARN_").
var translation_prefix: String = "YARN_"

Type String

#variable_storage

If null, an in-memory storage is created automatically.
var variable_storage: YarnVariableStorage

Type YarnVariableStorage

#verbose_logging

Log detailed VM execution, instruction traces, and command discovery.
var verbose_logging: bool = false

Type bool

#yarn_project

var yarn_project: YarnProjectResource

Type YarnProjectResource

#ysls_scan_path

EDITOR-ONLY setting. Directory of .gd files to scan when generating the .ysls.json used by the VS Code extension (autocomplete and squiggles). This does NOT register anything at runtime - a green .ysls.json does not mean a command/function is callable. To make it callable, use the Discovery Root above or add_command()/add_function(). When empty, scans the Yarn Project's folder and the scenes that use it; set to "res://" to scan the whole project.
var ysls_scan_path: String = ""

Type String

#Signals

#command_received

Emitted for every command before dispatch, parsed into name and args.
signal command_received(command_name: String, command_args: Array)

Parameters

  • command_nameString
  • command_argsArray

#command_unhandled

Emitted when a command is not handled by any registered handler. If a handler is connected, dialogue pauses until signal_content_complete is called. If no handler is connected, an error is logged and dialogue continues.
signal command_unhandled(command_text: String)

Parameters

  • command_textString

#dialogue_cancelled

Emitted when dialogue ends without reaching a natural finish: an explicit stop_dialogue, a restart via start_dialogue, or a VM runtime error. Fires immediately before dialogue_completed. Teardown (this runner leaving the tree mid-dialogue) emits neither signal.
signal dialogue_cancelled()

#dialogue_completed

signal dialogue_completed()

#dialogue_started

signal dialogue_started()

#node_completed

signal node_completed(node_name: String)

Parameters

  • node_nameString

#node_started

signal node_started(node_name: String)

Parameters

  • node_nameString

#Methods

#add_command_target(String, Node)

enables "target.method" syntax in yarn commands.
func add_command_target(target_name: String, target: Node) -> void

Parameters

  • target_nameString
  • targetNode

#add_command(String, Callable)

func add_command(command_name: String, callable: Callable) -> void

Parameters

  • command_nameString
  • callableCallable

#add_function(String, Callable, int)

func add_function(func_name: String, callable: Callable, param_count: int = -1) -> void

Parameters

  • func_nameString
  • callableCallable
  • param_countint

#add_presenter(YarnDialoguePresenter)

func add_presenter(presenter: YarnDialoguePresenter) -> void

Parameters

#add_strings_to_translation_server(String)

func add_strings_to_translation_server(locale_code: String) -> void

Parameters

  • locale_codeString

#are_options_active()

True while options are being presented and no selection has been applied yet. Presenters that share an input channel with options UI (e.g a line presenter's click-to-continue) should stand down while this is true
func are_options_active() -> bool

Returns bool

#export_for_godot_translation(String)

func export_for_godot_translation(output_path: String) -> int

Parameters

  • output_pathString

Returns int

#find_runner(Node)

static func find_runner(node: Node) -> YarnDialogueRunner

Parameters

  • nodeNode

Returns YarnDialogueRunner

#get_all_headers(String)

func get_all_headers(node_name: String) -> Array[Dictionary]

Parameters

  • node_nameString

Returns Array[Dictionary]

#get_all_node_names()

func get_all_node_names() -> PackedStringArray

Returns PackedStringArray

#get_asset_provider()

func get_asset_provider() -> YarnAssetProvider

Returns YarnAssetProvider

#get_available_locales()

func get_available_locales() -> PackedStringArray

Returns PackedStringArray

#get_cancellation_token()

may be null if no content is being presented.
func get_cancellation_token() -> YarnCancellationToken

Returns YarnCancellationToken

#get_content_frame()

func get_content_frame() -> int

Returns int

#get_current_line_as_dict()

keys: text, character_name, line_id, metadata. empty dict if no line is active.
func get_current_line_as_dict() -> Dictionary

Returns Dictionary

#get_current_node_name()

func get_current_node_name() -> String

Returns String

#get_current_options_as_array()

each element keys: text, option_index, is_available, line_id, metadata.
func get_current_options_as_array() -> Array

Returns Array

#get_header_value(String, String)

func get_header_value(node_name: String, header_name: String) -> String

Parameters

  • node_nameString
  • header_nameString

Returns String

#get_headers(String)

func get_headers(node_name: String) -> Dictionary

Parameters

  • node_nameString

Returns Dictionary

#get_library()

Internal — prefer add_command(), add_function() etc. on the DialogueRunner.
func get_library() -> YarnLibrary

Returns YarnLibrary

#get_line_provider()

func get_line_provider() -> YarnLineProvider

Returns YarnLineProvider

#get_locale()

func get_locale() -> String

Returns String

#get_localisation_debug_info()

func get_localisation_debug_info() -> String

Returns String

#get_localised_audio(String)

func get_localised_audio(line_id: String) -> AudioStream

Parameters

  • line_idString

Returns AudioStream

#get_presenters()

func get_presenters() -> Array[YarnDialoguePresenter]

Returns Array[YarnDialoguePresenter]

#get_saliency_options_for_node_group(String)

func get_saliency_options_for_node_group(node_group_name: String) -> Array

Parameters

  • node_group_nameString

Returns Array

#get_smart_variable_evaluator()

func get_smart_variable_evaluator() -> YarnSmartVariableEvaluator

Returns YarnSmartVariableEvaluator

#get_string_id_for_node(String)

func get_string_id_for_node(node_name: String) -> String

Parameters

  • node_nameString

Returns String

#get_variable_storage()

func get_variable_storage() -> YarnVariableStorage

Returns YarnVariableStorage

#get_visit_count(String)

func get_visit_count(node_name: String) -> int

Parameters

  • node_nameString

Returns int

#has_header(String, String)

func has_header(node_name: String, header_name: String) -> bool

Parameters

  • node_nameString
  • header_nameString

Returns bool

#has_line_advancer()

func has_line_advancer() -> bool

Returns bool

#has_locale(String)

func has_locale(locale_code: String) -> bool

Parameters

  • locale_codeString

Returns bool

#has_localised_audio(String)

func has_localised_audio(line_id: String) -> bool

Parameters

  • line_idString

Returns bool

#has_salient_content(String)

func has_salient_content(node_group_name: String) -> bool

Parameters

  • node_group_nameString

Returns bool

#has_visited_node(String)

func has_visited_node(node_name: String) -> bool

Parameters

  • node_nameString

Returns bool

#has_yarn_node(String)

named has_yarn_node to avoid conflict with Node.has_node()
func has_yarn_node(node_name: String) -> bool

Parameters

  • node_nameString

Returns bool

#is_node_group(String)

func is_node_group(node_name: String) -> bool

Parameters

  • node_nameString

Returns bool

#is_presenting_line()

func is_presenting_line() -> bool

Returns bool

#is_running()

func is_running() -> bool

Returns bool

#load_state_from_persistent_storage(String)

func load_state_from_persistent_storage(save_file_name: String) -> bool

Parameters

  • save_file_nameString

Returns bool

#regenerate_ysls()

regenerates the .ysls.json file next to the yarn project for VS Code integration.
func regenerate_ysls() -> void

#register_line_advancer(Node)

func register_line_advancer(advancer: Node) -> void

Parameters

  • advancerNode

#remove_command_target(String)

func remove_command_target(target_name: String) -> void

Parameters

  • target_nameString

#remove_command(String)

func remove_command(command_name: String) -> void

Parameters

  • command_nameString

#remove_function(String)

func remove_function(func_name: String) -> void

Parameters

  • func_nameString

#remove_presenter(YarnDialoguePresenter)

func remove_presenter(presenter: YarnDialoguePresenter) -> void

Parameters

#request_hurry_up_option()

func request_hurry_up_option() -> void

#request_hurry_up()

Asks the current content to hurry (skip animation, keep it on screen). Delivered through the cancellation token, which presenters watch.
func request_hurry_up() -> void

#request_line_cancellation(YarnLine)

Called by a presenter (via YarnLine.source) when it wants the currently-running line to end. Wrapper presenters (e.g. the Interruption add-on) may substitute themselves as the source and intercept this call. Calls request_next_content. The cancellation token fires, waking presenters parked on YarnCancellationToken.wait_for_next_content. The line actually ends when all presenters have finished: the token is the request, and the presenters' completion confirms it.
func request_line_cancellation(_line: YarnLine) -> void

Parameters

#request_next_content()

Asks the current content to finish and advance. Delivered through the cancellation token: presenters watching it dismiss their content and return, and the runner advances once all of them have returned.
func request_next_content() -> void

#request_next_line()

func request_next_line() -> void

#reset_visit_tracking()

func reset_visit_tracking() -> void

#save_state_to_persistent_storage(String)

func save_state_to_persistent_storage(save_file_name: String) -> bool

Parameters

  • save_file_nameString

Returns bool

#select_option(int)

func select_option(option_index: int) -> void

Parameters

  • option_indexint

#set_audio_base_path(String)

use {locale} placeholder, e.g., "res://audio/dialogue/{locale}/" Points voice-over lookup at the folder of BASE-language audio files (named after the line id: line:tutorial-tom-01 -> tutorial-tom-01.wav). Localised audio comes from Godot's translation remaps (Project Settings > Localization > Remaps), applied automatically when the file loads.
func set_audio_base_path(path: String) -> void

Parameters

  • pathString

#set_content_saliency_strategy(YarnSaliencyStrategy)

Installs a custom YarnSaliencyStrategy, overriding the built-in chosen by the saliency_strategy export. Keeps the VM and the library's has-salient-content context in step. Safe to call before the runner is ready: the strategy is applied once the VM exists.
func set_content_saliency_strategy(strategy: YarnSaliencyStrategy) -> void

Parameters

#set_locale(String)

func set_locale(locale_code: String) -> void

Parameters

  • locale_codeString

#set_project(YarnProjectResource)

cannot be called while dialogue is running.
func set_project(project: YarnProjectResource) -> void

Parameters

#signal_content_complete()

func signal_content_complete() -> void

#start_dialogue(String)

if dialogue is already running, it will be stopped first.
func start_dialogue(node_name: String = "") -> void

Parameters

  • node_nameString

#stop_dialogue()

func stop_dialogue() -> void

#unregister_line_advancer(Node)

func unregister_line_advancer(advancer: Node) -> void

Parameters

  • advancerNode

Generated from Yarn Spinner for Godot GDScript 3.3.