Additive blending within animation graphs

[aecsocket]

Objective

Expands on #15013 by adding the concept of additive animation graph nodes. These nodes do not share weight with other nodes in the same graph, and instead are applied with the raw weight of its node. For example, if an additive node has weight 1.0, its animation clip will always be applied with a weight of 1.0, regardless of if there are other nodes which have a weight > 0. This can be used to implement animations which play "on top of" other animations, i.e. a punching animation (additive) on top of movement (shared weight between idle/walk/run/..).

Solution

Adds the concept of additive animation nodes, and API to add these nodes to an AnimationGraph.

Testing

I used this implementation of additive blending in my own project, and it works.

Outstanding concerns

Before this exits draft stage:

• What are we calling non-additive nodes? Shared weight? Blended? (Although the term "blend node" already has a specific meaning, so I think we should avoid this)
• What should happen if you put non-additive nodes under an additive node?
• For both of the above points, this should be included in the AnimationGraphNode::additive docs.
• The AnimationGraph API for adding nodes is getting quite complex, with a lot of permutations of:
  • add_clip
  • add_blend
  • ..with_mask
  • ..additive
  • Perhaps this should be unified somehow?
  • Should be done in a separate PR
• Does adding unit tests for this make sense?
  • Additive blending within animation graphs #15198 (comment)
• What should be added to the examples to demo this feature?
  • Added additive toggle checkbox to all the clip nodes in the animation_graph example
• This adds a new field additive to serialized animgraph.ron files. Do we need to set a default for this for old animgraph files which don't have this field yet? Does this count as a breaking change?
  • This is a breaking change for existing graph files, but we shouldn't add a default, since there aren't a lot of animgraph files in the wild - Additive blending within animation graphs #15198 (comment)

---

Showcase

The AnimationGraph API now supports additive animation nodes. Additive nodes don't share weight with other nodes in the same graph, so their full weight will be applied to the animation. This is useful for when you want to layer an animation on top of another animation without it reducing the intensity of the animation underneath - for example, playing a punching animation on top of your base idle or movement animation.

The animation_graph example now includes checkboxes for each animation clip node, which allows toggling whether that node is additive or not. You can use this to preview how additive blending works.

Migration Guide

Existing animgraph.ron files must have the additive boolean field added to each animation graph node. Setting this field to false emulates the existing behavior of sharing weight across all nodes.

[pcwalton]

What are we calling non-additive nodes? Shared weight? Blended? (Although the term "blend node" already has a specific meaning, so I think we should avoid this)

Godot just calls them blend nodes, so I think it's fine to use that. See AnimationNodeAdd2 vs. AnimationNodeBlend2.

What should happen if you put non-additive nodes under an additive node?

I'm not sure right now; don't have time to think about it. Definitely research into what other engines do would be helpful.

The AnimationGraph API for adding nodes is getting quite complex

Perhaps a builder API might be better, but I think that should be done as a follow-up.

Does adding unit tests for this make sense?

It'd be nice, but I won't block this PR on it :)

What should be added to the examples to demo this feature?

I'd add "Additive" check boxes to the graph nodes in the animation_graph examples.

This adds a new field additive to serialized animgraph.ron files. Do we need to set a default for this for old animgraph files which don't have this field yet? Does this count as a breaking change?

Yes, it's a breaking change. I don't think we need to go out of our way to support old animgraph.ron files as I doubt there are many of them in the wild.

[aecsocket]

I've added the additive toggle checkboxes to the animation_graph example, although I think additive animation isn't working properly, since it seems to barely make a difference. I'll have to keep investigating this.

What are we calling non-additive nodes? Shared weight? Blended? (Although the term "blend node" already has a specific meaning, so I think we should avoid this)

Godot just calls them blend nodes, so I think it's fine to use that. See AnimationNodeAdd2 vs. AnimationNodeBlend2.

I don't like this because we already have a concept called a "blend node", which is an animation graph node without an associated animation clip. If I say "blend node", does this refer to a node without an animation clip (but unspecified additive/not-additive), or does this refer to a non-additive node (which may have an animation clip or not)?

[pcwalton]

@aecsocket I'd call the three types of node "clip nodes", "blend nodes", and "additive blend nodes". I don't think that's particularly ambiguous. If we need to disambiguate between the last two, though, we could call them "interpolating blend nodes" and "additive blend nodes".