v1.0.1

A bugfix release for v1.0. Thanks to everyone who's downloaded Yarn Spinner 1.0 so far!

Please consider supporting Yarn Spinner's development by becoming a patron!

Changed

• Fixed an issue where the first instruction after an if statement, option, shortcut option or jump to another node could be skipped.

v1.0.0

This is the first major release of Yarn Spinner. We're thrilled to bring this to you, and want to thank everyone who's helped us bring Yarn Spinner to this point.

To help support Yarn Spinner's development, we've launched a Patreon. Please consider becoming a patron!

Added

• Binary Program Format: Yarn programs are now compiled into a binary format, which uses Protocol Buffers. Compiled files can be written to disk and loaded at runtime, which means that you don't need to include the source code of your game's dialog when distributing it to players. The time needed to load a dialogue file is also significantly reduced, because compilation happens on your machine, not on the player's.
• Canvas Prefab: The Dialogue prefab, which you can find in the YarnSpinner/Prefabs folder, is a drag-and-drop object that you can add to your scene. It's a great way to get started using Yarn Spinner in your own game, and is designed to be customised to fit your needs.

• Dialogue UI Events: The DialogueUI class now fires Unity Events when important events occur, like dialogue starting, a line appearing, a line's delivery completing, and more. You can use this to control the behaviour of your dialogue UI without writing any code.

• Automatic Compilation in Unity: The Unity integration for Yarn Spinner will automatically detect your Yarn files and compile them.

• Instant Localisation Tags: Select the Yarn file in Unity, and click Add Line Tags. Any lines or options that don't have a localisation tag will have one added. (Note that this step changes your files on disk, and can't be undone.)

• Simpler CSV Export: When you want to export a CSV file containing your localised lines, select the Yarn file in Unity, choose the language you want to localise into from the drop-down menu, and click Create New Localisation. A .csv file will be created next to your Yarn file, ready to be sent to your translators. (Note that you can only create a CSV when every line and option in the file has a line tag. Yarn Spinner in Unity can create them for you if you click Add Line Tags.)

• Visual Studio Code Extension: We've heard from people who want to write their Yarn code in a text editor, and we've created an extension for Visual Studio Code that adds syntax highlighting support (with more features coming in the future!) You can install the extension from the Visual Studio Code Marketplace.

• New Website: A brand-new website for Yarn Spinner is now available at yarnspinner.dev. This will be the home of all future documentation.

Changed

• The standard file extension for Yarn codes has changed from .yarn.txt to .yarn. The Yarn Editor has been updated to save as .yarn by default. (It still supports opening your existing .yarn.txt files.)
• The Dialogue class, which executes your Yarn program, previously sent the text of the lines and options found in the source code. This has now changed; the Dialogue will now instead send just the line code, and it's up to your game to match that to a localised line.
• If a line doesn't have a line code, Yarn Spinner will create a unique one based on the name of the file, the name of the node, and where the line appears.
• The Compiler class's CompileFile and CompileString methods, which compile .yarn files into Yarn programs, have had their method signatures change. They now return a Yarn.Compiler.Status enum, and produce two results: the compiled Yarn program, and the extracted string table as a dictionary.
• The compiler has been moved into its own assembly, Yarn.Compiler.dll. If your code doesn't use any of the classes in the Yarn.Compiler namespace, it won't be included. This reduces the amount of code you need to include in your game.
• The Yarn.Unity.Example classes, like ExampleDialogUI, have been renamed to remove "Example". Everyone was using these as the basis for their own classes anyway, and we felt it was better to acknowledge that they weren't really showing one way to do it, but rather showing the preferred way. This name change acknowledges this fact.
• DialogueRunner now no longer relies on coroutines for operations that take longer than a single frame. Instead, DialogueUI's methods that run in response to lines, options and commands return a Dialogue.HandlerExecutionType enum to indicate to Yarn Spinner whether it should pause execution or continue running.
• DialogueRunner now separates out the act of loading compiled programs and the act of loading a string table into two distinct methods. This gives you control over which localised lines of text should be used when the Dialogue class sends line codes to your game.

Removed

• We've removed the "simple dialog example" from the repo, and made the "complex dialog example" - the one set in space, featuring Sally and the Ship - the sole example.
• We've removed the documentation from the repo; the new home for Yarn Spinner documentation is the official website, yarnspinner.dev.

v0.9.12

This is the final version of 0.9. Future versions of Yarn Spinner will change the API.

Use this version if you've got an existing project that's using Yarn Spinner, and can't upgrade to the new version.

In this release:

• Removed support for storing Yarn scripts as JSON. This allows us to remove Newtonsoft.JSON as a dependency, which was causing issues for consoles and mobile platforms.
• Minor code tidy-up in preparation for version 1.0.

v0.9.11

This is a bug-fix release that contains a number of community contributions. Thanks to everyone who helped!

v0.9.10.2

Version v0.9.10.2 includes several enhancements and bug-fixes.
Some highlights include:

• We now automatically generate documentation. You can find it at: http://thesecretlab.github.io/YarnSpinner/html/
• A new experimental ANTLR-based parser is being worked on. You can enable it by setting experimentalMode on your Dialogue object to true.
• We now support the new .yarn.txt format, which is much more easy to diff. The Yarn editor can save this format.

v0.9.9

Yarn Spinner v0.9.9 comes with several new, large features.

Automatic Commands in Unity

If you add a YarnCommand attribute to any method on any script attached to an object, Yarn Spinner will now automatically call it for you when it encounters a command.

For example, say you've got a game object in your scene called "Sally", and this object has the following script component attached to it:

public class MoveToPoint : MonoBehaviour {

    [YarnCommand("move")]
    public void Move(string destination) {            
        // start walking towards 'destination'
    }
}

And you've also got a Yarn script that looks like this:

Sally: Where did I put that fuel tank?
<<move Sally fuelTank>>
Sally: Ah, here it is.

When the script hits the command, the Move method on Sally's MoveToPoint script will be called, with the parameter "fuelTank".

Yarn Spinner will automatically dispatch a comand like this when all of the following are true:

• The command has at least two words
• The second word is the name of a game object in the scene ("Sally", in the earlier example)
• The game object has a script that contains a method with the YarnCommand attribute, and that attribute's parameter is the same as the first word ("move", in the earlier example).
• The method with this attribution only takes strings as parameters.

If Yarn Spinner can't dispatch a command automatically, your code will instead receive the full text of the command, as before.

Variables can now be different types

Previously, variables could only store numbers. Now, they can store any of the following types:

• Numbers
• Strings
• Booleans (i.e. true or false)
• Null (i.e. no value)

These are represented as Yarn.Value objects, which represent a single "value" that Yarn can know about.

To support this, your VariableStorageBehaviour subclass should now implement GetValue and SetValue, instead of GetNumber and SetNumber.

Important: For compatibility, we provide default implementations of GetValue and SetValue that simply call the older, obsolete GetNumber and SetNumber. This means that your projects will continue to work without you doing anything. However, this will change in a future version of Yarn Spinner. You should update your code to use GetValue and SetValue as soon as possible. The Yarn Spinner editor window in Unity will warn you if your variable storage classes still implement the old methods.

This feature is thanks to @konistehrad, who is an excellent person.

Floating point numbers

You can now use floating point numbers in Yarn:

<<set $one_half to (1 / 2 == 0.5)>>

<<if (0.1 + 0.1 == 0.2)>>
    Math works!
<<endif>>

Unused variable checker

The Yarn Spinner editor window in Unity (choose Window->Yarn Spinner to see it) will now show you if there are any variables that you're reading from but never assigning a value to, or are assigning a value to but not reading from. This usually happens when you make a typo:

New lexer

The lexer is a part of the compiler that converts the raw text of your Yarn scripts into a collection of tokens - individual elements of Yarn's syntax, like parentheses, <<, and numbers. This has now been replaced with a better-designed one, based on the lessons that were learned from the older implementation; the new one is much easier to extend and expand.

You shouldn't see any difference between the old version and the new version, but if you encounter any problems in your scripts that you weren't encountering in the previous version, please log an issue.

v0.9.8

Yarn Editor Window

Yarn Spinner now adds an editor window to Unity, which gives you tools for managing with your Yarn Scripts.

You can access the window by opening the Window menu and choosing Yarn Spinner, or by pressing Control-Shift-Y (Command-Shift-Y on Macs).

In this release, the Yarn Spinner editor window shows a list of all JSON files in your project, and shows you any parse errors that were encountered.

This window is brand new, and very much in beta. Please log issues if you have any problems.

Other changes:

• Added NodeComplete processing to DialogueRunner, and exposed NodeCompleteResult to clients. When the end of a dialogue node is reached, your DialogueUIBehaviour will receive the NodeComplete method call. (pull request #31 - thanks to @thebeardphantom!)
• Add a null check in Dialogue.Stop (fixes #29)
• Support colons in identifiers. (fixes #28)

v0.9.7.2

This is a quick bugfix release for 0.9.7, which was supposed to include a fix an issue caused by indenting an if statement further than its endif or else. This release actually does that. Whoops.

All the other goodness that's in 0.9.7 is still there and valid. Go wild!

v0.9.7

Note: there's a bug in this release! Go get v0.9.7.2 instead!

• Source Packages Now Available: Starting with this build, source code packages are now available. If you prefer to work with the source code instead of a compiled DLL, grab the source code package attached to this release.
• Fix a bug that caused parse errors if an if statement's endif or else was less indented than the initial if.
• Added a command line flag to only do a parse stage, which is useful for testing.
• Correctly set the line number for EndOfInput tokens, making certain error messages more useful.
• Parse errors will now show the filename and node that contained the error.
• The locations of labels in nodes are now cached.
• Attempting to load the same node twice should now fail.
• Better automated testing.

v0.9.6

• Update example project's Unity version from 5.3.2f1 to 5.3.3f1
• New scripts to automate the creation of .unitypackage files.
• Compilation now happens when files are loaded. The Compile() method in Dialogue is now obsolete.
• The string table now stores keys as strings, not ints. This is to help with localisation later.
• Shuffle options better. In particular, pairs of options should now shuffle properly. Fixes #22.
• No longer tries to show options when no options have been added [fixes #21].
• Commands can now begin with words that are similar to keywords like 'to', 'and', 'null', etc (fixes #20)
• Nodes tagged 'rawText' can have their source code accessed via the Dialogue class's GetTextForNode() [closes #18]
• Add a way to query the currently running node. Closes #19
• Attempting to continue a Dialogue that is waiting for an option to be selected now interrupts all execution.
• [[NodeName]] now immediately jumps to a node, rather than using the 'options' system.
• Handle the case of starting with a nonexistent node better.