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, Yarn Spinner for Godot GDScript and Yarn Spinner for Unreal Engine (work in progress) are on /docs/ (the new docs site).

Yarn Spinner for Godot (GDScript) Changelog

Every release of Yarn Spinner for Godot (GDScript).

3.3.1Latest2026-11-17

Early Access 3.3.1

  • The bundled compiler is made executable before it runs. If it still can’t run, the editor shows an error with the command to fix it, instead of failing without saying why.
  • Functions can now wait! A function that uses await, such as one that waits for the player to pick an item, pauses the dialogue until it returns a value. Give it a typed return, for example a -> String, so the compiler knows what it returns. Functions called from smart variables or when: headers still have to return straight away! Don’t forget.
  • Commands and functions can now be cancelled!! If the last parameter of a handler is a YarnCancellationToken, the Dialogue Runner passes one in. A command’s token is cancelled by request_hurry_up(), request_next_content() and stop_dialogue(). A function’s token is cancelled when dialogue stops..
  • A _yarn_function_ method that isn’t static is now an instance function. Its first argument in Yarn is tebh name of the node to call it on, like health("Alice"). Previously, it was skipped with an error. The .ysls.json lists it with the node as its first parameter…
  • Commands and functions can now take your own types as parameters!! Add a converter with add_converter() on the Dialogue Runner or YarnSpinner.register_converter(), or write a static _yarn_converter_<TypeName>(input: String) method, which is found automatically. A converter takes the text from the Yarn Script and returns the value, or null if nothing matches.
  • Commands and functions can now take a Yarn enum as a parameter, using the enum in the generated variables class, for example func feed(food: MyVariables.FoodType). They accept the enum’s value ({$food}), its full case name (FoodType.Apple) or its short case name (.Apple). In the .ysls.json, these parameters are marked as that Yarn enum… so the VS Code extension suggests its cases. Projects older than file version 5 get the enum’s raw type instead.
  • A function with a parameter whose type can’t be worked out, including a ... parameter, is now left undeclared, rather than being declared as taking fewer arguments than it does, which made calls to it fail to compile. This applies to functions found in your scripts and to ones listed in definitions files.
  • Enum parameters typed with the generated variables class are recognised before that class has been generated, so a Yarn Project that uses them compiles on its first import.
  • Presenters have a new run_command(command_text, token) method. The Dialogue Runner calls it on every Presenter before each command runs, and waits for them all to return.
  • The Dialogue Runner has a new run_dialogue(node_name) method, which returns once the whole conversation has ended.
  • request_hurry_up() on the Dialogue Runner now hurries options as well as lines. request_next_line() and request_hurry_up_option() still work, but are deprecated in favour of request_next_content() and request_hurry_up().
  • The Line Advancer has new request_hurry_up_content() and request_next_content() methods, matching Yarn Spinner for Unity! Its request_hurry_up(), request_next_line() and request_option_hurry_up() methods still work, but are deprecated.
  • A Presenter’s on_dialogue_started, on_dialogue_completed, on_node_started and on_node_completed methods can take a YarnCancellationToken as an extra last parameter. Presenters without it work as before.
  • An instance command or function can be on a type that has a converter, not only on a node’s script. Its first argument goes to the converter, and the method is called on the object it returns.
  • A String parameter can be marked for the VS Code extension with a line in the method’s ## comment: @yarn_node name for node names, or @yarn_enum name EnumName for an enum’s cases.
  • A function whose return type is an enum is now an error when it’s called, as in Yarn Spinner for Unity. Return the enum’s value instead.
  • Registering a command or function with a lambda now logs a deprecation warning. Pass a named method instead, please.
  • New Yarn Projects are created at project file version 5 (i.e. YS 3.3). The Yarn Project Inspector shows an Upgrade Yarn Project button for older projects.
  • In a version 5 project, calling a function that doesn’t declare a usable return type, such as one that returns a Signal, now explains how to fix it :)
  • The .ysls.json now includes functions and commands registered with a plain add_function(...) or add_command(...) call, not only ones written as runner.add_function(...).
  • The .ysls.json now lists the built-in functions that only Yarn Spinner for Godot has, such as abs, clamp, uppercase and plural, so the VS Code extension no longer marks them as unknown. Sorry!
  • In the .ysls.json, parameters that use a converter are written as instances of their type, the same way Yarn Spinner for Unity writes them. In projects older than file version 5, instance parameters are written as strings, so those functions are still declared. Cancellation token parameters are left out.
  • Functions that wait are now marked async in the .ysls.json…
  • The .ysls.json now flags commands and functions that can’t work, with the same error codes Yarn Spinner for Unity uses, so the VS Code extension marks them: YS1004 for a function whose return type Yarn can’t use (such as void or Array), YS1006 for a YarnCancellationToken that isn’t the last parameter, and YS1008 for a parameter type Yarn can’t pass in (such as Array or Dictionary). Each entry also has containsErrors.
  • A new project setting, Yarn Spinner > YSLS > Included Addon Paths, lists folders under res://addons for the .ysls.json scan to read. Addons are still skipped by default. Use it when an addon registers functions or commands, for example with YarnSpinner.register_function() from an autoload, so the compiler and the VS Code extension know about them.
  • Node pickers in the Inspector now list nodes alphabetically, and can be filtered. Add ;filter=Start to the yarn_node hint, with optional filter_type (contains, starts_with, ends_with or matches_regex) and header to filter on a header other than the title. contains, starts_with and ends_with ignore upper and lower case; matches_regex doesn’t, the same as in Yarn Spinner for Unity!
  • Options now keep their markup formatting, such as [b], [style] and your own palette tags. The default option scene has a RichTextLabel, set as the Text Label of its YarnOptionButton, which takes its font, size and colours from the button. Option scenes of your own that only have a Button still show plain text; add a RichTextLabel and set it as the button’s Text Label to get formatting.
  • Unavailable options are now struck through in the default option scene, the same as in Yarn Spinner for Unity.
  • [br /] now starts a new line.
  • Options can’t be picked until they have finished fading in, the same as in Yarn Spinner for Unity.
  • New YarnPaletteMarkerProcessorNode and YarnStyleMarkerProcessorNode, so a markup palette and your own [style] names can be set up in the Inspector without code. They work on every line and option of their Dialogue Runner.
  • When a command or function takes a Yarn enum, case names are now checked before backing values, the same as in Yarn Spinner for Unity. This only matters if one case’s backing value is the same text as another case’s name.
  • The Dialogue Runner now waits for a Presenter’s on_node_started() and on_node_completed() to return, the same as in Yarn Spinner for Unity. A Presenter that uses await in them, for example to fade in a title, holds the node’s first line until it’s done. Presenters that don’t wait in them work as before.
  • try_get_value() on the built-in Variable Storage now finds a variable that hasn’t been set yet, with its declared value, and a smart variable, with its current value, the same as in Yarn Spinner for Unity. Previously, it only found variables that had been set. Use the new try_get_stored_value() to check only what’s been set. A Variable Storage of your own can return the new try_get_unstored_value() from its try_get_value() to do the same.
  • start_dialogue() no longer restarts when dialogue is already running. It logs an error and leaves the current dialogue alone, the same as run_dialogue() and Yarn Spinner for Unity. Call stop_dialogue() first to switch to another node.
  • <<wait>> can now be skipped. Hurry-up and next-content both end it early, the same as in Yarn Spinner for Unity, and a Line Advancer’s hurry input now skips a running command. A negative duration is an error.
  • request_next_content() now cancels options that are showing: no option is picked, and the dialogue carries on after the options, the same as in Yarn Spinner for Unity.
  • After the player picks an option, the Dialogue Runner now waits for every Presenter’s run_options() to return before it carries on, so a Presenter can finish hiding its options first.
  • A Presenter that’s disabled (its Process Mode is Disabled, or it inherits that from a parent) is no longer sent options or on_dialogue_started(). run_command() is now called on every Presenter, disabled or not. This matches Yarn Spinner for Unity.
  • If a command or function takes a node and no node with that name is found, the Dialogue Runner now logs an error and doesn’t call it, the same as in Yarn Spinner for Unity. Previously it passed null.
  • A command or function on a node is now also found when the script is on a child of the node you name, the same as in Yarn Spinner for Unity.
  • The % operator now works on decimal numbers, so 5.5 % 2 is 1.5, and no longer reports an error when the second number is zero. random_range() and random_range_float() now round both of their bounds to whole numbers. Both match Yarn Spinner for Unity.
  • A line’s metadata no longer includes its line: tag, the same as in Yarn Spinner for Unity.
  • The typewriter now follows Engine.time_scale, like the Presenter’s fades already did.
  • The Voice Over Presenter no longer has a Volume dB setting and no longer changes its audio player’s volume. Set the volume on the audio player or its bus.
  • Compiler warnings now appear in the Output panel when a Yarn Project is imported. Previously only errors did.
  • The Yarn Project Inspector warns when a project’s file version is newer than this version of Yarn Spinner supports.
  • Fixed markup that mixes a palette or [style] tag with a built-in tag such as [b]. The built-in tag was being put inside the other tag’s formatting code.
  • Fixed a character name with a double quote in it, such as Mr "X" Jr: Hello, showing the line as raw markup.
  • Fixed the Yarn Project Inspector showing the same translated count for every language.
  • YarnDialogueView now fades its panel in and out around each line and set of options, and keeps the line before a set of options on screen above them, like the Dialogue System prefab in Yarn Spinner for Unity.
  • Presenters have a new fade_target property. Set it to a CanvasItem for the Presenter to show, hide and fade, when the Presenter isn’t one itself and doesn’t have one as a child.
  • A YarnOptionButton whose Text Label has Fit Content on now grows to fit its text.
  • first_letter_caps() is now declared to the compiler, so it works in version 5 Yarn Projects and inside lines, and is listed in the .ysls.json.
  • A Line Advancer’s Advance Action no longer does anything while options are showing, so it can’t skip a choice. Calling request_next_content() on the Dialogue Runner still cancels them.
3.3.0

Early Access 3.3

  • Presenters now get on_dialogue_started before on_node_started, and the Dialogue Runner emits dialogue_started before node_started. The start node is entered after every Presenter has finished on_dialogue_started.
  • A run of content that finishes instantly, such as a looping node whose Presenters return straight away, no longer locks the game. The Dialogue Runner now waits a frame after 100 pieces of content in a single frame.
  • A Presenter listed in a Dialogue Runner’s Presenters array can now use dialogue_runner in its own _ready(), wherever it sits in the scene tree. add_command(), add_function() and add_command_target() also work before the Dialogue Runner’s _ready() has run.
  • The editor’s Docs links now open the Yarn Spinner for Godot (GDScript) documentation, and the Yarn Project Inspector’s help text points to Project > Tools > Create Yarn Project….
  • The native compiler and plugin now report version 3.3.
  • The native compiler now uses the functions declared in a Yarn Project’s definitions files, not only the ones found in the project’s GDScript. Paths can be relative to the .yarnproject, absolute, res:// paths, or start with ${workspaceRoot}, which stands for the folder containing project.godot. Globs such as ${workspaceRoot}/definitions/*.ysls.json work too. Files in the current format (functions, yarnName, return.type) and the older one (Functions, YarnName, ReturnType) are both read.
  • When a function is declared both in the project’s GDScript and in a definitions file, the GDScript declaration is used.
  • The importer warns about definitions files it can’t find or read, and about placeholders other than ${workspaceRoot}.
  • Editing a .ysls.json that a Yarn Project lists in its definitions now recompiles that Yarn Project.
  • The native compiler is built against Yarn Spinner 3.3! And compiles each Yarn Project at its own projectFileVersion. In a version 4 project, using a function that isn’t declared is a warning. In version 5, it’s gonna be an error.
  • Functions in definitions files with enum or instance parameters need project file version 5. In a version 4 project the importer warns and leaves the function undeclared. In version 5, enum parameters are checked against the enum’s real type.
  • It’s version 5 of the file all the way for this version.
  • Functions in definitions files with default-valued parameters are now declared, and can be called with or without those arguments.
  • Fixed the native compiler failing on every Yarn Project that otherwise compiled, under Yarn Spinner 3.3!
  • When the importer adds its generated .ysls.json to a version 5 project, it writes the path as ${workspaceRoot}/.... Version 4 projects get the file name, as before. In a version 2 or 3 project, which can list only one definitions file, it fills in definitions when it’s empty and otherwise leaves the project unchanged and warns, instead of turning definitions into a list.
  • The importer no longer adds its generated .ysls.json to definitions again when the project already lists it under a different path, such as through ${workspaceRoot}.
  • Yarn Projects now keep the enums declared in their Yarn Scripts, with each case’s name and value, and the type of every declared variable, so a game can read them while it runs. YarnProjectResource has new enums and variable_types properties, and has_enum(), get_enum_cases(), get_enum_value(), get_enum_case_name() and get_variable_type(). These are filled in by the native compiler; a project compiled with the ysc fallback has them empty.
  • Every Yarn Project is reimported once after updating, so existing projects pick up their enums and variable types.
  • The Yarn Spinner tab’s main screen has a new edit_file_at_node() method, so other editor plugins can open a Yarn Script at a particular node.
3.2.0

Early Access 3.2

Yarn Project Inspector

The Inspector for .yarnproject files now matches the one in Yarn Spinner for Unity.

  • The Yarn Spinner header (logo and links) from the Dialogue Runner’s Inspector now appears on Yarn Projects, Yarn scripts, and .ysls.json files too.
  • Compile errors are listed in the Inspector, grouped by script. Projects that fail to compile still import, so their errors are shown.
  • The project’s source file patterns can be edited, added, and removed directly in the Inspector. Patterns now support folders and ** anywhere (Dialogue/**/*.yarn), and excludeFiles is respected.
  • Add Line Tags to Yarn Scripts adds #line: IDs to every untagged line, using either the random or the descriptive line tagger.
  • Export Strings and Metadata as CSV writes a Godot translation CSV using the project’s base language, plus a -metadata.csv file with each line’s file, node, line number and tags.
  • Update Existing Strings Files finds the translation CSVs that contain the project’s lines, adds new lines, removes deleted ones, and marks translations whose source text has changed with (NEEDS UPDATE).
  • The project can generate a typed Variable Storage class, with a property for each declared variable and a GDScript enum for each Yarn enum. Choose its class name and parent class in the Inspector.
  • Changes are made with Apply and Revert, and switching away from a project with unapplied changes asks whether to keep them. This is very Unity-esque, so we’re open to feedback.

These settings are also available in the Import dock.

Strict warning compatibility

A handful of internal variable declarations relied on inferring their type from a Variant value, which fails to compile in projects that escalate GDScript’s INFERENCE_ON_VARIANT warning to an error. Those declarations now use explicit types, so the addon compiles cleanly under strict warning settings.

Yarn node picker for your own scripts

The node dropdown used by the Dialogue Runner’s start_node can now be used on your own exported properties. Export a String or StringName with the yarn_node hint and name the property that holds the Yarn Project or Dialogue Runner:

@export var dialogue_runner: YarnDialogueRunner
@export_custom(PROPERTY_HINT_NONE, "yarn_node:dialogue_runner") var start_at: String

The source property can hold a YarnProjectResource or anything with a yarn_project property, such as a Dialogue Runner. Plain "yarn_node" reads a yarn_project property on the same object. The dropdown refreshes when the source property is changed in the Inspector.

Yarn Projects work in @tool scripts

YarnProjectResource, YarnProgram, YarnNode and YarnInstruction are now @tool, so their methods can be called from editor scripts. get_program(), get_node_names() and has_node() used to fail in the editor, because Godot only exposes a non-tool script’s exported properties there. The parsed program is cached and refreshed when the project is reimported.

The Samples tab in the Yarn Spinner editor screen now lists samples in a learning-path order (starting points first, then core features, presentation, voice over, and saliency) instead of alphabetically, and every sample card has a screenshot.

YarnDialoguePresenter is abstract

YarnDialoguePresenter is now marked @abstract, matching its Yarn Spinner for Unity equivalent (DialoguePresenterBase). Attaching the base script to a node used to look like it worked, then displayed nothing at runtime; the editor now refuses the attach outright. Attach one of the Presenters from addons/yarn_spinner/ui/ (YarnLinePresenter, YarnOptionsPresenter, and friends), or subclass the base for your own. Existing subclasses are unaffected.

Functions can be used inside lines

A function call inside a line, like Rosa: You have {coin_count()} coins., used to fail to compile with “Can’t determine the type of the expression”. This was because the compiler was never told what your functions return, so it could only guess from where each call was used, and a line doesn’t say.

Now, before compiling, the importer scans your scripts for functions (the same scan that writes the .ysls.json, so _yarn_function_ methods and functions added with add_function() are both found) and passes each one’s parameter and return types to the compiler. It also declares the built-in functions the compiler didn’t know about: visited, visited_count, has_any_content, abs, sign, clamp, lerp, inverse_lerp, smoothstep, pow, sqrt, wrap, mod, plural, ordinal, length, uppercase and lowercase.

Calling a function with the wrong type of argument, or using its result as the wrong type, is now a compile error instead of a problem at runtime. Functions are found in the same files the .ysls.json is written from: the Yarn Project’s folder and the scenes that use it, or the folder set in the Yarn Project’s Ysls Scan Path import option.

The bundled native compiler now accepts function declarations, which is how it gets them. The ysc fallback, used where there’s no native compiler, gets them from the project’s "definitions" instead:

  • The importer adds the project’s .ysls.json to the .yarnproject’s "definitions" if it isn’t already listed. Anything already there is kept, and the file is only written when the entry is missing. If "definitions" holds something other than a path or a list of paths, it’s left alone and you’ll get a warning.
  • Functions in the .ysls.json are now written under "Functions", in the PascalCase shape ysc reads. Commands are unchanged. The VS Code extension reads both.
  • ysc only reads the first file in "definitions", so if your project already listed another definitions file first, that’s the one it uses..

Faster function calls and numbers

All the operators in Yarn (+, <, == et al) are a function call, so the virtual machine calls functions a lot. Each call used to build a Dictionary for every argument, which was just used to report whether converting it worked. Arguments that already have the type the function declares now skip the conversion, so the argument array is filled by index instead of with push_front. A call to Number.Add is now faster, basically.

e.g. Whole numbers up to 2^24 are exact as 32-bit floats, so they now skip the slow paths:

  • YarnNumber.to_f32 returns them as they are, instead of round-tripping through a PackedFloat32Array.
  • YarnNumber.to_display_string prints them with str(int(v)), which makes turning a whole number into text much faster.
  • YarnNumber.to_int32 skips banker’s rounding for them.

YarnInMemoryVariableStorage.get_value now returns a stored value directly instead of going through try_get_value’s {found, value} Dictionary. Reading a stored variable went from 0.42 µs to 0.13 µs. Reading a variable that’s only declared and hasn’t been set yet now checks the stored values first.

Changed

  • Gamepads can work with the Presenters out of the box. Godot’s default ui_accept and ui_cancel have no gamepad buttons, so a gamepad couldn’t advance dialogue or choose an option. At startup, the YarnSpinner autoload now adds the A button to ui_accept and the B button to ui_cancel, but only when that action has no gamepad buttons, so projects with their own gamepad bindings are left alone.
  • The error for a command called with the wrong number of parameters now names the handler plus its signature and script, and tells you which parameters have no default value. If the handler is a lambda, it says that lambdas can’t have optional parameters. If a project’s .ysls.json accepts the call, the error says it’s out of date with the code and needs regenerating, as editors/VS Code reads the .ysls.json but the game reads the GDScript function.
  • The bundled compiler binaries are now named for their platform and architecture: ysc-native-macos-universal, ysc-native-windows-x64.exe, ysc-native-linux-x64, and the arm64 builds for Windows and Linux. The importer chooses the binary that matches the editor’s platform and architecture. Rebuild with native/build.sh to get the new names.
  • The bundled compiler is now run directly instead of through cmd.exe or /bin/sh etc., and reads its job from a file passed with --input. This fixes the compiler failing on Windows, where cmd seemed to misread Godot’s forward-slash paths.
  • The plural annd ordinal markup markers now use the full set of Unicode CLDR plural rules, covering over a hundred languages, instead of a hand-picked list of about twenty. Languages such as Welsh, Irish, Scottish Gaelic, Breton, Maltese, Slovenian, Lithuanian, Latvian, Icelandic, and most South and Southeast Asian languages now get correct plural forms in [plural value="%" ...] and [ordinal value="%" ...] text, rather than falling back to a generic “one for 1, other for everything else” guess. The rules are in their own file, cldr_plural_rules.gd, so they can be extended without touching the markup replacement code itself. Woo. This took a while.
  • Command text is now split into arguments the same way Yarn Spinner for Unity does: only double quotes delimit a quoted argument, and inside one only \\ and \" are treated as escapes. Single quotes and stray backslashes are no longer special. This is breaking if a command relied on single quotes to group an argument (<<say 'hello there'>> used to produce one argument; it now produces two, 'hello and there') or on a backslash escaping something other than a quote or another backslash. Wrap arguments that ned spaces in double quotes instead, and expect a literal backslash wherever your command text has one.
  • bool() and number() now stop the dialogue with a clear error when given input they can’t convert, instead of logging a warning and quietly substituting false or 0. bool() also no longer accepts "1" as a stand-in for "true" — only "true" and "false" (case-insensitive) convert from a string. format() now takes exactly one substitution argument, format(formatString, argument), matching every other Yarn Spinner runtime; every {0} in the format string is replaced, and any other numbered placeholder is an error rather than being left in the text or silently stripped.
  • Numbers are now stored and displayed as 32-bit floats, matching the Yarn Spinner value model, and print using the same shortest round-trip formatting as the other runtimes (0.1 stays 0.1, 10000000 stays plain, 1000000000 becomes 1E+09) instead of a fixed six-decimal-place format that could show trailing precision Yarn never had. I felt this was important for parity with the TypeScript runner that is used for people’s testing.
  • Malformed markup now logs a warning describing what went wrong and where, instead of failing silently and falling back to the raw text.
  • Breaking: YarnLine.text now includes the character name (so the same as LocalizedLine.Text in Yarn Spinner for Unity). Use text_without_character_name (or get_plain_text()) where you want the line without the name. The built-in Line Presenter has a new show_character_name_in_line option for when there’s no separate character name label.
  • Breaking: allow_option_fallthrough on the Dialogue Runner now defaults to true (also matching Unity). An option group with no available options now continues past the options instead of stopping the dialogue.
  • Breaking: the in-memory Variable Storage now rejects variable names that don’t start with $, as Unity does. Set validate_variable_names to false to turn this off.
  • Breaking: action markup handlers now receive the line’s YarnMarkupParseResult in on_prepare_for_line and on_line_display_begin, not the YarnLine. The wave and colour pulse example handlers have been removed.
  • Breaking: command parameters are now converted the same way Unity converts them. An int parameter no longer accepts 1.5, a bool parameter no longer accepts yes, on or 1, and a Vector2, Vector3 or Color that can’t be parsed is now an error instead of zero. A parameter typed as a node class that names a node which doesn’t exist now receives null with a warning, rather than failing the command. command_unhandled is now only emitted for commands that aren’t registered at all; other command failures are logged as errors.
  • Breaking: <<wait>> now requires a duration, as in Unity. It used to default to one second.
  • Breaking: the line advancer’s defaults now match Unity: the hurry up input is ui_accept/Space and the next line input is ui_cancel/Escape. The Line Presenter’s old hurry_action property has been removed; use a line advancer or YarnLinePresenterButtonHandler.
  • Breaking: YarnLineProvider is now a Resource, and can be set on the Dialogue Runner in the Inspector along with its text, asset and fallback locales.
  • Functions registered with add_function now take their argument count and types from the method’s signature, and reject return values that aren’t a Yarn type. Static _yarn_function_ methods on class_name scripts are registered automatically; non-static ones are only picked up from autoloads.
  • Booleans now show as True and False when substituted into a line, matching Unity.
  • The virtual machine’s instruction and call depth limits are now off by default, as Unity has no such limits.
  • Requesting the next line now also hurries up the current one, so a Presenter only needs to watch for one of them.
  • Variable change listeners fire every time a variable is set, and initial values are read from the program rather than copied into storage, as in Unity.
  • Added YarnTypewriter, with instant, letter and word typewriters, and a custom typewriter option on the Line Presenter.
  • Added save_state_to_persistent_storage() and load_state_from_persistent_storage() to the Dialogue Runner.
  • format() now follows .NET’s format rules exactly, including padding, precision and custom numeric formats.
  • Added get_line_ids_for_nodes() to YarnProjectResource and get_line_ids_for_node() to YarnProgram, the equivalent of YarnProject.GetLineIDsForNodes() in Unity, for preloading or debugging the lines in a set of nodes.
  • Line and option text is now normalised to Unicode NFC (composed) form before its markup is parsed, the same as Yarn Spinner for Unity. A line written with a combining accent, like e followed by U+0301, now produces the same text and the same attribute positions as one written with a precomposed é.
  • When a Yarn Project’s Ysls Scan Path is empty, the folder searched for Commands and Functions now starts at the project’s own folder and only moves up while it finds no scripts. It never moves into a folder that holds another Yarn Project, so projects that sit side by side no longer pick up each other’s Commands in their .ysls.json.
  • With an empty Ysls Scan Path, the .ysls.json now also lists the Commands and Functions from every scene that uses the Yarn Project, wherever their scripts live. The scenes are found by reading them as text, and the search follows the scripts attached to their nodes, instanced and inherited scenes, the scripts and scenes those scripts preload or name by class, and your autoloads. Scenes that only use a different Yarn Project are skipped. A project whose scenes use shared scripts, like a character script in another folder, now gets those scripts’ Commands.
  • The Ysls Scan Path import option is now empty by default, so new Yarn Projects get the search above instead of scanning the whole project. res://, the old default, is stored in the import settings of existing projects, so it’s now treated the same as empty. Any other folder is still used as it is.
  • The .ysls.json rewritten when you save a script, and the Commands palette in the Yarn Spinner tab, now use each project’s Ysls Scan Path import option, and the rewrite is skipped for projects with Generate Ysls turned off. The Dialogue Runner’s Regenerate YSLS button uses the same search when its own Ysls Scan Path is empty.

Fixed

  • Calling stop_dialogue() from a node_started handler no longer fails. The runner now stops cleanly, whether the node was jumped to or was the one dialogue started on.
  • Negative numbers now pick their plural form from the size of the number, ignoring the sign. [plural value=-1 one="% apple" other="% apples"] now reads “-1 apple” rather than “-1 apples”. Only the operands changed.
  • Fixed bugs in CLDR plural rules.
  • [plural] and [ordinal] markup now follows the active locale. The line’s locale was being set after its text had already been parsed, so every line used English plural and ordinal rules regardless of what set_locale() was called with.
  • Option text now processes select, plural, and ordinal markup, the same as lines do. These markers in an option used to be stripped to nothing by the display path.
  • Modulo by zero now stops the dialogue with a clear error instead of returning 0. Note both operands round to the nearest integer first (halves round to even), so a divisor between -0.5 and 0.5 also counts as zero.
  • Shadow lines (#shadow:) now display their source line’s text, and play its voice over audio, instead of showing a raw line ID. The line provider resolves the shadow source before any lookup, the same way Yarn Spinner for Unity does.
  • A line with no text in the current locale now logs a warning naming the line and locale. It still displays the line ID as before, but no longer does so silently.
  • The continue button installed by the action markup handler now advances the line. It was calling a method that doesn’t exist on the dialogue runner, behind a guard that hid the mistake, so pressing it did nothing.
  • Preloaded assets are now actually used. Background loads started by preload_assets() were never collected, so every line fell back to a synchronous load anyway, and a line ID that had ever been preloaded could never be requested again. Finished loads are now collected whenever an asset is fetched.
  • The bundled native compiler is invoked once per compile instead of twice. The first invocation was a leftover that ran the binary with no input and could stall the editor waiting on it.
  • Compiling with the native compiler now works when the project or the Godot cache directory has spaces or shell metacharacters in its path, and two editor instances compiling at the same time no longer overwrite each other’s temporary files.
  • Dividing zero by zero in a Yarn expression now produces NaN, matching Yarn Spinner for Unity. A hand-rolled guard was returning infinity.
  • A broken script now stops the dialogue with a clear error instead of limping on with wrong values. Calling an unknown function, or reading a variable that doesn’t exist anywhere (storage, smart variables, or the program’s initial values), used to log and continue with null on the VM stack, which sent the story down branches nobody wrote. All Yarn Spinner runtimes now fail identically here.
  • A smart variable whose expression leaves the wrong number of values on the stack is now reported as an error instead of silently returning whichever value happened to be on top.
  • round() and round_places() now round half to even (“banker’s rounding”, so 2.5 rounds to 2 and 3.5 to 4), matching every other Yarn Spinner runtime. Godot’s own roundf() rounds half away from zero. Again, important while folks are testing/using the TypeScript runner as part of their toolchain (e.g. VSCode).
  • A truncated or corrupt compiled program now fails to load with an error instead of hanging the editor.
  • Instructions the runtime doesn’t recognise now stop the dialogue with an error instead of shifting every jump in the node.
  • When a node has the same header more than once, the first one now wins, and get_all_headers() returns every one of them.
  • Dialogue completion now happens in the same order as Unity: nodes report completion when the dialogue is stopped, and dialogue_completed fires before the runner is marked as stopped.
  • Starting dialogue at a node that doesn’t exist now logs an error and doesn’t start, instead of emitting dialogue_started first.
  • Saliency strategies now pick between tied candidates the same way Unity does, and store view counts as floats like every other Yarn number.
  • Escaped square brackets in a line (\[ and \]) now display as brackets instead of being read as BBCode tags, and overlapping markup such as [b]a [i]b[/b] c[/i] now renders correctly.
  • Pauses in lines now respect hurry up, and wait for the game to be unpaused.
  • Command text is now split on every Unicode whitespace character, not just spaces and tabs.
  • Disabled Presenters are now skipped, as in Unity.
  • Calling start_dialogue() from a dialogue_completed handler now starts the new dialogue properly, instead of leaving the runner stuck.
  • Changing yarn_project while dialogue is running is now refused with an error, the same as set_project().
  • Checking a node group for content (has_any_content(), or get_saliency_options_for_node_group()) now stops with an error if one of its conditions can’t be evaluated, as Unity does, instead of quietly treating that condition as failed.
  • Command discovery now only loads scripts that actually declare a _yarn_command_ or _yarn_function_ method, instead of any script that mentions one.
  • Exported games no longer search every class_name script for commands and functions when dialogue starts. Exported scripts don’t include their source, so that search couldn’t rule anything out and ended up loading every script. The plugin now records which scripts declare commands and functions when you export, much like Yarn Spinner for Unity generates its command registrations at build time, and the exported game loads only those.
  • Lines, options, plural rules and variable name hashing can now be used from more than one thread at once. Every line and option used to share a single markup parser, so reading line text from worker threads (for example, preparing lines ahead of time) could produce the wrong text or crash the game.
  • Fixed several YarnEffects helpers:
    • The typewriters, including typewriter_with_line(), now take an optional cancellation token and finish immediately when hurried.
    • typewriter_words() now reveals text a whole word at a time, instead of by overall proportion.
    • typewriter_with_line() now returns a signal that fires when the line has finished, using the same typewriter as the Line Presenter, so pauses respect hurry-up and game pause.
    • Instant typewriters return a signal that can still be awaited.
    • shake() no longer divides by zero for very short shakes.
  • Registering several replacement marker processors on a Line Presenter no longer logs “already registered” errors for the processors registered before it.
  • A Dialogue Runner that leaves the scene before its first command search runs no longer logs a script error.
  • When two different scripts declare the same command or function name, the second one is now reported as an error instead of being silently ignored, as Unity does.
  • Commands on nodes added to the scene after dialogue started are now found. If a command isn’t registered and the scene has changed since it was last searched, the runner searches it again before giving up.
  • The Voice-Over Presenter now asks for a shadow line’s audio using its source line’s ID, so shadow lines get the source line’s clip even when a custom line provider doesn’t resolve shadow lines itself.
  • set_content_saliency_strategy() can now be called before the dialogue runner is ready. It used to crash; the strategy is now kept and applied when the runner sets up, and re-applied each time dialogue starts while Saliency Strategy is Custom.
  • Command bindings set up in a scene’s Inspector (the Bindings list on a YarnBindingLoader) are now found when writing the .ysls.json and the compiler’s Function declarations. Scenes are read as text, not instantiated.
  • .ysls.json entries for Command bindings now have the target method’s real parameters, return type and async flag, instead of no parameters.
  • Writing the .ysls.json no longer loads every .tres and .res file in the scan folder. Only files that hold Command bindings are read, so materials, textures and models aren’t loaded or imported along the way.

Documentation

  • The custom Presenter example in the quick start now uses the new Presenter contract (run_line(line, token) -> void, await inside). The old example still showed the pre-Alpha 7 return-a-Variant style.
  • Corrected signal and property names in the README and quick start: command_unhandled (not unhandled_command) and show_selected_option_as_line (not run_selected_option_as_line).
  • The docs now lead with the bundled native compiler, which needs no setup. Installing ysc via the .NET SDK is documented as the fallback for platforms without a bundled binary. This will improve in the next alpha, so probably worth still keeping ysc around for now.
0.0.0-alpha82026-07-28

Lots of small quality of life changes. Scene-based options, some tweaks to boolean flag parameters (to match Yarn Spinner for Unity), and a word wrap fix in the Line Presenter. If you show options with the built-in Presenter, note that option text no longer includes the character name prefix.

Options are scene-based

The Options Presenter now instantiates a scene per option, similar to the way Yarn Spinner for Unity instantiates its Option Item prefab. The default is the new ui/option_item.tscn (a YarnOptionItem wrapping a focus-styled button); edit that scene or point option_button_scene at your own to restyle options. Plain BaseButton scenes still work. When every option in a group is unavailable, the Presenter now declines immediately instead of waiting on an empty screen. Option text no longer includes the character name prefix (an option written as -> Tom: Who are you? displays as “Who are you?”), the same as Yarn Spinner forUnity’s option items; YarnOption gained character_name and text_without_character_name if you need either piece.

The voice over samples’ options are styled similarly to the Yarn Spinner for Unity voice over sample’s Option Item (60pt flat text, grey until selected, bottom-centre panel).

Word wrap is precalculated

The Line Presenter now lays out the whole line before the typewriter reveals any of it, so words no longer jump to the next line partway through being typed. A word that won’t fit on the current line starts on the next one from its first character, which is what Yarn Spinner for Unity’s TMP does with maxVisibleCharacters. If you still see problems, please report them.

Boolean parameters accept their name as a flag

A command parameter of type bool can now be set to true by passing the parameter’s own name as a bareword, matching Yarn Spinner for Unity’s convention. So for a handler like:

func _yarn_command_play_animation(layer: String, state: String, wait: bool = false) -> void: ...

both of these now work, and mean the same thing:

<<play_animation Tom Gesture LookAround wait>>
<<play_animation Tom Gesture LookAround true>>

true/1/yes/on (and false/0/no/off) keep working as before; this only adds the flag form.

If you only write command handlers without a trailing bool flag, or you already pass true/false explicitly, nothing should really change.

0.0.0-alpha72026-07-22

This alpha reworks how Presenters and the Dialogue Runner talk to each other. If you implemented Presenters or commands against an earlier alpha, read the Breaking changes, please. Most migrations should be signature change and the deletion of boilerplate. Hopefully.

Breaking: one Presenter contract

run_line no longer returns a Variant. There is now exactly one way to write a Presenter: return when you’re done, and await inside for anything that takes time. (In the previous alpha you couldn’t await inside run_line at all. The whole pattern we were previously using is is gone.)

So, before, you did something like this:

func run_line(line: YarnLine, token: YarnCancellationToken = null) -> Variant:
    label.text = line.text
    return _my_done_signal        # or: return null

And now, you do something like this:

func run_line(line: YarnLine, token: YarnCancellationToken = null) -> void:
    label.text = line.text
    await token.wait_for_next_content()   # hold the line open until dismissed
    label.text = ""

To migrate to the new API:

  • Sync Presenters (return null): change the return type to -> void and delete the return nulls. Done. Amazing.
  • Signal Presenters (return my_signal): change to -> void and replace return my_signal with await my_signal, or better, fold your detached helper’s logic straight into run_line, which is usually simpler now that awaiting inside it works. If your dialogue can be stopped mid-line, also emit that signal from on_dialogue_completed so the parked run_line is released.

run_options keeps its previous approach (-> int: the selected index, or -1 if you don’t handle options) and may await the player’s choice internally, as before.

The runner starts every Presenter in the same frame and advances only when all of them have returned. The cancellation token is the finish-up request: when it reports next-content, you should finish promptly.. the runner waits for you, and logs a warning naming your Presenter after 5 seconds if you don’t. Don’t be bad.

Breaking: `dispatch_command` is a coroutine

YarnLibrary.dispatch_command() must now be awaited. Coroutine command handlers run to completion inside it. If you called it directly, add await; if you only write command handlers, nothing changes.

To be clear about who this affects: dispatch is the internal step where a <<command>> in a Yarn script gets routed to your registered handler. The Dialogue Runner is normally the only thing that calls it, and it already awaits. So if your commands are ordinary _yarn_command_* methods or add_command() registrations, you have nothing to migrate as your handlers are called exactly as before, and a handler that awaits internally (like the built-in <<wait>>) now correctly holds the dialogue until it finishes. Returning a Signal from a handler for async work also still works.

The only code that needs an await added is game code that was invoking dispatch_command() on the library by hand, for example, a debug console that runs Yarn commands outside of dialogue.

Commands now receive typed parameters

Declare real types on command handlers, and arguments are converted before the call. This includes Node-derived parameters, resolved by node name:

func _yarn_command_give(item: String, count: int, loud: bool) -> void: ...
# <<give sword 3 true>> → "sword", 3, true

func _yarn_command_focus(target: Node3D) -> void: ...
# <<focus Camera>> → the actual node

Supported: String, int, float, bool, Vector2, Vector3, Color, Node classes. A value that can’t convert will spit out a command error naming the argument. Handlers registered as lambdas still receive raw strings (GDScript lambdas expose no parameter metadata, so use a named method).

Note: in earlier alphas this conversion existed but never quite worked, and coroutine command handlers invoked via callv silently failed, so, e.g., <<wait 2>> did not actually wait in some configurations. It does now; if your timing depended on waits being skipped, re-check pacing, please.

Behaviour changes

  • Presenters no longer have request_next() or request_hurry_up() callbacks. The cancellation token is the only wind-down channel: watch it or await it in run_line. The runner’s request_next_content() and request_hurry_up() still exist for game code and now just fire the token. A next-content request dismisses a line even mid-reveal, like Yarn Spinner for Unity. Two-stage “reveal, then advance” lives in YarnLineAdvancer, which was previously broken and now works, and in the Line Presenter’s own direct input handling, which is unchanged.
  • YarnVoiceOverPresenter: end_line_when_voice_complete now defaults to true (again, same as we do in Unity) and now works; a missing audio clip logs an error and skips the line instead of stalling; hurry-up no longer interrupts audio (only next-content does); audio is looked up through the runner’s locale-aware pipeline first, so set_locale() switches voice as well as text.
  • request_line_cancellation now routes through request_next_content(), so a Presenter asking to end the line actually dismisses every Presenter.
  • All dialogue timing (typewriter, <<wait>>, option timeout, auto-advance, fades) now respects the pause model. Paused nodes stop their clocks per standard process_mode rules…
  • Keyboard input for Presenters and the advancer moved to _unhandled_input, so UI controls get first look at focus and confirm presses. Click-to-continue stays in _input (a click over the dialogue panel or a fullscreen overlay would otherwise be eaten as GUI input), gated to “line showing, no options up”, with a new click_anywhere_to_continue export to turn it off. Use runner.are_options_active() instead of poking around in private state.

TranslationServer for Localisation

The parallel Yarn localisation layer is gone; the single system is Godot’s own. We don’t need a parallel one here, like we do in Yarn Spinner for Unity, as everyone should really be using the Godot one. Text goes through TranslationServer (keys are the line id prefixed with YARN_ by default, and .translation resources registered in Project Settings). Voice audio goes through translation remaps (Project Settings > Localization > Remaps): so just point the runner at your base-language folder with set_audio_base_path() and Godot substitutes the right file per locale on load.

  • set_audio_path_template("...{locale}/") is replaced by set_audio_base_path("res://.../audio/en/") — the {locale} folder templating no longer exists.
  • Live locale switching works. The lookup bypasses Godot’s resource cache (which pins a remapped resource to its first-loaded locale) and keeps its own per-locale cache

Voice Presenter slimmed

YarnVoiceOverPresenter no longer keeps its own audio cache: max_cache_size, set_audio_for_line() and clear_cache() are gone, along with its prepare_for_lines pre-loading. The localisation layer caches runner-provided audio, and Godot’s own resource cache covers the fallback path. Inspector tooltips across the addon also no longer cite what Yarn Spinner for Unity does; they just say what the property does.

Presenters must be listed

Child auto-discovery is gone. The runner uses exactly what is in its Presenters array, plus anything registered at runtime with add_presenter() (which is how YarnDialogueView registers its two). A runner with an empty array and Presenter children logs a warning naming the first one, so a scene relying on the old discovery tells you what to fix.

YarnDialogueView

  • Visuals now come from ui/dialogue_view_ui.tscn via the new ui_scene export, swap in your own scene to reskin it or change its layout.
  • start_node defaults to empty, meaning “use the runner’s Start Node”; set it only to override. auto_start is ignored when the runner’s own Auto Start is on. People got confused by this, sorry.

New API

  • YarnPromise — a completion object (settle() / await wait()); settlement is remembered, so late awaiters can’t lose it. It’s a bit like a Promise from other languages. Best we can do, anyway.
  • YarnCancellationToken.wait_for_next_content() — await for coroutine Presenters.
  • YarnAsync.wait(node, seconds) — pause-respecting timer.
  • runner.are_options_active(), runner.get_presenters().
  • line_dismissed signal on YarnLinePresenter.
  • Presenter children added to the runner after startup are now discovered.

Fixed

  • Lost-completion hangs: the runner joins Presenters through promises, so completion order can never strand the dialogue.
  • show_selected_option_as_line soft-locked dialogue after the first choice; synchronous option selection could skip the echoed line.
  • option_timeout with fallthrough disabled stopped dialogue with an error instead of falling through.
  • A force-advanced async command could end the wrong line later (epoch guards now cover commands as well as lines).
  • The built-in Options Presenter ignored its token: buttons survived timeouts and rival selections; it now winds down and returns -1.
  • A Presenter freed mid-line hung dialogue permanently; it now counts as finished.
  • External select_option() calls now route through the active options round instead of desyncing it.
  • Voice-over fallback paths strip the line: prefix when deriving filenames, matching the localisation resolver.
Earlier alphas

Earlier alpha releases aren’t listed here.