...

PLAYER.md

@@ -0,0 +1,103 @@
+# 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.

src/entities/player.js

@@ -542,8 +542,8 @@ class Player {
         ctx.rotate(this.angle);
 
         ctx.fillStyle = this.team === 'home' ? '#4a90e2' : '#e24a4a';
-        ctx.strokeStyle = '#fff';
+        ctx.strokeStyle = this.state.hasPuck ? '#000' : '#fff';
-        ctx.lineWidth = 2;
+        ctx.lineWidth = this.state.hasPuck ? 3 : 2;
 
         ctx.beginPath();
         ctx.arc(0, 0, this.radius, 0, Math.PI * 2);