# Esquemas de IA

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

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

Um **esquema** = uma IA completa: uma pasta + um manifesto `scheme.json` + código. Cada instância do jogo escolhe um esquema; troque com um clique no Farsight, e **até a partida em andamento pode ser assumida na hora por outra IA**.

Esquemas compartilhados por outras pessoas entram numa **área separada** quando importados, sem interferir nos seus; para alterar um deles, use “Copiar para os meus”.

```text
schemes/
  mine/<id>/          meus esquemas: escritos por você ou copiados de outro esquema para alterar (altere à vontade; vale na próxima partida)
  installed/<id>/     instalados: zips compartilhados por outras pessoas são extraídos aqui (é preciso confirmar a confiança antes da primeira execução)
brains/xwar3/         embutido: o cérebro de referência (IA completa)
brains/examples/      embutidos: quatro exemplos didáticos, hello / rush / macro / micro, o exemplo de companheiro buddy e dois mods de jogabilidade (Roguelike de Heróis, Defesa Infinita)
```

Um esquema não precisa ser uma IA que joga por você: um esquema `kind: mod` é um **conjunto de regras de jogo** — você mesmo joga, e ele cria os desafios; veja [Mods de jogabilidade](https://war3ai.com/pt/docs/mods/).

## Usando no Farsight

Página “Esquemas de IA” (barra lateral esquerda, “Sistema → Esquemas de IA”):

| Ação | O que faz |
|---|---|
| Importar esquema (zip) | Instala em `installed/`; se o mesmo id já estiver instalado, pergunta se deve substituir (depois de substituir, é preciso confirmar a confiança de novo) |
| Usar na instância… | Escolha a instância + “Vale agora” (para a IA atual, e o novo esquema assume esta partida) ou “Vale no próximo Iniciar teste” |
| Copiar para os meus | Copia para `mine/`, com autor “eu” e versão 0.1.0, e registra de qual versão de qual esquema a cópia foi feita |
| Exportar zip | Empacota como `<id>-<versão>.zip`; mandar esse arquivo para alguém é compartilhar |
| Abrir pasta | Abre a pasta do esquema no Explorador de Arquivos, para alterar o código direto |
| Confiar | Obrigatório antes da primeira execução de um esquema de outra pessoa (veja “Confiança e segurança” abaixo) |
| Resultados recentes | Vitória ou derrota, duração e motivo do fim de cada partida deste esquema |
| Excluir | Só dá para excluir “meus” e “instalados”; não é permitido enquanto alguma instância estiver usando o esquema |

O card da instância também ganhou uma linha “Esquema de IA”: escolha o esquema no menu → “Trocar (vale agora)”. Quando a instância não está rodando, o botão se chama “Selecionar”, e o próximo “Iniciar teste” sobe a IA com esse esquema.

## O manifesto scheme.json

```json
{
  "format": 1,
  "id": "fast-rush",
  "name": "Rush de três minutos",
  "version": "1.2.0",
  "author": "Fulano",
  "description": "Uma frase dizendo que estilo de jogo esta IA usa",
  "entry": "rush_bot.py",
  "class": "RushBot",
  "fair": true,
  "hz": 5,
  "races": ["human", "orc"],
  "license": "MIT"
}
```

| Campo | Obrigatório | Descrição |
|---|---|---|
| `id` | ✔ | Letras minúsculas, números, `-` e `_`; 2 ~ 41 caracteres |
| `entry` | ✔ | Um arquivo `.py` dentro da pasta do esquema (caminhos absolutos e `..` não são permitidos) |
| `kind` | | Padrão `bot` (subclasse de `openwar3.Bot`, joga por você); `mod` = [mod de jogabilidade](https://war3ai.com/pt/docs/mods/) (subclasse de `openwar3.Mod`, nunca usa o modo justo e não tem o resultado decidido pelas regras de confronto) |
| `class` | | Nome da subclasse de Bot (ou Mod) no arquivo de entrada; se omitido, usa a última subclasse de `openwar3.Bot` do arquivo de entrada |
| `fair` | | Padrão `true`: só vê o que está no campo de visão, a mesma regra da Arena. `false` = mapa inteiro visível, e só assim é possível usar o [canal JASS](https://war3ai.com/pt/docs/jass/) (necessário para companheiros) |
| `judge` | | Padrão `true`: decide vitória e derrota pelas regras de confronto. Esquemas de RPG / de companheiro usam `false` |
| `hz` | | Quantas vezes por segundo `on_tick` é chamado; padrão 5 |
| `format` | | Versão do formato do manifesto, atualmente 1; versões mais novas que o OpenWar3 desta máquina são rejeitadas com um aviso para atualizar |
| Demais | | `name`, `version`, `author`, `description`, `races`, `license`, `homepage` e `forked_from` servem só para exibição |

A pasta do esquema é adicionada ao caminho de busca de módulos do Python, então o arquivo de entrada pode fazer `import` de outros arquivos da mesma pasta. Pacotes de terceiros (numpy, torch…) não são instalados automaticamente — diga claramente em `description` do que o esquema precisa.

**O menor esquema possível tem só dois arquivos**:

```python
# my_bot.py
from openwar3 import Bot

class MyBot(Bot):
    def on_tick(self, g):
        for w in g.idle_workers():
            mine = g.nearest(g.gold_mines(), w)
            if mine:
                g.gather(w, mine)
```

```json
{"id": "my-first", "name": "Minha primeira IA", "entry": "my_bot.py"}
```

Coloque em `schemes/mine/my-first/` e atualize o Farsight para vê-lo. Um ponto de partida ainda mais fácil: escolha um exemplo em “Embutidos” e clique em “Copiar para os meus”.

## Execução e resultados

Os esquemas são executados pelo **executor de esquemas** (é ele que o “Iniciar teste / Trocar” do Farsight inicia):

```bash
python tools/run_scheme.py --inst 20 --scheme builtin/micro --hours 6
```

- Cada instância tem um processo supervisor permanente, que **inicia um subprocesso a cada partida** para rodar o esquema: se o código do esquema quebrar, o supervisor não cai junto; se você mudar o código de um dos “meus esquemas”, a próxima partida já usa a versão nova.
- Ao fim de cada partida, é registrada uma linha de resultado: esquema, versão, autor, vitória ou derrota, motivo, duração da partida, número de erros. As taxas de vitória do Farsight são calculadas a partir daí.

Como a vitória e a derrota são decididas:

| Situação | Registrado como |
|---|---|
| Todas as construções do adversário destruídas | Vitória |
| Todas as nossas construções destruídas (mesmo com tropas vivas — é assim que o confronto define a derrota) | Derrota |
| Todas as nossas unidades mortas | Derrota |
| Encerrada / parada manualmente no Farsight | Indefinido |
| A partida já tinha mais de 60 segundos de jogo na hora da troca (assumida no meio) | Contada à parte, **fora da taxa de vitória** |
| O relógio do jogo parado por muito tempo | Indefinido |

Depois de definido o resultado, o executor fecha a tela de resultados, abre a próxima partida conforme a “Próxima partida”, e o esquema assume de novo — dá para deixar rodando a noite toda, acumulando resultados. Pausa não conta como fim: durante a pausa, o Bot continua rodando; só o relógio do jogo para.

## Confiança e segurança

**Um esquema é código e roda com as mesmas permissões que você** (pode ler e gravar arquivos e acessar a rede). Por isso:

- esquemas em `installed/` **não são confiáveis** por padrão: o Farsight e o executor se recusam a rodá-los até você clicar em “Confiar”;
- substituir a instalação de um esquema com o mesmo id **reinicia a confiança** (versão nova = código novo);
- na importação, verifica-se que o zip tem no máximo 50 MB e no máximo 2000 arquivos; caminhos absolutos e `..` não são permitidos (para impedir a gravação fora da pasta do esquema); manifesto inválido ou arquivo de entrada inexistente são rejeitados na hora.

> **Atenção**
>
> Antes de confiar, use “Abrir pasta” e leia o código. Só aceite esquemas de pessoas em quem você confia.

## API (para scripts)

| API | Descrição |
|---|---|
| `GET /api/schemes` | Lista de esquemas + resultados + o esquema escolhido e o esquema em execução em cada instância |
| `GET /api/schemes/results?ref=` | As últimas 30 partidas de um esquema |
| `POST /api/schemes/import` | Importa um zip |
| `GET /api/schemes/export?ref=` | Baixa o zip |
| `POST /api/schemes/fork` | Copiar para os meus |
| `POST /api/schemes/trust` | Confiar |
| `DELETE /api/schemes?ref=` | Excluir (rejeitado se alguma instância estiver usando o esquema) |
| `POST /api/instances/{n}/scheme` | Troca o esquema de uma instância: assume esta partida na hora, ou vale no próximo Iniciar teste |

No Python, use a biblioteca direto: `from openwar3 import schemes` (`list_schemes`, `install_zip`, `export_zip`, `fork`, `trust`, `stats`…).

## No futuro: site de esquemas

O zip exportado já é a unidade de compartilhamento; o site só precisa acrescentar uma camada por fora: upload com um clique pelo Farsight; download pelo site, passando exatamente pelas mesmas verificações do “Importar esquema” e com a mesma confirmação de confiança; envio opcional de resultados, com o site agregando as taxas de vitória por versão. O botão “Compartilhar no site de esquemas” já tem lugar reservado no Farsight. Acompanhe o andamento no [roadmap](https://war3ai.com/pt/roadmap/).