Skip to content

Update documentation for WorldQuery and filters #11952

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 18, 2024
Merged

Update documentation for WorldQuery and filters #11952

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 5 additions & 7 deletions crates/bevy_ecs/src/query/filter.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,8 +70,6 @@ use std::{cell::UnsafeCell, marker::PhantomData};
/// [`matches_component_set`]: Self::matches_component_set
/// [`Query`]: crate::system::Query
/// [`State`]: Self::State
/// [`update_archetype_component_access`]: Self::update_archetype_component_access
/// [`update_component_access`]: Self::update_component_access

pub trait QueryFilter: WorldQuery {
/// Returns true if (and only if) this Filter relies strictly on archetypes to limit which
Expand Down Expand Up @@ -123,7 +121,7 @@ pub trait QueryFilter: WorldQuery {
pub struct With<T>(PhantomData<T>);

/// SAFETY:
/// `update_component_access` and `update_archetype_component_access` do not add any accesses.
/// `update_component_access` does not add any accesses.
/// This is sound because `fetch` does not access any components.
/// `update_component_access` adds a `With` filter for `T`.
/// This is sound because `matches_component_set` returns whether the set contains the component.
Expand Down Expand Up @@ -231,7 +229,7 @@ impl<T: Component> QueryFilter for With<T> {
pub struct Without<T>(PhantomData<T>);

/// SAFETY:
/// `update_component_access` and `update_archetype_component_access` do not add any accesses.
/// `update_component_access` does not add any accesses.
/// This is sound because `fetch` does not access any components.
/// `update_component_access` adds a `Without` filter for `T`.
/// This is sound because `matches_component_set` returns whether the set does not contain the component.
Expand Down Expand Up @@ -366,7 +364,7 @@ macro_rules! impl_query_filter_tuple {
#[allow(clippy::unused_unit)]
/// SAFETY:
/// `fetch` accesses are a subset of the subqueries' accesses
/// This is sound because `update_component_access` and `update_archetype_component_access` adds accesses according to the implementations of all the subqueries.
/// This is sound because `update_component_access` adds accesses according to the implementations of all the subqueries.
/// `update_component_access` replace the filters with a disjunction where every element is a conjunction of the previous filters and the filters of one of the subqueries.
/// This is sound because `matches_component_set` returns a disjunction of the results of the subqueries' implementations.
unsafe impl<$($filter: QueryFilter),*> WorldQuery for Or<($($filter,)*)> {
Expand Down Expand Up @@ -579,7 +577,7 @@ pub struct AddedFetch<'w> {

/// SAFETY:
/// `fetch` accesses a single component in a readonly way.
/// This is sound because `update_component_access` and `update_archetype_component_access` add read access for that component and panic when appropriate.
/// This is sound because `update_component_access` adds read access for that component and panics when appropriate.
/// `update_component_access` adds a `With` filter for a component.
/// This is sound because `matches_component_set` returns whether the set contains that component.
unsafe impl<T: Component> WorldQuery for Added<T> {
Expand Down Expand Up @@ -779,7 +777,7 @@ pub struct ChangedFetch<'w> {

/// SAFETY:
/// `fetch` accesses a single component in a readonly way.
/// This is sound because `update_component_access` and `update_archetype_component_access` add read access for that component and panic when appropriate.
/// This is sound because `update_component_access` add read access for that component and panics when appropriate.
/// `update_component_access` adds a `With` filter for a component.
/// This is sound because `matches_component_set` returns whether the set contains that component.
unsafe impl<T: Component> WorldQuery for Changed<T> {
Expand Down
6 changes: 3 additions & 3 deletions crates/bevy_ecs/src/query/world_query.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,6 @@ pub unsafe trait WorldQuery {
///
/// # Safety
///
/// - `world` must have permission to access any of the components specified in `Self::update_archetype_component_access`.
/// - `state` must have been initialized (via [`WorldQuery::init_state`]) using the same `world` passed
/// in to this function.
unsafe fn init_fetch<'w>(
Expand Down Expand Up @@ -128,7 +127,8 @@ pub unsafe trait WorldQuery {
/// Creates and initializes a [`State`](WorldQuery::State) for this [`WorldQuery`] type.
fn init_state(world: &mut World) -> Self::State;

/// Attempts to initializes a [`State`](WorldQuery::State) for this [`WorldQuery`] type.
/// Attempts to initialize a [`State`](WorldQuery::State) for this [`WorldQuery`] type using read-only
/// access to the [`World`].
fn get_state(world: &World) -> Option<Self::State>;

/// Returns `true` if this query matches a set of components. Otherwise, returns `false`.
Expand All @@ -145,7 +145,7 @@ macro_rules! impl_tuple_world_query {
#[allow(clippy::unused_unit)]
/// SAFETY:
/// `fetch` accesses are the conjunction of the subqueries' accesses
/// This is sound because `update_component_access` and `update_archetype_component_access` adds accesses according to the implementations of all the subqueries.
/// This is sound because `update_component_access` adds accesses according to the implementations of all the subqueries.
/// `update_component_access` adds all `With` and `Without` filters from the subqueries.
/// This is sound because `matches_component_set` always returns `false` if any the subqueries' implementations return `false`.
unsafe impl<$($name: WorldQuery),*> WorldQuery for ($($name,)*) {
Expand Down