Re-introduce "Replace Ambient Lights with Environment Map Lights (#17482)"

crates/bevy_light/Cargo.toml

@@ -27,6 +27,7 @@ bevy_color = { path = "../bevy_color", version = "0.17.0-dev", features = [
 
 # other
 tracing = { version = "0.1", default-features = false }
+wgpu-types = { version = "26", default-features = false }
 
 [features]
 default = []

crates/bevy_light/src/ambient_light.rs

@@ -1,3 +1,8 @@
+#![deprecated(
+    since = "0.17.0",
+    note = "Use `EnvironmentMapLight::solid_color` instead"
+)]
+
 use bevy_camera::Camera;
 use bevy_color::Color;
 use bevy_ecs::prelude::*;
@@ -48,7 +53,7 @@ impl Default for AmbientLight {
     fn default() -> Self {
         Self {
             color: Color::WHITE,
-            brightness: 80.0,
+            brightness: 50.0,
             affects_lightmapped_meshes: true,
         }
     }

crates/bevy_light/src/lib.rs

@@ -1,16 +1,19 @@
 #![expect(missing_docs, reason = "Not all docs are written yet, see #3492.")]
 
 use bevy_app::{App, Plugin, PostUpdate};
+use bevy_asset::Assets;
 use bevy_camera::{
     primitives::{Aabb, CascadesFrusta, CubemapFrusta, Frustum, Sphere},
     visibility::{
         CascadesVisibleEntities, CubemapVisibleEntities, InheritedVisibility, NoFrustumCulling,
         PreviousVisibleEntities, RenderLayers, ViewVisibility, VisibilityRange, VisibilitySystems,
         VisibleEntityRanges, VisibleMeshEntities,
     },
-    CameraUpdateSystems,
+    Camera3d, CameraUpdateSystems,
 };
+use bevy_color::Color;
 use bevy_ecs::{entity::EntityHashSet, prelude::*};
+use bevy_image::Image;
 use bevy_math::Vec3A;
 use bevy_mesh::Mesh3d;
 use bevy_reflect::prelude::*;
@@ -25,6 +28,10 @@ use cluster::{
     GlobalVisibleClusterableObjects, VisibleClusterableObjects,
 };
 mod ambient_light;
+#[expect(
+    deprecated,
+    reason = "AmbientLight has been replaced by EnvironmentMapLight"
+)]
 pub use ambient_light::AmbientLight;
 mod probe;
 pub use probe::{EnvironmentMapLight, GeneratedEnvironmentMapLight, IrradianceVolume, LightProbe};
@@ -48,7 +55,8 @@ pub use directional_light::{
     DirectionalLightTexture,
 };
 
-use crate::directional_light::validate_shadow_map_size;
+use directional_light::validate_shadow_map_size;
+use probe::DEFAULT_ENVIRONMENT_MAP_TEXTURE_HANDLE;
 
 /// Constants for operating with the light units: lumens, and lux.
 pub mod light_consts {
@@ -113,10 +121,25 @@ pub mod light_consts {
     }
 }
 
-pub struct LightPlugin;
+pub struct LightPlugin {
+    /// Controls if the default environment map light is added to every [`Camera3d`].
+    pub default_environment_map_light: bool,
+}
+
+impl Default for LightPlugin {
+    fn default() -> Self {
+        Self {
+            default_environment_map_light: true,
+        }
+    }
+}
 
 impl Plugin for LightPlugin {
     fn build(&self, app: &mut App) {
+        #[expect(
+            deprecated,
+            reason = "AmbientLight has been replaced by EnvironmentMapLight"
+        )]
         app.register_type::<AmbientLight>()
             .register_type::<CascadeShadowConfig>()
             .register_type::<Cascades>()
@@ -135,7 +158,6 @@ impl Plugin for LightPlugin {
             .register_type::<ShadowFilteringMethod>()
             .register_type::<ClusterConfig>()
             .init_resource::<GlobalVisibleClusterableObjects>()
-            .init_resource::<AmbientLight>()
             .init_resource::<DirectionalLightShadowMap>()
             .init_resource::<PointLightShadowMap>()
             .configure_sets(
@@ -151,6 +173,9 @@ impl Plugin for LightPlugin {
             .add_systems(
                 PostUpdate,
                 (
+                    map_ambient_lights
+                        .in_set(SimulationLightSystems::MapAmbientLights)
+                        .after(CameraUpdateSystems),
                     validate_shadow_map_size.before(build_directional_light_cascades),
                     add_clusters
                         .in_set(SimulationLightSystems::AddClusters)
@@ -200,6 +225,25 @@ impl Plugin for LightPlugin {
                         .after(clear_directional_light_cascades),
                 ),
             );
+
+        if self.default_environment_map_light {
+            app.world_mut()
+                .register_required_components_with::<Camera3d, EnvironmentMapLight>(|| {
+                    EnvironmentMapLight {
+                        intensity: 50.0,
+                        ..Default::default()
+                    }
+                });
+        }
+
+        app.world_mut().resource_mut::<Assets<Image>>().insert(
+            &DEFAULT_ENVIRONMENT_MAP_TEXTURE_HANDLE,
+            EnvironmentMapLight::hemispherical_gradient_cubemap(
+                Color::WHITE,
+                Color::WHITE,
+                Color::WHITE,
+            ),
+        );
     }
 }
 
@@ -230,7 +274,7 @@ pub struct NotShadowReceiver;
 #[reflect(Component, Default, Debug)]
 pub struct TransmittedShadowReceiver;
 
-/// Add this component to a [`Camera3d`](bevy_camera::Camera3d)
+/// Add this component to a [`Camera3d`]
 /// to control how to anti-alias shadow edges.
 ///
 /// The different modes use different approaches to
@@ -269,6 +313,7 @@ pub enum ShadowFilteringMethod {
 /// System sets used to run light-related systems.
 #[derive(Debug, Hash, PartialEq, Eq, Clone, SystemSet)]
 pub enum SimulationLightSystems {
+    MapAmbientLights,
     AddClusters,
     AssignLightsToClusters,
     /// System order ambiguities between systems in this set are ignored:
@@ -282,6 +327,63 @@ pub enum SimulationLightSystems {
     CheckLightVisibility,
 }
 
+#[derive(Component)]
+pub struct EnvironmentMapLightFromAmbientLight;
+
+#[expect(
+    deprecated,
+    reason = "AmbientLight has been replaced by EnvironmentMapLight"
+)]
+pub fn map_ambient_lights(
+    mut commands: Commands,
+    mut image_assets: ResMut<Assets<Image>>,
+    ambient_light: Option<Res<AmbientLight>>,
+    new_views: Query<
+        (Entity, Option<Ref<AmbientLight>>),
+        (
+            With<Camera3d>,
+            Without<EnvironmentMapLight>,
+            Without<EnvironmentMapLightFromAmbientLight>,
+        ),
+    >,
+    mut managed_views: Query<
+        (&mut EnvironmentMapLight, Option<Ref<AmbientLight>>),
+        With<EnvironmentMapLightFromAmbientLight>,
+    >,
+) {
+    let ambient_light = ambient_light.map(Into::into);
+    let ref_ambient_light = ambient_light.as_ref();
+    for (entity, ambient_override) in new_views.iter() {
+        let Some(ambient) = ambient_override.as_ref().or(ref_ambient_light) else {
+            continue;
+        };
+        let ambient_required = ambient.brightness > 0.0 && ambient.color != Color::BLACK;
+        if ambient_required && ambient.is_changed() {
+            commands
+                .entity(entity)
+                .insert(EnvironmentMapLight {
+                    intensity: ambient.brightness,
+                    affects_lightmapped_mesh_diffuse: ambient.affects_lightmapped_meshes,
+                    ..EnvironmentMapLight::solid_color(image_assets.as_mut(), ambient.color)
+                })
+                .insert(EnvironmentMapLightFromAmbientLight);
+        }
+    }
+    for (mut env_map, ambient_override) in managed_views.iter_mut() {
+        let Some(ambient) = ambient_override.as_ref().or(ref_ambient_light) else {
+            continue;
+        };
+        let ambient_required = ambient.brightness > 0.0 && ambient.color != Color::BLACK;
+        if ambient_required && ambient.is_changed() {
+            *env_map = EnvironmentMapLight {
+                intensity: ambient.brightness,
+                affects_lightmapped_mesh_diffuse: ambient.affects_lightmapped_meshes,
+                ..EnvironmentMapLight::solid_color(image_assets.as_mut(), ambient.color)
+            };
+        }
+    }
+}
+
 fn shrink_entities(visible_entities: &mut Vec<Entity>) {
     // Check that visible entities capacity() is no more than two times greater than len()
     let capacity = visible_entities.capacity();

crates/bevy_light/src/probe.rs

@@ -1,10 +1,14 @@
-use bevy_asset::Handle;
+use bevy_asset::{uuid_handle, Assets, Handle, RenderAssetUsages};
 use bevy_camera::visibility::Visibility;
+use bevy_color::{Color, ColorToPacked, Srgba};
 use bevy_ecs::prelude::*;
 use bevy_image::Image;
 use bevy_math::Quat;
 use bevy_reflect::prelude::*;
 use bevy_transform::components::Transform;
+use wgpu_types::{
+    Extent3d, TextureDimension, TextureFormat, TextureViewDescriptor, TextureViewDimension,
+};
 
 /// A marker component for a light probe, which is a cuboid region that provides
 /// global illumination to all fragments inside it.
@@ -96,14 +100,82 @@ pub struct EnvironmentMapLight {
     pub affects_lightmapped_mesh_diffuse: bool,
 }
 
+impl EnvironmentMapLight {
+    /// An environment map with a uniform color, useful for uniform ambient lighting.
+    pub fn solid_color(assets: &mut Assets<Image>, color: Color) -> Self {
+        Self::hemispherical_gradient(assets, color, color, color)
+    }
+
+    /// An environment map with a hemispherical gradient, fading between the sky and ground colors
+    /// at the horizon. Useful as a very simple 'sky'.
+    pub fn hemispherical_gradient(
+        assets: &mut Assets<Image>,
+        top_color: Color,
+        mid_color: Color,
+        bottom_color: Color,
+    ) -> Self {
+        let handle = assets.add(Self::hemispherical_gradient_cubemap(
+            top_color,
+            mid_color,
+            bottom_color,
+        ));
+
+        Self {
+            diffuse_map: handle.clone(),
+            specular_map: handle,
+            ..Default::default()
+        }
+    }
+
+    pub(crate) fn hemispherical_gradient_cubemap(
+        top_color: Color,
+        mid_color: Color,
+        bottom_color: Color,
+    ) -> Image {
+        let top_color: Srgba = top_color.into();
+        let mid_color: Srgba = mid_color.into();
+        let bottom_color: Srgba = bottom_color.into();
+        Image {
+            texture_view_descriptor: Some(TextureViewDescriptor {
+                dimension: Some(TextureViewDimension::Cube),
+                ..Default::default()
+            }),
+            ..Image::new(
+                Extent3d {
+                    width: 1,
+                    height: 1,
+                    depth_or_array_layers: 6,
+                },
+                TextureDimension::D2,
+                [
+                    mid_color,
+                    mid_color,
+                    top_color,
+                    bottom_color,
+                    mid_color,
+                    mid_color,
+                ]
+                .into_iter()
+                .flat_map(Srgba::to_u8_array)
+                .collect(),
+                TextureFormat::Rgba8UnormSrgb,
+                RenderAssetUsages::RENDER_WORLD,
+            )
+        }
+    }
+}
+
+pub const DEFAULT_ENVIRONMENT_MAP_TEXTURE_HANDLE: Handle<Image> =
+    uuid_handle!("99e3f21e-9c08-4924-9895-fa8599416316");
+
 impl Default for EnvironmentMapLight {
     fn default() -> Self {
         EnvironmentMapLight {
-            diffuse_map: Handle::default(),
-            specular_map: Handle::default(),
+            diffuse_map: DEFAULT_ENVIRONMENT_MAP_TEXTURE_HANDLE,
+            specular_map: DEFAULT_ENVIRONMENT_MAP_TEXTURE_HANDLE,
             intensity: 0.0,
             rotation: Quat::IDENTITY,
-            affects_lightmapped_mesh_diffuse: true,
+            affects_lightmapped_mesh_diffuse: false,
         }
     }
 }