football/docs/specs/2026-05-09-players-ai-design.md

Design: Players & AI Behavior (M3)

Goal

Implement autonomous players with role-based and zone-based AI that move realistically and maintain tactical positions without user input.

Architecture

The system separates player data from behavior logic.

1. Components

• Player Entity: A data structure containing physical properties (position, velocity, radius), team identity (Red/Blue), role (Striker/Defender), and movement constraints (MaxSpeed, Acceleration).
• PlayerAI Logic: A set of rules that determine the "Target Point" based on the puck's position and the player's role.
• World Integration: The world manages a collection of players, updates their AI state, applies steering physics, and handles boundary clamping.

Detailed Design

1. Player Roles & Behavior

Players operate based on a hybrid of roles and zones.

Defender

• Home Zone: Their own half of the field.
• Behavior:
  • Puck in opponent's half: Return to HomePosition (positioned in front of their own goal).
  • Puck in their half: Move to a point on the line between the Puck and Their Goal to block the path.

Striker

• Home Zone: Center of the field and opponent's half.
• Behavior:
  • Puck in their zone: Actively chase the Puck.
  • Puck deep in their own half: Maintain a position near the center or between the center and the opponent's goal, avoiding overcrowding the defender's zone.

2. Movement Physics (Steering)

To avoid "robotic" movement, players use a steering-like approach:

1. Target Point: AI determines where the player wants to be.
2. Desired Velocity: A vector from current position to target, normalized and scaled by MaxSpeed.
3. Acceleration: The difference between Desired Velocity and Current Velocity is applied as a force, capped by the Acceleration parameter.
4. Integration: Position += Velocity.

3. File Structure

• internal/entities/player.go: Defines Team, Role, and Player struct.
• internal/game/world.go:
  • Adds Players []*Player to World.
  • Defines goal coordinates (GoalLeft, GoalRight).
  • Implements updatePlayersAI() and integrates it into World.Update.
• internal/game/world_test.go: Tests for AI target selection and movement.

4. Edge Cases & Polish

• Anti-Clumping: Small repulsive force between teammates to prevent them from overlapping perfectly.
• Dead Zone: A small radius around the target point where the player stops moving to prevent jittering.
• Boundary Clamping: Players are clamped to the field boundaries to prevent them from leaving the screen.

Success Criteria

• Players are rendered on screen with distinct colors.
• Defenders stay back when the puck is far and block the goal when it's near.
• Strikers chase the puck but don't crowd their own defenders.
• Movement is smooth (accelerating/decelerating) rather than instant.