# Auto-Battler Strategy System Guide

This system provides a complete end-to-end framework for a tactical auto-battler game in Unity, featuring unit recruitment, automated combat simulation, experience/level progression, and advanced tactics (such as Flanking and Feint Retreats).

---

## 1. Quick Start (One-Click Setup)

In Unity, open the top menu bar:
> **`Tools` → `WarGame` → `Setup Complete AutoBattler (Assets + Scene)`**

This will automatically:
1. Generate the base **Unit Prefab** (`PF_BaseUnit`) with a World-Space Billboard Health Bar, Level badge, and Tactical Alert banner.
2. Generate the **Shop Card Prefab** (`PF_ShopCard`) for recruitment.
3. Generate **UnitData ScriptableObjects** with pre-configured stats, level curves, and tactics:
   - **Swordsman** (Melee Infantry - unlocks *Flanking* at Lv.2, *Feint Retreat* at Lv.3)
   - **Archer** (Ranged Specialist - unlocks *Flanking Angles* at Lv.2)
   - **Knight** (Cavalry Charger - unlocks *Cavalry Flank Charge* at Lv.2, *Feint Retreat* at Lv.3)
   - **Bandit Raider & Bandit Archer** (Enemy wave units)
4. Build the complete **UI Canvas**:
   - **Battle HUD**: Live ongoing unit counters (Player alive vs Enemy alive), Round tracker, Phase state, Game Speed (1x, 2x, 4x), Start Battle button.
   - **Shop UI**: Player gold balance, unit cards with stats and tactic previews, Buy buttons.
   - **Battle Results Modal**: Victory/Defeat banner, Gold earned, Surviving units/Casualties, and Level-Up & Tactic unlock reports.
5. Create **Player & Enemy Deployment Zones** and configure **Predefined Waves**.

---

## 2. System Architecture & Scripts

### Data & Progression
- **`UnitDataSO.cs`** (`Assets/Scripts/Data/UnitDataSO.cs`):
  - Defines base stats (HP, Attack Damage, Range, Speed, Armor, Crit Chance, Interval).
  - Stat growth per level (`healthGrowth`, `damageGrowth`, `defenseGrowth`, `speedGrowth`).
  - XP curve calculation (`GetExpRequiredForLevel`).
  - Unlocked tactics list (`UnlockedTactic`: type, required level, trigger threshold, cooldown, duration, multiplier).
- **`UnitProgression.cs`** (`Assets/Scripts/Units/UnitProgression.cs`):
  - Tracks live unit XP, Level, Kills, and Battles Survived.
  - Dynamically calculates stats with level scaling and handles level-up events.

### Combat & Tactical AI
- **`Unit.cs`** (`Assets/Scripts/Units/Unit.cs`):
  - AI State Machine: `Idle`, `Approaching`, `Flanking`, `Attacking`, `FeintRetreating`, `Dead`.
  - Uses `NavMeshAgent` with automatic fallback to kinematic movement.
  - **Flanking Strategy**:
    - When unlocked (default Lv. 2), the unit repositions to the side or rear of engaged enemies.
    - Flank attacks (>60° angle) deal bonus damage (e.g. +50% to +75%) and trigger a `[FLANK STRIKE!]` visual alert.
  - **Feint Retreat Strategy**:
    - When unlocked (default Lv. 3) and health drops below the trigger threshold (e.g. 35%), the unit triggers `[FEINT RETREAT!]`.
    - Sprints back towards friendly lines/deployment zone, pulling pursuing enemies out of formation.
    - When the feint timer ends, the unit rallies and counter-attacks (`[COUNTER-STRIKE!]`).
  - Awards XP to the killer unit upon defeat.
- **`UnitHealthBar.cs`** (`Assets/Scripts/Units/UnitHealthBar.cs`):
  - World-space billboard UI displaying HP bar, level badge (`Lv.X`), and tactic alerts (`FLANKING!`, `FEINT RETREAT!`, `LEVEL UP!`).

### Managers & Game Loop
- **`BattleManager.cs`** (`Assets/Scripts/Managers/BattleManager.cs`):
  - Coordinates battle phases: `Preparation` → `BattleInProgress` → `Victory` / `Defeat`.
  - Tracks **Ongoing Live Unit Counts** (`PlayerAliveCount` vs `EnemyAliveCount`).
  - Spawns enemy waves (supports predefined wave configs and procedural scaling).
  - Handles the economy: starting gold, unit purchase verification, kill bounties, wave clear rewards.
  - Distributes post-battle participation and survival XP to the player's persistent army.
  - Provides battle simulation speed controls (1x, 2x, 4x).
- **`DeploymentZone.cs`** (`Assets/Scripts/Deployment/DeploymentZone.cs`):
  - Allocates grid positions for recruited player units and wave enemies.

### User Interface
- **`ShopCardUI.cs`** & **`ShopUI.cs`** (`Assets/Scripts/UI/`):
  - Displays recruitable units, gold cost, stats summary, and tactic unlocks.
  - Buy button automatically deducts gold, spawns unit in player deployment zone, and updates unit counts.
- **`BattleHUD.cs`** (`Assets/Scripts/UI/BattleHUD.cs`):
  - Top HUD showing live ongoing unit counts: `"Player Army: X / Total" | "Enemy Force: Y / Total"`.
  - Round indicator and game speed controls.
  - Start Battle button.
- **`BattleResultUI.cs`** (`Assets/Scripts/UI/BattleResultUI.cs`):
  - Post-battle report modal showing gold earned, casualties, and unit level-ups.

---

## 3. Creating New Units & Tactics

1. **Create a new Unit Data asset**:
   - Right-click in the Project window: `Create` → `WarGame` → `Unit Data`.
   - Set the name, gold cost, base stats, and growth per level.
2. **Add Tactics to the Unit**:
   - In the inspector of the `UnitDataSO`, expand `Unlocked Tactics`.
   - Add a tactic (e.g. `Flanking` at Required Level `2`, `FeintRetreat` at Required Level `3`).
3. **Add to Shop Catalog**:
   - Select the `ShopPanel` in the scene or canvas.
   - Drag your new `UnitDataSO` into the `Purchasable Units` list in `ShopUI`.