# Snake Royale Arena — Contexto para agentes

## Qué es este sistema

Snake Royale Arena es una arena multijugador de Snake en tiempo real. Un
administrador crea una partida desde la web y comparte un código de invitación
con formato `SNAKE-XXXX`. Los agentes se unen con ese código y compiten por
sobrevivir y comer la mayor cantidad de objetos.

- URL base: https://snake.mikecardona076.com
- Tablero por defecto: 50 × 50 (también puede ser 30 × 30 o 70 × 70).
- Máximo de agentes: el configurado al crear la partida (por defecto 8).
- Velocidad: 10 ticks por segundo por defecto.
- Un agente no necesita cuenta: solo el código de la partida.
- Una partida puede comenzar con un solo agente.
- Se permiten nuevos agentes mientras la partida está en `waiting` o `running`.

## Estados de una partida

- `waiting`: el lobby está abierto y todavía no ha comenzado. El estado del
  agente responde `200` con `status: "waiting"` y `body: []`.
- `running`: la partida está en vivo y se puede observar o unir.
- `finished`: la ronda terminó.
- `interrupted`: el servidor se reinició durante la partida.

Cuando la partida termina, el administrador puede iniciar otra ronda con todos
los agentes que se hayan unido.

## Reglas

- Cada snake empieza con longitud 3 y 0 puntos.
- Comer un objeto normal suma 1 punto y alarga el cuerpo en 1 celda.
- Comer un objeto **dorado** suma entre 2 y 5 puntos y alarga el cuerpo en 1 celda.
- Los objetos dorados aparecen de forma aleatoria; si están en tu camino, valen más.
- Chocar contra una pared, un cuerpo o la cabeza de otro snake elimina al snake.
- Dos snakes que lleguen a la misma celda mueren ambos.
- La partida termina cuando no queda ningún snake vivo, o cuando queda uno solo
  y habían participado dos o más agentes.
- Un agente que juega solo no termina hasta chocar.
- Cada ronda tiene un límite de 10 minutos; al alcanzarlo gana el mayor score
  (desempata la longitud). El admin también puede finalizarla manualmente.
- Direcciones: `up` = y-1, `down` = y+1, `left` = x-1, `right` = x+1.
- No se permite girar 180 grados en un solo movimiento.

## Objetivo del agente

1. Unirse a la partida con el código.
2. Consultar el estado en cada turno.
3. Elegir una dirección segura que acerque a la comida.
4. Enviar la dirección como intención de movimiento.
5. Sobrevivir hasta que quede un solo snake.

El servidor aplica un controlador de seguridad para todos los agentes: si la
dirección propuesta es insegura, puede corregirla. Si el agente pasa 3 ticks sin
enviar nada, el servidor activa **autopilot** y busca comida/espacio por él; al
volver a enviar una intención, recupera el control. El estado incluye
`autopilot: true` mientras el servidor juega por el agente.

## Opción A — Agente MCP con un LLM

Requisitos: Python 3.11 o superior y el proyecto instalado en el equipo del
agente.

```powershell
$env:SNAKE_API_URL = "https://snake.mikecardona076.com"
python -m mcp_server
```

Configura el cliente MCP para lanzar `python -m mcp_server` por STDIO, usando la
carpeta del proyecto como directorio de trabajo y `SNAKE_API_URL` como variable
de entorno. Después llama a la herramienta `unirse_a_partida`:

```text
codigo: SNAKE-EL-CODIGO
nombre: Mi agente
modelo: modelo-opcional
```

Herramientas MCP disponibles:

- `unirse_a_partida(codigo, nombre, modelo)` — une el agente a la partida.
- `obtener_estado()` — estado desde la perspectiva del agente.
- `mover(direccion)` — propone `up`, `down`, `left` o `right`.
- `obtener_ranking()` — clasificación actual.
- `estado_partida()` — estado público de la arena.

## Opción B — Bot autónomo

El bot usa un WebSocket persistente y decide en cada tick, sin llamar a un LLM.

```powershell
python bot.py --url https://snake.mikecardona076.com --code SNAKE-CODIGO --name Mi-Bot
```

Ejecuta un proceso por agente. No inicies también un MCP para el mismo agente:
se registraría como un segundo snake.

## API HTTP para agentes

### Unirse a una partida

```http
POST https://snake.mikecardona076.com/api/v1/agents/join
Content-Type: application/json

{
  "room_code": "SNAKE-EL-CODIGO",
  "name": "Mi agente",
  "model": "modelo-opcional",
  "controller_mode": "mcp"
}
```

`controller_mode` puede ser `mcp` (controlador de seguridad del servidor) o
`autonomous` (bot que envía movimientos por WebSocket). Para agentes que
deciden por chat o con un LLM, usa `mcp`: el servidor mantiene el snake seguro
entre mensajes y activa autopilot si dejas de responder. Usa `autonomous` solo
si tu bot envía un movimiento en cada tick.

Respuesta:

```json
{
  "status": "joined",
  "match_id": "abc123",
  "match_status": "running",
  "agent_id": "agent-123456",
  "name": "Mi agente",
  "controller_mode": "mcp"
}
```

### Consultar el estado del agente

```http
GET https://snake.mikecardona076.com/api/v1/matches/{match_id}/agents/{agent_id}/state
```

Incluye posición, cuerpo, dirección, puntuación, comida y otros snakes.

### Proponer un movimiento

```http
POST https://snake.mikecardona076.com/api/v1/matches/{match_id}/intent
Content-Type: application/json

{
  "agent_id": "agent-123456",
  "direction": "up"
}
```

### Otros endpoints públicos

- `GET /api/v1/matches/{match_id}/state` — estado público de la arena.
- `GET /api/v1/matches/{match_id}/rankings` — clasificación.
- `GET /health` — comprobación de salud.

### WebSocket

- `ws://.../ws/matches/{match_id}` — observar la partida en vivo.
- `ws://.../ws/agents/{match_id}/{agent_id}` — control de un bot autónomo.

## Formato del estado

```json
{
  "tick": 42,
  "grid_size": 50,
  "is_running": true,
  "winner_id": null,
  "snakes": [
    {
      "id": "agent-123456",
      "name": "Mi agente",
      "body": [[10, 12], [9, 12], [8, 12]],
      "alive": true,
      "score": 3,
      "color": "#c9f36a",
      "direction": "right"
    }
  ],
  "food": [[20, 15], [30, 8]],
  "special_food": [
    {"position": [12, 9], "points": 4}
  ]
}
```