feat: initial commit with M1-M4 implementation

docs/specs/2026-05-08-hockey-design.md

@@ -0,0 +1,102 @@
+# Hockey Game Design Specification
+
+## 1. Game Overview
+A top-down autonomous hockey simulation where the user observes two teams playing. The game features 6v6 teams (1 goalie, 2 defenders, 3 forwards) plus 1 referee. The match duration is 10 minutes with goals, resets, and scoring.
+
+## 2. Technical Stack
+- **Language**: Go
+- **Graphics Engine**: Ebitengine (2D rendering)
+- **Physics**: Simple 2D collision detection and response
+- **AI**: Steering Behaviors combined with tactical zone management
+
+## 3. Game Rules & Setup
+- **Team Composition**: 6v6 (1 goalie, 2 defenders, 3 forwards) per team, plus 1 referee
+- **Match Duration**: 10 minutes
+- **Objective**: Score more goals than the opponent
+- **Reset**: After each goal, players and puck reset to starting positions
+- **Scoring**: Goals scored when puck enters opponent's goal area
+
+## 4. Architecture
+
+### 4.1 Simulation Engine
+- **World/Game State**: Manages all entities and game state
+- **Physics**: Handles collisions, bounces, and movement
+- **Game Timer**: Tracks match time and game state
+
+### 4.2 Entities
+- **Puck**: Position, velocity, friction
+- **Player**: Role, team, steering behavior
+- **Referee**: Follows puck with larger arrival radius
+
+### 4.3 AI System
+- **Zone Manager**: Defines defensive, middle, and attack zones
+- **Steering Logic**: Weighted sum of vectors (Seek, Separation, Arrival, Avoidance)
+- **Role-based Behaviors**: Specific AI for each player role
+
+### 4.4 Rendering
+- Ebitengine-based 2D rendering of the rink, players, and puck
+
+## 5. File Structure
+```
+cmd/game/main.go
+internal/game/engine.go
+internal/game/world.go
+internal/game/timer.go
+internal/entities/player.go
+internal/entities/puck.go
+internal/entities/referee.go
+internal/ai/steering.go
+internal/ai/zones.go
+internal/ai/brain.go
+internal/physics/collisions.go
+internal/render/renderer.go
+```
+
+## 6. Detailed Logic
+
+### 6.1 Game Loop
+1. AI Update
+2. Physics Update
+3. Game State Update (goals, timer)
+4. Render
+
+### 6.2 Steering Behaviors
+- **Seek**: Calculate vector towards target
+- **Separation**: Avoid nearby teammates
+- **Arrival**: Slow down as target is reached
+- **Avoidance**: Prevent sticking to boards
+- **Weighted Sum**: Combine behaviors with tactical zone weights
+
+### 6.3 Role-based AI
+
+#### Forwards
+- Aggressive Seek(Puck) in attack zone
+- Return to home zone if puck is far
+- Use Support behavior to create passing options
+
+#### Defenders
+- High Separation(Opponents)
+- Seek(Puck) in defense/middle zones
+- Use Support behavior to coordinate attacks and transitions
+
+#### Goalie
+- Restricted to goal area
+- Seek(Puck) primarily on X-axis
+- Maintain position in goal area
+
+#### Referee
+- Gentle Seek(Puck) to stay nearby
+- Larger arrival radius than players
+
+### 6.4 Puck Interaction
+- **Possession**: When within radius R
+- **Shooting**: Triggered by probability or position
+- **Passing**: A player with the puck can pass to a teammate if they are in a favorable position (closer to the opponent's goal and not heavily blocked). A pass is a high-velocity impulse towards the teammate.
+- **Control**: Radius-based capture and release
+- **Friction**: Gradual velocity reduction over time
+
+## 7. Physics
+- **Collisions**: Simple 2D elastic collisions (player-player, player-puck, puck-boards)
+- **Bounces**: Puck bounces off walls with energy loss
+- **Friction**: Puck gradually slows down over time
+- **Movement**: Velocity-based position updates