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.
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”.
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.
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
{
"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 (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 (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:
# 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){"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):
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.
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.