Skip to main content

Crate bevy_ecs_animations

Crate bevy_ecs_animations 

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

combinators

Structs§

AnimationConfiguration
Encapsulates the configuration for an animation. Construct using the From implementation for f32, which supplies the duration, the minimal requirement.
AnimationController
Control and query Animations of a given type
AnimationFinished
Observe an entity to get notified when an animation finishes
AnimationRepeated
Observe an entity to get notified when an animation repeats
AnimationState
The state of the animation. Users are free to inspect it!
AnimationSystems
The SystemSet containing all the systems associated to an Animation type, exposed for relative ordering
PersistentTick
A Component wrapper for an optional Tick, 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 Component as an animation, which associates it with a system that inserts Tick Components on entities that have the animation inserted, according to a timeline configured by the component instance.
AnimationAppExt
Extends App with a registration function for Animations, enabling the plugin to maintain a timeline for the system processing ticks
AnimationCommandsExt
Command interface to control animations commands-style. if you want to make immediate changes or query internal state live, use AnimationController as 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§

TickSystemConfigs
A nice alias

Attribute Macros§

animation
Implements the Animation trait for the attributed system for the animation type, which is inferred by searching the system parameters for a query referencing a Tick or PersistentTick component. If your system configuration is more complicated than a single system with such a query, you’ll need to implement the trait directly