FSM docs v1

Packages/FSM/Runtime/FiniteStateMachine/FiniteStateMachine.cs

@@ -162,7 +162,7 @@ namespace UnityAtoms.FSM
         }
 
         /// <summary>
-        /// Define a command that is going to automatically be dispatched when the condition provided is met.
+        /// Defines a command that is going to automatically be dispatched when the condition provided is met.
         /// </summary>
         public void DispatchWhen(string command, Func<string, bool> func, GameObject gameObject)
         {
@@ -212,7 +212,7 @@ namespace UnityAtoms.FSM
         }
 
         /// <summary>
-        /// Reset 
+        /// Reset the state machine
         /// </summary>
         /// <param name="shouldTriggerEvents">Should we trigger Change Events.</param>
         public override void Reset(bool shouldTriggerEvents = false)

docs/subpackages/fsm.md

@@ -7,4 +7,115 @@ sidebar_label: FSM
 
 # Unity Atoms / FSM
 
-Finite state machine implemented using Unity Atoms. See the [API](../api/unityatoms.fsm) for more info.
+Finite state machine implemented using Unity Atoms.
+
+## API
+
+Check out the [API](../api/unityatoms.fsm).
+
+## What is it?
+
+A finite state machine implementation for Unity Atoms. The package was inspired by [this](https://github.com/dubit/unity-fsm) open source Unity FSM repo. The FSM in Unity Atoms is actually derrived from `StringVariable`, so everything you can do with a `StringVariable` you can also do with a FSM.
+
+## Concepts
+
+A finite state machine is composed of 2 things:
+
+1. States - a list of possible states. A state is either a string of a sub finite state machine (oh yes, FSM's can be nested).
+2. Transitions - a list of possible transitions. State can only be altered to another state based on the transitions defined here.
+
+In order to change state you need to dispatch a command and that command must be defined in your transitions for the current state.
+
+## Example
+
+Here is a simple example taken from [here](https://github.com/dubit/unity-fsm)
+
+```
+          "CLOSE"               "LOCK"
+    +-------->---------+  +-------->---------+
+    |                  |  |                  |
+ +----+              +------+              +------+
+ |OPEN|              |CLOSED|              |LOCKED|
+ +----+              +------+              +------+
+    |                  |  |                  |
+    +--------<---------+  +--------<---------+
+           "OPEN"                "UNLOCK"
+```
+
+This FSM has 3 states:
+
+-   `OPEN`
+-   `CLOSED`
+-   `LOCKED`.
+
+It also has 4 transitions:
+
+-   From `OPEN`, to `CLOSED` when dispatching `CLOSE`.
+-   From `CLOSED`, to `LOCKED` when dispatching `LOCK`.
+-   From `LOCKED`, to `CLOSED` when dispatching `UNLOCK`.
+-   From `CLOSED`, to `OPEN` when dispatching `OPEN`.
+
+## States
+
+-   `Id` - the state name / identifier (string)
+-   `Cooldown` - if set to above 0 the state machine will re set the state every `n` th seconds where `n` is the cooldown specified in seconds. If for example cooldown is set to 1 and the state id is set to `SECOND`, then the state machine will be set to `SECOND` every second. This means that you will receive that value in the FSM's Changed Event.
+-   `Sub Machine` - FSMs can be nested. If specified this sub machine will take over resolving the state value.
+
+## Transitions
+
+-   `From State` - The state that we transition from.
+-   `To State` - The state that we transition to.
+-   `Command` - The command that needs to be dispatched in order to begin this transition.
+-   `Test Condition` - If specified this condition must be true in order to start the transition.
+-   `Raise Event To Complete Transition` - If set to true the transition will not complete automatically, Instead you will need to manually Raise the Complete Current Transition Event.
+
+## Hooks
+
+-   `OnUpdate` - Calls a handler with the state value each Update.
+-   `OnFixedUpdate` - Calls a handler with the state value each FixedUpdate.
+-   `DispatchWhen` - Defines a command that is going to automatically be dispatched when the condition provided is met.
+-   `OnStateCooldown` - Calls the handler of every state cooldown.
+
+## Funcs
+
+-   `Reset` - Reset the FSM.
+-   `Dispatch` - Dispatch / raise a command.
+
+## Simple example
+
+A simple example showing how you can move a rigidibody towards a target depending on if the current state of the FMS is set to `CHASING` or not.
+
+```cs
+public class EnemyMovement : MonoBehaviour
+{
+    [SerializeField]
+    private StringReference _tagToTarget;
+
+    [SerializeField]
+    private FloatReference _shootingRange = new FloatReference(5f);
+
+    [SerializeField]
+    private FloatReference _moveSpeedMultiplier = new FloatReference(2f);
+
+    [SerializeField]
+    private FiniteStateMachineReference _enemyState;
+
+
+    void Awake()
+    {
+        Transform target = null;
+        AtomTags.OnInitialization(() => target = AtomTags.FindByTag(_tagToTarget.Value).transform);
+        var body = GetComponent<Rigidbody2D>();
+
+        _enemyState.Machine.OnUpdate((deltaTime, value) =>
+        {
+            if (target)
+            {
+                body.Move((target.position - transform.position), value == "CHASING" ? 2f : 0f, deltaTime);
+            }
+        }, gameObject);
+        _enemyState.Machine.DispatchWhen(command: "ATTACK", (value) => target != null && value == "CHASING" && (_shootingRange.Value >= Vector3.Distance(target.position, transform.position)), gameObject);
+        _enemyState.Machine.DispatchWhen(command: "CHASE", (value) => target != null && value == "ATTACKING" && (_shootingRange.Value < Vector3.Distance(target.position, transform.position)), gameObject);
+    }
+    }
+```