WarGame/Assets/AutoBattler_System_Guide.md

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.