bevy_fairy 0.2.0

/// Visual Debug Overlay Module
/// 
/// This module contains all the visual overlay implementations and the manager
/// that coordinates them. Each overlay type has its own module with specific
/// rendering logic and configuration options.
///
/// This module is only available when the "visual_overlays" feature is enabled.

pub mod entity_highlight;
pub mod colliders;
pub mod transforms;
pub mod system_flow;
pub mod performance_metrics;
pub mod custom_markers;

use crate::server::brp_messages::DebugOverlayType;
#[cfg(feature = "visual_overlays")]
use bevy::prelude::*;
#[cfg(feature = "visual_overlays")]
use bevy::camera::Viewport;
use serde::{Deserialize, Serialize};
use std::collections::HashMap;

/// Common trait for all visual debug overlays
pub trait VisualOverlay: Send + Sync + std::fmt::Debug {
    /// Initialize the overlay system
    fn initialize(&mut self, app: &mut App);
    
    /// Update the overlay configuration
    fn update_config(&mut self, config: &serde_json::Value) -> Result<(), String>;
    
    /// Enable or disable the overlay
    fn set_enabled(&mut self, enabled: bool);
    
    /// Check if the overlay is enabled
    fn is_enabled(&self) -> bool;
    
    /// Get performance metrics for this overlay
    fn get_metrics(&self) -> OverlayMetrics;
    
    /// Get the overlay type
    fn overlay_type(&self) -> DebugOverlayType;
    
    /// Cleanup when the overlay is disabled
    fn cleanup(&mut self);
}

/// Performance metrics for individual overlays
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct OverlayMetrics {
    /// Render time in microseconds
    pub render_time_us: u64,
    /// Number of visual elements rendered
    pub element_count: usize,
    /// Memory usage in bytes
    pub memory_usage_bytes: usize,
    /// Frame update count
    pub frame_updates: usize,
    /// Whether the overlay is active this frame
    pub active_this_frame: bool,
    /// Per-viewport rendering statistics
    pub viewport_stats: HashMap<String, ViewportRenderStats>,
}

/// Per-viewport rendering statistics
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct ViewportRenderStats {
    /// Number of elements rendered in this viewport
    pub elements_rendered: usize,
    /// Render time for this viewport in microseconds
    pub render_time_us: u64,
    /// Whether this viewport was active this frame
    pub active: bool,
    /// Viewport dimensions
    pub viewport_size: Option<(u32, u32)>,
}

/// Configuration for viewport-specific rendering
#[derive(Resource, Debug, Clone)]
pub struct ViewportConfig {
    /// Per-viewport overlay visibility settings
    pub viewport_overlays: HashMap<String, ViewportOverlaySettings>,
    /// Default settings for new viewports
    pub default_settings: ViewportOverlaySettings,
    /// Whether to automatically detect new viewports
    pub auto_detect_viewports: bool,
    /// Maximum number of viewports to support
    pub max_viewports: usize,
}

/// Overlay settings for a specific viewport
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ViewportOverlaySettings {
    /// Whether overlays are enabled for this viewport
    pub enabled: bool,
    /// Maximum render time budget per viewport in microseconds
    pub render_budget_us: u64,
    /// Maximum number of overlay elements per viewport
    pub max_elements: usize,
    /// LOD (Level of Detail) settings based on distance
    pub lod_settings: LodSettings,
    /// Specific overlay type visibility
    pub overlay_visibility: HashMap<String, bool>,
}

/// Level of Detail settings for performance optimization
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LodSettings {
    /// Distance thresholds for different LOD levels
    pub distance_thresholds: Vec<f32>, // [near, medium, far]
    /// Element count limits for each LOD level
    pub element_limits: Vec<usize>,
    /// Detail levels for each LOD (0.0 = minimal, 1.0 = full detail)
    pub detail_levels: Vec<f32>,
}

impl Default for ViewportConfig {
    fn default() -> Self {
        Self {
            viewport_overlays: HashMap::new(),
            default_settings: ViewportOverlaySettings::default(),
            auto_detect_viewports: true,
            max_viewports: 8, // Support up to 8 viewports
        }
    }
}

impl Default for ViewportOverlaySettings {
    fn default() -> Self {
        Self {
            enabled: true,
            render_budget_us: 800, // 0.8ms per viewport
            max_elements: 50, // Limit elements per viewport
            lod_settings: LodSettings::default(),
            overlay_visibility: HashMap::new(),
        }
    }
}

impl Default for LodSettings {
    fn default() -> Self {
        Self {
            distance_thresholds: vec![10.0, 50.0, 200.0],
            element_limits: vec![100, 50, 20],
            detail_levels: vec![1.0, 0.7, 0.3],
        }
    }
}

/// Manager for all visual debug overlays
#[cfg_attr(feature = "visual_overlays", derive(Resource))]
#[derive(Debug)]
pub struct VisualOverlayManager {
    /// All registered overlays
    overlays: HashMap<String, Box<dyn VisualOverlay>>,
    /// Global enable/disable state
    global_enabled: bool,
    /// Performance budget in microseconds (2ms = 2000us)
    performance_budget_us: u64,
    /// Total metrics across all overlays
    total_metrics: OverlayMetrics,
}

impl VisualOverlayManager {
    /// Create new visual overlay manager
    pub fn new() -> Self {
        Self {
            overlays: HashMap::new(),
            global_enabled: true,
            performance_budget_us: 2000, // 2ms as per requirements
            total_metrics: OverlayMetrics::default(),
        }
    }
    
    /// Initialize the manager with all overlay types
    pub fn initialize(&mut self, app: &mut App) {
        // Register all overlay implementations
        self.register_overlay("entity_highlight", Box::new(entity_highlight::EntityHighlightOverlay::new()));
        self.register_overlay("colliders", Box::new(colliders::CollidersOverlay::new()));
        self.register_overlay("transforms", Box::new(transforms::TransformsOverlay::new()));
        self.register_overlay("system_flow", Box::new(system_flow::SystemFlowOverlay::new()));
        self.register_overlay("performance_metrics", Box::new(performance_metrics::PerformanceMetricsOverlay::new()));
        
        // Initialize all overlays
        for overlay in self.overlays.values_mut() {
            overlay.initialize(app);
        }
        
        // Add viewport configuration resource
        app.insert_resource(ViewportConfig::default());
        
        // Add global systems
        app.add_systems(PostUpdate, (
            Self::update_performance_metrics,
            Self::check_performance_budget.after(Self::update_performance_metrics),
            Self::manage_viewport_config,
        ));
    }
    
    /// Register a new overlay
    fn register_overlay(&mut self, key: &str, overlay: Box<dyn VisualOverlay>) {
        self.overlays.insert(key.to_string(), overlay);
    }
    
    /// Set overlay enabled/disabled state
    pub fn set_overlay_enabled(
        &mut self,
        overlay_type: &DebugOverlayType,
        enabled: bool,
        config: Option<&serde_json::Value>,
    ) -> Result<(), String> {
        let key = self.overlay_type_to_key(overlay_type);
        
        if let Some(overlay) = self.overlays.get_mut(&key) {
            overlay.set_enabled(enabled);
            
            if let Some(config) = config {
                overlay.update_config(config)?;
            }
            
            info!(
                "Visual overlay '{}' {} with config: {:?}",
                key,
                if enabled { "enabled" } else { "disabled" },
                config
            );
            
            Ok(())
        } else {
            Err(format!("Unknown overlay type: {:?}", overlay_type))
        }
    }
    
    /// Get overlay status
    pub fn get_overlay_status(&self, overlay_type: &DebugOverlayType) -> Option<(bool, OverlayMetrics)> {
        let key = self.overlay_type_to_key(overlay_type);
        self.overlays.get(&key).map(|overlay| {
            (overlay.is_enabled(), overlay.get_metrics())
        })
    }
    
    /// Get all overlay statuses
    pub fn get_all_statuses(&self) -> HashMap<String, (bool, OverlayMetrics)> {
        self.overlays
            .iter()
            .map(|(key, overlay)| {
                (key.clone(), (overlay.is_enabled(), overlay.get_metrics()))
            })
            .collect()
    }
    
    /// Get total performance metrics
    pub fn get_total_metrics(&self) -> &OverlayMetrics {
        &self.total_metrics
    }
    
    /// Check if performance budget is exceeded
    pub fn is_performance_budget_exceeded(&self) -> bool {
        self.total_metrics.render_time_us > self.performance_budget_us
    }
    
    /// Convert overlay type to string key
    fn overlay_type_to_key(&self, overlay_type: &DebugOverlayType) -> String {
        match overlay_type {
            DebugOverlayType::EntityHighlight => "entity_highlight".to_string(),
            DebugOverlayType::Colliders => "colliders".to_string(),
            DebugOverlayType::Transforms => "transforms".to_string(),
            DebugOverlayType::SystemFlow => "system_flow".to_string(),
            DebugOverlayType::PerformanceMetrics => "performance_metrics".to_string(),
            DebugOverlayType::ColliderVisualization => "collider_visualization".to_string(),
            DebugOverlayType::TransformGizmos => "transform_gizmos".to_string(),
            DebugOverlayType::DebugMarkers => "debug_markers".to_string(),
            DebugOverlayType::Custom(name) => format!("custom_{}", name),
        }
    }
    
    /// System to update performance metrics
    fn update_performance_metrics(
        time: Res<Time>,
        mut overlay_manager: ResMut<VisualOverlayManager>,
    ) {
        let start_time = std::time::Instant::now();
        
        // Aggregate metrics from all overlays
        let mut total_render_time = 0;
        let mut total_element_count = 0;
        let mut total_memory_usage = 0;
        let mut total_frame_updates = 0;
        let mut any_active = false;
        
        for overlay in overlay_manager.overlays.values() {
            let metrics = overlay.get_metrics();
            total_render_time += metrics.render_time_us;
            total_element_count += metrics.element_count;
            total_memory_usage += metrics.memory_usage_bytes;
            total_frame_updates += metrics.frame_updates;
            any_active |= metrics.active_this_frame;
        }
        
        overlay_manager.total_metrics = OverlayMetrics {
            render_time_us: total_render_time,
            element_count: total_element_count,
            memory_usage_bytes: total_memory_usage,
            frame_updates: total_frame_updates,
            active_this_frame: any_active,
            viewport_stats: HashMap::new(),
        };
        
        // Track system execution time
        let execution_time = start_time.elapsed().as_micros() as u64;
        overlay_manager.total_metrics.render_time_us += execution_time;
    }
    
    /// System to check performance budget and warn if exceeded
    fn check_performance_budget(
        overlay_manager: Res<VisualOverlayManager>,
    ) {
        if overlay_manager.is_performance_budget_exceeded() {
            warn!(
                "Visual debug overlay performance budget exceeded: {}μs > {}μs",
                overlay_manager.total_metrics.render_time_us,
                overlay_manager.performance_budget_us
            );
            
            // Log details about which overlays are consuming time
            for (name, overlay) in &overlay_manager.overlays {
                let metrics = overlay.get_metrics();
                if metrics.render_time_us > 100 { // Log overlays taking more than 100μs
                    warn!(
                        "Overlay '{}' performance: {}μs, {} elements",
                        name,
                        metrics.render_time_us,
                        metrics.element_count
                    );
                }
            }
        }
    }
    
    /// System to manage viewport configuration and auto-detection
    fn manage_viewport_config(
        mut viewport_config: ResMut<ViewportConfig>,
        cameras: Query<(Entity, &Camera, &GlobalTransform), With<Camera>>,
    ) {
        if !viewport_config.auto_detect_viewports {
            return;
        }
        
        let mut active_viewports = std::collections::HashSet::new();
        
        // Detect active viewports from cameras
        for (entity, camera, _transform) in &cameras {
            if !camera.is_active {
                continue;
            }
            
            let viewport_id = format!("camera_{}", entity.index());
            active_viewports.insert(viewport_id.clone());
            
            // Add new viewport if not exists
            if !viewport_config.viewport_overlays.contains_key(&viewport_id) {
                if viewport_config.viewport_overlays.len() < viewport_config.max_viewports {
                    let default = viewport_config.default_settings.clone();
                    viewport_config.viewport_overlays.insert(
                        viewport_id.clone(),
                        default,
                    );
                    info!("Auto-detected new viewport: {}", viewport_id);
                } else {
                    warn!("Maximum viewport limit reached: {}", viewport_config.max_viewports);
                }
            }
        }
        
        // Remove inactive viewports (optional cleanup)
        let inactive_viewports: Vec<String> = viewport_config
            .viewport_overlays
            .keys()
            .filter(|k| !active_viewports.contains(*k))
            .cloned()
            .collect();
        
        for viewport_id in inactive_viewports {
            viewport_config.viewport_overlays.remove(&viewport_id);
            debug!("Removed inactive viewport: {}", viewport_id);
        }
    }
}

impl Default for VisualOverlayManager {
    fn default() -> Self {
        Self::new()
    }
}

/// Plugin to add visual debug overlay support to a Bevy app
pub struct VisualDebugOverlayPlugin {
    /// Whether to initialize overlays immediately
    pub auto_initialize: bool,
}

impl Default for VisualDebugOverlayPlugin {
    fn default() -> Self {
        Self {
            auto_initialize: true,
        }
    }
}

impl Plugin for VisualDebugOverlayPlugin {
    fn build(&self, app: &mut App) {
        if self.auto_initialize {
            let mut manager = VisualOverlayManager::new();
            manager.initialize(app);
            app.insert_resource(manager);
        } else {
            app.insert_resource(VisualOverlayManager::new());
        }
    }
}

// Re-export overlay implementations
pub use entity_highlight::{EntityHighlightOverlay, HighlightedEntity, HighlightMode, HighlightConfig};

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_overlay_type_to_key() {
        let manager = VisualOverlayManager::new();
        
        assert_eq!(
            manager.overlay_type_to_key(&DebugOverlayType::EntityHighlight),
            "entity_highlight"
        );
        assert_eq!(
            manager.overlay_type_to_key(&DebugOverlayType::Colliders),
            "colliders"
        );
        assert_eq!(
            manager.overlay_type_to_key(&DebugOverlayType::Custom("test".to_string())),
            "custom_test"
        );
    }

    #[test]
    fn test_performance_budget_tracking() {
        let manager = VisualOverlayManager::new();
        
        // Default budget is 2000us (2ms)
        assert_eq!(manager.performance_budget_us, 2000);
        assert!(!manager.is_performance_budget_exceeded()); // Should be false initially
    }
}