Visão geral da documentação

OpenWar3 é a camada de interface aberta do War3AI: um runtime injetado no Warcraft III 1.27, mais um SDK em Python.

• A cada 50 ms, o runtime envia para a memória compartilhada o estado completo do mapa inteiro: recursos e comida de todos os jogadores; vida e mana, ordem atual, quem cada unidade está atacando, recargas de habilidades, buffs e inventário de todas as unidades; itens no chão, árvores, filas de produção, dia e noite. Há também um fluxo de eventos: unidades aparecendo e morrendo, cada golpe de dano, produção concluída…
• Programas externos enviam comandos semânticos com latência de cerca de um frame: mover, atacar, coletar, construir, treinar, lançar feitiços, aprender habilidades, reviver, usar itens, comprar… Cada comando tem um recibo que diz se o motor aceitou e, se não aceitou, o código de motivo.
• Você só diz “o que fazer”: unidades por código de quatro caracteres, habilidades por nome de ordem, os mesmos nomes usados no jogo; o “como” fica por conta do runtime.

Por isso o LLM não precisa de nenhum conhecimento de baixo nível nem precisa ver a tela. Depois de ler a documentação, ele consegue escrever um Bot que cuida da economia e sabe lutar, e depois ajustá-lo sozinho com base nos recibos e eventos da partida.

E não é só para partidas competitivas: o canvas desenha seus próprios painéis e marcações na tela do jogo, Interface e entrada torna clicáveis os botões desenhados e faz as teclas de atalho responderem, o canal JASS chama de fora as 1291 funções do jogo, e em mapas RPG você ainda pode ter um companheiro de IA ao seu lado. Uma IA pronta pode virar um esquema, que você troca com um clique e exporta para compartilhar; uma jogabilidade nova inteira pode virar um mod de jogabilidade.

Também dá para conectar sem escrever Python: o gateway deixa qualquer linguagem ou página de navegador chamar as mesmas APIs via WebSocket / JSON, e o servidor MCP deixa agentes como o Claude Code chamarem ferramentas diretamente para ver a partida e dar comandos.

Escolha um caminho para o seu caso

Você	Comece por aqui	Depois
Joga Warcraft, mas não programa	Início rápido → Escreva um Bot com um LLM	Se algo der errado, veja as Perguntas frequentes
Sabe Python	Seu primeiro Bot → Modelo mental → As quinze regras	Receitas de jogadas profissionais, Bots de exemplo
Está criando um agente de programação / automação	Iteração autônoma do agente	Recibos e códigos de motivo, llms-full.txt
Quer que um LLM tome decisões durante a partida	LLM como coach de estratégia	Balões de fala e modelos locais
Quer que um agente opere o jogo diretamente (Claude Code etc.)	LLM usando ferramentas (MCP)	Interface e entrada
Usa outra linguagem (JS, C#, Go, Rust…)	Gateway	Mais baixo nível: Protocolo W3P
Quer pôr IAs de pessoas diferentes para se enfrentar	Modo justo	Arena
Quer criar sua própria jogabilidade em mapas RPG / personalizados	Mods de jogabilidade	Interface e entrada, Canvas, Canal JASS, Companheiro de RPG
Quer compartilhar a sua IA com outras pessoas	Esquemas de IA	Console Farsight

O que há no repositório

start.bat       Único ponto de entrada: instalação do zero + abre o Farsight; stop.bat para tudo
sdk/python/     Camada de interface. openwar3/ é a fachada pública (Game + Bot); comece por aqui
brains/         Camada de decisão
  examples/       hello_bot (economia) → rush_bot (tropas) → macro_bot (macro) → micro_bot (micro + creeps); buddy (companheiro de RPG);
                  mod_hero_roguelike / mod_endless_defense (mods de jogabilidade)
  xwar3/          Cérebro de referência: camada de estratégia (segundos) + camada reflexa (4 processos) + modelo de vitória
console/        Console web Farsight (FastAPI + React)
gateway/        Gateway (WebSocket / JSON) + cliente JS + página de demonstração no navegador
director/       Câmera automática, barras de vida sobre as unidades
speech/         Balões de fala sobre as unidades + LLM local
runtime/        Orquestração de várias instâncias (cada partida reiniciada conforme a configuração)
data/           order-ids.txt; ferramentas para extrair dados do seu próprio jogo
schemes/        Seus esquemas de IA (mine/) e os compartilhados por outras pessoas (installed/); fora do repositório
tools/          play.py (inicia uma partida com um comando), run_scheme.py (executor de esquemas), war3_mcp.py (servidor MCP), run_tests.py, scripts de verificação em partidas reais
docs/           Catálogo da API api.json (gerado a partir do código), protocolo, manual

Entre o runtime e o seu código há apenas o protocolo W3P, que é versionado: o SDK em Python é o caminho mais fácil, mas você também pode integrar a partir de outra linguagem seguindo o protocolo.

O que significa o “status de teste” de uma API

Cada API do catálogo tem um de três status:

• Verificado em partidas reais: o caminho interno (número da ação, formato dos parâmetros, efeito lido de volta) foi verificado em partidas reais e é protegido por um script de verificação.
• Experimental: API nova, que já funciona na instância de teste e ainda está sendo verificada item por item em partidas reais. Pode ser usada, mas os detalhes da interface ainda podem mudar.
• Inferido / não totalmente testado: o mecanismo interno copia o que o próprio motor faz (por exemplo, a função JASS equivalente), mas ainda não foi verificado item por item numa partida. Confira o recibo antes de depender dele.