Escreva um Bot com um LLM

Serve para quem joga Warcraft mas não programa, e também para desenvolvedores que querem ganhar tempo. O processo todo é uma conversa: você descreve a estratégia → o modelo escreve o código → você joga uma partida → conta ao modelo o que aconteceu → ele ajusta.

1. Prepare o material para o modelo

A qualidade do código que o modelo escreve depende, em grande parte, de ele ter lido o material certo. Escolha a opção que combina com a sua ferramenta:

O que você usa	Como entregar o material
Um agente de programação que lê o repositório (Claude Code, Cursor, Codex etc.)	Abra-o no diretório do repositório e peça que leia primeiro docs/BOT_HANDBOOK_ZH.md, docs/api.json e um exemplo (brains/examples/macro_bot.py para economia, micro_bot.py para combate)
Um modelo de chat com acesso à web	Peça que leia primeiro https://war3ai.com/llms-full.txt — toda a documentação do site está nesse único arquivo
Chat na web sem acesso à internet	Cole o manual, o api.json e um arquivo de exemplo depois do seu prompt
Um modelo local (LM Studio, Ollama)	Igual ao anterior. Recomenda-se uma janela de contexto de 32K tokens ou mais; caso contrário, o manual e a referência da API não cabem

Se você quer uma técnica profissional específica, cole também a receita correspondente das Receitas de jogadas profissionais.

2. Copie este prompt

Troque “A estratégia que eu quero”, no final, pelas suas próprias palavras — quanto mais específico, melhor:

Você vai escrever uma IA (em Python) para Warcraft III 1.27. Use apenas os métodos de Game listados em api.json;
não invente métodos que não existem. Siga o estilo de rush_bot.py: herde de openwar3.Bot e implemente on_start(g) e on_tick(g).

Regras:
- on_tick é chamado cerca de 5 vezes por segundo e precisa ser rápido (não use sleep dentro dele).
- Valores que não puderam ser lidos são None, não 0 — verifique antes de usar.
- Comandos retornam um recibo (Receipt); `if r:` significa "o engine aceitou"; quando não foi aceito, `r.reason` diz o motivo
  (falta comida, falta ouro, alvo não visível, você já tem este herói…) — tente de novo no próximo tick ou mude de abordagem.
- Para atacar um inimigo específico, use g.attack(unidades, inimigo); o inimigo precisa estar no campo de visão — os que você não vê são rejeitados.
- Um herói morto precisa ser revivido com g.revive(altar); não dá para treinar outro.
- Para construir, use g.build_near(trabalhador, código_da_construção, x, y): ele encontra um lugar que caiba, acompanha o resultado e não faz nada quando falta dinheiro.
- Para saber "o que acabou de acontecer" (quem morreu, quem levou dano, herói subiu de nível, item caiu), implemente on_event(g, ev).
- Não repita o mesmo comando para a mesma unidade a cada tick (isso interrompe o que ela está fazendo); dê ordens às unidades "ociosas".
- Só mande para a coleta trabalhadores de idle_workers(). No máximo 5 trabalhadores por mina de ouro.
- Coloque só 1 unidade por vez na fila de treino (enfileire a próxima quando g.queue(construção) estiver vazia); para saber se travou por comida, veja g.production(construção).blocked.
- Quando um tick envia muitos comandos, coloque-os dentro de with g.batch(): (espera a thread do jogo uma única vez).
- Para escolher quem atacar, use g.time_to_kill(meu_grupo, inimigo) (considera vantagens de tipo e armadura); para escolher aonde ir, use g.path_distance (retorna None se não houver caminho).
- No modo justo você só vê o que está no campo de visão; para inimigos que você viu antes, use g.last_seen().
- Unidades são códigos de quatro caracteres (Camponês humano hpea, Soldado hfoo, Quartel hbar…), magias são strings de ordem (thunderbolt Storm Bolt,
  blizzard Nevasca, holybolt Luz Sagrada…, tabela completa em data/order-ids.txt), e aprender habilidades usa códigos de quatro caracteres (AHtb, AHbz…).

A estratégia que eu quero:
<Escreva aqui em linguagem simples, por exemplo:
  "Humanos. No início, 5 camponeses no ouro e 1 na madeira; Arquimago primeiro; dois Quartéis fazendo Soldados e Fuzileiros;
   quando tiver 12 unidades, leve o herói e ataque a expansão inimiga; volte para casa quando o herói ficar abaixo de 30% de vida;
   ao creepar, priorize os acampamentos mais perto de casa.">

Como descrever sua estratégia com clareza

O que os modelos mais têm dificuldade é com pedidos vagos. Em vez de “jogue de forma mais agressiva”, estas informações são muito mais úteis:

• Raça e heróis: qual herói primeiro e a ordem de habilidades (por exemplo, Arquimago: Elemental da Água, Nevasca, Elemental da Água…).
• Ordem de construção: com quantos camponeses construir o Quartel, quando subir de tier, quantos Quartéis.
• Composição do exército: Soldados + Fuzileiros? Com quantas unidades sair para atacar?
• Condições de ataque e recuo: quantas unidades antes de atacar, com quanto de vida o herói recua, voltar para casa e reconstruir depois de perdas pesadas.
• Creeping: creepar ou não, quando (depois de anoitecer?), só acampamentos que você consegue vencer?
• Justo ou não: se você pretende entrar na Arena depois, diga “use só inimigos visíveis no campo de visão”.

3. Rode

Salve o código do modelo como brains/my_bot.py e então:

python tools/play.py --bot brains/my_bot.py --race 1 --difficulty 2

Para ver os resultados mais rápido, adicione --speed 200 (velocidade 2×).

4. Peça ajustes

• Deu erro: cole o erro inteiro, exatamente como apareceu, de volta para o modelo e diga “corrija isso”.
• Joga mal: descreva o que você viu no jogo, não a causa que você imagina. Por exemplo: “o herói fica parado em casa”, “as unidades chegam uma de cada vez”, “os camponeses se amontoam em uma mina só”.
• Quer adicionar uma tática nova: adicione uma coisa de cada vez, jogue uma partida para confirmar que nada quebrou e só então adicione a próxima.

5. Problemas comuns

Sintoma	Causa mais provável
Nada se mexe	Número de instância errado (--inst), ou a partida ainda não começou
Camponeses não mineram	Ordens foram dadas a camponeses que já estavam trabalhando; só designe a partir de idle_workers()
As casas nunca são construídas	Use build_near em vez de coordenadas fixas; veja se o reason do recibo diz que falta dinheiro
O herói nunca sai	Veja o recibo do train: falta comida? Ou o herói morreu (use revive)?
O herói não lança magias	A habilidade não foi aprendida (learn) ou falta mana; depois de lançar, veja se cooldown() mostra a recarga
Unidades se contorcem tick após tick	Os comandos estão sendo repetidos a cada tick; só dê ordens às unidades ociosas
Nenhuma unidade sai e o ouro só aumenta	Travou por comida: veja g.production(quartel).blocked
O modelo usou métodos que não existem	Reforce no prompt “use só métodos que estão em api.json” e cole o api.json completo

Indo além

• Todas as APIs e o mecanismo por trás de cada uma: referência da API;
• O cérebro de referência (brains/xwar3/strategy) é uma IA completa que expande, creepa e ataca. Você pode pedir ao modelo que leia o código para tirar ideias, mas ele usa APIs de nível mais baixo, então não é recomendável copiá-lo diretamente;
• Quando você entrar na Arena, só vai conseguir ver inimigos no campo de visão — adicione --fair desde já para se impor essa regra, e não vai precisar mudar nada depois.