Crate bevy_tweening

Expand description

Tweening animation plugin for the Bevy game engine

🍃 Bevy Tweening provides interpolation-based animation between (“tweening”) two values, for Bevy components and assets. Each field of a component or asset can be animated via a collection or predefined easing functions, or providing a custom animation curve. Custom components and assets are also supported.

Example

Add the tweening plugin to your app:

use bevy::prelude::*;
use bevy_tweening::*;

App::default()
    .add_plugins(DefaultPlugins)
    .add_plugin(TweeningPlugin)
    .run();

Animate the position (Transform::translation) of an Entity:

// Create a single animation (tween) to move an entity.
let tween = Tween::new(
    // Use a quadratic easing on both endpoints.
    EaseFunction::QuadraticInOut,
    // Animation time.
    Duration::from_secs(1),
    // The lens gives access to the Transform component of the Entity,
    // for the Animator to animate it. It also contains the start and
    // end values respectively associated with the progress ratios 0. and 1.
    TransformPositionLens {
        start: Vec3::ZERO,
        end: Vec3::new(1., 2., -4.),
    },
);

commands.spawn((
    // Spawn an entity to animate the position of.
    TransformBundle::default(),
    // Add an Animator component to control and execute the animation.
    Animator::new(tween),
));

Tweenables

🍃 Bevy Tweening supports several types of tweenables, building blocks that can be combined to form complex animations. A tweenable is a type implementing the Tweenable trait.

Tween - A simple tween (easing) animation between two values.
Sequence - A series of tweenables executing in series, one after the other.
Tracks - A collection of tweenables executing in parallel.
Delay - A time delay. This doesn’t animate anything.

Chaining animations

Most tweenables can be chained with the then() operator to produce a Sequence tweenable:

let tween1 = Tween::new(
    // [...]
);
let tween2 = Tween::new(
    // [...]
);
// Produce a Sequence executing first 'tween1' then 'tween2'
let seq = tween1.then(tween2);

Animators and lenses

Bevy components and assets are animated with tweening animator components, which take a tweenable and apply it to another component on the same Entity. Those animators determine that other component and its fields to animate using a lens.

Components animation

Components are animated with the Animator component, which is generic over the type of component it animates. This is a restriction imposed by Bevy, to access the animated component as a mutable reference via a Query and comply with the ECS rules.

The Animator itself is not generic over the subset of fields of the components it animates. This limits the proliferation of generic types when animating e.g. both the position and rotation of an entity.

Assets animation

Assets are animated in a similar way to component, via the AssetAnimator component. This requires the bevy_asset feature (enabled by default).

Because assets are typically shared, and the animation applies to the asset itself, all users of the asset see the animation. For example, animating the color of a ColorMaterial will change the color of all the 2D meshes using that material.

Lenses

Both Animator and AssetAnimator access the field(s) to animate via a lens, a type that implements the Lens trait.

Several predefined lenses are provided in the lens module for the most commonly animated fields, like the components of a Transform. A custom lens can also be created by implementing the trait, allowing to animate virtually any field of any Bevy component or asset.