hockey-manager/PLAYER.md

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.