Migrate lights to required components (bevyengine#15554)

# Objective

Another step in the migration to required components: lights!

Note that this does not include `EnvironmentMapLight` or reflection
probes yet, because their API hasn't been fully chosen yet.

## Solution

As per the [selected
proposals](https://hackmd.io/@bevy/required_components/%2FLLnzwz9XTxiD7i2jiUXkJg):

- Deprecate `PointLightBundle` in favor of the `PointLight` component
- Deprecate `SpotLightBundle` in favor of the `PointLight` component
- Deprecate `DirectionalLightBundle` in favor of the `DirectionalLight`
component

## Testing

I ran some examples with lights.

---

## Migration Guide

`PointLightBundle`, `SpotLightBundle`, and `DirectionalLightBundle` have
been deprecated. Use the `PointLight`, `SpotLight`, and
`DirectionalLight` components instead. Adding them will now insert the
other components required by them automatically.

Author: Jondolf

crates/bevy_gltf/src/loader.rs

@@ -17,8 +17,7 @@ use bevy_ecs::{
 use bevy_hierarchy::{BuildChildren, ChildBuild, WorldChildBuilder};
 use bevy_math::{Affine2, Mat4, Vec3};
 use bevy_pbr::{
-    DirectionalLight, DirectionalLightBundle, PbrBundle, PointLight, PointLightBundle, SpotLight,
-    SpotLightBundle, StandardMaterial, UvChannel, MAX_JOINTS,
+    DirectionalLight, PbrBundle, PointLight, SpotLight, StandardMaterial, UvChannel, MAX_JOINTS,
 };
 use bevy_render::{
     alpha::AlphaMode,
@@ -1523,14 +1522,11 @@ fn load_node(
             if let Some(light) = gltf_node.light() {
                 match light.kind() {
                     gltf::khr_lights_punctual::Kind::Directional => {
-                        let mut entity = parent.spawn(DirectionalLightBundle {
-                            directional_light: DirectionalLight {
-                                color: Color::srgb_from_array(light.color()),
-                                // NOTE: KHR_punctual_lights defines the intensity units for directional
-                                // lights in lux (lm/m^2) which is what we need.
-                                illuminance: light.intensity(),
-                                ..Default::default()
-                            },
+                        let mut entity = parent.spawn(DirectionalLight {
+                            color: Color::srgb_from_array(light.color()),
+                            // NOTE: KHR_punctual_lights defines the intensity units for directional
+                            // lights in lux (lm/m^2) which is what we need.
+                            illuminance: light.intensity(),
                             ..Default::default()
                         });
                         if let Some(name) = light.name() {
@@ -1543,17 +1539,14 @@ fn load_node(
                         }
                     }
                     gltf::khr_lights_punctual::Kind::Point => {
-                        let mut entity = parent.spawn(PointLightBundle {
-                            point_light: PointLight {
-                                color: Color::srgb_from_array(light.color()),
-                                // NOTE: KHR_punctual_lights defines the intensity units for point lights in
-                                // candela (lm/sr) which is luminous intensity and we need luminous power.
-                                // For a point light, luminous power = 4 * pi * luminous intensity
-                                intensity: light.intensity() * core::f32::consts::PI * 4.0,
-                                range: light.range().unwrap_or(20.0),
-                                radius: 0.0,
-                                ..Default::default()
-                            },
+                        let mut entity = parent.spawn(PointLight {
+                            color: Color::srgb_from_array(light.color()),
+                            // NOTE: KHR_punctual_lights defines the intensity units for point lights in
+                            // candela (lm/sr) which is luminous intensity and we need luminous power.
+                            // For a point light, luminous power = 4 * pi * luminous intensity
+                            intensity: light.intensity() * core::f32::consts::PI * 4.0,
+                            range: light.range().unwrap_or(20.0),
+                            radius: 0.0,
                             ..Default::default()
                         });
                         if let Some(name) = light.name() {
@@ -1569,19 +1562,16 @@ fn load_node(
                         inner_cone_angle,
                         outer_cone_angle,
                     } => {
-                        let mut entity = parent.spawn(SpotLightBundle {
-                            spot_light: SpotLight {
-                                color: Color::srgb_from_array(light.color()),
-                                // NOTE: KHR_punctual_lights defines the intensity units for spot lights in
-                                // candela (lm/sr) which is luminous intensity and we need luminous power.
-                                // For a spot light, we map luminous power = 4 * pi * luminous intensity
-                                intensity: light.intensity() * core::f32::consts::PI * 4.0,
-                                range: light.range().unwrap_or(20.0),
-                                radius: light.range().unwrap_or(0.0),
-                                inner_angle: inner_cone_angle,
-                                outer_angle: outer_cone_angle,
-                                ..Default::default()
-                            },
+                        let mut entity = parent.spawn(SpotLight {
+                            color: Color::srgb_from_array(light.color()),
+                            // NOTE: KHR_punctual_lights defines the intensity units for spot lights in
+                            // candela (lm/sr) which is luminous intensity and we need luminous power.
+                            // For a spot light, we map luminous power = 4 * pi * luminous intensity
+                            intensity: light.intensity() * core::f32::consts::PI * 4.0,
+                            range: light.range().unwrap_or(20.0),
+                            radius: light.range().unwrap_or(0.0),
+                            inner_angle: inner_cone_angle,
+                            outer_angle: outer_cone_angle,
                             ..Default::default()
                         });
                         if let Some(name) = light.name() {

crates/bevy_pbr/src/bundle.rs

@@ -1,3 +1,5 @@
+#![expect(deprecated)]
+
 use crate::{
     CascadeShadowConfig, Cascades, DirectionalLight, Material, PointLight, SpotLight,
     StandardMaterial,
@@ -97,6 +99,10 @@ pub struct CascadesVisibleEntities {
 
 /// A component bundle for [`PointLight`] entities.
 #[derive(Debug, Bundle, Default, Clone)]
+#[deprecated(
+    since = "0.15.0",
+    note = "Use the `PointLight` component instead. Inserting it will now also insert the other components required by it automatically."
+)]
 pub struct PointLightBundle {
     pub point_light: PointLight,
     pub cubemap_visible_entities: CubemapVisibleEntities,
@@ -115,6 +121,10 @@ pub struct PointLightBundle {
 
 /// A component bundle for spot light entities
 #[derive(Debug, Bundle, Default, Clone)]
+#[deprecated(
+    since = "0.15.0",
+    note = "Use the `SpotLight` component instead. Inserting it will now also insert the other components required by it automatically."
+)]
 pub struct SpotLightBundle {
     pub spot_light: SpotLight,
     pub visible_entities: VisibleMeshEntities,
@@ -133,6 +143,10 @@ pub struct SpotLightBundle {
 
 /// A component bundle for [`DirectionalLight`] entities.
 #[derive(Debug, Bundle, Default, Clone)]
+#[deprecated(
+    since = "0.15.0",
+    note = "Use the `DirectionalLight` component instead. Inserting it will now also insert the other components required by it automatically."
+)]
 pub struct DirectionalLightBundle {
     pub directional_light: DirectionalLight,
     pub frusta: CascadesFrusta,

crates/bevy_pbr/src/lib.rs

@@ -68,6 +68,7 @@ pub use volumetric_fog::{
 /// The PBR prelude.
 ///
 /// This includes the most common types in this crate, re-exported for your convenience.
+#[expect(deprecated)]
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{

crates/bevy_pbr/src/light/directional_light.rs

@@ -1,3 +1,5 @@
+use bevy_render::{view::Visibility, world_sync::SyncToRenderWorld};
+
 use super::*;
 
 /// A Directional light.
@@ -36,8 +38,8 @@ use super::*;
 ///
 /// Shadows are produced via [cascaded shadow maps](https://developer.download.nvidia.com/SDK/10.5/opengl/src/cascaded_shadow_maps/doc/cascaded_shadow_maps.pdf).
 ///
-/// To modify the cascade set up, such as the number of cascades or the maximum shadow distance,
-/// change the [`CascadeShadowConfig`] component of the [`DirectionalLightBundle`].
+/// To modify the cascade setup, such as the number of cascades or the maximum shadow distance,
+/// change the [`CascadeShadowConfig`] component of the entity with the [`DirectionalLight`].
 ///
 /// To control the resolution of the shadow maps, use the [`DirectionalLightShadowMap`] resource:
 ///
@@ -49,6 +51,15 @@ use super::*;
 /// ```
 #[derive(Component, Debug, Clone, Reflect)]
 #[reflect(Component, Default, Debug)]
+#[require(
+    Cascades,
+    CascadesFrusta,
+    CascadeShadowConfig,
+    CascadesVisibleEntities,
+    Transform,
+    Visibility,
+    SyncToRenderWorld
+)]
 pub struct DirectionalLight {
     /// The color of the light.
     ///

crates/bevy_pbr/src/light/point_light.rs

@@ -1,3 +1,5 @@
+use bevy_render::{view::Visibility, world_sync::SyncToRenderWorld};
+
 use super::*;
 
 /// A light that emits light in all directions from a central point.
@@ -19,6 +21,13 @@ 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
+)]
 pub struct PointLight {
     /// The color of this light source.
     pub color: Color,

crates/bevy_pbr/src/light/spot_light.rs

@@ -1,3 +1,5 @@
+use bevy_render::{view::Visibility, world_sync::SyncToRenderWorld};
+
 use super::*;
 
 /// A light that emits light in a given direction from a central point.
@@ -7,6 +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)]
 pub struct SpotLight {
     /// The color of the light.
     ///

examples/3d/3d_scene.rs

@@ -30,14 +30,13 @@ fn setup(
         ..default()
     });
     // light
-    commands.spawn(PointLightBundle {
-        point_light: PointLight {
+    commands.spawn((
+        PointLight {
             shadows_enabled: true,
             ..default()
         },
-        transform: Transform::from_xyz(4.0, 8.0, 4.0),
-        ..default()
-    });
+        Transform::from_xyz(4.0, 8.0, 4.0),
+    ));
     // camera
     commands.spawn(Camera3dBundle {
         transform: Transform::from_xyz(-2.5, 4.5, 9.0).looking_at(Vec3::ZERO, Vec3::Y),

examples/3d/3d_shapes.rs

@@ -116,17 +116,16 @@ fn setup(
         ));
     }
 
-    commands.spawn(PointLightBundle {
-        point_light: PointLight {
+    commands.spawn((
+        PointLight {
             shadows_enabled: true,
             intensity: 10_000_000.,
             range: 100.0,
             shadow_depth_bias: 0.2,
             ..default()
         },
-        transform: Transform::from_xyz(8.0, 16.0, 8.0),
-        ..default()
-    });
+        Transform::from_xyz(8.0, 16.0, 8.0),
+    ));
 
     // ground plane
     commands.spawn(PbrBundle {

examples/3d/3d_viewport_to_world.rs

@@ -66,10 +66,10 @@ fn setup(
     ));
 
     // light
-    commands.spawn(DirectionalLightBundle {
-        transform: Transform::from_translation(Vec3::ONE).looking_at(Vec3::ZERO, Vec3::Y),
-        ..default()
-    });
+    commands.spawn((
+        DirectionalLight::default(),
+        Transform::from_translation(Vec3::ONE).looking_at(Vec3::ZERO, Vec3::Y),
+    ));
 
     // camera
     commands.spawn(Camera3dBundle {

examples/3d/anisotropy.rs

@@ -252,24 +252,18 @@ fn add_skybox_and_environment_map(
 
 /// Spawns a rotating directional light.
 fn spawn_directional_light(commands: &mut Commands) {
-    commands.spawn(DirectionalLightBundle {
-        directional_light: DirectionalLight {
-            color: WHITE.into(),
-            illuminance: 3000.0,
-            ..default()
-        },
+    commands.spawn(DirectionalLight {
+        color: WHITE.into(),
+        illuminance: 3000.0,
         ..default()
     });
 }
 
 /// Spawns a rotating point light.
 fn spawn_point_light(commands: &mut Commands) {
-    commands.spawn(PointLightBundle {
-        point_light: PointLight {
-            color: WHITE.into(),
-            intensity: 200000.0,
-            ..default()
-        },
+    commands.spawn(PointLight {
+        color: WHITE.into(),
+        intensity: 200000.0,
         ..default()
     });
 }