football/docs/specs/2026-05-12-match-logic-design.md

Design: Match Logic & Game Rules (M5)

Goal: Implement a high-level match management system to handle scoring, game timing, and state transitions (Playing, Goal Pause, Match Ended).

Architecture: Introduction of a MatchManager component that acts as a controller over the World. The World remains responsible for physics and AI, while the MatchManager handles the "rules of the sport".

---

1. Components

MatchManager

The central authority for the match state.

• GameState: Playing, GoalPause, MatchEnded.
• Score: ScoreRed, ScoreBlue (integers).
• Match Timer: MatchDuration (total time) and CurrentTime (elapsed).
• Pause Timer: PauseDuration (fixed duration for goal celebration) and PauseTimer (countdown).
• Reference: Pointer to World.

World (Extensions)

• CheckGoal() (team entities.Team, scored bool): Checks if the puck has crossed the goal lines (X < 0 or X > WorldWidth).
• ResetPositions(): Resets the puck to the center and all players to their HomePosition, zeroing out all velocities.

---

2. File Structure

• internal/game/match_manager.go (New):
  • Definition of GameState and MatchManager struct.
  • Update() method to drive the match lifecycle.
• internal/game/world.go (Modified):
  • Implementation of CheckGoal() and ResetPositions().
• cmd/game/main.go (Modified):
  • Replace World with MatchManager in the Game struct.
  • Update Update() and Draw() calls to go through MatchManager.

---

3. Data Flow

Main Loop \rightarrow MatchManager

Game.Update() \rightarrow MatchManager.Update():

1. If Playing:
   • Call World.CheckGoal().
   • If goal \rightarrow transition to GoalPause, increment score, start PauseTimer.
   • If no goal \rightarrow call World.Update() (physics/AI) and increment CurrentTime.
   • If CurrentTime >= MatchDuration \rightarrow transition to MatchEnded.
2. If GoalPause:
   • Decrement PauseTimer.
   • If PauseTimer <= 0 \rightarrow call World.ResetPositions() and transition to Playing.
   • World.Update() is skipped (game is frozen).
3. If MatchEnded:
   • World.Update() is skipped.

World \rightarrow MatchManager (Goal Detection)

• X < 0 \rightarrow (TeamBlue, true)
• X > WorldWidth \rightarrow (TeamRed, true)
• Otherwise \rightarrow (_, false)

---

4. Edge Cases & Handling

• Double Scoring: The GoalPause state prevents CheckGoal from being called repeatedly until the world is reset.
• Reset Collisions: ResetPositions explicitly sets Velocity = 0 for all entities to prevent immediate "explosions" from anti-clumping logic.
• Boundary Stuck: CheckGoal is evaluated before physics clamping to ensure goals are registered even at high speeds.
• Last-second Goal: Goals are processed before the match timer check, ensuring a goal on the final frame is counted.

---

5. Success Criteria

• Puck crossing the boundary increments the correct team's score.
• The game freezes for a few seconds after a goal.
• All entities return to starting positions after the pause.
• The match stops automatically when the timer reaches the limit.