# Perception-Based Spottable Event System - Implementation Guide

## Overview

Your RPG now supports **spottable events** that appear as red markers within your team's perception range! Instead of all events triggering automatically, players can now spot potential encounters and choose whether to approach them or avoid them.

## 🎯 Key Features

### **Spottable Event Markers**
- **Red dots** appear within your team's perception circle
- Markers represent events that can be spotted before they trigger
- Players can choose to approach markers to trigger events
- Markers disappear after 30 seconds if not approached

### **Enhanced Perception System**
- Team's perception range (purple circle) now serves a gameplay purpose
- Higher perception = larger detection range for events
- Events can only be spotted within the perception radius

### **Dual Event System**
- **Automatic Events**: Trigger immediately (legacy behavior)
- **Spottable Events**: Appear as markers first, trigger when approached

## 🚀 Quick Setup

### **Step 1: Add Setup Component**
1. In your scene with the travel system, find any GameObject (or create a new one)
2. Add the `PerceptionEventSystemSetup` component
3. Click **"Setup Perception Event System"** in the inspector
4. The system will automatically add required components

### **Step 2: Verify Integration**
- Use the **"Show System Status"** button to verify all components are present
- You should see ✅ for all required components

### **Step 3: Test the System**
1. Start your travel scene
2. You should see the purple perception circle around your team marker
3. As you travel, red event markers may appear within the circle
4. Move your team near a red marker to trigger the event

## 📋 Creating Spottable Events

### **Option 1: Use Pre-built Events**
- **SpottableSkeletonPatrol**: Skeleton warriors that can be spotted and avoided
- Right-click in Project → Create → RPG → Travel Events → Spottable → Skeleton Patrol

### **Option 2: Convert Existing Events**
1. Open any existing `TravelEvent` asset
2. Change **Trigger Type** from `Automatic` to `Spottable`
3. The event will now appear as a red marker instead of triggering immediately

### **Option 3: Create Custom Spottable Events**
```csharp
[CreateAssetMenu(fileName = "MySpottableEvent", menuName = "RPG/Travel Events/Spottable/Custom Event")]
public class MySpottableEvent : CombatTravelEvent
{
    void OnEnable()
    {
        triggerType = EventTriggerType.Spottable;  // Key setting!
        eventName = "My Spottable Event";
        // Configure other settings...
    }
}
```

## ⚙️ System Components

### **EventMarkerVisualizer**
- Manages red event markers within perception range
- Handles marker spawning, lifetime, and cleanup
- Configurable marker appearance and behavior

### **TeamPerceptionVisualizer** (Enhanced)
- Shows purple perception circle around team
- Now used by event system to determine marker spawn range
- Based on team's highest perception value

### **TravelEventSystem** (Enhanced)
- Supports both automatic and spottable events
- Checks for marker triggers when team moves
- Spawns markers for spottable events

### **EventTriggerType** (New Enum)
- `Automatic`: Traditional immediate triggering
- `Spottable`: Appears as marker first, triggers when approached

## 🎮 Player Experience

### **Before (Automatic Events)**
1. Team travels
2. Event triggers randomly
3. Player must deal with event immediately

### **After (Spottable Events)**
1. Team travels with visible perception range
2. Red markers appear for potential events
3. Player can see threats/opportunities coming
4. Player chooses to approach or avoid
5. Strategic perception building becomes valuable

## 🔧 Configuration Options

### **EventMarkerVisualizer Settings**
- **Max Active Markers**: How many red dots can be on screen (default: 5)
- **Marker Lifetime**: How long markers last if not approached (default: 30s)
- **Min/Max Distance**: How close/far from team markers can spawn
- **Marker Color**: Red by default, customizable
- **Pulsing Effect**: Visual pulsing to draw attention

### **Event Settings**
- **Trigger Type**: Choose Automatic or Spottable per event
- **Terrain Preferences**: Where events are more/less likely
- **Rarity**: How often events spawn

### **Perception Settings**
- **Perception Multiplier**: How perception value converts to world distance
- **Visualization**: Purple circle can be toggled on/off

## 📊 Benefits of the New System

### **Strategic Gameplay**
- **Perception becomes valuable**: High perception = see threats/opportunities sooner
- **Player agency**: Choose which encounters to face
- **Risk management**: Avoid dangerous encounters when weakened

### **Improved Immersion**
- **Visual feedback**: See your party's awareness range
- **Realistic encounters**: Spot enemies before they spot you
- **Environmental storytelling**: Markers show the danger level of areas

### **Tactical Depth**
- **Scouting**: High perception characters become scouts
- **Route planning**: Navigate around dangerous encounters
- **Resource management**: Engage only when ready

## 🐛 Troubleshooting

### **No Red Markers Appearing**
- Check that events have `triggerType = EventTriggerType.Spottable`
- Verify EventMarkerVisualizer is in the scene
- Ensure team has perception > 0
- Check event rarity settings

### **Purple Circle Not Showing**
- Check that TeamPerceptionVisualizer is in the scene
- Verify team members have perception values
- Check visualization is enabled in PlayerPrefs

### **Events Not Triggering When Approached**
- Verify team position is within trigger distance (1.5 units)
- Check TravelEventSystem integration
- Look for error messages in console

## 🎯 Advanced Usage

### **Creating Event Chains**
Create multiple spottable events that spawn based on player choices:
```csharp
// First event spawns marker for "Bandit Camp"
// If approached, can spawn "Bandit Leader" marker
// If avoided, can spawn "Bandit Patrol" marker later
```

### **Perception-Based Difficulty**
Adjust event spawning based on team perception:
```csharp
// Higher perception = spot better opportunities
// Lower perception = more dangerous surprises
```

### **Environmental Storytelling**
Use marker density to show area danger:
```csharp
// Forests: Many spottable encounters
// Roads: Fewer spottable, more automatic (safe travel)
// Mountains: Very dangerous spottable encounters
```

## 🎉 Conclusion

The perception-based spottable event system transforms travel from random interruptions into strategic exploration. Players now have meaningful choices, perception becomes a valuable stat, and the game world feels more immersive and tactical.

Your players can now truly scout ahead, avoid dangerous encounters when needed, and make informed decisions about which opportunities to pursue!