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:

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. These release notes cover both Yarn Spinner for Unity, and the core Yarn Spinner compiler that Unity uses under the hood.

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.

New things

• The .yarnproject importer has been updated to use new JSON-based Yarn Projects.

  • JSON-formatted Yarn Projects replace the previous format, which stored all import data in Unity’s .meta files. This helps us lay the groundwork for releases that support other engines. 👀
  • JSON-formatted Yarn Projects allow a single Yarn script to be used in multiple Yarn Projects, and also allow the Yarn Spinner compiler to support upcoming new features.
    • 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.
      • You can see an example of the format of these JSON-based Yarn Projects here.
  • Yarn scripts no longer need to be manually associated with a Yarn Project. If they are in the same folder, or a subfolder, of the Yarn Project, they will be included.
  • In Unity, you can add, modify, and delete source file patterns for Yarn projects in the Inspector.
  • When you update from an earlier version to 2.3, all Yarn scripts and Yarn Projects will be re-imported:
    • You will receive import errors on your existing Yarn Projects, telling you that your Yarn Project needs to be upgraded. To do this, follow the message’s instructions: select the project, and click Upgrade Yarn Project in the Inspector.
    • After upgrading your projects, you will need to set up your localisations again by adding them in the Yarn Project’s inspector and dragging in your strings file and asset file.
    • If your project uses any Yarn files that are not in the same folder, or subfolder, of the Yarn Project, you will need to move the Yarn files to the folder.
    • Your Yarn scripts, strings files, and localised assets will not be modified, and you won’t need to change any objects in your scenes or prefabs. The only thing that will be changed is the Yarn Project file.

• In Unity, the Unity Localization integration is now available when the Localization package is installed.

  • Prior to this change, the YARN_USE_EXPERIMENTAL_FEATURES scripting definition symbol needed to be added to the Player settings.

• You can now add a Dialogue System prefab to your scene by opening the GameObject menu and choosing Yarn Spinner -> Dialogue Runner.

• Added ‘On Dialogue Start’ event to Dialogue Runner. This event is called when the dialogue starts running.

• Methods tagged with the YarnCommand and YarnFunction attribute are now discovered at compile time, rather than at run-time. This makes game start-up significantly faster.

  • Yarn Spinner for Unity will search your source code for methods with the YarnCommand and YarnFunction attributes, and generate source code that registers these methods when the game starts up, or when you enter Play Mode in the editor.
  • This is a change from previous versions of Yarn Spinner for Unity, which searched for commands and functions at run-time, which had performance and compatibility implications on certain platforms (notably, consoles).
  • This search is done automatically in Unity 2021.2 and later. In earlier versions of Unity, you will need to manually tell Yarn Spinner for Unity to check your code, by opening the Window menu and choosing Yarn Spinner -> Update Yarn Commands.
  • In Unity 2021.2 and later, you can now see which commands have been registered using YarnCommand by opening the Window menu and choosing Yarn Spinner -> Commands…

• Under the hood, Yarn Programs now store all headers for their nodes.

  • Prior to this change, only the tags header was stored.

• DialogueReference objects can now be implicitly converted to strings.

• The YarnNode attribute can be attached to a string property to turn it into a drop-down menu for choosing nodes in a Yarn Project:

  // A reference to a Yarn Project
  public YarnProject project;
  
  // A node in ‘project’
  [YarnNode(nameof(project))]
  public string node1;
  
  // Another node in ‘project’
  [YarnNode(nameof(project))]
  public string node2;
  

• The YarnProject.GetHeaders method has been added, which fetches all headers for a node.

• The YarnProject.InitialValues property has been added, which fetches a dictionary containing the initial values for every variable in the project.

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.
• 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.
• Fixed a bug in the Language Server that caused crashes when code-completion was requested at a position more than 50% of the way through a document.
• 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.
• Fixed a compile error in the Minimal Viable Dialogue System sample in Unity 2019.
• Added code to invalidate the Program cache on awake for Yarn Projects properly. This means your Yarn Projects will be correctly compiled and referenced in the editor.
• Dialogue Runner will now report an error and stop early if you tell it to start running a node that isn’t in the provided Yarn Project.
• Dialogue Runner’s ‘On Dialogue Complete’ event will now fire when you stop it via by calling the Stop() method.
  • Calling Stop() on the Dialogue Runner will now also dismiss the LineView, OptionListView, and VoiceOverView.