blender/blender-manual
23
23
Fork 104
Code Issues 74 Pull Requests 6 Projects 1 Releases Wiki Activity

Update Action documentation #104974

Merged
Nathan Vegdahl merged 8 commits from nathanvegdahl/blender-manual:slotted_actions into main 2024-11-11 15:52:29 +01:00
Conversation 3 Commits 8 Files Changed 10 +8 -9
1 changed files with 8 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 3457e17348 - Show all commits

17
manual/animation/actions.rst
View File

@ -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 <Data-Block>` (:doc:`objects </scene_layout/object/introduction>`, :doc:`meshes </modeling/meshes/introduction>`, :doc:`materials </render/materials/introduction>`, 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 <Data-Block>` (:doc:`objects </scene_layout/object/introduction>`, :doc:`meshes </modeling/meshes/introduction>`, :doc:`materials </render/materials/introduction>`, 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.
nathanvegdahl marked this conversation as resolved Outdated
Sybren A. Stüvel commented 2024-11-04 11:44:41 +01:00
Outdated
Review
Copy Link

It may help to keep the word Action capitalised, to emphasise that it's the name of a data-block, rather than a normal noun. No strong preference though, and the rest of the text consistently uses 'normal case'.

When talking about meshes, materials, and shading, add a link to the relevant chapter of the documentation.

data-blocks

Link to the glossary

And as a meta-thing: maybe it's a good idea to rewrap paragraphs instead of having them as long sentences, if anything it'll make reviewing the PR easier (with Gitea's one-note-per-line limitation).

It may help to keep the word Action capitalised, to emphasise that it's the name of a data-block, rather than a normal noun. No strong preference though, and the rest of the text consistently uses 'normal case'. When talking about meshes, materials, and shading, add a link to the relevant chapter of the documentation. ------ > data-blocks Link to the glossary ------ And as a meta-thing: maybe it's a good idea to rewrap paragraphs instead of having them as long sentences, if anything it'll make reviewing the PR easier (with Gitea's one-note-per-line limitation).
👍 1
Nathan Vegdahl commented 2024-11-08 15:55:43 +01:00
Outdated
Review
Copy Link

Good point about the wrapping. I'll do that after I've addressed the rest of your comments.

Re: keeping Action capitalized, I agree and actually initially wrote it that way. I changed it to be consistent with the rest of the manual (I didn't read the whole manual, but checked a handful of randomly selected pages, and none of them capitalized things that way), which I think is more important. Might be something to change throughout the manual at some point.

Good point about the wrapping. I'll do that after I've addressed the rest of your comments. Re: keeping Action capitalized, I agree and actually initially wrote it that way. I changed it to be consistent with the rest of the manual (I didn't read the whole manual, but checked a handful of randomly selected pages, and none of them capitalized things that way), which I think is more important. Might be something to change throughout the manual at some point.
👍 1
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.
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.
nathanvegdahl marked this conversation as resolved Outdated
Sybren A. Stüvel commented 2024-11-08 11:46:51 +01:00
Outdated
Review
Copy Link

Add that an Action is also a data-block, and thus that it can be appended/linked to other files.

Add that an Action is also a data-block, and thus that it can be appended/linked to other files.
👍 1
Action Slots 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.
nathanvegdahl marked this conversation as resolved Outdated
Sybren A. Stüvel commented 2024-11-07 16:21:11 +01:00
Outdated
Review
Copy Link

The combination of "both" and "and also" seems a bit much, especially with the doubling of "it uses". Maybe just "…specifies both an action and a slot within that action, and that determines…"?

The combination of "both" and "and also" seems a bit much, especially with the doubling of "it uses". Maybe just "…specifies both an action and a slot within that action, and that determines…"?
👍 1
.. figure:: /images/animation_actions_slots_ui.png .. 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 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.
nathanvegdahl marked this conversation as resolved Outdated
Sybren A. Stüvel commented 2024-11-08 11:31:45 +01:00
Outdated
Review
Copy Link

You can set these names however you like, but by default slots are named after the data-block they were initially created for.

I'd split this up into two sentences, as the "but" implies some [I can't come up with the right word here. Conflct? Negativity?] that simply doesn't exist.

> You can set these names however you like, but by default slots are named after the data-block they were initially created for. I'd split this up into two sentences, as the "but" implies some [I can't come up with the right word here. Conflct? Negativity?] that simply doesn't exist.
👍 1
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.
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.
dr.sybren marked this conversation as resolved Outdated
Sybren A. Stüvel commented 2024-11-08 11:32:35 +01:00
Outdated
Review
Copy Link

This is also shown in the side-panel of the Action editor, whenever there is an active Slot.

This is also shown in the side-panel of the Action editor, whenever there is an active Slot.
👍 1
Nathan Vegdahl commented 2024-11-08 15:32:01 +01:00
Outdated
Review
Copy Link

That's true, but I wasn't meaning to be exhaustive here, but rather give one place that this is visible to help illustrate the concept. I'll try rephrasing to make that clearer.

That's true, but I wasn't meaning to be exhaustive here, but rather give one place that this is visible to help illustrate the concept. I'll try rephrasing to make that clearer.
.. figure:: /images/animation_actions_slots_in_channel_list.png .. figure:: /images/animation_actions_slots_in_channel_list.png
Slots displayed in the :doc:`Action Editor's </editors/dope_sheet/modes/action>` channel list, with their associated type as an icon. Slots displayed in the :doc:`Action Editor's </editors/dope_sheet/modes/action>` 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. 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.
nathanvegdahl marked this conversation as resolved Outdated
Sybren A. Stüvel commented 2024-11-08 11:36:53 +01:00
Outdated
Review
Copy Link

A slot must have a unique combination of name + associated type within its action.

This is a bit ambiguous, as it can be read as (name) + (associated type within its action). Maybe it's better to elaborate a bit more, at the cost of some repetition (which in itself might be good, as this is a complex topic until it clicks). How's this?

"As described above, each slot has a name and an associated type. This combination of name + type has to be unique within its action."

but not if they are both for objects.

It might help to clarify things when you describe the 'positive case' here. So instead of saying that it doesn't work when they are both for object, explain what it would look like if that were the case. Something like:

"When they are both for objects, their associated type is the same, and thus they have to have different names. Blender will use the familiar approach and name them Cube and Cube.001."

Actually, I think you can keep the 'it doesn't work when they are both for object' text, and just add the above as well.

> A slot must have a unique combination of name + associated type within its action. This is a bit ambiguous, as it can be read as (name) + (associated type within its action). Maybe it's better to elaborate a bit more, at the cost of some repetition (which in itself might be good, as this is a complex topic until it clicks). How's this? "As described above, each slot has a name and an associated type. This combination of name + type has to be unique within its action." > but not if they are both for objects. It might help to clarify things when you describe the 'positive case' here. So instead of saying that it doesn't work when they are both for object, explain what it would look like if that were the case. Something like: "When they are both for objects, their associated type is the same, and thus they have to have different names. Blender will use the familiar approach and name them `Cube` and `Cube.001`." Actually, I think you can keep the 'it doesn't work when they are both for object' text, and just add the above as well.
👍 1
Nathan Vegdahl commented 2024-11-08 16:46:10 +01:00
Outdated
Review
Copy Link

This is a bit ambiguous, as it can be read as (name) + (associated type within its action).

Ah! Good catch. I think it can be fixed by just rearranging the clauses: "Within an action, a slot must have a unique combination of name + associated type."

> This is a bit ambiguous, as it can be read as (name) + (associated type within its action). Ah! Good catch. I think it can be fixed by just rearranging the clauses: "Within an action, a slot must have a unique combination of name + associated type."
@ -88,9 +87,9 @@ When you first animate an object (or other data-block) in Blender, Blender tries
Manually Assigning Actions and Slots 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.
nathanvegdahl marked this conversation as resolved Outdated
Sybren A. Stüvel commented 2024-11-08 11:47:28 +01:00
Outdated
Review
Copy Link

"Rather than" → "In addition to"

"Rather than" → "In addition to"
👍 1
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.
nathanvegdahl marked this conversation as resolved Outdated
Sybren A. Stüvel commented 2024-11-08 11:48:22 +01:00
Outdated
Review
Copy Link

In the properties of each data-block

This is not true. We've only added them to the Properties editor, which doesn't include every data-block type.

> In the properties of each data-block This is not true. We've only added them to the Properties editor, which doesn't include every data-block type.
👍 1
Nathan Vegdahl commented 2024-11-08 15:43:27 +01:00
Outdated
Review
Copy Link

That's what I was intending to get across, but clearly failed, ha ha. I'll try rephrasing to make that clearer, without getting too verbose.

That's what I was intending to get across, but clearly failed, ha ha. I'll try rephrasing to make that clearer, without getting too verbose.
nathanvegdahl marked this conversation as resolved Outdated
Sybren A. Stüvel commented 2024-11-08 11:49:14 +01:00
Outdated
Review
Copy Link

Add an explanation as to why you would do this. Also include that you can assign an action but keep the slot unassigned, and what you'd use that for.

Add an explanation as to _why_ you would do this. Also include that you can assign an action but keep the slot unassigned, and what you'd use that for.
👍 1
.. figure:: /images/animation_actions_properties_action_slot_selector.png .. 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 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.
nathanvegdahl marked this conversation as resolved Outdated
Sybren A. Stüvel commented 2024-11-08 11:50:00 +01:00
Outdated
Review
Copy Link

Add what to do in this case. Something like "You can then create a new slot yourself, or just start keying to let Blender create it for you".

Add what to do in this case. Something like "You can then create a new slot yourself, or just start keying to let Blender create it for you".
👍 1
NLA NLA
--- ---