# AI Movement System Setup Guide

## Overview

This AI movement system provides realistic, physics-based hockey player behavior with configurable strategies for different game situations.

## Features

### 1. **Physics-Based Movement**
- All movement uses forces (no direct position manipulation)
- Realistic momentum and inertia
- Hockey-like skating with acceleration/deceleration
- Cannot instantly change direction - must overcome current velocity

### 2. **Intelligent Behaviors**

#### When Player Has Puck:
- Maintains distance from opponents (configurable avoidance radius)
- Moves toward offensive zone
- Looks for shooting opportunities when in range
- Finds optimal shooting positions in the slot

#### When Teammate Has Puck:
- **Defenders**: Position themselves to be open for passes
  - Support puck-carrying defender
  - Stay at defensive blue line or push forward (configurable)
- **Forwards**: Push toward offensive zone with speed
  - Spread out by position (LW, C, RW)
  - Maintain minimum speed to support attack
  - Position for pass reception

#### When Opponent Has Puck:
- **Closest Player**: Pressures puck carrier, attempts interception
- **Defenders**: 
  - Form defensive structure
  - One plays at blue line, one lower
  - Protect own goal
- **Forwards**: Backcheck to support defense

## Setup Instructions

### Step 1: Add Components to Players

Add these components to each AI-controlled player GameObject:

1. **Rigidbody** (if not present)
   - Mass: 80-100 (kg)
   - Drag: 1
   - Angular Drag: 5
   - Use Gravity: true
   - Is Kinematic: false
   - Constraints: Freeze Rotation X, Z, and Freeze Position Y

2. **PlayerController** (existing)
   - Assign PlayerStats
   - Assign PlayerMentality
   - Set team tag ("HomeTeam" or "AwayTeam")

3. **PlayerMovement** (updated)
   - Set `isPlayerControlled` to `false` for AI players
   - Set `isPlayerControlled` to `true` for human players

4. **PlayerAIMovement** (new)
   - Max Speed: 8
   - Acceleration: 15
   - Deceleration: 10
   - Turn Speed: 5
   - Stopping Force: 20
   - Min Opponent Distance: 5
   - Pass Search Radius: 20
   - Shooting Distance: 15
   - Assign Movement Schema (optional)

### Step 2: Create Movement Schemas

Right-click in Project window:
`Create > Hockey > AI > Movement Schema`

Configure the schema:

**Default Balanced Schema:**
- Defender Support Distance: 5
- Defender Lateral Spread: 4
- Forward Push Distance: 8
- Forward Lateral Spread: 6
- Forward Aggressiveness: 0.7
- Forward Minimum Speed: 3

**Aggressive Schema:**
- Forward Push Distance: 12
- Forward Aggressiveness: 0.9
- Forecheck Aggression: 0.8
- Forecheckers Count: 2

**Defensive Schema:**
- Defender Stay At Blue Line: true
- Forward Push Distance: 5
- Forward Aggressiveness: 0.4
- Defensive Depth: 0.8

### Step 3: Configure Zone Positions

Adjust these values in PlayerAIMovement to match your rink:

- `defensiveBlueLineZ`: -18 (adjust based on your rink)
- `offensiveBlueLineZ`: 18 (adjust based on your rink)
- `neutralZoneCenter`: 0

### Step 4: Set Up Team Tags

Make sure players have correct tags:
- Home team players: Tag = "HomeTeam"
- Away team players: Tag = "AwayTeam"

### Step 5: Reference the Puck

The PlayerAIMovement script will automatically find the PuckController in the scene. Make sure:
- There is exactly one GameObject with a PuckController component
- The PuckController has proper physics setup

## Customization

### Adjusting Movement Feel

**Faster, More Responsive:**
```csharp
acceleration = 20
turnSpeed = 8
maxSpeed = 10
```

**Heavier, More Realistic:**
```csharp
acceleration = 12
deceleration = 8
turnSpeed = 4
stoppingForce = 25
```

### Behavior Tuning

Edit MovementSchema values to change team strategy:

**Run and Gun (Offensive):**
- High forward aggressiveness
- Large forward push distance
- Multiple forecheckers

**Trap Defense:**
- Defenders stay at blue line
- Lower forward aggressiveness
- Tight defensive formation

### Position-Specific Behavior

The system automatically adjusts behavior by position:

- **LW/RW**: Spread wide in offensive zone
- **C**: Stay center, support both wings
- **LD/RD**: Play respective sides, defensive responsibilities

## Testing and Debugging

### Debug Visualization

PlayerAIMovement draws Gizmos in Scene view:
- **Yellow sphere**: Target position
- **Green ray**: Desired velocity
- **Blue ray**: Current velocity
- **Yellow line**: Path to target

### Common Issues

**Players not moving:**
- Check isPlayerControlled is `false`
- Verify Rigidbody is not kinematic
- Ensure PuckController exists in scene

**Players moving too fast/slow:**
- Adjust maxSpeed and acceleration
- Check Rigidbody drag settings

**Players colliding:**
- Verify Collider setup
- Adjust opponent avoidance distance
- Check Physics layer collision matrix

**Poor positioning:**
- Tune MovementSchema values
- Adjust zone line positions to match rink
- Verify team tags are correct

## Advanced Usage

### Custom Schemas Per Team

```csharp
public MovementSchema homeTeamSchema;
public MovementSchema awayTeamSchema;

void Start()
{
    bool isHomeTeam = CompareTag("HomeTeam");
    movementSchema = isHomeTeam ? homeTeamSchema : awayTeamSchema;
}
```

### Dynamic Strategy Changes

```csharp
// Switch to defensive schema when losing
if (scoreDeficit > 0)
{
    aiMovement.movementSchema = defensiveSchema;
}
```

### Individual Player Overrides

```csharp
// Make one forward more aggressive
if (stats.position == PlayerPosition.C)
{
    aiMovement.shootingDistance = 20f; // Shoots from farther out
}
```

## Performance Notes

- Decision making updates every 0.2 seconds (configurable)
- Physics calculations run every FixedUpdate
- Suitable for 10-12 AI players simultaneously
- Minimal GC allocation

## Next Steps

1. Integrate with existing shoot/pass systems in PlayerController
2. Add line changes and fatigue system
3. Implement special teams (power play, penalty kill)
4. Add more complex forechecking systems (1-2-2, 1-1-3, etc.)
5. Create AI difficulty levels using schema presets