manual/animation/actions.rst

@@ -5,70 +5,111 @@
 Actions
 *******
 
-When animating objects and properties in Blender, Actions record and contain the data.
+*Actions* are Blender's container for animation data.  For example, when you animate the location of an object, that animation is stored in an action rather than directly on the object itself.  The object then uses the action to get animated, much the same way that a mesh uses a material to get shaded.  All animatable data-blocks (objects, meshes, materials, etc.) are animated this way: they don't store their own animation data, but instead use an action that stores the animation data for them.
-As everything else in Blender, Actions are data-blocks.
 
-.. figure:: /images/animation_actions_data3.png
+The benefit of this approach is that animation data can be flexibly organized and reused.  For example, if you're building a library of animations (run cycles, jumps, idling, etc.), each animation can go into its own action, which can then be linked or imported into other files to be reused as needed.
 
-   Actions.
+Action Slots
+============
 
-So when you animate an object by changing its location with keyframes,
+The animation data inside an action is further organized into *Slots*.  Each slot has animation data for a single data-block, and an animated data-block must specify not only which action it uses but also which slot within that action it uses.
-the animation is saved to the Action.
 
-Each property has a channel which it is recorded to, for example,
+.. figure:: /images/animation_actions_slots_ui.png
-``Cube.location.x`` is recorded to Channel X Location.
+
-The *X location* and *Y location* properties can be shared across multiple objects,
+   Action selector and its accompanying slot selector.  **TODO: create this screenshot.**
-if all objects have *X location* and *Y location* properties beneath them.
+
+Slots allow an action to store animation data for more than one data-block at a time.  For example, you may have an animation of a bouncing ball that changes its color on each bounce.  That would involve two data-blocks: the object and its material.  Slots allow you to put both the object's animation and the material's animation in the same action by having a slot for each.
+
+.. figure:: /images/animation_actions_slots_diagram.png
+
+   Visualization of a ball and its material connected to different slots in an action.  **TODO: create this diagram.**
+
+In this example there is one slot for an object and one slot for a material, but you can have as many slots as you like for as many objects, materials, lights, etc. as you like.  If you're baking down a simulation of *100* bouncing balls, you could store that animation in single action with 100 slots.
+
+Not all actions need to take advantage of slots: you are free to use 100 separate actions for all those bouncing balls if you prefer.  Nevertheless, animation data in an action is always organized into slots, and therefore you need at least one slot in an action in order to animate something.
+
+.. note::
+
+   Internally, the animation data in an action is further organized into layers and strips.  This is not currently exposed in the UI and does not impact how you utilize actions right now.  It is purely in preparation for future animation features that are not yet in Blender, and can be safely ignored for now.
+
+   However, layers and strips *are* exposed in the Python API, so you will need to be aware of this when writing scripts and addons that work with actions.  See the Python API documentation for more details.
+
+Slot Names and Associated Types
+-------------------------------
+
+Each slot in an action has a name.  You can set these names however you like, but by default slots are named after the data-block they were initially created for.
+
+In addition to having a name, each slot also has an associated data-block type that it is intended for (for example, "material", "object", etc.).  This is set automatically when a slot is first assigned to animate a data-block.
+
+In the animation editors you can see the associated type of each slot displayed as an icon next to its name in the channel list.
+
+.. figure:: /images/animation_actions_slots_in_channel_list.png
+
+   Slots displayed in the :doc:`Dopesheet Editor's </editors/dope_sheet/introduction>` channel list, with their associated type as an icon.  **TODO: create this screenshot.**
+
+A slot must have a unique combination of name + associated type within its action.  For example, you can have two slots named "Cube" in an action as long as one of them is for objects and the other is for materials, but not if they are both for objects.
+
+.. note::
+
+   Although it's not useful, and Blender tries to make it difficult to do, it is nevertheless possible cause slots to get assigned to a data-block of the wrong type.  For example, assigning a slot intended for materials to an object.  Nothing bad happens if you manage to do this, but the F-Curves of that slot are unlikely to match any properties on the mismatched data-block, and therefore won't animate anything.
+
+F-Curves & Channels
+===================
+
+:doc:`F-Curves </editors/graph_editor/fcurves/introduction>` are the fundamental unit of animation in Blender, and are the main kind of animation data that actions contain.  Each F-Curve contains keyframes that define how a property (such as the X location of an object) should change over time.
 
 .. figure:: /images/animation_actions_keyframes.png
 
-   Graph Editor. Each channel has an F-Curve represented by the lines between the keyframes.
+   :doc:`Graph Editor</editors/graph_editor/introduction>`, displaying three F-Curves for three different properties.
 
-Actions
+Blender's animation editors (such as the dopesheet, graph editor, etc.) have a **channel list** on the left side that display animated properties.  For actions, these channels correspond to the F-Curves that animate those properties.
-   Record and contain animation data.
-Groups
-   Are groups of channels.
-Channels
-   Record properties.
-F-Curves
-   :doc:`F-Curves </editors/graph_editor/fcurves/introduction>` are used to
-   interpolate the difference between the keyframes.
-Keyframes
-   :doc:`Keyframes </animation/keyframes/introduction>` are used to
-   set the values of properties bound to a point in time.
 
-.. The hierarchy is created with the RNA data paths,
+.. figure:: /images/animation_actions_channels_and_groups.png
 
+   The :doc:`Dopesheet Editor's </editors/dope_sheet/introduction>` channel list, with the animated channels of various bones.  **TODO: create this screenshot.**
 
-.. _actions-workflow:
+Channels also support a limited form of organization called "channel groups".  For example, by default Blender creates a channel group for the channels of each bone.  These groups are purely for your convenience and have no impact on how Blender interprets or uses the channels.
 
-Working with Actions
+Working With Actions
 ====================
 
-.. figure:: /images/animation_actions_create.png
+When you first animate an object (or other data-block) in Blender, Blender tries to automatically find an appropriate action for it, or if it can't find an appropriate action then it will create one.  After assigning that action, it also creates and assigns a new slot for the data-block.
-   :align: right
 
-   The Action data-block menu.
+.. note::
+   The full heuristics Blender uses to find an appropriate action are beyond the scope of this manual, but can be summarized as: look for actions on closely related attached data-blocks.  For example, if a camera object is already animated and you're now inserting keys for its fov (which lives on the camera data, *not* the camera object), the action the object is using will be reused for the camera data as well.  For more details on these heuristics, see **TODO**.
 
-When you first animate an object by adding keyframes,
+Manually Assigning Actions and Slots
-Blender creates an *Action* to record the data.
+------------------------------------
 
-*Actions* can be managed with the *Action data-block menu*
+Rather than letting Blender automatically choose an action and slot for a data-block, you can also manually assign them.
-in the Dope Sheet :doc:`Action Editor </editors/dope_sheet/modes/action>` header,
-or the Sidebar region of the :doc:`NLA Editor </editors/nla/sidebar>`.
 
-If you are making multiple actions for the same object,
+In the properties of each data-block there is an Animation panel with action and slot selectors.  You can use these to assign actions and slots to a data-block.
-press the shield button for each action.
-This will give the actions a *Fake User* and will make Blender save the unlinked actions.
 
-Objects can only use one *Action* at a time for editing.
+.. figure:: /images/animation_actions_properties_action_slot_selector.png
-The :doc:`NLA Editor </editors/nla/index>` is used to blend multiple actions together.
 
+   The action and slot selector for Camera data in the :doc:`Properties Editor </editors/properties_editor>`.  **TODO: create this screenshot.**
+
+For the active object you can also assign its action and slot in the action Editor's header.
+
+.. figure:: /images/animation_actions_action_editor_action_slot_selector.png
+
+   The action and slot selector for the active object in the :doc:`Action Editor </editors/dope_sheet/modes/action>`.  **TODO: create this screenshot.**
+
+.. note::
+
+   When selecting a slot for a data-block, you won't necessarily see all the slots of an action listed in the dropdown.  This is because Blender limits that dropdown to the slots with an associated type that matches the data-block.
+
+When you select an action to animate a data-block, for convenience Blender will also attempt to automatically select an appropriate slot for you based on name and associated type.  If no appropriate slot is found, the slot selector will remain empty.
+
+NLA
+---
+
+Actions can also be assigned to NLA strips within a data-block's NLA system.  Please see the documentation for the :doc:`NLA Editor </editors/nla/introduction>` for how to animate data-blocks via the NLA system.
 
 .. _actions-properties:
 
-Properties
+Action Properties
-==========
+=================
 
 .. figure:: /images/animation_actions_range.png
    :align: center