-
Jerome Humbert authored0b2426a0
- 🍃 Bevy Tweening
- Usage
- System setup
- Animate a component
- Predefined Lenses
- Bevy Components
- Bevy Assets
- Custom component support
- Custom asset support
- Examples
- sprite_color
- transform_rotation
- transform_translation
- colormaterial_color
- ui_position
- Ease Functions
- Compatible Bevy versions
- Comparison with bevy_easings
🍃 Bevy Tweening
Tweening animation plugin for Bevy.
Usage
System setup
Add the tweening plugin to your app:
App::default()
.add_default_plugins()
.add_plugin(TweeningPlugin)
.run();
Animate a component
Animate the transform position of an entity:
commands
// Spawn a Sprite entity to animate the position of
.spawn_bundle(SpriteBundle {
sprite: Sprite {
color: Color::RED,
custom_size: Some(Vec2::new(size, size)),
..Default::default()
},
..Default::default()
})
// Add an Animator component to perform the animation
.insert(Animator::new(
// Use a quadratic easing on both endpoints
EaseFunction::QuadraticInOut,
// Loop animation back and forth over 1 second, with a 0.5 second
// pause after each cycle (start -> end -> start).
TweeningType::PingPong {
duration: Duration::from_secs(1),
pause: Some(Duration::from_millis(500)),
},
// The lens gives access to the Transform component of the Sprite,
// for the Animator to animate it. It also contains the start and
// end values associated with the animation ratios 0. and 1.
TransformPositionLens {
start: Vec3::new(0., 0., 0.),
end: Vec3::new(1., 2., -4.),
},
));
Predefined Lenses
The naming scheme for predefined lenses is "<TargetName><FieldName>Lens"
, where <TargetName>
is the name of the target component or asset which is queried, and <FieldName>
is the field which is mutated in place.
Bevy Components
Target Component | Animated Field | Lens |
---|---|---|
Sprite |
color |
SpriteColorLens |
Transform |
translation |
TransformPositionLens |
rotation |
TransformRotationLens |
|
scale |
TransformScaleLens |
|
Style |
position |
UiPositionLens |
Text |
TextStyle::color |
TextColorLens |
Bevy Assets
Target Asset | Animated Field | Lens |
---|---|---|
ColorMaterial |
color |
ColorMaterialColorLens |
Custom component support
To be able to animate some fields of a custom component, a custom lens need to be implemented for that component, which linearly interpolates the field(s) of that component.
#[derive(Component)]
struct CustomComponent(f32);
struct CustomLens {
start: f32,
end: f32,
}
impl Lens<CustomComponent> for CustomLens {
fn lerp(&self, target: &mut CustomComponent, ratio: f32) -> f32 {
target.0 = self.start + (self.end - self.start) * ratio;
}
}
This process can also be used to interpolate fields of existing Bevy built-in components for which a predfined lens is not provided.
The basic formula for lerp (linear interpolation) is either of:
start + (end - start) * scalar
start * (1.0 - scalar) + end * scalar
The two formulations are mathematically equivalent, but one may be more suited than the other depending on the type interpolated and the operations available, and the potential floating-point precision errors.
Then, the system component_animator_system::<CustomComponent>
needs to be added to the application.
Custom asset support
The process is similar to custom components, creating a custom lens for the custom asset. The system to add is asset_animator_system::<CustomAsset>
.
Examples
See the examples/
folder.
sprite_color
cargo run --example sprite_color --features="bevy/bevy_winit"
transform_rotation
cargo run --example transform_rotation --features="bevy/bevy_winit"
transform_translation
cargo run --example transform_translation --features="bevy/bevy_winit"
colormaterial_color
cargo run --example colormaterial_color --features="bevy/bevy_winit"
ui_position
cargo run --example ui_position --features="bevy/bevy_winit"
Ease Functions
Many ease functions are available:
- QuadraticIn
- QuadraticOut
- QuadraticInOut
- CubicIn
- CubicOut
- CubicInOut
- QuarticIn
- QuarticOut
- QuarticInOut
- QuinticIn
- QuinticOut
- QuinticInOut
- SineIn
- SineOut
- SineInOut
- CircularIn
- CircularOut
- CircularInOut
- ExponentialIn
- ExponentialOut
- ExponentialInOut
- ElasticIn
- ElasticOut
- ElasticInOut
- BackIn
- BackOut
- BackInOut
- BounceIn
- BounceOut
- BounceInOut
Compatible Bevy versions
The main
branch is compatible with the latest Bevy release.
Compatibility of bevy_tweening
versions:
bevy_tweening |
bevy |
---|---|
0.2 |
0.6 |
0.1 |
0.5 |
bevy_easings
Comparison with The bevy_tweening
library started as a fork of the bevy_easings
library by François Mocker, with the goals to:
- explore an alternative design based on lenses instead of generic types for each easer/animator. This reduces both the number of generic types needed, and hopefully the code size, as well as the number of systems needed to perform the interpolation.
- improve the interpolation of assets to avoid creating many copies like
bevy_easings
does, and instead mutate the assets (and, by similarity, the components too) in-place without making a copy. The in-place mutation also allows a more optimal interpolation limited to modifying the fields of interest only, instead of creating a new copy of the entire component each tick.