diff --git a/README.md b/README.md index 602f80a..71c6e2c 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,35 @@ App::default() .run(); ``` +This provides the basic setup for using 🍃 Bevy Tweening. However, additional setup is required depending on the components and assets you want to animate: + +- To ensure a component `C` is animated, the `component_animator_system::` system must run each frame, in addition of adding an `Animator::` component to the same Entity as `C`. + +- To ensure an asset `A` is animated, the `asset_animator_system::` system must run each frame, in addition of adding an `AssetAnimator` component to any Entity. Animating assets also requires the `bevy_asset` feature (enabled by default). + +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 Asset | Animation system added by `TweeningPlugin`? | +|---|---| +| `Transform` | Yes | +| `Sprite` | Only if `bevy_sprite` feature | +| `ColorMaterial` | Only if `bevy_sprite` feature | +| `Style` | Only if `bevy_ui` feature | +| `Text` | Only if `bevy_text` feature | +| All other components | No | + +To add a system for a component `C`, use: + +```rust +app.add_systems(Update, component_animator_system::.in_set(AnimationSystem::AnimationUpdate)); +``` + +Similarly for an asset `A`, use: + +```rust +app.add_systems(Update, asset_animator_system::.in_set(AnimationSystem::AnimationUpdate)); +``` + ### Animate a component Animate the transform position of an entity by creating a `Tween` animation for the transform, and adding an `Animator` component with that tween: @@ -170,7 +199,7 @@ The two formulations are mathematically equivalent, but one may be more suited t ## Custom component support -Custom components are animated like built-in Bevy ones, via a lens. +Custom components are animated via a lens like the ones described in (Bevy Components)[#bevy-components]. ```rust #[derive(Component)] @@ -188,11 +217,11 @@ impl Lens for MyCustomLens { } ``` -Then, in addition, the system `component_animator_system::` needs to be added to the application. This system will extract each frame all `CustomComponent` instances with an `Animator` on the same entity, and animate the component via its animator. +Then, in addition, the system `component_animator_system::` needs to be added to the application, as described in [System Setup](#system-setup). This system will extract each frame all `CustomComponent` instances with an `Animator` on the same entity, and animate the component via its animator. ## 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::`. This requires the `bevy_asset` feature (enabled by default). +The process is similar to custom components, creating a custom lens for the custom asset. The system to add is `asset_animator_system::`, as described in [System Setup](#system-setup). This requires the `bevy_asset` feature (enabled by default). ## Examples diff --git a/src/lib.rs b/src/lib.rs index 89f5d67..5bde6d1 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -64,6 +64,56 @@ //! # } //! ``` //! +//! 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: +//! +//! - To ensure a component `C` is animated, the +//! [`component_animator_system::`] system must run each frame, in addition +//! of adding an [`Animator::`] component to the same Entity as `C`. +//! +//! - To ensure an asset `A` is animated, the [`asset_animator_system::`] +//! system must run each frame, in addition of adding an [`AssetAnimator`] +//! component to any Entity. Animating assets also requires the `bevy_asset` +//! feature (enabled by default). +//! +//! 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 Asset | Animation system added by `TweeningPlugin`? | +//! |---|---| +//! | [`Transform`] | Yes | +//! | [`Sprite`] | Only if `bevy_sprite` feature | +//! | [`ColorMaterial`] | Only if `bevy_sprite` feature | +//! | [`Style`] | Only if `bevy_ui` feature | +//! | [`Text`] | Only if `bevy_text` feature | +//! | All other components | No | +//! +//! To add a system for a component `C`, use: +//! +//! ``` +//! # use bevy::prelude::*; +//! # use bevy_tweening::*; +//! # let mut app = App::default(); +//! # #[derive(Component)] struct C; +//! app.add_systems(Update, +//! component_animator_system:: +//! .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 @@ -150,6 +200,8 @@ //! [`Query`]: https://docs.rs/bevy/0.11.0/bevy/ecs/system/struct.Query.html //! [`ColorMaterial`]: https://docs.rs/bevy/0.11.0/bevy/sprite/struct.ColorMaterial.html //! [`Sprite`]: https://docs.rs/bevy/0.11.0/bevy/sprite/struct.Sprite.html +//! [`Style`]: https://docs.rs/bevy/0.11.0/bevy/ui/struct.Style.html +//! [`Text`]: https://docs.rs/bevy/0.11.0/bevy/text/struct.Text.html //! [`Transform`]: https://docs.rs/bevy/0.11.0/bevy/transform/components/struct.Transform.html use std::time::Duration; diff --git a/src/plugin.rs b/src/plugin.rs index 0f2e025..815571e 100644 --- a/src/plugin.rs +++ b/src/plugin.rs @@ -79,7 +79,7 @@ pub enum AnimationSystem { /// Animator system for components. /// -/// This system extracts all components of type `T` with an `Animator` +/// This system extracts all components of type `T` with an [`Animator`] /// attached to the same entity, and tick the animator to animate the component. pub fn component_animator_system( time: Res