This is the compiler for Yarn Spinner. If you want to use Yarn Spinner in a Unity game, please see the releases page for Yarn Spinner for Unity!

Yarn Spinner is made possible by your generous patronage. Please consider supporting Yarn Spinner's development by becoming a patron!

Added

• Standard library functions (e.g. random, round_places, dice) have been moved from Yarn Spinner for Unity to the core Yarn Spinner library.
• Added a format function to the standard library.
  • This method works identically to the C# string.Format, but currently only accepts one parameter.
  • format("{0}", 123) will return the string "123".
  • format("${0:F2}", 0.451) will return the string "$0.45".
  • For more information on string formatting, see the .NET documentation on numeric formatting strings.

Changed

• Updated the schema for .ysls.json files:
  • Commands may no longer specify a return type.
  • Functions must now specify a return type.
  • Changed the definition of 'types' to be an enum of "string", "number", "bool", or "any".
    • Enums in JSON schema are type sensitive, so a warning will be issued for types that have capital letters. To fix these warnings, change your type names in your .ysls.json file to be lowercase. (These warnings have no impact on your Yarn script editing experience or runtime behaviour.)
• Empty nodes will no longer be included in the compiled output.
  • A warning diagnostic will be generated for each empty node.
• Fixed a bug where self-referencing inferred value set statements (e.g. <<set $a = $a + 1>>, where $a is not explicitly declared) would crash the compiler.
• The language server no longer truncates XML documentation comments when it reaches a nested XML node.
• Updated dependency versions:
  • Google.Protobuf: Moved from 3.15.0 to 3.25.2.
  • System.Text.Json: Moved from 7.0.2 to 8.0.1.
  • Microsoft.Extensions.FileSystemGlobbing: Moved from 7.0.0 to 8.0.0

This is the compiler for Yarn Spinner. If you want to use Yarn Spinner in a Unity game, please see the releases page for Yarn Spinner for Unity!

Yarn Spinner is made possible by your generous patronage. Please consider supporting Yarn Spinner's development by becoming a patron!

Added

• Added a new method, Utility.TagLines, which will eventually replace the now deprecated AddTagsToLines method.
• Added a new method, Program.LineIDsForNode, which allows you to get the list of all line IDs in a node.
• Added a new function, format_invariant, which formats a number as a string using the invariant culture (rather than the end-user's current culture.)
  • Commands expect all numbers to be formatted using the invariant (i.e. US English) style, with . as a decimal point.
  • If a number is inserted into a command, it will by default be formatted for the user's current culture. If that culture formats numbers differently, it can cause problems.
  • format_invariant will always format a value in the invariant culture, making it useful for situations where a number needs to be embedded in a command (which expects all numbers to be ), and not shown to the user.
  • You can use format_invariant like this:

    <<set $gold_per_turn = 4.51>>
    
    // de-DE: 'give_gold 4,51'
    // en-US: 'give_gold 4.51'
    <<give_gold {$gold_per_turn}>>
    
    // de-DE: 'give_gold 4.51'
    // en-US: 'give_gold 4.51'
    <<give_gold {format_invariant($gold_per_turn)}>>
    

Changed

Language Server

• Fixed a bug in the language server that would cause it to crash when opening a workspace with no root (for example, creating a new window in Visual Studio Code and then creating a Yarn file, without ever saving anything to disk.)
• Fixed an issue where workspaces where no Yarn Projects exist on disk would fail to attach Yarn files to the workspace's implicit Yarn Project.
• Improved the code-completion behaviour to provide better filtering when offering command completions, in both jump commands and custom commands.
• Fixed character names being incorrectly recognised when the colon is not part of the line
• Fixed a bug where a missing 'Parameters' field in a .ysls.json file would cause the definitions file to not parse correctly.
• If a workspace that has no .yarnproject files in it is opened, the language server will now look for a .ysls.json file containing command and function definitions. A warning will be reported if more than one file is found.
• The language server now shows a warning if the workspace is opened without a folder.

Compiler

• Fixed a crash bug when declaration statements were used without a value (<<declare $var>>).
• Fixed a bug where unusual interpolated commands (such as <<{0}{""}>>) would resolve to unexpected final values (<<>>).

Utilities

• Flagged the Utility.AddTagsToLines method as obsolete.
• Fixed a bug where escaped characters weren't being correctly added back into the file after adding line tags.

Removed

This is the compiler for Yarn Spinner. If you want to use Yarn Spinner in a Unity game, please see the releases page for Yarn Spinner for Unity!

Yarn Spinner is made possible by your generous patronage. Please consider supporting Yarn Spinner's development by becoming a patron!

Yarn Spinner 2.3

Get excited! Yarn Spinner 2.3 is here! Here’s an outline of what’s new since the previous release, 2.2.

Yarn Projects

• Added support for JSON-based Yarn Project files.
  • Yarn Project files contain information that the Yarn Spinner compiler can use to compile multiple Yarn scripts at the same time. Yarn Projects are designed to be used by game engines to identify how Yarn content should be imported into the game.
  • Yarn Project files have the following syntax:

  {
    "projectFileVersion": 2,
    "sourceFiles": ["**/*.yarn"],
    "excludeFiles": ["DontInclude.yarn"],
    "baseLanguage": "en",
    "localisation": {
        "en": {
            "assets": "./voiceover/en/"
        },
        "de": {
            "strings": "./de.csv",
            "assets": "../voiceover/de/"
        }
    },
    "definitions": "Functions.ysls.json",
    "compilerOptions": {}
  }
  

  • projectFileVersion is used to identify which version of the project file format is being used, and is currently required to be the number 2.
  • sourceFiles is an array of search paths used to find the Yarn files that should be compiled as part of this project. Glob patterns, including globstar, are supported.
  • excludeFiles (optional) is an array of search paths used to find Yarn files that should not be compiled. The same kinds of patterns as sourceFiles are supported.
  • baseLanguage is a IETF BCP 47 language tag indicating the language that the source scripts are written in (for example, en for English.)
  • localisation (optional) is a dictionary containing zero or more objects that describe where locale-specific resources can be found, where the key is a language tag and the value is an object of the following layout:
    • strings: The path to a file containing the localised line text for the project. (This is typically, but not required to be, a CSV file.)
    • assets: The path to a directory containing the localised assets (for example, voiceover audio) for the project.
  • definitions (optional) is the path to a JSON file containing command and function definitions used by the project.
  • compilerOptions (optional) is an object containing additional settings used by the Yarn Spinner compiler.

Yarn script changes

• The Yarn Spinner compiler’s indentation tracking has been rewritten to be more consistent in how it works.
  • 🚨 Breaking Change: if statements must now all be at the same level of indentation as they’re corresponding else, elseif, and endif statements.
    • This was already strongly encouraged for readability, but is now a requirement.
    • If an if statement is at a different indentation level to its corresponding statements, a compiler error will now be generated.
    • The lines and other content inside an if statement can be indented as much as you like, as long as it’s not less indented than the initial if statement.
      • For example, the following code will work:

        / With indentation
        <if $something>>
        A line!
        <else>>
        A different line!
        <endif>>
        
        / Without indentation
        <if $something>>
         line!
        <else>>
         different line!
        <endif>>			
        

      • The following code will not work:

        / With indentation
        <if $something>>
         line!
        <else>>
         different line!
        <endif>>			
        

  • 🚨Breaking Change: Empty lines between options now split up different option groups.
    • Previously, the following code would appear as a single option group (with the options ‘A’, ‘B’, ‘C’, ‘D’):

      -> A
      -> B
      
      -> C
      -> D		
      

    • In Yarn Spinner 2.3 and above, this will appear as two option groups: one containing the options ‘A’, ‘B’, and another containing ‘C’, ‘D’.
      • This change was made in response to user reports that the previous behaviour didn’t behave the way they expected.

Changed things

• Node title verification now occurs at declaration time instead of code generation. This means invalid titles will be caught and presented as a problem earlier on, to aid in debugging issues.
• The following event handlers on the Dialogue class, which were previously required to be set, are now optional and may be set to null:
  • LineHandler
  • CommandHandler
  • NodeStartHandler
  • NodeCompleteHandler
  • DialogueCompleteHandler
  • Note that OptionsHandler remains not optional, and is required to be set.
• VM now nullifies its state when stopped. Previously, the VM's state would persist after the Stop method is called.

This is the compiler for Yarn Spinner. If you want to use Yarn Spinner in a Unity game, please see the releases page for Yarn Spinner for Unity!

Yarn Spinner is made possible by your generous patronage. Please consider supporting Yarn Spinner's development by becoming a patron!

Added

• Yarn Programs now store all headers for their nodes.
  • Prior to this change, only the tags header was stored.

Changed

• The Yarn Spinner compiler's indentation tracking has been rewritten to be more consistent in how it works.

  • 🚨 Breaking Change: if statements must now all be at the same level of indentation as their corresponding else, elseif, and endif statements.

    • This was already strongly encouraged for readability, but is now a requirement.

    • If an if statement is at a different indentation level to its corresponding statements, a compiler error will now be generated.

    • The lines and other content inside an if statement can be indented as much as you like, as long as it's not less indented than the initial if statement.

      For example, the following code will work:

      // With indentation
      <<if $something>>
          A line!
      <<else>>
          A different line!
      <<endif>>
      
      // Without indentation
      <<if $something>>
      A line!
      <<else>>
      A different line!
      <<endif>>
      

      The following code will not work:

      // With indentation
      <<if $something>>
        A line!
        <<else>>
      A different line!
      <<endif>>
      

  • 🚨 Breaking Change: Empty lines between options now split up different option groups.

    • Previously, the following code would appear as a single option group (with the options 'A', 'B', 'C', 'D'):

      -> A
      -> B
      
      -> C
      -> D
      

      In Yarn Spinner 2.3 and above, this will appear as two option groups: one containing the options 'A', 'B', and another containing 'C', 'D'.

      This change was made in response to user reports that the previous behaviour didn't behave the way they expected.

• Node title verification now occurs at declaration time instead of code generation. This means invalid titles will be caught and presented as a problem earlier on, to aid in debugging issues.

• Code completion in the Language Server has been completely rewritten. It is now much less flexible, but way more performant. For most situations, the changes will not be noticeable.

• Fixed a crash in the Language Server when encountering declaration statements without a variable.

This is the compiler for Yarn Spinner. If you want to use Yarn Spinner in a Unity game, please see the releases page for Yarn Spinner for Unity!

Yarn Spinner is made possible by your generous patronage. Please consider supporting Yarn Spinner's development by becoming a patron!

Changed

• Number pluralisation rules have been updated. The rules have now use CLDR version 42.0 (previously, 36.1)
• Merged LanguageServer projects into the core YarnSpinner repository.
• NodeInfo.PreviewText no longer removes comments from the preview.
• Migrated tests from xUnit's Assert tests to Fluent Assertions.
• Fixed an issue where pluralisation markup (i.e. the plural and ordinal tags) would not work correctly with country-specific locales (for example "en-AU").

This is the compiler for Yarn Spinner. If you want to use Yarn Spinner in a Unity game, please see the releases page for Yarn Spinner for Unity!

Yarn Spinner is made possible by your generous patronage. Please consider supporting Yarn Spinner's development by becoming a patron!

Changed

• The compiler will now produce more useful error messages when two or more nodes in a compilation share the same name.

This is the compiler for Yarn Spinner. If you want to use Yarn Spinner in a Unity game, please see the releases page for Yarn Spinner for Unity!

Yarn Spinner is made possible by your generous patronage. Please consider supporting Yarn Spinner's development by becoming a patron!

This is a small release to enable core features needed by other components.

Added

• a new utility DetermineNodeConnections that analyses Yarn files and returns a directed graph of node connections.

This is the compiler for Yarn Spinner. If you want to use Yarn Spinner in a Unity game, please see the releases page for Yarn Spinner for Unity!

Yarn Spinner is made possible by your generous patronage. Please consider supporting Yarn Spinner's development by becoming a patron!

Changed

• Handling of escape characters is now more consistent in how it approaches the situation of when the first character is the escape character \.
• Tagging lines that contain multiwidth characters should no longer create weird invalid split characters in the dialogue.

This is the compiler for Yarn Spinner. If you want to use Yarn Spinner in a Unity game, please see the releases page for Yarn Spinner for Unity!

Yarn Spinner is made possible by your generous patronage. Please consider supporting Yarn Spinner's development by becoming a patron!

Added

• Added a means to detect and return runs of lines through basic block analysis to the Utils. This is called via the Yarn.Compiler.Utility.ExtractStringBlocks function.

Changed

• Markup attributes may now begin with a digit, letter or underscore. Previously, they were required to begin with a letter or an underscore. This allows the select marker to work with numbers: [select value=1 1=one 2=two 3=three /]

This is the compiler for Yarn Spinner. If you want to use Yarn Spinner in a Unity game, please see the releases page for Yarn Spinner for Unity!

Yarn Spinner is made possible by your generous patronage. Please consider supporting Yarn Spinner's development by becoming a patron!

Added

• Added DeclarationBuilder and FunctionTypeBuilder classes. These classes allow external libraries to construct new Declaration and FunctionType objects, without having to have access to the internal setters.
• CompilationResult.DebugInfo now provides per-instruction positional debug information.
  • This allows users of the Compiler class to access positional information for each instruction, which is an important first step for source-level debugging.
• Made Diagnostic and Declaration serializable, for easier communication with language servers and other utilities.
• The compiler now does a last-line-before-options tagging pass.
  • This will add a #lastline tag onto any dialogue line that immediately precedes a block of options.
  • This is intended to used by other parts of the game to modify dialogue view behaviours.

Changed

• Declaration and Diagnostic now provide position information via a Range object, which specifies the start and end position of the relevant parts of the document.
• Fixed an issue where attempting to access the value of a variable with insufficient context to figure out its type would crash the compiler. (This could happen when you used a variable in a line, like Variable: {$myVar} with no other uses of $myVar.)
• Fixed an issue where an option condition with no expression (for example: -> Option one <<if>>) would crash the compiler.
• The compiler will no longer attempt to generate code if the Yarn script contains errors. (Previously, it was generating code, and then discarding it, but this allows for potential errors and crashes if code-generation is attempted on an invalid parse tree.)
• Typechecker now does partial backwards type inference, allowing for functions and variables to inform the type of the other regardless of them being the l- or r-value in an expression.