v3.0.0-beta2

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

• The compiler will now warn if additional text is present on the same line before or after commands and other statements.
  • For example, the following code will emit a warning, because the last > character is likely a typo: <<wait 5>>>
• Added a new method, Dialogue.GetHeaders, which returns the collection of headers present on a node.
• Added a new method, Dialogue.GetHeaderValue, which returns the value of the specified header on a node.
• Language Server: Nodes that are part of a node group now show their condition complexity as a code lens.
• Added a new method, Dialogue.HasSalientContent(nodegroup), which returns a bool if there is any salient content for the requested nodegroup.
• Added min(a,b) and max(a,b) to the standard library. We genuinely thought we'd add this earlier.
• Added unwrapped TryGetProperty calls to markup, allowing direct access to the type if you know it ahead of time.

Changed

• Commands are now better at checking to see if the first word is a keyword (e.g. return) or a word that just begins with a keyword (returnToMenu).
• Fixed an error where the compiler would crash if an error expression resulted in the implicit declaration of a variable (for example, <<set $x = >>).
• Fixed an error where whitespace consumption of markup could extend beyond it's immediate younger text sibling.
• Renamed BestLeastRecentlyViewSalienceStrategy to be BestLeastRecentlyViewSaliencyStrategy.
• Renamed RandomBestLeastRecentlyViewSalienceStrategy to be RandomBestLeastRecentlyViewSaliencyStrategy.

Removed

• Removed GetTagsForNode. This method is replaced with GetHeaderValue(nodeName, "tags").

v2.5.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!

Changed

• random_range(min, max) now returns a random integer between min and max, inclusive. (Previously, it returned a float.)
• Added a new function, random_range_float now returns a random float between min and max, inclusive. (This is the previous behaviour of random_range.)

v3.0.0-beta1

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

Enums

Enums have been added to the Yarn language.

Enums are a type of variable that are allowed to be one of a specific set of named values. For example:

// Create a new enum called Food.
<<enum Food>>
  <<case Apple>>
  <<case Orange>>
  <<case Pear>>
<<endenum>>

// Declare a new variable with the default value Food.Apple
<<declare $favouriteFood = Food.Apple>>

// You can set $favouriteFood to the 'apple', 'orange' or 'pear'
// cases, but nothing else!
<<set $favouriteFood to Food.Orange>>

// You can use enums in if statements, like any other type of value:
<<if $favouriteFood == Food.Apple>>
  I love apples!
<<endif>>

// You can even skip the name of the enum if Yarn Spinner can 
// figure it out from context!
<<set $favouriteFood = .Orange>>

The only valid operators that can be used with enums are == (equal to) and != (not equal to).

Enums only support being compared to other values of the same type.

For example, if you created a new enum called Food, and another enum called Drink, you can't compare Food.Apple to Drink.Soda, because they're different enums.

Enum Cases

You declare an enum using the enum...endenum statement. This can be anywhere in your code.

Inside your enum statement, you put one or more case statements, which define one of the values that that enum can be. Each case statement must be unique inside the enum, but you can reuse the same case across different enums.

Raw Values

When you add an enum case, you can specify its 'raw value'. This is useful for when you want to use an enum to represent a specific set of numbers or strings. Raw values can be either strings, or numbers.

Each raw value must be unique inside the enum, but you can reuse the same raw value across different enums. If you specify the raw value of any of an enum's cases, they all must have a raw value. All raw values in an enum must be the same type.

If you don't specify any raw values for an enum, then Yarn Spinner will choose numbers for you as the raw values.

Enums and Functions

Functions can receive enums as parameters, as long as the enum's raw value type matches the parameter type. For example, if you have a function print that takes a string as a parameter, you can pass any enum to it that uses strings for its raw values; if you have a function multiplyByTwo that takes a number as a parameter, you can pass any enum to it that uses numbers for its raw values.

Smart Variables

Smart variables have been added to the Yarn language.

A smart variable is one that determines its value at run-time, rather than setting and retrieving a value from storage.

Smart variables give you a simple way to create more complex expressions, and re-use them across your project.

To create a smart variable, declare it using the declare statement and provide an expression, rather than a single value:

// $player_can_afford_pie is a boolean value that is 'true' 
// when the player has more than 10 money
<<declare $player_can_afford_pie = $player_money > 10>>

Smart variables can be accessed anywhere a regular variable would be used:

// Run some lines if the player can afford a pie
<<if $player_can_afford_pie>>
  Player: One pie, please.
  PieMaker: Certainly!
<<endif>>

'Once' statements

'Once' statements have been added to the language.

A 'once' statement ensures that some content in your dialogue is seen by the player one time only. Uses for this include ensuring that lines where a character introduces themselves don't run multiple times, or barks that should never be run more than a single time (the 'arrow in the knee' problem.)

The once keyword can be used in two different ways:

once..endonce Statements

A once..endonce statement allows you to wrap one or more lines (or other kinds of Yarn content) into a block that will only ever run once.

<<once>>
  // The guard will introduce herself to the player only once. 
  Guard: Hail, traveller! Well met.
  Guard: I am Alys, the guard!
<<endonce>>

once..endonce statements can be combined with an if expression. If the expression evaluates to false, the contents of the once..endonce block will not be run. (The block may run in the future if it's reached again and the expression evaluates to true.)

<<once if $player_is_adventurer>>
  // The guard knows the player is an adventurer, so say this line, 
  // but only ever once!
  Guard: I used to be an adventurer like you, but then I took an arrow in the knee.
<<endonce>>

The once..endonce statement can also take an else block. This block runs if the first part of the once statement didn't run.

<<once>>
  Guard: Hail, traveller! Well met.
<<else>>
  Guard: Welcome back.
<<endonce>>

once in line conditions

In Yarn Spinner, you can add conditions to the ends of lines, options and line group items to control when they can be presented to the player.

You can use the once keyword at the end of a line to make that line only run once. You can also combine this with an if expression to make it only run once, and only when the condition passes. If a line with a once or once if condition has been run before, Yarn Spinner will skip over that line.

Guard: Greetings, traveller. <<once>>
Guard: Met some bandits on the road, I see. <<once if $defeated_bandits>>
Guard: Be safe out there.

You can use the once keyword at the end of an option to make it so that line is only available for selection one time. As with lines, you can also combine this with an if expression. An option that has a once condition may be shown to the user multiple times as part of a collection of options, but after they select that option, it can't be selected again.

-> Where is the castle? <<once>>
-> I must see the king. Where is he? <<once if $needs_to_see_king>>
-> Farewell, friend. <<if $friends_with_guard>>
-> I should go. 

Note

Conditions on options control whether the option is available to be selected. Depending on how you've configured your game, this may mean that the option is not shown at all to the player, or that the option is visible but not selectable, or something else user-defined.

Finally, you can use the once keyword at the end of a line group item to make it so that it will only ever be run once. As with lines and options, you can combine it with an if expression to further control when it may appear.

// Scenario: The guard is pursuing the player.
// We'll create some simple, short lines that can run many times without 
// standing out, and some specific lines that we should only ever hear once, 
// because hearing them multiple times would make them stand out.

=> Guard: Halt!
=> Guard: Stop them!
=> Guard: You there! Halt, in the name of the king! <<once>>
=> Guard: Halt, thief! Someone stop them! <<once if $player_stole_treasure>>

Node groups and 'when' headers

Much like how line groups let you create groups of lines that the system chooses from based on the current game state, node groups let you create groups of nodes that the system chooses from.

You create a node group by creating one or more nodes that all have the same name, and have a when: header.

The when: header tells Yarn Spinner under what circumstances a particular node can run. For example:

title: SpeakToGuard
when: $guard_friendly == true
---
// The guard likes us
Guard: Halt, traveller!
Player: Why, hello there!
Guard: Ah, my friend! You may pass.
===

title: SpeakToGuard
when: $guard_friendly == false
---
// The guard doesn't like us
Guard: Halt, scum!
Guard: None shall pass this point!
===

To run this node group, you run the SpeakToGuard node. You can do this from within your Yarn scripts, by calling <<jump SpeakToGuard>>, or you can do it from within your game (telling your Dialogue Runner to run the node SpeakToGuard). Yarn Spinner will then select the most appropriate node to run, using the saliency strategy that you have configured for your game.

You can have as many when: headers in a node as you like. If you have more than one, all of their conditions must pass in order for the node to potentially run.

All nodes in a node group must have a when: header. It's a compiler error if any of them don't have one.

You can use any of the following kinds of expressions in a when: header:

• when: <boolean expression> - any expression that evaluates to the values true or false.
• when: once - The node will run precisely one time.
• when: once if <boolean expression> - The node will run precisely one time, and only when the expression evaluates to true.
• when: always - The node may always run.

Other Changes

• Standard library functions (e.g. random, round_places, dice) have been moved to the core Yarn Spinner library.
• Added a format function to the standard library, this works identical to the C# string.Format.
• Added `Buil...

v2.4.2

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

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

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.

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

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

v2.2.5

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

v2.2.4

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.

v2.2.3

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.