Add an `Entry` api to `EntityWorldMut`. #10650

13ros27 · 2023-11-20T02:41:27Z

Objective

Adds .entry to EntityWorldMut with Entry, OccupiedEntry and VacantEntry for easier in-situ modification, based on HashMap.entry.

Fixes #10635

Solution

This adds the entry method to EntityWorldMut which returns an Entry. This is an enum of OccupiedEntry and VacantEntry and has the methods and_modify, insert_entry, or_insert, or_insert_with and or_default. The only difference between OccupiedEntry and VacantEntry is the type, they are both a mutable reference to the EntityWorldMut and a marker for the component type, HashMap also stores things to make it quicker to access the data in OccupiedEntry but I wasn't sure if we had anything it would be logical to store to make accessing/modifying the component faster? As such, the differences are that OccupiedEntry assumes the entity has the component (because nothing else can have an EntityWorldMut so it can't be changed outside the entry api) and has different methods.

All the methods are based very closely off hashbrown::HashMap (because its easier to read the source of) with a couple of quirks like OccupiedEntry.insert doesn't return the old value because we don't appear to have an api for mem::replacing components.

Changelog

Added a new function EntityWorldMut.entry which returns an Entry, allowing easier in-situ modification of a component.

…ifetime transmutation with questionable safety, question for the future

…insert (more questionable transmutation)

…ed (otherwise we should be using `or_insert`)

…he documentation

crates/bevy_ecs/src/world/entity_ref.rs

viridia · 2023-11-20T02:52:07Z

Meets my needs. Minor nit on doc comment.

DasLixou · 2023-11-20T05:47:43Z

Could we also get those for commands?

viridia · 2023-11-20T06:51:02Z

Could we also get those for commands?

Since commands are asynchronous, this would be more difficult: you can't insert a component and get back the same component instance in the same tick (I think).

crates/bevy_ecs/src/world/entity_ref.rs

DasLixou · 2023-11-20T11:56:34Z

Could we also get those for commands?

Since commands are asynchronous, this would be more difficult: you can't insert a component and get back the same component instance in the same tick (I think).

Should be possible when we introduce a EntityEntryCommands thing like EntityCommands which you can call or_insert, etc. on but when executing the command we do the entry thing, right?

Co-authored-by: Pascal Hertleif <[email protected]>

alice-i-cecile · 2023-11-20T12:56:37Z

Should be possible when we introduce a EntityEntryCommands thing like EntityCommands

Agreed, but let's leave that for another PR :)

crates/bevy_ecs/src/world/entity_ref.rs

alice-i-cecile · 2023-11-20T13:41:00Z

crates/bevy_ecs/src/world/entity_ref.rs

+ /// assert_eq!(world.query::<&Comp>().single(&world).0, 0);
+ /// ```
+ #[inline]
+ pub fn or_default(self) -> Mut<'a, T> {


Might be nice to make both a FromReflect and FromWorld equivalent, but those can wait.

crates/bevy_ecs/src/world/entity_ref.rs

alice-i-cecile

Very clean construction, and a useful bit of API.

IMO we should replace the unwrap_unchecked with simple unwrap. Unless there's compelling benchmarks, I would much rather have surprising panics than risk UB in a refactor or edge case.

…plaining how it must be occupied before being created (it has private fields so this shouldn't be a problem for user code).

…comments explaining why it should never panic.

13ros27 · 2023-11-20T20:17:15Z

Replacing unwrap_unchecked makes sense to me, I do plan to make some (micro-)benchmarks for this to see whether it is faster to store the archetype or something but that will wait for a future PR.

# Objective Adds `.entry` to `EntityWorldMut` with `Entry`, `OccupiedEntry` and `VacantEntry` for easier in-situ modification, based on `HashMap.entry`. Fixes bevyengine#10635 ## Solution This adds the `entry` method to `EntityWorldMut` which returns an `Entry`. This is an enum of `OccupiedEntry` and `VacantEntry` and has the methods `and_modify`, `insert_entry`, `or_insert`, `or_insert_with` and `or_default`. The only difference between `OccupiedEntry` and `VacantEntry` is the type, they are both a mutable reference to the `EntityWorldMut` and a marker for the component type, `HashMap` also stores things to make it quicker to access the data in `OccupiedEntry` but I wasn't sure if we had anything it would be logical to store to make accessing/modifying the component faster? As such, the differences are that `OccupiedEntry` assumes the entity has the component (because nothing else can have an `EntityWorldMut` so it can't be changed outside the entry api) and has different methods. All the methods are based very closely off `hashbrown::HashMap` (because its easier to read the source of) with a couple of quirks like `OccupiedEntry.insert` doesn't return the old value because we don't appear to have an api for mem::replacing components. --- ## Changelog - Added a new function `EntityWorldMut.entry` which returns an `Entry`, allowing easier in-situ modification of a component. --------- Co-authored-by: Alice Cecile <[email protected]> Co-authored-by: Pascal Hertleif <[email protected]>

13ros27 added 14 commits November 19, 2023 23:37

Added Entry, OccupiedEntry and VacantEntry

7dc910a

Added Entry.add_modify which uses OccupiedEntry.get_mut, which does l…

d5c0e23

…ifetime transmutation with questionable safety, question for the future

Added Entry.or_default, using OccupiedEntry.into_mut and VacantEntry.…

17b924e

…insert (more questionable transmutation)

Added Entry.insert_entry

808e2b1

Added Entry.or_insert

35804b0

Added Entry.or_insert_with

568cfca

Fixed Entry.insert_entry so that it will change the value if Occupi…

a68f114

…ed (otherwise we should be using `or_insert`)

Fixed lifetimes and signatures to avoid the insane lifetime alchemy

fa5ed2b

Added OccupiedEntry.get and OccupiedEntry.take

215ab4c

Moved _marker to after entity_world

1e27ce2

Added basic docs (no examples yet)

d936215

Fixed some doc-links and made these types public so they show up in t…

6636a52

…he documentation

Added examples to all of Entry's methods

1ce81c2

Added examples to the methods of OccupiedEntry and VacantEntry

b7ebc40

13ros27 mentioned this pull request Nov 20, 2023

Provide a convenient method for lazy Component creation based on HashMap::entry #10635

Closed

Appeased clippy

2190952

viridia reviewed Nov 20, 2023

View reviewed changes

crates/bevy_ecs/src/world/entity_ref.rs Outdated Show resolved Hide resolved

Adjusted doc comment 'default' -> 'given default'

71e0e81

viridia approved these changes Nov 20, 2023

View reviewed changes

killercup reviewed Nov 20, 2023

View reviewed changes

crates/bevy_ecs/src/world/entity_ref.rs Show resolved Hide resolved

alice-i-cecile added A-ECS Entities, components, systems, and events C-Usability A targeted quality-of-life change that makes Bevy easier to use labels Nov 20, 2023

Add doc test

d69e4fa

Co-authored-by: Pascal Hertleif <[email protected]>

alice-i-cecile reviewed Nov 20, 2023

View reviewed changes

crates/bevy_ecs/src/world/entity_ref.rs Outdated Show resolved Hide resolved

alice-i-cecile reviewed Nov 20, 2023

View reviewed changes

crates/bevy_ecs/src/world/entity_ref.rs Outdated Show resolved Hide resolved

alice-i-cecile added the D-Complex Quite challenging from either a design or technical perspective. Ask for help! label Nov 20, 2023

alice-i-cecile requested changes Nov 20, 2023

View reviewed changes

13ros27 added 3 commits November 20, 2023 20:04

Fixed doc-test

0c989d8

Adjusted doc comment and added an extra comment to OccupiedEntry ex…

55c688b

…plaining how it must be occupied before being created (it has private fields so this shouldn't be a problem for user code).

Replaced unwrap_unchecked with unwrap and changed safety comments to …

0ec411c

…comments explaining why it should never panic.

alice-i-cecile approved these changes Nov 20, 2023

View reviewed changes

alice-i-cecile added the S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it label Nov 20, 2023

alice-i-cecile mentioned this pull request Nov 21, 2023

Add an Entry-style API for working with component data on Commands #10669

Closed

alice-i-cecile added this pull request to the merge queue Nov 21, 2023

Merged via the queue into bevyengine:main with commit 865041d Nov 21, 2023
22 checks passed

13ros27 deleted the entity_world_mut_entry branch October 4, 2024 10:33

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add an `Entry` api to `EntityWorldMut`. #10650

Add an `Entry` api to `EntityWorldMut`. #10650

13ros27 commented Nov 20, 2023

viridia commented Nov 20, 2023

DasLixou commented Nov 20, 2023

viridia commented Nov 20, 2023 •

edited

Loading

DasLixou commented Nov 20, 2023

alice-i-cecile commented Nov 20, 2023

alice-i-cecile Nov 20, 2023

alice-i-cecile left a comment

13ros27 commented Nov 20, 2023

Add an Entry api to EntityWorldMut. #10650

Add an Entry api to EntityWorldMut. #10650

Conversation

13ros27 commented Nov 20, 2023

Objective

Solution

Changelog

viridia commented Nov 20, 2023

DasLixou commented Nov 20, 2023

viridia commented Nov 20, 2023 • edited Loading

DasLixou commented Nov 20, 2023

alice-i-cecile commented Nov 20, 2023

alice-i-cecile Nov 20, 2023

Choose a reason for hiding this comment

alice-i-cecile left a comment

Choose a reason for hiding this comment

13ros27 commented Nov 20, 2023

Add an `Entry` api to `EntityWorldMut`. #10650

Add an `Entry` api to `EntityWorldMut`. #10650

viridia commented Nov 20, 2023 •

edited

Loading