generals-bots

Generals.io Bots é um simulador de alto desempenho do jogo de estratégia generals.io, escrito em Python sobre JAX e voltado para pesquisa em aprendizado por reforço. Ele oferece um ambiente funcional e rápido onde agentes podem ser treinados e avaliados, além de ferramentas para implantar agentes em servidores reais do generals.io. Características principais descritas pelo projeto: - Simulador JAX totalmente compilado via JIT com suporte vetorizado a vmap para paralelismo em larga escala. - Design funcional puro com estado imutável e trajetórias reproduzíveis. - Suporte a implantação ao vivo em servidores do generals.io. - GUI integrada para visualizar partidas e depurar o comportamento dos agentes. A instalação é feita clonando o repositório e executando pip install -e . O README observa que o simulador segue as regras atuais do jogo, com a afirmação de que 10.000 partidas ranqueadas reproduzidas por ele corresponderam ao motor do generals.io após cada turno. Primeiros passos: a classe GeneralsEnv recebe as dimensões da grade e um limite de truncamento. Uma chamada reset retorna um pool de reinício automático mais um estado inicial. Os agentes implementam uma interface act(observation, key); o README mostra RandomAgent e ExpanderAgent como exemplos. O loop do jogo obtém observações por jogador, empilha as ações e avança o ambiente, que se reinicia automaticamente a partir do pool pré-gerado. Um exemplo vetorizado demonstra a execução de muitos ambientes em paralelo com jax.vmap, usando um pool compartilhado e estados em lote. O ambiente suporta 1v1, todos contra todos com N jogadores e partidas em equipe. Em equipes, mover-se para a célula de um companheiro acumula exércitos e transfere a célula; capturar um general transfere as células da vítima com exércitos reduzidos pela metade e elimina aquele jogador; uma equipe perde somente quando todos os seus generais caem, e a última equipe restante vence. A visão é compartilhada dentro da equipe, e as observações incluem células aliadas, contagem de território aliado e contagem de exércitos aliados, com campos de oponentes cobrindo todas as equipes inimigas em conjunto. As observações expõem campos como exércitos, generais, castelos, montanhas, células próprias/do oponente/neutras/sob névoa, estruturas sob névoa, contagens de território e exércitos, passo de tempo e campos aliados. O auxiliar as_tensor() empilha os primeiros 14 campos em um tensor (14, H, W), anexando opcionalmente canais aliados. As ações são arrays de cinco inteiros: passar, linha, coluna, direção e divisão. Um auxiliar compute_valid_move_mask retorna movimentos legais como uma máscara (H, W, 4). A implantação usa generals.remote.autopilot com um agente, user_id e lobby_id para conectar-se a servidores reais do generals.io. O README inclui uma citação BibTeX de um artigo arXiv de 2025 intitulado "Artificial Generals Intelligence: Mastering Generals.io with Reinforcement Learning", de Matej Straka e Martin Schmid.