Expand description
§bevy_ecs_animations
An ECS approach to procedural animation in the Bevy engine
§Deprecation notice!
The AnimationConfiguration::start_at function has been renamed to start_after.
In a future release, the start_at function will be repurposed to configure an absolute timestamp for starting the animation.
§What is it?
This crate gives you a lightweight, opinionated timeline manager with minimal ceremony.
You define a normal Component that implements the Animation trait,
add it to the app with add_animation, and insert instances
on entities you want to animate.
While the animation is active, a Tick component is automatically added to the entity.
Your system reads this Tick to know where you are in the timeline (via t,
dt, and more).
Everything else — what you animate, how you react to progress, easing, state machines, etc. — is up to you.
§How to use it
(see examples/basic.rs for more info)
use bevy::{
prelude::*,
ecs::schedule::ScheduleLabel,
};
use bevy_ecs_animations::*;
fn run_app() -> AppExit {
App::new()
.add_plugins(MinimalPlugins)
.add_animation::<Fade>() // <-- this ties it all together
.add_systems(Startup, |mut commands: Commands| {
commands.spawn((Fade::In, Alpha::default()));
})
.run()
}
#[derive(Component, Default)]
struct Alpha(f32);
#[derive(Component)]
enum Fade {
In,
Out,
}
// this implements the `Animation` trait for you
#[animation(config = {
match *self {
Fade::In => duration(2.5),
Fade::Out => duration(2.5).play_in_reverse(),
}
})]
fn tick_fade(mut fades: Query<(&Tick<Fade>, &mut Alpha)>) {
for (tick, mut alpha) in fades.iter_mut() {
alpha.0 = tick.normalized_t;
}
}§Rambling
Bevy’s built-in animation plugin abstracts the notion of changing properties on particular
components over time, according to some curve definition that can produce values given a
timestamp across a domain that maps to seconds by default. Because it is designed with an
internal animation graph that abstracts blend operations to nodes outside the property accesses,
there are a few limitations. Primarily, only types the system knows how to blend are supported.
It is not trivial to animate the hue of HSLA colors, or the translation of UI nodes, as examples.
The specific components need to be accessed via EntityMut, and only
a single field of an understood type can be exposed per curve, even if you want to animate several
properties together.
Also, managing these animations has a lot of bookkeeping. Users have to create animation clips, add curves targeting particular fields on components to the clips (including all timeline coordination if multiple properties are involved). These clips are managed in the asset system. The clip asset is then used to construct an animation graph, which also needs to be managed in the asset system. Next, an animation player is created that references the node ID in the graph that represents the clip. The player and a component holding the graph handle have to be added to an entity that will behave as a “manager” for the animation in question. Next, the targeted entities need to receive components identifying this manager element. There is also a separate identification component that is used to match clips to particular target entities. It’s extremely flexible, but it leaves a lot of fiddly ceremony in the user’s hands, and the nature of the identification means mistakes often result in nothing happening at all - if you’re missing a necessary component on a target entity it simply does not show up in the relevant query, and users are left wondering why until they notice,
This plugin takes a more concrete approach. Users define a component that holds relevant animation
state (whatever that happens to be, I’m not the boss of users), implement the Animation trait
on it, then register the component during app initialization and insert an instance on entities that
should be animated, optionally managing the animation via AnimationCommandsExt or an AnimationController. The
Animation trait enables the plugin to tick the given system according to configuration, and
in general, you’re just writing a normal Bevy ECS code with no restrictions.
Modules§
Structs§
- Animation
Configuration - Encapsulates the configuration for an animation. Construct using the From implementation for f32, which supplies the duration, the minimal requirement.
- Animation
Controller - Control and query
Animations of a given type - Animation
Finished - Observe an entity to get notified when an animation finishes
- Animation
Repeated - Observe an entity to get notified when an animation repeats
- Animation
State - The state of the animation. Users are free to inspect it!
- Animation
Systems - The
SystemSetcontaining all the systems associated to anAnimationtype, exposed for relative ordering - Persistent
Tick - A
Componentwrapper for an optionalTick, to signal that archetype changes should be avoided. - Tick
- Information about the current state of an active
Animation, inserted as a component on the same entity while the animation is active (i.e. started, not paused, not finished) and removed from the entity when the animation is not active (i.e. delayed, paused, finished).
Traits§
- Animation
- Core trait to define a
Componentas an animation, which associates it with a system that insertsTickComponentson entities that have the animation inserted, according to a timeline configured by the component instance. - Animation
AppExt - Extends
Appwith a registration function forAnimations, enabling the plugin to maintain a timeline for the system processing ticks - Animation
Commands Ext - Command interface to control animations commands-style. if you want to make immediate
changes or query internal state live, use
AnimationControlleras a system parameter
Functions§
- duration
- Common case helper because writing
AnimationConfiguration::duration()gets old and (10.0).into() feels off - duration_
f64 - Common case helper because writing
AnimationConfiguration::duration()gets old and (10.0).into() feels off - duration_
time - Common case helper because writing
AnimationConfiguration::duration()gets old and (10.0).into() feels off - forever
- An AnimationConfiguration that runs for 3,600 seconds with 4.3ish billion repetitions
Type Aliases§
- Tick
System Configs - A nice alias
Attribute Macros§
- animation
- Implements the
Animationtrait for the attributed system for the animation type, which is inferred by searching the system parameters for a query referencing aTickorPersistentTickcomponent. If your system configuration is more complicated than a single system with such a query, you’ll need to implement the trait directly