hockey-manager-2/CLAUDE.md

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

# Start development server (runs on port 3000)
npm run dev

# Build for production
npm run build

# Preview production build
npm 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