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!