Updated documentation and tutorials (#267)

Some tutorials now have animation in them to give a clearer explanation of how things work. Added a short tutorial about creating Atoms with the new Search function. Documentation about installation has also changed.

PUBLISHING.md

@@ -4,7 +4,7 @@ _Here is a check list for publishing a new version:_
 
 -   [] Checkout the canary branch and make sure `CHANGELOG.md` is up to date.
 -   [] Update the version number in all `package.json` files (on the root and in all the `Packages/<PackageName>/package.json`)
--   [] Update the root `README.md` file with the correct version. Also update the version in `docs/introduction/quick-start.md`.
+-   [] Update the root `README.md` file with the correct version. Also update the version in `docs/introduction/installation.md`.
 -   [] From the root run `npm run generate:docs` to make sure all API documentation is up to date.
 -   [] Commit and push your changes to the canary branch.
 -   [] Merge the canary branch into the master branch.

docs/README.md

@@ -1,11 +1,12 @@
 # Table of Contents
 
 -   Introduction
-    -   [Quick start: adding Unity Atoms your project](./introduction/quick-start.md)
+    -   [Installation](./introduction/installation.md)
     -   [Overview and philosopy](./introduction/overview.md)
     -   [Preferences](./introduction/preferences.md)
     -   [FAQ](./introduction/faq.md)
 -   Tutorials
+    -   [Creating Atoms](./tutorials/creating-atoms.md)
     -   [Variables](./tutorials/variables.md)
     -   [Events](./tutorials/events.md)
     -   [Listeners](./tutorials/listeners.md)

docs/introduction/installation.md

@@ -1,16 +1,15 @@
 ---
-id: quick-start
-title: Quick start
+id: installation
+title: Installation
 hide_title: true
-sidebar_label: Quick start
+sidebar_label: Installation
 ---
 
-# Quick start
+# Installation
 
-## Installation
+Welcome to Unity Atoms! There are several ways to add Unity Atoms to your project.
 
 _Prerequisite: Since Unity Atoms is using the Unity Package Manager (UPM) you need to use Unity version 2018.3 >=_
-
 ### NPM
 
 Add the following to your `manifest.json`:
@@ -97,8 +96,8 @@ Follow [Unity Atoms on Github](https://github.com/unity-atoms/unity-atoms) to st
 
 ## Create your first Atom
 
-You are now ready to create your first Atom. Simply right click somewhere in the Project window and go to **Create / Unity Atoms** and pick the Atom of your choice:
+To dive right in, create your first Atom using any of the available techniques mentioned in [Creating Atoms](../tutorials/creating-atoms.md).
 
-![create-your-first-atom](../assets/quick-start/create-your-first-atom.png)
+## Learn more
 
-Now you are ready to go to [Overview and philosopy](./overview.md) to learn more about Unity Atoms!
+Go to [Overview and philosopy](./overview.md) to learn more about Unity Atoms and how to tune in to the correct mindset when using them.

docs/tutorials/actions.md

@@ -11,6 +11,9 @@ The `ChangeFillAmount` function created in the listeners tutorial is actually a
 
 ```cs
 [CreateAssetMenu(menuName = "Unity Atoms/Examples/Health Logger")]
+using UnityEngine;
+using UnityAtoms.BaseAtoms;
+
 public class HealthLogger : IntAction
 {
     public override void Do(int health)

docs/tutorials/creating-atoms.md

@@ -0,0 +1,16 @@
+---
+id: creating-atoms
+title: Creating Atoms
+hide_title: true
+sidebar_label: Creating Atoms
+---
+
+# Creating Atoms
+
+There are several ways of creating Atoms in your project. The recommended way is to use the new `Atoms Search` function (introduced in 4.4.2) accessible in the usual Unity `Create` context menu or by pressing the hotkey `Alt + 1`:
+
+![creating-atoms](../assets/creating-atoms/atoms-creation.gif)
+
+Another way to create Atoms is to select `Unity Atoms` in the context menu. The items are listed by category and by type. Custom Atom types created using the `Generator` (introduced by a later tutorial) also appear in this menu.
+
+In the following tutorials this is simply referred to as "creating an Atom" using any of the above mentioned techniques.

docs/tutorials/events.md

@@ -12,23 +12,23 @@ Events are things that happens in our game that other scripts or entities could
 -   `Changed` — raised every time a Variable’s value is changed. The Event contains the new value.
 -   `Changed With History` — also raised every time a Variable’s value is changed. However, this Event contains both the new and the old value.
 
-This makes it easier to make our game more data driven than just using Variables. Lets take a look at how that looks in our last example. We can create a new `IntEvent` as a `.asset` file by right clicking and go _Create / Unity Atoms / Event / Int_ and name it `HealthChangedEvent`:
+This makes it easier to make our game more data driven than just using Variables. Lets take a look at how that looks in our last example. We can [create](./creating-atoms.md) a new `IntEvent` and called `HealthChangedEvent`. Drop it on our `IntVariable` for the player’s health like this:
 
-![health-changed-event](../assets/events/health-changed-event.png)
-
-And then drop it on our `IntVariable` for the player’s health like this:
-
-![int-variable_player-health-v2](../assets/events/int-variable_player-health-v2.png)
+![health-changed-event-drop](../assets/events/health-changed-event-drop.gif)
 
 We can then modify our `HealthBar.cs` script to look like this:
 
 ```cs
+using UnityEngine;
+using UnityEngine.UI;
+using UnityAtoms.BaseAtoms;
+
 public class HealthBar : MonoBehaviour
 {
     [SerializeField]
     private IntEvent HealthChangedEvent;
     [SerializeField]
-    private IntVariable MaxHealth;
+    private IntConstant MaxHealth;
 
     void Start()
     {
@@ -49,6 +49,6 @@ public class HealthBar : MonoBehaviour
 
 And then inject the `HealthChangedEvent` to our `HealthBar` component:
 
-![healthbar-script-v2](../assets/events/healthbar-script-v2.png)
+![events-to-healthbar](../assets/events/events-to-healthbar.gif)
 
 We now react to global state changes instead of checking the Variable value each Update tick. In other words we only update our `Image` component when we actually need to. That is pretty sweet!

docs/tutorials/listeners.md

@@ -9,17 +9,21 @@ sidebar_label: Listeners
 
 There is still an issue that the `HealthBar.cs` script is in charge of registering itself as a listener and at the same time defining what happens when a Event is raised. We need to seperate its concerns! This brings us to the third concept of Unity Atoms, Listeners. A Listener listens (sometimes also referred to as observes or subscribes) to an Event and responds by firing off zero to many responses. Listeners are MonoBehaviours and therefore live in a scene. They can be seen as the glue between Events and Actions.
 
-The `HealthBar.cs` script from our last example is actually a Listener, but a very specific implementation of it. We can do better than that! Lets create a Game Object in our scene and call it `HealthListener`. Unity Atoms comes with some predefined Listeners. In this case we want to listen to an `IntEvent` so we will press the Add Component button on our `HealthListener`, create an IntListener and drop in the `HealthChangedEvent`:
+The `HealthBar.cs` script from our last example is actually a Listener, but a very specific implementation of it. We can do better than that! Lets create a Game Object in our scene and call it `HealthListener`. Unity Atoms comes with some predefined Listeners. In this case we want to listen to an `IntEvent` so we will press the Add Component button on our `HealthListener`, create an `IntEventReferenceListener` and drop in the `HealthChangedEvent`:
 
-![health-listener](../assets/listeners/health-listener-v1.png)
+![health-listener](../assets/listeners/health-changed-event-listener.gif)
 
 We can now shave off some of the code in our `HealthBar.cs` script to look like this:
 
 ```cs
+using UnityEngine;
+using UnityEngine.UI;
+using UnityAtoms.BaseAtoms;
+
 public class HealthBar : MonoBehaviour
 {
     [SerializeField]
-    private IntVariable MaxHealth;
+    private IntConstant MaxHealth;
 
     public void ChangeFillAmount(int health)
     {
@@ -28,8 +32,8 @@ public class HealthBar : MonoBehaviour
 }
 ```
 
-And then go back to our `HealthListener`’s IntListener component, press the `+` to add an Unity Event Response, drop in the `HealthBar` component (from the scene) and point out the `ChangeFillAmount` function defined above:
+And then go back to our `HealthListener`’s `IntEventReferenceListener` component, press the `+` to add an Unity Event Response, drop in the `HealthBar` component (from the scene) and point out the `ChangeFillAmount` function defined above:
 
-![health-listener](../assets/listeners/health-listener-v2.png)
+![health-listener-response](../assets/listeners/health-changed-event-listener-response.gif)
 
 The `HealthBar.cs` script is now only responsible for what happens when our player’s health is changing. Pretty great, huh?

docs/tutorials/variable-instancer.md

@@ -7,11 +7,17 @@ sidebar_label: Variable Instancer
 
 # Variable Instancer
 
-Unity Atoms have no problems with being used in a prefab. However, it will quickly become apparent that all instances of the prefab refer to the one and the same Atom asset, such as a specific `IntVariable` in the asset folder.
+Unity Atoms have no problems with prefabs. However, it will quickly become apparent that all instances of the prefab refer to the one and the same Atom asset, such as a specific `IntVariable`.
+
+## Instancers explained
 
 For example, changing the value of a Variable applies to all prefab instances that use the Variable. Triggering the `Changed` event also causes all prefab instances to react. While this still has it's uses, the behaviour is not always desirable.
 
-To break free from global Atoms, Variables can be instantiated as an in-memory copy when a prefab is created. To do this, we need a `VariableInstancer`.
+![without-instancers](../assets/variable-instancer/without-instancers.png)
+
+To break free from globally defined Atoms, Variables can be instantiated as an in-memory copy when a prefab is created. To do this, we need a `VariableInstancer`.
+
+![with-instancers](../assets/variable-instancer/with-instancers.png)
 
 > **Note:** A `VariableInstancer` is unique to the type of the Variable. The generator can generate a `VariableInstancer` of any type needed. Unity Atoms comes with a set of predefined basic types.
 
@@ -19,21 +25,17 @@ To break free from global Atoms, Variables can be instantiated as an in-memory c
 
 Start by creating an empty `GameObject` called `Monster` and add an `Int Variable Instancer` component to it:
 
-![add-int-var-instancer](../assets/variable-instancer/add-int-var-instancer-1.png)
+![add-int-var-instancer-1](../assets/variable-instancer/add-int-var-instancer-1.png)
 
-The `VariableInstancer` needs a base Variable to instantiate. Create any `IntVariable` and use the inspector to add the variable to the `Base` field. You can also click on `Create` to use a shortcut for type-appropriate Variable creation from the instancer itself.
+The `VariableInstancer` needs a base Variable to instantiate. [Create](creating-atoms.md) any `IntVariable` and use the inspector to add the variable to the `Base` field. You can also click on `Create` to use a shortcut for type-appropriate Variable creation from the instancer itself.
 
-![add-int-var-instancer](../assets/variable-instancer/add-int-var-instancer-2.png)
+![instancer-base-variable](../assets/variable-instancer/instancer-base-variable.gif)
 
 ## Listening for `Changed` event
 
-The `VariableInstancer` instantiates the appropriate `Changed` and `Changed With History` event instances for this Variable. That's why it's possible to listen for the `Changed` event in an `Int Event Reference Listener`. Add an `Int Event Reference Listener` as a component and use the three dots next to `Event Reference` to select `Use Variable Instancer`:
+The `VariableInstancer` instantiates the appropriate `Changed` and `Changed With History` event instances for this Variable. That's why it's possible to listen for the `Changed` event in an `Int Event Reference Listener`. Add an `Int Event Reference Listener` as a component and use the three dots next to `Event Reference` to select `Use Variable Instancer` and drag the `Int Variable Instancer` on the `Event Reference` field:
 
-![use-variable-instancer](../assets/variable-instancer/use-variable-instancer.png)
-
-Grabbing from the title of the component, drag the `Int Variable Instancer` on the `Event Reference` field:
-
-![drag-variable-instancer](../assets/variable-instancer/drag-variable-instancer.png)
+![listener-use-instancer](../assets/variable-instancer/listener-use-instancer.gif)
 
 This event listener now listens to the instantiated `Changed` event from the `Int Variable Instancer`.
 
@@ -56,7 +58,7 @@ public class LogHealth : MonoBehaviour
 
 Add the `LogHealth` component and click `+` on the `Unity Event Response`, drag the `LogHealth` to the response field and choose the `ReportHealth` method from the list:
 
-![add-log-health](../assets/variable-instancer/add-log-health.png)
+![instancer-listener-response](../assets/variable-instancer/instancer-listener-response.gif)
 
 > **Note:** If the method does not appear under the `Dynamic` section with the data type of the listener, the method signature is wrong. The Unity response method can only have one parameter which corresponds to the listener type. Using a method with static parameters will still get called, but won't have access to the event data.
 

docs/tutorials/variables.md

@@ -5,19 +5,22 @@ hide_title: true
 sidebar_label: Variables
 ---
 
-# Variables and constants
+# Variables, Constants, and References
 
-Below follows a step-by-step example of managing a player's health using Unity Atoms. If you haven't read the [Overview and philosopy](../introduction/overview.md) section you should do that before proceeding.
+Below follows a step-by-step example of managing a player's health using Unity Atoms. If you haven't read the [Creating Atoms](./creating-atoms.md) and [Overview and philosopy](../introduction/overview.md) section you should do that before proceeding.
 
-_NOTE: This tutorial is based on [this](https://medium.com/@adamramberg/unity-atoms-tiny-modular-pieces-utilizing-the-power-of-scriptable-objects-e8add1b95201) blog post._
+_NOTE: This tutorial is based on [this](https://medium.com/@adamramberg/unity-atoms-tiny-modular-pieces-utilizing-the-power-of-scriptable-objects-e8add1b95201) blog post. The blog post is based on a previous version of Unity Atoms and as such will vary in content and appearance. The ideas presented by the blog post still apply._ 
 
 ## Decouple your scripts using Variables and Constants
 
 Variables are storing data, for example primitives, reference types or structs as Scriptable Objects. Because Variables are stored as Scriptable Objects they are not part of any scene, but could instead be seen as part of the game’s global shared state. Variables are designed to make it easy to inject them (via the Unity Inspector) and share them between your MonoBehaviours. A Constant is a trimmed down version of a Variable and it's value can't be altered at runtime. Lets see an example on how to use Variables and Constants!
 
-Imagine you have a `PlayerHealth.cs` script that contains the health of the game’s player. We will attach the script to a `GameObject` with a `SpriteRenderer`, `BoxCollider2D` and a `Rigidbody2D` called Player. The health is represented by an int, which corresponds to an `IntVariable` in Unity Atoms. The script will look like this:
+Imagine you have a `PlayerHealth.cs` script that contains the health of the game’s player. We will attach the script to a `GameObject` with a `SpriteRenderer`, `BoxCollider2D` and a `Rigidbody2D` called Player. The health is represented by an `int`, which corresponds to an `IntVariable` in Unity Atoms. The script will look like this:
 
 ```cs
+using UnityEngine;
+using UnityAtoms.BaseAtoms;
+
 public class PlayerHealth : MonoBehaviour
 {
     public IntVariable Health;
@@ -27,21 +30,31 @@ public class PlayerHealth : MonoBehaviour
 In the game the player’s health will decrease when hitting something harmful. We will attach this `Harmful.cs` script to a GameObject called Harmful that also has a `SpriteRenderer` and a `BoxCollider2D` (as a trigger):
 
 ```cs
+using UnityEngine;
+
 public class Harmful : MonoBehaviour
 {
     void OnTriggerEnter2D(Collider2D collider)
     {
         if (collider.tag == "Player")
         {
-            collider.GetComponent<Player>().Health.Value -= 10;
+            collider.GetComponent<PlayerHealth>().Health.Value -= 10;
         }
     }
 }
 ```
 
+This script is added as an example of what might influence the value of the player's health during gameplay. It will be referenced in a later tutorial.
+
+## Creating a simple health bar
+
 Finally we will add an UI `HealthBar.cs` script that we attach to a `GameObject` (inside a UI Canvas) with a `RectTransforn`, `CanvasRenderer` and UI `Image` component. The `HealthBar.cs` script will update the `Image` representing the health bar when the player’s health is changing:
 
 ```cs
+using UnityEngine;
+using UnityEngine.UI;
+using UnityAtoms.BaseAtoms;
+
 public class HealthBar : MonoBehaviour
 {
     [SerializeField]
@@ -56,25 +69,58 @@ public class HealthBar : MonoBehaviour
 }
 ```
 
-Since the player's health is going to change at runtime we make `Health` an `IntVariable` while `MaxHealth` is not going to be changed at runtime is therefore created as an `IntConstant`, They are both global assets stored as `.asset` files that could be shared between scripts. To create these `.asset` files we can right click somewhere in the Project window, and go _Create / Unity Atoms / Variables / Int_ to create the Variable and go _Create / Unity Atoms / Constants / Int_ to create the Constant. The Variable looks like this in the Unity Inspector:
+## Adding Atoms
+
+Go ahead and create an `IntVariable` called `Health` and an `IntConstant` called `MaxHealth`. `MaxHealth` is an `IntConstant` since it will not be changed during runtime. Set the initial value and value to 100, respectively.
+
+To create these `.asset` files, see [Creating Atoms](./creating-atoms.md). They are both global assets stored as `.asset` files that could be shared between scripts.
+
+The Variable Atom looks like this in the Unity Inspector:
 
 ![int-variable_player-health-v1](../assets/variables/int-variable_player-health-v1.png)
 
-And the Constant looks like this:
+And the Constant Atom looks like this:
 
 ![int-variable_player-health](../assets/variables/int-constant_max-player-health.png)
 
-The `Developer Description` is a text describing the Variable in order to document it, the `Value` is the actual value of the Variable, and `Old Value` is the last value the Variable had after it was changed via code. `Changed` and `Changed With History` will be explained later in this tutorial. We name the `IntVariable` created to `Health` and the `IntConstant` to `MaxHealth` and set both their initial value to 100. After they are created we can drop them on the `PlayerHealth` and `HealthBar` components via Unity’s inspector like this:
+The `Developer Description` is a text describing the Variable in order to document it, the `Value` is the actual value of the Variable, and `Old Value` is the last value the Variable had after it was changed via code. 
 
-![player-health-script](../assets/variables/player-health-script.png)
+`Changed` and `Changed With History` are explained in the [Events](./events.md) tutorial.
 
-![healthbar-script-v1](../assets/variables/healthbar-script-v1.png)
+## Assigning Atoms
 
-Variables gives us a way of separating our game’s shared state from the actual implementation. It also makes our code less coupled since we do not need to reference other MonoBehaviours in our scripts, eg. we do not need to reference the `PlayerHealth.cs` script in our `HealthBar.cs` script like this:
+Atoms can be assigned using the Unity Inspector. Assign the Atoms on the `PlayerHealth`  like this:
+
+![assign-to-playerhealth](../assets/variables/assign-to-playerhealth.gif)
+
+and `HealthBar` like this:
+
+![assign-to-healthbar](../assets/variables/assign-to-healthbar.gif)
+
+Variables give us a way of separating our game’s shared state from the actual implementation. It also makes our code less coupled since we do not need to reference other MonoBehaviours in our scripts, e.g. we do not need to reference the `PlayerHealth.cs` script in our `HealthBar.cs` script like this:
 
 ```cs
 [SerializeField]
-private PlayerHealth playerHealth;
+private PlayerHealth playerHealth; // Code would become coupled with PlayerHealth
 ```
 
+## Introduce flexibility using References
+
+For more flexibility in your code, you may also choose to use `IntReference` instead of `IntVariable` or `IntConstant`. 
+
+In the previous example, change the type of `MaxHealth` to `IntReference`:
+
+```cs
+[SerializeField]
+private IntReference MaxHealth;
+```
+
+Now you have more options for the variable in the inspector:
+
+![intreference-demo](../assets/variables/intreference-demo.gif)
+
+## Conclusion
+
+At first glance the scipts here do not seem to work. The health bar stays at the same value even if the value of the `Health` Atom changes. This tutorial is primarily about decoupling scripts. To have the health bar function as expected, events and listeners are needed. These are both introduced in later tutorials. 
+
 Hurray for less coupled code! 🎉

website/README.md

@@ -107,7 +107,7 @@ My new content here..
 {
   "docs": {
     "Getting Started": [
-      "quick-start",
+      "installation",
       "newly-created-doc" // new doc here
     ],
     ...

website/core/Footer.js

@@ -40,7 +40,7 @@ class Footer extends React.Component {
           </a>
           <div>
             <h5>Docs</h5>
-            <a href={this.docUrl('introduction/quick-start')}>Quick Start</a>
+            <a href={this.docUrl('introduction/installation')}>Installation</a>
             <a href={this.docUrl('api/actions')}>API</a>
             <a href={this.docUrl('subpackages/base-atoms')}>Subpackages</a>
           </div>

website/i18n/en.json

@@ -73,6 +73,10 @@
         "title": "FAQ",
         "sidebar_label": "FAQ"
       },
+      "introduction/installation": {
+        "title": "Installation",
+        "sidebar_label": "Installation"
+      },
       "introduction/overview": {
         "title": "Overview and philosopy",
         "sidebar_label": "Overview and philosopy"
@@ -81,10 +85,6 @@
         "title": "Preferences",
         "sidebar_label": "Preferences"
       },
-      "introduction/quick-start": {
-        "title": "Quick start",
-        "sidebar_label": "Quick start"
-      },
       "README": {
         "title": "README"
       },
@@ -132,6 +132,10 @@
         "title": "Conditions",
         "sidebar_label": "Conditions"
       },
+      "tutorials/creating-atoms": {
+        "title": "Creating Atoms",
+        "sidebar_label": "Creating Atoms"
+      },
       "tutorials/event-instancer": {
         "title": "Event Instancer",
         "sidebar_label": "Event Instancer"
@@ -166,7 +170,7 @@
       }
     },
     "links": {
-      "Quick Start": "Quick Start",
+      "Installation": "Installation",
       "API": "API",
       "Github": "Github"
     },

website/pages/en/index.js

@@ -82,7 +82,7 @@ const HomeSplash = ({ language = '' }) => (
     <div className="inner">
       <ProjectTitle />
       <PromoSection>
-        <Button href={docUrl('introduction/quick-start', language)}>
+        <Button href={docUrl('introduction/installation', language)}>
           Get Started
         </Button>
       </PromoSection>

website/sidebars.json

@@ -1,7 +1,7 @@
 {
   "docs": {
     "Introduction": [
-      "introduction/quick-start",
+      "introduction/installation",
       "introduction/overview",
       "introduction/preferences",
       "introduction/faq"
@@ -11,6 +11,7 @@
         "type": "subcategory",
         "label": "Basics",
         "ids": [
+          "tutorials/creating-atoms",
           "tutorials/variables",
           "tutorials/events",
           "tutorials/listeners",

website/siteConfig.js

@@ -24,7 +24,7 @@ const siteConfig = {
 
   // For no header links in the top nav bar -> headerLinks: [],
   headerLinks: [
-    { doc: 'introduction/quick-start', label: 'Quick Start' },
+    { doc: 'introduction/installation', label: 'Installation' },
     { doc: 'api/unityatoms', label: 'API' },
     { href: 'https://www.github.com/unity-atoms/unity-atoms', label: 'Github' },
   ],