diff --git a/manual/animation/actions.rst b/manual/animation/actions.rst index 4fd43d0d6..0f3879040 100644 --- a/manual/animation/actions.rst +++ b/manual/animation/actions.rst @@ -5,70 +5,225 @@ Actions ******* -When animating objects and properties in Blender, Actions record and contain the data. -As everything else in Blender, Actions are data-blocks. +*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 :term:`data-blocks ` +(:doc:`objects `, +:doc:`meshes `, +:doc:`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. -.. figure:: /images/animation_actions_data3.png +Actions are also data-blocks themselves, and therefore can be easily appended or +linked into other blend files. This lets actions be used not just for storage, +but also for organizing and reusing animation data. 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 conveniently linked or +exported as a distinct animation. - Actions. +Action Slots +============ -So when you animate an object by changing its location with keyframes, -the animation is saved to the Action. +The animation data inside an action is further organized into *Slots*. Each +action has a set of slots and different animation data for each of those slots. +An animated data-block then specifies both an action and a slot within that +action, and that determines which animation data the data-block is animated by. -Each property has a channel which it is recorded to, for example, -``Cube.location.x`` is recorded to Channel X Location. -The *X location* and *Y location* properties can be shared across multiple objects, -if all objects have *X location* and *Y location* properties beneath them. +.. figure:: /images/animation_actions_slots_ui.png + + Action selector and its accompanying slot selector in the properties of an + object, for seeing and selecting which action and slot animate the object. + +The purpose of slots is to allow an action to store distinct animation data for +multiple data-blocks. For example, you may have an animation of a bouncing ball +that changes its color on each bounce, and that involves 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 different slot for each. + +.. figure:: /images/animation_actions_slots_diagram_object_and_material.png + + Visualization of a ball and its material connected to different slots in an + action. + +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. + +.. figure:: /images/animation_actions_slots_diagram_many_objects.png + + Visualization of many balls all connected to different slots in an action. + +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, the +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 that slots are not "for" any specific data-block: any data-block can use +any slot. For example, you can have two different characters use the same slot +in the same action, and they'll both simply get animated by the same animation +data. Slots are just a way to organize distinct animation data within an action, +and don't have any intrinsic attachment to anything in the scene. + +.. 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 use actions right now. It is purely in preparation for future animation + features that are not yet in Blender, and you can safely ignore it 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, and you are free to name them whatever you +like. 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. + +One of the places you can see a slot's associated type is in the action editor's +channel list, where it's displayed as an icon next to the slot's name. + +.. figure:: /images/animation_actions_slots_in_channel_list.png + + Slots displayed in the :doc:`Action Editor's ` + channel list, with their associated type as an icon to the right of their name. + +Within an action, a slot must have a unique combination of name + associated +type. 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. When they are both for objects, their associated type is the +same, and thus they must have different names. In that case Blender will use the +familiar approach and name them "Cube" and "Cube.001". + +.. note:: + + Although it's not useful, and Blender makes this difficult to do, it is + nevertheless possible to 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 ` 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`, displaying three + F-Curves for three different properties. -Actions - Record and contain animation data. -Groups - Are groups of channels. -Channels - Record properties. -F-Curves - :doc:`F-Curves ` are used to - interpolate the difference between the keyframes. -Keyframes - :doc:`Keyframes ` are used to - set the values of properties bound to a point in time. +Blender's animation editors (such as the dopesheet, graph editor, etc.) have a +**channel list** on their left side that display animated properties. For +actions, these channels correspond to the F-Curves that animate those +properties. -.. The hierarchy is created with the RNA data paths, +.. figure:: /images/animation_actions_channels_and_groups.png + The :doc:`Dopesheet Editor's ` channel + list, with the animated channels of various bones grouped under their bone + names. -.. _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. There are a few features in Blender that rely on the groups, but mostly +they are just for your convenience. -Working with Actions +Working With Actions ==================== -.. figure:: /images/animation_actions_create.png - :align: right +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 an action has been assigned, +it also creates and assigns a new slot for the data-block. - The Action data-block menu. +Blender uses heuristics to try to find an appropriate action, based on the +idea that animation of closely related data-blocks should typically go in the +same action. For example, an object and its data are considered closely related, +so if a camera object is already animated and you insert keys for its +:term:`focal length ` (which lives on the camera data, *not* the +camera object), the action that's assigned to the object will be reused for the +camera data as well. These relationships go both ways, so the action will also +be reused when keying the camera object if the camera data is already animated. -When you first animate an object by adding keyframes, -Blender creates an *Action* to record the data. +Some examples of other data-blocks that are considered closely related for this +purpose are: materials and their embedded node trees, worlds and their embedded +node trees, and meshes and their shape key data. -*Actions* can be managed with the *Action data-block menu* -in the Dope Sheet :doc:`Action Editor ` header, -or the Sidebar region of the :doc:`NLA Editor `. +.. note:: + There is an exception to this "closely related" heuristic, which is when a + data-block has more than one user. For example, if a single mesh data-block + is used by multiple mesh objects, then the relationship is ignored and the + mesh data and its users will get separate actions despite otherwise being + considered closely related. -If you are making multiple actions for the same object, -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. -The :doc:`NLA Editor ` is used to blend multiple actions together. +Manually Assigning Actions and Slots +------------------------------------ +In addition to letting Blender automatically choose an action and slot for a +data-block, you can also manually assign them. This can be used to assign +existing animation to a data-block by selecting both the action and slot. It can +also be used to specify an action for a data-block's keys to go into, by +assigning the action but leaving the slot blank, in which case a new slot will +be created when the first key is set. + +For each data-block in the properties editor there is an Animation panel with +action and slot selectors. You can use these to assign actions and slots to a +data-block. + +.. figure:: /images/animation_actions_properties_action_slot_selector.png + + The action and slot selector for Camera data in the + :doc:`Properties Editor `. + +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 this case a camera object) in the + :doc:`Action Editor `. + +.. 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 +attempts to automatically select an appropriate slot for you based on name and +associated type. If no appropriate slot is found then the slot selector will +remain empty, in which case you can manually select an existing slot, create a +new one, or just start keying and let Blender automatically create a new slot +for you. If Blender assigns a slot you didn't want, you can select another slot +manually or simply clear the slot selection. + +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 ` +for how to animate data-blocks via the NLA system. .. _actions-properties: -Properties -========== +Action Properties +================= .. figure:: /images/animation_actions_range.png :align: center diff --git a/manual/glossary/index.rst b/manual/glossary/index.rst index 2e2814324..6931e7048 100644 --- a/manual/glossary/index.rst +++ b/manual/glossary/index.rst @@ -18,6 +18,9 @@ This page lists definitions for terms used in Blender and this manual. See also :ref:`selection states `. + :doc:`Action ` + Blender's container for animation data. In Blender, animatable :term:`data-blocks ` do not store their own animation data, but instead store their animation data an actions. + Action Safe Area of the screen visible on most devices. Place content inside it to ensure it does not get cut off. diff --git a/manual/images/animation_actions_action_editor_action_slot_selector.png b/manual/images/animation_actions_action_editor_action_slot_selector.png new file mode 100644 index 000000000..651dd97f7 --- /dev/null +++ b/manual/images/animation_actions_action_editor_action_slot_selector.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c90a4e1dfc0a008e04fecf6c6aa49487fce3fae409d9164d63271c3e01fd1fbd +size 6115 diff --git a/manual/images/animation_actions_channels_and_groups.png b/manual/images/animation_actions_channels_and_groups.png new file mode 100644 index 000000000..09e359c0d --- /dev/null +++ b/manual/images/animation_actions_channels_and_groups.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:03a531a891940c63a07360776dad4422fee53fbaed6f52a2494f3c8d9bad3810 +size 24837 diff --git a/manual/images/animation_actions_data3.png b/manual/images/animation_actions_data3.png deleted file mode 100644 index f159604e1..000000000 --- a/manual/images/animation_actions_data3.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:e6f8474335df7c06ac5eed9b654f70c89810e76518d47b1fd80d5135d5ebcba4 -size 1757 diff --git a/manual/images/animation_actions_properties_action_slot_selector.png b/manual/images/animation_actions_properties_action_slot_selector.png new file mode 100644 index 000000000..cf4c1d334 --- /dev/null +++ b/manual/images/animation_actions_properties_action_slot_selector.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:aef01208eda1f2aa556ecce561598daafc230fe6b341866dafb8da4494bc91ed +size 5704 diff --git a/manual/images/animation_actions_slots_diagram_many_objects.png b/manual/images/animation_actions_slots_diagram_many_objects.png new file mode 100644 index 000000000..6ceff58d0 --- /dev/null +++ b/manual/images/animation_actions_slots_diagram_many_objects.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a09c92e1ddd9335b80e54a39d229bc717695dbaea7eda79085ab895d37a08471 +size 27759 diff --git a/manual/images/animation_actions_slots_diagram_object_and_material.png b/manual/images/animation_actions_slots_diagram_object_and_material.png new file mode 100644 index 000000000..26540241f --- /dev/null +++ b/manual/images/animation_actions_slots_diagram_object_and_material.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:eb58d8adec25e8ba3c715137be2edbeb0a4951c3b327ee33b3262402b84a6783 +size 16282 diff --git a/manual/images/animation_actions_slots_in_channel_list.png b/manual/images/animation_actions_slots_in_channel_list.png new file mode 100644 index 000000000..3bcf233d0 --- /dev/null +++ b/manual/images/animation_actions_slots_in_channel_list.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:051fca1112aea61313ea3830b56e55726cd54e224d00be0c39b51f24dd4d8719 +size 9664 diff --git a/manual/images/animation_actions_slots_ui.png b/manual/images/animation_actions_slots_ui.png new file mode 100644 index 000000000..7fdab9045 --- /dev/null +++ b/manual/images/animation_actions_slots_ui.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5ec7d21feff208bb89d85e2f6bb0552ffeb8e64b95eec7ead5326ea7f0c63c4a +size 7104