# Visão geral da documentação

> 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.

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

**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](https://war3ai.com/pt/docs/canvas/) desenha seus próprios painéis e marcações na tela do jogo, [Interface e entrada](https://war3ai.com/pt/docs/ui-input/) torna clicáveis os botões desenhados e faz as teclas de atalho responderem, o [canal JASS](https://war3ai.com/pt/docs/jass/) chama de fora as 1291 funções do jogo, e em mapas RPG você ainda pode ter um [companheiro de IA](https://war3ai.com/pt/docs/companion/) ao seu lado. Uma IA pronta pode virar um [esquema](https://war3ai.com/pt/docs/schemes/), que você troca com um clique e exporta para compartilhar; uma jogabilidade nova inteira pode virar um [mod de jogabilidade](https://war3ai.com/pt/docs/mods/).

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

  - [Início rápido](https://war3ai.com/pt/docs/quickstart/): Prepare o ambiente, inicie uma partida com um comando e veja o Bot de exemplo assumir.
  - [Escreva um Bot com um LLM](https://war3ai.com/pt/docs/ai-bot/): Não precisa saber programar: copie o prompt, descreva a estratégia e entregue ao agente.
  - [Modelo mental](https://war3ai.com/pt/docs/concepts/): Snapshot, comando, recibo, evento, tick. Cinco minutos de leitura antes de escrever um Bot.
  - [Catálogo da API](https://war3ai.com/pt/api/): Todas as APIs, cada uma com status de teste, faixa de latência e mecanismo interno.

## Escolha um caminho para o seu caso

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

## O que há no repositório

```text
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](https://war3ai.com/pt/docs/protocol/), 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.

> **Nota**
>
> No momento, só há suporte ao **Warcraft III 1.27** (The Frozen Throne). As versões 1.24 ~ 1.28 compartilham a mesma estrutura de motor; o suporte a várias versões está na fase P4 do [roadmap](https://war3ai.com/pt/roadmap/). A 1.29 em diante e o Reforged usam outro motor e ficam fora do escopo.