Crate bevy_tweening

source ·
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:

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 AssetAnimation system added by TweeningPlugin?
TransformYes
SpriteOnly if bevy_sprite feature
ColorMaterialOnly if bevy_sprite feature
StyleOnly if bevy_ui feature
TextOnly if bevy_text feature
All other componentsNo

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§

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

Traits§

  • Lerp
    Describes a type that can linearly interpolate between two points.
  • 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§

Type Aliases§