RPG-RougeLiteBattler/TEAM_PERCEPTION_VISUALIZATION_GUIDE.md

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

// The setup component handles everything automatically
// Just add TeamPerceptionSetup to any GameObject and it will work

Runtime Control

// 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

// 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.