Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
121 changes: 121 additions & 0 deletions _release-content/migration-guides/query_many_iter_results.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
---
title: Query iterators from "many" entities now iterate over `Result` instead of `QueryData::Item`.
pull_requests: [25200]
---

The following iterators now return `Result<QueryData::Item<'w, 's>, QueryEntityError>`
instead of `QueryData::Item<'w, 's>` as the `Iterator::Item`.

- `QueryManyIter`
- `QueryManyUniqueIter`
- `QuerySortedManyIter`

These iterators are created by the following methods.

- `Query::iter_many`
- `Query::iter_many_mut`
- `Query::iter_many_unique`
- `Query::iter_many_unique_mut`
- `QueryManyIter::sort*`

Likewise, the following parallel iterator methods now have `Result<QueryData::Item<'w, 's>, QueryEntityError>`
instead of `QueryData::Item<'w, 's>` as the closure argument.

- `QueryParManyIter::for_each`
- `QueryParManyIter::for_each_init`,
- `QueryParManyUniqueIter::for_each`
- `QueryParManyUniqueIter::for_each_init`,

These parallel iterators are created by the following methods.

- `Query::par_iter_many`
- `Query::par_iter_many_unique`
- `Query::par_iter_many_unique_mut`

These changes were made to allow for full flexibility in handling not matched or not spawned entities.
This allows easier debugging by making these errors visible through a panic or logging
instead of only giving the option to silently ignore these errors.

For `QueryManyIter` and `QueryManyUniqueIter` users can migrate using

- `QueryManyIter::matched`
- `QueryManyUniqueIter::matched`

which provide the same behavior as before.

```rust
// 0.19
fn my_system(entity_list: Res<MyEntityList>, my_component_query: Query<&MyComponent>) {
for my_component in my_component_query.iter_many(entity_list.iter()) {
// ...
}
}

// 0.20
fn my_system(entity_list: Res<MyEntityList>, my_component_query: Query<&MyComponent>) {
for my_component in my_component_query.iter_many(entity_list.iter()).matched() {
// ...
}
}

// 0.19
fn my_mutation_system(entity_list: Res<MyEntityList>, mut my_component_query: Query<&mut MyComponent>) {
let mut iter = my_component_query.iter_many_mut(entity_list.iter());
while let Some(my_component) in iter.fetch_next() {
// ...
}
}

// 0.20
fn my_mutation_system(entity_list: Res<MyEntityList>, mut my_component_query: Query<&mut MyComponent>) {
let mut iter = my_component_query.iter_many_mut(entity_list.iter()).matched();
while let Some(my_component) in iter.fetch_next() {
// ...
}
}
```

For `QuerySortedManyIter` you can only use `.flat_map(Result::ok)`.

```rust
// 0.19
fn my_system(entity_list: Res<MyEntityList>, my_component_query: Query<&MyComponent>) {
for my_component in my_component_query.iter_many(entity_list.iter())
.sort::<&MyComponent>()
{
// ...
}
}

// 0.20
fn my_system(entity_list: Res<MyEntityList>, my_component_query: Query<&MyComponent>) {
for my_component in my_component_query.iter_many(entity_list.iter())
.sort::<&MyComponent>()
.flat_map(Result::ok)
{
// ...
}
}
```

For `QueryParManyIter` and `QueryParManyUniqueIter` you need to return early when there is an error
to get the same `matched` behavior as before.

```rust
// 0.19
fn my_system(entity_list: Res<MyEntityList>, my_component_query: Query<&MyComponent>) {
my_component_query.par_iter_many(entity_list.iter()).for_each(|my_component| {
// ...
});
}

// 0.20
fn my_system(entity_list: Res<MyEntityList>, my_component_query: Query<&MyComponent>) {
my_component_query.par_iter_many(entity_list.iter()).for_each(|my_component| {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

random, and not sure if this is even possible but i wonder if a filter_map could work with the iterator chains better than the let Ok(..) else { }

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since QueryParManyIter does not actually implement the Iterator trait, it is not possible to call Iterator::filter_map.

let Ok(my_component) = my_component else {
return;
};
// ...
});
}
```
4 changes: 3 additions & 1 deletion crates/bevy_dev_tools/src/diagnostics_overlay.rs
Original file line number Diff line number Diff line change
Expand Up @@ -471,7 +471,9 @@ fn collapse_on_click_to_header(
let Ok(children) = diagnostics_overlays.get_mut(child_of.get()) else {
unreachable!("DiagnosticsOverlay has been tempered with. Do not despawn its children.");
};
let mut lists_iter = diagnostics_overlay_contents.iter_many_mut(children.collection());
let mut lists_iter = diagnostics_overlay_contents
.iter_many_mut(children.collection())
.matched();

let Some(mut node) = lists_iter.fetch_next() else {
panic!(
Expand Down
6 changes: 4 additions & 2 deletions crates/bevy_ecs/src/entity/entity_set.rs
Original file line number Diff line number Diff line change
Expand Up @@ -831,8 +831,10 @@ mod tests {
.cloned();

// With `iter_many_mut` collecting is not possible, because you need to drop each `Mut`/`&mut` before the next is retrieved.
let _results: Vec<Mut<Thing>> =
query.iter_many_unique_mut(&mut world, entity_set).collect();
let _results: Vec<Mut<Thing>> = query
.iter_many_unique_mut(&mut world, entity_set)
.unwrapped()
.collect();
}

#[test]
Expand Down
Loading