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_plugins(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),
));

Note that this example leverages the fact TweeningPlugin automatically adds the necessary system to animate Transform components. However, for most other components and assets, you need to manually add those systems to your App.

§System setup

Adding the TweeningPlugin to your app provides the basic setup for using 🍃 Bevy Tweening. However, additional setup is required depending on the components and assets you want to animate:

To ensure a component C is animated, the component_animator_system::<C> system must run each frame, in addition of adding an Animator::<C> component to the same Entity as C.
To ensure an asset A is animated, the asset_animator_system::<A> system must run each frame, in addition of adding an AssetAnimator<A> component to any Entity. Animating assets also requires the bevy_asset feature (enabled by default).

By default, 🍃 Bevy Tweening adopts a minimalist approach, and the TweeningPlugin will only add systems to animate components and assets for which a Lens is provided by 🍃 Bevy Tweening itself. This means that any other Bevy component or asset (either built-in from Bevy itself, or custom) requires manually scheduling the appropriate system.

Component or Asset	Animation system added by `TweeningPlugin`?
`Transform`	Yes
`Sprite`	Only if `bevy_sprite` feature
`ColorMaterial`	Only if `bevy_sprite` feature
`Node`	Only if `bevy_ui` feature
`Text`	Only if `bevy_text` feature
All other components	No

To add a system for a component C, use:

app.add_systems(Update,
    component_animator_system::<C>
        .in_set(AnimationSystem::AnimationUpdate));

Similarly for an asset A, use the asset_animator_system. This is only available with the bevy_asset feature.

§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.

Re-exports§

pub use lens::Lens;

Modules§

lens: Collection of predefined lenses for common Bevy components and assets.

Structs§

Animator: Component to control the animation of another component.
AssetAnimator: Component to control the animation of an asset.
AssetTarget: Implementation of Targetable for an Asset.
ComponentTarget: Implementation of Targetable for a Component.
Delay: A time delay that doesn’t animate anything.
Sequence: A sequence of tweens played back in order one after the other.
Tracks: A collection of Tweenable executing in parallel.
Tween: Single tweening animation instance.
TweenCompleted: Event raised when a tween completed.
TweeningPlugin: Plugin to add systems related to tweening of common components and assets.

Enums§

AnimationSystem: Label enum for the systems relating to animations
AnimatorState: Playback state of an animator.
EaseMethod: Describe how eased value should be computed.
RepeatCount: How many times to repeat a tweenable animation.
RepeatStrategy: What to do when a tween animation needs to be repeated.
TotalDuration: Possibly infinite duration of an animation.
TweenState: Playback state of a Tweenable.
TweeningDirection: Direction a tweening animation is playing.

Traits§

Targetable: Trait to workaround the discrepancies of the change detection mechanisms of assets and components.
Tweenable: An animatable entity, either a single Tween or a collection of them.

Functions§

asset_animator_system: Animator system for assets.
component_animator_system: Animator system for components.

Type Aliases§

BoxedTweenable: The dynamic tweenable type.

Crate bevy_tweeningCopy item path