# Bots de exemplo

> Quatro exemplos, do mais simples ao mais completo. Todos rodam direto, e cada trecho de lógica corresponde a um recurso do SDK. Há também um cérebro de referência completo.

Fonte: https://war3ai.com/pt/docs/examples/

Os exemplos ficam em `brains/examples/`; cada um herda do anterior e só acrescenta o que é novo. Leia na ordem:

| Exemplo | O que ensina | Como rodar |
|---|---|---|
| `hello_bot.py` | Coleta (5 por mina; mina cheia, vai cortar madeira), treinar camponeses (só 1 na fila), erguer construções de comida, retomar fundações paradas; funciona com as quatro raças | `python tools/play.py --bot brains/examples/hello_bot.py` |
| `rush_bot.py` | Quartel e altar (se não houver, constrói com `build_near`), herói primeiro (se morrer, revive), aprender habilidades quando houver pontos, juntar uma leva e atacar-mover | `… --bot brains/examples/rush_bot.py` |
| `macro_bot.py` | Ordem de construção + voltar sozinho à mina ao terminar (Shift), repor comida assim que travar, fila do quartel com 1, melhorias de ataque/armadura, subir de tier e tropas avançadas, escolher o alvo pela **distância real por terra** e seguir o caminho | `… --bot brains/examples/macro_bot.py --speed 200` |
| `micro_bot.py` | Assume o combate por cima da macro: focar no alvo que morre mais rápido, recuar unidades feridas, proteger o herói, à noite escolher acampamentos de creeps que dá para vencer, voltar para defender quando o inimigo chega à base; os comandos de um tick saem em um lote | `… --bot brains/examples/micro_bot.py --fair` |

> **Nota**
>
> Os comentários de `hello_bot` e `rush_bot` registram armadilhas encontradas em partidas reais, como “sempre escolhia o primeiro trabalhador para construir, e as 3 fazendas ficaram todas como fundações pela metade” e “a coordenada fixa do quartel caía bem numa floresta; em 3 minutos, nenhum foi construído”. Ler os comentários rende mais do que ler o código.

## hello_bot: economia

```python
# raça -> (trabalhador, edifícios principais, construção 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            # no máximo 5 camponeses por mina (mais que isso não aumenta a renda)
LUMBER_CREW = 5         # quantos cortam madeira: 5 no ouro por mina + estes = meta de trabalhadores
```

Três tarefas: trabalhadores ociosos vão coletar ouro (o Bot conta quantos há em cada mina; mina cheia, eles vão cortar madeira); se faltar trabalhador, treina mais (só 1 na fila); quando a comida está perto do limite, escolhe um trabalhador que não esteja construindo e ergue uma construção de comida ao lado do edifício principal (Humanos e Orcs também mandam alguém retomar fundações paradas).

## rush_bot: tropas e ataque

Sobre o `hello_bot`, acrescenta três coisas: construir quartel e altar se não houver; o altar treina o herói (**se ele morrer, reviva primeiro** — o herói é único) e aprende habilidades quando houver pontos; ao juntar 8 soldados, todos atacam-movem até o edifício principal inimigo e, se forem dizimados, voltam para casa e juntam de novo. Só dá ordens a soldados ociosos, para não interromper o combate tick após 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"]),
    ...
}
```

O que um jogador profissional faz em toda partida, cada item ligado a um recurso do SDK: tabela de ordem de construção + `gather(..., queue="after")` para voltar à mina ao terminar; `production().blocked` para perceber que a comida travou; `g.queue` para garantir só 1 na fila do quartel; `can_do` para perguntar ao motor se já dá para pesquisar o próximo nível de ataque/armadura; subir de tier e tropas avançadas (lição de partida real: ficou parado no tier 1 e, aos 23 minutos, foi arrasado por cavaleiros e grifos de tier 3); escolher alvos por `path_distance` e seguir os pontos de virada com `path()`.

## micro_bot: depois que a luta começa

```python
def _fight(self, g, army, foes, home, now):
    ...
    visible = [e for e in foes if e.visible_to(me)]              # alvos que não estão visíveis são rejeitados (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))         # o que morre mais rápido, não o mais próximo
    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)
```

Em partida real: 5 minutos, 1497 ticks, 3023 comandos, 0 erros.

## Cérebro de referência: uma IA completa

`brains/xwar3/` é uma IA completa, que expande, creepa e ataca, organizada em três camadas:

| Camada | Local | Ritmo | O que faz |
|---|---|---|---|
| Camada de estratégia | `strategy/` | Segundos | Escolha e troca entre várias estratégias no estilo AMAI, tabelas de construção, tropas de counter, escolha de heróis; [conselheiro de estratégia com LLM](https://war3ai.com/pt/docs/llm-coach/) opcional |
| Camada reflexa | `reflex/` (4 processos independentes) | Na casa dos 100 ms | Proteger unidades, lançar feitiços, focar fogo, pegar itens |
| Modelo de vitória | `worldmodel/` | — | Dá para vencer esta luta? (subconjunto de inferência) |

Os processos compartilham unidades por meio da **tabela de reivindicações**, que decide pela prioridade quem manda: humano 95 > proteção 90 > desviar de habilidades 85 > lançar feitiços 80 > pegar itens 70 > … > estratégia 50 > distribuir trabalhadores 45. O seu Bot aparece na tabela como `bot`, com prioridade padrão 50.

> **Atenção**
>
> O cérebro de referência usa diretamente a camada baixa do SDK (`w3cmd` / `act`) e depende muito de informação do mapa inteiro. Ele serve como referência de “ideias”, mas não recomendamos que um LLM o copie diretamente. Ele precisa dos dados do AMAI: na primeira instalação, o `start.bat` baixa do repositório público do AMAI e gera esses dados (o AMAI tem licença própria; os arquivos gerados não entram no git; se não der certo, rode `start.bat setup` para tentar de novo).

A forma mais simples de iniciar o cérebro de referência é pelo [console Farsight](https://war3ai.com/pt/docs/console/): na página “Instâncias e partidas”, marque o número da instância e clique em “Iniciar teste”.