# Bots de ejemplo

> Cuatro ejemplos de menor a mayor complejidad; todos se ejecutan tal cual y cada bloque de lógica corresponde a una capacidad del SDK. Además, un cerebro de referencia completo.

Fuente: https://war3ai.com/es/docs/examples/

Los ejemplos están en `brains/examples/`; cada uno hereda del anterior y solo añade lo nuevo. Te recomendamos leerlos en orden:

| Ejemplo | Qué aprendes | Cómo ejecutarlo |
|---|---|---|
| `hello_bot.py` | Recolección (5 por mina; con la mina llena, a talar), entrenar trabajadores (solo 1 en cola), construir edificios de comida, retomar cimientos abandonados; funciona con las cuatro razas | `python tools/play.py --bot brains/examples/hello_bot.py` |
| `rush_bot.py` | Cuartel y altar (si faltan, se construyen con `build_near`), el héroe primero (si muere, se revive), aprender habilidades cuando hay puntos, reunir una oleada y avanzar atacando | `… --bot brains/examples/rush_bot.py` |
| `macro_bot.py` | Orden de construcción + volver a la mina al terminar (Shift), cubrir la comida en cuanto se bloquea, 1 en la cola del cuartel, mejoras de ataque y armadura, subir de tier y tropas avanzadas, elegir objetivo por **distancia real por tierra** y seguir la ruta | `… --bot brains/examples/macro_bot.py --speed 200` |
| `micro_bot.py` | Sobre la macro, toma el control del combate: concentrar fuego en lo que antes muere, retirar heridos, salvar al héroe, elegir de noche campamentos de creeps asumibles, volver a defender si el enemigo llega a la base; los comandos de un tick van en un solo lote | `… --bot brains/examples/micro_bot.py --fair` |

> **Nota**
>
> Los comentarios de `hello_bot` y `rush_bot` recogen trampas encontradas en partidas reales, como "elegía siempre al primer trabajador para construir y las 3 granjas se quedaron en cimientos a medias" o "las coordenadas fijas del cuartel caían justo en un bosque y en 3 minutos no se construyó ninguno". Leer los comentarios enseña más que leer el código.

## hello_bot: economía

```python
# raza -> (trabajador, ayuntamientos, edificio de comida)
RACES = {
    "h": ("hpea", {"htow", "hkee", "hcas"}, "hhou"),
    "o": ("opeo", {"ogre", "ostr", "ofrt"}, "otrb"),
    "u": ("uaco", {"unpl", "unp1", "unp2"}, "uzig"),
    "e": ("ewsp", {"etol", "etoa", "etoe"}, "emow"),
}
MINE_CAP = 5            # como máximo 5 trabajadores por mina (más no aumenta los ingresos)
LUMBER_CREW = 5         # leñadores: 5 al oro por mina + estos a la madera = objetivo de trabajadores
```

Tres cosas: los trabajadores ociosos van al oro (el Bot lleva su propia cuenta de cuántos hay en cada mina y, si está llena, los manda a talar); si faltan trabajadores, entrena más (solo 1 en la cola); cuando la comida está casi al límite, busca un trabajador que no esté construyendo y levanta un edificio de comida junto al ayuntamiento (con Humanos y Orcos, además, manda a alguien a terminar los cimientos abandonados).

## rush_bot: tropas y ataque

Sobre `hello_bot` añade tres cosas: si no hay cuartel ni altar, los construye; el altar saca un héroe (**si muere, primero se revive**: el héroe es único) y aprende habilidades cuando tiene puntos; al reunir 8 unidades, todas avanzan atacando hacia el ayuntamiento enemigo y, si quedan muy dañadas, vuelven a casa para reagruparse. Solo da órdenes a las unidades ociosas, para no interrumpir el combate tick tras tick.

## macro_bot: fundamentos de macro

```python
TECH = {
    "h": dict(order=["halt", "hbar", "hbla", "hlum"], altar="halt", hero="Hamg", skills=["AHwe", "AHbz", "AHab"],
              barracks="hbar", soldiers=["hfoo", "hrif", "hkni"], smith="hbla", upgrades=["Rhme", "Rhar", "Rhra", "Rhla"],
              tiers=["hkee", "hcas"]),
    ...
}
```

Lo que un jugador profesional hace en cada partida, cada punto ligado a una capacidad del SDK: tabla de orden de construcción + `gather(..., queue="after")` para volver a la mina al terminar; `production().blocked` para detectar el bloqueo por comida; `g.queue` para que el cuartel tenga solo 1 en cola; `can_do` para preguntar al motor si se puede investigar el siguiente nivel de ataque o armadura; subir de tier y tropas avanzadas (lección de una partida real: se quedó en tier 1 y a los 23 minutos lo arrasaron los caballeros y jinetes de grifo de un rival en tier 3); elegir objetivo con `path_distance` y seguir los puntos de giro con `path()`.

## micro_bot: cuando empieza la pelea

```python
def _fight(self, g, army, foes, home, now):
    ...
    visible = [e for e in foes if e.visible_to(me)]              # los objetivos no visibles se rechazan (1001)
    atk = [s for s in (g.stats(u) for u in fighters) if s]
    target = min(visible, key=lambda e: _ttk(g, atk, e))         # el que antes muere, no el más cercano
    idle_or_other = [u for u in fighters if g.current_target(u) is None
                     or g.current_target(u).handle != target.handle]
    if idle_or_other:
        g.attack(idle_or_other, target)
```

En partida real: 5 minutos, 1497 ticks, 3023 comandos, 0 errores.

## Cerebro de referencia: una IA completa

`brains/xwar3/` es una IA completa que expande, hace creeping y ataca, organizada en tres capas:

| Capa | Ubicación | Ritmo | Qué hace |
|---|---|---|---|
| Capa de estrategia | `strategy/` | Segundos | Selección y cambio entre varias estrategias al estilo AMAI, tablas de construcción, tropas de counter, elección de héroes; [asesor de estrategia LLM](https://war3ai.com/es/docs/llm-coach/) opcional |
| Capa de reflejos | `reflex/` (4 procesos independientes) | Del orden de 100 ms | Protección, hechizos, concentrar fuego, recoger objetos |
| Modelo de victoria | `worldmodel/` | — | ¿Se puede ganar este combate? (subconjunto de inferencia) |

Varios procesos comparten las unidades mediante una **tabla de reclamación**, y la prioridad decide quién manda: control manual 95 > protección 90 > esquivar habilidades 85 > hechizos 80 > recoger objetos 70 > … > estrategia 50 > asignación de trabajadores 45. Tu propio Bot figura en la tabla como `bot`, con prioridad 50 por defecto.

> **Atención**
>
> El cerebro de referencia usa directamente la capa baja del SDK (`w3cmd` / `act`) y depende mucho de la información de todo el mapa. Sirve como referencia de "ideas", pero no conviene que un LLM lo copie tal cual. Necesita los datos de AMAI: la primera vez que `start.bat` despliega el entorno, los descarga del repositorio público de AMAI y los genera (AMAI tiene una licencia propia; lo generado no entra en git; si falla, reinténtalo con `start.bat setup`).

La forma más sencilla de arrancar el cerebro de referencia es la [consola Farsight](https://war3ai.com/es/docs/console/): en la página "Instancias y partida", marca el número de instancia y pulsa "Iniciar prueba".