ADD: spot light

docs/MultiLighting.md

@@ -148,6 +148,60 @@ This provides accurate point light shadows without additional shadow maps.
 
 Call `clearPointLights()` before adding your own lights to remove these defaults.
 
+## Spot Lights
+
+Adds cone-limited spot lights alongside point lights, sharing the same BRDF helpers.
+
+### Data Structures
+
+**CPU-side (C++)**
+
+```cpp
+// src/scene/vk_scene.h
+struct SpotLight {
+    WorldVec3 position_world;
+    glm::vec3 direction;        // world-space unit direction (cone axis)
+    float radius;
+    glm::vec3 color;
+    float intensity;
+    float inner_angle_deg;      // cone half-angle (deg)
+    float outer_angle_deg;      // cone half-angle (deg), >= inner
+};
+```
+
+**GPU-side (GLSL)**
+
+```glsl
+// shaders/input_structures.glsl
+#define MAX_SPOT_LIGHTS 32
+
+struct GPUSpotLight {
+    vec4 position_radius;      // xyz: position, w: radius
+    vec4 direction_cos_outer;  // xyz: direction (unit), w: cos(outer_angle)
+    vec4 color_intensity;      // rgb: color, a: intensity
+    vec4 cone;                 // x: cos(inner_angle), yzw: unused
+};
+```
+
+The `GPUSceneData` uniform buffer includes:
+- `spotLights[MAX_SPOT_LIGHTS]`: array of packed spot lights
+- `lightCounts.y`: number of active spot lights
+
+### Shader Implementation
+
+**lighting_common.glsl**
+
+- `eval_spot_light(light, pos, N, V, albedo, roughness, metallic)`:
+  - Applies the same smooth inverse-square falloff as point lights
+  - Multiplies by a soft cone attenuation between `outer_angle` and `inner_angle`
+
+### Render Path Integration
+
+- Deferred lighting (`deferred_lighting*.frag`) and forward (`mesh.frag`) both accumulate spot lights:
+  - `uint spotCount = sceneData.lightCounts.y;`
+  - `for (uint i = 0u; i < spotCount; ++i) { direct += eval_spot_light(...); }`
+
 ### Future Extensions
 
-- Spot lights (add cone angle to `GPUPunctualLight`)
+- Shadow maps for spot lights (single frustum)
+- IES profiles / photometric falloff

docs/Scene.md

@@ -127,6 +127,23 @@ Notes:
   - On level load: call `addPointLight` for each baked/runtime point light.
   - At runtime (e.g. gameplay): read/modify lights via the indexed helpers.
 
+### Spot Lights
+
+- `SceneManager::SpotLight`
+  - `position_world` – world‑space position.
+  - `direction` – world‑space unit direction (cone axis).
+  - `radius` – approximate influence radius (used for falloff).
+  - `inner_angle_deg`, `outer_angle_deg` – cone half‑angles in degrees (inner ≤ outer).
+  - `color` – RGB color.
+  - `intensity` – scalar brightness.
+- API
+  - `addSpotLight(const SpotLight &light)`
+  - `clearSpotLights()`
+  - `getSpotLightCount()`, `getSpotLight(index, outLight)`, `setSpotLight(index, light)`, `removeSpotLight(index)`
+- Usage pattern
+  - On level load: call `addSpotLight` for each flashlight/beam/cone light.
+  - At runtime: read/modify lights via the indexed helpers.
+
 ### Picking & Selection (Game‑Facing)
 
 The scene system exposes CPU ray‑based picking and rectangle selection that the engine uses for editor tools, but you can also call them directly from game code.