RPG-RougeLiteBattler/COMBAT_EVENT_POPUP_UXML_GUIDE.md

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!