Merge pull request #1708 from Jason0214/more_blender_exporter_animation_doc

more guidance on godot_blender_exporter animation

getting_started/workflow/assets/escn_exporter/animation.rst

@@ -1,41 +1,81 @@
 Animation
 =========
+Animation supported:
+ - transform animation of all types of objects
+ - transform animation of pose bones
+ - shape key animation
+ - light animation
+ - camera animation
 
-Supported Animation
--------------------
- - transform animation of all types of object
- - transform animation of pose bone
+Multiple Actions For Single Object 
+----------------------------------
+In most games, one objects would have serveral animations to switch between. 
+This addon have a support for exporting multiple actions all at once into
+a single AnimationPlayer and makes it easy to switch actions.
 
-Action Lib
-----------
-Every action in object's nla tracks would be exported as
-a separate track and placed in AnimationPlayer.
+This worksflow makes use of blender nla_tracks. Here is a brief guide of how
+to use this feature:
 
-Placing of AnimationPlayer
+**1. Switch workspace to 'Dope Sheet'**
+
+.. image:: img/dope_sheet.jpg
+
+**2. Stash the active action**
+
+the stashed action while not action would still be exported
+
+.. image:: img/stash_action.jpg
+
+**3. Check stashed actions in 'NLA Editor' [optional]**
+
+Switch workspace to 'NLA Editor'
+
+.. image:: img/nla_editor.jpg
+
+Make sure all stashed actions are muted
+
+.. image:: img/nla_strip.jpg
+
+**4. Export the scene**
+
+all the stashed action as well as the active action are exported
+to the an AnimationPlayer
+
+.. image:: img/in_godot.jpg
+
+
+Constraints
+-----------
+Sometimes complicated animation is built with object constraint, an usual
+example is inverse kinematics. The addon would automatically check if an
+object has some constraint, if it does, all the constraints are baked into
+every action the object has and then exported.
+
+
+Animation Mode
 ---------------------------
 Godot and Blender have different structure to store animation data.
 In Godot animation data is stored in an AnimationPlayer node, instead
-of in each animated node.
-
-The exporter has an option :code:`Separate AnimationPlayer For Each Object`
-which controls how the exported AnimationPlayers are placed.
-
-.. note::
-    If :code:`Separate AnimationPlayer For Each Object` is **disabled**
-    children of any animated object shares one AnimationPlayer
-
-In the following case, animation data of Mesh is also exported to
-AnimationPlayer "RigAnimation"
-
-.. image:: img/animation_non_sep.jpg
+of in each animated node. In order to fix this inconsistence and still
+make the animation play versatile, this addon has three aimation exporting
+modes.
 
 
-.. note::
-    If :code:`Separate AnimationPlayer For Each Object` is **enabled**
-    every animated object got its own AnimationPlayer. It is useful when
-    artists want to play multiple animation concurrently, because one
-    AnimationPlayer node can only play one track at a time.
+**Mode 'Animation as Actions'**
 
-In the following case, Mesh and Rig have their own AnimationPlayer
+Treat all the animation as object actions, so in the exported scene, every
+object would have its own AnimationPlayer and hold its actions.
 
-.. image:: img/animation_sep.jpg
+
+**Mode 'Scene Animation'**
+
+If you want your animation generate same result as playing at Blender's
+timeline, this is what you want. In this mode, all the animation in the scene
+are placed in just one AnimationPlayer in the scene root.
+
+**Mode 'Animation as Action with Squash'**
+
+This mode has very similar behaviour of mode 'Animation as Action', but it
+can generate less AnimationPlayers, objects in parent-children relation would
+share their AnimationPlayer. It is useful when you have several rigs, and each
+Skeleton and Mesh has actions, then one rig would have just one AnimationPlayer.