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_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.
Re-exports
pub use lens::Lens;
Modules
- Collection of predefined lenses for common Bevy components and assets.
Structs
- Component to control the animation of another component.
- Component to control the animation of an asset.
- A time delay that doesn’t animate anything.
- A sequence of tweens played back in order one after the other.
- A collection of
Tweenable
executing in parallel. - Single tweening animation instance.
- Event raised when a tween completed.
- Plugin to add systems related to tweening of common components and assets.
Enums
- Label enum for the systems relating to animations
- Playback state of an animator.
- Describe how eased value should be computed.
- How many times to repeat a tween animation. See also:
RepeatStrategy
. - What to do when a tween animation needs to be repeated. See also
RepeatCount
. - Possibly infinite duration of an animation.
- Playback state of a
Tweenable
. - Direction a tweening animation is playing.
Traits
- Describes a type that can linearly interpolate between two points.
- Trait to workaround the discrepancies of the change detection mechanisms of assets and components.
- An animatable entity, either a single
Tween
or a collection of them.
Functions
- Animator system for assets.
- Animator system for components.
Type Definitions
- The dynamic tweenable type.