Seu modelo pensa, o War3AI executa
Para realizar tarefas sozinho num ambiente real, um agente precisa de três coisas — ações que possam ser descritas com clareza, feedback que ele consiga entender e um ambiente em que errar não custe caro. Transformamos o Warcraft III num ambiente assim.
Por que agentes conseguem fazer as coisas sozinhos aqui
A forma comum de pôr uma IA para jogar é simular mouse e teclado e reconhecer a tela — e aí só dá para adivinhar se deu certo. Fizemos o contrário e projetamos cada API a partir da pergunta “do que um modelo precisa para corrigir os próprios erros”.
Diga só “o que fazer”
Mover, atacar, construir, lançar feitiços… os comandos semânticos correspondem direto às ações do jogador; unidades por código de quatro caracteres, habilidades por nome de ordem, os mesmos nomes do jogo. O modelo não precisa de nenhum conhecimento de baixo nível.
Feedback estruturado para cada ação
O recibo é lido no mesmo frame — se foi aceito, código de motivo, ordem antes e depois, tempo de execução. “Por que não deu certo” é um número, não um palpite.
Resultados sem olhar a tela
O snapshot diz como está agora; o fluxo de eventos diz o que aconteceu — cada golpe de dano, cada abate, cada produção concluída. O agente pode verificar os próprios julgamentos.
A documentação é a API
O api.json é gerado a partir do código, e cada um dos 103 métodos traz status de teste e mecanismo interno; o llms.txt permite ler o site inteiro de uma vez. O modelo não tem motivo para inventar métodos.
Falhar é seguro
Se o Bot lançar uma exceção, o próximo tick continua; comandos que passaram do prazo não são executados; se o processo do Bot cair, o jogo continua normalmente. O agente pode experimentar sem medo.
Jogo limpo desde o primeiro dia
O modo justo só entrega o que está na visão, igual à regra da Arena. O que o agente aprende na sua máquina vai para a Arena sem mudar uma linha.
O agente escreve o Bot
A forma mais rápida de começar, sem precisar programar. Entregue o manual, o api.json e um exemplo ao Claude Code, Cursor, Codex ou qualquer modelo de chat e descreva a estratégia em linguagem comum. Ele escreve um arquivo Python que herda de openwar3.Bot, e um comando põe o Bot em campo.
- O modelo de prompt já traz as 15 “regras aprendidas em partidas reais”
- Exige que ele use só métodos do api.json, sem invenções
- Cole os erros como estão, descreva o que viu e peça a correção
Certo, vou seguir a estrutura do rush_bot.py e usar só métodos do api.json:
- Coleta só com
idle_workers(), 5 por mina - Fila do quartel com só 1; comida travada via
production().blocked - O ataque escolhe a expansão por
path_distancee vai comattack_move - Herói abaixo de 30% de vida volta com
move; se morrer,revive
Deixe o agente iterar sozinho
Um agente de programação que executa comandos pode assumir também o “jogar uma partida e ver o resultado”. Dê a ele um comando que roda sem supervisão, um relatório estruturado da partida e um objetivo claro, e ele melhora rodada após rodada.
- Rodar
play.py --speed 200 --minutes 10 --fair - Ler o relatório da partida — linha do tempo da produção, baixas, motivos de rejeição mais frequentes
- Alterar o ponto que mais afeta o resultado, com a justificativa num comentário
- Rodar de novo — se várias partidas seguidas não melhorarem, parar e reportar
{
"reason": "到时间了",
"clock": 612.4,
"timeline": [
[15, "training", "hpea"],
[118, "construction", "hbar"],
[161, "training", "Hamg"],
[402, "upgrade", "hkee"]
],
"lost": {"hfoo": 7, "Hamg": 1},
"killed": {"ogru": 4, "ngno": 6},
"rejects": [
["train hfoo: rejected（人口不够）", 41],
["attack ogru: rejected（目标看不见…）", 9]
]
}O motivo de rejeição mais frequente foi “comida insuficiente”, 41 vezes — o quartel ficou esperando comida o tempo todo. Pela regra 12, construir uma fazenda assim que production().blocked aparecer, em vez de esperar a comida chegar perto do limite. Nesta rodada, só isso muda.
LLM como coach de estratégia
“O que acumular, onde pôr os trabalhadores, atacar ou segurar neste minuto” — julgamentos globais de prioridade como esses, escritos como if / else, brigam entre si, mas são justamente o forte de um LLM. O cérebro de referência consulta um modelo local a cada 20 segundos de jogo e recebe um JSON estrito.
{
"diagnosis": "Ouro 820, madeira 60 — a madeira é o gargalo, o quartel parou por falta de madeira",
"workers": {"gold": 10, "lumber": 7},
"priority": ["hpea", "hhou", "hfoo"],
"posture": "hold",
"avoid": ["Não pesquise Iron Plating com pouca madeira"]
}Trabalhadores 10 / 7 · prioridade de treino hpea → hhou → hfoo · postura hold
Dar ordens, ler recibos, micro
Faça as unidades falarem
Balões sobre qualquer unidade, com qualquer identidade; várias unidades falando ao mesmo tempo, com o estilo de cada balão personalizável. Conecte um LLM local e cada frase que entra vira uma resposta em streaming sobre a unidade. Roda de conversa dos camponeses, diálogos entre heróis, narração da partida — tudo pronto.
POST http://127.0.0.1:8872/api/chat
{
"inst": 16, "unit": "0x14A12614", "name": "Rei da Montanha",
"persona": "Você é o Rei da Montanha, expansivo e bom de copo; uma ou duas frases coloquiais",
"message": "Tem um bando de ogros ali na frente. Vamos atacar?",
"stream": true
}
→ {"reply": "Avante! Só mais um gole e vamos!",
"first_token_ms": 283, "total_ms": 342}Companheiro de IA
Em mapas RPG e personalizados, arrume um parceiro de IA — ele segue você, ajuda a lutar, cura você quando sua vida está baixa e, nas horas paradas, puxa conversa; as falas podem vir de um LLM local. Herde uma classe, mude alguns atributos, e o companheiro é seu.
A cada tick, verifica nesta ordem e faz a primeira que se aplica
- Recuar com a própria vida baixa e inimigos por perto — vai para trás de você
- Curar com a sua vida baixa e a habilidade pronta — cura você
- Ajudar primeiro quem está atacando você, depois quem você está atacando
- Seguir se ficou longe demais, vai atrás; se ficou longe demais mesmo, volta correndo
- Conversar sem luta por perto, solta uma frase a cada um ou dois minutos
Digite -follow / -stay / -heal / -hi no chat, ou clique nele com o botão direito
O LLM usa as ferramentas diretamente
Clientes com suporte a MCP — Claude Code, Claude Desktop, frameworks de agentes para modelos locais — conectam o war3_mcp.py, e o LLM passa a ver a partida, dar comandos, falar com o jogador na tela, perguntar ao jogador com cartões e tirar capturas de tela diretamente. Sem escrever código antes; é só pedir o que vier à cabeça.
- 10 ferramentas: resumo da partida, unidades, eventos, chamar qualquer API pública, consultar a API, aviso na tela, fala sobre a unidade, perguntar ao jogador, captura de tela, JASS
- Três papéis: dev, jogador (comanda um só jogador e só enxerga a visão dele), observador (só leitura)
- A conexão com o jogo só acontece na primeira chamada de ferramenta, então o jogo pode ser aberto depois
Chamei 2 ferramentas:
war3_overview→ ouro 500 · comida 10/12 · edifício principal 1 · camponeses 5 · paladino 1war3_ask_player→ três cartões no meio da tela; o jogo fica pausado durante a escolha- Você clicou em “Expandir”, o resultado voltou para a conversa como está, e eu sigo organizando os camponeses
O agente entra em campo
A Arena usa WebSocket / JSON — a cada tick, o árbitro envia uma observação filtrada pela visão, e o Bot responde com um conjunto de ações. Qualquer linguagem, qualquer modelo — até sem código, com um LLM gerando JSON tick a tick — pode se conectar. A versão local já funciona hoje: o papel de jogador do gateway só deixa você comandar um jogador e só enxergar a visão dele; o que falta para a Arena é um árbitro em quem todos confiem.
- Ticks marcados pelo tempo de jogo; o lado lento sai perdendo, sem atrasar o outro
- Cada ação tem a propriedade das unidades verificada antes e é registrada para replay
- Bots escritos com o SDK entram em campo trocando
GameporArenaGame
{"t": "obs", "tick": 57, "gameMs": 11400, "me": 1,
"res": {"gold": 320, "lumber": 150, "food": [18, 30]},
"units": [
{"id": 101, "type": "hfoo", "owner": 1,
"x": -4500, "y": 2200, "hp": 380, "hpMax": 420}],
"visibleEnemies": [
{"id": 733, "type": "ogru", "owner": 2,
"x": -3900, "y": 2500, "hp": 700}],
"deadlineMs": 180}id é um identificador estável atribuído pelo árbitro, que não muda durante a partida. {"t": "act", "tick": 57, "actions": [
{"do": "attack", "unit": 101, "target": 733},
{"do": "train", "unit": 5, "code": "hfoo"},
{"do": "cast", "unit": 7, "spell": "thunderbolt", "target": 733},
{"do": "move", "unit": 102, "x": -5000, "y": 2000}]}category == "command" no api.json, com parâmetros de mesmo nome; um act atrasado conta como tick passado em branco. Entregue isto ao seu agente
Tudo é texto puro ou JSON, sem login e sem renderização — o agente só precisa baixar.
| O que você usa | Como conectar | Indicado para |
|---|---|---|
| Claude Code / Cursor / Codex e outros agentes de programação | Abra na pasta do repositório e peça para ler o manual, o api.json e os exemplos; ele pode rodar partidas, ler relatórios e iterar sozinho | Escrever Bots, iteração autônoma |
| Modelos de chat com acesso à internet | Peça para ler war3ai.com/pt/llms-full.txt primeiro | Escrever Bots |
| Modelos de chat sem acesso à internet | Cole o manual, o api.json e um exemplo no prompt | Escrever Bots |
| Modelos locais (LM Studio / Ollama) | API compatível com OpenAI; recomendamos modelos MoE com o raciocínio desligado | Conselheiro, falas (sensível à latência) |
| APIs na nuvem (Claude / GPT / Gemini / DeepSeek…) | Compatível com OpenAI ou o SDK de cada provedor; a camada de conselheiro é assíncrona, então alguns segundos de latência são aceitáveis | Conselheiro; no futuro, jogar direto |
| Clientes com suporte a MCP (Claude Code / Claude Desktop…) | Conecte o tools/war3_mcp.py: 10 ferramentas para ver a partida, dar comandos, perguntar ao jogador e tirar capturas de tela diretamente | Comandar durante a partida, jogar junto, narrar |
| Qualquer linguagem / navegador / outra máquina | Gateway WebSocket / JSON: mesmos nomes e parâmetros do SDK em Python, com cliente JS e página de demonstração incluídos | Suas próprias ferramentas e interfaces, Bots remotos |
Comece com uma frase
Preparar o ambiente leva uns 15 minutos. O resto fica com o seu agente.