Improved Entity Lifecycle: remove flushing, support manual spawning and despawning#19451
Merged
cart merged 104 commits intobevyengine:mainfrom Nov 3, 2025
Merged
Conversation
it's not exact, but it should be good enough.
ElliottjPierce
added
C-Feature
github-merge-queue
bot
removed this pull request from the merge queue due to failed status checks
github-merge-queue bot
pushed a commit
that referenced
this pull request
Nov 4, 2025
# Objective This is a tiny clean up to #19451 that removes some now completely unneeded public constants. I mean, they aren't wrong, but there's no point to their existence. ## Solution Removed `ArchetypeRow::INVALID` and `ArchetypeId::INVALID` and extend migration guide.
github-merge-queue bot
pushed a commit
that referenced
this pull request
Feb 2, 2026
# Objective #19451 changed how entities handle spawning and despawning. One of those changes introduced the idea that despawning an entity from commands while holding an `EntityWorldMut` of that entity made that `EntityWorldMut` invalid and panicked when that happend. Fixes #19828. ## Solution Handle these despawns in the same way as despawning without freeing. This means an `EntityWorldMut` can no longer assume its `EntityId` is valid; it can not assume that its generation is up to date. AFAIK, this restriction doesn't introduce any new or exciting ways for this to fail. It just delays the panics for some cases. For example, despawning from commands and then attempting an insert will panic later (at the insert) instead of earlier (at the despawn). ## Testing - CI
viridia
pushed a commit
to viridia/bevy
that referenced
this pull request
Feb 3, 2026
…22725) # Objective bevyengine#19451 changed how entities handle spawning and despawning. One of those changes introduced the idea that despawning an entity from commands while holding an `EntityWorldMut` of that entity made that `EntityWorldMut` invalid and panicked when that happend. Fixes bevyengine#19828. ## Solution Handle these despawns in the same way as despawning without freeing. This means an `EntityWorldMut` can no longer assume its `EntityId` is valid; it can not assume that its generation is up to date. AFAIK, this restriction doesn't introduce any new or exciting ways for this to fail. It just delays the panics for some cases. For example, despawning from commands and then attempting an insert will panic later (at the insert) instead of earlier (at the despawn). ## Testing - CI
alice-i-cecile
pushed a commit
that referenced
this pull request
Mar 2, 2026
# Objective #19451 changed how entities handle spawning and despawning. One of those changes introduced the idea that despawning an entity from commands while holding an `EntityWorldMut` of that entity made that `EntityWorldMut` invalid and panicked when that happend. Fixes #19828. ## Solution Handle these despawns in the same way as despawning without freeing. This means an `EntityWorldMut` can no longer assume its `EntityId` is valid; it can not assume that its generation is up to date. AFAIK, this restriction doesn't introduce any new or exciting ways for this to fail. It just delays the panics for some cases. For example, despawning from commands and then attempting an insert will panic later (at the insert) instead of earlier (at the despawn). ## Testing - CI
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
12 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Objective
This is the next step for #19430 and is also convinient for #18670.
For context, the way entities work on main is as a "allocate and use" system. Entity ids are allocated, and given a location. The location can then be changed, etc. Entities that are free have an invalid location. To allocate an entity, one must also set its location. This introduced the need for pending entities, where an entity would be reserved, pending, and at some point flushed. Pending and free entities have an invalid location, and others are assumed to have a valid one.
This paradigm has a number of downsides: First, the entities metadata table is inseparable from the allocator, which makes remote reservation challenging. Second, the
Worldmust be flushed, even to do simple things, like allocate a temporary entity id. Third, users have little control over entity ids, only interacting with conceptual entities. This made things likeEntities::alloc_atclunky and slow, leading to its removal, despite some users still having valid need of it.So the goal of this PR is to:
Entitiesfrom entity allocation to make room for other allocators and resolvealloc_atissues.reserveandflushpatterns toallocandconstructpatterns.It is possible to break this up into multiple prs, as I originally intended, but doing so would require lots of temporary scaffolding that would both hurt performance and make things harder to review.
Solution
This solution builds on #19433, which changed the representation of invalid entity locations from a constant to
None.There's quite a few steps to this, each somewhat controversial:
Entities with no location
This pr introduces the idea of entity rows both with and without locations. This corresponds to entities that are constructed (the row has a location) and not constructed (the row has no location). When a row is free or pending, it is not constructed. When a row is outside the range of the meta list, it still exists; it's just not constructed.
This extends to conceptual entities; conceptual entities may now be in one of 3 states: empty (constructed; no components), normal (constructed; 1 or more components), or null (not constructed). This extends to entity pointers (
EntityWorldMut, etc): These now can point to "null"/not constructed entities. Depending on the privilege of the pointer, these can also construct or destruct the entity.This also changes how
Entityids relate to conceptual entities. AnEntitynow exists if its generation matches that of its row. AnEntitythat has the right generation for its row will claim to exist, even if it is not constructed. This means, for example, anEntitymanually constructed with a large index and generation of 0 will exist if it has not been allocated yet.Entitiesis separate from the allocatorThis pr separates entity allocation from
Entities.Entitiesis now only focused on tracking entity metadata, etc. The newEntitiesAllocatoronWorldmanages all allocations. This forcesEntitiesto not rely on allocator state to determine if entities exist, etc, which is convinient for remote reservation and needed for custom allocators. It also paves the way for allocators not housed within theWorld, makes some unsafe code easier since the allocator and metadata live under different pointers, etc.This separation requires thinking about interactions with
Entitiesin a new way. Previously, theEntitiesset the rules for what entities are valid and what entities are not. Now, it has no way of knowing. Instead, interaction withEntitiesare more like declaring some information for it to track than changing some information it was already tracking. To reflect this,sethas been split up intodeclareandupdate.Constructing and destructing
As mentioned, entities that have no location (not constructed) can be constructed at any time. This takes on exactly the same meaning as the previous
spawn_non_existent. It creates/declares a location instead of updating an old one. As an example, this makes spawning an entity now literately just allocate a new id and construct it immediately.Conversely, entities that are constructed may be destructed. This removes all components and despawns related entities, just like
despawn. The only difference is that destructing does not free the entity id for reuse. Between constructing and destructing, all needs foralloc_atare resolved. If you want to keep the id for custom reuse, just destruct instead of despawn! Despawn, now just destructs the entity and frees it.Destructing a not constructed entity will do nothing. Constructing an already constructed entity will panic. This is to guard against users constructing a manually formed
Entitythat the allocator could later hand out. However, public construction methods have proper error handling for this. Despawning a not constructed entity just frees its id.No more flushing
All places that once needed to reserve and flush entity ids now allocate and construct them instead. This improves performance and simplifies things.
Flow chart
(Thanks @ItsDoot)
Testing
Showcase
Here's an example of constructing and destructing
Future Work
Entitydoesn't always correspond to a conceptual entity.EntityWorldMut. There is (and was) a lot of assuming the entity is constructed there (was assuming it was not despawned).Performance
Benchmarks
This roughly doubles command spawning speed! Despawning also sees a 20-30% improvement. Dummy commands improve by 10-50% (due to not needing an entity flush). Other benchmarks seem to be noise and are negligible. It looks to me like a massive performance win!