RPG-RougeLiteBattler/COMBAT_EVENT_POPUP_GUIDE.md

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

[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

[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!