本页目录

generals.io 强化学习机器人框架(generals-bots)

generals-bots · strakam/generals-bots

面向 generals.io 的策略机器人开发库,使用 Python 编写,核心是基于 JAX 的高性能模拟器,供强化学习研究使用。仓库 topics 涵盖 gymnasium、pygame、强化学习与策略。README 自述支持 JIT 编译与 vmap 并行、内置图形界面用于可视化对...

策略 多人对战 Pygame Python 敌人 AI 游戏状态管理 高级
★ Stars 130 Forks 32 License 未明确 更新 2026-11-18

国内开发环境适配

Windows
未知
Linux
未知
macOS
未知
引擎 / 框架:Pygame 暂无中文教程标记 未标记站长实测
依赖 JAX,国内安装时 pip 源与 JAX 轮子(尤其 CUDA 版本)下载可能较慢,建议配置镜像并确认平台对应的 JAX 版本;README 未列出完整依赖清单,具体以仓库包配置为准,待核验。

中文项目介绍

generals-bots 是面向 generals.io 的策略机器人开发框架,目标是为强化学习研究提供一个快速的机器人开发平台。它并非 generals.io 的客户端复刻,而是一个用 Python 编写、以 JAX 为核心的高性能模拟器:环境状态不可变、轨迹可复现,便于做大规模自对弈与策略搜索实验。README 说明,模拟器遵循当前游戏规则,并曾用 2026 年进行的 10,000 场排位对局回放逐回合比对,与 generals.io 官方引擎的棋盘状态保持一致。

仓库自述的亮点包括:

  • 完全 JIT 编译的 JAX 模拟器,配合向量化 vmap 实现大规模并行,README 宣称可达每秒千万级 step(属仓库自述指标,实际取决于硬件与网格规模,待核验);
  • 纯函数式设计,状态不可变、轨迹可复现;
  • 支持把智能体部署到 generals.io 线上服务器;
  • 内置图形界面,用于观察对局、调试智能体行为。

补充说明

安装与环境准备

README 给出的安装方式是从源码以可编辑模式安装:

git clone https://github.com/strakam/generals-bots
cd generals-bots
pip install -e .

由于核心依赖 JAX,实际安装时通常还需要按本机是否有 GPU 选择对应的 JAX 版本;README 未对这一步骤做额外说明,具体依赖清单请以仓库内的包配置为准。安装完成后,generals 包提供环境、智能体与工具函数,examples/ 目录下存有可直接运行的示例脚本。

快速上手:基础对局循环

最小可运行流程由三步构成:创建环境、创建智能体、循环交互。

import jax.numpy as jnp
import jax.random as jrandom
from generals import GeneralsEnv, get_observation
from generals.agents import RandomAgent, ExpanderAgent

env = GeneralsEnv(grid_dims=(10, 10), truncation=500)
agent_0, agent_1 = RandomAgent(), ExpanderAgent()

key = jrandom.PRNGKey(42)
pool, state = env.reset(key)

while True:
    obs_0 = get_observation(state, 0)
    obs_1 = get_observation(state, 1)
    key, k1, k2 = jrandom.split(key, 3)
    actions = jnp.stack([agent_0.act(obs_0, k1), agent_1.act(obs_1, k2)])
    timestep, state = env.step(state, actions, pool)
    if timestep.terminated or timestep.truncated:
        break
print(f"Winner: Player {int(timestep.info.winner)}")

两个参数值得注意:grid_dims 决定棋盘尺寸,truncation 设定单局最大步数,超过即截断。reset 的返回值是「自动重置池 + 首个状态」的组合,回合结束后的自动重置会从预先生成的池中取新局,从而避免在训练循环中反复调用初始化逻辑。

向量化并行环境

框架的核心卖点是把成千上万局游戏并行跑起来。做法是先用 reset 生成一次共享的状态池,再用 jax.vmap(env.init_state) 批量生成各环境的初始状态,最后用 jax.vmap 包住 env.step 批量推进:

NUM_ENVS = 1024
key, pool_key = jrandom.split(key)
pool, _ = env.reset(pool_key)
states = jax.vmap(env.init_state)(jrandom.split(key, NUM_ENVS))

step_vmap = jax.vmap(lambda s, a: env.step(s, a, pool))
timesteps, states = step_vmap(states, actions)

这样得到的是批量的观测、动作与奖励,天然适配向量化策略网络与自对弈采样。完整脚本见 examples/vectorized_example.py。

团队与自由混战

同一个环境支持三种对局形态,通过构造参数切换:

env = GeneralsEnv(grid_dims=(15, 15))                     # 1v1
env = GeneralsEnv(grid_dims=(15, 15), num_players=4)      # 4 人自由混战
env = GeneralsEnv(grid_dims=(15, 15), teams=[0, 0, 1, 1]) # 2v2

N 人对局中,动作形状为 (N, 5),state.ownership 为 (N, H, W),观测与奖励同样按玩家维度堆叠。README 明确列出的多人规则包括:

  • 走到队友格子上会把兵力合并,并把该格转交给移动方;
  • 夺取对方将军后,受害者全部领地归捕获者,但所有兵力减半(向上取整),将军变为城堡,受害者出局、其动作被忽略;只要还有其他队伍存活,对局继续;
  • 一支队伍只有在全部将军均被攻陷后才算失败,最后存活的队伍获胜;info.winner 为获胜队伍 id,胜方全员奖励 +1,其余 -1;
  • 队伍内共享视野,观测中带有 allied_cells、allied_land_count、allied_army_count(无队友时全为零),opponent_* 则合并统计所有敌对队伍。

批量 2v2 / 自由混战 / 1v1 的 jax.jit 示例见 examples/multiplayer_example.py。

环境接口:观察与动作

每个玩家拿到的 Observation 是一组以 (H, W) 为主的场:armies(可见格兵力)、generals、castles(旧名 cities 保留为废弃别名)、mountains、owned_cells、opponent_cells、neutral_cells、fog_cells、structures_in_fog,外加若干标量统计:owned_land_count、owned_army_count、opponent_land_count、opponent_army_count、timestep。obs.as_tensor() 会把前 14 个字段堆成 (14, H, W) 张量,obs.as_tensor(include_allied=True) 再追加三路队友通道。

动作是长度 5 的整数数组 [pass, row, col, direction, split]:第 0 位为 1 表示跳过回合,1/2 位为源格行列,第 3 位方向取 0 上、1 下、2 左、3 右,第 4 位为 1 表示派出半数兵力、为 0 表示派出「全部减一」。合法动作可用 compute_valid_move_mask(obs.armies, obs.owned_cells, obs.mountains) 取得,返回 (H, W, 4) 的布尔掩码。

部署到 generals.io

训练好的智能体可以直接接到线上服务器对局:

from generals.remote import autopilot
from generals.agents import ExpanderAgent

autopilot(ExpanderAgent(), user_id="your_user_id", lobby_id="your_lobby")

user_id 需要在 generals.io 注册后获得。README 未给出更细的部署细节与稳定性说明。

学习建议

generals-bots 更适合已经了解强化学习基本流程、想研究策略与自对弈的读者。建议的阅读顺序是:先跑通基础对局循环,理解「状态池 + 自动重置」这一非典型设计;再进入向量化示例,把单局逻辑改造成批量训练采样;随后阅读观察与动作的定义,设计特征编码与合法动作掩码;最后尝试多人/团队规则,观察共享视野与兵力减半等机制对策略的影响。若关心它是否忠于原版规则,可参考 README 中提到的回放比对方法自行验证。项目在论文引用中给出标题为《Artificial Generals Intelligence: Mastering Generals.io with Reinforcement Learning》(arXiv:2507.06825),可作进一步阅读。

开源许可证与版权说明

许可证标识:未明确。源码、资源与依赖许可可能不同,请以官方仓库为准。本站仅做索引,不托管源码。

相似项目