State Machine Design Documentation (nicholas-maltbie#86)

* Added basic fsm design docs and formatting update

* Added fsm design to project

* Fixed borken toc link for fsm doc

* Updated buidl workflow to support docfx

.markdownlint.json

@@ -0,0 +1,4 @@
+{
+    "default": true,
+    "MD007": { "indent": 4 },
+}

Documentation/build.cmd

@@ -15,7 +15,7 @@ docfx metadata %~dp0\docfx.json --warningsAsErrors --logLevel verbose --force &&
 )
 
 echo Generating website
-docfx build %~dp0\docfx.json --warningsAsErrors --logLevel verbose && (
+docfx build %~dp0\docfx.json -t default --warningsAsErrors --logLevel verbose && (
     echo Successfuly generated website for documentation
 ) || (
     echo Could not properly website for documentation

Documentation/build.sh

@@ -12,4 +12,4 @@ echo "Building code metadata"
 docfx metadata $BASEDIR/docfx.json --warningsAsErrors --logLevel verbose --force
 
 echo "Generating website"
-docfx build $BASEDIR/docfx.json --warningsAsErrors --logLevel verbose
+docfx build $BASEDIR/docfx.json -t default --warningsAsErrors --logLevel verbose

Documentation/docfx.json

@@ -22,6 +22,10 @@
         }
     ],
     "build": {
+        "template": [
+            "default",
+            "templates/mermaid"
+        ],
         "globalMetadata": {
             "_appTitle": "OpenKCC Documentation",
             "_appFooter": "OpenKCC Documentation",

Documentation/manual/introduction.md

@@ -50,16 +50,16 @@ the important folders for using and learning about the project:
 
 * `Assets\Samples` - OpenKCC Sample scenes and examples for the project.
 * `Packages\com.nickmaltbie.openkcc` -
-  main package folder with all the code, tests, and shared assets.
-  * `Packages\com.nickmaltbie.openkcc\common` -
-    Common prefabs, materials, and assets used across the entire project.
-  * `Packages\com.nickmaltbie.openkcc\Editor` -
-    Editor specific assets for the project configuration,
-    not included in builds.
-  * `Packages\com.nickmaltbie.openkcc\OpenKCC` -
-    Main project source code and assemblies.
-  * `Packages\com.nickmaltbie.openkcc\Tests` -
-    EditMode and PlayMode tests for the project.
+    main package folder with all the code, tests, and shared assets.
+    * `Packages\com.nickmaltbie.openkcc\common` -
+        Common prefabs, materials, and assets used across the entire project.
+    * `Packages\com.nickmaltbie.openkcc\Editor` -
+        Editor specific assets for the project configuration,
+        not included in builds.
+    * `Packages\com.nickmaltbie.openkcc\OpenKCC` -
+        Main project source code and assemblies.
+    * `Packages\com.nickmaltbie.openkcc\Tests` -
+        EditMode and PlayMode tests for the project.
 
 The rest of the assets folder contains code for render pipeline and
 settings, feel free to look through them if you want an example

Documentation/manual/kcc-design/kcc-fsm-design.md

@@ -0,0 +1,108 @@
+# State Machine Design
+
+In order to manage the movement and controls of the
+kinematic character controller, the OpenKCC will use a
+[Finite State Machine](https://en.wikipedia.org/wiki/Finite-state_machine)
+(FSM) based design to manage character actions.
+
+The character controller will have high level "states"
+that can be changed based on external input or internal
+changes. The character will act differently
+based on these states.
+
+## State Overview
+
+The state machine for the OpenKCC is composed
+of a few different states.
+
+* Idling - When the player is standing still on the ground
+* Walking - When the player is moving around
+* Falling - When the player is not standing on something
+* Sliding - When the player is standing on a steep surface
+
+Each of these states will have a different set of
+capabilities and behaviors and will transition to
+other states based on external input.
+
+### Transition Diagram
+
+```mermaid
+stateDiagram
+    [*] --> Idling
+
+    Idling --> Walking : Move Input
+    Idling --> Falling : Not Grounded
+    Idling --> Sliding : Steep Slope
+
+    Walking --> Idling : Stop Input
+    Walking --> Falling : Not Grounded
+    Walking --> Sliding : Steep Slope
+
+    Sliding --> Falling : Not Grounded
+    Sliding --> Idling : Flat Ground
+
+    Falling --> Idling : Grounded + Flat
+    Falling --> Sliding : Grounded + Steep
+```
+
+### State Attributes
+
+Each state of the KCC will have a few different
+attributes:
+
+* State name and transitions
+* Animation to play during state (if any)
+* Behavior on entry, exit, and update
+* Available player inputs
+    such as movement, camera control, etc...
+
+In addition, each transition will also
+have a set of configurations that include:
+
+* Conditions to trigger transition
+* Animation to play on transition (if any)
+* Transition time and configuration
+    such as allow early exit/cancellation
+
+## Code Design
+
+The code for this is still in development
+but it will be managed via a few different classes.
+The main design of these classes will be managed
+by a set of [C# Attributes](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/attributes/)
+to configure and manage controls for the state machine
+directly from the C# code.
+
+* StateMachine - class to manage a set of states and transitions.
+* State - A state for a given FSM.
+* TransitionAttribute - Attribute to define and manage
+    the transitions for a given state.
+* AnimationAttribute - Attribute to configure an animation
+    or set of animations to play based on a configuration.
+* Entry and exit behaviors defined via the attributes:
+
+    * OnEnterState - Called when state is entered
+    * OnExitState - Called when the state is exited
+
+* Update Attributes to be triggered on various [MonoBehaviour](https://docs.unity3d.com/ScriptReference/MonoBehaviour.html)
+    functions including the following subset. There are other
+    messages defined for the unity MonoBehaviour but these
+    are the only planned ones as of now, feel free to extend
+    the code or add your own events if you wish.
+
+    * OnUpdate - Called each frame.
+    * OnFixedUpdate - Called each fixed update.
+    * OnLateUpdate - Called at the end of each frame.
+    * OnGUI - Called each GUI update.
+    * OnEnable - Called when object is enabled.
+    * OnDisable - Called when object is disabled.
+    * OnAnimatorIk - Callback for setting up animation IK (inverse kinematics).
+
+## Customization
+
+You may want to design your own character controller or
+other object based on this state machine design, feel
+free to use or extend the code however you see fit.
+As of right now, there is only one state machine example
+in the project of the character controller
+but you can extend or change it however you wish.

Documentation/manual/kcc-design/overview.md

@@ -23,5 +23,6 @@ work as well as propose new features or structures for the project.
 
 See the various sections for further details
 
+* [State Machine Design](kcc-fsm-design.md)
 * [KCC Movement Design](kcc-movement.md)
 * [Physics for Character Controllers](physics-notes.md)

Documentation/manual/toc.yml

@@ -6,6 +6,8 @@
 - name: KCC Design overview
   href: kcc-design/overview.md
   items:
+    - name: State Machine Design
+      href: kcc-design/kcc-fsm-design.md
     - name: KCC Movement Design
       href: kcc-design/kcc-movement.md
     - name: Physics for Character Controllers

Documentation/manual/usage.md

@@ -72,58 +72,58 @@ are also explained in depth in the
 documentation page.
 
 - **Input Controls** - Controls to manage character movement.
-  - _Move Action_ - Action to move player along two axis input
-    (forward back, left right)
-  - _Jump Action_ - Button action to start player jump
-  - _Sprint Action_ - Button action to control sprinting speed
-- **Ground Checking** - Configures grounded state for player.
-  - _Grounded Distance_ - Threshold distance for when player is considered
-    to be "on the ground". Used to detect if the player is falling or sliding.
-  - _Standing Distance_ - Distance to ground at which player is considered
-    standing on something. Used to identify what the player is standing on.
-  - _Ground Check Distance_ - Distance to create raycast for checking grounded
-    state. Sometimes useful to be slightly farther than grounded distance
-    or standing distance to catch edge cases.
-  - _Max Walk Angle_ - Maximum slope a player can walk without sliding
-    or falling down.
-  - _Gravity_ - Direction and magnitude of gravity in units per second squared.
+    - _Move Action_ - Action to move player along two axis input
+        (forward back, left right)
+    - _Jump Action_ - Button action to start player jump
+    - _Sprint Action_ - Button action to control sprinting speed
+    - **Ground Checking** - Configures grounded state for player.
+    - _Grounded Distance_ - Threshold distance for when player is considered
+        to be "on the ground". Used to detect if the player is falling or sliding.
+    - _Standing Distance_ - Distance to ground at which player is considered
+        standing on something. Used to identify what the player is standing on.
+    - _Ground Check Distance_ - Distance to create raycast for checking grounded
+        state. Sometimes useful to be slightly farther than grounded distance
+        or standing distance to catch edge cases.
+    - _Max Walk Angle_ - Maximum slope a player can walk without sliding
+        or falling down.
+    - _Gravity_ - Direction and magnitude of gravity in units per second squared.
 - **Motion Settings** - Settings for controlling player movement.
   Many of these settings are based on the character movement design,
   See [KCC Movement Design](kcc-design/kcc-movement.md) for more details.
-  - _Walking Speed_ - Speed at which the player walks, in units per second.
-  - _Sprint Speed_ - Speed of player when sprinting, in units per second.
-  - _Max Bounces_ - Maximum bounces for computing player movement.
-  - _Push Decay_ - Preserved momentum percentage when pushing an object. A value
-    of 0 would indicate a complete stop while a value of 1 would be fully
-    bouncing off an object when the player collides with it.
-  - _Angle Power_ - Angle decay rate when sliding off surfaces.
-  - _Max Push Speed_ - Maximum distance a player can be pushed when overlapping
-    other objects in units per second. Useful for resolving collisions.
-  - _Vertical Snap Down_ - Distance at which the player can "snap down" when
-    walking.
+    - _Walking Speed_ - Speed at which the player walks, in units per second.
+    - _Sprint Speed_ - Speed of player when sprinting, in units per second.
+    - _Max Bounces_ - Maximum bounces for computing player movement.
+    - _Push Decay_ - Preserved momentum percentage when pushing an object. A value
+        of 0 would indicate a complete stop while a value of 1 would be fully
+        bouncing off an object when the player collides with it.
+    - _Angle Power_ - Angle decay rate when sliding off surfaces.
+    - _Max Push Speed_ - Maximum distance a player can be pushed when overlapping
+        other objects in units per second. Useful for resolving collisions.
+    - _Vertical Snap Down_ - Distance at which the player can "snap down" when
+        walking.
 - **Stair and Step** - Setting related to player stairs and steps.
-  - _Step Up Depth_ - Minimum depth required when stepping up stairs.
-  - _Vertical Snap Up_ - Max distance the player can snap up stairs.
-  - _Snap Buffer Time_ - Time in which the player can snap up or down
-    steps even after starting to fall
+    - _Step Up Depth_ - Minimum depth required when stepping up stairs.
+    - _Vertical Snap Up_ - Max distance the player can snap up stairs.
+    - _Snap Buffer Time_ - Time in which the player can snap up or down
+        steps even after starting to fall
 - **Player Jump Settings** - Settings relevant to player jumps
-  - _Jump Velocity_ - Vertical velocity of player when they jump.
-  - _Max Jump Angle_ - Maximum surface angle when the player wants to jump.
-  - _Jump Angle Weight Factor_ - How much does surface angle impact jump
-    direction.
-  - _Jump Cooldown_ - Minimum time between jumps in seconds.
-  - _Coyote Time_ - Time in which the player will float before they start to
-    fall when they are not grounded.
-  - _Jump Buffer Time_ - Time in which the player's input for jumping
-    will be buffered before hitting hte ground in seconds.
+    - _Jump Velocity_ - Vertical velocity of player when they jump.
+    - _Max Jump Angle_ - Maximum surface angle when the player wants to jump.
+    - _Jump Angle Weight Factor_ - How much does surface angle impact jump
+        direction.
+    - _Jump Cooldown_ - Minimum time between jumps in seconds.
+    - _Coyote Time_ - Time in which the player will float before they start to
+        fall when they are not grounded.
+    - _Jump Buffer Time_ - Time in which the player's input for jumping
+        will be buffered before hitting hte ground in seconds.
 - **Player Prone Settings** - Settings to control player behavior when knocked
   prone/rag doll
-  - _Early Stop Prone Threshold_ - Threshold time in which player is not moving
-    to exit prone state.
-  - _Threshold Angular Velocity_ - Threshold angular velocity in degrees per
-    second for existing prone early.
-  - _Threshold Velocity_ - Threshold linear velocity in units per seconds for
-    exiting prone early.
+    - _Early Stop Prone Threshold_ - Threshold time in which player is not moving
+        to exit prone state.
+    - _Threshold Angular Velocity_ - Threshold angular velocity in degrees per
+        second for existing prone early.
+    - _Threshold Velocity_ - Threshold linear velocity in units per seconds for
+        exiting prone early.
 
 ## Making Your Own Custom Kinematic Character Controller
 

Documentation/templates/mermaid/partials/scripts.tmpl.partial

@@ -0,0 +1,21 @@
+<!-- Derived from https://blog.christian-schou.dk/how-to-produce-static-documentation-using-docfx/#including-diagrams-in-your-documentation-mermaid-with-docfx !-->
+<!-- mermaid support -->
+<script src="https://unpkg.com/[email protected]/dist/mermaid.min.js"></script>
+<script>
+    mermaid.initialize({
+        startOnLoad: false
+    });
+
+    window.onload = function () {
+        const elements = document.getElementsByClassName("lang-mermaid");
+        let index = 0;
+
+        while (elements.length != 0) {
+            let element = elements[0];
+            mermaid.render('graph'+index, element.innerText, (svgGraph) => {                    
+                element.parentElement.outerHTML = "<div class='mermaid'>" + svgGraph + "</div>";
+            });
+            ++index;
+        }
+    }
+</script>