Início rápido

O que você precisa

	Requisito	Observações
Sistema	Windows 10 / 11, 64 bits	Por enquanto só há suporte a Windows
Jogo	Warcraft III 1.27a (The Frozen Throne, `Game.dll` 1.27.0.52240)	Um cliente que você possui legalmente; nenhum arquivo do jogo em disco é modificado

Não é preciso instalar mais nada antes. O start.bat baixa só uma coisa: o Python 3.13 (pacote portátil oficial, com cerca de 14 MB), colocado em bin\env\ dentro do repositório, sem precisar de permissão de administrador nem alterar o PATH do sistema; em redes da China continental, troca automaticamente para espelhos. Se o computador já tiver um Python que funcione, ele é usado diretamente. O PowerShell usado é o que já vem com o Windows; a página web do Farsight já vem compilada junto com o repositório, sem precisar do Node.js.

Instalação

Obtenha o código
```
git clone https://github.com/OPENXXAI/OpenWar3AI.git
```
Ou baixe o arquivo compactado e extraia. O runtime (a DLL de injeção e o lançador) vem junto com o repositório; não é preciso baixá-lo à parte.
Dê dois cliques em start.bat

Na primeira vez, ele faz sozinho:
- Baixa o Python 3.13;
- Instala os pacotes Python e instala os arquivos do runtime depois de conferi-los;
- Baixa os dados de estratégia do AMAI usados para gerar o cérebro de referência (o AMAI tem licença própria e os arquivos gerados não entram no git; uma falha aqui só afeta o cérebro de referência);
- Abre a página inicial do Farsight, a “Central de controle”, em http://127.0.0.1:8866.
Cada passo imprime o resultado; se algum não der certo, ele explica como completar. Das próximas vezes, cada clique duplo só faz uma verificação de um ou dois segundos e abre o Farsight.

A janela preta se fecha sozinha depois de alguns segundos: o Farsight continua rodando em segundo plano, e fechar o navegador não o interrompe.
Defina a pasta do jogo na Central de controle

No topo da Central de controle, use “Localizar automaticamente” ou “Procurar…” para escolher você mesmo a pasta do Warcraft III. O Farsight verifica a versão do jogo e extrai os dados da sua própria cópia do jogo (tabela de unidades, habilidades, itens, tabela de vantagens de tipo… os arquivos da Blizzard não são distribuídos com o código).

Se a versão não for 1.27a, ele avisa. Os mapas e as configurações da próxima partida são relativos a essa pasta (dá para escolher mapas de qualquer pasta dentro de <pasta do jogo>\Maps); para trocar a pasta depois, use a página “Configurações”.
Inicie uma partida e deixe o Bot de exemplo assumir

O jeito mais fácil é, na página “Instâncias e partidas” do Farsight, marcar um número de instância, escolher um esquema de IA e clicar em “Iniciar teste”. Também dá para usar a linha de comando:
```
python tools/play.py --bot brains/examples/hello_bot.py
```
Esse comando inicia uma instância do jogo, injeta o runtime, começa a partida automaticamente e então sobe o Bot. Quando você vir os camponeses indo minerar e a sede começando a treinar camponeses, deu certo.

O python do comando é o que está registrado no openwar3.json; o que o start.bat instala fica em bin\env\python\python.exe.

start.bat e stop.bat

start.bat              # verificação da instalação + abre o Farsight
start.bat setup        # verificação completa: reinstala os pacotes Python, tenta o AMAI de novo
start.bat restart      # reinicia só o backend do Farsight (jogos e serviços não são afetados)
start.bat node         # também instala uma cópia do Node.js (só é necessária para a prévia do site; no dia a dia não precisa)
start.bat 5 6          # também inicia os testes nas instâncias 5 e 6 (jogo + cérebro de referência)
stop.bat               # para tudo; stop.bat --keep-llm mantém o modelo local na VRAM

O gateway, os balões de fala e o LLM local também são iniciados e parados na “Central de controle” do Farsight; não é preciso procurar outros scripts. Para parar tudo: dê dois cliques em stop.bat ou clique em “Parar tudo” no canto superior direito da Central de controle — as instâncias do jogo, a IA, o gateway, os balões, o modelo local usado por este sistema e o backend do Farsight param, nessa ordem. Os servidores MCP são gerenciados pelos clientes, como o Claude, e não são parados.

Arquivo de configuração

O openwar3.json é escrito automaticamente pelo start.bat e pelo Farsight, guarda só caminhos locais e não entra no git. Para mudar as portas ou o endereço e o nome do modelo do LLM local, siga o openwar3.example.json e escreva só os itens que forem diferentes dele.

Parâmetros do play.py

python tools/play.py --bot my_bot.py --inst 9 --race 2 --enemy-race 1 --difficulty 3 --speed 200
python tools/play.py --bot my_bot.py --inst 9 --attach      # o jogo já está aberto; só conecta o Bot
python tools/play.py --bot my_bot.py --fair                 # modo justo: só vê o que está no campo de visão

Parâmetro	Padrão	Descrição
`--bot`	Obrigatório	Caminho do arquivo do Bot (o arquivo precisa conter uma subclasse de `Bot`)
`--inst`	`9`	Número da instância. Não repita o número de uma instância que já está rodando (a página “Instâncias e partidas” do Farsight mostra quais números estão em uso)
`--race`	`1`	Nossa raça: 1 Humanos, 2 Orcs, 3 Mortos-vivos, 4 Elfos Noturnos
`--enemy-race`	`0`	Raça do adversário
`--difficulty`	`2`	Dificuldade do computador: 2 Fácil, 3 Normal, 4 Insano
`--speed`	`100`	Velocidade do jogo (porcentagem, 200 = 2×)
`--map`	`default_map` da configuração	Mapa
`--attach`		Não inicia o jogo; só se conecta a uma instância que já está rodando
`--hz`	`5`	Quantas vezes por segundo `on_tick` é chamado
`--minutes`	`60`	Tempo máximo de execução em minutos (relógio real)
`--fair`		Modo justo
`--player`		Com qual número de jogador comandar (para IA contra IA)

Não inicie o jogo com --minimize: a simulação do jogo para enquanto a janela está minimizada (o relógio não anda), e o Bot vai ficar esperando para sempre a partida começar.

Você também pode dispensar o play.py e usar a linha de comando do SDK para se conectar direto a uma instância que já está rodando:

python -m openwar3 run brains/examples/hello_bot.py --inst 5     # roda um Bot
python -m openwar3 status --inst 5                              # conecta e imprime o estado do snapshot / da via rápida
python -m openwar3 catalog                                      # imprime a referência da API

Depois que funcionar

Escreva seu primeiro Bot Comece com um Bot mínimo de 10 linhas e adicione, passo a passo, treino de unidades e ataques. Deixe um LLM escrever para você Copie o modelo de prompt e descreva sua estratégia em linguagem simples.

Autoverificação

python tools/run_tests.py          # SDK / cérebro de referência / camada reflexa / console / balões de fala / exemplos, um subprocesso por suíte

Os testes offline não precisam do jogo aberto. A “Central de controle” do Farsight também tem uma verificação do ambiente, que mostra se cada parte está instalada.