# CLAUDE.md

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

## Project Overview

A hockey match engine simulation built with PhaserJS and TypeScript. The engine uses continuous positioning (exact X/Y coordinates on a 2D rink) combined with behavior trees for AI decision-making to create a realistic hockey match simulation.

**Core Concept**: Players have exact positions on a 60x30m international hockey rink, with AI running behavior trees at 60 FPS to make tactical decisions (passing, shooting, positioning, etc.).

## Development Commands

```bash
# Start development server (runs on port 3000)
pnpm run dev

# Build for production
pnpm run build

# Preview production build
pnpm run preview
```

## Coordinate System

**Critical**: The rink uses a centered coordinate system:
- Origin (0, 0) = center of rink
- Rink dimensions: 60m length × 30m width
- Left goal: x = -26m, Right goal: x = +26m
- All positions use **meters as floats** (not integers)
- Screen rendering: 1 meter = 20 pixels (SCALE constant)

## Architecture

### Project Structure

```
src/
  config/
    constants.ts      # All game constants (rink dimensions, colors, speeds)
  game/
    main.ts          # Phaser game initialization and config
    GameScene.ts     # Main game scene (rendering, game loop)
    Goal.ts          # Goal structure with physics bodies
  entities/         # Player and Puck classes (planned)
  systems/          # BehaviorTree, PositioningSystem, PuckSystem (planned)
```

### Implementation Phases (from PLAN.md)

The project follows a phased approach:
1. **Phase 1** (✓): Environment setup, rink rendering
2. **Phase 2** (Next): Player entities (12 players: 10 skaters + 2 goalies) with smooth movement
3. **Phase 3**: Puck entity and possession mechanics
4. **Phase 4**: Behavior tree for puck carrier decisions (shoot/pass/carry)
5. **Phase 5**: Team offensive positioning system
6. **Phase 6**: Defensive behaviors and pressure mechanics
7. **Phase 7**: Goalie AI
8. **Phase 8**: Game flow (goals, faceoffs, scoring)
9. **Phase 9**: Polish and tuning

### Key Systems (Planned)

**Behavior Trees**: Decision-making engine that runs every tick
- Evaluates game state (possession, positions, threats)
- Weights actions by player attributes (Hockey IQ, Skill, Speed)
- Outputs: move, pass, shoot, or defensive actions

**Tactical Positioning**: Heat map-based positioning
- Different formations based on game situation (offense/defense)
- Players move toward ideal positions modified by:
  - Puck location
  - Teammate spacing
  - Opponent positions
  - Player stamina/speed

**Puck Movement**:
- Pass success = f(passer skill, distance, pressure, receiver skill)
- Shots use trajectory calculation with goalie save probability
- Smooth interpolation for visual feedback

## Technical Details

- **Framework**: Phaser 3.90.0 (with Arcade Physics)
- **TypeScript**: Strict mode enabled
- **Build Tool**: Vite 5.4
- **Target FPS**: 60 (constant in constants.ts)
- **Physics**: Arcade physics with zero gravity (top-down view)

## Configuration

All magic numbers and game constants are centralized in `src/config/constants.ts`:
- Rink dimensions and zone lines
- Goal dimensions
- Colors (ice, boards, lines)
- Scale factor (meters to pixels)
- Game settings (FPS)

Future constants will include:
- Player speeds, shot speeds, pass speeds
- AI decision probabilities
- Attribute ranges

## Development Notes

- **Incremental testing**: Test each phase thoroughly before proceeding
- **Debug visualization**: Add toggleable overlays for targets, zones, etc.
- **Tuning over precision**: Numbers are starting points; tune based on feel
- Refer to PLAN.md for detailed phase requirements and validation criteria
- Refer to NOTES.md for architectural decisions and design notes