# Team Perception Visualization System

## Overview
The Team Perception Visualization System displays a semi-transparent purple circle around the team marker in MapScene2 to represent the team's collective perception range. The circle radius is based on the highest perception value among all team members.

## Features

### 🔮 Visual Perception Range
- **Purple Circle**: 50% transparent purple circle around team marker
- **Dynamic Radius**: Based on highest team member perception value
- **Real-time Updates**: Updates when team composition or perception changes
- **Customizable**: Color, size multiplier, and other settings can be adjusted

### 🎯 Smart Team Detection
- **Multiple Sources**: Gets team data from MainTeamSelectScript or GameStateManager
- **Automatic Updates**: Monitors team changes and updates visualization
- **Fallback Support**: Works even if team data is only in save file

### ⚙️ Easy Setup
- **Automatic Setup**: Just add TeamPerceptionSetup component to any GameObject
- **Inspector Configuration**: All settings available in Unity Inspector
- **Debug Tools**: Built-in verification and debug tools

## Setup Instructions

### Method 1: Automatic Setup (Recommended)
1. **Open MapScene2** in Unity
2. **Create Empty GameObject**:
   - Right-click in Hierarchy → Create Empty
   - Name it "PerceptionSystem"
3. **Add Setup Component**:
   - Select the new GameObject
   - In Inspector, click "Add Component"
   - Search for "TeamPerceptionSetup" and add it
4. **Configure Settings** (optional):
   - Adjust color if you want different from purple
   - Modify perception multiplier to change circle size
   - Enable/disable debug logging
5. **Play the Scene**: The system will automatically set up when the scene starts

### Method 2: Manual Setup
1. **Find SimpleTeamPlacement**: Locate the existing SimpleTeamPlacement object in your scene
2. **Add Visualizer Component**: Add TeamPerceptionVisualizer component to the same GameObject
3. **Configure Settings**: Adjust the settings in the Inspector as needed

## Configuration Options

### TeamPerceptionSetup Settings
- **Auto Setup On Start**: Automatically sets up the system when scene starts
- **Enable Perception Visualization**: Toggle to show/hide the perception circle
- **Perception Color**: Color of the circle (default: 50% transparent purple)
- **Perception Multiplier**: How large the circle is relative to perception value (default: 0.2)
- **Custom Material**: Optional material for advanced circle styling
- **Show Debug Info**: Enable debug logging for troubleshooting

### TeamPerceptionVisualizer Settings (Advanced)
- **Circle Segments**: Resolution of the circle (higher = smoother)
- **Height Offset**: How high above ground the circle appears
- **Update Interval**: How often to check for perception changes
- **Update In Real Time**: Whether to continuously monitor for changes

## How It Works

### Perception Calculation
1. **Scans Team Members**: Checks all current team members
2. **Finds Highest Perception**: Uses the highest `FinalPerception` value (includes equipment bonuses)
3. **Calculates Radius**: `radius = highestPerception * perceptionMultiplier`
4. **Positions Circle**: Centers the circle on the team marker position

### Team Data Sources
The system gets team information from multiple sources:
1. **MainTeamSelectScript.teamMembers** (if available in current scene)
2. **GameStateManager.savedTeam** (fallback from save data)

### Visual Updates
- **Team Changes**: Updates when team composition changes
- **Equipment Changes**: Updates when perception-affecting equipment is added/removed
- **Position Changes**: Follows the team marker when it moves
- **Real-time**: Checks for changes every second (configurable)

## Usage Examples

### Basic Setup
```csharp
// The setup component handles everything automatically
// Just add TeamPerceptionSetup to any GameObject and it will work
```

### Runtime Control
```csharp
// Get the setup component
TeamPerceptionSetup setup = FindObjectOfType<TeamPerceptionSetup>();

// Change color to blue with 30% transparency
setup.SetPerceptionColor(new Color(0f, 0f, 1f, 0.3f));

// Make circles larger
setup.SetPerceptionMultiplier(0.4f);

// Toggle visualization
setup.SetPerceptionVisualizationEnabled(false);
```

### Advanced Customization
```csharp
// Get the visualizer directly for advanced control
TeamPerceptionVisualizer visualizer = FindObjectOfType<TeamPerceptionVisualizer>();

// Force an immediate update
visualizer.ForceUpdatePerception();

// Show debug information
visualizer.ShowPerceptionDebugInfo();
```

## Debug Tools

### Inspector Context Menus
Right-click on the components in Inspector to access:

**TeamPerceptionSetup**:
- "Setup Perception Visualization" - Manually trigger setup
- "Verify Perception System" - Check if everything is working
- "Force Refresh Perception" - Update visualization immediately

**TeamPerceptionVisualizer**:
- "Show Perception Debug Info" - Display detailed team perception data

### Console Output
With debug logging enabled, you'll see messages like:
```
TeamPerceptionVisualizer: Updated perception circle - Max Perception: 15, Radius: 3.0
=== Team Perception Debug Info ===
Team Members Count: 4
- Alice: Perception 15 (Base: 12, Modifier: 3)
- Bob: Perception 10 (Base: 10, Modifier: 0)
- Carol: Perception 14 (Base: 14, Modifier: 0)
- Dave: Perception 8 (Base: 8, Modifier: 0)
Highest Perception: 15 (Alice)
Circle Radius: 3.0 units
```

## Troubleshooting

### Circle Not Appearing
1. **Check Team Data**: Verify you have team members with perception > 0
2. **Check Team Marker**: Ensure SimpleTeamPlacement has placed the team marker
3. **Run Verification**: Use "Verify Perception System" context menu
4. **Check Console**: Look for error messages

### Circle Wrong Size
1. **Adjust Multiplier**: Increase perceptionMultiplier for larger circles
2. **Check Perception Values**: Use debug info to see actual perception values
3. **Verify Calculation**: radius = highestPerception × multiplier

### Circle Wrong Position
1. **Check Team Marker**: Ensure team marker is correctly positioned
2. **Verify SimpleTeamPlacement**: Make sure it's working properly
3. **Check Console**: Look for position-related debug messages

### Team Data Not Found
1. **Create Team**: Make sure you've created team members in Team Select scene
2. **Save Game**: Ensure team data is saved to GameStateManager
3. **Check Sources**: Verify MainTeamSelectScript or GameStateManager has team data

## Integration with Existing Systems

### Compatible With
- ✅ **SimpleTeamPlacement**: Uses team marker position automatically
- ✅ **GameStateManager**: Reads saved team data
- ✅ **MainTeamSelectScript**: Reads current team composition
- ✅ **TeamCharacter System**: Uses FinalPerception property
- ✅ **Equipment System**: Automatically includes perception equipment bonuses

### Performance Notes
- **Efficient Updates**: Only updates when perception actually changes
- **Configurable Frequency**: Update interval can be adjusted for performance
- **Memory Friendly**: Minimal memory footprint
- **Scene Integration**: Works seamlessly with existing map systems

## Future Enhancements

Possible improvements:
- **Gradient Colors**: Different colors based on perception level
- **Multiple Circles**: Show individual team member perception ranges
- **Animated Effects**: Pulsing or rotating circle animations
- **Terrain Integration**: Different visibility based on terrain type
- **Minimap Integration**: Show perception range on minimap

## Files Created

1. **`Assets/Scripts/Map/TeamPerceptionVisualizer.cs`**: Main visualization component
2. **`Assets/Scripts/Map/TeamPerceptionSetup.cs`**: Easy setup and configuration script
3. **Enhanced `Assets/Scripts/Map/SimpleTeamPlacement.cs`**: Added team marker access properties

## Example Team Perception Values

With default settings (multiplier = 0.2):
- **Perception 10**: 2.0 unit radius circle
- **Perception 15**: 3.0 unit radius circle  
- **Perception 20**: 4.0 unit radius circle
- **Perception 25**: 5.0 unit radius circle (high-perception scouts)

The system automatically uses the highest perception value among all team members, so having one high-perception scout will give the entire team a large detection radius.