v2.0.0 Beta 2

This is the beta release of the compiler for Yarn Spinner. If you want to check out the v2.0 beta for Yarn Spinner for Unity, you should head to the beta release!

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

Added

• The [[Destination]] and [[Option|Destination]] syntax has been removed from the language.
  • This syntax was inherited from the original Yarn language, which itself inherited it from Twine.
  • We removed it for four reasons:
    • it conflated jumps and options, which are very different operations, with too-similar syntax;
    • the Option-destination syntax for declaring options involved the management of non-obvious state (that is, if an option statement was inside an if branch that was never executed, it was not presented, and the runtime needed to keep track of that);
    • it was not obvious that options accumulated and were only presented at the end of the node;
    • finally, shortcut options provide a cleaner way to present the same behaviour.
  • We have added a <<jump Destination>> command, which replaces the [[Destination]] jump syntax.
  • No change to the bytecode is made here; these changes only affect the compiler.
  • Instead of using [[Option|Destination]] syntax, use shortcut options instead. For example:

// Before
Kim: You want a bagel?
[[Yes, please!|GiveBagel]]
[[No, thanks!|DontWantBagel]]

// After
Kim: You want a bagel?
-> Yes, please!
  <<jump GiveBagel>>
-> No, thanks!
  <<jump DontWantBagel>>

• An automatic upgrader has been added that attempts to determine the types of variables in Yarn Spinner 1.0, and generates <<declare>> statements for variables.

  • This upgrader infers the type of a variable based on the values that are assigned to it, and the values of expressions that it participates in.
  • If the upgrader cannot determine the type of a variable, it generates a declaration of the form <<declare $variable_name as undefined>>. The word undefined is not a valid type in Yarn Spinner, which means that these declarations will cause an error in compilation (which is a signal to the developer that the script needs to be manually updated.)

• For example: given the following script:

<<set $const_string = "foo">>
<<set $const_number = 2>>
<<set $const_bool = true>>

• The upgrader will generate the following variable declarations:

    <<declare $const_string = "" as string>>
    <<declare $const_number = 0 as number>>
    <<declare $const_bool = false as bool>>

The upgrader is able to make use of type even when it appears later in the program, and is able to make inferences about type using indirect information.

// These variables are participating in expressions that include
// variables we've derived the type for earlier in this program, so they
// will be bound to that type
{$derived_expr_const_string + $const_string}
{$derived_expr_const_number + $const_number}
{$derived_expr_const_bool && $const_bool}

// These variables are participating in expressions that include
// variables that we define a type for later in this program. They will
// also be bound to that type.
{$derived_expr_const_string_late + $const_string_late}
{$derived_expr_const_number_late + $const_number_late}
{$derived_expr_const_bool_late && $const_bool_late}

<<set $const_string_late = "yes">>
<<set $const_number_late = 1>>
<<set $const_bool_late = true>>

• The upgrader will also make in-line changes to any if or elseif statements where the expression is determined to use a number rather than a bool will be rewritten so that the expression evaluates to a bool:

// Define some variables whose type is known before the expressions are
// hit
<<set $some_num_var = 1>>
<<set $some_other_num_var = 1>>

// This will be converted to a bool expression
<<if $some_num_var>>
<<elseif $some_other_num_var>>
<<endif>>

Will be rewritten to:

<<if $some_num_var != 0>>
<<elseif $some_other_num_var != 0>>
<<endif>>

Changed

• The internal structure of the LanguageUpgrader system has been updated to make it easier to add future upgrade passes.

v2.0.0 Beta 1

This is the beta release of the compiler for Yarn Spinner. If you want to check out the v2.0 beta for Yarn Spinner for Unity, you should head to the beta release!

These release notes are a summary of important changes. A more complete document is made available as part of the Yarn Spinner for Unity beta release.

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

Added

• Version 2 of the Yarn language requires variables to be declared in order to use them. It's now an error to set or get a value from a variable that isn't declared.
  • Variables must always have a defined type, and aren't allowed to change type. This means, for example, that you can't store a string inside a variable that was declared as a number.
  • Variables also have a default value. As a result, variables are never allowed to be null.
  • Variable declarations can be in any part of a Yarn script. As long as they're somewhere in the file, they'll be used.
  • Variable declarations don't have to be in the same file as where they're used. If a script has a variable declaration, other scripts compiled with it can use the variable.
  • To declare a variable in a script, use the following syntax:

<<declare $variable_name = "hello">> // declares a string
<<declare $variable_name = 123>> // declares a number
<<declare $variable_name = true>> // declares a boolean

• Added substitution support to Dialogue (previously, the game client had to do it)
• Added support for markup.
• Added an EditorConfig file to assist future contributions in following the .NET coding style (@Schroedingers-Cat)
• Added Dialogue.prepareForLinesHandler, a delegate that is called when the Dialogue anticipates running certain lines; games can use this to pre-load content or take other actions to prepare to run lines.
  • Yarn Spinner will check the types of the delegate you provide. At present, parameters must be either ints, floats, doubles, bools, strings, or Yarn.Values.

Changed

• Library.RegisterFunction no longer works with the Function and ReturningFunction classes, which have been removed. Instead, you provide a Func directly, which can take multiple individual parameters, rather than a single Value[] parameter.
• The LineHandler, CommandHandler, and NodeCompleteHandler callbacks, used by the Dialogue class, no longer return a value that indicates whether the Dialogue should pause execution. Instead, the Dialogue will now always pause execution, which can be resumed by calling Dialogue.Continue(). (This method may be called from inside the line handler or command handler, or at any point after these handlers return.)
• The Compiler class no longer compiles Yarn scripts using the CompileFile and CompileString methods. Instead, the Compile method accepts a CompilationJob struct that describes the work to do, and returns a CompilationResult struct containing the result. This method allows for the compilation of multiple files into a single program, as well as supplying variable and function declarations.
• The Compiler class also supports doing only a partial compilation, returning only variable declarations or string table entries.
• Yarn scripts are now all compiled into a single YarnProgram. This improves compilation performance, ensures that scripts don't have multiple nodes with the same name, and ensures that scripts are able to make use of variables declared in other scripts.

Removed

• Functions registered with the Library class can no longer accept an unlimited number of parametes.

v1.2.0

Yarn Spinner v1.2 adds a variety of bug fixes and quality-of-life improvements.

Important Note: Yarn Spinner for Unity is moving to a new, dedicated repository. Future releases of Yarn Spinner for Unity will be made at its repo, YarnSpinnerTool/YarnSpinner-Unity. The core Yarn Spinner compiler will continue to be worked on on this repo.

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

Added

• Yarn scripts now appear with Yarn Spinner icon. (@Schroedingers-Cat)
• Documentation is updated to reflect the current version number (also to mention 2018.4 LTS as supported)
• Added a button in the Inspector for .yarn files in Yarn Spinner for Unity, which updates localised .csv files when the .yarn file changes. (@stalhandske, #227)
• Added handlers for when nodes begin executing (in addition to the existing handlers for when nodes complete.) (@arendhil, #222)
• OptionSet.Option now includes the name of the node that an option will jump to if selected.
• Added unit tests for Yarn Spinner for Unity (@Schroedingers-Cat)
• Yarn Spinner for Unity: Added a menu item for creating new Yarn scripts (Assets -> Create -> Yarn Script)
• Added Nuget package definitions for YarnSpinner and YarnSpinner.Compiler.

Changed

• Fixed a crash in the compiler when parsing single-character commands (e.g. <<p>>) (#231)
• Parse errors no longer show debugging information in non-debug builds.

v1.2.0 (beta 1)

Yarn Spinner v1.2 adds a variety of bug fixes and quality-of-life improvements.

NOTE: This release is a beta of v1.2. In addition to a higher risk of bugs, the features and APIs in this version may change in the final release without notice.

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

Added

• Yarn scripts now appear with Yarn Spinner icon. (@Schroedingers-Cat)
• Documentation is updated to reflect the current version number (also to mention 2018.4 LTS as supported)
• Added a button in the Inspector for .yarn files in Yarn Spinner for Unity, which updates localised .csv files when the .yarn file changes. (@stalhandske, #227)
• Added handlers for when nodes begin executing (in addition to the existing handlers for when nodes complete.) (@arendhil, #222)
• OptionSet.Option now includes the name of the node that an option will jump to if selected.
• Added unit tests for Yarn Spinner for Unity (@Schroedingers-Cat)
• Yarn Spinner for Unity: Added a menu item for creating new Yarn scripts (Assets -> Create -> Yarn Script)

Changed

• Fixed a crash in the compiler when parsing single-character commands (e.g. <<p>>) (#231)

v1.1.0

Yarn Spinner v1.1 adds powerful new features for creating content, and improves the development experience for programmers and writers.

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

Added

• Inline Expressions: Added support for inline expressions, which can be used in lines and options.
  • You can use inline expressions in lines, options, and shortcut options.
  • Inline expressions look like this: Mae: Wow! I have {$num_pies} pies!.
  • When the compiler processes a line that includes an inline expression, the line that's stored in the string table will have each of the expressions replaced with a placeholder. For example, the line above will be stored as Mae: Wow! I have {0} pies!. If you're translating a line to other languages, the placeholders can be moved and re-ordered as you need them.
  • Any expression can be used - numbers, strings, variables, function calls, or more complex expressions.
  • The Line struct now includes an array of substitutions, which Dialogue UI objects will insert into the localised line at the appropriate place.
• Format Functions: In-line expressions in your scripts that dynamically select text based on a variable.
  • These functions can be localised, which means you can change them based on the needs of the language you're translating the game into.
  • Format functions will appear as-is in the .csv string tables that Yarn Spinner for Unity generates, which means that they can be edited by translators.
  • Please note that format functions are intended to be a tool for ensuring correct grammar across multiple languages. They are more complex than a simple inline expression, and may complicate your dialogue. They're not intended to replace if-endif structures for your dialogue's logic.
  • There are three format functions available: select, plural, and ordinal.
  • The select function takes a string variable and uses its value to select a piece of text to use. For example:
    • Character: Wow, [select {$gender} male="he seems" female="she seems" other="they seem"] happy!
  • The plural function uses a number variable and determines its plural category. For example:
    • Character: Good thing I have {$money_count} gold [plural {$money_count} one="piece" other="pieces"]!
  • The ordinal function uses a number variable and determines its ordinal category. For example:
    • Character: The race is over! I came [ordinal {$race_position} one="%st" two="%nd" few="%rd" other="%th"]!
    • This example also shows how you can embed the variable that the function is using in the result - the % character will be replaced the variable's value (in this example, $race_position, creating text like "I came 3rd!")
  • Different languages have different plural rules. Yarn Spinner uses the plural rules defined by the Unicode CLDR; note that not all languages make use of all plural categories.
    • Yarn Spinner for Unity will use the Text Language setting in the Inspector to determine which plural rules to apply.
• Faster Compiling: Yarn Spinner for Unity now uses .asmdef files.
  • Yarn Spinner's Unity code now compiles to a separate assembly. (@Schroedingers-Cat)
  • IMPORTANT: if you're using asmdefs in your own code, any assembly you write that needs to refer to Yarn Spinner will need to add a reference to the YarnSpinner.Unity assembly.
• New Documentation: The Yarn Spinner site now has a lot more content. Full API documentation is now also available.
• Patreon Supporter Info: Patreon supporter information is now displayed in the Yarn Spinner window in Yarn Spinner for Unity.
  • To view it, open the Window menu, and choose Yarn Spinner.
  • While you're viewing it, why not consider becoming a supporter yourself? 😃

Changed

• Yarn Spinner's Unity integration now supports Unity 2018.4 LTS and later. (Previously, the minimum version was unspecified, but was actually 2019.2.)
• Fixed a bug that caused the unary minus operator (e.g. -$foo) to cause crashes when it's run.
• Unit tests now use test plans, which makes the test cases much more rigorous.

v1.1.0 (beta 3)

In addition to the work done in v1.1.0-beta2, this release fixes a bug in the parser that caused incorrect behaviour in if statements.

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

Changed

• Fixed a bug that caused <<else>> to be incorrectly parsed as a command, not an else statement, which meant that flow control didn't work correctly.

v1.1.0 (beta 2)

In addition to the work done in v1.1.0-beta1, this release adds support for .asmdef files, and displays information about our beloved Patreon supporters.

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

• Faster Compiling: Yarn Spinner for Unity now uses .asmdef files.
  • Yarn Spinner's Unity code now compiles to a separate assembly. (@Schroedingers-Cat)
  • IMPORTANT: if you're using asmdefs in your own code, any assembly you write that needs to refer to Yarn Spinner will need to add a reference to the YarnSpinner.Unity assembly.
• Patreon Supporter Info: Patreon supporter information is now displayed in the Yarn Spinner window in Yarn Spinner for Unity.
  • To view it, open the Window menu, and choose Yarn Spinner.
  • While you're viewing it, why not consider becoming a supporter yourself? 😃

v1.1 (beta 1)

This release adds support for inline expressions and format functions.

NOTE: This release is a beta of v1.1. In addition to a higher risk of bugs, the features and APIs in this version may change in the final release without notice.

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

Added

• Added support for inline expressions, which can be used in lines, options and commands.
  • You can use inline expressions in lines, options, shortcut options, and commands.
  • Inline expressions look like this: Mae: Wow! I have {$num_pies} pies!.
  • When the compiler processes a line that includes an inline expression, the line that's stored in the string table will have each of the expressions replaced with a placeholder. For example, the line above will be stored as Mae: Wow! I have {0} pies!. If you're translating a line to other languages, the placeholders can be moved and re-ordered as you need them.
  • Any expression can be used - numbers, strings, variables, function calls, or more complex expressions.
  • The Line struct now includes an array of substitutions, which Dialogue UI objects will insert into the localised line at the appropriate place.
• Added support for format functions.
  • Format functions are in-line expressions in your scripts that dynamically select text based on a variable. These functions can be localised, which means you can change them based on the needs of the language you're translating the game into.
  • Format functions will appear as-is in the .csv string tables that Yarn Spinner for Unity generates, which means that they can be edited by translators.
  • Please note that format functions are intended to be a tool for ensuring correct grammar across multiple languages. They are more complex than a simple inline expression, and may complicate your dialogue. They're not intended to replace if-endif structures for your dialogue's logic.
  • There are three format functions available: select, plural, and ordinal.
  • The select function takes a string variable and uses its value to select a piece of text to use. For example:
    • Character: Wow, [select {$gender} male="he seems" female="she seems" other="they seem"] happy!
  • The plural function uses a number variable and determines its plural category. For example:
    • Character: Good thing I have {$money_count} gold [plural {$money_count} one="piece" other="pieces"]!
  • The ordinal function uses a number variable and determines its ordinal category. For example:
    • Character: The race is over! I came [ordinal {$race_position} one="%st" two="%nd" few="%rd" other="%th"]!
    • This example also shows how you can embed the variable that the function is using in the result - the % character will be replaced the variable's value (in this example, $race_position, creating text like "I came 3rd!")
  • Different languages have different plural rules. Yarn Spinner uses the plural rules defined by the Unicode CLDR; note that not all languages make use of all plural categories.
    • Yarn Spinner for Unity will use the Text Language setting in the Inspector to determine which plural rules to apply.
• Yarn Spinner for Unity now uses .asmdef files. Yarn Spinner's Unity code now compiles to a separate assembly.
  • IMPORTANT: if you're using asmdefs in your game's code, you will need to add a reference to YarnSpinner.Unity.

Changed

• Yarn Spinner's Unity integration now supports Unity 2018.4 LTS and later. (Previously, the minimum version was unspecified, but was actually 2019.2.)
• Fixed a bug that caused the unary minus operator (e.g. -$foo) to cause crashes when it's run.
• Unit tests now use test plans, which makes the test cases much more rigorous.

v1.0.3

This release adds bug fixes and some small quality-of-life improvements. In particular, a bug that could cause the string tables for a node to not load correctly has been fixed. Thanks to all who reported it!

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 reject node titles that contain an invalid character. Invalid characters for node titles are: [, ], {, }, |, :, #, $, or spaces.
• Added some parser tests for working with node headers.

Changed

• Fixed a bug where the Dialogue UI component in Unity would not actually send any commands to the 'On Command' event.
• Command handlers will now look for command handlers added via AddCommandHandler first (which is faster), followed by commands registered using the YarnCommand attribute (which is slower).
• When writing an option (for example, [[Hello!| Greeting ]]), any whitespace around the node name (Greeting) will be discarded. This fixes a bug where Yarn Spinner would try to go to a node named " Greeting ", but spaces in node names aren't allowed. (#192)
• Fixed a bug where a null reference exception would be thrown the first time a new Yarn file's Inspector is drawn. (@Schroedingers-Cat)
• Made string table CSVs always be read and written in the Invariant culture. Previously, locale differences would lead to parsing failures. (#197)
• Disabled 'this field is never assigned to' warnings for certain files in the Unity version (they're assigned in the Editor, which the compiler doesn't know about.)

v1.0.2

This release adds bug fixes and some small quality-of-life improvements.

Please consider supporting Yarn Spinner's development by becoming a patron!

Added

• Added a method for manually loading a string table as a dictionary to DialogueRunner
• DialogueUI now allows skipping to the end of a line's delivery, by calling MarkLineComplete before the line has finished appearing.
• Option buttons can now use TextMeshPro Text components, in addition to Unity UI Text components. (TextMeshPro for line display was already supported.)
• DialogueUI now allows other scripts to select an option. When the SelectOption method, which takes an integer representing the index of the option you want to select, is called, the Dialogue UI will act as though the corresponding button was clicked.

Changed

• Made the debug display in InMemoryVariableStorage slightly tidier
• Made changing the InMemoryVariableStorage update its debug display's layout components
• Made InMemoryVariableStorage's contents enumerable in a foreach loop
• Fixed a bug where the Dialog would pause when a blocking command handler immediately calls its onComplete and returns
• Fixed a bug where parsing the <<wait>> command's parameter was locale-specific (i.e. certain European locales parse decimal numbers as "1,0"), which meant that behaviour would vary based on the end-user's configuration.
• Fixed a bug where manually-added functions would never run if the first parameter was the name of an object in the scene.
• Improved the UI for managing localised lines (thanks to @Schroedingers-Cat)