# Combat Event Popup UXML Setup Guide

This guide explains how to set up and use the new UXML-based combat event popup system.

## 📁 Files Created

### UI Assets:
- **`Assets/UI/CombatEventPopup.uxml`** - UXML template defining the popup structure
- **`Assets/UI/CombatEventPopup.uss`** - USS stylesheet with animations and styling
- **`Assets/Scripts/UI/CombatEventPopupUXML.cs`** - Script that uses UXML template

### Key Features:
- ✅ **UXML Template-based** - Easier to edit UI structure
- ✅ **USS Styling** - Professional animations and hover effects
- ✅ **Fallback Support** - Works even without UXML template
- ✅ **Threat Level Indicators** - Color-coded enemy danger levels
- ✅ **Enemy Details** - Shows HP, AC, weapons, and threat levels
- ✅ **Smooth Animations** - Enter/exit transitions and hover effects
- ✅ **Mouse Input Blocking** - Prevents map clicks while popup is open

## 🎯 Per-Event Escape Configuration

**NEW**: Each `CombatTravelEvent` asset now has its own escape configuration! This allows for much more varied and interesting combat encounters:

### Individual Combat Event Setup:
1. **Create/Edit Combat Event Assets**: Go to `Create -> RPG -> Travel Events -> Combat Event`
2. **Configure Escape Settings**:
   - **Allow Running Away**: Uncheck for boss fights or special encounters where escape isn't allowed
   - **Run Away Success Chance**: Set different values per encounter type
     - **Weak enemies** (bandits): 0.9 (90% success)
     - **Normal enemies** (wolves): 0.75 (75% success) 
     - **Strong enemies** (bears): 0.5 (50% success)
     - **Boss encounters**: 0.1 (10% success) or disable entirely
   - **Run Away Health Penalty**: Adjust damage based on enemy danger
   - **Custom Messages**: Write encounter-specific escape descriptions

### Examples:
- **Bandit Ambush**: High escape chance (0.9), low penalty (3 damage), messages like "You slip away while the bandits argue over loot"
- **Dragon Encounter**: Low escape chance (0.2), high penalty (15 damage), messages like "The dragon's flames sear your party as you flee"
- **Town Guard Pursuit**: Escape disabled (legal consequences), forces combat

## 🔄 System Priority:
1. **Combat Event Configuration** (only option) - Uses the specific event's settings
2. **Hardcoded Fallback** - Simple defaults (75% success, 5 damage) if no combat event is available
3. **Error Handling** - Graceful degradation with basic escape mechanics

## 🛠️ Setup Instructions

### Step 1: Create UI Document
1. Create a new GameObject in your scene
2. Name it "CombatEventUI"
3. Add a **UIDocument** component
4. Create a **Panel Settings** asset (Create -> UI Toolkit -> Panel Settings)
5. Assign the Panel Settings to the UIDocument

### Step 2: Setup the Popup Component
1. Add the **CombatEventPopupUXML** component to the same GameObject
2. In the inspector, assign these references:
   - **UI Document**: The UIDocument component you just added
   - **Popup Template**: Drag `Assets/UI/CombatEventPopup.uxml`
   - **Popup Style Sheet**: Drag `Assets/UI/CombatEventPopup.uss`

### Step 3: Setup Combat Integration
**Option A (Recommended): Add to TravelEventSystem GameObject**
1. Find the GameObject that has the **TravelEventSystem** component
2. Add the **CombatEventIntegration** component to that GameObject
3. In the inspector, assign:
   - **Combat Event Popup UXML**: Drag your "CombatEventUI" GameObject's CombatEventPopupUXML component here
   - Leave **Combat Event Popup** empty (this is for the legacy system)
   - Leave **Combat Popup Prefab** empty (only needed if you're using prefabs)

**Option B: Add to UI GameObject (Also works)**
1. Add the **CombatEventIntegration** component to the same GameObject as your popup (CombatEventUI)
2. The system will automatically find the TravelEventSystem in the scene
3. In the inspector, assign:
   - **Combat Event Popup UXML**: The CombatEventPopupUXML component on the same GameObject
   - Leave other fields empty

### Step 4: Configure Panel Settings
In your Panel Settings asset, configure:
- **Scale Mode**: Scale With Screen Size
- **Screen Match Mode**: Match Width Or Height
- **Reference Resolution**: 1920x1080 (or your preferred resolution)

## 🎮 Usage

The system will automatically work with your travel events! When a combat event is triggered:

1. **Automatic Detection**: The system finds CombatEventIntegration in the scene
2. **Beautiful Popup**: Shows enemy details with:
   - Enemy count and names
   - Health, Armor Class, and threat levels
   - Weapon information
   - Color-coded threat indicators
3. **Player Choice**: Two options with hover effects:
   - **[FLEE] RUN AWAY** - Attempt to escape (configurable success rate)
   - **[FIGHT] ATTACK!** - Enter battle
4. **Input Blocking**: Prevents mouse clicks from reaching the map while popup is open

## 🎨 Customization Options

### Visual Customization:
Edit `CombatEventPopup.uss` to change:
- Colors and themes
- Animation speeds and effects
- Button styles and hover effects
- Threat level color coding

### UXML Structure:
Edit `CombatEventPopup.uxml` to:
- Rearrange UI elements
- Add new information displays
- Change button layouts
- Modify popup structure

### Script Configuration:
In `CombatEventPopupUXML.cs` inspector:
- **Animation Duration**: How long show/hide animations take
- **Background Blur Intensity**: Overlay darkness level

### Integration Settings:
In **individual CombatTravelEvent assets** (Required):
- **Allow Running Away**: Enable/disable escape option for this specific combat
- **Run Away Success Chance**: Probability of successful escape (0.0 = never, 1.0 = always)
- **Run Away Health Penalty**: Damage taken on failed escape attempts
- **Successful Run Away Messages**: Custom success messages for this combat type
- **Failed Run Away Messages**: Custom failure messages for this combat type

**Note**: `CombatEventIntegration` no longer has escape configuration fields. All escape behavior is now configured per combat event asset for maximum flexibility and narrative control.

## 🔧 Advanced Features

### Threat Level System:
- **T1-T2**: Green (Low threat)
- **T3-T4**: Yellow (Medium threat) 
- **T5-T6**: Orange (High threat)
- **T7+**: Red with pulse animation (Extreme threat)

### Fallback Support:
If UXML template is missing, the system automatically creates UI programmatically.

### Animation Classes:
- `.popup-enter` - Fade in and scale up
- `.popup-exit` - Fade out and scale down
- `.enemy-item:hover` - Hover effects on enemy items
- `.threat-extreme` - Pulsing animation for dangerous enemies

## 🐛 Troubleshooting

### Common Issues:

**Popup not showing but debug logs say "✅ Combat popup displayed"**
This usually means the UI is created but not visible. Check:
1. **Panel Settings Configuration**:
   - Ensure Panel Settings asset is assigned to UIDocument
   - Set Scale Mode to "Scale With Screen Size"
   - Set Screen Match Mode to "Match Width Or Height"
   - Set Reference Resolution (e.g., 1920x1080)

2. **UIDocument Setup**:
   - GameObject with UIDocument must be active
   - UIDocument component must be enabled
   - Sort Order should be higher than other UI (try 1000)

3. **Camera Setup**:
   - If using Multiple Displays, ensure correct target display
   - Check if UI is behind other UI elements

4. **UXML/USS Assets**:
   - Verify UXML and USS files are properly assigned in inspector
   - Check Console for "Could not find [element] element" errors

**"Could not find [element] element"**
- Ensure UXML template is properly assigned
- Check element names match between UXML and script
- Verify Panel Settings are configured

**"No UIDocument found"**
- Add UIDocument component to GameObject
- Assign Panel Settings to UIDocument

**"No CombatEventIntegration found in scene"**
- Add CombatEventIntegration component to scene
- Assign CombatEventPopupUXML reference

### Quick Diagnostic Steps:

1. **Check Console Logs**: Look for these debug messages:
   - `🔧 SetupUI: Root element size: [width]x[height]`
   - `✅ UXML template instantiated and added to root`
   - `🔍 UI Elements found:` (should show ✅ for all elements)

2. **Verify Panel Settings**:
   - Select your UIDocument GameObject
   - Check if Panel Settings is assigned
   - Open Panel Settings asset and verify configuration

3. **Test with Fallback UI**:
   - Temporarily remove UXML template assignment
   - System should create UI programmatically as fallback
   - If this works, issue is with UXML/USS setup

4. **Check GameObject Hierarchy**:
   - Ensure CombatEventUI GameObject is active
   - Verify no parent objects are disabled
   - Check if GameObject is in correct scene

### Debug Logs:
The system provides detailed debug information:
- `🔍 Looking for CombatEventIntegration component...`
- `✅ Found CombatEventIntegration: [name]`
- `🎭 Calling ShowCombatChoicePopup with X enemies`
- `🗡️ Player chose to ATTACK!`
- `🏃 Player chose to RUN AWAY!`

## 🚀 Comparison: UXML vs Programmatic

### UXML Benefits:
- ✅ **Visual Editor**: Edit UI structure in Unity Inspector
- ✅ **Separation of Concerns**: UI structure separate from logic
- ✅ **Easier Styling**: CSS-like USS styling
- ✅ **Performance**: More efficient element creation
- ✅ **Maintainability**: Easier to modify and update

### Programmatic Benefits:
- ✅ **Dynamic Creation**: Runtime element generation
- ✅ **No Asset Dependencies**: Fully self-contained
- ✅ **Procedural UI**: Complex dynamic layouts

## 📋 File Dependencies

```
CombatEventPopupUXML.cs
├── CombatEventPopup.uxml (optional - has fallback)
├── CombatEventPopup.uss (optional - inline styles as fallback)
├── UIDocument component
└── Panel Settings asset

CombatEventIntegration.cs
├── CombatEventPopupUXML reference
└── TravelEventSystem integration

Travel Events
├── CombatTravelEvent.cs (uses reflection to find integration)
└── BattleEventData (enemy information structure)
```

The new UXML-based system provides a much cleaner, more maintainable approach to creating beautiful combat event popups while maintaining full backwards compatibility!