hockey-manager/CLAUDE.md

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