From 64b29617d682e44aafd981a501a03475b7a643e5 Mon Sep 17 00:00:00 2001 From: sdfgeoff Date: Sat, 6 Mar 2021 01:57:01 +0000 Subject: [PATCH] Added documentation on the query filters (#1553) This documents both the non-obvious interaction with non-explicit system ordering and adds examples for Changed and Added. This likely closes #1551 --- crates/bevy_ecs/src/query/filter.rs | 53 +++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/crates/bevy_ecs/src/query/filter.rs b/crates/bevy_ecs/src/query/filter.rs index 1f9d8c8eea..ff977445d3 100644 --- a/crates/bevy_ecs/src/query/filter.rs +++ b/crates/bevy_ecs/src/query/filter.rs @@ -574,6 +574,29 @@ macro_rules! impl_flag_filter { impl_flag_filter!( /// Filter that retrieves components of type `T` that have been added since the start of the frame + /// + /// This filter is useful as a performance optimization as it means that the query contains fewer items + /// for a system to iterate over. + /// + /// Because the ordering of systems can change and this filter is only effective on changes before the query executes + /// you need to use explicit dependency ordering or ordered stages for these query filters to be useful. + /// + /// + /// Example: + /// ``` + /// # use bevy_ecs::system::Query; + /// # use bevy_ecs::query::Added; + /// # + /// # #[derive(Debug)] + /// # struct Name {}; + /// # struct Transform {}; + /// # + /// fn print_add_name_component(query: Query<&Name, Added>) { + /// for name in query.iter() { + /// println!("Named entity created: {:?}", name) + /// } + /// } + /// ``` Added, AddedState, AddedFetch, @@ -583,6 +606,28 @@ impl_flag_filter!( impl_flag_filter!( /// Filter that retrieves components of type `T` that have been mutated since the start of the frame. /// Added components do not count as mutated. + /// + /// This filter is useful as a performance optimization as it means that the query contains fewer items + /// for a system to iterate over. + /// + /// Because the ordering of systems can change and this filter is only effective on changes before the query executes + /// you need to use explicit dependency ordering or ordered stages for these query filters to be useful. + /// + /// Example: + /// ``` + /// # use bevy_ecs::system::Query; + /// # use bevy_ecs::query::Mutated; + /// # + /// # #[derive(Debug)] + /// # struct Name {}; + /// # struct Transform {}; + /// # + /// fn print_moving_objects_system(query: Query<&Name, Mutated>) { + /// for name in query.iter() { + /// println!("Entity Moved: {:?}", name) + /// } + /// } + /// ``` Mutated, MutatedState, MutatedFetch, @@ -591,6 +636,14 @@ impl_flag_filter!( impl_flag_filter!( /// Filter that retrieves components of type `T` that have been added or mutated since the start of the frame + /// + /// This filter is useful as a performance optimization as it means that the query contains fewer items + /// for a system to iterate over. + /// + /// Because the ordering of systems can change and this filter is only effective on changes before the query executes + /// you need to use explicit dependency ordering or ordered stages for these query filters to be useful. + /// + /// Also see the documentation for [`Mutated`] and [`Added`] as this filter is a logical OR of them. Changed, ChangedState, ChangedFetch,