Starting on 2.17 docs

docs/2.17/Alternatives.md

@@ -0,0 +1,11 @@
+# Alternatives
+
+ 
+
+Chatterbox might not be the perfect fit for your game. The GameMaker community has produced other solutions that you might like to try:
+
+- [FriendlyCosmonaut's dialogue system](https://friendlycosmonaut.itch.io/dialoguesystem)
+
+- [Quack](https://marketplace.yoyogames.com/assets/8789/quack-dialogue-system)
+
+- [gmdialogue](https://github.com/danielpancake/gmdialogue)

docs/2.17/README.md

@@ -0,0 +1,66 @@
+<img src="https://raw.githubusercontent.com/JujuAdams/Chatterbox/master/LOGO.png" width="50%" style="display: block; margin: auto;" />
+<h1 align="center">2.16</h1>
+<p align="center">Narrative engine for GameMaker 2022 LTS by <a href="https://www.jujuadams.com/" target="_blank">Juju Adams</a></p>
+
+<p align="center"><a href="https://github.com/JujuAdams/chatterbox/releases/" target="_blank">Download the .yymps</a></p>
+<p align="center">Download the <a href="https://github.com/FaultyFunctions/YarnEditor/" target="_blank">visual editor</a> by <a href="https://twitter.com/FaultyFunctions" target="_blank">Faulty</a></p>
+
+---
+
+Chatterbox is a GameMaker implementation of the [Yarn language](https://yarnspinner.dev/), used in games such as [Far From Noise](https://www.georgebatchelor.com/farfromnoise), [Knights and Bikes](https://foamswordgames.com/#knights), and [Night In The Woods](http://www.nightinthewoods.com/).
+
+Yarn is designed to be accessible to writers who have little or no programming knowledge. It makes no assumptions about how your game presents dialogue to the player, or about how the player chooses their responses. Yarn has lots of [thorough documentation](https://yarnspinner.dev/docs/tutorial).
+
+Syntax and features specific to Chatterbox [can be found here](concept-yarn-script). Chatterbox attempts to be a full implementation of the Yarn specification; if there's anything missing, please [create an Issue](https://github.com/JujuAdams/Chatterbox/issues) and Juju will do his best to meet your request.
+
+Yarn files can be written by hand, but the best way to start with Yarn is to use an editor. The best editor to use with YarnScript v2 is [Crochet](https://github.com/FaultyFunctions/Crochet), available on [Windows, MacOS, & Ubuntu](https://github.com/FaultyFunctions/Crochet/releases), or as a [web-based editor](https://faultyfunctions.github.io/Crochet/).
+
+## Features
+
+-   **Powerful**<br>
+    Yarn is node-based, with each node containing dialogue and options as you'd expect. But the real power to bring life to your stories is found in Yarn's [in-line commands](concept-yarn-script#actions). These can be used at any point to execute GML functions from specific points in your text, triggering cutscenes or animating faces or playing sound effects.<br>
+
+-   **Familiarity**<br>
+    Yarn looks similar to [Twine](https://twinery.org/) in many ways, but avoids the trappings of that tool. There's no [debating what version to use](https://www.reddit.com/r/twinegames/comments/eic3na/which_version_should_i_start_with/) or what particular standard is best like with Twine - Yarn has a single standard. The [visual editor](https://faultyfunctions.github.io/Crochet/) should feel comfortable for anyone who's worked in narrative design before.
+
+-   **Tools**<br>
+    Chatterbox is designed to be easy to implement and easy to make games with. [YarnScript](concept-yarn-script) can be written by hand or, more commonly, an editor is used to write your stories. There's a [web editor](https://faultyfunctions.github.io/Crochet/) as well as [Windows, MacOS, & Ubuntu](https://github.com/FaultyFunctions/Crochet/releases) binaries. Chatterbox loads in Yarn files straight from your [Included Files](https://manual.yoyogames.com/Settings/Included_Files.htm) with a [single command](reference-configuration#chatterboxloadfromfilefilename-aliasname) without any other setup.
+
+-   **Community**<br>
+    Yarn has a thriving community of narrative designers. The maintainers of Yarn run a [Slack group](http://lab.to/narrativegamedev) & [Discord server](https://discord.gg/yarnspinner), and [YarnSpinner](https://github.com/YarnSpinnerTool/) and [Crochet](https://faultyfunctions.github.io/Crochet/) (community maintained editor for Yarn v2) are constantly being updated.
+
+?> For a full explanation of Yarn's features and syntax, please read the [YarnScript](concept-yarn-script) page.
+
+## Updating
+
+Releases go out once in while, typically expedited if there is a serious bug. This library uses [semantic versioning](https://semver.org/). In short, if the left-most number in the version is increased then this is a "major version increase". Major version increases introduce breaking changes and you'll almost certainly have to rewrite some code. However, if the middle or right-most number in the version is increased then you probably won't have to rewrite any code. For example, moving from `1.1.0` to `2.0.0` is a major version increase but moving from `1.1.0` to `1.2.0` isn't.
+
+?> Please always read patch notes. Very occasionally a minor breaking change in an obscure feature may be introduced by a minor version increase.
+
+At any rate, the process to update is as follows:
+
+1. **Back up your whole project using source control!**
+2. Back up the contents of your configuration script (`__ChatterboxConfig` or `__ChatterboxConfigMacros` depending on the version) within your project. Duplicating the script is sufficient
+3. Delete all library scripts from your project. Unless you've moved things around, this means deleting the library folder from the asset browser
+4. Import the latest [.yymps](https://github.com/JujuAdams/chatterbox/releases/)
+5. Restore your configuration script from the back-up line by line
+
+!> Because configuration macros might be added or removed between versions, it's important to restore your configuration script carefully.
+
+## About & Support
+
+If you'd like to report a bug or suggest a feature, please use the repo's [Issues page](https://github.com/JujuAdams/chatterbox/issues). Chatterbox is constantly being maintained and upgraded; bugs are usually addressed within a few days of being reported.
+
+Chatterbox is supported for all GameMaker export modules, apart from HTML5. You might run into edge cases on platforms that I haven't tested; please [report any bugs](https://github.com/JujuAdams/chatterbox/issues) if and when you find them.
+
+---
+
+Chatterbox is built and maintained by [Juju Adams](https://www.jujuadams.com/) who has a long history of fiddling with text engines. Juju's worked on a lot of [commercial GameMaker games](http://www.jujuadams.com/); Chatterbox is the product of experience writing a custom narrative scripting language for [Retrace](https://store.steampowered.com/app/1052640/Retrace/) and tooling for another major GameMaker title, as yet unreleased.
+
+Additional contributions have been made by [squircledev](https://github.com/squircledev) and [Faulty](https://github.com/FaultyFunctions). A big thank you to Els White, Jukio Kallio, rIKmAN, and squircledev for helping to test this library.
+
+Chatterbox will never truly be finished because contributions and suggestions from new users are always welcome. Chatterbox wouldn't be the same without [your](https://tenor.com/search/whos-awesome-gifs) input! Make a suggestion on the repo's [Issues page](https://github.com/JujuAdams/chatterbox/issues) if you'd like a feature to be added.
+
+## License
+
+Chatterbox is licensed under the [MIT License](https://github.com/JujuAdams/Chatterbox/blob/master/LICENSE).

docs/2.17/_sidebar.md

@@ -0,0 +1,27 @@
+-   [Introduction](README)
+-   [Alternatives](Alternatives)
+-   [Getting Started](getting-started)
+-   [Spider Lily's Tutorial](https://spiderlilystudios.medium.com/clickable-choices-in-gms2-using-chatterbox-and-scribble-0ed81dfe16a5)
+
+---
+
+**Concepts**
+
+-   [YarnScript](concept-yarn-script)
+-   [Source Files](concept-source-files)
+-   [Chatterboxes](concept-chatterboxes)
+-   [Metadata and Speakers](concept-metadata-and-speakers)
+-   [Actions and Functions](concept-actions-functions)
+
+---
+
+**API Reference**
+
+-   [Configuration](reference-configuration)
+-   [Setup](reference-setup)
+-   [Chatterboxes](reference-chatterboxes)
+-   [Content Getters](reference-content-getters)
+-   [Option Getters](reference-option-getters)
+-   [Flow Control](reference-flow)
+-   [Variables and Constants](reference-variables)
+-   [Localisation](reference-localisation)

docs/2.17/concept-actions-functions.md

@@ -0,0 +1,234 @@
+# Actions and Functions
+
+YarnScript allows for flow control and the execution of external code by using its "action" syntax. Actions in YarnScript are commands written in between `<<` and `>>` like so:
+
+```yaml
+title: FlowerSeedShelf
+---
+
+<<declare $flowerSeeds as 0>>
+<<const $maximumFlowerSeeds as 3>>
+
+You see upon the shelf a selection of packets of flower seeds arranged clumsily.
+-> Inspect them.
+    Their attractive full-colour printing is rather eye-catching. Their names are unfamiliar to you, as though the words were made of jumbled syllables.
+-> Pick one at random.
+    <<if $flowerSeeds >= $maximumFlowerSeeds>>
+        You pick up a packet but another in your hands slips through your fingers. You're holding as many flower seeds as you can.
+    <<else>>
+        <<set $flowerSeeds to $flowerSeeds + 1>>
+        You thrust your hand into the pile of seed packets and choose by feel... though they all feel the same to you.
+    <<endif>>
+-> Move down the aisle. You don't trust yourself to grow flowers anyway.
+    <<jump DownTheAisle>>
+
+//Replay this node until the player chooses to move down the aisle
+<<jump FlowerSeedShelf>>
+===
+```
+
+&nbsp;
+
+Chatterbox has the following in-built actions:
+
+### `jump`
+
+*Example:* `<<jump TheNodeOnTheHill>>`
+
+*Example*: `<<jump Christina.yarn:GenericGreeting>>`
+
+*Example*: `<<jump $nodeTitleStoredInAVariable>>`
+
+The `<<jump>>` action causes a chatterbox to immediately swap execution to another node in a YarnScript file. Execution will start from the top of the new node. If you `<<jump>>` back to the old node then you will start execution from the top of the node. You can specify a particular YarnScript file to jump to by specifying the filename first, typing a `:` colon, and then specifying the node in that file. If you don't specify a file then Chatterbox will search in the current file for the desired node. `<<jump>>` can be used to jump to a node stored in a variable by referencing the variable as the destination node title.
+
+&nbsp;
+
+### `hop` and `hopback`
+
+*Example:* `<<hop WistfulMemories>>` and later `<<hopback>>`
+
+*Example:* `<<hop TangentialConversations.yarn:NatureOfBeing>>` and later `<<hopback>>`
+
+*Example*: `<<hop $nodeTitleStoredInAVariable>>` and later `<<hopback>>`
+
+
+`<<hop>>` operates similarly to `<<jump>>` (see above). `<<hop>>` differs from `<<jump>>` insofar as you can hop back into a node from where you hopped out. This operates on a stack such that calling `<<hop>>` twice and then calling `<<hopback>>` twice will result in a chatterbox being at the exact same position that the first `<<hop>>` was called.
+
+!> It is not possible to save or load the hop stack. Do not rely on the hop stack for tracking important game logic that may need to persist between game sessions.
+
+&nbsp;
+
+### `declare`
+
+*Example:* `<<declare $favouriteFood = "Cheesecake">>`
+
+*Example:* `<<declare $favouriteFood as "Cheesecake">>`
+
+This action instructs Chatterbox to declare a variable and to give it a default value.
+
+&nbsp;
+
+### `set`
+
+*Example:* `<<set $favouriteFood = "Curry">>`
+
+*Example:* `<<set $favouriteFood as "Curry">>`
+
+Sets the value of a variable, plain and simple. The datatype of a variable (string, number, or boolean `true`/`false`) cannot change.
+
+&nbsp;
+
+### `const`
+
+*Example:* `<<const $favouriteFood as "Crisps">>`
+
+The `<<const>>` action defines a special kind of variable - it is a variable whose value cannot be changed. This might seem contradictory at first glace - a variable must surely be able to vary?! - but this behaviour is very helpful when trying to keep track of so-called "magic numbers" in your game. For example, you might want to set the maximum number of health points that a player can have. At some point in development, that number might need to go up or down in order to balance the game's difficulty. Using a constant means that you can tweak the maximum number of health points throughout the game without having to find and adjust every single occurrence of a special number (a time-consuming endeavour that is likely to result in bugs).
+
+&nbsp;
+
+### `wait`
+
+*Example:* `<<wait>>`
+
+`<<wait>>` will put a chatterbox into a "waiting" state. This is used to break up sections of dialogue in non-singleton mode. You can tell a chatterbox to "un-wait" by calling `ChatterboxContinue()`.
+
+?> In singleton mode this action does nothing because `<<wait>>` is implicitly and automatically called after every line of dialogue (so long as that dialogue isn't followed immediately by an `->` option).
+
+?> `<<wait>>` is analogous to the `ChatterboxWait()` function.
+
+&nbsp;
+
+### `stop`
+
+*Example:* `<<stop>>`
+
+Tells a chatterbox to stop processing entirely. The chatterbox can be restarted by calling `ChatterboxJump()`.
+
+?> `<<stop>>` is analogous to the `ChatterboxStop()` function.
+
+&nbsp;
+
+### `if`, `else` etc.
+
+Branching logic is also written in between `<<` and `>>` too, such as `<<if visited("Home") == 4>>`. These are used to selectively execute parts of your YarnScript but aren't considered "actions" per se.
+
+&nbsp;
+
+## Functions
+
+Chatterbox contains one native function: `visited("NodeTitle")`. This function returns the number of times that a particular node has been visited. You can specifiy a node in a particular file by You can specifying the filename first, typing a `:` colon, and then specifying the node in that file. If you don't specify a file then Chatterbox will search in the current file for the desired node.
+
+Powerful custom functions can be added to Chatterbox using the [`ChatterboxAddFunction()`](reference-configuration#chatterboxaddfunctionname-function) function. This is a global function and you only need to call it once per custom function. Custom functions can do anything that GML can do... because they're written in GML!
+
+!> Custom functions must be defined before calling [`ChatterboxCreate()`](reference-chatterboxes#chatterboxcreatefilename-singletontext-localscope).
+
+Custom functions can have parameters. Parameters should be separated by spaces and are passed into a script as an array of values in `argument0`. Custom functions can return values, and like Chatterbox variables, a function must return a number, a string, or a boolean `true` / `false`. A function can also return nothing (`undefined`).
+
+?> You can use the `CHATTERBOX_CURRENT` read-only macro to get the chatterbox that is currently being processed. This is helpful when using `ChatterboxJump()` etc.
+
+<!-- tabs:start -->
+
+#### **GML**
+
+```gml
+function am_i_dead()
+{
+    return instance_exists(obj_player);
+}
+
+
+ChatterboxLoad("example.json");
+ChatterboxAddFunction("AmIDead", am_i_dead);
+```
+
+#### **YarnScript**
+
+```yarn
+Am I dead?
+<<if AmIDead("player")>>
+    Yup. Definitely dead.
+<<else>>
+    Not today!
+<<endif>>
+```
+
+<!-- tabs:end -->
+
+This example shows how the script `am_i_dead()` is called by Chatterbox in an if statement. The value returned from `am_i_dead()` determines which text is displayed.
+
+&nbsp;
+
+## Custom Actions
+
+A function that has been added to Chatterbox can further be executed as an action. This means you can execute any old code you like using Chatterbox; if you were so inclined you code write an entire game's logic from within YarnScript.
+
+You can also define custom actions which are used in a similar way to in-built actions:
+
+```yarn
+What a beautiful evening, Amelia.
+-> It'd be a shame if the Moon hid behind the clouds.
+    <<HideTheMoon>>
+-> The stars are so bright!
+    <<FlickerStars>>
+```
+
+In this example, both `<<HideTheMoon>>` and `<<FlickerStars>>` are custom actions. 
+
+There are three ways that custom actions can be used in Chatterbox; to swap between the different implementations set [`CHATTERBOX_ACTION_MODE`](reference-configuration?id=chatterbox_action_mode) to one of the following (the default is option `1`):
+- `0` Pass YarnScript actions as a raw string to a function, defined by `CHATTERBOX_ACTION_FUNCTION`
+- `1` Treat actions as expressions
+- `2` Treat actions as they were in version 1 (Python-esque function calls)
+
+Mode `0` is the official recommendation from the Yarn team. This mode instructs a chatter to actions as a strings into the game engine for manual interpretation. Chatterbox's implementation is that the function defined by `CHATTERBOX_ACTION_FUNCTION` is called when Chatterbox encounters an action, the first argument (`argument0`) for the function call being the text inside the action as a string. The intention is that you'd then parse that text and execute behaviour accordingly but... this sucks, it's a ton of work to actually do this, let's move on.
+
+Mode `1` is the default Chatterbox behaviour:
+1. Every custom action is expected to use GML-like syntax: functions are executed using their name followed by a comma-separated list of arguments e.g. `<<CustomFunction("string", "string with spaces", 3.14, true)>>`
+2. Variables are referenced by using the standard dollar-prefixed token e.g. `<<TransmutateLead("Gold", $lead)>>`
+3. You can also do basic operations, such as concatenation and basic arithmetic, in function arguments as you would expect in GML e.g. `<<ShowItem("BigAssSword" + $modifier)>>`
+
+Mode `2` is provided as an easier-to-use alternative for larger teams where people are working with writers who are uncomfortable with GML-like function syntax. The examples above would be written like so:
+1. `<<CustomFunction string "string with spaces" 3.14 true>>`
+2. You can reference variables by using the standard dollar-prefixed token wrapped in `{` `}` curly brackets e.g. `<<TransmutateLead Gold {$lead}>>`
+3. `<<ShowItem {"BigAssSword" + $modifier}>>`
+
+&nbsp;
+
+## Asynchronous Functions
+
+This is an advanced power move! It's possible to create asynchronous function execution so that you can temporarily pause a chatterbox whilst something else happens in your game, such as running an animation or showing a cutscene. To do this we need three different components:
+1. `CHATTERBOX_CURRENT` - Macro that contains a reference to the chatterbox that is currently being processed
+2. `ChatterboxWait()` - Function that forces a chatterbox into a waiting state (pauses processing)
+3. `ChatterboxContinue()` - Function that resumes processing for a chatterbox
+
+The following example assumes [`CHATTERBOX_ACTION_MODE`](reference-configuration?id=chatterbox_action_mode) has been set to `1` and [`CHATTERBOX_FUNCTION_ARRAY_ARGUMENTS`](reference-configuration?id=chatterbox_function_array_arguments) has been set to `true`.
+
+<!-- tabs:start -->
+
+#### **GML**
+
+```gml
+ChatterboxAddFunction("example", function(_argumentArray)
+{
+    ChatterboxWait(CHATTERBOX_CURRENT);
+    show_debug_message("Waiting chatterbox for " + string(_argumentArray[0]) + " frames...");
+    time_source_start(time_source_create(time_source_game, _argumentArray[0], time_source_units_frames,
+    function(_chatterbox)
+    {
+        show_debug_message("...continuing chatterbox!");
+        ChatterboxContinue(_chatterbox);
+    },
+    [CHATTERBOX_CURRENT]));
+});
+```
+
+#### **YarnScript**
+
+```yarn
+Hello there, would you like to wait 5 seconds?
+-> Nah...
+-> Please.
+    <<example(300)>>
+Okey dokey.
+```
+
+<!-- tabs:end -->