bevy_light

Light component types — point, spot, and directional lights — plus ambient lighting, environment maps, lightmap data, and clustered shading metadata. Data only; the renderer reads from these types but lives in bevy_pbr.

Purpose

bevy_light was carved out of bevy_pbr so users who want a custom renderer can still consume Bevy's light component types. The crate has no wgpu dependency.

Directory layout

crates/bevy_light/src/
├── lib.rs
├── point_light.rs
├── spot_light.rs
├── directional_light.rs
├── ambient_light.rs
├── light_probe/      # Environment / irradiance volume probes
├── shadow.rs         # Shadow map config
├── volumetric.rs     # Volumetric light component
├── cascade.rs        # Cascade settings for directional shadows
├── cluster/          # Cluster config (consumed by bevy_pbr clustering)
└── …

Key abstractions

Type	File	Description
PointLight	crates/bevy_light/src/point_light.rs	Omnidirectional light component.
SpotLight	crates/bevy_light/src/spot_light.rs	Cone light component.
DirectionalLight	crates/bevy_light/src/directional_light.rs	Sun-like infinite light component.
AmbientLight	crates/bevy_light/src/ambient_light.rs	Per-camera ambient term.
EnvironmentMapLight	crates/bevy_light/src/light_probe/environment_map.rs	IBL environment map component.
IrradianceVolume	crates/bevy_light/src/light_probe/irradiance_volume.rs	Probe-grid baked GI.
Cascades, CascadeShadowConfig	crates/bevy_light/src/cascade.rs	Directional shadow cascade settings.

How it works

Each light type is a regular ECS component plus, optionally, a Transform. PbrPlugin in bevy_pbr extracts these into the render world, builds GPU buffers (clustered light list, shadow map texture array), and consumes them in shaders. The Volumetric component is a marker indicating a light should contribute to volumetric fog.

Shadow casting is opt-in per light via the shadows_enabled flag.

Integration points

• Depends on: bevy_app, bevy_ecs, bevy_math, bevy_color, bevy_camera, bevy_transform, bevy_image (for shadow atlas dimensions).
• Depended on by: bevy_pbr, bevy_solari (which augments lighting), bevy_gltf (which spawns these from glTF lights).

Entry points for modification

• New light type: add a struct + plugin; teach bevy_pbr to extract and render it.
• Per-light shadow tweaks: shadow.rs and the corresponding light file.
• Probe-grid changes: light_probe/.

See also

• bevy_pbr — the renderer half.
• bevy_solari — experimental ray-traced GI on top of these lights.