LowPolyBattleSim/Assets/Scripts/Script_Hierarchy_Guide.md

# Low Poly Battle Sim - Script Hierarchy & Assignment Guide

This document outlines the complete script hierarchy and where each component should be assigned in Unity.

## 📋 Project Hierarchy Structure

```
LowPolyBattleSim (Scene)
├── 🎮 Game Managers
│   ├── BattleManager [BattleManager.cs]
│   └── UI Canvas [Canvas]
│       └── BattleUI [BattleUI.cs]
├── 🏰 Battle Arena
│   ├── Terrain
│   ├── Obstacles (Buildings, Walls, etc.)
│   └── Spawn Areas
│       ├── PlayerSpawnArea [Transform]
│       └── EnemySpawnArea [Transform]
├── 👥 Player Army
│   ├── Infantry Squad
│   │   ├── Infantry_01 [UnitController.cs, SightDetector, UnitSightSystem.cs]
│   │   ├── Infantry_02 [UnitController.cs, SightDetector, UnitSightSystem.cs]
│   │   └── ...
│   ├── Cavalry Squad
│   │   ├── Cavalry_01 [UnitController.cs, SightDetector, UnitSightSystem.cs]
│   │   ├── Cavalry_02 [UnitController.cs, SightDetector, UnitSightSystem.cs]
│   │   └── ...
│   └── Archer Squad
│       ├── Archer_01 [UnitController.cs, SightDetector, UnitSightSystem.cs]
│       ├── Archer_02 [UnitController.cs, SightDetector, UnitSightSystem.cs]
│       └── ...
└── 👹 Enemy Army
    ├── Infantry Squad
    │   ├── EnemyInfantry_01 [UnitController.cs, SightDetector, UnitSightSystem.cs]
    │   └── ...
    ├── Cavalry Squad
    │   ├── EnemyCavalry_01 [UnitController.cs, SightDetector, UnitSightSystem.cs]
    │   └── ...
    └── Archer Squad
        ├── EnemyArcher_01 [UnitController.cs, SightDetector, UnitSightSystem.cs]
        └── ...
```

## 🎯 Script Assignment Details

### 1. **BattleManager GameObject**
```
GameObject: BattleManager (Empty GameObject)
Required Scripts:
├── BattleManager.cs
Required Assignments:
├── Player Spawn Area: [Transform] → PlayerSpawnArea transform
├── Enemy Spawn Area: [Transform] → EnemySpawnArea transform  
├── Default Player Strategy: [BattleStrategy] → Auto-assigned or custom
└── Default Enemy Strategy: [BattleStrategy] → Auto-assigned or custom

Inspector Configuration:
• Battle Duration: 300 (seconds)
• Player Units Remaining: Auto-populated
• Enemy Units Remaining: Auto-populated
```

### 2. **UI Canvas GameObject**
```
GameObject: UI Canvas
Required Components:
├── Canvas
├── Canvas Scaler
├── Graphic Raycaster
└── BattleUI.cs

BattleUI.cs Assignments:
├── Strategy Panel: [GameObject] → Panel containing strategy controls
├── Strategy Input Field: [TMP_InputField] → Text input for natural language
├── Start Battle Button: [Button] → Button to begin battle
├── Reset Battle Button: [Button] → Button to reset battle
├── Hold Position Toggle: [Toggle] → Strategy selection
├── Flank Toggle: [Toggle] → Strategy selection
├── Charge Toggle: [Toggle] → Strategy selection
├── Spread Wide Toggle: [Toggle] → Strategy selection
├── Wait For Close Toggle: [Toggle] → Strategy selection
├── Infantry Strategy Dropdown: [TMP_Dropdown] → Unit-specific strategy
├── Cavalry Strategy Dropdown: [TMP_Dropdown] → Unit-specific strategy
├── Archer Strategy Dropdown: [TMP_Dropdown] → Unit-specific strategy
├── Battle Status Text: [TextMeshProUGUI] → Current battle status
├── Player Units Text: [TextMeshProUGUI] → Player unit count
├── Enemy Units Text: [TextMeshProUGUI] → Enemy unit count
├── Battle Time Text: [TextMeshProUGUI] → Battle timer
└── Strategy Description Text: [TextMeshProUGUI] → Strategy explanation
```

### 3. **Unit GameObjects (Player & Enemy)**
```
GameObject: [UnitName] (e.g., Infantry_01, Cavalry_01, etc.)
Required Components:
├── Transform
├── Rigidbody (optional, for physics-based movement)
├── Collider (for detection and collision)
├── UnitController.cs
├── SightDetector (RaycastPro)
└── UnitSightSystem.cs

UnitController.cs Assignments:
├── Unit Data: [UnitData ScriptableObject] → Specific unit configuration
├── Team: [Team Enum] → Player or Enemy
├── Unit Id: [int] → Unique identifier (0, 1, 2, etc.)
├── Current Health: Auto-set from UnitData
├── Current State: Auto-managed
├── Assigned Strategy: Auto-assigned by BattleManager
├── Target: Auto-managed
├── Formation Position: Auto-set
└── Rally Point: Auto-set

SightDetector (RaycastPro) Configuration:
├── Radius: Auto-set from UnitData.detectionRange
├── Angle X: Auto-set from UnitData.sightAngleX
├── Angle Y: Auto-set from UnitData.sightAngleY
├── Full Awareness: Auto-set from UnitData.fullAwarenessRadius
├── Min Radius: Auto-set from UnitData.minDetectionRadius
├── Limited: Auto-set from UnitData.limitDetectedTargets
├── Limit Count: Auto-set from UnitData.maxDetectedTargets
├── Detect Layer: Set to include enemy/ally layers
└── Block Layer: Set to obstacle layers

UnitSightSystem.cs Assignments:
├── Unit Controller: [UnitController] → Auto-assigned
├── Sight Detector: [SightDetector] → Auto-assigned
├── Enemy Layer Mask: [LayerMask] → Layers containing enemies
├── Ally Layer Mask: [LayerMask] → Layers containing allies
├── Obstacle Layer Mask: [LayerMask] → Layers blocking line of sight
└── Show Debug Info: [bool] → Enable for testing
```

## 📦 ScriptableObject Assets

### **UnitData Assets** (Create in Project/Assets/Data/)
```
Infantry_Data.asset
├── Unit Name: "Heavy Infantry"
├── Unit Type: Infantry
├── Health: 120
├── Damage: 25
├── Attack Range: 2.5
├── Move Speed: 3
├── Detection Range: 8
├── Sight Angle X: 90
├── Sight Angle Y: 60
├── Can Charge: false
├── Is Ranged: false
└── Auto Configure Sight Detector: true

Cavalry_Data.asset
├── Unit Name: "Heavy Cavalry"
├── Unit Type: Cavalry
├── Health: 100
├── Damage: 35
├── Attack Range: 3
├── Move Speed: 8
├── Detection Range: 12
├── Sight Angle X: 120
├── Sight Angle Y: 90
├── Can Charge: true
├── Is Ranged: false
└── Auto Configure Sight Detector: true

Archer_Data.asset
├── Unit Name: "Longbow Archer"
├── Unit Type: Archer
├── Health: 80
├── Damage: 30
├── Attack Range: 10
├── Move Speed: 2.5
├── Detection Range: 15
├── Sight Angle X: 60
├── Sight Angle Y: 45
├── Can Charge: false
├── Is Ranged: true
├── Max Ammo: 30
└── Auto Configure Sight Detector: true
```

## 🏷️ Layer Configuration

### **Required Layers:**
```
Layer 8: PlayerUnits
Layer 9: EnemyUnits
Layer 10: Obstacles
Layer 11: Terrain
Layer 12: Projectiles (future use)
```

### **Layer Mask Assignments:**
```
Player Units:
├── Enemy Layer Mask: EnemyUnits (Layer 9)
├── Ally Layer Mask: PlayerUnits (Layer 8)
└── Obstacle Layer Mask: Obstacles + Terrain (Layers 10, 11)

Enemy Units:
├── Enemy Layer Mask: PlayerUnits (Layer 8)  
├── Ally Layer Mask: EnemyUnits (Layer 9)
└── Obstacle Layer Mask: Obstacles + Terrain (Layers 10, 11)

SightDetector Settings:
├── Detect Layer Mask: PlayerUnits + EnemyUnits (Layers 8, 9)
└── Block Layer Mask: Obstacles + Terrain (Layers 10, 11)
```

## 🎨 Prefab Structure

### **Unit Prefabs** (Create in Project/Assets/Prefabs/)
```
Infantry_Prefab
├── Model (Visual representation)
├── UnitController.cs → Unit Data: Infantry_Data
├── SightDetector → Auto-configured
├── UnitSightSystem.cs → Auto-configured
├── Rigidbody
├── Collider
└── Layer: PlayerUnits or EnemyUnits

Cavalry_Prefab
├── Model (Visual representation)
├── UnitController.cs → Unit Data: Cavalry_Data
├── SightDetector → Auto-configured  
├── UnitSightSystem.cs → Auto-configured
├── Rigidbody
├── Collider
└── Layer: PlayerUnits or EnemyUnits

Archer_Prefab
├── Model (Visual representation)
├── UnitController.cs → Unit Data: Archer_Data
├── SightDetector → Auto-configured
├── UnitSightSystem.cs → Auto-configured
├── Rigidbody
├── Collider
└── Layer: PlayerUnits or EnemyUnits
```

## 🔧 Setup Workflow

### **Step 1: Create Scene Structure**
1. Create empty GameObjects for organization
2. Set up terrain and obstacles
3. Create spawn area markers

### **Step 2: Create ScriptableObject Assets**
1. Right-click → Create → Battle Sim → Unit Data
2. Create separate assets for each unit type
3. Configure stats and RaycastPro settings

### **Step 3: Setup Game Managers**
1. Create BattleManager GameObject
2. Add BattleManager.cs script
3. Assign spawn area references

### **Step 4: Create UI**
1. Create UI Canvas
2. Add BattleUI.cs script
3. Create and assign all UI elements

### **Step 5: Create Unit Prefabs**
1. Use Unit Setup Helper tool OR
2. Manually add all required components
3. Assign UnitData assets
4. Set proper layers and tags

### **Step 6: Populate Scene**
1. Instantiate unit prefabs in scene
2. Set team assignments (Player/Enemy)
3. Assign unique unit IDs
4. Position in spawn areas

### **Step 7: Configure Layers & Physics**
1. Create required layers
2. Configure Physics Layer Matrix
3. Set layer masks on components

## 🚀 Quick Setup Using Helper Tool

**Use the Unit Setup Helper:**
1. Window → Battle Sim → Unit Setup Helper
2. Select unit GameObjects
3. Assign UnitData assets
4. Click "Configure All Selected Units"

**This automatically:**
- Adds all required components
- Configures SightDetector settings
- Sets up component references
- Applies UnitData configurations

## 🐛 Common Assignment Issues

### **Missing References:**
- Use Unit Setup Helper to auto-assign
- Check that UnitData assets are created
- Verify SightDetector is added to units

### **Layer Conflicts:**
- Ensure units are on correct layers
- Check Physics Layer Matrix settings
- Verify layer masks match team assignments

### **Performance Issues:**
- Enable pulse detection in UnitData
- Limit detected targets (5-10 recommended)
- Use appropriate detection ranges

This hierarchy ensures all scripts work together seamlessly for your battle simulation system!