# Combat Event Popup System - Setup Guide

## Overview
This system provides a beautiful popup UI for combat encounters that allows players to choose between "Attack" or "Run Away" when encountering enemies during travel.

## Components Created

### 1. CombatEventPopup.cs
- **Purpose**: Beautiful UI popup showing enemy details and choice buttons
- **Features**: 
  - Displays enemy count, names, stats, and threat levels
  - Animated popup with smooth transitions
  - Hover effects on buttons
  - Enemy threat level color coding

### 2. CombatEventIntegration.cs
- **Purpose**: Connects the popup with the travel event system
- **Features**:
  - Handles player choices (attack/run away)
  - Manages escape success/failure logic
  - Applies health penalties for failed escapes
  - Configurable escape chance and messages

### 3. Enhanced TravelEventTypes.cs
- **Purpose**: Updated combat events to use the popup system
- **Features**:
  - Automatically detects if popup system is available
  - Falls back to immediate battle if no popup found
  - Integrates with existing enemy character data

## Setup Instructions

### Step 1: Create UI Document
1. In your scene, create a UI Document GameObject
2. Add a UI Document component
3. Create or assign a Panel Settings asset
4. Leave the Visual Tree Asset blank (popup creates its own UI)

### Step 2: Setup Combat Event Popup
1. Create an empty GameObject named "CombatEventPopup"
2. Add the `CombatEventPopup` component
3. Assign the UI Document from step 1 to the `uiDocument` field
4. Adjust animation settings if desired

### Step 3: Setup Combat Event Integration
1. Find your existing TravelEventSystem GameObject
2. Add the `CombatEventIntegration` component to the same GameObject
3. Assign the CombatEventPopup from step 2 to the `combatEventPopup` field
4. Configure settings:
   - **Allow Running Away**: Enable/disable run away option
   - **Run Away Success Chance**: Probability of successful escape (0.0 - 1.0)
   - **Run Away Health Penalty**: Damage taken on failed escape
   - **Messages**: Customize success/failure messages

### Step 4: Test the System
1. Create or find a CombatTravelEvent asset
2. Assign EnemyCharacterData assets to the `possibleEnemies` array
3. Add the combat event to your TravelEventSystem's `availableEvents` list
4. Start travel and trigger the event (use "Force Next Event" for testing)

## Configuration Options

### Combat Event Integration Settings
```csharp
[Header("Combat Popup Integration")]
public bool allowRunningAway = true;            // Can players run away?
public float runAwaySuccessChance = 0.75f;      // 75% success chance
public int runAwayHealthPenalty = 5;            // Damage on failed escape

[Header("Run Away Messages")]
public string[] successfulRunAwayMessages;      // Success messages
public string[] failedRunAwayMessages;          // Failure messages (use {damage} placeholder)
```

### Popup Animation Settings
```csharp
[Header("Popup Settings")]
public float animationDuration = 0.3f;          // Animation speed
public float backgroundBlurIntensity = 0.5f;    // Background overlay opacity
```

## Enemy Display Features

### Threat Level Color Coding
- **Green (1-2)**: Easy enemies
- **Yellow (3-4)**: Medium enemies  
- **Orange (5-6)**: Hard enemies
- **Red (7+)**: Very hard enemies

### Enemy Information Shown
- Enemy count and name
- Health points, armor class, threat level
- Preferred weapon (if assigned)
- Visual threat level indicator

## Integration Flow

### 1. Combat Event Triggered
```
Travel Event System → Combat Travel Event → Combat Integration → Popup UI
```

### 2. Player Makes Choice
```
Popup UI → Combat Integration → Apply Result → Continue/Battle
```

### 3. Escape Outcomes
**Successful Escape:**
- Show success message
- No penalties applied
- Travel continues normally

**Failed Escape:**
- Show failure message with damage
- Apply health penalty to party
- Force combat to start

### 4. Attack Choice
- Show battle preparation message
- Stop travel
- Set up battle with enemy data
- Transition to battle system

## Troubleshooting

### Popup Not Appearing
1. Check that UI Document is properly assigned
2. Verify CombatEventIntegration is on the same GameObject as TravelEventSystem
3. Ensure combat events have valid EnemyCharacterData assigned

### Escape Always Fails/Succeeds
1. Check `runAwaySuccessChance` setting (0.0 = always fail, 1.0 = always succeed)
2. Verify `allowRunningAway` is enabled

### UI Layout Issues
1. Check that Panel Settings asset is properly configured
2. Verify screen resolution compatibility
3. Adjust popup container sizing in CombatEventPopup.cs

### Events Go Straight to Battle
1. Verify CombatEventIntegration component is present and enabled
2. Check console for "No CombatEventIntegration found" warnings
3. Ensure all components are on active GameObjects

## Customization Tips

### Custom Enemy Display
Modify `CreateEnemyElement()` in CombatEventPopup.cs to show additional enemy information like special abilities or lore.

### Custom Button Styles
Update `SetupButtonHoverEffects()` and button creation code to match your game's visual style.

### Different Escape Mechanics
Modify `HandleRunAwayChoice()` in CombatEventIntegration.cs to implement different escape mechanics based on party stats, terrain, or enemy types.

### Battle System Integration
Update `ApplyBattleResult()` in CombatEventIntegration.cs to properly integrate with your existing battle scene transition system.

## File Locations
- `/Assets/Scripts/UI/CombatEventPopup.cs`
- `/Assets/Scripts/Events/CombatEventIntegration.cs`  
- `/Assets/Scripts/Events/TravelEventTypes.cs` (modified)

This system provides a rich, interactive combat encounter experience while maintaining compatibility with your existing travel and battle systems!