2.2.0-beta

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

👩‍🚒 Getting Help

There are several places you can go to get help with Yarn Spinner.

• Join the Yarn Spinner Discord.
• Tweet at us, at @YarnSpinnerTool.
• To report a bug, file an issue on GitHub.

📦 How To Install Yarn Spinner

To install the most recent release of Yarn Spinner for Unity, please see the Installation Instructions in the Yarn Spinner documentation.

If you want to install this particular version of Yarn Spinner for Unity, follow these steps:

Installing Yarn Spinner for Unity 2.2.0-beta from Git

• Open the Window menu, and choose Package Manager.
• If you already have any previous version of the Yarn Spinner package installed, remove it.
• Click the + button, and click Add package from git URL...
• Enter the following URL:
  • https://github.com/YarnSpinnerTool/YarnSpinner-Unity.git#2.2.0-beta

Each release will have a different URL. To upgrade to future versions of Yarn Spinner, you will need to uninstall the package, and reinstall using the new URL.

📜 Changes

Added

• A simple, built-in system for saving and loading Yarn variables to the built-in PlayerPrefs object has been added.
  • Call DialogueRunner.SaveStateToPlayerPrefs to save all variables to the PlayerPrefs system, and DialogueRunner.LoadStateFromPlayerPrefs to load from PlayerPrefs into the variable storage.
  • These methods do not write to file (except via PlayerPrefs, which handles disk writing on its own), and only work with variables (and not information like which line is currently being run.)
• Metadata for each line is exposed through a Yarn Project. Metadata generally comes as hashtags similar to #line. They can be used to define line-specific behavior (no particular behavior is supported by default, each user will need to define their own).
• When exporting Strings files, a Yarn Project will also export another CSV file with the line metadata (for each line with metadata).
• LocalizedLines now contain a field for any metadata associated with the line.
• YarnFunction tagged methods now appear in the inspector window for the project, letting you view their basic info.

Changed

• YarnPreventPlayMode no longer uses WeakReference pointing to Unity.Object (this is unsupported by Unity).
• ActionManager no longer logs every single command that it registers. (#165)
• Line view should no longer have unusual interactions around enabling and disabling different effects (#161 and #153).
• Improved the type inference system around the use of functions.

This has two pieces, the first is in YarnSpinner Core and adds in support for partial backwards type inference.
This means in many situations where either the l-value or r-value of an expression is known that can be used to provide a type to the other side of the equation.
Additionally now functions tagged with the YarnFunction attribute are sent along to the compiler so that they can be used to inform values.
The upside of this is in situations like <<set $cats = get_cats()>> if either $cats is declared or get_cats is tagged as a YarnFunction there won't be an error anymore.

v2.1.0

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

👩‍🚒 Getting Help

There are several places you can go to get help with Yarn Spinner.

• Read the Yarn Spinner Documentation.
• Join the Yarn Spinner Discord.
• Tweet at us, at @YarnSpinnerTool.
• To report a bug, file an issue on GitHub.

📦 How To Install Yarn Spinner

To install the most recent release of Yarn Spinner for Unity, please see the Installation Instructions in the Yarn Spinner documentation.

If you want to install this particular version of Yarn Spinner for Unity, follow these steps:

Installing Yarn Spinner for Unity v2.1.0 from Git

• Open the Window menu, and choose Package Manager.
• If you already have any previous version of the Yarn Spinner package installed, remove it.
• Click the + button, and click Add package from git URL...
• Enter the following URL:
  • https://github.com/YarnSpinnerTool/YarnSpinner-Unity.git#v2.1.0

Each release will have a different URL. To upgrade to future versions of Yarn Spinner, you will need to uninstall the package, and reinstall using the new URL.

📜 Changes

Dialogue View API Update

The API for creating new Dialogue Views has been updated.

Background: Dialogue Views are objects that receive lines and options from the Dialogue Runner, present them to the player, receive option selections, and signal when the user should see the next piece of content. They're subclasses of the DialogueViewBase class. All of our built-in Dialogue Views, such as LineView and OptionsListView, are examples of this.

Previously, line objects stored information about their current state, and as Dialogue Views reported that they had finished presenting or dismissing their line, all views would receive a signal that the line's state had changed, and respond to those changes by changing the way that the line was presented (such as by dismissing it when the line's state became 'Dismissed'). This meant that every Dialogue View class needed to implement fairly complex logic to handle these changes in state.

In this release, 'line state' is no longer a concept that Dialogue Views need to keep track of. Instead, Dialogue Views that present lines simply need to implement three methods:

• RunLine is called when the Dialogue Runner wants to show a line to the player. It receives a line, as well as a completion handler to call when the line view has finished delivering the contents line.
• InterruptLine is called when the Dialogue Runner wants all Dialogue Views to finish presenting their lines as fast as possible. It receives the line that's currently being presented, as well as a new completion handler to call when the presentation is finished (which this method should try and call as quickly as it can.)
• DismissLine is called when all Dialogue Views have finished delivering their line (whether it was interrupted, or whether it completed normally). It receives a completion handler to call when the dismissal is complete.

The updated flow is this:

1. While running a Yarn script, the Dialogue Runner encounters a line of dialogue to show to the user.
2. It calls RunLine on all Dialogue Views, and waits for all of them to call their completion handler to indicate that they're done presenting the line.
   • At any point, a Dialogue View can call a method that requests that the current line be interrupted. When this happens, the Dialogue Runner calls InterruptLine on the Dialogue Views, and waits for them to call the new completion handler to indicate that they've finished presenting the line.
3. Once all Dialogue Views have reported that they're done, the Dialogue Runner calls DismissLine on all Dialogue Views, and waits for them to call the completion handler to indicate that they're done dismissing the line.
4. The Dialogue Runner then moves on to the next piece of content.

This new flow significantly simplifies the amount of information that a Dialogue View needs to keep track of, as well as the amount of logic that a Dialogue View needs to have to manage this information.

Instead, it's a simpler model of: "when you're told to run a line, run it, and tell us when you're done. When you're told to interrupt the line, finish running it ASAP and tell us when you're done. Finally, when you're told to dismiss your line, do it and let us know when you're done."

We've also moved the user input handling code out of the built-in LineView class, and into a new class called DialogueAdvanceInput. This class lets you use either of the Unity Input systems to signal to a DialogueView that the user wants to advance the dialogue; by moving it out of our built-in view, it's a little easier for Dialogue View writers, who may not want to have to deal with input.

This hopefully alleviates some of the pain points in issues relating to how Dialogue Views work, like issue #95.

There are no changes to how options are handled in this new API.

Jump to Expressions

• The <<jump>> statement can now take an expression.

<<set $myDestination = "Home">>
<<jump {$myDestination}>>

• Previously, the jump statement required the name of a node. With this change, it can now also take an expression that resolves to the name of a node.
• Jump expressions may be a constant string, a variable, a function call, or any other type of expression.
• These expressions must be wrapped in curly braces ({ }), and must produce a string.

Added

• Added a new component, DialogueAdvanceInput, which responds to user input and tells a Dialogue View to advance.
• Added DialogueViewBase.RunLine method.
• Added DialogueViewBase.InterruptLine method.
• Added DialogueViewBase.DismissLine method.

Changed

• Updated to Yarn Spinner Core 2.1.0.
• Updated DialogueRunner to support a new, simpler API for Dialogue Views; lines no longer have a state for the Dialogue Views to respond to changes to, and instead only receive method calls that tell them what to do next.
• Fixed a bug where changing a Yarn script asset in during Play Mode would cause the string table to become empty until the next import (#154)
• Fixed a bug where Yarn functions outside the default assembly would fail to be loaded.

Removed

• Removed LineStatus enum.
• Removed DialogueViewBase.OnLineStatusChanged method.
• Removed DialogueViewBase.ReadyForNextLine method.
• Removed VoiceOverPlaybackFmod class. (This view was largely unmaintained, and we feel that it's best for end users to customise their FMOD integration to suit their own needs.)
• Renamed VoiceOverPlaybackUnity to VoiceOverView.

v2.0.2

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

👩‍🚒 Getting Help

There are several places you can go to get help with Yarn Spinner.

• Join the Yarn Spinner Discord.
• Tweet at us, at @YarnSpinnerTool.
• To report a bug, file an issue on GitHub.

📦 How To Install Yarn Spinner

To install the most recent release of Yarn Spinner for Unity, please see the Installation Instructions in the Yarn Spinner documentation.

If you want to install this particular version of Yarn Spinner for Unity, follow these steps:

Installing Yarn Spinner for Unity v2.0.2 from Git

• Open the Window menu, and choose Package Manager.
• If you already have any previous version of the Yarn Spinner package installed, remove it.
• Click the + button, and click Add package from git URL...
• Enter the following URL:
  • https://github.com/YarnSpinnerTool/YarnSpinner-Unity.git#v2.0.2

Each release will have a different URL. To upgrade to future versions of Yarn Spinner, you will need to uninstall the package, and reinstall using the new URL.

📜 Changes

Added

• You can now specify which assemblies you want Yarn Spinner to search for YarnCommand and YarnFunction methods in.
  • By default, Yarn Spinner will search in your game's code, as well as every assembly definition in your code and your packages.
  • You can choose to make Yarn Spinner only look in specific assembly definitions, which reduces the amount of time needed to search for commands and functions.
  • To control how Yarn Spinner searches for commands and actions, turn off "Search All Assemblies" in the Inspector for a Yarn Project.
• Added a Spanish translation to the Intro sample.

Changed

• ActionManager now only searches for commands and actions in assemblies that Yarn Projects specify. This significantly reduces startup time and memory usage.
• Improved error messages when calling methods defined via the YarnCommand attribute where the specified object can't be found.

v2.0.1

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

👩‍🚒 Getting Help

There are several places you can go to get help with Yarn Spinner.

• Join the Yarn Spinner Discord.
• Tweet at us, at @YarnSpinnerTool.
• To report a bug, file an issue on GitHub.

📦 How To Install Yarn Spinner

To install the most recent release of Yarn Spinner for Unity, please see the Installation Instructions in the Yarn Spinner documentation.

If you want to install this particular version of Yarn Spinner for Unity, follow these steps:

Installing Yarn Spinner for Unity v2.0.1 from Git

• Open the Window menu, and choose Package Manager.
• If you already have any previous version of the Yarn Spinner package installed, remove it.
• Click the + button, and click Add package from git URL...
• Enter the following URL:
  • https://github.com/YarnSpinnerTool/YarnSpinner-Unity.git#v2.0.1

Each release will have a different URL. To upgrade to future versions of Yarn Spinner, you will need to uninstall the package, and reinstall using the new URL.

📜 Changes

For the full list of changes from Yarn Spinner 1.x to Yarn Spinner 2.x, please see the full changelog from the original Yarn Spinner 2.0 release.

Added

• The v1 to v2 language upgrader now renames node names that have a period (.) in their names to use underscores (_) instead. Jumps and options are also updated to use these new names.

Changed

• Fixed a crash in the compiler when producing an error message about an undeclared function.
• Fixed an error when a constant float value (such as in a <<declare>> statement) was parsed and the user's current locale doesn't use a period (.) as the decimal separator.

v2.0.0

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

👩‍🚒 Getting Help

There are several places you can go to get help with Yarn Spinner.

• Join the Yarn Spinner Discord.
• Tweet at us, at @YarnSpinnerTool.
• To report a bug, file an issue on GitHub.

📦 How To Install Yarn Spinner

To install the most recent release of Yarn Spinner for Unity, please see the Installation Instructions in the Yarn Spinner documentation.

If you want to install this particular version of Yarn Spinner for Unity, follow these steps:

Installing Yarn Spinner for Unity v2.0.0 from Git

• Open the Window menu, and choose Package Manager.
• If you already have any previous version of the Yarn Spinner package installed, remove it.
• Click the + button, and click Add package from git URL...
• Enter the following URL:
  • https://github.com/YarnSpinnerTool/YarnSpinner-Unity.git#v2.0.0

Each release will have a different URL. To upgrade to future versions of Yarn Spinner, you will need to uninstall the package, and reinstall using the new URL.

📜 Changes

Yarn Spinner 2.0

Yarn Spinner 2.0 is a major new release, and contains a large number of new features and improvements.

New syntax for jumping to a different node.

• We have added a <<jump Destination>> command, which replaces the [[Destination]] jump syntax.

• Accordingly, the [[Destination]] and [[Option|Destination]] syntax has been removed from the language.
• Instead of using [[Option|Destination]] syntax, combine the new <<jump Destination>> command with 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>>

• The old syntax was inherited from the original Yarn language, which itself inherited it from Twine.
  - We removed it for four reasons:
  1. it conflated jumps and options, which are very different operations, with too-similar syntax
  2. 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)
  3. it was not obvious that options accumulated and were only presented at the end of the node
  4. finally, shortcut options provide a cleaner way to present the same behaviour.
• No change to the bytecode is made here; these changes only affect the compiler.

Automatic upgrader for Yarn Spinner 1.0 variables.

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

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

You can use characters that the parser uses in scripts!

• Characters can now be escaped in lines and options.

• The \ character can be used to write characters that the parser would otherwise use.
• The following characters can be escaped: { } < > # / \
  • The / and < characters don't usually need to be escaped if they're appearing on their own (they're only meaningful when they appear in pairs), but this allows you to escape things like commands and comments.

Identifiers now support a wider range of characters.

This includes most multilingual letters and numbers, as well as symbols and emoji.

Made line conditions control the IsAvailable flag on options that are sent to the game.

• This change was made in order to allow games to conditionally present, but disallow, options that the player can't choose. For example, consider the following script:

TD-110: Let me see your identification.
-> Of course... um totally not General Kenobi and the son of Darth Vader.
    Luke: Wait, what?!
    TD-110: Promotion Time!
-> You don't need to see his identification. <<if $learnt_mind_trick is true>>
    TD-110: We don't need to see his identification.

• If the variable $learnt_mind_trick is false, a game may want to show the option but not allow the player to select it (i.e., show that this option could have been chosen if they'd learned how to do a mind trick.)
  • In previous versions of Yarn Spinner, if a line condition failed, the entire option was not delivered to the game. With this change, all options are delivered, and the OptionSet.Option.IsAvailable variable contains false if the condition was not met, and true if it was (or was not present.)
  • It's entirely up to the game to decide what to do with this information. To re-create the behaviour from previous Yarn Spinner versions, simply don't show any options whose IsAvailable value is false.

Variable declarations are now automatically determined, where possible

• If a variable is not declared (i.e. it doesn't have a <<declare>> statement), the compiler will now attempt to infer its declaration.
• When a variable doesn't have a declaration, the compiler will try to figure out the type based on how the variable is being used. It will always try to figure out the single type that the variable must be; if it's ambiguous, or no information is available at all, it will report an error, and you will have to add a declaration.

Variable declaration descriptions use comments

• Declarations have their descriptions set using a triple-slash (///) comment:

/// The number of coins the player has
<<declare $coins = 0>>

• These documentation comments can be before a declaration, or on the same line as a declaration:

<<declare $player_likes_dogs = true>> /// Whether the player likes dogs or not

• Multiple-line documentation comments are also supported:

/// Whether these are the droids that the 
/// guards are looking for.
<<declare $are_the_droids_we're_looking_for = false>>

A new type system has been added.

• The type-checking system in Yarn Spinner now supports types with supertypes and methods. This change has no significant impact on users writing Yarn scripts, but it enables the development of more advanced language features.
  • The main impact on users of this library (such as, for example, Yarn Spinner for Unity) is that the Yarn.Type enumeration has been removed, and is now replaced with the Yarn.IType interface and the BuiltinTypes class.
  • The type checker no longer hard-codes which operations can be run on which types; this decision is now determined by the types themselves.

Better Error Messages

The Compiler will no longer throw a ParseException, TypeException or CompilerException when an error is encountered during compilation. Instead, CompilationResult.Diagnostics contains a collection of Diagnostic objects...

v2.0.0-rc1

This is a pre-release version of Yarn Spinner for Unity. It is not yet considered ready for production use.

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

👩‍🚒 Getting Help

There are several places you can go to get help with Yarn Spinner.

• Join the Yarn Spinner Discord.
• Tweet at us, at @YarnSpinnerTool.
• To report a bug, file an issue on GitHub.

📦 How To Install Yarn Spinner

This release is available as a Unity package, using a Git URL. Additional download options will be available for the final release.

To install this release of Yarn Spinner into your Unity project, follow these steps:

• Open the Window menu, and choose Package Manager.
• If you already have any previous version of the Yarn Spinner package installed, remove it.
• Click the + button, and click Add package from git URL...
• Enter the following URL:
  • https://github.com/YarnSpinnerTool/YarnSpinner-Unity.git#v2.0.0-rc1

Each release will have a different URL. To upgrade to future versions of Yarn Spinner 2.0, you will need to uninstall the package, and reinstall using the new URL.

📜 Changes

Added

• Command parameters can now be grouped with double quotes. eg. <<add-recipe "Banana Sensations"> and <<move "My Game Object" LocationName>> (@andiCR)

• You can now add dialogue views to dialogue runner at any time.

• The inspector for Yarn scripts now allows you to change the Project that the script belongs to. (@radiatoryang)

• Yarn script compile errors will prevent play mode.

• Default functions have been added for convenience.

  • float random() - returns a number between 0 and 1, inclusive (proxies Unity's default prng)
  • float random_range(float, float) - returns a number in a given range, inclusive (proxies Unity's default prng)
  • int dice(int) - returns an integer in a given range, like a dice (proxies Unity's default prng)
    • For example, dice(6) + dice(6) to simulate two dice, or dice(20) for a D20 roll.
  • int round(float) - rounds a number using away-from-zero rounding
  • float round_places(float, int) - rounds a number to n digits using away-from-zero rounding
  • int floor(float) - floors a number (towards negative infinity)
  • int ceil(float) - ceilings a number (towards positive infinity)
  • int int(float) - truncates the number (towards zero)
  • int inc(float | int) - increments to the next integer
  • int dec(float | int) - decrements to the previous integer
  • int decimal(float) - gets the decimal portion of the float

• The YarnFunction attribute has been added.

  • Simply add it to a static function, eg

    [YarnFunction] // registers function under "example"
    public static int example(int param) {
      return param + 1;
    }
    
    [YarnFunction("custom_name")] // registers function under "custom_name"
    public static int example2(int param) {
      return param * param;
    }

• The YarnCommand attribute has been improved and made more robust for most use cases.

  • You can now leave the name blank to use the method name as the registration name.

    [YarnCommand] // like in previous example with YarnFunction.
    void example(int steps) {
      for (int i = 0; i < steps; i++) { ... }
    }
    
    [YarnCommand("custom_name")] // you can still provide a custom name if you want
    void example2(int steps) {
      for (int i = steps - 1; i >= 0; i--) { ... }
    }

  • It now recognizes static functions and does not attempt to use the first parameter as an instance variable anymore.

    [YarnCommand] // use like so: <<example>>
    static void example() => ...;
    
    [YarnCommand] // still as before: <<example2 objectName>>
    void example2() => ...;

  • You can also define custom getters for better performance.

    [YarnStateInjector(nameof(GetBehavior))] // if this is null, the previous behavior of using GameObject.Find will still be available
    class CustomBehavior : MonoBehaviour {
      static CustomBehavior GetBehavior(string name) {
        // e.g., it may only exist under a certain transform, or you have a custom cache...
        // or it's built from a ScriptableObject...
        return ...;
      }
    
      [YarnCommand] // the "this" will be as returned from GetBehavior
      void example() => Debug.Log(this);
    
      // special variation on getting behavior
      static CustomBehavior GetBehaviorSpecial(string name) => ...;
    
      [YarnCommand(Injector = nameof(GetBehaviorSpecial))]
      void example_special() => Debug.Log(this);
    }

  • You can also define custom getters for Component parameters in the same vein.

    class CustomBehavior : MonoBehaviour {
      static Animator GetAnimator(string name) => ...;
    
      [YarnCommand]
      void example([YarnParameter(nameof(GetAnimator))] Animator animator) => Debug.Log(animator);
    }

  • You should continue to use manual registration if you want to make an instance function (ie where the "target" is defined) static.

• Sample scenes now have a render pipeline detector gameobject that will warn when the sample scene materials won't look correct in the current render pipeline.

• Variables declared inside Yarn scripts will now have the default values set into the variable storage.

Changed

• Updated to support new error handling in Yarn Spinner.

  • Yarn Spinner longer reports errors by throwing an exception, and instead provides a collection of diagnostic messages in the compiler result. In Unity, Yarn Spinner will now show all error messages that the compiler may produce.

• The console will no longer report an error indicating that a command is "already defined" when a subclass of a MonoBehaviour that has YarnCommand methods exists.

• LocalizedLine.Text's setter is now public, not internal.

• DialogueRunner will now throw an exception if a dialogue view attempts to select an
  option on the same frame that options are run.

• DialogueRunner.VariableStorage can now be modified at runtime.

• Calling DialogueRunner.StartDialogue when the dialogue runner is already running will now result in an error being logged.

• Line Views will now only enable and disable action references if the line view is also configured to use said action.

• Yarn Project importer will now save variable declaration metadata on the first time

Removed

• Support for Unity 2018 LTS has been dropped, and 2019 LTS (currently 2019.4.32f1) will be the minimum supported version. The support scheme for Yarn Spinner will be clarified in the CONTRIBUTING docs. If you still require support for 2018, please join our Discord!

v2.0.0 Beta 5

If you haven't read the release notes for the previous beta, we strongly suggest you read those first to learn what's new in Yarn Spinner 2.0!

This is a pre-release version of Yarn Spinner for Unity. It is not yet considered ready for production use.

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

👩‍🚒 Getting Help

There are several places you can go to get help with the Yarn Spinner beta.

• Join the Yarn Spinner Discord.
• Tweet at us, at @YarnSpinnerTool, or use the #YS2beta hashtag.
• To report a bug, file an issue on GitHub.

📦 How To Install Yarn Spinner 2.0 Beta 5

The beta is available as a Unity package, using a Git URL. Additional download options will be available for the final release.

To install Yarn Spinner 2.0 Beta 5 into your Unity project, follow these steps:

• Open the Window menu, and choose Package Manager.
• If you already have any previous version of the Yarn Spinner package installed, remove it.
• Click the + button, and click Add package from git URL...
• Enter the following URL:
  • https://github.com/YarnSpinnerTool/YarnSpinner-Unity.git#v2.0.0-beta5

Each beta will have a different URL. To upgrade to future versions of the Yarn Spinner 2.0 beta, you will need to uninstall the package, and reinstall using the new URL.

📜 Changes

Added

• InMemoryVariableStorage now throws an exception if you attempt to get or set a variable whose name doesn't start with $.

Changed

• OptionsListView no longer throws a NullPointerException when the dialogue starts with options (instead of a line.)
• When creating a new Yarn Project file from the Assets -> Create menu, the correct icon is now used.
• Updated to use the new type system in Yarn Spinner 2.0-beta5.

Removed

• Yarn Programs: The 'Convert Implicit Declarations' button has been temporarily removed, due to a required compatibility change related to the new type system. It will be restored before final 2.0 release.

v2.0.0 Beta 4

Yarn Spinner 2.0 Beta 4 is a hotfix release for Yarn Spinner 2.0 Beta 3. It fixes an issue that caused Yarn Spinner to not compile on Unity 2018 or Unity 2019.

The release notes for Beta 3 follow:

If you haven't read the release notes for the first and second betas, we strongly suggest you read those first to learn what's new in Yarn Spinner 2.0!

This is a pre-release version of Yarn Spinner for Unity. It is not yet considered ready for production use.

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

🚨 The Most Important Parts

This release contains significant changes to the workflow compared to previous betas. The most important are:

• Yarn Programs have been renamed Yarn Projects.
  • Because this is a change to the name of a type, any references to Yarn Programs will need to be set up again.
• You no longer create Localisation assets yourself. They're generated for you by the Yarn Project.
  • Localised assets, such as voice-over clips, are now automatically located and set up (you no longer need to occasionally manually refresh the localisation system.)
• The Localisation Database asset has been removed, and you don't need to create or use them.
  • Yarn Projects now serve the same function.
• Addressable Assets no longer require a separate workflow and components. The same components used for direct asset references now also support Addressable Assets.
• You no longer specify a list of supported languages in your project settings.
  • The list of available languages is now defined by the Yarn Project, and the specific language to use is determined by the Line Provider that your Dialogue Runner is using.
  • If the appropriate language cannot be found for the selected language, the original language of your Yarn Project is used.
• A new dialogue prefab, found in Packages > Yarn Spinner > Prefabs > Dialogue System, has been added.
  • This prefab makes use of new, more customisable dialogue views. This prefab is designed to be a complete solution for games to use, while also being a useful jumping-off point for building custom interfaces.
  • The majority of the Sample projects, including Intro, VisualNovel, and 3D, have been updated to use these new dialogue views, to demonstrate how they can be used.

👩‍🚒 Getting Help

There are several places you can go to get help with the Yarn Spinner beta.

• Join the Yarn Spinner Discord.
• Tweet at us, at @YarnSpinnerTool, or use the #YS2beta hashtag.
• To report a bug, file an issue on GitHub.

📦 How To Install Yarn Spinner 2.0 Beta 4

The beta is available as a Unity package, using a Git URL. Additional download options will be available for the final release.

To install Yarn Spinner 2.0 Beta 4 into your Unity project, follow these steps:

• Open the Window menu, and choose Package Manager.
• If you already have any previous version of the Yarn Spinner package installed, remove it.
• Click the + button, and click Add package from git URL...
• Enter the following URL:
  • https://github.com/YarnSpinnerTool/YarnSpinner-Unity.git#v2.0.0-beta4

Each beta will have a different URL. To upgrade to future versions of the Yarn Spinner 2.0 beta, you will need to uninstall the package, and reinstall using the new URL.

Added

• The dialogue runner can now be configured to log less to the console, reducing the amount of noise it generates there. (@radiatoryang)
• Warning messages and errors now appear to help users diagnose two common problems: (1) not adding a Command properly, (2) can't find a localization entry for a line (either because of broken line tag or bad connection to Localization Database) (@radiatoryang)
• Made options that have a line condition able to be presented to the player, but made unavailable.
• This change was made in order to allow games to conditionally present, but disallow, options that the player can't choose. For example, consider the following script:

TD-110: Let me see your identification.
-> Of course... um totally not General Kenobi and the son of Darth Vader.
    Luke: Wait, what?!
    TD-110: Promotion Time!
-> You don't need to see his identification. <<if $learnt_mind_trick is true>>
    TD-110: We don't need to see his identification.

• If the variable $learnt_mind_trick is false, a game may want to show the option but not allow the player to select it (i.e., show that this option could have been chosen if they'd learned how to do a mind trick.)
• In previous versions of Yarn Spinner, if a line condition failed, the entire option was not delivered to the game. With this change, all options are delivered, and the OptionSet.Option.IsAvailable variable contains false if the condition was not met, and true if it was (or was not present.)
• The DialogueUI component now has a "showUnavailableOptions" option that controls the display behaviour of unavailable options. If it's true, then unavailable options are presented, but not selectable; if it's false, then unavailable options are not presented at all (i.e. same as Yarn Spinner 1.0.)
• Audio for lines in a Localization object can now be previewed in the editor. (@radiatoryang)
• Lines can be added to a Localization object at runtime. They're only stored in memory, and are discarded when gameplay ends.
• Commands that take a boolean parameter now support specifying that parameter by its name, rather than requiring the string true.
• For example, if you have a command like this:

  [YarnCommand("walk")]
  void WalkToPoint(string destinationName, bool wait = false) {
    // ...
  }

Previously, you'd need to use this in your Yarn scripts:

<<walk MyObject MyDestination true>>

With this change, you can instead say this:

<<walk MyObject MyDestination wait>>

• New icons for Yarn Spinner assets have been added.
• New dialogue views, LineView and OptionListView, have been added. These are intended to replace the previous DialogueUI, make use of TextMeshPro for text display, and allow for easier customisation through prefabs.
• DialogueRunners will now automatically create and use an InMemoryVariableStorage object if one isn't provided.
• The Inspector for DialogueRunner has been updated, and is now easier to use.

Changed

• Certain private methods in DialogueUI have changed to protected, making it easier to subclass (@radiatoryang)
• Fixed an issue where option buttons from previous option prompts could re-appear in later prompts (@radiatoryang)
• Fixed an issue where dialogue views that are not enabled were still being waited for (@radiatoryang)
• Upgrader tool now creates new files on disk, where needed (for example, .yarnproject files)
• YarnProgram, the asset that stores references to individual .yarn files for compilation, has been renamed to YarnProject. Because this change makes Unity forget any existing references to "YarnProgram" assets, when upgrading to this version, you must set the Yarn Project field in your Dialogue Runners again.
• Localization, the asset that mapped line IDs to localized data, is now automatically generated for you by the YarnProject.
  • You don't create them yourselves, and you no longer need to manually refresh them.
  • The YarnProject always creates at least one localization: the "Base" localization, which contains the original text found in your .yarn files.
  • You can create more localizations in the YarnProject's inspector, and supply the language code to use and a .csv file containing replacement strings.
• Renamed the 'StartHere' demo to 'Intro', because it's not actually the first step in installing Yarn Spinner.
• Simplified the workflow for working with Addressable Assets.
  • You now import the package, enable its use on your Yarn Project, and click the Update Asset Addresses button to ensure that all assets have an address that Yarn Spinner knows about.
• The 3D, VisualNovel, and Intro examples have been updated to use the new LineView and OptionsListView components, rather than DialogueUI.
• DialogueRunner.ResetDialogue is now marked as Obsolete (it had the same effect as just calling StartDialogue anyway.)
• The LineStatus enum's values have been renamed, to better convey their purpose:
  • Running is now Presenting.
  • Interrupted remains the same.
  • Delivered is now FinishedPresenting.
  • Ended is now Dismissed .
• The ResetDialogue() method now takes an optional parameter to restart from. If none is provided, the dialogue runner attempts to restart from the start node, followed by the current node, or else throws an exception.
• DialogueViewBase.MarkLineComplete, the method for signalling that the user wants to interrupt or proceed to the next line, has been renamed to ReadyForNextLine.
• DialogueRunner.continueNextLineOnLineFinished has been renamed to automaticallyContinueLines.

Removed

• LocalizationDatabase, the asset that stored references to Localization assets and manages per-locale line lookups, has been removed. This functionality is now handled by YarnProject assets. You no longer supply a localizati...

v2.0.0 Beta 3

Yarn Spinner Beta 3 has been superseded by Beta 4, which contains a critical bugfix for Unity 2018 and Unity 2019 users.

v2.0.0 Beta 2

This is the second beta for Yarn Spinner 2.0. If you haven't read the release notes for the first beta, we strongly suggest you read those first to learn what's new in Yarn Spinner 2.0!

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

Added

• InMemoryVariableStorage now shows the current state of variables in the Inspector. (@radiatoryang)
• InMemoryVariableStorage now supports saving variables to file, and to PlayerPrefs. (@radiatoryang)

Changed

• Inline expressions (for example, One plus one is {1+1}) are now expanded.
• Added Help URLs to various classes. (@radiatoryang)
• The Upgrader window (Window -> Yarn Spinner -> Upgrade Scripts) now uses the updated Yarn Spinner upgrade tools. See Yarn Spinner 2.0.0-beta2 release notes for more information on the upgrader.
• Fixed an issue where programs failed to import if a source script reference is invalid
• Fixed an issue where the DialogueUI would show empty lines when showCharacterName is false and the line has no character name

Removed

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

• InMemoryVariableStorage no longer manages 'default' variables (this concept has moved to the Yarn Program.) (@radiatoryang)