bevy/crates
Carter Anderson 1db1119819 Replace VisitEntities with MapEntities (#18432)
# Objective

There are currently too many disparate ways to handle entity mapping,
especially after #17687. We now have MapEntities, VisitEntities,
VisitEntitiesMut, Component::visit_entities,
Component::visit_entities_mut.

Our only known use case at the moment for these is entity mapping. This
means we have significant consolidation potential.

Additionally, VisitEntitiesMut cannot be implemented for map-style
collections like HashSets, as you cant "just" mutate a `&mut Entity`.
Our current approach to Component mapping requires VisitEntitiesMut,
meaning this category of entity collection isn't mappable. `MapEntities`
is more generally applicable. Additionally, the _existence_ of the
blanket From impl on VisitEntitiesMut blocks us from implementing
MapEntities for HashSets (or any types we don't own), because the owner
could always add a conflicting impl in the future.

## Solution

Use `MapEntities` everywhere and remove all "visit entities" usages.

* Add `Component::map_entities`
* Remove `Component::visit_entities`, `Component::visit_entities_mut`,
`VisitEntities`, and `VisitEntitiesMut`
* Support deriving `Component::map_entities` in `#[derive(Coomponent)]`
* Add `#[derive(MapEntities)]`, and share logic with the
`Component::map_entities` derive.
* Add `ComponentCloneCtx::queue_deferred`, which is command-like logic
that runs immediately after normal clones. Reframe `FromWorld` fallback
logic in the "reflect clone" impl to use it. This cuts out a lot of
unnecessary work and I think justifies the existence of a pseudo-command
interface (given how niche, yet performance sensitive this is).

Note that we no longer auto-impl entity mapping for ` IntoIterator<Item
= &'a Entity>` types, as this would block our ability to implement cases
like `HashMap`. This means the onus is on us (or type authors) to add
explicit support for types that should be mappable.

Also note that the Component-related changes do not require a migration
guide as there hasn't been a release with them yet.

## Migration Guide

If you were previously implementing `VisitEntities` or
`VisitEntitiesMut` (likely via a derive), instead use `MapEntities`.
Those were almost certainly used in the context of Bevy Scenes or
reflection via `ReflectMapEntities`. If you have a case that uses
`VisitEntities` or `VisitEntitiesMut` directly, where `MapEntities` is
not a viable replacement, please let us know!

```rust
// before
#[derive(VisitEntities, VisitEntitiesMut)]
struct Inventory {
  items: Vec<Entity>,
  #[visit_entities(ignore)]
  label: String,
}

// after
#[derive(MapEntities)]
struct Inventory {
  #[entities]
  items: Vec<Entity>,
  label: String,
}
```
2025-03-24 00:09:29 +01:00
..
bevy_a11y Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_animation Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_app Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_asset Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_audio Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_color Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_core_pipeline Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_derive Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_dev_tools Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_diagnostic Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_dylib enable std when building bevy_dylib (#18405) 2025-03-19 08:03:12 +01:00
bevy_ecs Replace VisitEntities with MapEntities (#18432) 2025-03-24 00:09:29 +01:00
bevy_encase_derive Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_gilrs Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_gizmos Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_gltf Gltf handle missing bindposes (#18419) 2025-03-24 00:09:29 +01:00
bevy_image Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_input Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_input_focus Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_internal Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_log Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_macro_utils Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_math Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_mesh Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_mikktspace Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_pbr Fix specialize_shadows system ordering (#18412) 2025-03-19 21:36:18 +01:00
bevy_picking Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_platform_support Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_ptr Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_reflect Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_remote Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_render Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_scene Replace VisitEntities with MapEntities (#18432) 2025-03-24 00:09:29 +01:00
bevy_sprite Fix unecessary specialization checks for apps with many materials (#18410) 2025-03-19 21:36:18 +01:00
bevy_state Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_tasks Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_text Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_time Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_transform Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_ui Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_utils Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00
bevy_window Replace VisitEntities with MapEntities (#18432) 2025-03-24 00:09:29 +01:00
bevy_winit Release 0.16.0-rc.1 2025-03-18 21:48:22 +01:00