Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Draft
wants to merge 5 commits into
base: main
Choose a base branch
from

Conversation

ItsDoot
Copy link
Contributor

@ItsDoot ItsDoot commented Oct 3, 2024

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

Showcase

This section is optional. If this PR does not include a visual change or does not add a new feature, you can delete this section.

  • Help others understand the result of this PR by showcasing your awesome work!
  • If this PR adds a new feature or public API, consider adding a brief pseudo-code snippet of it in action
  • If this PR includes a visual change, consider adding a screenshot, GIF, or video
    • If you want, you could even include a before/after comparison!
  • If the Migration Guide adequately covers the changes, you can delete this section

While a showcase should aim to be brief and digestible, you can use a toggleable section to save space on longer showcases:

Click to view showcase
println!("My super cool code.");

Migration Guide

This section is optional. If there are no breaking changes, you can delete this section.

  • If this PR is a breaking change (relative to the last release of Bevy), describe how a user might need to migrate their code to support these changes
  • Simply adding new functionality is not a breaking change.
  • Fixing behavior that was definitely a bug, rather than a questionable design choice is not a breaking change.

@ItsDoot ItsDoot added A-ECS Entities, components, systems, and events C-Usability A targeted quality-of-life change that makes Bevy easier to use D-Modest A "normal" level of difficulty; suitable for simple features or challenging fixes D-Unsafe Touches with unsafe code in some way S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged C-Breaking-Change A breaking change to Bevy's public API that needs to be noted in a migration guide labels Oct 3, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-ECS Entities, components, systems, and events C-Breaking-Change A breaking change to Bevy's public API that needs to be noted in a migration guide C-Usability A targeted quality-of-life change that makes Bevy easier to use D-Modest A "normal" level of difficulty; suitable for simple features or challenging fixes D-Unsafe Touches with unsafe code in some way S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant