Add AnimationGraph::from_clips and simplify animated_fox example (b…

…evyengine#14853)

# Objective

Add a convenience constructor to make simple animation graphs easier to
build.

I've had some notes about attempting this since bevyengine#11989 that I just
remembered after seeing bevyengine#14852.

This partially addresses bevyengine#14852, but I don't really know animation well
enough to write all of the documentation it's asking for.

## Solution

Add `AnimationGraph::from_clips` and use it to simplify `animated_fox`.

Do some other little bits of incidental cleanup and documentation .

## Testing

I ran `cargo run --example animated_fox`.

crates/bevy_animation/src/graph.rs

@@ -192,6 +192,23 @@ impl AnimationGraph {
         (graph, node_index)
     }
 
+    /// A convenience method to create an [`AnimationGraph`]s with an iterator
+    /// of clips.
+    ///
+    /// All of the animation clips will be direct children of the root with
+    /// weight 1.0.
+    ///
+    /// Returns the the graph and indices of the new nodes.
+    pub fn from_clips<'a, I>(clips: I) -> (Self, Vec<AnimationNodeIndex>)
+    where
+        I: IntoIterator<Item = Handle<AnimationClip>>,
+        <I as IntoIterator>::IntoIter: 'a,
+    {
+        let mut graph = Self::new();
+        let indices = graph.add_clips(clips, 1.0, graph.root).collect();
+        (graph, indices)
+    }
+
     /// Adds an [`AnimationClip`] to the animation graph with the given weight
     /// and returns its index.
     ///

crates/bevy_animation/src/lib.rs

@@ -529,7 +529,10 @@ impl ActiveAnimation {
     }
 }
 
-/// Animation controls
+/// Animation controls.
+///
+/// Automatically added to any root animations of a `SceneBundle` when it is
+/// spawned.
 #[derive(Component, Default, Reflect)]
 #[reflect(Component)]
 pub struct AnimationPlayer {

examples/animation/animated_fox.rs

@@ -9,6 +9,8 @@ use bevy::{
     prelude::*,
 };
 
+const FOX_PATH: &str = "models/animated/Fox.glb";
+
 fn main() {
     App::new()
         .insert_resource(AmbientLight {
@@ -37,26 +39,17 @@ fn setup(
     mut graphs: ResMut<Assets<AnimationGraph>>,
 ) {
     // Build the animation graph
-    let mut graph = AnimationGraph::new();
-    let animations = graph
-        .add_clips(
-            [
-                GltfAssetLabel::Animation(2).from_asset("models/animated/Fox.glb"),
-                GltfAssetLabel::Animation(1).from_asset("models/animated/Fox.glb"),
-                GltfAssetLabel::Animation(0).from_asset("models/animated/Fox.glb"),
-            ]
-            .into_iter()
-            .map(|path| asset_server.load(path)),
-            1.0,
-            graph.root,
-        )
-        .collect();
+    let (graph, node_indices) = AnimationGraph::from_clips([
+        asset_server.load(GltfAssetLabel::Animation(2).from_asset(FOX_PATH)),
+        asset_server.load(GltfAssetLabel::Animation(1).from_asset(FOX_PATH)),
+        asset_server.load(GltfAssetLabel::Animation(0).from_asset(FOX_PATH)),
+    ]);
 
     // Insert a resource with the current scene information
-    let graph = graphs.add(graph);
+    let graph_handle = graphs.add(graph);
     commands.insert_resource(Animations {
-        animations,
-        graph: graph.clone(),
+        animations: node_indices,
+        graph: graph_handle,
     });
 
     // Camera
@@ -91,7 +84,7 @@ fn setup(
 
     // Fox
     commands.spawn(SceneBundle {
-        scene: asset_server.load(GltfAssetLabel::Scene(0).from_asset("models/animated/Fox.glb")),
+        scene: asset_server.load(GltfAssetLabel::Scene(0).from_asset(FOX_PATH)),
         ..default()
     });
 
@@ -104,7 +97,8 @@ fn setup(
     println!("  - return: change animation");
 }
 
-// Once the scene is loaded, start the animation
+// An `AnimationPlayer` is automatically added to the scene when it's ready.
+// When the player is added, start the animation.
 fn setup_scene_once_loaded(
     mut commands: Commands,
     animations: Res<Animations>,