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 +6 -2
2 changed files with 6 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 2370d9309a - Show all commits

5
manual/animation/actions.rst
View File

@ -5,7 +5,8 @@
Actions
*******
nathanvegdahl marked this conversation as resolved
Sybren A. Stüvel commented 2024-11-04 11:45:05 +01:00
Review
Copy Link

Not sure if the glossary entry for 'Action' already links here, but might be worth checking & adding if it doesn't.

Not sure if the glossary entry for 'Action' already links here, but might be worth checking & adding if it doesn't.
👍 1
Nathan Vegdahl commented 2024-11-08 17:14:24 +01:00
Review
Copy Link

Added a glossary entry for "Action" and made it link back here.

Added a glossary entry for "Action" and made it link back here.
*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 <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
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
@ -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::
nathanvegdahl marked this conversation as resolved Outdated
Sybren A. Stüvel commented 2024-11-08 11:44:22 +01:00
Outdated
Review
Copy Link

The full heuristics Blender uses to find an appropriate action are beyond the scope of this manual

I think it's good to explain why. Even when this heuristic might change in the future, I don't see it being in constant flux, and thus IMO it would be fine to just explain how it works.

its fov

Use proper puncuation to indicate this is an abbreviation, and make it link to the glossary. Or just write "Field of View". And link it to the glossary.

> The full heuristics Blender uses to find an appropriate action are beyond the scope of this manual I think it's good to explain why. Even when this heuristic might change in the future, I don't see it being in constant flux, and thus IMO it would be fine to just explain how it works. > its fov Use proper puncuation to indicate this is an abbreviation, and make it link to the glossary. Or just write "Field of View". And link it to the glossary.
👍 1
Nathan Vegdahl commented 2024-11-08 16:41:04 +01:00
Outdated
Review
Copy Link

I don't see it being in constant flux, and thus IMO it would be fine to just explain how it works.

I agree it's unlikely to change much, if at all. The reason I left it out of scope is because of how detailed the heuristics are (basically a table of which data-blocks are considered related and when), and knowing the details doesn't seem important to normal usage...? Where the specific details become more relevant is when doing scripting that interacts with this, I think?

So instead I opted to give the broad idea behind it, and refer people elsewhere for people who do need the details. Although as is clear from the todo, I don't know where yet. But I agree that it should be documented somewhere.

> I don't see it being in constant flux, and thus IMO it would be fine to just explain how it works. I agree it's unlikely to change much, if at all. The reason I left it out of scope is because of how detailed the heuristics are (basically a table of which data-blocks are considered related and when), and knowing the details doesn't seem important to normal usage...? Where the specific details become more relevant is when doing scripting that interacts with this, I think? So instead I opted to give the broad idea behind it, and refer people elsewhere for people who do need the details. Although as is clear from the todo, I don't know where yet. But I agree that it should be documented *somewhere*.
Nathan Vegdahl commented 2024-11-11 10:58:30 +01:00
Outdated
Review
Copy Link

Re: explaining the related data-blocks: after sleeping on it over the weekend, I think I've come around to explaining this in a bit more detail, and then we can get rid of the TODO to link it. I'll try to explain it as concisely as I can without turning it into a table. It probably won't be fully detailed, but should give enough info for users to predict what will happen in typical cases.

Re: explaining the related data-blocks: after sleeping on it over the weekend, I think I've come around to explaining this in a bit more detail, and then we can get rid of the TODO to link it. I'll try to explain it as concisely as I can without turning it into a table. It probably won't be fully detailed, but should give enough info for users to predict what will happen in typical cases.
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 <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
------------------------------------

3
manual/glossary/index.rst
View File

@ -18,6 +18,9 @@ This page lists definitions for terms used in Blender and this manual.
See also :ref:`selection states <object-active>`.
:doc:`Action </animation/actions>`
Blender's container for animation data. In Blender, animatable :term:`data-blocks <Data-Block>` 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.