Repository navigation
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.
- Join the Yarn Spinner Discord.
- Talk to us via BlueSky or Mastodon
- 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 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
DialogueRunnernow 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
CancellationTokenor aLineCancellationToken, 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
outparameter of your custom object's type. Add theYarnConverterattribute 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.jsonfiles 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
.yarnprojectfile 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.
- In order to assist with the migration from previous versions of Yarn Spinner, if your
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
filterparameter 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, includingtags,clusteror 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.
- You can now limit which nodes appear in the Inspector by specifying a filter string in
Changed
- Paths in generated YSLS files now use a consistent path separator (the forward slash
/), independent of the current operating system. YarnNodeandDialogueReferencenow sort their nodes alphabetically.IRequestNextLinehas been replaced withIContentSource.
