Root motion implementation

Cargo.toml

@@ -1751,6 +1751,21 @@ description = "Plays an animation from a glTF file with meshes with morph target
 category = "Animation"
 wasm = true
 
+[[example]]
+name = "root_motion"
+path = "examples/animation/root_motion.rs"
+doc-scrape-examples = true
+
+[package.metadata.example.root_motion]
+name = "Root Motion"
+description = """
+Plays an animation and use root motion to move the entity.
+
+When root motion is disabled only the mesh is moved so the position resets each time the animation resets.
+When root motion is enabled, the mesh stays in place and the movement is transferred to the main entity."""
+category = "Animation"
+wasm = true
+
 [[example]]
 name = "animated_transform"
 path = "examples/animation/animated_transform.rs"

_release-content/migration-guides/animation_curve_evaluator_commit.md

@@ -0,0 +1,19 @@
+---
+title: Change function signature of commit in AnimationCurveEvaluator
+pull_requests: [24201]
+---
+
+The root motion feature needs to access the animated entity after the curves are applied. For this reason, the commit method of
+AnimationCurveEvaluator changed from :
+
+```rust
+    fn commit(&mut self, entity: AnimationEntityMut) -> Result<(), AnimationEvaluationError>;
+```
+
+to
+
+```rust
+    fn commit(&mut self, entity: &mut AnimationEntityMut) -> Result<(), AnimationEvaluationError>;
+```
+
+Passing the AnimationEntityMut by mutable reference is now necessary.

_release-content/release-notes/root_motion.md

@@ -0,0 +1,12 @@
+---
+title: Root Motion
+authors: ["@Hilpogar", "@emberlightstudios"]
+pull_requests: [24201]
+---
+
+In animation and game development, root motion is a technique where the movement of a character is driven directly by the animation’s root bone instead of being controlled purely by code or physics.
+It is used to create more natural, accurate movements such as walking, climbing, or attacks, by synchronizing the character’s in-game position with the animation itself.
+
+You can now use this technique by using the `set_root_motion_target` method in the `AnimationPlayer`. To do so, you need to get the `AnimationTargetId` of your model's root motion bone.
+It can be the root bone or any bone you want. When a bone is configured to be used for root motion, its position and / or rotation will be erased each frame and the delta with the previous
+frame is stored in the `RootMotion` component inside the `AnimationPlayer`'s entity. You can configure if the root motion should extract translation and rotation or just translation with the `set_root_motion_mode` method in `AnimationPlayer`.

assets/models/animated/FoxRootMotion.md

@@ -0,0 +1,4 @@
+# What's FoxRootMotion.glb
+
+This model is the same as Fox.glb but with an additional curve for translation in the `b_Root_00` bone of the `run` animation.
+It's used to illustrate the root motion in the root_motion example.

crates/bevy_animation/src/animation_curves.rs

@@ -306,6 +306,18 @@ pub struct AnimatableCurveEvaluator<A: Animatable> {
     property: Box<dyn AnimatableProperty<Property = A>>,
 }
 
+impl<A: Animatable> AnimatableCurveEvaluator<A> {
+    pub(super) fn push_value(&mut self, value: A, weight: f32, graph_node: AnimationNodeIndex) {
+        self.evaluator
+            .stack
+            .push(BasicAnimationCurveEvaluatorStackElement {
+                value,
+                weight,
+                graph_node,
+            });
+    }
+}
+
 impl<P, C> AnimatableCurve<P, C>
 where
     P: AnimatableProperty,
@@ -413,8 +425,8 @@ impl<A: Animatable> AnimationCurveEvaluator for AnimatableCurveEvaluator<A> {
         self.evaluator.push_blend_register(weight, graph_node)
     }
 
-    fn commit(&mut self, mut entity: AnimationEntityMut) -> Result<(), AnimationEvaluationError> {
-        let property = self.property.get_mut(&mut entity)?;
+    fn commit(&mut self, entity: &mut AnimationEntityMut) -> Result<(), AnimationEvaluationError> {
+        let property = self.property.get_mut(entity)?;
         *property = self
             .evaluator
             .stack
@@ -708,7 +720,7 @@ pub trait AnimationCurveEvaluator: Downcast + Send + Sync + 'static {
     ///
     /// The property on the component must be overwritten with the value from
     /// the stack, not blended with it.
-    fn commit(&mut self, entity: AnimationEntityMut) -> Result<(), AnimationEvaluationError>;
+    fn commit(&mut self, entity: &mut AnimationEntityMut) -> Result<(), AnimationEvaluationError>;
 }
 
 impl_downcast!(AnimationCurveEvaluator);