From e9ea5be2f35a8e6f0d1aae3c630bd1c74aecd9a2 Mon Sep 17 00:00:00 2001 From: Jerome Humbert Date: Fri, 27 Oct 2023 21:06:35 +0100 Subject: [PATCH 1/3] Clarify doc around systems Clarify the documentation around animation systems, which ones are added automatically by the `TweeningPlugin` and which ones need to be added manually, depending on which feature is active. - Expand the Setup section of the README to explain the systems need to be added manually for most components and assets, and give a table for built-in ones where the system is automatically added. - Add a similar section to the rustdoc section of `lib.rs`. Also fix a couple of doc links. Bug: #103 --- README.md | 33 ++++++++++++++++++++++++++++++-- src/lib.rs | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++ src/plugin.rs | 4 ++-- 3 files changed, 85 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 602f80a..440d703 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: @@ -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..5374eaf 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_tweening::{lens::*, *}; +//! # let mut app = App::default(); +//! app.add_systems(Update, +//! component_animator_system:: +//! .in_set(AnimationSystem::AnimationUpdate)); +//! ``` +//! +//! Similarly for an asset `A`, use: +//! +//! ``` +//! # use bevy_tweening::{lens::*, *}; +//! # let mut app = App::default(); +//! app.add_systems(Update, +//! asset_animator_system:: +//! .in_set(AnimationSystem::AnimationUpdate)); +//! ``` +//! //! # 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..360a1ed 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`] 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). +//! - 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. +//! 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`? | //! |---|---| @@ -97,22 +102,17 @@ //! To add a system for a component `C`, use: //! //! ``` -//! # use bevy_tweening::{lens::*, *}; +//! # 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: -//! -//! ``` -//! # use bevy_tweening::{lens::*, *}; -//! # let mut app = App::default(); -//! app.add_systems(Update, -//! asset_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 //! diff --git a/src/plugin.rs b/src/plugin.rs index 360a1ed..815571e 100644 --- a/src/plugin.rs +++ b/src/plugin.rs @@ -227,8 +227,8 @@ mod tests { let transform = env.transform(); assert!(transform.is_changed()); - //fn nit() {} - //let mut system = IntoSystem::into_system(nit); + // fn nit() {} + // let mut system = IntoSystem::into_system(nit); let mut system = IntoSystem::into_system(component_animator_system::); system.initialize(env.world_mut());