Implement the AnimationGraph, allowing for multiple animations to be blended together.

[pcwalton]

This is an implementation of RFC #51: https://github.com/bevyengine/rfcs/blob/main/rfcs/51-animation-composition.md

Note that the implementation strategy is different from the one outlined in that RFC, because two-phase animation has now landed.

Objective

Bevy needs animation blending. The RFC for this is RFC 51.

Solution

This is an implementation of the RFC. Note that the implementation strategy is different from the one outlined there, because two-phase animation has now landed.

This is just a draft to get the conversation started. Currently we're missing a few things:

• A fully-fleshed-out mechanism for transitions
• A serialization format for AnimationGraphs
• Examples are broken, other than animated_fox
• Documentation

---

Changelog

Added

• The AnimationPlayer has been reworked to support blending multiple animations together through an AnimationGraph, and as such will no longer function unless a Handle<AnimationGraph> has been added to the entity containing the player. See RFC 51 for more details.

• Transition functionality has moved from the AnimationPlayer to a new component, AnimationTransitions, which works in tandem with the AnimationGraph.

Migration Guide

• AnimationPlayers can no longer play animations by themselves and need to be paired with a Handle<AnimationGraph>. Code that was using AnimationPlayer to play animations will need to create an AnimationGraph asset first, add a node for the clip (or clips) you want to play, and then supply the index of that node to the AnimationPlayer's play method.

• The AnimationPlayer::play_with_transition() method has been removed and replaced with the AnimationTransitions component. If you were previously using AnimationPlayer::play_with_transition(), add all animations that you were playing to the AnimationGraph, and create an AnimationTransitions component to manage the blending between them.

[pcwalton]

I removed the Controversial label as this is implementing an approved RFC.

[djeedai]

Looks good overall, no special concern or comment

[github-actions]

The generated examples/README.md is out of sync with the example metadata in Cargo.toml or the example readme template. Please run cargo run -p build-templated-pages -- update examples to update it, and commit the file change.

[github-actions]

The generated examples/README.md is out of sync with the example metadata in Cargo.toml or the example readme template. Please run cargo run -p build-templated-pages -- update examples to update it, and commit the file change.

[github-actions]

The generated examples/README.md is out of sync with the example metadata in Cargo.toml or the example readme template. Please run cargo run -p build-templated-pages -- update examples to update it, and commit the file change.

[pcwalton]

OK, I'm much happier with this. I've solved the problems of animation ordering and removed the "scheduled animation" overhead. This should be ready for re-review.

[pcwalton]

Improved the example a bit, thanks to @rparrett.

[james7132]

I'm overall happy with the current state of this PR. Given the size of the PR, I'm opting to skip the smaller nits and opt to iteratively improve upon the implementation.

[alice-i-cecile]

Really pleased with the documentation and general care shown here. I'm content with the level of review from subject matter experts, and the examples appear to work correctly for me.

There's definitely some general-purpose abstractions missing on the asset management side, but I'm content with this for now. It'll be useful to have this in place to help us figure out a design there.

However, I'm getting a bunch of warnings like:

2024-03-07T15:32:36.708431Z WARN bevy_animation: Couldn't find the animation player 53v1 for the target entity 49v1 (Some("b_LeftLeg02_016"))

on both the animated_fox and animation_graph examples. This doesn't appear to be present on main. I suspect a system ordering problem.

Once those are fixed up I'm happy to approve and merge.

[rparrett]

2024-03-07T15:32:36.708431Z WARN bevy_animation: Couldn't find the animation player 53v1 for the target entity 49v1 (Some("b_LeftLeg02_016"))

These started showing up after 283a4d0.

I have some more ideas for the examples, but I will follow up later. They're definitely in a good enough state.

So "approved," but I only looked at the examples.

[pcwalton]

I demoted the warnings to traces because they're relatively common and harmless now. They'll occur whenever you load a glTF and haven't added an AnimationGraph. glTF has no concept of animation blending, so Bevy has no way to figure out what you want, and you have to add it manually. Until you do, animations won't play. This is documented in the migration guide. (It might be convenient to have some sort of default AnimationGraph, but that can be a followup.)

I also switched the system order to hopefully avoid 1-frame lag (and avoid those traces) in the examples.