Merge pull request #1 from TimWillebrands/configurable-colors

Author: TimWillebrands

docs/decisions/0001-bresenham-based-lighting-engine.md

@@ -1,8 +1,6 @@
 # Use Bresenham Line Algorithms for CPU-Based Lighting Engine
 
 - Status: accepted
-- Deciders: Development Team
-- Date: 2024-12-19
 
 Technical Story: Need for a portable, GPU-independent lighting engine that can work across multiple platforms and devices.
 

docs/decisions/0002-use-rust-for-core-engine.md

@@ -1,8 +1,6 @@
 # Use Rust for Core Engine Instead of C3
 
 - Status: accepted
-- Deciders: Development Team
-- Date: 2024-12-19
 
 Technical Story: The project needs a robust, modern, and maintainable language for its core logic to ensure long-term viability and developer productivity.
 

docs/decisions/0003-avoid-async-for-simplicity.md

@@ -1,8 +1,6 @@
 # Avoid Async Rust for Core Engine Simplicity
 
 - Status: accepted
-- Deciders: Development Team
-- Date: 2024-12-19
 
 Technical Story: As we adopt Rust, we need to decide on a concurrency model that fits the project's goals of simplicity and performance for a CPU-bound workload.
 

docs/decisions/0004-rust-native-collision-detection.md

@@ -1,8 +1,6 @@
 # Rust-Native Collision Detection for Ray Casting Performance
 
-- Status: proposed
-- Deciders: [Performance Analysis and Architecture Review]
-- Date: 2025-07-27
+- Status: accepted
 
 Technical Story: Performance bottleneck identified in ray casting where JavaScript-based collision detection causes ~250ms per light update due to expensive WASM bridge calls.
 

src/lib.rs

@@ -18,6 +18,7 @@
 //! - **Deterministic**: Same inputs always produce identical outputs
 //! - **Portable**: Works on any platform with a CPU
 //! - **Minimalistic**: Small codebase with no heavy dependencies
+//! - **Configurable Colors**: Support for rainbow, solid, and custom HSV colors
 //!
 //! # Architecture
 //!
@@ -37,8 +38,14 @@
 //! // Initialize the engine
 //! init();
 //!
-//! // Add a light at position (100, 50) with radius 30
-//! const lightCanvas = put(1, 30, 100, 50);
+//! // Add a rainbow light at position (100, 50) with radius 30
+//! const rainbowLight = put(1, 30, 100, 50);
+//!
+//! // Add a red light at position (200, 50) with radius 25
+//! const redLight = put_solid_color(2, 25, 200, 50, 0);
+//!
+//! // Add a desaturated blue light with custom color
+//! const customLight = put_custom_color(3, 20, 150, 100, 170, 128);
 //!
 //! // Set up some obstacles
 //! set_tile(5, 3, 1);
@@ -53,8 +60,14 @@
 //! // Initialize the lighting system
 //! lighting::init();
 //!
-//! // Create a light source
+//! // Create a rainbow light source (default)
 //! let canvas_ptr = lighting::update_or_add_light(1, 30, 100, 50);
+//!
+//! // Create a solid color light source
+//! let red_light = lighting::update_or_add_light_with_solid_color(2, 25, 200, 50, 0);
+//!
+//! // Create a custom HSV color light source
+//! let custom_light = lighting::update_or_add_light_with_custom_color(3, 20, 150, 100, 170, 128);
 //! ```
 //!
 //! # Performance Characteristics
@@ -144,6 +157,7 @@ pub fn start() {
 ///
 /// This is the primary interface for managing lights in the scene.
 /// Each light is identified by a unique ID and can be updated independently.
+/// Uses the default rainbow color mode for backward compatibility.
 ///
 /// # Arguments
 /// * `id` - Unique identifier for this light (0-255)
@@ -174,7 +188,7 @@ pub fn start() {
 /// # Example Usage (JavaScript)
 ///
 /// ```javascript
-/// // Create a red light with radius 50 at position (200, 100)
+/// // Create a rainbow light with radius 50 at position (200, 100)
 /// const lightCanvas = put(0, 50, 200, 100);
 ///
 /// // Later, move the same light to a new position
@@ -185,6 +199,59 @@ pub fn put(id: u8, r: i16, x: i16, y: i16) -> *const lighting::Color {
     lighting::update_or_add_light(id, r, x, y)
 }
 
+/// Updates an existing light or creates a new one with a solid color.
+///
+/// # Arguments
+/// * `id` - Unique identifier for this light (0-255)
+/// * `r` - Light radius/range in world units
+/// * `x` - World X coordinate of the light center
+/// * `y` - World Y coordinate of the light center
+/// * `hue` - Color hue (0-255, representing 0-360°)
+///
+/// # Returns
+/// A pointer to the light's rendered canvas data (RGBA pixel array).
+///
+/// # Example Usage (JavaScript)
+///
+/// ```javascript
+/// // Create a red light (hue=0) with radius 50 at position (200, 100)
+/// const lightCanvas = put_solid_color(0, 50, 200, 100, 0);
+///
+/// // Create a green light (hue=85) with radius 30 at position (150, 200)
+/// const greenLight = put_solid_color(1, 30, 150, 200, 85);
+/// ```
+#[wasm_bindgen]
+pub fn put_solid_color(id: u8, r: i16, x: i16, y: i16, hue: u8) -> *const lighting::Color {
+    lighting::update_or_add_light_with_solid_color(id, r, x, y, hue)
+}
+
+/// Updates an existing light or creates a new one with custom HSV color.
+///
+/// # Arguments
+/// * `id` - Unique identifier for this light (0-255)
+/// * `r` - Light radius/range in world units
+/// * `x` - World X coordinate of the light center
+/// * `y` - World Y coordinate of the light center
+/// * `hue` - Color hue (0-255, representing 0-360°)
+/// * `saturation` - Color saturation (0-255, 0=grayscale, 255=full color)
+///
+/// # Returns
+/// A pointer to the light's rendered canvas data (RGBA pixel array).
+///
+/// # Example Usage (JavaScript)
+///
+/// ```javascript
+/// // Create a desaturated blue light
+/// const lightCanvas = put_custom_color(0, 50, 200, 100, 170, 128);
+///
+/// // Create a bright cyan light  
+/// const cyanLight = put_custom_color(1, 30, 150, 200, 128, 255);
+/// ```
+#[wasm_bindgen]
+pub fn put_custom_color(id: u8, r: i16, x: i16, y: i16, hue: u8, saturation: u8) -> *const lighting::Color {
+    lighting::update_or_add_light_with_custom_color(id, r, x, y, hue, saturation)
+}
+
 /// Returns a pointer to the world's tile data array.
 ///
 /// The tile array represents the high-level structure of the world,

src/lighting.rs

@@ -23,7 +23,14 @@ use std::sync::RwLock;
 
 use crate::{arctan, ray};
 
-
+/// Color mode configuration for light sources
+#[derive(Clone, Debug, PartialEq)]
+pub enum ColorMode {
+    /// Solid color using specified hue (0-255)
+    Solid(u8),
+    /// Custom HSV color with specified hue and saturation
+    Custom { hue: u8, saturation: u8 },
+}
 
 /// Maximum distance for light ray casting
 #[cfg(all(test, not(target_arch = "wasm32")))]
@@ -101,6 +108,8 @@ struct Light {
     pos: PtI,
     /// Radius/range of the light (maximum distance it can illuminate)
     r: i16,
+    /// Color mode configuration for this light (None = default rainbow effect)
+    color_mode: Option<ColorMode>,
     /// Rendered pixel data for this light (RGBA format)
     canvas: Vec<Color>,
     /// Canvas dimensions (width and height)
@@ -116,15 +125,17 @@ impl Light {
     /// # Arguments
     /// * `pos` - World coordinates (x, y) where the light is positioned
     /// * `r` - Maximum distance the light can illuminate
+    /// * `color_mode` - Color configuration for this light (None for default rainbow)
     ///
     /// # Returns
     /// A new Light instance with cleared canvas and unblocked angles
-    fn new(pos: PtI, r: i16) -> Self {
+    fn new(pos: PtI, r: i16, color_mode: Option<ColorMode>) -> Self {
         let canvas_size = (r * 2 + 1) as usize;
         let canvas_pixels = canvas_size * canvas_size;
         Light {
             pos,
             r,
+            color_mode,
             canvas: vec![Color::default(); canvas_pixels],
             canvas_size,
             blocked_angles: [255; ANGLES], // 255 = not blocked
@@ -219,7 +230,7 @@ impl Light {
     ///
     /// # Arguments
     /// * `cell` - Local coordinates relative to the light center
-    /// * `angle` - The angle of the ray (used for hue calculation)
+    /// * `angle` - The angle of the ray (used for hue calculation when in rainbow mode)
     /// * `distance` - Distance from light source (used for brightness falloff)
     fn render_light_pixel(&mut self, cell: PtI, angle: usize, distance: u8) {
         // Transform local coordinates to canvas coordinates
@@ -240,10 +251,23 @@ impl Light {
 
         // Ensure we don't write outside the canvas bounds
         if cell_idx < self.canvas.len() {
-            // Use angle for hue, full saturation, and distance-based brightness
-            // Scale angle to full hue range (0-255) for proper color distribution
-            let scaled_hue = (angle * 255) / (ANGLES - 1);
-            self.canvas[cell_idx] = hsv2rgb(scaled_hue as u8, 255, falloff as u8);
+            let color = match &self.color_mode {
+                // Default rainbow effect - hue varies by angle, full saturation
+                None => {
+                    let scaled_hue = (angle * 255) / (ANGLES - 1);
+                    hsv2rgb(scaled_hue as u8, 255, falloff as u8)
+                }
+                // Solid color - fixed hue, full saturation
+                Some(ColorMode::Solid(hue)) => {
+                    hsv2rgb(*hue, 255, falloff as u8)
+                }
+                // Custom color - specified hue and saturation
+                Some(ColorMode::Custom { hue, saturation }) => {
+                    hsv2rgb(*hue, *saturation, falloff as u8)
+                }
+            };
+            
+            self.canvas[cell_idx] = color;
         }
     }
 }
@@ -286,46 +310,62 @@ fn hsv2rgb(h: u8, s: u8, v: u8) -> Color {
     }
 }
 
-/// Updates an existing light or creates a new one with the specified parameters
-///
-/// This is the main entry point for the lighting system from WASM. It manages
-/// the light storage and triggers recalculation when light properties change.
+/// Updates an existing light or creates a new one with a solid color
 ///
 /// # Arguments
 /// * `id` - Unique identifier for the light (0-255)
 /// * `r` - Light radius/range (clamped to MAX_DIST)
 /// * `x` - World X coordinate
 /// * `y` - World Y coordinate
+/// * `hue` - Color hue (0-255, representing 0-360°)
 ///
 /// # Returns
 /// Pointer to the light's canvas data for rendering, or null pointer on error
+pub fn update_or_add_light_with_solid_color(id: u8, r: i16, x: i16, y: i16, hue: u8) -> *const Color {
+    update_light_with_color_mode(id, r, x, y, Some(ColorMode::Solid(hue)))
+}
+
+/// Updates an existing light or creates a new one with custom HSV color
 ///
-/// # Thread Safety
-/// This function is thread-safe thanks to the RwLock protecting the light map.
-/// Multiple lights can be updated concurrently from different threads.
-pub fn update_or_add_light(id: u8, r: i16, x: i16, y: i16) -> *const Color {
+/// # Arguments
+/// * `id` - Unique identifier for the light (0-255)
+/// * `r` - Light radius/range (clamped to MAX_DIST)
+/// * `x` - World X coordinate
+/// * `y` - World Y coordinate
+/// * `hue` - Color hue (0-255, representing 0-360°)
+/// * `saturation` - Color saturation (0-255, 0=grayscale, 255=full color)
+///
+/// # Returns
+/// Pointer to the light's canvas data for rendering, or null pointer on error
+pub fn update_or_add_light_with_custom_color(id: u8, r: i16, x: i16, y: i16, hue: u8, saturation: u8) -> *const Color {
+    update_light_with_color_mode(id, r, x, y, Some(ColorMode::Custom { hue, saturation }))
+}
+
+/// Internal helper function to update lights with any color mode
+fn update_light_with_color_mode(id: u8, r: i16, x: i16, y: i16, color_mode: Option<ColorMode>) -> *const Color {
     // Clamp radius to maximum supported distance
     let clamped_r = r.min(MAX_DIST as i16).max(1);
 
     // Attempt to get write access to the light map
     if let Ok(mut light_map) = LIGHT_MAP.write() {
         // Check if we need to create a new light or update existing
         let needs_new_light = if let Some(existing_light) = light_map.get(&id) {
-            existing_light.r != clamped_r
+            existing_light.r != clamped_r || existing_light.color_mode != color_mode
         } else {
             true
         };
 
         if needs_new_light {
-            // Create new light with correct radius
-            let new_light = Light::new((x, y), clamped_r);
+            // Create new light with correct radius and color mode
+            let new_light = Light::new((x, y), clamped_r, color_mode.clone());
             light_map.insert(id, new_light);
         }
 
         // Get the light and update its properties
         if let Some(light) = light_map.get_mut(&id) {
             light.pos = (x, y);
             light.r = clamped_r;
+            light.color_mode = color_mode;
             light.update()
         } else {
             std::ptr::null()
@@ -336,6 +376,28 @@ pub fn update_or_add_light(id: u8, r: i16, x: i16, y: i16) -> *const Color {
     }
 }
 
+/// Updates an existing light or creates a new one with the specified parameters
+///
+/// This function maintains backward compatibility by using the default rainbow color mode.
+/// For custom colors, use `update_or_add_light_with_solid_color` or 
+/// `update_or_add_light_with_custom_color`.
+///
+/// # Arguments
+/// * `id` - Unique identifier for the light (0-255)
+/// * `r` - Light radius/range (clamped to MAX_DIST)
+/// * `x` - World X coordinate
+/// * `y` - World Y coordinate
+///
+/// # Returns
+/// Pointer to the light's canvas data for rendering, or null pointer on error
+///
+/// # Thread Safety
+/// This function is thread-safe thanks to the RwLock protecting the light map.
+/// Multiple lights can be updated concurrently from different threads.
+pub fn update_or_add_light(id: u8, r: i16, x: i16, y: i16) -> *const Color {
+    update_light_with_color_mode(id, r, x, y, None)
+}
+
 /// Initializes the lighting system
 ///
 /// This function must be called before any lighting calculations can be performed.