feat: initial commit with M1-M4 implementation

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

@@ -0,0 +1,55 @@
+# 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.