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

// 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();

// 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);

// 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]);

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!

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.