# Player Logic Documentation

## Overview
The `Player` class represents hockey players with AI-driven behavior, physics simulation, and role-based positioning. Each player has attributes, states, and intelligent decision-making capabilities.

## Player Structure

### Core Properties
- **Identity**: `id`, `name`, `team` ('home' or 'away'), `role` (C, LW, RW, LD, RD, G)
- **Physics**: `position`, `velocity`, `targetPosition`, `mass`, `radius`, `maxSpeed`
- **Attributes**: Speed, shooting, passing, defense, checking, puck handling, awareness (70-90 range)
- **State**: Energy, puck possession, checking status, injury status
- **AI State**: Current target, behavior mode, reaction timing

### Player Roles
- **C (Center)**: Primary playmaker, takes faceoffs
- **LW/RW (Wings)**: Offensive forwards, positioned on left/right sides
- **LD/RD (Defense)**: Defensive players, protect own zone
- **G (Goalie)**: Larger, slower, stays in crease area

## AI Behavior System

### Main Update Loop
1. **Energy Management**: Drains based on movement speed, regenerates when stationary
2. **Movement Physics**: Accelerates toward target position with friction
3. **Angle Updates**: Smoothly rotates toward target angle
4. **Behavior Selection**: Chooses actions based on game situation

### Faceoff Handling
When `gameState.faceoff.isActive` is true:
- Players move to specific faceoff positions based on their role
- Centers line up at the dot, wings/defense stay outside the circle
- Goalies remain in their nets

### Behavior States

#### With Puck
- **Shooting**: Attempts shots when in good scoring position (<250 units from goal)
- **Passing**: Finds open teammates when under pressure (<60 units from opponent)
- **Advancing**: Moves toward enemy goal while avoiding opponents

#### Without Puck
- **Chasing**: Closest non-goalie teammate pursues loose puck
- **Checking**: Applies body checks to opponents with puck
- **Defending**: Positions between puck carrier and own goal
- **Formation**: Moves to tactical position based on game situation

### Formation System
Players dynamically switch between attacking and defensive formations:

**Attacking Formation** (when team has puck or puck in offensive zone):
- Forwards push toward opponent's goal
- Defense provides support from behind
- Creates offensive pressure

**Defensive Formation** (when opponent has puck):
- Players fall back toward own goal
- Tight defensive positioning
- Focus on puck recovery

## Key AI Methods

### Decision Making
- `updateAI()`: Main AI decision loop with reaction timing
- `behaviorWithPuck()`: Offensive actions (shoot, pass, advance)
- `behaviorWithoutPuck()`: Defensive/support actions
- `determineTeamState()`: Analyzes if team is attacking or defending

### Movement & Positioning
- `getFormationPosition()`: Calculates tactical position based on game state
- `moveToPosition()`: Sets movement target and facing direction
- `findBestPathToGoal()`: Intelligent pathfinding around opponents

### Interactions
- `shoot()`: Fires puck toward target with accuracy based on attributes
- `pass()`: Passes to teammate with appropriate power
- `checkPlayer()`: Physical body check that affects opponent's velocity

### Utility Functions
- `isClosestPlayerToPuck()`: Determines if this player should chase loose puck
- `hasGoodShootingAngle()`: Checks for clear shot opportunity
- `findBestPassTarget()`: Locates optimal passing target

## Goalie Behavior
Goalies have specialized behavior:
- Stay within crease boundaries
- Position based on puck location
- Move to intercept shots
- Don't participate in offensive plays

## Physics Integration
- Collision detection with radius-based boundaries
- Realistic acceleration and deceleration
- Energy affects maximum speed (tired players move slower)
- Friction applied for realistic movement

## Rendering
- Team-colored circles with role labels
- Yellow indicator when player has puck
- Rotation shows facing direction
- Debug information available

The player system creates realistic hockey gameplay through intelligent AI, formation tactics, and physics-based movement.