//! Lighting system for scene illumination.
//!
//! Provides light components following glTF KHR_lights_punctual:
//!
//! - [`Light`]: Light source component with type, color, and intensity
//! - [`LightType`]: Directional (sun), Point (omni), or Spot light
//!
//! Lights interact with the entity's transform to determine direction (directional/spot)
//! or position (point/spot). Shadow mapping is supported for all light types.
//!
//! # Quick Start: Add a Sun
//!
//! The easiest way to light a scene:
//!
//! ```ignore
//! spawn_sun(world);  // Directional light with shadows
//! ```
//!
//! # Directional Light (Sun)
//!
//! Infinitely distant light affecting all objects uniformly:
//!
//! ```ignore
//! use nightshade::ecs::light::{Light, LightType};
//! use nightshade::ecs::world::LIGHT;
//!
//! let sun = world.spawn_entities(
//!     LIGHT | LOCAL_TRANSFORM | GLOBAL_TRANSFORM | LOCAL_TRANSFORM_DIRTY,
//!     1
//! )[0];
//!
//! world.set_light(sun, Light {
//!     light_type: LightType::Directional,
//!     color: Vec3::new(1.0, 0.95, 0.9),  // Warm white
//!     intensity: 100000.0,               // Lux (outdoor daylight ~100000)
//!     cast_shadows: true,
//!     shadow_bias: 0.005,
//!     ..Default::default()
//! });
//!
//! // Light direction is entity's -Z axis
//! world.set_local_transform(sun, LocalTransform {
//!     rotation: UnitQuaternion::from_euler_angles(-0.8, 0.5, 0.0),
//!     ..Default::default()
//! });
//! world.add_local_transform_dirty(sun);
//! ```
//!
//! # Point Light (Omni)
//!
//! Light radiating in all directions from a position:
//!
//! ```ignore
//! let lamp = world.spawn_entities(
//!     LIGHT | LOCAL_TRANSFORM | GLOBAL_TRANSFORM | LOCAL_TRANSFORM_DIRTY,
//!     1
//! )[0];
//!
//! world.set_light(lamp, Light {
//!     light_type: LightType::Point,
//!     color: Vec3::new(1.0, 0.8, 0.6),  // Warm orange
//!     intensity: 800.0,                  // Lumens (60W bulb ~800)
//!     range: 10.0,                       // Falloff distance
//!     cast_shadows: true,
//!     shadow_bias: 0.001,
//!     ..Default::default()
//! });
//!
//! world.set_local_transform(lamp, LocalTransform {
//!     translation: Vec3::new(0.0, 3.0, 0.0),
//!     ..Default::default()
//! });
//! world.add_local_transform_dirty(lamp);
//! ```
//!
//! # Spot Light
//!
//! Cone-shaped light for flashlights, stage lights, headlights:
//!
//! ```ignore
//! let spotlight = world.spawn_entities(
//!     LIGHT | LOCAL_TRANSFORM | GLOBAL_TRANSFORM | LOCAL_TRANSFORM_DIRTY,
//!     1
//! )[0];
//!
//! world.set_light(spotlight, Light {
//!     light_type: LightType::Spot,
//!     color: Vec3::new(1.0, 1.0, 1.0),
//!     intensity: 1000.0,
//!     range: 20.0,
//!     inner_cone_angle: 15.0_f32.to_radians(),  // Full intensity cone
//!     outer_cone_angle: 30.0_f32.to_radians(),  // Falloff cone
//!     cast_shadows: true,
//!     shadow_bias: 0.002,
//! });
//!
//! // Position and aim the spotlight
//! world.set_local_transform(spotlight, LocalTransform {
//!     translation: Vec3::new(5.0, 5.0, 0.0),
//!     rotation: UnitQuaternion::face_towards(
//!         &Vec3::new(-1.0, -1.0, 0.0),  // Direction to target
//!         &Vec3::y(),
//!     ),
//!     ..Default::default()
//! });
//! world.add_local_transform_dirty(spotlight);
//! ```
//!
//! # Light Properties
//!
//! | Property | Description |
//! |----------|-------------|
//! | `light_type` | Directional, Point, or Spot |
//! | `color` | Linear RGB color |
//! | `intensity` | Lumens (point/spot) or lux (directional) |
//! | `range` | Falloff distance for point/spot (0 = unlimited) |
//! | `inner_cone_angle` | Spot inner cone (full intensity) in radians |
//! | `outer_cone_angle` | Spot outer cone (zero intensity) in radians |
//! | `cast_shadows` | Enable shadow mapping |
//! | `shadow_bias` | Depth bias to reduce shadow acne |
//!
//! # Typical Intensity Values
//!
//! | Light Type | Intensity | Real-World Equivalent |
//! |------------|-----------|----------------------|
//! | Directional | 100000 lux | Bright daylight |
//! | Directional | 10000 lux | Overcast day |
//! | Point | 800 lumens | 60W incandescent bulb |
//! | Point | 1600 lumens | 100W bulb |
//! | Spot | 1000 lumens | Stage spotlight |
//!
//! # Disabling Shadows
//!
//! For performance or artistic reasons:
//!
//! ```ignore
//! // Light without shadows (no spawn_sun helper)
//! spawn_sun_without_shadows(world);
//!
//! // Or manually
//! light.cast_shadows = false;
//! ```
//!
//! [`Light`]: components::Light
//! [`LightType`]: components::LightType

pub mod components;

pub use components::*;
