Skip to content

v3.3.2

Latest

Choose a tag to compare

@github-actions github-actions released this 17 Nov 04:43

Yarn Spinner is made possible by your generous patronage. Please consider supporting Yarn Spinner's development by becoming a patron, or by buying a copy of Yarn Spinner on itch.io or the Unity Asset Store!

👩‍🚒 Getting Help

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

📦 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 v3.3.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#v3.3.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

Version 3.3 is a significant update to two main areas of Yarn Spinner for Unity:

  • Async everywhere: The DialogueRunner now uses async methods across much more of its API.
  • Async functions: Functions can now return an awaitable type, and can take as long as they need to return a value. The dialogue runner will pause until the function returns.
  • Cancellable commands and functions: If the last parameter of a command or function's method is CancellationToken or a LineCancellationToken, Yarn Spinner will provide it with a token that becomes cancelled when the command or function should return early.
  • Dialogue Presenter methods are now virtual: Previously, when you were implementing a custom dialogue presenter, you had to implement every single method, even if they did nothing. Now, you can implement just the ones that are relevant to you. (We'll take care of doing all of the nothing for you.)
  • Commands and functions can now take custom objects as parameters: To use a custom object as a parameter, create a static public method that returns bool and takes two parameters: a string, and an out parameter of your custom object's type. Add the YarnConverter attribute to this method, and Yarn Spinner will invoke it to convert from strings to your object's type.
    public class Tool {
      public string Name { get; set; }
      public int Durability { get; set; }
    }
    
    [YarnConverter(typeof(Tool))]
    public static bool TryGetTool(string input, out Tool value)
    {  
      value = /* use 'input' to get a Tool instance */ ;
    
      return true;
    }
    
    [YarnCommand("dig")]
    public static void Dig(Tool tool)
    {
        Debug.Log($"I am digging a hole with {tool.Name}!");
        tool.Durability--;
    }
  • Definitions files are stored relative to the project root: Previously, references to the .ysls.json files that .yarnprojects use to identify commands and functions were stored as a relative path to the file, which was brittle and caused breakages if the project file moved. They're now stored as paths relative to the root of the project, which won't change when the Yarn Project moves.
  • Using lambdas for commands and functions is now deprecated: Using a lambda when registering a command or function at runtime is now deprecated, because it's slower, can lead to unintended bugs, and isn't automatically cleaned up.
  • Undeclared functions are now errors: If your Yarn script makes use of functions that the compiler doesn't know about, it will result in an error.
    • In order to assist with the migration from previous versions of Yarn Spinner, if your .yarnproject file was created by a previous version, undeclared functions will result in a warning and will prompt you to upgrade your project. Note that not all features from Yarn Spinner v3.3 may be available until you upgrade your project file.

Check out the new docs website for v3.3!

Added

  • Added filtering in [YarnNode] dropdowns (thanks to Shane Marks!).
    • You can now limit which nodes appear in the Inspector by specifying a filter string in YarnNode-attributed strings.
    • To filter the list, provide a filter parameter on your [YarnNode] attribute:
      public YarnProject project;
      
      // Only show nodes in 'project' whose title contains 'Start'
      [YarnNode(nameof(project), filter: "Start")]
      public string node;
    • You can customise how the filtering is done by providing a filterType:
      // Only show nodes whose titles contain "Start" (this is the default)
      [YarnNode(nameof(project), filterType: YarnNodeFilter.Contains, filter: "Start")]
      
      // Only show nodes whose titles start with "Entry"
      [YarnNode(nameof(project), filterType: YarnNodeFilter.StartsWith, filter: "Entry")]
      
      // Only show nodes whose titles end with "Entry"
      [YarnNode(nameof(project), filterType: YarnNodeFilter.EndsWith, filter: "Entry")]
      
      // Only show nodes whose titles match the regular expression "Test[0-9]+"
      [YarnNode(nameof(project), filterType: YarnNodeFilter.MatchesRegex, filter: "Test[0-9]+")]
    • You can customise which header to filter on. By default, nodes will be filtered based on their title, but you can specify most other headers, including tags, cluster or your own custom headers.
      // Only show nodes whose colour in the editor is red
      [YarnNode(nameof(project), filterHeader: "color", filter: "red")]
    • Filtering is case-insensitive for all filter types except YarnNodeFilter.MatchesRegex.

Changed

  • Paths in generated YSLS files now use a consistent path separator (the forward slash /), independent of the current operating system.
  • YarnNode and DialogueReference now sort their nodes alphabetically.
  • IRequestNextLine has been replaced with IContentSource.