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.