RPG-RougeLiteBattler/BATTLE_ACTION_SYSTEM_GUIDE.md

Battle Action System Setup Guide

Overview

This new battle action system provides a radial decision wheel for selecting character actions including:

• Move - Move to a target location
• Attack - Attack an enemy target
  
• Use Item - Use consumable items (healing potions, etc.)
• Cast Spell - Cast magical spells (placeholder implementation)
• Defend - Defensive stance for damage reduction
• Run Away - Retreat from combat

Setup Instructions

1. Scene Setup

Add these components to your BattleScene:

1. BattleActionSystem - Main system controller

   • Add to an empty GameObject named "BattleActionSystem"

2. BattleActionWheel - The radial menu UI

   • Create a Canvas with these settings:
     • Render Mode: Screen Space - Overlay (or Camera)
     • Canvas Scaler: Scale With Screen Size
   • Add BattleActionWheel script to Canvas or child object

3. BattleActionIntegration - Connects new and old systems

   • Add to an empty GameObject named "BattleActionIntegration"

2. UI Setup

Action Wheel Canvas Structure:

Canvas (BattleActionWheel)
├── WheelBackground (Image)
└── WheelCenter (Empty GameObject)
    └── ActionButtons (will be created automatically)

Action Button Prefab:

Create a prefab with this structure:

ActionButton (Button + Image)
├── Icon (Image)
└── Label (TextMeshPro)

Use the ActionButtonCreator.CreateActionButton() method to create buttons programmatically.

3. Integration with Existing System

The new system can run alongside your existing click-drag system:

• Space Key - Show action wheel for selected character
• Left Click - Select character (when using new system)
• Toggle - Switch between old and new systems via BattleActionIntegration.ToggleActionSystem()

4. Required Assets

Icons (Optional but recommended):

• Move icon (arrow or footsteps)
• Attack icon (sword or crossed swords)
  
• Item icon (potion or bag)
• Spell icon (magic wand or star)
• Defend icon (shield)
• Run Away icon (running figure)

Fonts:

• TextMeshPro font for button labels

5. Character Setup

No changes needed to existing Character prefabs! The system will:

• Automatically initialize enhanced action data when needed
• Work with existing health/damage systems
• Use existing weapon systems

6. Usage Flow

1. Character Selection:

   // Manual selection
   battleActionIntegration.SelectCharacter(character);
      
   // Or click on character in game
   

2. Action Selection:

   • Action wheel appears automatically
   • Click desired action type
   • Follow targeting prompts if needed

3. Action Execution:

   // Execute single character
   battleActionSystem.ExecuteCharacterAction(character);
      
   // Execute all players (turn-based)
   battleActionIntegration.ExecuteAllPlayerActions();
   

API Reference

Key Components

BattleActionSystem

• ShowActionWheel(Character) - Display action wheel
• ExecuteCharacterAction(Character) - Execute selected action
• Events: OnActionStarted, OnActionCompleted

BattleActionWheel

• ShowWheel(Character, Vector3) - Show at world position
• HideWheel() - Hide the wheel
• Events: OnActionSelected, OnWheelClosed

BattleActionIntegration

• SelectCharacter(Character) - Select for action
• ExecuteAllPlayerActions() - Execute all player actions
• ResetAllPlayerActions() - Clear all actions for new turn
• AllPlayersHaveActions() - Check if all players ready

Action Types

public enum BattleActionType
{
    Move,        // Position targeting
    Attack,      // Enemy targeting  
    UseItem,     // Item selection + optional targeting
    CastSpell,   // Spell selection + optional targeting
    Defend,      // No targeting needed
    Wait,        // No targeting needed
    RunAway      // No targeting needed
}

Enhanced Action Data

// Access character's action data
var actionData = character.enhancedActionData as EnhancedCharacterActionData;
if (actionData != null && actionData.hasValidAction)
{
    Debug.Log($"Action: {actionData.GetActionDescription()}");
}

Extending the System

Adding New Actions:

1. Add to BattleActionType enum
2. Update BattleActionWheel.CreateActionButtons()
3. Add case to BattleActionSystem.ExecuteActionCoroutine()
4. Create execution method in BattleActionSystem

Custom Item/Spell Systems:

Replace placeholder implementations in:

• ItemSelectionUI.GetCharacterItems()
• SpellSelectionUI.GetCharacterSpells()
• BattleActionSystem.UseItem()
• BattleActionSystem.CastSpell()

Visual Customization:

• Modify colors in BattleActionWheel
• Replace button creation in ActionButtonCreator
• Add animations to action execution methods

Testing

Use the debug UI (visible when useNewActionSystem = true):

• Select characters
• View action status
• Execute actions manually
• Reset system state
• Toggle between old/new systems

The system includes extensive debug logging with emoji prefixes:

• 🎯 Action selection
• ⚔️ Combat actions
• 🧪 Item usage
• ✨ Spell casting
• 🛡️ Defensive actions

Troubleshooting

Common Issues:

1. Action wheel not showing: Check Canvas setup and camera assignments
2. Buttons not working: Verify Button components and event setup
3. Targeting not working: Check LayerMasks in BattleActionSystem
4. Compilation errors: Ensure all scripts are in correct folders

Debug Commands:

// Force show action wheel
battleActionSystem.ShowActionWheel(character);

// Check action status
Debug.Log(character.enhancedActionData?.GetActionDescription());

// Reset if stuck
battleActionIntegration.ResetAllPlayerActions();

This system provides a solid foundation for complex battle actions while maintaining compatibility with your existing combat system!