From ca7add2756596f69ffce4e8f6bcb9a862b935214 Mon Sep 17 00:00:00 2001 From: Nathan Vegdahl Date: Fri, 11 Oct 2024 10:26:02 +0200 Subject: [PATCH 1/8] WIP: update Action documentation for slots, etc. --- manual/animation/actions.rst | 123 ++++++++++++++-------- manual/images/animation_actions_data3.png | 3 - 2 files changed, 82 insertions(+), 44 deletions(-) delete mode 100644 manual/images/animation_actions_data3.png diff --git a/manual/animation/actions.rst b/manual/animation/actions.rst index 4fd43d0d6..878491525 100644 --- a/manual/animation/actions.rst +++ b/manual/animation/actions.rst @@ -5,70 +5,111 @@ 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 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. -.. 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 is saved to the Action. +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. -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. **TODO: create this screenshot.** + +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 ` 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 ` 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 the 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. **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 - :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 assigning that action, it also creates and assigns a new slot for the data-block. - 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, -Blender creates an *Action* to record the data. +Manually Assigning Actions and Slots +------------------------------------ -*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 `. +Rather than letting Blender automatically choose an action and slot for a data-block, you can also manually assign them. -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. +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. -Objects can only use one *Action* at a time for editing. -The :doc:`NLA Editor ` is used to blend multiple actions together. +.. figure:: /images/animation_actions_properties_action_slot_selector.png + The action and slot selector for Camera data in the :doc:`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 `. **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 ` 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/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 -- 2.30.2 From 1156f55fe01d2d93403924b65193fa4eaaf7dc60 Mon Sep 17 00:00:00 2001 From: Nathan Vegdahl Date: Thu, 7 Nov 2024 16:07:38 +0100 Subject: [PATCH 2/8] More work on the action docs - Phrasing improvements. - Add screenshots. --- manual/animation/actions.rst | 38 +++++++++++-------- ...ons_action_editor_action_slot_selector.png | 3 ++ .../animation_actions_channels_and_groups.png | 3 ++ ...ctions_properties_action_slot_selector.png | 3 ++ ...nimation_actions_slots_in_channel_list.png | 3 ++ manual/images/animation_actions_slots_ui.png | 3 ++ 6 files changed, 37 insertions(+), 16 deletions(-) create mode 100644 manual/images/animation_actions_action_editor_action_slot_selector.png create mode 100644 manual/images/animation_actions_channels_and_groups.png create mode 100644 manual/images/animation_actions_properties_action_slot_selector.png create mode 100644 manual/images/animation_actions_slots_in_channel_list.png create mode 100644 manual/images/animation_actions_slots_ui.png diff --git a/manual/animation/actions.rst b/manual/animation/actions.rst index 878491525..f38015bc1 100644 --- a/manual/animation/actions.rst +++ b/manual/animation/actions.rst @@ -12,25 +12,31 @@ The benefit of this approach is that animation data can be flexibly organized an Action Slots ============ -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 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 which action it uses and also which slot within that action it uses, and that determines which animation data the data-block is animated by. .. figure:: /images/animation_actions_slots_ui.png - Action selector and its accompanying slot selector. **TODO: create this screenshot.** + Action selector and its accompanying slot selector in the properties of an object, for seeing and selecting which action and slot animate the object. -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. +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.png +.. figure:: /images/animation_actions_slots_diagram_object_and_material.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. +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. +.. figure:: /images/animation_actions_slots_diagram_many_objects.png + + Visualization of many balls all connected to different slots in an action. **TODO: create this diagram.** + +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 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. + 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. @@ -41,17 +47,17 @@ Each slot in an action has a name. You can set these names however you like, bu 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. +In the action editor's channel list you can see the associated type of each slot displayed as an icon next to its name. .. figure:: /images/animation_actions_slots_in_channel_list.png - Slots displayed in the :doc:`Dopesheet Editor's ` channel list, with their associated type as an icon. **TODO: create this screenshot.** + Slots displayed in the :doc:`Action Editor's ` channel list, with their associated type as an icon. 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. + 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 =================== @@ -62,18 +68,18 @@ F-Curves & Channels :doc:`Graph Editor`, displaying three F-Curves for three different properties. -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. +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. .. figure:: /images/animation_actions_channels_and_groups.png - The :doc:`Dopesheet Editor's ` channel list, with the animated channels of various bones. **TODO: create this screenshot.** + The :doc:`Dopesheet Editor's ` channel list, with the animated channels of various bones grouped under their bone names. -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. +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 the channels. Working With Actions ==================== -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. +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. .. 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**. @@ -87,13 +93,13 @@ In the properties of each data-block there is an Animation panel with action and .. figure:: /images/animation_actions_properties_action_slot_selector.png - The action and slot selector for Camera data in the :doc:`Properties Editor `. **TODO: create this screenshot.** + 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 the :doc:`Action Editor `. **TODO: create this screenshot.** + The action and slot selector for the active object (in this case a camera object) in the :doc:`Action Editor `. .. note:: 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_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_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 -- 2.30.2 From 0c6f945265ead97072a9893c6544b91e4cc4db60 Mon Sep 17 00:00:00 2001 From: Nathan Vegdahl Date: Fri, 8 Nov 2024 11:45:35 +0100 Subject: [PATCH 3/8] Add diagrams of slotted action --- manual/animation/actions.rst | 4 ++-- .../images/animation_actions_slots_diagram_many_objects.png | 3 +++ .../animation_actions_slots_diagram_object_and_material.png | 3 +++ 3 files changed, 8 insertions(+), 2 deletions(-) create mode 100644 manual/images/animation_actions_slots_diagram_many_objects.png create mode 100644 manual/images/animation_actions_slots_diagram_object_and_material.png diff --git a/manual/animation/actions.rst b/manual/animation/actions.rst index f38015bc1..502799186 100644 --- a/manual/animation/actions.rst +++ b/manual/animation/actions.rst @@ -22,13 +22,13 @@ The purpose of slots is to allow an action to store distinct animation data for .. figure:: /images/animation_actions_slots_diagram_object_and_material.png - Visualization of a ball and its material connected to different slots in an action. **TODO: create this diagram.** + 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. **TODO: create this diagram.** + 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. 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 -- 2.30.2 From 2370d9309a7391c5595cff64245ce279858795c0 Mon Sep 17 00:00:00 2001 From: Nathan Vegdahl Date: Fri, 8 Nov 2024 15:10:56 +0100 Subject: [PATCH 4/8] Add links to other parts of the documentation Also add an entry in the glossary for "Action". --- manual/animation/actions.rst | 5 +++-- manual/glossary/index.rst | 3 +++ 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/manual/animation/actions.rst b/manual/animation/actions.rst index 502799186..da5fddd31 100644 --- a/manual/animation/actions.rst +++ b/manual/animation/actions.rst @@ -5,7 +5,8 @@ Actions ******* -*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. +*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. + 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. @@ -82,7 +83,7 @@ Working With Actions 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. .. 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**. + 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 :term:`focal length ` (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**. Manually Assigning Actions and Slots ------------------------------------ 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. -- 2.30.2 From 3457e1734879c090cc41180c65e0cc072a5e65d0 Mon Sep 17 00:00:00 2001 From: Nathan Vegdahl Date: Fri, 8 Nov 2024 15:46:42 +0100 Subject: [PATCH 5/8] Address some review comments --- manual/animation/actions.rst | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/manual/animation/actions.rst b/manual/animation/actions.rst index da5fddd31..e5dd9a026 100644 --- a/manual/animation/actions.rst +++ b/manual/animation/actions.rst @@ -7,13 +7,12 @@ Actions *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. - -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 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. Action Slots ============ -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 which action it uses and also which slot within that action it uses, and that determines which animation data the data-block is animated by. +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. .. figure:: /images/animation_actions_slots_ui.png @@ -44,15 +43,15 @@ Note that slots are not "for" any specific data-block: any data-block can use an 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. +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. -In the action editor's channel list you can see the associated type of each slot displayed as an icon next to its name. +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. + Slots displayed in the :doc:`Action Editor's ` channel list, with their associated type as an icon to the right of their name. 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. @@ -88,9 +87,9 @@ When you first animate an object (or other data-block) in Blender, Blender tries Manually Assigning Actions and Slots ------------------------------------ -Rather than letting Blender automatically choose an action and slot for a data-block, you can also manually assign them. +In addition to letting Blender automatically choose an action and slot for a data-block, you can also manually assign them. -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. +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 @@ -106,7 +105,7 @@ For the active object you can also assign its action and slot in the action Edit 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. +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 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. NLA --- -- 2.30.2 From b9dbeff1c14389bd9695120846ffa943992c7fd8 Mon Sep 17 00:00:00 2001 From: Nathan Vegdahl Date: Fri, 8 Nov 2024 17:13:05 +0100 Subject: [PATCH 6/8] Address more review comments --- manual/animation/actions.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/manual/animation/actions.rst b/manual/animation/actions.rst index e5dd9a026..3e65803ec 100644 --- a/manual/animation/actions.rst +++ b/manual/animation/actions.rst @@ -53,7 +53,7 @@ One of the places you can see a slot's associated type is in the action editor's Slots displayed in the :doc:`Action Editor's ` channel list, with their associated type as an icon to the right of their name. -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. +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:: @@ -74,7 +74,7 @@ Blender's animation editors (such as the dopesheet, graph editor, etc.) have a * The :doc:`Dopesheet Editor's ` channel list, with the animated channels of various bones grouped under their bone names. -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 the channels. +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 ==================== @@ -87,7 +87,7 @@ When you first animate an object (or other data-block) in Blender, Blender tries 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. +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. @@ -105,7 +105,7 @@ For the active object you can also assign its action and slot in the action Edit 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 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. +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 --- -- 2.30.2 From 8687e22277bd8188c855fcd1b595a359ac6dfef4 Mon Sep 17 00:00:00 2001 From: Nathan Vegdahl Date: Mon, 11 Nov 2024 10:53:44 +0100 Subject: [PATCH 7/8] Hard wrap text --- manual/animation/actions.rst | 160 ++++++++++++++++++++++++++++------- 1 file changed, 128 insertions(+), 32 deletions(-) diff --git a/manual/animation/actions.rst b/manual/animation/actions.rst index 3e65803ec..b64387484 100644 --- a/manual/animation/actions.rst +++ b/manual/animation/actions.rst @@ -5,112 +5,208 @@ Actions ******* -*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. +*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. -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 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. Action Slots ============ -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. +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. .. 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. + 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. +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. + 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. +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. +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 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. + 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. + 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. +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. +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. +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. + 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". +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. + 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. +: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 - :doc:`Graph Editor`, displaying three F-Curves for three different properties. + :doc:`Graph Editor`, displaying three + F-Curves for three different properties. -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. +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. .. 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. + The :doc:`Dopesheet Editor's ` channel + list, with the animated channels of various bones grouped under their bone + names. -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. +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 ==================== -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. +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. .. 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 :term:`focal length ` (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**. + 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 :term:`focal length ` + (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**. 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. +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. +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 `. + 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. +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 `. + 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 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. +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 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: -- 2.30.2 From 94ad131f12e2c856176963292cfd6abd71c9ca07 Mon Sep 17 00:00:00 2001 From: Nathan Vegdahl Date: Mon, 11 Nov 2024 11:35:10 +0100 Subject: [PATCH 8/8] Spell out the action re-use heuristics in more detail --- manual/animation/actions.rst | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/manual/animation/actions.rst b/manual/animation/actions.rst index b64387484..0f3879040 100644 --- a/manual/animation/actions.rst +++ b/manual/animation/actions.rst @@ -150,14 +150,26 @@ 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. +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. + +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. + .. 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 :term:`focal length ` - (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**. + 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. + Manually Assigning Actions and Slots ------------------------------------ -- 2.30.2