Struct DefaultQueryFilters 

pub struct DefaultQueryFilters { /* private fields */ }

Default query filters work by excluding entities with certain components from most queries.

If a query does not explicitly mention a given disabling component, it will not include entities with that component. To be more precise, this checks if the query’s FilteredAccess contains the component, and if it does not, adds a Without filter for that component to the query.

Allow and Has can be used to include entities with and without the disabling component. Allow is a QueryFilter and will simply change the list of shown entities, while Has is a QueryData and will allow you to see if each entity has the disabling component or not.

This resource is initialized in the World whenever a new world is created, with the Disabled component as a disabling component.

Note that you can remove default query filters by overwriting the DefaultQueryFilters resource. This can be useful as a last resort escape hatch, but is liable to break compatibility with other libraries.

See the module docs for more info.

Warning

Default query filters are a global setting that affects all queries in the World, and incur a small performance cost for each query.

They can cause significant interoperability issues within the ecosystem, as users must be aware of each disabling component in use.

Think carefully about whether you need to use a new disabling component, and clearly communicate their presence in any libraries you publish.

Implementations

impl DefaultQueryFilters

pub fn empty() -> Self

Creates a new, completely empty DefaultQueryFilters.

This is provided as an escape hatch; in most cases you should initialize this using FromWorld, which is automatically called when creating a new World.

pub fn register_disabling_component(&mut self, component_id: ComponentId)

Adds this ComponentId to the set of DefaultQueryFilters, causing entities with this component to be excluded from queries.

This method is idempotent, and will not add the same component multiple times.

Warning

This method should only be called before the app starts, as it will not affect queries initialized before it is called.

As discussed in the module docs, this can have performance implications, as well as create interoperability issues, and should be used with caution.

pub fn disabling_ids(&self) -> impl Iterator<Item = ComponentId>

Get an iterator over all of the components which disable entities when present.

Trait Implementations

impl Debug for DefaultQueryFilters

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromWorld for DefaultQueryFilters

fn from_world(world: &mut World) -> Self

Creates Self using data from the given World.

impl Resource for DefaultQueryFilters

where Self: Send + Sync + 'static,