Query filters
Narrow a query with With, Without, Or, Added, Changed, Spawned and Allow, combine filters, and define reusable filter types.
On this page
The second type parameter of a Query is a filter. A filter decides which entities match without fetching any data from them. Use it to pick out entities by a marker component, to exclude some, or to see only what changed since the system last ran.
use neo::prelude::*;
#[derive(Component)]
struct Enemy;
#[derive(Component)]
struct Frozen;
// enemies that aren't frozen
fn move_enemies(mut query: Query<&mut Transform, (With<Enemy>, Without<Frozen>)>) {
for mut transform in &mut query {
transform.translation.x += 1.0;
}
}The filters#
| Filter | Matches entities that |
|---|---|
With<T> | have a T. |
Without<T> | don't have a T. |
Or<(F1, F2, ..)> | pass at least one of the filters. |
(F1, F2, ..) | pass all of the filters (a tuple means "and"). |
Added<T> | had T added since this system last ran. |
Changed<T> | had T added or written to since this system last ran. |
Spawned | were spawned since this system last ran. Import it from neo::ecs::query::Spawned. |
Allow<T> | have or don't have T, overriding a default filter that would hide them, such as Disabled. |
With and Without don't fetch the component, so they also work for marker types that carry no data, and they don't count as access to it. That's why Without<Player> can make a second mutable query on Transform legal next to one that has With<Player>.
Combine filters#
#[derive(Component)]
struct Player;
#[derive(Component)]
struct Npc;
#[derive(Component)]
struct Health(u32);
// players or NPCs whose health changed this frame
fn show_health(query: Query<(&Name, &Health), (Or<(With<Player>, With<Npc>)>, Changed<Health>)>) {
for (name, health) in &query {
info!("{name}: {}", health.0);
}
}Added and Changed#
Added<T> and Changed<T> compare the component's change ticks with the last time this system ran, so each system sees each change once:
- the first time a system runs, everything counts as added and changed;
Changed<T>also matches whenTwas just added;- a change is any write through a
Mut<T>orResMut<T>(any mutable dereference), even if the value stayed the same. Only fetching&mut Twithout writing doesn't count. Useset_if_neqto avoid marking unchanged values. See Change detection.
fn on_new_enemy(query: Query<Entity, Added<Enemy>>) {
for entity in &query {
info!("enemy {entity} appeared");
}
}Default filters and disabled entities#
Some components hide entities from every query that doesn't mention them. The built-in one is Disabled. With<Disabled>, Has<Disabled> or Allow<Disabled> in a query let it see disabled entities. See Disable an entity.
Reusable filters#
Derive QueryFilter to give a combination of filters a name:
use neo::ecs::query::QueryFilter;
#[derive(QueryFilter)]
struct ActiveEnemy {
_enemy: With<Enemy>,
_not_frozen: Without<Frozen>,
}
fn tick(query: Query<&Transform, ActiveEnemy>) {
for transform in &query {
// ...
}
}Filters in run conditions#
The same filters drive some run conditions:
app.add_systems(Update, boss_music.run_if(any_with_component::<Boss>));
app.add_systems(Update, rebuild_nav.run_if(any_match_filter::<Changed<Obstacle>>));