Hockey/Assets/Scripts/Player/AI/AI_MOVEMENT_GUIDE.md

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:

acceleration = 20
turnSpeed = 8
maxSpeed = 10

Heavier, More Realistic:

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

public MovementSchema homeTeamSchema;
public MovementSchema awayTeamSchema;

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

Dynamic Strategy Changes

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

Individual Player Overrides

// 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