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

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