Implement the AnimationGraph, allowing for multiple animations to b…

…e blended together. (#11989)

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:

- [x] A fully-fleshed-out mechanism for transitions
- [x] A serialization format for `AnimationGraph`s
- [x] Examples are broken, other than `animated_fox`
- [x] 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

* `AnimationPlayer`s 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.

[RFC 51]:
https://github.com/bevyengine/rfcs/blob/main/rfcs/51-animation-composition.md

---------

Co-authored-by: Rob Parrett <robparrett@gmail.com>

Cargo.toml

@@ -980,6 +980,17 @@ description = "Plays an animation from a skinned glTF"
 category = "Animation"
 wasm = true
 
+[[example]]
+name = "animation_graph"
+path = "examples/animation/animation_graph.rs"
+doc-scrape-examples = true
+
+[package.metadata.example.animation_graph]
+name = "Animation Graph"
+description = "Blends multiple animations together with a graph"
+category = "Animation"
+wasm = true
+
 [[example]]
 name = "morph_targets"
 path = "examples/animation/morph_targets.rs"

assets/animation_graphs/Fox.animgraph.ron

@@ -0,0 +1,35 @@
+(
+    graph: (
+        nodes: [
+            (
+                clip: None,
+                weight: 1.0,
+            ),
+            (
+                clip: None,
+                weight: 0.5,
+            ),
+            (
+                clip: Some(AssetPath("models/animated/Fox.glb#Animation0")),
+                weight: 1.0,
+            ),
+            (
+                clip: Some(AssetPath("models/animated/Fox.glb#Animation1")),
+                weight: 1.0,
+            ),
+            (
+                clip: Some(AssetPath("models/animated/Fox.glb#Animation2")),
+                weight: 1.0,
+            ),
+        ],
+        node_holes: [],
+        edge_property: directed,
+        edges: [
+            Some((0, 1, ())),
+            Some((0, 2, ())),
+            Some((1, 3, ())),
+            Some((1, 4, ())),
+        ],
+    ),
+    root: 0,
+)

crates/bevy_animation/Cargo.toml

@@ -13,9 +13,12 @@ keywords = ["bevy"]
 bevy_app = { path = "../bevy_app", version = "0.14.0-dev" }
 bevy_asset = { path = "../bevy_asset", version = "0.14.0-dev" }
 bevy_core = { path = "../bevy_core", version = "0.14.0-dev" }
+bevy_derive = { path = "../bevy_derive", version = "0.14.0-dev" }
+bevy_log = { path = "../bevy_log", version = "0.14.0-dev" }
 bevy_math = { path = "../bevy_math", version = "0.14.0-dev" }
 bevy_reflect = { path = "../bevy_reflect", version = "0.14.0-dev", features = [
   "bevy",
+  "petgraph",
 ] }
 bevy_render = { path = "../bevy_render", version = "0.14.0-dev" }
 bevy_time = { path = "../bevy_time", version = "0.14.0-dev" }
@@ -25,7 +28,13 @@ bevy_transform = { path = "../bevy_transform", version = "0.14.0-dev" }
 bevy_hierarchy = { path = "../bevy_hierarchy", version = "0.14.0-dev" }
 
 # other
+fixedbitset = "0.4"
+petgraph = { version = "0.6", features = ["serde-1"] }
+ron = "0.8"
+serde = "1"
 sha1_smol = { version = "1.0" }
+thiserror = "1"
+thread_local = "1"
 uuid = { version = "1.7", features = ["v4"] }
 
 [lints]