111 lines
3.7 KiB
Markdown
111 lines
3.7 KiB
Markdown
# 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)
|
||
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
|