# Hockey Manager - 2D Match Engine

A JavaScript-based 2D hockey match engine for web browsers featuring realistic physics, AI players, and complete hockey rules implementation.

## Features

### Core Game Engine
- **60 FPS game loop** with requestAnimationFrame
- **Physics system** with collision detection and realistic puck/player movement
- **Game state management** with time tracking, scoring, and statistics
- **Event-driven architecture** for game events and interactions

### Gameplay Features
- **12 players** (6 per team) with distinct roles (C, LW, RW, LD, RD, G)
- **Realistic hockey rules**: offsides, icing, penalties, power plays
- **Player AI behaviors**: puck handling, passing, shooting, checking, formations
- **Complete hockey rink** with proper dimensions, goals, creases, and faceoff dots
- **Live statistics** tracking shots, saves, hits, penalties, ice time

### Visual Features
- **2D Canvas rendering** with smooth animations
- **Hockey rink visualization** with proper lines, zones, and markings
- **Player sprites** with team colors and role indicators
- **Puck physics** with trail effects and realistic bouncing
- **Camera system** with zoom and follow capabilities
- **Particle effects** for goals, saves, and collisions

### Controls & UI
- **Real-time scoreboard** with period and clock display
- **Game statistics panel** showing shots, saves, and penalties
- **Interactive controls** for play/pause, speed adjustment, and reset
- **Keyboard shortcuts** for quick game control
- **Responsive design** that adapts to screen size

## Project Structure

```
hockey-manager/
├── index.html              # Main HTML entry point
├── css/
│   └── styles.css          # Game styling and UI
├── src/
│   ├── engine/
│   │   ├── game-engine.js  # Main game engine
│   │   ├── game-state.js   # Game state management
│   │   └── main.js         # Application initialization
│   ├── entities/
│   │   ├── player.js       # Player entity with AI
│   │   └── puck.js         # Puck physics and behavior
│   ├── systems/
│   │   ├── renderer.js     # 2D rendering system
│   │   ├── physics-system.js # Physics calculations
│   │   ├── ai-system.js    # AI formation and strategy
│   │   ├── rules-system.js # Hockey rules enforcement
│   │   └── debug-system.js # Comprehensive debugging interface
│   └── utils/
│       ├── vector.js       # 2D vector mathematics
│       └── physics.js      # Physics utility functions
```

## Getting Started

1. **Open the game**: Simply open `index.html` in a modern web browser
2. **Start playing**: The game will automatically initialize and start
3. **Use controls**:
   - **Space**: Pause/Resume
   - **D**: Toggle debug mode with visual overlays
   - **R**: Reset game
   - **Debug Mode Button**: Open comprehensive debug panel
   - **Mouse wheel**: Zoom in/out
   - **F11**: Toggle fullscreen

## Controls Reference

### Keyboard Controls
- `SPACE` - Pause/Resume game
- `D` - Toggle debug information display
- `R` - Reset game to initial state
- `F11` - Toggle fullscreen mode

### Mouse Controls
- `Mouse Wheel` - Zoom camera in/out
- `Click buttons` - Use UI controls for game management

### UI Controls
- **Play/Pause** - Start/stop game simulation
- **Speed Control** - Adjust game speed (0.5x, 1x, 2x, 4x)
- **Reset Game** - Return to initial game state
- **Debug Mode** - Open comprehensive debug panel for game inspection

## Debug System

The hockey engine includes a comprehensive debug system for inspecting game state and player behavior:

### Debug Panel Features
- **Real-time Game State**: Live monitoring of period, time, score, and game status
- **Player State Inspection**: Click any player to view detailed attributes, AI decisions, and physics data
- **Puck Tracking**: Complete puck state including position, velocity, and ownership
- **Interactive Selection**: Click players in the panel or directly on the canvas for detailed inspection

### Visual Debug Overlays
When debug mode is active (`D` key):
- **Velocity Vectors**: Red arrows showing player movement direction and speed
- **Target Lines**: Green dashed lines indicating where players are trying to move
- **AI Targets**: Yellow dotted lines showing AI decision targets
- **Energy Bars**: Visual indicators of player energy levels
- **Selected Player Visualization**: Bright cyan lines showing target destination with crosshair markers

### Console Debug Functions
Access programmatic debugging via the global `debugHelpers` object:
```javascript
debugHelpers.getPlayers()        // All player objects
debugHelpers.getHomeTeam()       // Home team players only
debugHelpers.getAwayTeam()       // Away team players only
debugHelpers.getPlayer(id)       // Specific player by ID
debugHelpers.getPuck()           // Puck object with full state
debugHelpers.getPuckCarrier()    // Player currently with puck
debugHelpers.exportGameState()   // Complete game state export
```

This debug system is essential for:
- **AI Development**: Understanding player decision-making and behavior patterns
- **Performance Analysis**: Monitoring physics calculations and render performance
- **Game Balance**: Analyzing player attributes and gameplay mechanics
- **Bug Investigation**: Detailed state inspection for troubleshooting issues

## Game Mechanics

### Player AI
Each player has sophisticated AI that includes:
- **Role-based behavior** (forwards vs defensemen vs goalie)
- **Formation positioning** based on game situation
- **Puck awareness** and decision making
- **Teammate cooperation** for passing and positioning
- **Opponent pressure** and defensive reactions

### Physics System
- **Realistic puck physics** with momentum and friction
- **Player collision detection** and response
- **Board bouncing** with energy conservation
- **Goalie save mechanics** based on skill attributes

### Hockey Rules
- **Offside detection** when players cross lines ahead of puck
- **Icing calls** for long shots across multiple zones
- **Penalty system** for infractions like checking and interference
- **Power play situations** with player advantages
- **Faceoff mechanics** at center ice and zone dots

## Technical Details

### Performance
- Optimized 60 FPS rendering
- Efficient collision detection
- Smooth camera interpolation
- Responsive UI updates

### Browser Compatibility
- Modern browsers with HTML5 Canvas support
- Chrome, Firefox, Safari, Edge
- Mobile browsers (with touch controls)

### Customization
The engine is highly modular and can be extended with:
- Custom player attributes and skills
- Different team formations and strategies
- Additional hockey rules and penalties
- Enhanced visual effects and animations
- Sound effects and music integration

## Development

The codebase is organized into clean, modular components:
- **Entity-Component system** for game objects
- **Event-driven communication** between systems
- **Separation of concerns** (rendering, physics, AI, rules)
- **Utility libraries** for common operations

## Future Enhancements

Potential improvements include:
- **Sound system** with hockey arena audio
- **Advanced AI** with machine learning behaviors
- **Multiplayer support** for online matches
- **Tournament mode** with brackets and playoffs
- **Player statistics** tracking across multiple games
- **Save/load functionality** for game states

---

*This 2D hockey match engine provides a complete foundation for hockey management games, featuring realistic gameplay mechanics and professional-quality code architecture.*