Synchronize removed components with the render world (#15582)

# Objective

Fixes #15560
Fixes (most of) #15570

Currently a lot of examples (and presumably some user code) depend on
toggling certain render features by adding/removing a single component
to an entity, e.g. `SpotLight` to toggle a light. Because of the
retained render world this no longer works: Extract will add any new
components, but when it is removed the entity persists unchanged in the
render world.

## Solution

Add `SyncComponentPlugin<C: Component>` that registers
`SyncToRenderWorld` as a required component for `C`, and adds a
component hook that will clear all components from the render world
entity when `C` is removed. We add this plugin to
`ExtractComponentPlugin` which fixes most instances of the problem. For
custom extraction logic we can manually add `SyncComponentPlugin` for
that component.

We also rename `WorldSyncPlugin` to `SyncWorldPlugin` so we start a
naming convention like all the `Extract` plugins.

In this PR I also fixed a bunch of breakage related to the retained
render world, stemming from old code that assumed that `Entity` would be
the same in both worlds.

I found that using the `RenderEntity` wrapper instead of `Entity` in
data structures when referring to render world entities makes intent
much clearer, so I propose we make this an official pattern.

## Testing

Run examples like

```
cargo run --features pbr_multi_layer_material_textures --example clearcoat
cargo run --example volumetric_fog
```

and see that they work, and that toggles work correctly. But really we
should test every single example, as we might not even have caught all
the breakage yet.

---

## Migration Guide

The retained render world notes should be updated to explain this edge
case and `SyncComponentPlugin`

---------

Co-authored-by: Alice Cecile <[email protected]>
Co-authored-by: Trashtalk217 <[email protected]>

Author: 3 people

crates/bevy_core_pipeline/src/auto_exposure/buffers.rs

@@ -2,7 +2,7 @@ use bevy_ecs::prelude::*;
 use bevy_render::{
     render_resource::{StorageBuffer, UniformBuffer},
     renderer::{RenderDevice, RenderQueue},
-    world_sync::RenderEntity,
+    sync_world::RenderEntity,
     Extract,
 };
 use bevy_utils::{Entry, HashMap};

crates/bevy_core_pipeline/src/core_2d/camera_2d.rs

@@ -6,7 +6,7 @@ use crate::{
 };
 use bevy_ecs::prelude::*;
 use bevy_reflect::{std_traits::ReflectDefault, Reflect};
-use bevy_render::world_sync::SyncToRenderWorld;
+use bevy_render::sync_world::SyncToRenderWorld;
 use bevy_render::{
     camera::{
         Camera, CameraMainTextureUsages, CameraProjection, CameraRenderGraph,

crates/bevy_core_pipeline/src/core_2d/mod.rs

@@ -55,9 +55,9 @@ use bevy_render::{
         TextureFormat, TextureUsages,
     },
     renderer::RenderDevice,
+    sync_world::RenderEntity,
     texture::TextureCache,
     view::{Msaa, ViewDepthTexture},
-    world_sync::RenderEntity,
     Extract, ExtractSchedule, Render, RenderApp, RenderSet,
 };
 

crates/bevy_core_pipeline/src/core_3d/camera_3d.rs

@@ -11,8 +11,8 @@ use bevy_render::{
     extract_component::ExtractComponent,
     primitives::Frustum,
     render_resource::{LoadOp, TextureUsages},
+    sync_world::SyncToRenderWorld,
     view::{ColorGrading, Msaa, VisibleEntities},
-    world_sync::SyncToRenderWorld,
 };
 use bevy_transform::prelude::{GlobalTransform, Transform};
 use serde::{Deserialize, Serialize};

crates/bevy_core_pipeline/src/core_3d/mod.rs

@@ -89,9 +89,9 @@ use bevy_render::{
         Texture, TextureDescriptor, TextureDimension, TextureFormat, TextureUsages, TextureView,
     },
     renderer::RenderDevice,
+    sync_world::RenderEntity,
     texture::{BevyDefault, ColorAttachment, Image, TextureCache},
     view::{ExtractedView, ViewDepthTexture, ViewTarget},
-    world_sync::RenderEntity,
     Extract, ExtractSchedule, Render, RenderApp, RenderSet,
 };
 use bevy_utils::{tracing::warn, HashMap};

crates/bevy_core_pipeline/src/dof/mod.rs

@@ -46,12 +46,12 @@ use bevy_render::{
         TextureDescriptor, TextureDimension, TextureFormat, TextureSampleType, TextureUsages,
     },
     renderer::{RenderContext, RenderDevice},
+    sync_world::RenderEntity,
     texture::{BevyDefault, CachedTexture, TextureCache},
     view::{
         prepare_view_targets, ExtractedView, Msaa, ViewDepthTexture, ViewTarget, ViewUniform,
         ViewUniformOffset, ViewUniforms,
     },
-    world_sync::RenderEntity,
     Extract, ExtractSchedule, Render, RenderApp, RenderSet,
 };
 use bevy_utils::{info_once, prelude::default, warn_once};

crates/bevy_core_pipeline/src/taa/mod.rs

@@ -32,9 +32,9 @@ use bevy_render::{
         TextureDimension, TextureFormat, TextureSampleType, TextureUsages,
     },
     renderer::{RenderContext, RenderDevice},
+    sync_world::RenderEntity,
     texture::{BevyDefault, CachedTexture, TextureCache},
     view::{ExtractedView, Msaa, ViewTarget},
-    world_sync::RenderEntity,
     ExtractSchedule, MainWorld, Render, RenderApp, RenderSet,
 };
 use bevy_utils::tracing::warn;

crates/bevy_gizmos/src/lib.rs

@@ -105,7 +105,7 @@ use {
             ShaderStages, ShaderType, VertexFormat,
         },
         renderer::RenderDevice,
-        world_sync::TemporaryRenderEntity,
+        sync_world::TemporaryRenderEntity,
         Extract, ExtractSchedule, Render, RenderApp, RenderSet,
     },
     bytemuck::cast_slice,

crates/bevy_pbr/src/bundle.rs

@@ -15,8 +15,8 @@ use bevy_reflect::{std_traits::ReflectDefault, Reflect};
 use bevy_render::{
     mesh::Mesh3d,
     primitives::{CascadesFrusta, CubemapFrusta, Frustum},
+    sync_world::SyncToRenderWorld,
     view::{InheritedVisibility, ViewVisibility, Visibility},
-    world_sync::SyncToRenderWorld,
 };
 use bevy_transform::components::{GlobalTransform, Transform};
 

crates/bevy_pbr/src/cluster/mod.rs

@@ -20,7 +20,7 @@ use bevy_render::{
         UniformBuffer,
     },
     renderer::{RenderDevice, RenderQueue},
-    world_sync::RenderEntity,
+    sync_world::RenderEntity,
     Extract,
 };
 use bevy_utils::{hashbrown::HashSet, tracing::warn};

crates/bevy_pbr/src/lib.rs

@@ -127,6 +127,7 @@ use bevy_render::{
     render_asset::prepare_assets,
     render_graph::RenderGraph,
     render_resource::Shader,
+    sync_component::SyncComponentPlugin,
     texture::{GpuImage, Image},
     view::{check_visibility, VisibilitySystems},
     ExtractSchedule, Render, RenderApp, RenderSet,
@@ -314,7 +315,6 @@ impl Plugin for PbrPlugin {
             .register_type::<PointLight>()
             .register_type::<PointLightShadowMap>()
             .register_type::<SpotLight>()
-            .register_type::<DistanceFog>()
             .register_type::<ShadowFilteringMethod>()
             .init_resource::<AmbientLight>()
             .init_resource::<GlobalVisibleClusterableObjects>()
@@ -346,6 +346,11 @@ impl Plugin for PbrPlugin {
                 VolumetricFogPlugin,
                 ScreenSpaceReflectionsPlugin,
             ))
+            .add_plugins((
+                SyncComponentPlugin::<DirectionalLight>::default(),
+                SyncComponentPlugin::<PointLight>::default(),
+                SyncComponentPlugin::<SpotLight>::default(),
+            ))
             .configure_sets(
                 PostUpdate,
                 (

crates/bevy_pbr/src/light/directional_light.rs

@@ -1,4 +1,4 @@
-use bevy_render::{view::Visibility, world_sync::SyncToRenderWorld};
+use bevy_render::view::Visibility;
 
 use super::*;
 
@@ -57,8 +57,7 @@ use super::*;
     CascadeShadowConfig,
     CascadesVisibleEntities,
     Transform,
-    Visibility,
-    SyncToRenderWorld
+    Visibility
 )]
 pub struct DirectionalLight {
     /// The color of the light.

crates/bevy_pbr/src/light/point_light.rs

@@ -1,4 +1,4 @@
-use bevy_render::{view::Visibility, world_sync::SyncToRenderWorld};
+use bevy_render::view::Visibility;
 
 use super::*;
 
@@ -21,13 +21,7 @@ use super::*;
 /// Source: [Wikipedia](https://en.wikipedia.org/wiki/Lumen_(unit)#Lighting)
 #[derive(Component, Debug, Clone, Copy, Reflect)]
 #[reflect(Component, Default, Debug)]
-#[require(
-    CubemapFrusta,
-    CubemapVisibleEntities,
-    Transform,
-    Visibility,
-    SyncToRenderWorld
-)]
+#[require(CubemapFrusta, CubemapVisibleEntities, Transform, Visibility)]
 pub struct PointLight {
     /// The color of this light source.
     pub color: Color,

crates/bevy_pbr/src/light/spot_light.rs

@@ -1,4 +1,4 @@
-use bevy_render::{view::Visibility, world_sync::SyncToRenderWorld};
+use bevy_render::view::Visibility;
 
 use super::*;
 
@@ -9,7 +9,7 @@ use super::*;
 /// the transform, and can be specified with [`Transform::looking_at`](Transform::looking_at).
 #[derive(Component, Debug, Clone, Copy, Reflect)]
 #[reflect(Component, Default, Debug)]
-#[require(Frustum, VisibleMeshEntities, Transform, Visibility, SyncToRenderWorld)]
+#[require(Frustum, VisibleMeshEntities, Transform, Visibility)]
 pub struct SpotLight {
     /// The color of the light.
     ///

crates/bevy_pbr/src/light_probe/mod.rs

@@ -21,9 +21,9 @@ use bevy_render::{
     render_resource::{DynamicUniformBuffer, Sampler, Shader, ShaderType, TextureView},
     renderer::{RenderDevice, RenderQueue},
     settings::WgpuFeatures,
+    sync_world::RenderEntity,
     texture::{FallbackImage, GpuImage, Image},
     view::ExtractedView,
-    world_sync::RenderEntity,
     Extract, ExtractSchedule, Render, RenderApp, RenderSet,
 };
 use bevy_transform::{components::Transform, prelude::GlobalTransform};

crates/bevy_pbr/src/prepass/mod.rs

@@ -3,7 +3,7 @@ mod prepass_bindings;
 use bevy_render::{
     mesh::{Mesh3d, MeshVertexBufferLayoutRef, RenderMesh},
     render_resource::binding_types::uniform_buffer,
-    world_sync::RenderEntity,
+    sync_world::RenderEntity,
 };
 pub use prepass_bindings::*;
 

crates/bevy_pbr/src/render/light.rs

@@ -8,7 +8,7 @@ use bevy_ecs::{
     system::lifetimeless::Read,
 };
 use bevy_math::{ops, Mat4, UVec4, Vec2, Vec3, Vec3Swizzles, Vec4, Vec4Swizzles};
-use bevy_render::world_sync::RenderEntity;
+use bevy_render::sync_world::RenderEntity;
 use bevy_render::{
     diagnostic::RecordDiagnostics,
     mesh::RenderMesh,

crates/bevy_pbr/src/ssao/mod.rs

@@ -30,9 +30,9 @@ use bevy_render::{
         *,
     },
     renderer::{RenderAdapter, RenderContext, RenderDevice, RenderQueue},
+    sync_world::RenderEntity,
     texture::{CachedTexture, TextureCache},
     view::{Msaa, ViewUniform, ViewUniformOffset, ViewUniforms},
-    world_sync::RenderEntity,
     Extract, ExtractSchedule, Render, RenderApp, RenderSet,
 };
 use bevy_utils::{

crates/bevy_pbr/src/volumetric_fog/mod.rs

@@ -51,6 +51,7 @@ use bevy_render::{
     mesh::{Mesh, Meshable},
     render_graph::{RenderGraphApp, ViewNodeRunner},
     render_resource::{Shader, SpecializedRenderPipelines},
+    sync_component::SyncComponentPlugin,
     texture::Image,
     view::{InheritedVisibility, ViewVisibility, Visibility},
     ExtractSchedule, Render, RenderApp, RenderSet,
@@ -231,6 +232,8 @@ impl Plugin for VolumetricFogPlugin {
         app.register_type::<VolumetricFog>()
             .register_type::<VolumetricLight>();
 
+        app.add_plugins(SyncComponentPlugin::<FogVolume>::default());
+
         let Some(render_app) = app.get_sub_app_mut(RenderApp) else {
             return;
         };

crates/bevy_pbr/src/volumetric_fog/render.rs

@@ -36,9 +36,9 @@ use bevy_render::{
         TextureSampleType, TextureUsages, VertexState,
     },
     renderer::{RenderContext, RenderDevice, RenderQueue},
+    sync_world::RenderEntity,
     texture::{BevyDefault as _, GpuImage, Image},
     view::{ExtractedView, Msaa, ViewDepthTexture, ViewTarget, ViewUniformOffset},
-    world_sync::RenderEntity,
     Extract,
 };
 use bevy_transform::components::GlobalTransform;

crates/bevy_render/src/camera/camera.rs

@@ -6,12 +6,12 @@ use crate::{
     render_asset::RenderAssets,
     render_graph::{InternedRenderSubGraph, RenderSubGraph},
     render_resource::TextureView,
+    sync_world::{RenderEntity, SyncToRenderWorld},
     texture::GpuImage,
     view::{
         ColorGrading, ExtractedView, ExtractedWindows, GpuCulling, Msaa, RenderLayers, Visibility,
         VisibleEntities,
     },
-    world_sync::{RenderEntity, SyncToRenderWorld},
     Extract,
 };
 use bevy_asset::{AssetEvent, AssetId, Assets, Handle};

crates/bevy_render/src/extract_component.rs

@@ -1,8 +1,9 @@
 use crate::{
     render_resource::{encase::internal::WriteInto, DynamicUniformBuffer, ShaderType},
     renderer::{RenderDevice, RenderQueue},
+    sync_component::SyncComponentPlugin,
+    sync_world::RenderEntity,
     view::ViewVisibility,
-    world_sync::{RenderEntity, SyncToRenderWorld},
     Extract, ExtractSchedule, Render, RenderApp, RenderSet,
 };
 use bevy_app::{App, Plugin};
@@ -12,7 +13,6 @@ use bevy_ecs::{
     prelude::*,
     query::{QueryFilter, QueryItem, ReadOnlyQueryData},
     system::lifetimeless::Read,
-    world::OnAdd,
 };
 use core::{marker::PhantomData, ops::Deref};
 
@@ -160,15 +160,6 @@ fn prepare_uniform_components<C>(
 /// This plugin extracts the components into the render world for synced entities.
 ///
 /// To do so, it sets up the [`ExtractSchedule`] step for the specified [`ExtractComponent`].
-///
-/// # Warning
-///
-/// Be careful when removing the [`ExtractComponent`] from an entity. When an [`ExtractComponent`]
-/// is added to an entity, that entity is automatically synced with the render world (see also
-/// [`WorldSyncPlugin`](crate::world_sync::WorldSyncPlugin)). When removing the entity in the main
-/// world, the synced entity also gets removed. However, if only the [`ExtractComponent`] is removed
-/// this *doesn't* happen, and the synced entity stays around with the old extracted data.
-/// We recommend despawning the entire entity, instead of only removing [`ExtractComponent`].
 pub struct ExtractComponentPlugin<C, F = ()> {
     only_extract_visible: bool,
     marker: PhantomData<fn() -> (C, F)>,
@@ -194,10 +185,8 @@ impl<C, F> ExtractComponentPlugin<C, F> {
 
 impl<C: ExtractComponent> Plugin for ExtractComponentPlugin<C> {
     fn build(&self, app: &mut App) {
-        // TODO: use required components
-        app.observe(|trigger: Trigger<OnAdd, C>, mut commands: Commands| {
-            commands.entity(trigger.entity()).insert(SyncToRenderWorld);
-        });
+        app.add_plugins(SyncComponentPlugin::<C>::default());
+
         if let Some(render_app) = app.get_sub_app_mut(RenderApp) {
             if self.only_extract_visible {
                 render_app.add_systems(ExtractSchedule, extract_visible_components::<C>);
@@ -219,7 +208,7 @@ impl<T: Asset> ExtractComponent for Handle<T> {
     }
 }
 
-/// This system extracts all components of the corresponding [`ExtractComponent`], for entities that are synced via [`SyncToRenderWorld`].
+/// This system extracts all components of the corresponding [`ExtractComponent`], for entities that are synced via [`crate::sync_world::SyncToRenderWorld`].
 fn extract_components<C: ExtractComponent>(
     mut commands: Commands,
     mut previous_len: Local<usize>,
@@ -235,7 +224,7 @@ fn extract_components<C: ExtractComponent>(
     commands.insert_or_spawn_batch(values);
 }
 
-/// This system extracts all components of the corresponding [`ExtractComponent`], for entities that are visible and synced via [`SyncToRenderWorld`].
+/// This system extracts all components of the corresponding [`ExtractComponent`], for entities that are visible and synced via [`crate::sync_world::SyncToRenderWorld`].
 fn extract_visible_components<C: ExtractComponent>(
     mut commands: Commands,
     mut previous_len: Local<usize>,

crates/bevy_render/src/extract_param.rs

@@ -30,7 +30,7 @@ use core::ops::{Deref, DerefMut};
 /// ```
 /// use bevy_ecs::prelude::*;
 /// use bevy_render::Extract;
-/// use bevy_render::world_sync::RenderEntity;
+/// use bevy_render::sync_world::RenderEntity;
 /// # #[derive(Component)]
 /// // Do make sure to sync the cloud entities before extracting them.
 /// # struct Cloud;

crates/bevy_render/src/gpu_readback.rs

@@ -5,6 +5,7 @@ use crate::{
     render_resource::{Buffer, BufferUsages, Extent3d, ImageDataLayout, Texture, TextureFormat},
     renderer::{render_system, RenderDevice},
     storage::{GpuShaderStorageBuffer, ShaderStorageBuffer},
+    sync_world::MainEntity,
     texture::{GpuImage, TextureFormatPixelInfo},
     ExtractSchedule, MainWorld, Render, RenderApp, RenderSet,
 };
@@ -232,7 +233,7 @@ fn prepare_buffers(
     mut buffer_pool: ResMut<GpuReadbackBufferPool>,
     gpu_images: Res<RenderAssets<GpuImage>>,
     ssbos: Res<RenderAssets<GpuShaderStorageBuffer>>,
-    handles: Query<(Entity, &Readback)>,
+    handles: Query<(&MainEntity, &Readback)>,
 ) {
     for (entity, readback) in handles.iter() {
         match readback {
@@ -254,7 +255,7 @@ fn prepare_buffers(
                     );
                     let (tx, rx) = async_channel::bounded(1);
                     readbacks.requested.push(GpuReadback {
-                        entity,
+                        entity: entity.id(),
                         src: ReadbackSource::Texture {
                             texture: gpu_image.texture.clone(),
                             layout,
@@ -272,7 +273,7 @@ fn prepare_buffers(
                     let buffer = buffer_pool.get(&render_device, size);
                     let (tx, rx) = async_channel::bounded(1);
                     readbacks.requested.push(GpuReadback {
-                        entity,
+                        entity: entity.id(),
                         src: ReadbackSource::Buffer {
                             src_start: 0,
                             dst_start: 0,