v2.3.1

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>>
         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.

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.