bevy_tween

The animation system is built on top of bevy_time_runner, treating an animator as a tree of entities:

1. Parent (TimeRunner): The parent entity handles all timing and progress management for its children.
2. Children: Children can be any combination of components, including tweens provided by bevy_tween.
3. Pipeline: Systems run in a pipeline, communicating through dependency-injected components.

This tree-based approach allows for high flexibility, enabling parallel, sequential, or overlapping animations of any type, and makes it easy to extend the system with custom components or events.

You can explore the capabilities of bevy_tween by running the provided examples. Note that most examples require the bevy/bevy_winit feature to run in a windowed environment.

• Follow: A square follows a circle with configurable animation. cargo run --example follow -F bevy/bevy_winit
• Click: Spawns circles on click (or repeatedly on right-click hold). cargo run --example click -F bevy/bevy_winit
• Hold: Increases effect intensity by holding left click. cargo run --example hold -F bevy/bevy_winit
• Event: Showcases the tween event feature. cargo run --example event -F bevy/bevy_winit
• Sprite Sheet: Demonstrates sprite sheet animation. cargo run --example sprite_sheet -F bevy/bevy_winit

Use parallel() to run multiple animations simultaneously. Every animation in the parallel group receives the same starting position. The total duration of the parallel group is determined by the longest animation within it. You can pass a tuple of animations to parallel() (up to 16 elements via standard tuples, or more by nesting tuples).

// Example of running animations in parallel
parallel((
    tween(Duration::from_secs(1), interp1, tween1),
    tween(Duration::from_secs(3), interp2, tween2),
));

You can enable specific features to add built-in interpolators and systems for different Bevy modules:

Default Features:

• bevy_asset: Adds tweening systems for assets.
• bevy_render: Required by the bevy_sprite feature.
• bevy_sprite: Adds built-in interpolators for sprites.
• bevy_ui: Adds built-in interpolators for UI.

Optional Features:

• bevy_lookup_curve: Adds interpolation implementation using the bevy_lookup_curve crate.

To avoid manually specifying the starting value of an animation (which can lead to boilerplate if you want a tween to continue from its current value), use the state method. This allows you to use relative interpolators like sprite_color_to instead of absolute ones like sprite_color.

use bevy_tween::{interpolate::sprite_color_to, combinator::{tween, sequence}};

let sprite = sprite_commands.id().into_target();
// Initialize the state with the starting value
let mut sprite_color = sprite.state(WHITE.into()); 

sprite_commands.animation().insert(sequence(( 
    tween(
        Duration::from_secs(1),
        EaseKind::QuadraticOut,
        sprite_color.with(sprite_color_to(RED.into()))
    ),
    tween(
        Duration::from_secs(1),
        EaseKind::QuadraticIn,
        sprite_color.with(sprite_color_to(WHITE.into()))
    ),
)));

For complex or sequential animations, use the combinator framework. This approach adds a TimeRunner to your entity and creates Tween entities as children to manage the animation lifecycle.

Common combinators include:

• tween(...): Creates a single tween animation.
• sequence(...): Chains multiple animations to run one after another.

use bevy_tween::{interpolate::sprite_color, combinator::{tween, sequence}};

let sprite = sprite_commands.id().into_target();
sprite_commands.animation().insert(sequence(( 
    tween(
        Duration::from_secs(1),
        EaseKind::QuadraticOut,
        sprite.with(sprite_color(WHITE.into(), RED.into()))
    ),
    tween(
        Duration::from_secs(1),
        EaseKind::QuadraticIn,
        sprite.with(sprite_color(RED.into(), WHITE.into()))
    ),
)));

Use sequence() to run multiple animations one after another. Each animation in the sequence starts immediately after the previous one finishes. The total duration of the sequence is the sum of the durations of its components. You can pass a tuple of animations to sequence() (up to 16 elements via standard tuples, or more by nesting tuples).

// Example of sequencing two animations
sequence((
    tween(Duration::from_secs(1), my_interpolation, my_tween),
    tween(Duration::from_secs(2), other_interpolation, other_tween),
));

To animate Bevy resources, add a resource tween system to your app. This allows you to interpolate values stored in global resources using an Interpolator.

use bevy::prelude::*;
use bevy_tween::prelude::*;

#[derive(Resource)]
struct ScreenFade(f32);

struct InterpolateScreenFade {
    start: f32,
    end: f32,
}

impl Interpolator for InterpolateScreenFade {
    type Item = ScreenFade;

    fn interpolate(&self, item: &mut Self::Item, value: f32, _previous_value: f32) {
        item.0 = self.start.lerp(self.end, value);
    }
}

fn main() {
    let mut app = App::new();

    // Generic interpolator for resources
    app.add_tween_systems(
        PostUpdate,
        resource_tween_system::<InterpolateScreenFade>(),
    );
}

To enable the automatic sampling of EaseKind components, you must add the EaseKindPlugin to your Bevy application. By default, it registers systems to the PostUpdate schedule. You can customize the schedule using .in_schedule().

// Standard setup using default PostUpdate schedule
app.add_plugins(EaseKindPlugin::default());

// Custom setup specifying a different schedule
app.add_plugins(EaseKindPlugin::in_schedule(MyCustomSchedule));

To use bevy_tween in your Bevy application, add the DefaultTweenPlugins to your App. By default, these plugins are registered to run in the PostUpdate schedule. You can also specify a custom schedule using .in_schedule(your_schedule).

use bevy::prelude::*;
use bevy_tween::prelude::*;

fn main() {
    App::default()
        .add_plugins((DefaultPlugins, DefaultTweenPlugins::default()))
        .run();
}