From 6d5fe304b15f5e1aab5a8de477a066110df14dc3 Mon Sep 17 00:00:00 2001 From: Ellen Date: Thu, 12 May 2022 15:20:27 +0100 Subject: [PATCH] filtered access docs --- crates/bevy_ecs/src/query/access.rs | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/crates/bevy_ecs/src/query/access.rs b/crates/bevy_ecs/src/query/access.rs index f9855f06def6d..5567075015687 100644 --- a/crates/bevy_ecs/src/query/access.rs +++ b/crates/bevy_ecs/src/query/access.rs @@ -148,6 +148,23 @@ impl Access { /// An [`Access`] that has been filtered to include and exclude certain combinations of elements. /// /// Used internally to statically check if queries are disjoint. +/// +/// Subtle: a `read` or `write` in `access` should not be considered to imply a +/// `with` access. +/// +/// For example consider `Query>` this only has a `read` of `T` as doing +/// otherwise would allow for queriess to be considered disjoint that actually arent: +/// - `Query<(&mut T, Option<&U>)>` read/write `T`, read `U`, with `U` +/// - `Query<&mut T, Without>` read/write `T`, without `U` +/// from this we could reasonably conclude that the queries are disjoint but they aren't. +/// +/// In order to solve this the actual access that `Query<(&mut T, Option<&U>)>` has +/// is read/write `T`, read `U`. It must still have a read `U` access otherwise the following +/// queries would be incorrectly considered disjoint: +/// - `Query<&mut T>` read/write `T` +/// - `Query` accesses nothing +/// +/// See comments the `WorldQuery` impls of `AnyOf`/`Option`/`Or` for more information. #[derive(Debug, Clone, Eq, PartialEq)] pub struct FilteredAccess { access: Access,