Expose sequences and active tweens

Allow querying the active tween of a sequence. Use this to improve the
`sequence` example with some text showing the current active tween and
its progress.

CHANGELOG

@@ -11,10 +11,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Implement `Default` for `AnimatorState` as `AnimatorState::Playing`.
 - Added `Animator::with_state()` and `AssetAnimator::with_state()`, builder-like functions to override the default `AnimatorState`.
 - Added `Tween::is_looping()` returning true for all but `TweeningType::Once`.
+- Publicly exposed `Sequence<T>`, a sequence of tweens running one after the other.
+- Publicly exposed `Animator<T>::tracks()` and `Animator<T>::tracks_mut()` to access the animation sequences running in parallel on multiple animation tracks.
 
 ### Changed
 
 - Moved tween duration out of the `TweeningType` enum, which combined with the removal of the "pause" feature in loops makes it a C-like enum.
+- Updated the `sequence` example to add some text showing the current sequence active tween index and its progress.
 
 ### Removed
 

benchmarks/Cargo.toml

@@ -10,6 +10,7 @@ documentation = "https://docs.rs/bevy_tweening"
 keywords = ["bevy", "animation", "easing", "tweening"]
 license = "MIT"
 readme = "README.md"
+include = ["assets", "thirdparty"]
 exclude = ["examples/*.gif"]
 
 [dependencies]

examples/sequence.rs

@@ -14,14 +14,76 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
         .add_plugins(DefaultPlugins)
         .add_plugin(TweeningPlugin)
         .add_startup_system(setup)
+        .add_system(update_text)
+        .add_system(update_anim)
         .run();
 
     Ok(())
 }
 
-fn setup(mut commands: Commands) {
+#[derive(Component)]
+struct IndexText;
+
+#[derive(Component)]
+struct ProgressText;
+
+fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
     commands.spawn_bundle(OrthographicCameraBundle::new_2d());
 
+    let font = asset_server.load("fonts/FiraMono-Regular.ttf");
+    let text_style = TextStyle {
+        font,
+        font_size: 50.0,
+        color: Color::WHITE,
+    };
+
+    let text_alignment = TextAlignment {
+        vertical: VerticalAlign::Center,
+        horizontal: HorizontalAlign::Center,
+    };
+
+    // Text with the index of the active tween in the sequence
+    commands
+        .spawn_bundle(Text2dBundle {
+            text: Text {
+                sections: vec![
+                    TextSection {
+                        value: "index: ".to_owned(),
+                        style: text_style.clone(),
+                    },
+                    TextSection {
+                        value: "0".to_owned(),
+                        style: text_style.clone(),
+                    },
+                ],
+                alignment: text_alignment,
+            },
+            transform: Transform::from_translation(Vec3::new(0., 40., 0.)),
+            ..Default::default()
+        })
+        .insert(IndexText);
+
+    // Text with progress of the active tween in the sequence
+    commands
+        .spawn_bundle(Text2dBundle {
+            text: Text {
+                sections: vec![
+                    TextSection {
+                        value: "progress: ".to_owned(),
+                        style: text_style.clone(),
+                    },
+                    TextSection {
+                        value: "0%".to_owned(),
+                        style: text_style.clone(),
+                    },
+                ],
+                alignment: text_alignment,
+            },
+            transform: Transform::from_translation(Vec3::new(0., -40., 0.)),
+            ..Default::default()
+        })
+        .insert(ProgressText);
+
     let size = 25.;
 
     let margin = 40.;
@@ -29,6 +91,7 @@ fn setup(mut commands: Commands) {
     let screen_y = 600.;
     let center = Vec3::new(screen_x / 2., screen_y / 2., 0.);
 
+    // Run around the window from corner to corner
     let dests = &[
         Vec3::new(margin, margin, 0.),
         Vec3::new(screen_x - margin, margin, 0.),
@@ -41,9 +104,8 @@ fn setup(mut commands: Commands) {
         .map(|pair| {
             Tween::new(
                 EaseFunction::QuadraticInOut,
-                TweeningType::Once {
-                    duration: Duration::from_secs(1),
-                },
+                TweeningType::Once,
+                Duration::from_secs(1),
                 TransformPositionLens {
                     start: pair[0] - center,
                     end: pair[1] - center,
@@ -61,5 +123,38 @@ fn setup(mut commands: Commands) {
             },
             ..Default::default()
         })
-        .insert(Animator::new_seq(tweens));
+        .insert(Animator::new_seq(tweens).with_state(AnimatorState::Paused));
+}
+
+fn update_anim(time: Res<Time>, mut q: Query<&mut Animator<Transform>>) {
+    if time.seconds_since_startup() >= 10. {
+        q.single_mut().state = AnimatorState::Playing;
+    }
+}
+
+fn update_text(
+    // Note: need a QuerySet<> due to the "&mut Text" in both queries
+    mut query_text: QuerySet<(
+        QueryState<&mut Text, With<IndexText>>,
+        QueryState<&mut Text, With<ProgressText>>,
+    )>,
+    query_anim: Query<&Animator<Transform>>,
+) {
+    let anim = query_anim.single();
+    let seq = &anim.tracks()[0];
+    let index = seq.index();
+    let tween = seq.current();
+    let progress = tween.progress();
+
+    // Use scopes to force-drop the mutable context before opening the next one
+    {
+        let mut q0 = query_text.q0();
+        let mut index_text = q0.single_mut();
+        index_text.sections[1].value = format!("{:1}", index).to_string();
+    }
+    {
+        let mut q1 = query_text.q1();
+        let mut progress_text = q1.single_mut();
+        progress_text.sections[1].value = format!("{:5.1}%", progress * 100.).to_string();
+    }
 }

src/lib.rs

@@ -350,13 +350,15 @@ impl<T> Tween<T> {
     }
 }
 
-struct Sequence<T> {
+/// A sequence of tweens played back in order one after the other.
+pub struct Sequence<T> {
     tweens: Vec<Tween<T>>,
     index: usize,
     state: TweenState,
 }
 
 impl<T> Sequence<T> {
+    /// Create a new sequence of tweens.
     pub fn new<I>(tweens: I) -> Self
     where
         I: IntoIterator<Item = Tween<T>>,
@@ -368,6 +370,7 @@ impl<T> Sequence<T> {
         }
     }
 
+    /// Create a new sequence containing a single tween.
     pub fn from_single(tween: Tween<T>) -> Self {
         Sequence {
             tweens: vec![tween],
@@ -376,6 +379,16 @@ impl<T> Sequence<T> {
         }
     }
 
+    /// Index of the current active tween in the sequence.
+    pub fn index(&self) -> usize {
+        self.index.min(self.tweens.len() - 1)
+    }
+
+    /// Get the current active tween in the sequence.
+    pub fn current(&self) -> &Tween<T> {
+        &self.tweens[self.index()]
+    }
+
     fn tick(&mut self, delta: Duration, target: &mut T) {
         if self.index < self.tweens.len() {
             let tween = &mut self.tweens[self.index];
@@ -474,13 +487,14 @@ impl<T: Component> Animator<T> {
         self
     }
 
-    #[allow(dead_code)]
-    fn tracks(&self) -> &Tracks<T> {
-        &self.tracks
+    /// Get the collection of sequences forming the parallel tracks of animation.
+    pub fn tracks(&self) -> &[Sequence<T>] {
+        &self.tracks.tracks
     }
 
-    fn tracks_mut(&mut self) -> &mut Tracks<T> {
-        &mut self.tracks
+    /// Get the mutable collection of sequences forming the parallel tracks of animation.
+    pub fn tracks_mut(&mut self) -> &mut [Sequence<T>] {
+        &mut self.tracks.tracks
     }
 }
 
@@ -566,13 +580,14 @@ impl<T: Asset> AssetAnimator<T> {
         self.handle.clone()
     }
 
-    #[allow(dead_code)]
-    fn tracks(&self) -> &Tracks<T> {
-        &self.tracks
+    /// Get the collection of sequences forming the parallel tracks of animation.
+    pub fn tracks(&self) -> &[Sequence<T>] {
+        &self.tracks.tracks
     }
 
-    fn tracks_mut(&mut self) -> &mut Tracks<T> {
-        &mut self.tracks
+    /// Get the mutable collection of sequences forming the parallel tracks of animation.
+    pub fn tracks_mut(&mut self) -> &mut [Sequence<T>] {
+        &mut self.tracks.tracks
     }
 }
 
@@ -725,8 +740,8 @@ mod tests {
         );
         assert_eq!(animator.state, AnimatorState::default());
         let tracks = animator.tracks();
-        assert_eq!(tracks.tracks.len(), 1);
-        let seq = &tracks.tracks[0];
+        assert_eq!(tracks.len(), 1);
+        let seq = &tracks[0];
         assert_eq!(seq.tweens.len(), 1);
         let tween = &seq.tweens[0];
         assert_eq!(tween.direction(), TweeningDirection::Forward);
@@ -748,8 +763,8 @@ mod tests {
         );
         assert_eq!(animator.state, AnimatorState::default());
         let tracks = animator.tracks();
-        assert_eq!(tracks.tracks.len(), 1);
-        let seq = &tracks.tracks[0];
+        assert_eq!(tracks.len(), 1);
+        let seq = &tracks[0];
         assert_eq!(seq.tweens.len(), 1);
         let tween = &seq.tweens[0];
         assert_eq!(tween.direction(), TweeningDirection::Forward);

src/plugin.rs

@@ -54,13 +54,13 @@ pub fn component_animator_system<T: Component>(
         animator.prev_state = animator.state;
         if animator.state == AnimatorState::Paused {
             if state_changed {
-                for seq in &mut animator.tracks_mut().tracks {
+                for seq in animator.tracks_mut() {
                     seq.stop();
                 }
             }
         } else {
             // Play all tracks in parallel
-            for seq in &mut animator.tracks_mut().tracks {
+            for seq in animator.tracks_mut() {
                 seq.tick(time.delta(), target);
             }
         }
@@ -80,13 +80,13 @@ pub fn asset_animator_system<T: Asset>(
         animator.prev_state = animator.state;
         if animator.state == AnimatorState::Paused {
             if state_changed {
-                for seq in &mut animator.tracks_mut().tracks {
+                for seq in animator.tracks_mut() {
                     seq.stop();
                 }
             }
         } else if let Some(target) = assets.get_mut(animator.handle()) {
             // Play all tracks in parallel
-            for seq in &mut animator.tracks_mut().tracks {
+            for seq in animator.tracks_mut() {
                 seq.tick(time.delta(), target);
             }
         }

thirdparty/LICENSE_FiraMono.txt

+Copyright (c) 2012-2013, The Mozilla Corporation and Telefonica S.A.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

thirdparty/LICENSE_FiraSans.txt

+Copyright (c) 2012-2015, The Mozilla Foundation and Telefonica S.A.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.