Merge branch 'master' into development

.gitignore

@@ -20,6 +20,8 @@ bin/
 obj/
 *.userprefs
 
+### Visual Studio ###
+.vs/
 
 ### OSX ###
 .DS_Store
@@ -84,3 +86,4 @@ GPATH
 GRTAGS
 GTAGS
 GSYMS
+(??)

.travis.yml

@@ -27,14 +27,14 @@ addons:
 script:
 - "./antlr.sh"
 - "./build.sh -bcuv"
-#deploy:
-#  provider: releases
-#  api_key:
-#    secure: ppMWm5zS3NfplInwq+JdBBLFgTPVvpLrTeqcTdpHRBLtoiKHtfiPDVhvRKshu5qdbp+h1L0ZWTxfXdmOzYxdrXlLQkUAMFIlj7kY+hfzBcSnfA707dJapx6Q9LeJCy50JuDXEx+hPCjNAREz6+YP1Cb5FVwFoC3pu0FQ0Qg+86uUy4D3jZDMmjHIg0qN+sdwOf1xTmLJ37nuoDSpsUWx4MDMh/RP/7Uwz9lxYBw1XcWlddZzHesLj0HUuRmRSrk/4KNEQsYavH2U+vgPnRuWVITuB/Y2LqLE+pleNCt5NiqVvSHZgRTSYu4Jik7ivaNa+JuVjeAokJubRv1wUba3wlU25fUfzeBvm1bxGbF+7HofZSaaUvK28JP1e/LYR8EfwPy4L+yfasEGh5McTKjsdKKK+c8wrvR1EaPwNe7bPy0YOeHfxf2/aTR8PoEqPQdzLo2VIIMdqEvChiE7Z6X2WgPBxbGoBp5NOL3uRhE/9aAyMSIt/sYZvtSmbtxfK5qCEMP0j2cNRs0d91DaL9nsnEFYu9jrddwX68HgtWmt77MdGAYMz5vyQPQtJuKKATST3HkKDvWyoWcNgnF4xL0U0bOZZcBGilZDuvEAqSSyw7oCXTnbh0B+pCpo6NOaV4ks62klmAbaC3IPAOvajlgViB6sHsknixys/Z1VkQjI5YY=
-#  file: YarnSpinner/bin/Release/YarnSpinner.dll
-#  skip_cleanup: true
-#  on:
-#    tags: true
+deploy:
+  provider: releases
+  api_key:
+    secure: ppMWm5zS3NfplInwq+JdBBLFgTPVvpLrTeqcTdpHRBLtoiKHtfiPDVhvRKshu5qdbp+h1L0ZWTxfXdmOzYxdrXlLQkUAMFIlj7kY+hfzBcSnfA707dJapx6Q9LeJCy50JuDXEx+hPCjNAREz6+YP1Cb5FVwFoC3pu0FQ0Qg+86uUy4D3jZDMmjHIg0qN+sdwOf1xTmLJ37nuoDSpsUWx4MDMh/RP/7Uwz9lxYBw1XcWlddZzHesLj0HUuRmRSrk/4KNEQsYavH2U+vgPnRuWVITuB/Y2LqLE+pleNCt5NiqVvSHZgRTSYu4Jik7ivaNa+JuVjeAokJubRv1wUba3wlU25fUfzeBvm1bxGbF+7HofZSaaUvK28JP1e/LYR8EfwPy4L+yfasEGh5McTKjsdKKK+c8wrvR1EaPwNe7bPy0YOeHfxf2/aTR8PoEqPQdzLo2VIIMdqEvChiE7Z6X2WgPBxbGoBp5NOL3uRhE/9aAyMSIt/sYZvtSmbtxfK5qCEMP0j2cNRs0d91DaL9nsnEFYu9jrddwX68HgtWmt77MdGAYMz5vyQPQtJuKKATST3HkKDvWyoWcNgnF4xL0U0bOZZcBGilZDuvEAqSSyw7oCXTnbh0B+pCpo6NOaV4ks62klmAbaC3IPAOvajlgViB6sHsknixys/Z1VkQjI5YY=
+  file: "$TRAVIS_BUILD_DIR/YarnSpinner/bin/Release/YarnSpinner.dll"
+  skip_cleanup: true
+  on:
+      tags: true
 after_success:
 - cd $TRAVIS_BUILD_DIR
 - chmod +x DeployDocumentation.sh

Documentation/Doxyfile

@@ -790,7 +790,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = README.md LICENSE.md Documentation/YarnSpinner-Programming Unity YarnSpinner YarnSpinnerConsole YarnSpinnerTests
+(??)
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

Documentation/YarnSpinner-Dialogue/Localization.md

@@ -0,0 +1,20 @@
+# LOCALIZATION
+Yarn Spinner provides tools to help convert your game in to any language you like. This is achieved by usage of the [YarnSpinnerConsole](../YarnSpinnerConsole) tool. At the moment, this tool is not available standalone and needs to be [built from source](../YarnSpinner-Programming/Building.md).
+
+## Localisation procedure
+
+1. We first use the tool to place unique **taglines** on each line of text that the end user will see. To do this, we execute the tool with the **taglines** command, eg:  `YarnSpinnerConsole.exe taglines MyYarnFile.yarn.txt`.
+
+2. Next, we use the tool to generate a file of strings (**genstrings**) in '[comma separated value](https://en.wikipedia.org/wiki/Comma-separated_values)' (csv) format. `YarnSpinnerConsole.exe genstrings MyYarnFile.yarn.txt` will generate a file, (in this example MyYarnFIle.yarn_lines.csv), that can then distributed to translators. It is recommended that this file first be renamed using a language identifier before distribution, eg
+    ```
+    MyYarnFIle.yarn_lines.enAU.csv
+    MyYarnFIle.yarn_lines.ptTL.csv
+    ```
+3. When the file is returned from translators, we then use Yarn Spinner's DialogueRunner inside Unity to set String Groups for the required language.
+<!-- Placeholder for image of DialogueRunner -->
+## Footnotes
+* While not essential that all files follow a standard, but highly recommended that consistency of format be used across all localisation files within a project eg [ISO-15897](https://www.iso.org/obp/ui/#iso:std:iso-iec:15897:ed-2:v1:en)
+* Originally, Yarn Spinner used .json format. The Yarn Spinner Console can convert this json format to the new improved text format: `YarnSpinnerConsole.exe convert --yarn Ship.json`
+* Command reference is available for YarnSpinnerConsole.exe by either running it with no arguments or by utilising the help command (`YarnSpinnerConsole.exe help`). Help for each command is available by using 'help command' (eg `YarnSpinnderConsole.exe help compile`)
+
+

Documentation/YarnSpinner-Dialogue/README.md

@@ -1,4 +1,4 @@
-# Yarn Dialogue - README
+# Writing Yarn Dialogue - README
 
 ## Introducing Yarn Dialogue
 

Documentation/YarnSpinner-Dialogue/Yarn-HowTo-Write-Dialogue-Complex-Example.md

@@ -0,0 +1,133 @@
+# Yarn for Writers
+
+This document talks about how to use Yarn if you're using it to write content. It doesn't talk about how to integrate Yarn Spinner into your project; for that, see ["Using Yarn Spinner in your Unity game"](../YarnSpinner-Unity).
+
+## Lines
+
+Yarn lets you define multiple chunks of dialogue that are linked together. Each chunk is called a *node*.
+
+Nodes are filled with different kinds of text. The simplest is lines of dialogue, which look like this:
+
+	Alice: Hey, I'm a character speaking in a dialogue!
+	Bob: Wild!
+
+Each line is delivered to your game one at a time.
+
+## Options
+
+To link a node to another node, you provide *options*. Options look like this:
+
+	[[Go to the woods|GoToWoods]]
+	[[Go back to the city|GoToCity]]
+
+Options have two parts: the label, which is shown to the user, and the name of the node that we should link to when the user selects the option. The label and the node name are separated by a vertical bar (`|`).
+
+You don't have to provide the label. Instead, you can just provide the node name, like so:
+
+	[[GoToCity]]
+
+If an option has no label, Yarn will automatically jump to that node when that line is run, and it won't show options to the player.
+
+When all of the lines in a node have been displayed, the dialogue system gives your game the list of available options. You then let the user choose an option, and then continue loading lines of dialogue, one at a time.
+
+If there are no options when we reach the end of a node, then we've reached the end of a conversation, and Yarn Spinner will let your game know.
+
+## Shortcut Options
+
+Sometimes, you'll want to add little branches to your conversation, but you don't want to create separate nodes for them. Instead, you can use *shortcut options*:
+
+	Mae: What did you say to her?
+	-> Nothing.
+		Mae: Oh, man. Maybe you should have.
+	-> That she was an idiot.
+		Mae: Hah! I bet that pissed her off.
+	Mae: Anyway, I'd better get going.
+
+When this is run, Yarn Spinner will behave just as if you'd broken all of this up into multiple nodes.
+
+You can also attach conditions to shortcut options, which will make them only appear if a certain condition passes:
+
+	Bob: What would you like?
+	-> A burger. <<if $money >= 5>>
+		Bob: Nice. Enjoy!
+	-> A soda. <<if $money >= 2>>
+		Bob: Yum!
+	-> Nothing.
+	Bob: Thanks for coming!
+
+Note that in the last example, there wasn't any attached text. If the player selected the last option ("Nothing."), then the next line to appear would be "Bob: Thanks for coming!"
+
+You can also nest these shortcut options, if you like. Be careful, though - too much nested options can make your text difficult to read.
+
+## Commands
+
+In addition to showing lines of dialogue, your game will probably want to run actions - things like "move the camera to position X", or "make character start smiling". You can use commands for this.
+
+Commands look like this:
+
+	<<move alice to under_bridge>>
+
+Any text inside the double-chevrons will be sent directly to your game as a string. It's up to you to decide what to do with that string.
+
+Yarn has a special command, called `stop`. If you include `<<stop>>` in your node, Yarn will stop the entire conversation when it reaches it.
+
+## Variables and If statements
+
+You can store numbers in variables. To do this, use the `set` command:
+
+	<<set $door_unlocked to 1>>
+
+You can check the value of a variable using the `if` command:
+
+	<<if $door_unlocked is 1>>
+		The door is unlocked! (This will only appear if $door_unlocked is equal to 1.)
+	<<endif>>
+
+## Expressions
+
+You can do math in an `if` command. For example:
+
+	<<if $number_of_stars_collected > 5>>
+		You have more than 5 stars!
+	<<endif>>
+
+You can also get fancier, and do stuff like this:
+
+	<<if $hostages_saved == $number_of_hostages and $time_remaining > 0>>
+		You win the game!
+	<<elseif $hostages_saved < $number_of_hostages and $time_remaining > 0>>
+		You need to rescue more hostages!
+	<<elseif $bomb_has_exploded == 0>>
+		You failed to rescue the hostages before time ran out!
+	<<endif>>
+
+## Types
+
+There are four different types of value in Yarn: strings, numbers, booleans, and `null`.
+
+* Strings contain text.
+* Numbers are floating-point numbers.
+* Booleans are either true or false.
+* `null` means no value.
+
+Yarn will automatically convert between types for you. For example:
+
+	<<if "hi" == "hi">>
+		The two strings are the same!
+	<<endif>>
+
+	<<if 1+1+"hi" == "2hi">>
+		Strings get joined together with other values!
+	<<endif>>
+
+**Warning:** Currently, variables can only store numbers. If you try to store anything else in a variable, it will get converted to a number first.
+
+## Functions
+
+You can call functions in your `if` commands. For example, Yarn Spinner provides a function called `visited`, which you can use to find out if a node has been entered before or not. It takes a single parameter (which is a string), and returns true or false depending on whether or not the node you specified has been entered.
+
+	<<if visited("GoToCity")>>
+		We have gone to the city before!
+	<<endif>>
+
+You can't define your own functions inside Yarn itself, but they can be added at run-time. See ["Extending Yarn Spinner"](Extending.md) for more info.