# War3AI / OpenWar3

> Interface aberta de Warcraft III 1.27 para agentes de IA. Um runtime injetado envia a cada 50 ms o estado completo do mapa inteiro e um fluxo de eventos; programas externos enviam comandos semânticos em cerca de um frame, cada um com recibo e código de motivo. O SDK em Python (openwar3) descreve tudo com os nomes do jogo (códigos de quatro caracteres, nomes de ordens de habilidades).

O caminho mais curto para escrever um Bot: leia “As quinze regras” + as APIs do api.json, herde de openwar3.Bot e implemente on_start(g) / on_tick(g) / on_event(g, ev); use apenas métodos que existem no api.json.
Toda a documentação em um só arquivo: https://war3ai.com/pt/llms-full.txt

## Começar

- [Visão geral da documentação](https://war3ai.com/pt/docs/index.md): Documentação do OpenWar3: o que é, o que faz; Início rápido, Seu primeiro Bot, Escreva um Bot com um LLM, API e protocolo, Gateway e MCP — por onde começar depende do seu caso.
- [Início rápido](https://war3ai.com/pt/docs/quickstart.md): Dê dois cliques em start.bat para instalar tudo automaticamente, defina a pasta do jogo no Farsight e inicie uma partida para ver um Bot de exemplo assumir o controle. Cerca de 15 minutos.
- [Seu primeiro Bot](https://war3ai.com/pt/docs/first-bot.md): Comece com um Bot mínimo de 10 linhas, depois adicione treino de camponeses, construções para comida, exército, heróis e ataques — e, por fim, aprenda a ler os recibos.

## IA escrevendo Bots

- [Escreva um Bot com um LLM](https://war3ai.com/pt/docs/ai-bot.md): Não precisa saber programar: você explica como quer que ele jogue, e o LLM escreve o código. Copie o modelo de prompt, descreva sua estratégia, rode e depois peça ao modelo para ajustar.
- [Iteração autônoma do agente](https://war3ai.com/pt/docs/agent-loop.md): Deixe um agente de programação jogar partidas, ler os resultados, mudar o código e jogar de novo sozinho. Ele precisa de um comando que rode sem supervisão, de um relatório de partida estruturado e de um objetivo claro.
- [LLM como coach de estratégia](https://war3ai.com/pt/docs/llm-coach.md): Entregue a um LLM as decisões "para o que economizar, onde colocar trabalhadores, atacar ou segurar neste minuto" e deixe a camada de regras apenas executar e vetar. O cérebro de referência já funciona assim; esta página explica o padrão e as armadilhas.
- [LLM usando ferramentas (MCP)](https://war3ai.com/pt/docs/mcp.md): tools/war3_mcp.py é um servidor MCP. Conecte-o ao Claude Code, ao Claude Desktop ou a qualquer cliente com suporte a MCP, 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.

## Conceitos centrais

- [Modelo mental](https://war3ai.com/pt/docs/concepts.md): Snapshots, comandos, recibos, eventos, ticks e lotes. Entenda esses seis conceitos e você vai entender por que a API tem esse formato e como escrever código rápido.
- [As quinze regras](https://war3ai.com/pt/docs/rules.md): Cada uma foi aprendida na prática, em partidas reais. Confira a lista ao escrever um Bot e você economiza a maior parte do tempo de investigação.
- [Modo justo](https://war3ai.com/pt/docs/fair-mode.md): Um cliente injetado no jogo consegue ler o mapa inteiro. O modo justo faz o Bot enxergar só o que está na sua visão — como um jogador humano, e como na regra da Arena.

## Guias

- [Receitas de jogadas profissionais](https://war3ai.com/pt/docs/cookbook.md): A maior parte da vantagem de um jogador de alto nível vem de dezenas de pequenos hábitos. Esta página traduz, uma a uma, técnicas comuns dos profissionais em código do SDK — cada trecho pode ser colado direto no on_tick.
- [Bots de exemplo](https://war3ai.com/pt/docs/examples.md): 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.
- [Depuração e desempenho](https://war3ai.com/pt/docs/debugging.md): Por que um tick está lento, por que um comando não teve efeito, por que o jogo não se mexe. Investigue pelo sintoma e confirme com os scripts de verificação em partidas reais que vêm no projeto.

## Extensões de jogo

- [Companheiro de RPG](https://war3ai.com/pt/docs/companion.md): Dê ao jogador um companheiro de IA em mapas RPG e personalizados: ele segue você, ajuda a matar monstros, cura você quando sua vida está baixa e conversa com você. Quatro modos; herde uma classe, mude algumas propriedades e você tem o seu próprio companheiro.
- [Canvas](https://war3ai.com/pt/docs/canvas.md): Desenhe caixas de texto, painéis, barras de progresso, imagens, círculos no chão e rotas com seta sobre a tela do jogo. O runtime desenha tudo a cada frame, sem alterar o estado do jogo, então é seguro em partidas multijogador; funciona por Python, HTTP ou escrevendo direto na memória compartilhada.
- [Interface e entrada](https://war3ai.com/pt/docs/ui-input.md): Botões e cartões de escolha do canvas ficam clicáveis, com destaque automático ao passar o mouse; registre teclas de atalho, clique no chão para escolher uma posição, leia para onde o mouse aponta e saiba quem o jogador local selecionou. Cliques, teclas de atalho, feitiços lançados, o texto completo do chat e jogadores que saem entram no fluxo de eventos.
- [Canal JASS](https://war3ai.com/pt/docs/jass.md): As 1291 funções JASS que autores de mapas podem usar agora podem ser chamadas pelo nome, de fora do jogo: criar unidades, alterar atributos, efeitos, painéis, caixas de diálogo, sons, câmera, névoa… Quatro formas de uso: console Farsight, linha de comando, HTTP e Python.
- [Mods de jogabilidade](https://war3ai.com/pt/docs/mods.md): Um esquema não precisa ser uma IA que joga por você; também pode ser um conjunto de regras: você mesmo joga na janela do jogo, e o mod prepara o início, gera inimigos, dá recompensas, põe botões e cartões de escolha na tela e decide o resultado. Herde de openwar3.Mod: um arquivo é uma jogabilidade inteira.

## Ferramentas

- [Console Farsight](https://war3ai.com/pt/docs/console.md): Console web local e também o único ponto de entrada: definir a pasta do jogo, iniciar e parar os serviços, iniciar e parar instâncias do jogo, configurar a próxima partida, ver o que a IA está pensando, dar ordens manuais, dirigir a câmera e consultar o histórico de partidas.
- [Esquemas de IA](https://war3ai.com/pt/docs/schemes.md): Um esquema é uma IA completa. Troque com um clique no Farsight — até a partida em andamento pode ser assumida na hora por outra IA; exporte um zip para compartilhar, importe esquemas de outras pessoas para testar, e os resultados de cada esquema são contabilizados automaticamente.
- [Balões de fala e modelos locais](https://war3ai.com/pt/docs/speech.md): Faça qualquer unidade do jogo exibir um balão de fala sobre a cabeça, com qualquer identidade; conecte um LLM local e cada frase que entra vira uma resposta sobre a unidade.
- [Gateway](https://war3ai.com/pt/docs/gateway.md): Gateway WebSocket / JSON: as APIs públicas que o SDK em Python chama também podem ser chamadas de JS, C#, Go, Rust, páginas de navegador e programas em outra máquina. Três papéis, com cliente JS e página de demonstração no navegador incluídos; a latência é a da via rápida mais cerca de 1 ms.

## Referência

- [Protocolo W3P](https://war3ai.com/pt/docs/protocol.md): O contrato completo entre o runtime e programas externos: oito blocos de memória compartilhada, leitura do estado do mundo, leitura de eventos, envio de comandos, recibos, papéis das vias, canvas e interface e entrada. Leia esta página se você for integrar com uma linguagem que não seja Python.
- [Recibos e códigos de motivo](https://war3ai.com/pt/docs/reason-codes.md): O recibo de cada comando traz um código de status e um código de motivo. Eles são a base para Bots e agentes se corrigirem sozinhos: transformam “por que não deu certo” em um número legível por máquina.
- [De onde vêm os dados](https://war3ai.com/pt/docs/data-sources.md): A origem e a precisão de cada tipo de dado. Quando algo “parecer errado”, comece por esta página.

## Outros

- [Perguntas frequentes](https://war3ai.com/pt/docs/faq.md): Isto é um cheat? Quais versões são suportadas? O que a IA vê e o que ela pode fazer? Dá para usar sem saber programar? …
- [Limites de uso](https://war3ai.com/pt/docs/legal.md): O que é permitido, o que não é, as estatísticas de acesso deste site, e avisos sobre marcas e licenças de terceiros. Ao usar este projeto, você concorda em respeitar estes limites.

## API

- [api.json](https://war3ai.com/pt/api.json): Todos os 103 métodos de Game (name / category / status / latency / mechanism / signature / doc), gerados a partir do código
- [Catálogo da API (web)](https://war3ai.com/pt/api/): Versão pesquisável dos mesmos dados

## Opcional

- [llms-full.txt](https://war3ai.com/pt/llms-full.txt): Toda a documentação + catálogo da API, numa só leitura
- [Limites de uso](https://war3ai.com/pt/docs/legal.md): Apenas para clientes que você possui legalmente; não pode ser usado na Battle.net nem em qualquer servidor com anti-cheat