generals-bots · strakam/generals-bots
面向 generals.io 的策略机器人开发库,使用 Python 编写,核心是基于 JAX 的高性能模拟器,供强化学习研究使用。仓库 topics 涵盖 gymnasium、pygame、强化学习与策略。README 自述支持 JIT 编译与 vmap 并行、内置图形界面用于可视化对...
generals-bots 是面向 generals.io 的策略机器人开发框架,目标是为强化学习研究提供一个快速的机器人开发平台。它并非 generals.io 的客户端复刻,而是一个用 Python 编写、以 JAX 为核心的高性能模拟器:环境状态不可变、轨迹可复现,便于做大规模自对弈与策略搜索实验。README 说明,模拟器遵循当前游戏规则,并曾用 2026 年进行的 10,000 场排位对局回放逐回合比对,与 generals.io 官方引擎的棋盘状态保持一致。
仓库自述的亮点包括:
vmap 实现大规模并行,README 宣称可达每秒千万级 step(属仓库自述指标,实际取决于硬件与网格规模,待核验);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) 的布尔掩码。
训练好的智能体可以直接接到线上服务器对局:
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),可作进一步阅读。
NBlood 是用 EDuke32 引擎技术与开发思路对 Build 引擎游戏所做的逆向工程移...
Frogatto & Friends 是一款 2D 横版动作冒险游戏,主角是一只青蛙;开发团队...
id Software 以 GPL 许可证发布的《雷神之锤3竞技场》(Quake III Arena)源...