# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

This is a client-side JavaScript application that runs directly in the browser:

- **Run the application**: Open `index.html` in a web browser
- **No build process**: The application uses vanilla JavaScript with no build tools
- **No package manager**: No npm/yarn dependencies, all code is self-contained

## Project Architecture

### Core Architecture Pattern
The project uses an **Entity-Component-System (ECS)** pattern with event-driven communication:

- **Entities**: `Player` and `Puck` classes represent game objects
- **Systems**: Modular systems handle specific concerns (rendering, physics, AI, rules)
- **Game Engine**: Central orchestrator that manages all systems and entities
- **Game State**: Centralized state management for scores, time, penalties, etc.

### System Dependencies
The application loads scripts in a specific order due to class dependencies:

1. **Utilities**: `vector.js`, `physics.js` (foundational math/physics)
2. **Entities**: `player.js`, `puck.js` (game objects)
3. **Systems**: `renderer.js`, `physics-system.js`, `ai-system.js`, `rules-system.js`, `debug-system.js`
4. **Engine**: `game-state.js`, `game-engine.js`, `main.js` (orchestration)

### Key Classes and Responsibilities

- **HockeyManager** (`main.js`): Application lifecycle, canvas setup, global events
- **GameEngine** (`game-engine.js`): 60 FPS game loop, system coordination, player/puck management
- **GameState** (`game-state.js`): Score tracking, time management, penalty system
- **Player** (`player.js`): Hockey player with AI, physics, and role-based behavior
- **Puck** (`puck.js`): Physics-based puck with collision detection
- **Renderer** (`renderer.js`): 2D canvas rendering with camera system and debug visualizations
- **AISystem** (`ai-system.js`): Team formations and strategic AI behaviors
- **RulesSystem** (`rules-system.js`): Hockey rule enforcement (offside, icing, penalties)
- **DebugSystem** (`debug-system.js`): Comprehensive debugging interface with real-time inspection

### Game Loop Architecture
The engine runs at 60 FPS using `requestAnimationFrame` with these phases:
1. Input processing
2. Physics simulation
3. AI decision making
4. Rules enforcement
5. Rendering

### Hockey-Specific Features
- **12 players** (6 per team) with distinct roles: Center (C), Left/Right Wing (LW/RW), Left/Right Defense (LD/RD), Goalie (G)
- **Formation system** with offensive/defensive positioning
- **Rule enforcement**: Offside detection, icing calls, penalty system
- **Realistic physics**: Collision detection, momentum conservation, board bouncing

## Controls Reference
- `SPACE` - Pause/Resume game
- `D` - Toggle debug information and visual overlays
- `R` - Reset game
- `F11` - Toggle fullscreen
- `Mouse Wheel` - Camera zoom
- **Debug Mode Button** - Open/close comprehensive debug panel

## Debug System Features

### Enhanced Debug Panel
When debug mode is active, you can pause the game and inspect all variables:

- **Real-time Debug Panel**: Right-side panel with live game state information
- **Player State Inspection**: Click any player to see detailed attributes, AI state, and physics data
- **Game State Monitoring**: Period, time, score, pause status, faceoff information
- **Puck Tracking**: Position, velocity, ownership, and physics data

### Interactive Debug Features
- **Player Selection**: Click players in debug panel or directly on the canvas
- **Target Visualization**: Selected players show bright cyan lines to their target positions
- **Visual Feedback**: Hover effects, selection highlighting, and smooth animations

### Console Debug Functions
Access via `debugHelpers` global object:
- `debugHelpers.getPlayers()` - Get all player objects
- `debugHelpers.getHomeTeam()` / `debugHelpers.getAwayTeam()` - Get team players
- `debugHelpers.getPlayer(id)` - Get specific player by ID
- `debugHelpers.getPuck()` - Get puck object with full state
- `debugHelpers.getGameState()` - Get complete game state
- `debugHelpers.getPuckCarrier()` - Get player currently carrying the puck
- `debugHelpers.exportGameState()` - Export full game state for analysis

### Debug Visualizations
When visual debug mode is active (`D` key):
- **Velocity Vectors**: Red arrows showing player movement direction
- **Target Lines**: Green dashed lines to player destinations
- **AI Targets**: Yellow dotted lines to AI decision targets
- **Energy Bars**: Visual energy indicators above players
- **Puck Carrier Highlight**: Yellow dashed circle around puck carrier
- **Selected Player**: Cyan line to target with crosshair marker

## File Structure Notes
- All code is vanilla JavaScript (ES6 classes)
- No modules or imports - everything is global
- Canvas-based 2D rendering
- Self-contained with no external dependencies