Allow World::entity family of functions to take multiple entities and get multiple references back

[ItsDoot]

Objective

Following the pattern established in #15593, we can reduce the API surface of World by providing a single function to grab both a singular entity reference, or multiple entity references.

Solution

The following functions can now also take multiple entity IDs and will return multiple entity references back:

• World::entity
• World::get_entity
• World::entity_mut
• World::get_entity_mut
• DeferredWorld::entity_mut
• DeferredWorld::get_entity_mut

If you pass in X, you receive Y:

• give a single Entity, receive a single EntityRef/EntityWorldMut (matches current behavior)
• give a [Entity; N]/&[Entity; N] (array), receive an equally-sized [EntityRef; N]/[EntityMut; N]
• give a &[Entity] (slice), receive a Vec<EntityRef>/Vec<EntityMut>
• give a &EntityHashSet, receive a EntityHashMap<EntityRef>/EntityHashMap<EntityMut>

Note that EntityWorldMut is only returned in the single-entity case, because having multiple at the same time would lead to UB. Also, DeferredWorld receives an EntityMut in the single-entity case because it does not allow structural access.

Testing

• Added doc-tests on World::entity, World::entity_mut, and DeferredWorld::entity_mut
• Added tests for aliased mutability and entity existence

---

Showcase

Click to view showcase

The APIs for fetching EntityRefs and EntityMuts from the World have been unified.

// This code will be referred to by subsequent code blocks.
let world = World::new();
let e1 = world.spawn_empty().id();
let e2 = world.spawn_empty().id();
let e3 = world.spawn_empty().id();

Querying for a single entity remains mostly the same:

// 0.14
let eref: EntityRef = world.entity(e1);
let emut: EntityWorldMut = world.entity_mut(e1);
let eref: Option<EntityRef> = world.get_entity(e1);
let emut: Option<EntityWorldMut> = world.get_entity_mut(e1);

// 0.15
let eref: EntityRef = world.entity(e1);
let emut: EntityWorldMut = world.entity_mut(e1);
let eref: Result<EntityRef, Entity> = world.get_entity(e1);
let emut: Result<EntityWorldMut, Entity> = world.get_entity_mut(e1);

Querying for multiple entities with an array has changed:

// 0.14
let erefs: [EntityRef; 2] = world.many_entities([e1, e2]);
let emuts: [EntityMut; 2] = world.many_entities_mut([e1, e2]);
let erefs: Result<[EntityRef; 2], Entity> = world.get_many_entities([e1, e2]);
let emuts: Result<[EntityMut; 2], QueryEntityError> = world.get_many_entities_mut([e1, e2]);

// 0.15
let erefs: [EntityRef; 2] = world.entity([e1, e2]);
let emuts: [EntityMut; 2] = world.entity_mut([e1, e2]);
let erefs: Result<[EntityRef; 2], Entity> = world.get_entity([e1, e2]);
let emuts: Result<[EntityMut; 2], EntityFetchError> = world.get_entity_mut([e1, e2]);

Querying for multiple entities with a slice has changed:

let ids = vec![e1, e2, e3]);

// 0.14
let erefs: Result<Vec<EntityRef>, Entity> = world.get_many_entities_dynamic(&ids[..]);
let emuts: Result<Vec<EntityMut>, QueryEntityError> = world.get_many_entities_dynamic_mut(&ids[..]);

// 0.15
let erefs: Result<Vec<EntityRef>, Entity> = world.get_entity(&ids[..]);
let emuts: Result<Vec<EntityMut>, EntityFetchError> = world.get_entity_mut(&ids[..]);
let erefs: Vec<EntityRef> = world.entity(&ids[..]); // Newly possible!
let emuts: Vec<EntityMut> = world.entity_mut(&ids[..]); // Newly possible!

Querying for multiple entities with an EntityHashSet has changed:

let set = EntityHashSet::from_iter([e1, e2, e3]);

// 0.14
let emuts: Result<Vec<EntityMut>, QueryEntityError> = world.get_many_entities_from_set_mut(&set);

// 0.15
let emuts: Result<EntityHashMap<EntityMut>, EntityFetchError> = world.get_entity_mut(&set);
let erefs: Result<EntityHashMap<EntityRef>, EntityFetchError> = world.get_entity(&set); // Newly possible!
let emuts: EntityHashMap<EntityMut> = world.entity_mut(&set); // Newly possible!
let erefs: EntityHashMap<EntityRef> = world.entity(&set); // Newly possible!

Migration Guide

• World::get_entity now returns Result<_, Entity> instead of Option<_>.
  • Use world.get_entity(..).ok() to return to the previous behavior.
• World::get_entity_mut and DeferredWorld::get_entity_mut now return Result<_, EntityFetchError> instead of Option<_>.
  • Use world.get_entity_mut(..).ok() to return to the previous behavior.
• Type inference for World::entity, World::entity_mut, World::get_entity, World::get_entity_mut, DeferredWorld::entity_mut, and DeferredWorld::get_entity_mut has changed, and might now require the input argument's type to be explicitly written when inside closures.
• The following functions have been deprecated, and should be replaced as such:
  • World::many_entities -> World::entity::<[Entity; N]>
  • World::many_entities_mut -> World::entity_mut::<[Entity; N]>
  • World::get_many_entities -> World::get_entity::<[Entity; N]>
  • World::get_many_entities_dynamic -> World::get_entity::<&[Entity]>
  • World::get_many_entities_mut -> World::get_entity_mut::<[Entity; N]>
    • The equivalent return type has changed from Result<_, QueryEntityError> to Result<_, EntityFetchError>
  • World::get_many_entities_dynamic_mut -> World::get_entity_mut::<&[Entity]>
    • The equivalent return type has changed from Result<_, QueryEntityError> to Result<_, EntityFetchError>
  • World::get_many_entities_from_set_mut -> World::get_entity_mut::<&EntityHashSet>
    • The equivalent return type has changed from Result<Vec<EntityMut>, QueryEntityError> to Result<EntityHashMap<EntityMut>, EntityFetchError>. If necessary, you can still convert the EntityHashMap into a Vec.

[hymm]

Is is possible to deprecate the existing methods rather than deleting them outright?

[ItsDoot]

Is is possible to deprecate the existing methods rather than deleting them outright?

Yes, I can do that.

[djeedai]

Very neat change and very good quality contribution. Not an ECS expert so maybe need a review from an SME, but otherwise looks good to merge.

[ItsDoot]

Forgot to switch the label :)

[atornity]

I quite like this, although I don't love the fact that get_entity (singular) can now be used with multiple entities. How would you feel about keeping get_entity as a way to get one entity, while using the new WorldEntityFetch stuff with get_many_entities instead?

[bushrat011899]

I quite like this, although I don't love the fact that get_entity (singular) can now be with multiple entities.

Personally, I think that's reasonable, considering that Vec and [T] have a get method that can return either a single value or multiple values depending on the indexing type.

[atornity]

Personally, I think that's reasonable, considering that Vec and [T] have a get method that can return either a single value or multiple values depending on the indexing type.

Ah I didn't even know that xp. Altough to be fair (to me), it is called get, that could just as easily be interpreted as "get many" as "get one", so that case makes more sense to me.

[ItsDoot]

I don't mind looking for a better fitting name, but I would prefer having just two functions (one for immutable, one for mutable) for fetching entities.

EDIT: Well, 4 total for the panicking vs non-panicking variants.

[alice-i-cecile]

Thank you to everyone involved with the authoring or reviewing of this PR! This work is relatively important and needs release notes! Head over to bevyengine/bevy-website#1717 if you'd like to help out.