Retain Rendering World #14449

re0312 · 2024-07-23T09:34:38Z

Objective

fix Render world blocking certain ecs developments #12144 ,compare to Persistent Render World #14252
We want Relations! However, the render world currently hinders the development of * as entities because it needs to despawn all entities each frame to ensure consistent entity IDs between the main world and render world.

Solution

Transition to a strategy of maintaining entity-to-entity mapping between the main world and render world, abandoning the method of removing all entities every frame.
Use Observer to listen the components that tis entity needs to be synchronized to the render world.
Before executing the extract schedule, the entity_sync_system will be run first, which is responsible for maintaining the entity mapping between the main world and the rendering world

Bevy Schedule

Alternative(s)

we could using Resource to manage all rendering entity component data so that we don't have any entities at all.

Advantages

We can continue to use ECS in rendering, which can bring more performance advantages in many aspects(Retain redering world + update in place)
More consistent primitives, as Bevy is entirely based on ECS.

Drawbacks

Once a component has a dependency relationship on other main world entities, this relationship must also be synchronized to the rendering world, which undoubtedly increases the user's mental burden
Not all the entities are in sync with the rendering world, And that makes it pretty confusing to tell apart the entities in the main world from those in the rendering world when we're in the middle of rendering stuff. And considering our extensive use of EntityHashmap to handle rendering data. that's could made everything even more of a headache to deal with.

Performance

cargo run --release --example many_cubes --features bevy/trace_tracy
red is main

cargo run --release --example many_foxes --features bevy/trace_tracy

cargo run --release --example many_buttons --features bevy/trace_tracy

~30% loss
The majority of the performance loss from the spawn(~3ms) and despawn(~3ms) operations of ephemeral entity.

Next Steps

Stop spawn temporary entities and depsawn it every frame , it could persist in render world
Update in place for instance data instead re-insert it per frame

Migration Guide

Render world no longer clear all entities per frame , Instead, You must manually control the spawn and despawn of render entities properly.

Before this pr ,extract would copy the related main world entity and its data into render world. Then, the render world clear all render entities at the end of the frame to reserve enough entity space, ensuring that no main world entity ID would be occupied when next extract.

For the sake of * as entities, we turn to an entity-to-entity mapping strategy to sync between main world entity and render world entity, where each synchronized main entity has a RenderEntity component that holds an Entity ID pointer to its unique counterpart entity in the render world.

To establish a "Synchronous Relationship", you can add a SyncRenderWorld component to an entity, indicating that it needs to be synchronized to the render world. (Currently, its added by default in Camera2dBundle , Camera3dBundle, DirectionalLightBundle, SpotLightBundle, PointLightBundle, SpriteBundle, and SpriteSheetBundle.)

Once a synchronized main entity despawned ,its corresponding render entity will automatically be purged before next extract.

Temporary entities are part of entities in render world , bevy's renderer spawns numerous temporary entities for rendering per frame , which need to be cleared at the end of each frame.
To avoid duplicating spawn these entities each frame,you can add a TemporaryRenderEntity component to it. Bevy will then automatically clean up it at the end of each frame. But as best you should turn to persisit entity in render world instead of spawn and clear them every frame.

ExtractComponentPlugin now only extracts "Synchronized" entity to render world.

Co-Authored-By:Trashtalk217 Trashtalk217@gmail.com

re0312 · 2024-07-23T10:02:51Z

Added @Trashtalk217 as coauthor ,because this pr was highly inspired by his work #14252

NthTensor · 2024-08-27T20:12:18Z

The big thing this actually appears to be lacking is documentation. Alice mentioned wanting a broad overview of how extraction works. This is, imo, a blocking requirement. It should probably live in module docs and (contain at-least one easily broken doc-test so we are forced to keep it up to date).

JMS55 · 2024-08-28T05:17:22Z

Meshlets seem good now based on how the new extraction system has been described to me. I'll make further improvements to cache resources on view entities directly in a followup PR.

In terms of getting this merged, I agree we need a lot more docs on this. I don't have time to do another review pass over the code and test all the examples, but that will also be necessary.

ecoskey · 2024-08-28T05:26:31Z

I like the move to a single SyncRenderWorld component, and the possibility of using required components for this, especially now that that PR's been merged. It definitely simplifies the mental model and keeping track of what component actually marks an entity for syncing.

IMO there's still some things worth ironing out in a followup PR (like a removal/filter check in ExtractComponent), but I'm generally in approval now.

wilk10 · 2024-08-29T06:59:37Z

Coming from a user point of view, I have read the PR and superficially followed the discussion on Discord, but I don't know all the nitty gritty.

I think there's something missing in the documentation about entities that are not synchronized. Are all entities that are not synced (Without<SyncRenderWorld>) temporary entities? Or are there three groups: synced, temporary and neither synced nor temporary? I guess the confusion comes from the asymmetry between Sprites being synced and Camera2d not being synced, while 3D Meshes are not synced, but Camera3d is. It's a bit confusing why that is the case. And what about 2D Meshes?

re0312 · 2024-08-29T22:26:57Z

Are all entities that are not synced (Without<SyncRenderWorld>) temporary entities?

No , Temporary entities are merely part of entities in render world . previously, bevy's renderer spawns numerous temporary entities for rendering per frame , which need to be cleared at the end of each frame. IMO, it should be unnecessary once retain render world landed,
However, to minimize the impact of this PR, I have retained this concept and left it to future pr.

Or are there three groups: synced, temporary and neither synced nor temporary?

There are only two groups of entities : synced and unsynced , A synced entity X is one in the main world that has a corresponding ID Y in the render world( X !=Y ).
for a synced main world entity it corresponding render entity ID is stored in the component RenderEntity.

Camera2d not being synced

That's my bad ,Camera2D is synced but not mentioned in the pr description.

while 3D Meshes are not synced, but Camera3d is. It's a bit confusing why that is the case. And what about 2D Meshes?

this is because the current 3D and 2D Mesh instances in render world are all organized within an EntityHashmap, there are no corresponding render entities at all . so it is unnecessary to sync them.

wilk10 · 2024-08-30T06:25:07Z

crates/bevy_render/src/world_sync.rs

+/// |      |         |         Render wrold loop                         |
+/// |--------------------------------------------------------------------|
+/// ```
+///


Here we could cover the fact that not all entities that are extracted in the render world need to be kept in sync via SyncRenderWorld because they are handled differently (without entities) in the render world.

examples/3d/fog_volumes.rs

wilk10 · 2024-08-30T06:33:31Z

Thanks for the reply! It's all clear now. I left a comment about specifying it in the documentation as well.

Trashtalk217

I've checked the documentation. It could use some work, but it's getting there.

crates/bevy_render/src/world_sync.rs

Trashtalk217 · 2024-08-30T23:32:06Z

crates/bevy_render/src/world_sync.rs

+///
+/// Previously, `extract` will copy the related main world entity and its data into the render world , and then render world will clear all render entities at the end of frame to reserve enough entity space to ensure that no main world entity ID has been occupied during next `extract`.
+///
+/// With `* as entities`, we should not clear all entities in render world because some core metadata (e.g. [`Component`], [`Query`]) are also stored in the form of entity.


Documentation should describe something as-is, not as a before and after. That's what patch notes are for. These previous two lines can be removed.

crates/bevy_render/src/world_sync.rs

Trashtalk217 · 2024-08-30T23:37:18Z

crates/bevy_render/src/world_sync.rs

+///
+/// ```
+///
+/// To establish a "Synchronous Relationship", you can add a [`SyncRenderWorld`] component to an entity. Once a `synchronized` main entity is despawned ,its corresponding render entity will be automatically purged in the next `Sync`


Suggested change

/// To establish a "Synchronous Relationship", you can add a [`SyncRenderWorld`] component to an entity. Once a `synchronized` main entity is despawned ,its corresponding render entity will be automatically purged in the next `Sync`

/// To establish a "Synchronous Relationship", you can add a [`SyncRenderWorld`] component to an entity. Once a synchronized main entity is despawned, its corresponding render entity will be automatically purged in the next `Sync`

This should probably have some example code of how people can sync their own components using this plugin.

Co-authored-by: Trashtalk217 <trashtalk217@gmail.com> Co-authored-by: Anselmo Sampietro <ans.samp@gmail.com>

bushrat011899

I'm not familiar enough with the rendering side of Bevy to feel comfortable approving this PR, but it does look good to my novice eyes. I don't see anything that stands out as particularly wrong (that hasn't already been pointed in e.g. documentation).

I do have a suggestion around implementing WorldQuery on RenderEntity directly, which reduces the noise in this PR quite a bit and gives the rendering people some slightly nicer ergonomics. I've tested this implementation and it works as expected, allowing RenderEntity to be a drop-in replacement for Entity.

bushrat011899 · 2024-09-05T05:34:54Z

crates/bevy_core_pipeline/src/auto_exposure/buffers.rs

    mut removed: Extract<RemovedComponents<AutoExposureSettings>>,
 ) {
    commands.insert_resource(ExtractedStateBuffers {
        changed: changed
            .iter()
-            .map(|(entity, settings)| (entity, settings.clone()))
+            .map(|(entity, settings)| (entity.id(), settings.clone()))


There's quite a lot of noise in this PR due to the need to insert these RenderEntity::id calls. This might be a controversial suggestion, but we can implement WorldQuery for RenderEntity so it still behaves like a Component, but also returns the inner Entity when queried directly.

unsafe impl WorldQuery for RenderEntity { ... }

/// SAFETY: /// This implementation delegates to the existing implementation for &RenderEntity unsafe impl WorldQuery for RenderEntity { type Item<'w> = Entity; type Fetch<'w> = ReadFetch<'w, RenderEntity>; type State = ComponentId; fn shrink<'wlong: 'wshort, 'wshort>(item: Entity) -> Entity { item } fn shrink_fetch<'wlong: 'wshort, 'wshort>(fetch: Self::Fetch<'wlong>) -> Self::Fetch<'wshort> { <&Self as WorldQuery>::shrink_fetch(fetch) } #[inline] unsafe fn init_fetch<'w>( world: UnsafeWorldCell<'w>, component_id: &ComponentId, last_run: Tick, this_run: Tick, ) -> ReadFetch<'w, RenderEntity> { // SAFETY: This implementation delegates to the existing implementation for &RenderEntity unsafe { <&Self as WorldQuery>::init_fetch(world, component_id, last_run, this_run) } } const IS_DENSE: bool = <&Self as WorldQuery>::IS_DENSE; #[inline] unsafe fn set_archetype<'w>( fetch: &mut ReadFetch<'w, RenderEntity>, component_id: &ComponentId, archetype: &'w Archetype, table: &'w Table, ) { // SAFETY: This implementation delegates to the existing implementation for &RenderEntity unsafe { <&Self as WorldQuery>::set_archetype(fetch, component_id, archetype, table) } } #[inline] unsafe fn set_table<'w>( fetch: &mut ReadFetch<'w, RenderEntity>, component_id: &ComponentId, table: &'w Table, ) { // SAFETY: This implementation delegates to the existing implementation for &RenderEntity unsafe { <&Self as WorldQuery>::set_table(fetch, component_id, table) } } #[inline(always)] unsafe fn fetch<'w>( fetch: &mut Self::Fetch<'w>, entity: Entity, table_row: TableRow, ) -> Self::Item<'w> { // SAFETY: This implementation delegates to the existing implementation for &RenderEntity unsafe { <&Self as WorldQuery>::fetch(fetch, entity, table_row).id() } } fn update_component_access( component_id: &ComponentId, access: &mut FilteredAccess<ComponentId>, ) { <&Self as WorldQuery>::update_component_access(component_id, access) } fn init_state(world: &mut World) -> ComponentId { <&Self as WorldQuery>::init_state(world) } fn get_state(components: &Components) -> Option<Self::State> { <&Self as WorldQuery>::get_state(components) } fn matches_component_set( state: &ComponentId, set_contains_id: &impl Fn(ComponentId) -> bool, ) -> bool { <&Self as WorldQuery>::matches_component_set(state, set_contains_id) } } /// SAFETY: `Self` is the same as `Self::ReadOnly` unsafe impl QueryData for RenderEntity { type ReadOnly = Self; } /// SAFETY: access is read only unsafe impl ReadOnlyQueryData for RenderEntity {}

This would then allow for render systems to query for RenderEntity and directly receive the inner Entity, reducing the noise in this PR. Crucially, this doesn't conflict with the existing derive(Component), so you can still query for &RenderEntity, the mutable version, use it in filters, etc.

alice-i-cecile · 2024-09-05T12:20:53Z

I think I like the WorldQuery impl 🤔

Improve documentation

NthTensor

I would say this generally meets or exceeds my requirements for docs. Thanks for working on that.

I can't attest any of the code at this point, maybe i'll find time later for a review.

NthTensor · 2024-09-10T22:13:01Z

crates/bevy_render/src/world_sync.rs

+/// |      |         |          Main world loop                          |
+/// | sync | extract |---------------------------------------------------|
+/// |      |         |         Render world loop                         |
+//are/ |--------------------------------------------------------------------|


this looks like a typo

Suggested change

//are/ |--------------------------------------------------------------------|

/// |--------------------------------------------------------------------|

wilk10

LGTM! I mainly focused on the documentation and commented on a few tiny doc adjustments.
Thanks for previously including the part about assets not being synced, it's very clear now.

wilk10 · 2024-09-11T07:46:12Z

crates/bevy_render/src/world_sync.rs

+///
+/// ```
+///
+/// Note that not this effectively establishes a link between the main world entity and the render world entity.


Suggested change

/// Note that not this effectively establishes a link between the main world entity and the render world entity.

/// Note that this effectively establishes a link between the main world entity and the render world entity.

wilk10 · 2024-09-11T07:46:45Z

crates/bevy_render/src/world_sync.rs

+/// Note that not this effectively establishes a link between the main world entity and the render world entity.
+/// Not every entity needs to be synchronized, however, only entities with [`SyncRenderWorld`] are synced.
+/// Adding [`SyncRenderWorld`] to a main world component will establish such a link.
+/// Once a synchronized main entity is despawned, it's corresponding render entity will be automatically


Suggested change

/// Once a synchronized main entity is despawned, it's corresponding render entity will be automatically

/// Once a synchronized main entity is despawned, its corresponding render entity will be automatically

wilk10 · 2024-09-11T07:47:14Z

crates/bevy_render/src/world_sync.rs

+/// The sync step does not handle the transfer of component data between worlds,
+/// since it's often not necessary to transfer over all the components of a main world entity.
+/// The render world probably cares about a `Position` component, but not a `Velocity` component.
+/// The extraction happens in it's own step, independently from synchronization.


Suggested change

/// The extraction happens in it's own step, independently from synchronization.

/// The extraction happens in its own step, independently from synchronization.

JMS55

I left a bunch of comments, but awesome work overall! This is much clearer and more intuitive than the previous version, and I'm happy with how this looks and the level of docs.

WorldQuery impl would be nice, but we can leave it to a followup (open an issue please!).

My only major concern is needing SyncRenderWorld on intermediate spatial entities - this seems like a huge footgun. Not sure how to solve it...

I'd also vote in favor of renaming SyncRenderWorld to SyncWithRenderWorld or SyncToRenderWorld to be even more explicit, but I don't feel too strongly on it, the name is acceptable as-is.

JMS55 · 2024-09-12T04:07:55Z

crates/bevy_core_pipeline/src/core_2d/camera_2d.rs

@@ -37,6 +38,8 @@ pub struct Camera2dBundle {
    pub deband_dither: DebandDither,
    pub main_texture_usages: CameraMainTextureUsages,
    pub msaa: Msaa,
+    /// Marker component that indicates that its entity needs to be Synchronized to the render world


For here and all other comments, please do not capitalize "Synchronized" in the middle of the sentence.

JMS55 · 2024-09-12T04:09:59Z

crates/bevy_core_pipeline/src/taa/mod.rs


    for (entity, camera, camera_projection, mut taa_settings) in
        cameras_3d.iter_mut(&mut main_world)
    {
+        let entity = entity.id();


Tiny nit: entity is only used once here, I'd rather not create a new variable, and just use entity.id() directly in commands.get_or_spawn()

JMS55 · 2024-09-12T04:12:08Z

crates/bevy_core_pipeline/src/taa/mod.rs


    for (entity, camera, camera_projection, mut taa_settings) in
        cameras_3d.iter_mut(&mut main_world)
    {
+        let entity = entity.id();
        let has_perspective_projection = matches!(camera_projection, Projection::Perspective(_));
        if camera.is_active && has_perspective_projection {
            commands.get_or_spawn(entity).insert(taa_settings.clone());


Lets see if I understand this correctly: this could be just get_mut() here instead of get_or_spawn(), as the entity should already exist as camera bundles have SyncRenderWorld, correct?

(That said I do think we should leave it as get_or_spawn() in case users aren't using the bundle, this comment is just to see if I understand this PR correctly or not)

JMS55 · 2024-09-12T04:14:05Z

crates/bevy_pbr/src/cluster/mod.rs

-                data.push(ExtractedClusterableObjectElement::ClusterableObjectEntity(
-                    *clusterable_entity,
-                ));
+                if let Ok(entity) = mapper.get(*clusterable_entity) {


Shouldn't we modify the clusterizer system to store RenderEntity on Clusters directly, instead of using another query here?

JMS55 · 2024-09-12T04:14:29Z

crates/bevy_pbr/src/lib.rs

@@ -420,6 +420,9 @@ impl Plugin for PbrPlugin {
            )
            .init_resource::<LightMeta>();

+        render_app.world_mut().observe(add_light_view_entities);


What are these two lines doing here ?

JMS55 · 2024-09-12T04:48:13Z

crates/bevy_render/src/world_sync.rs

+                    if let Some(mut entity) = world.get_entity_mut(e) {
+                        match entity.entry::<RenderEntity>() {
+                            bevy_ecs::world::Entry::Occupied(_) => {
+                                warn!("Attempting to synchronize an entity that has already been synchronized!");


warn -> error? This should never happen, right?

JMS55 · 2024-09-12T04:48:40Z

crates/bevy_render/src/world_sync.rs

+}
+
+pub(crate) fn entity_sync_system(main_world: &mut World, render_world: &mut World) {
+    main_world.resource_scope(|world, mut pending: Mut<PendingSyncEntity>| {


This function could use some splitting up into closures or smaller functions to reduce the nesting 😬

JMS55 · 2024-09-12T04:49:05Z

crates/bevy_render/src/world_sync.rs

+                }
+                EntityRecord::Removed(e) => {
+                    if let Some(ec) = render_world.get_entity_mut(e) {
+                        ec.despawn_recursive();


Is recursive despawn what we want here?

JMS55 · 2024-09-12T04:49:35Z

crates/bevy_render/src/world_sync.rs

+
+    local.extend(query.iter());
+
+    // ensure next frame allocation keeps order


Suggested change

// ensure next frame allocation keeps order

// Ensure next frame allocation keeps order

Also, can you expand the comment a bit more? What does this mean, and why are we doing it?

JMS55 · 2024-09-12T04:51:11Z

crates/bevy_ui/src/render/mod.rs

I'm also going to pass on this file for now, but we'll need to review it at some point soon.

ecoskey · 2024-09-12T05:25:41Z

One last nit from me: while it doesn't affect any of the in-engine uses of ExtractComponentPlugin afaik, deletions of components in the main world won't propagate to their render world counterparts. I'd like to at least see a notice that ExtractComponentPlugin has this caveat, and recommend to only use it with transient entities or those whose components are not expected to be removed (aside from when the entity is despawned)

JMS55 · 2024-09-12T05:50:57Z

Something else I forgot to mention, I'd like to mention in the code somewhere that we have to make sure that RenderEntity IDs are consistent across frames, i.e. if entity A has render entity B in one frame, then that same mapping will exist in all subsequent frames. A test for it would be awesome as well if you feel up to it.

alice-i-cecile · 2024-09-12T12:30:29Z

SyncToRenderWorld gets my vote: extremely clear.

- Adopted from #14449 - Still fixes #12144. ## Migration Guide The retained render world is a complex change: migrating might take one of a few different forms depending on the patterns you're using. For every example, we specify in which world the code is run. Most of the changes affect render world code, so for the average Bevy user who's using Bevy's high-level rendering APIs, these changes are unlikely to affect your code. ### Spawning entities in the render world Previously, if you spawned an entity with `world.spawn(...)`, `commands.spawn(...)` or some other method in the rendering world, it would be despawned at the end of each frame. In 0.15, this is no longer the case and so your old code could leak entities. This can be mitigated by either re-architecting your code to no longer continuously spawn entities (like you're used to in the main world), or by adding the `bevy_render::world_sync::TemporaryRenderEntity` component to the entity you're spawning. Entities tagged with `TemporaryRenderEntity` will be removed at the end of each frame (like before). ### Extract components with `ExtractComponentPlugin` ``` // main world app.add_plugins(ExtractComponentPlugin::<ComponentToExtract>::default()); ``` `ExtractComponentPlugin` has been changed to only work with synced entities. Entities are automatically synced if `ComponentToExtract` is added to them. However, entities are not "unsynced" if any given `ComponentToExtract` is removed, because an entity may have multiple components to extract. This would cause the other components to no longer get extracted because the entity is not synced. So be careful when only removing extracted components from entities in the render world, because it might leave an entity behind in the render world. The solution here is to avoid only removing extracted components and instead despawn the entire entity. ### Manual extraction using `Extract<Query<(Entity, ...)>>` ```rust // in render world, inspired by bevy_pbr/src/cluster/mod.rs pub fn extract_clusters( mut commands: Commands, views: Extract<Query<(Entity, &Clusters, &Camera)>>, ) { for (entity, clusters, camera) in &views { // some code commands.get_or_spawn(entity).insert(...); } } ``` One of the primary consequences of the retained rendering world is that there's no longer a one-to-one mapping from entity IDs in the main world to entity IDs in the render world. Unlike in Bevy 0.14, Entity 42 in the main world doesn't necessarily map to entity 42 in the render world. Previous code which called `get_or_spawn(main_world_entity)` in the render world (`Extract<Query<(Entity, ...)>>` returns main world entities). Instead, you should use `&RenderEntity` and `render_entity.id()` to get the correct entity in the render world. Note that this entity does need to be synced first in order to have a `RenderEntity`. When performing manual abstraction, this won't happen automatically (like with `ExtractComponentPlugin`) so add a `SyncToRenderWorld` marker component to the entities you want to extract. This results in the following code: ```rust // in render world, inspired by bevy_pbr/src/cluster/mod.rs pub fn extract_clusters( mut commands: Commands, views: Extract<Query<(&RenderEntity, &Clusters, &Camera)>>, ) { for (render_entity, clusters, camera) in &views { // some code commands.get_or_spawn(render_entity.id()).insert(...); } } // in main world, when spawning world.spawn(Clusters::default(), Camera::default(), SyncToRenderWorld) ``` ### Looking up `Entity` ids in the render world As previously stated, there's now no correspondence between main world and render world `Entity` identifiers. Querying for `Entity` in the render world will return the `Entity` id in the render world: query for `MainEntity` (and use its `id()` method) to get the corresponding entity in the main world. This is also a good way to tell the difference between synced and unsynced entities in the render world, because unsynced entities won't have a `MainEntity` component. --------- Co-authored-by: re0312 <re0312@outlook.com> Co-authored-by: re0312 <45868716+re0312@users.noreply.github.com> Co-authored-by: Periwink <charlesbour@gmail.com> Co-authored-by: Anselmo Sampietro <ans.samp@gmail.com> Co-authored-by: Emerson Coskey <56370779+ecoskey@users.noreply.github.com> Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Christian Hughes <9044780+ItsDoot@users.noreply.github.com>

- Adopted from bevyengine#14449 - Still fixes bevyengine#12144. ## Migration Guide The retained render world is a complex change: migrating might take one of a few different forms depending on the patterns you're using. For every example, we specify in which world the code is run. Most of the changes affect render world code, so for the average Bevy user who's using Bevy's high-level rendering APIs, these changes are unlikely to affect your code. ### Spawning entities in the render world Previously, if you spawned an entity with `world.spawn(...)`, `commands.spawn(...)` or some other method in the rendering world, it would be despawned at the end of each frame. In 0.15, this is no longer the case and so your old code could leak entities. This can be mitigated by either re-architecting your code to no longer continuously spawn entities (like you're used to in the main world), or by adding the `bevy_render::world_sync::TemporaryRenderEntity` component to the entity you're spawning. Entities tagged with `TemporaryRenderEntity` will be removed at the end of each frame (like before). ### Extract components with `ExtractComponentPlugin` ``` // main world app.add_plugins(ExtractComponentPlugin::<ComponentToExtract>::default()); ``` `ExtractComponentPlugin` has been changed to only work with synced entities. Entities are automatically synced if `ComponentToExtract` is added to them. However, entities are not "unsynced" if any given `ComponentToExtract` is removed, because an entity may have multiple components to extract. This would cause the other components to no longer get extracted because the entity is not synced. So be careful when only removing extracted components from entities in the render world, because it might leave an entity behind in the render world. The solution here is to avoid only removing extracted components and instead despawn the entire entity. ### Manual extraction using `Extract<Query<(Entity, ...)>>` ```rust // in render world, inspired by bevy_pbr/src/cluster/mod.rs pub fn extract_clusters( mut commands: Commands, views: Extract<Query<(Entity, &Clusters, &Camera)>>, ) { for (entity, clusters, camera) in &views { // some code commands.get_or_spawn(entity).insert(...); } } ``` One of the primary consequences of the retained rendering world is that there's no longer a one-to-one mapping from entity IDs in the main world to entity IDs in the render world. Unlike in Bevy 0.14, Entity 42 in the main world doesn't necessarily map to entity 42 in the render world. Previous code which called `get_or_spawn(main_world_entity)` in the render world (`Extract<Query<(Entity, ...)>>` returns main world entities). Instead, you should use `&RenderEntity` and `render_entity.id()` to get the correct entity in the render world. Note that this entity does need to be synced first in order to have a `RenderEntity`. When performing manual abstraction, this won't happen automatically (like with `ExtractComponentPlugin`) so add a `SyncToRenderWorld` marker component to the entities you want to extract. This results in the following code: ```rust // in render world, inspired by bevy_pbr/src/cluster/mod.rs pub fn extract_clusters( mut commands: Commands, views: Extract<Query<(&RenderEntity, &Clusters, &Camera)>>, ) { for (render_entity, clusters, camera) in &views { // some code commands.get_or_spawn(render_entity.id()).insert(...); } } // in main world, when spawning world.spawn(Clusters::default(), Camera::default(), SyncToRenderWorld) ``` ### Looking up `Entity` ids in the render world As previously stated, there's now no correspondence between main world and render world `Entity` identifiers. Querying for `Entity` in the render world will return the `Entity` id in the render world: query for `MainEntity` (and use its `id()` method) to get the corresponding entity in the main world. This is also a good way to tell the difference between synced and unsynced entities in the render world, because unsynced entities won't have a `MainEntity` component. --------- Co-authored-by: re0312 <re0312@outlook.com> Co-authored-by: re0312 <45868716+re0312@users.noreply.github.com> Co-authored-by: Periwink <charlesbour@gmail.com> Co-authored-by: Anselmo Sampietro <ans.samp@gmail.com> Co-authored-by: Emerson Coskey <56370779+ecoskey@users.noreply.github.com> Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Christian Hughes <9044780+ItsDoot@users.noreply.github.com>

re0312 added 22 commits July 7, 2024 05:55

init

95b7f0b

sync

17f2bb0

cleanup

35fe01e

clean

f9bae87

fix

34853b2

Fly

000cef4

Merge branch 'main' into retain_world

2255b21

fly entity

f90c360

sync world

756b082

ui

5b5ef76

lighting

e15e3a3

fix example

e4e0bc0

ui

33cae8d

fix ui

4a58b0e

fix gizmos

3fc2207

fix light

f9c8d5a

cleanup

44d36a4

Merge branch 'main' into retain_world

9a7d641

fix cli

7989d21

fix ui

9485455

clean

bb3289b

fix cli

39e4f2e

re0312 added 2 commits July 23, 2024 19:29

fix ui_material

4b6506e

fix sprite

03a6e09

alice-i-cecile added this to the 0.15 milestone Jul 23, 2024

re0312 added 5 commits August 29, 2024 02:26

document and test

37944a8

fix

1e8601f

typo

7167cc0

cleanup

bfad1de

rename

8d2c81a

wilk10 reviewed Aug 30, 2024

View reviewed changes

examples/3d/fog_volumes.rs Outdated Show resolved Hide resolved

re0312 mentioned this pull request Aug 30, 2024

Split Main world and Render world Entity space #14988

Closed

Trashtalk217 reviewed Aug 30, 2024

View reviewed changes

re0312 and others added 2 commits September 1, 2024 03:40

Apply suggestions from code review

d857e6e

Co-authored-by: Trashtalk217 <trashtalk217@gmail.com> Co-authored-by: Anselmo Sampietro <ans.samp@gmail.com>

Cleared up some documentation

9c1a523

bushrat011899 reviewed Sep 5, 2024

View reviewed changes

Merge pull request #1 from Trashtalk217/retain_world

753d286

Improve documentation

NthTensor reviewed Sep 10, 2024

View reviewed changes

wilk10 approved these changes Sep 11, 2024

View reviewed changes

JMS55 suggested changes Sep 12, 2024

View reviewed changes

Trashtalk217 mentioned this pull request Sep 19, 2024

Retain Rendering World (adopted) #15320

Merged

JMS55 closed this Sep 27, 2024

	/// To establish a "Synchronous Relationship", you can add a [`SyncRenderWorld`] component to an entity. Once a `synchronized` main entity is despawned ,its corresponding render entity will be automatically purged in the next `Sync`
	/// To establish a "Synchronous Relationship", you can add a [`SyncRenderWorld`] component to an entity. Once a synchronized main entity is despawned, its corresponding render entity will be automatically purged in the next `Sync`

	//are/ \|--------------------------------------------------------------------\|
	/// \|--------------------------------------------------------------------\|

	/// Note that not this effectively establishes a link between the main world entity and the render world entity.
	/// Note that this effectively establishes a link between the main world entity and the render world entity.

	/// Once a synchronized main entity is despawned, it's corresponding render entity will be automatically
	/// Once a synchronized main entity is despawned, its corresponding render entity will be automatically

	/// The extraction happens in it's own step, independently from synchronization.
	/// The extraction happens in its own step, independently from synchronization.


		local.extend(query.iter());

		// ensure next frame allocation keeps order

Retain Rendering World #14449

Retain Rendering World #14449

Conversation

re0312 commented Jul 23, 2024 • edited Loading

Objective

Solution

Alternative(s)

Advantages

Drawbacks

Performance

Next Steps

Migration Guide

re0312 commented Jul 23, 2024

NthTensor commented Aug 27, 2024

JMS55 commented Aug 28, 2024

ecoskey commented Aug 28, 2024

wilk10 commented Aug 29, 2024

re0312 commented Aug 29, 2024

Choose a reason for hiding this comment

wilk10 commented Aug 30, 2024

Trashtalk217 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bushrat011899 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alice-i-cecile commented Sep 5, 2024

NthTensor left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wilk10 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JMS55 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JMS55 Sep 12, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ecoskey commented Sep 12, 2024

JMS55 commented Sep 12, 2024

alice-i-cecile commented Sep 12, 2024

re0312 commented Jul 23, 2024 •

edited

Loading

NthTensor left a comment •

edited

Loading

JMS55 Sep 12, 2024 •

edited

Loading