LowPolyBattleSim/Assets/Scripts/RaycastPro_Integration_Guide.md

# RaycastPro Integration Guide

This guide explains how to set up units with RaycastPro SightDetector integration for the Low Poly Battle Simulator.

## Quick Setup Using the Helper Tool

1. **Open the Unit Setup Helper**
   - In Unity, go to `Battle Sim > Unit Setup Helper`
   - The helper window will open

2. **Configure Single Unit**
   - Drag your unit GameObject to "Target Unit" field
   - Drag your UnitData ScriptableObject to "Unit Data" field
   - Click "Setup Unit Components"

3. **Configure Multiple Units**
   - Select multiple unit GameObjects in the Scene/Hierarchy
   - Set the "Unit Data" field (optional, for units without UnitController)
   - Click "Configure All Selected Units"

## Manual Setup

### Step 1: Create UnitData Assets
1. Right-click in Project window
2. Go to `Create > Battle Sim > Unit Data`
3. Configure the settings:
   - **Detection Range**: How far the unit can see
   - **Sight Angle X**: Horizontal field of view (0-360°)
   - **Sight Angle Y**: Vertical field of view (0-180°)
   - **Full Awareness Radius**: Instant detection range
   - **Attack Range**: Combat range

### Step 2: Setup Unit GameObjects
Each unit needs these components:
1. **UnitController** - Main AI logic
2. **SightDetector** (RaycastPro) - Vision system
3. **UnitSightSystem** - Bridge between the two

### Step 3: Configure Components

**UnitController:**
- Assign the UnitData asset
- Set the team (Player/Enemy)
- Set unique unitId

**UnitSightSystem:**
- References are auto-assigned
- Configure layer masks:
  - Enemy Layer Mask: Layers containing enemy units
  - Ally Layer Mask: Layers containing friendly units  
  - Obstacle Layer Mask: Layers that block line of sight

## Layer Setup Recommendations

Create these layers in your project:
- **Player Units** (Layer 8)
- **Enemy Units** (Layer 9)  
- **Obstacles** (Layer 10)
- **Terrain** (Layer 11)

### Configure Physics Layer Matrix
- Player Units should collide with: Terrain, Obstacles
- Enemy Units should collide with: Terrain, Obstacles
- Both unit types should NOT collide with each other (for movement)

## UnitData Configuration Examples

### Infantry Unit
```
Detection Range: 8
Attack Range: 2
Sight Angle X: 90
Sight Angle Y: 60
Full Awareness: 2
Move Speed: 3
```

### Cavalry Unit
```
Detection Range: 12
Attack Range: 3
Sight Angle X: 120
Sight Angle Y: 90
Full Awareness: 4
Move Speed: 8
Can Charge: true
```

### Archer Unit
```
Detection Range: 15
Attack Range: 8
Sight Angle X: 60
Sight Angle Y: 45
Full Awareness: 3
Move Speed: 2
Is Ranged: true
Max Ammo: 30
```

## Performance Optimization

### Pulse Detection
- Enable "Use Pulse Detection" in UnitData
- Set appropriate pulse interval (default 0.2s)
- Uses less CPU by not updating every frame

### Target Limiting
- Enable "Limit Detected Targets"
- Set max targets (recommended: 5-10)
- Prevents performance issues with large armies

### Layer Masks
- Use specific layers instead of "Everything"
- Only detect what you need to detect
- Configure proper obstacle layers for line-of-sight

## Debugging

### Visual Debug
- Enable "Show Debug Info" on UnitSightSystem
- Shows detection ranges and connections in Scene view
- Console logs for detection events

### SightDetector Gizmos
- RaycastPro automatically shows field-of-view in Scene view
- Different colors for active/inactive states
- Shows detection radius and angles

## Common Issues

### Units Not Detecting Each Other
1. Check layer masks are correct
2. Verify UnitData detection range
3. Ensure units are on proper layers
4. Check if obstacles are blocking line of sight

### Performance Issues
1. Enable pulse detection
2. Limit detected targets
3. Reduce detection ranges
4. Use fewer units or LOD system

### Missing References
1. Use the Unit Setup Helper tool
2. Ensure all components are added
3. Check UnitData is assigned
4. Verify SightDetector configuration

## Integration with Battle System

The sight system automatically integrates with:
- **BattleManager**: Coordinates all units
- **BattleStrategy**: Affects detection behavior
- **Unit AI**: Uses detection for targeting and movement

Units will react to detection based on their:
- Unit type (Infantry/Cavalry/Archer)
- Assigned strategy (Hold/Flank/Charge/etc.)
- Current state and health

## Advanced Features

### Custom Detection Reactions
Override `ReactToEnemyDetection()` in UnitController for custom behavior per unit type.

### Dynamic Configuration
Call `UpdateSightConfiguration()` on UnitSightSystem to apply UnitData changes at runtime.

### Manual Pulse Triggers
Call `TriggerDetectionPulse()` for manual update timing in special situations.