# Explaining Action Bindings

This document is a work in progress, to get a good explanation of Action Bindings.

Once that explanation is in place, we can either confirm the term 'bindings' or choose another term. Until then, the explanation uses `${BINDING}`/`${BINDINGS}` to indicate that this is still fluid.

## Goals

- Understandable by Blender animators and Blender users in general.
- Understandable by non-Blender animators?
- Does not require understanding legacy Actions.
- Does not require deep understanding of Blender's data model (beyond data-block types like Object, Armature, Mesh, etc, but even requiring that is questionable as people may refer to an Armature Object as "the Armature", a Mesh Object as "the mesh", etc.)

## Current explanation of Actions

The [Blender 4.1 manual](https://docs.blender.org/manual/en/4.1/animation/actions.html) reads:

> When animating objects and properties in Blender, Actions record and contain the data. As everything else in Blender, Actions are data-blocks.
>
> 
>
> So when you animate an object by changing its location with keyframes, the animation is saved to the Action.
>
> 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.
>
> 
> Image annotation: *Graph Editor. Each channel has an F-Curve represented by the lines between the keyframes.*
>
> Actions
> : Record and contain animation data.
>
> Groups
> : Are groups of channels.
>
> Channels
> : Record properties.
>
> F-Curves
> : [F-Curves](https://docs.blender.org/manual/en/4.1/editors/graph_editor/fcurves/introduction.html) are used to interpolate the difference between the keyframes.
>
> Keyframes
> : [Keyframes](https://docs.blender.org/manual/en/4.1/animation/keyframes/introduction.html) are used to set the values of properties bound to a point in time.

The manual then continues to explain how to work with Actions. The above seems to be the only explanation as to what Actions *are*.

Pros of the current explanation:
: - Simple explanation.
- Concrete example.
- Has a definition of terms.

Cons of the current explanation:
: - Limited to explaining the animation of Objects. The title of the first image says Actions can also animate Scenes, but that's it. No mention of animating object data, materials, nodes, etc. Not included in the above-quoted text, but also the "[Working with Actions](https://docs.blender.org/manual/en/4.1/animation/actions.html#working-with-actions)" section in the manual is very Object-oriented (pun very much intended).
- The word "data-block" should be a link to a section that explains what data-blocks are.
- Some if-you-read-carefully errors, like "*Actions record and contain the data*"; the Actions themselves don't do the recording.
- Reading the definition of terms top to bottom, the "Channels" term is used before it is defined.
- "Channels" and "F-Curves" are defined as if they are entirely different things for different purposes, instead of one being the most common form of the other. The words may have different technical implementations, pointing to different places in the source code, but that shouldn't matter for the manual.
- Uses "keyframes" where "keys" is the more appropriate term (IMO - Sybren).
- Does not explain what happens when multiple data-blocks use the same Action.
- Does not explain that Actions are tied to the data-block type they were first assigned to.

## Explanation #1

Just a list of points I (Sybren) want to express. No precise wording yet.

- An Action contains the animation for one or more data-blocks.
- To tell the animation for each data-block apart, Actions are divided into `${BINDINGS}`.
- Data-blocks point at what Action they are animated by, and what `${BINDING}` has the animation they're interested in.
- It is **not** the Action that chooses what to animate.

### ChatGPT expansion

ChatGPT expands the above to:

### Actions and Bindings in Blender Animation

In Blender, an Action is a container that holds the animation data for one or more data-blocks. Data-blocks in Blender represent various types of data such as objects, bones, or materials, which can all be animated.

#### Dividing Actions with Bindings

To differentiate the animations for each data-block within an Action, the concept of `${BINDINGS}` is used. Each `${BINDING}` within an Action corresponds to a specific data-block, allowing for organized and precise animation control. This division ensures that animations for different data-blocks do not interfere with each other and can be managed separately.

#### Linking Data-blocks to Actions and Bindings

Data-blocks are linked to Actions to define their animations. Each data-block points to the Action that contains its animation data and specifies which `${BINDING}` within that Action it uses. This setup allows for a flexible animation system where multiple data-blocks can share the same Action but still have distinct animations through their respective `${BINDINGS}`.

#### Action Independence

It is important to note that an Action itself does not decide what it will animate. Instead, it is the data-blocks that reference an Action and choose the appropriate `${BINDING}` to define their animation. This design provides a clear separation between the animation data and the entities being animated, allowing for better management and reuse of animations across different data-blocks.

By understanding the relationship between Actions, `${BINDINGS}`, and data-blocks, animators can efficiently organize and control complex animations within Blender.

## Explanation #2

Same as Explanation #1 above, but then with the added notion that `${BINDINGS}` can be shared.

- An Action contains the animation for one or more data-blocks.
- To tell the animation for each data-block apart, Actions are divided into `${BINDINGS}`.
- Data-blocks point at what Action they are animated by, and what `${BINDING}` has the animation they're interested in.
- It is **not** the Action that chooses what to animate.
- Multiple data-blocks can share the same Action and the same `${BINDING}`. In that case they will be animated identically. This is a corner case though, and not expected to be widely used.

### ChatGPT expansion

### Actions and Bindings in Blender Animation

In Blender, an Action is a container that holds the animation data for one or more data-blocks. Data-blocks in Blender represent various types of data such as objects, bones, or materials, which can all be animated.

#### Dividing Actions with Bindings

To differentiate the animations for each data-block within an Action, the concept of `${BINDINGS}` is used. Each `${BINDING}` within an Action corresponds to a specific data-block, allowing for organized and precise animation control. This division ensures that animations for different data-blocks do not interfere with each other and can be managed separately.

#### Linking Data-blocks to Actions and Bindings

Data-blocks are linked to Actions to define their animations. Each data-block points to the Action that contains its animation data and specifies which `${BINDING}` within that Action it uses. This setup allows for a flexible animation system where multiple data-blocks can share the same Action but still have distinct animations through their respective `${BINDINGS}`.

#### Action Independence

It is important to note that an Action itself does not decide what it will animate. Instead, it is the data-blocks that reference an Action and choose the appropriate `${BINDING}` to define their animation. This design provides a clear separation between the animation data and the entities being animated, allowing for better management and reuse of animations across different data-blocks.

#### Sharing Bindings Across Data-blocks

In some cases, multiple data-blocks can share the same `${BINDING}`. When this occurs, the data-blocks will be animated identically, as they are referencing the same set of animation data within the Action. However, sharing the same `${BINDING}` is considered a corner case and is not expected to be widely used. It can be useful in specific scenarios where identical animation across multiple data-blocks is desired.

By understanding the relationship between Actions, `${BINDINGS}`, and data-blocks, animators can efficiently organize and control complex animations within Blender.

## Name for the 'Binding' concept

Some alternatives, in no particular order.

- Binding
- Division
- Lane
- Pairing
- Part (like a music score)
- Partition
- Section
- Slot
- Subject (like 'of an email' but also like 'of a story')
- Subset
- Topic
- Track