Explain Changed, Added are not archetype filters (#11049)

Explain potential footgun.
This commit is contained in:
Stepan Koltsov 2023-12-21 20:01:03 +00:00 committed by GitHub
parent 8666b076d8
commit b27f74911a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -525,6 +525,36 @@ all_tuples!(impl_query_filter_tuple, 0, 15, F, S);
/// are visible only after deferred operations are applied,
/// typically at the end of the schedule iteration.
///
/// # Time complexity
///
/// `Added` is not [`ArchetypeFilter`], which practically means that
/// if query (with `T` component filter) matches million entities,
/// `Added<T>` filter will iterate over all of them even if none of them were just added.
///
/// For example, these two systems are roughly equivalent in terms of performance:
///
/// ```
/// # use bevy_ecs::change_detection::{DetectChanges, Ref};
/// # use bevy_ecs::entity::Entity;
/// # use bevy_ecs::query::Added;
/// # use bevy_ecs::system::Query;
/// # use bevy_ecs_macros::Component;
/// # #[derive(Component)]
/// # struct MyComponent;
/// # #[derive(Component)]
/// # struct Transform;
///
/// fn system1(q: Query<&MyComponent, Added<Transform>>) {
/// for item in &q { /* component added */ }
/// }
///
/// fn system2(q: Query<(&MyComponent, Ref<Transform>)>) {
/// for item in &q {
/// if item.1.is_added() { /* component added */ }
/// }
/// }
/// ```
///
/// # Examples
///
/// ```
@ -699,6 +729,37 @@ impl<T: Component> QueryFilter for Added<T> {
/// are visible only after deferred operations are applied,
/// typically at the end of the schedule iteration.
///
/// # Time complexity
///
/// `Changed` is not [`ArchetypeFilter`], which practically means that
/// if query (with `T` component filter) matches million entities,
/// `Changed<T>` filter will iterate over all of them even if none of them were changed.
///
/// For example, these two systems are roughly equivalent in terms of performance:
///
/// ```
/// # use bevy_ecs::change_detection::DetectChanges;
/// # use bevy_ecs::entity::Entity;
/// # use bevy_ecs::query::Changed;
/// # use bevy_ecs::system::Query;
/// # use bevy_ecs::world::Ref;
/// # use bevy_ecs_macros::Component;
/// # #[derive(Component)]
/// # struct MyComponent;
/// # #[derive(Component)]
/// # struct Transform;
///
/// fn system1(q: Query<&MyComponent, Changed<Transform>>) {
/// for item in &q { /* component changed */ }
/// }
///
/// fn system2(q: Query<(&MyComponent, Ref<Transform>)>) {
/// for item in &q {
/// if item.1.is_changed() { /* component changed */ }
/// }
/// }
/// ```
///
/// # Examples
///
/// ```