我们最近注意到许多论文未能正确复现 MAPPO 的结果，这很可能是由于超参数描述不够详细所致。我们已在 /train/train_xxx_scripts/*.sh 中为每个地图或场景更新了训练脚本，欢迎大家尝试。

支持的环境：

• StarCraftII (SMAC)
• Hanabi
• 多智能体粒子世界环境 (MPEs)
• Google Research Football (GRF)
• StarCraftII (SMAC) v2

1. 使用方法

警告：默认情况下，所有实验都假设所有智能体共享同一策略，即只有一个神经网络供所有智能体使用。

核心代码位于 onpolicy 文件夹内。algorithms/ 子文件夹包含针对 MAPPO 的算法特定代码。

• envs/ 子文件夹包含 MPEs、SMAC 和 Hanabi 的环境封装实现。
• 用于执行训练 rollout 和策略更新的代码位于 runner/ 文件夹中——每个环境都有一个对应的 runner。
• 使用默认超参数进行训练的可执行脚本位于 scripts/ 文件夹中。文件名格式为 train_algo_environment.sh。在每个文件中，可以修改地图名称（对于 SMAC 和 MPEs）。
• 每个环境的 Python 训练脚本位于 scripts/train/ 文件夹中。
• config.py 文件包含相关的超参数和环境设置。大多数超参数已设置为论文中使用的值；不过，请参阅附录以获取完整的超参数列表。

2. 安装

以下是在 CUDA == 10.1 上的安装示例。对于非 GPU 及其他 CUDA 版本的安装，请参考 PyTorch 官网。需要注意的是，本仓库并不依赖于特定的 CUDA 版本，用户可以根据自己的电脑选择合适的 CUDA 版本。

# 创建 conda 环境
conda create -n marl python==3.6.1
conda activate marl
pip install torch==1.5.1+cu101 torchvision==0.6.1+cu101 -f https://download.pytorch.org/whl/torch_stable.html

# 安装 on-policy 包
cd on-policy
pip install -e .

尽管我们提供了 requirement.txt 文件，但其中可能存在冗余。建议用户在运行代码时，根据实际需要自行安装缺失的包。

2.1 StarCraftII 4.10

unzip SC2.4.10.zip
# 密码是 iagreetotheeula
echo "export SC2PATH=~/StarCraftII/" >> ~/.bashrc

• 下载 SMAC 地图，并将其移动到 ~/StarCraftII/Maps/。
• 若要使用 stableid，请从 https://github.com/Blizzard/s2client-proto.git 复制 stableid.json 到 ~/StarCraftII/。

对于 SMAC v2，请参考 https://github.com/oxwhirl/smacv2.git。请确保您的 SMAC_Maps 文件夹中包含 32x32_flat.SC2Map 地图文件。

2.2 Hanabi

Hanabi 的环境代码基于开源环境代码开发，但经过轻微修改以适配此处使用的算法。 安装步骤如下：

pip install cffi
cd envs/hanabi
mkdir build & cd build
cmake ..
make -j

Hanabi 的所有模型均可在此处下载：models。

2.3 MPE

# 首先安装此包
pip install seaborn

MPE 中包含 3 种合作场景：

• simple_spread
• simple_speaker_listener，即论文中的“Comm”场景
• simple_reference

2.4 GRF

请参阅 football 仓库以安装足球环境。

3. 训练

以下以 train_mpe.sh 为例：

cd onpolicy/scripts
chmod +x ./train_mpe.sh
./train_mpe.sh

本地结果将存储在 scripts/results 子文件夹中。请注意，我们默认使用 Weights & Biases 作为可视化平台；若要使用 Weights & Biases，需先注册并登录该平台。更多关于 Weights & Biases 的使用说明可在其官方文档中找到：文档。如果在命令行或 .sh 文件中添加 --use_wandb 参数，则会使用 TensorBoard 而不是 Weights & Biases。

我们还提供了 ./eval_hanabi_forward.sh，用于评估 Hanabi 在 10 万次试验中的得分。

4. 引用

如果您觉得本仓库有用，请引用我们的论文（https://arxiv.org/abs/2103.01955）：

@inproceedings{
yu2022the,
title={The Surprising Effectiveness of {PPO} in Cooperative Multi-Agent Games},
author={Chao Yu and Akash Velu and Eugene Vinitsky and Jiaxuan Gao and Yu Wang and Alexandre Bayen and Yi Wu},
booktitle={Thirty-sixth Conference on Neural Information Processing Systems Datasets and Benchmarks Track},
year={2022}
}

本指南帮助中国开发者快速部署并运行基于 PyTorch 的多智能体强化学习算法 MAPPO。

1. 环境准备

• 操作系统: Linux (推荐 Ubuntu)
• Python 版本: 3.6+ (官方示例使用 3.6.1)
• 深度学习框架: PyTorch (需匹配本地 CUDA 版本，官方示例为 CUDA 10.1 + Torch 1.5.1)
• 依赖环境:
  • StarCraft II (SMAC): 需单独安装 SC2 客户端及地图文件。
  • Hanabi: 需编译 C++ 扩展。
  • MPE/GRF: 需安装对应的 Python 环境包。
• 可视化工具: 默认使用 Weights & Biases (W&B)，也可切换为 TensorBoard。

注意：本仓库默认所有智能体共享同一个策略网络（Parameter Sharing）。

2. 安装步骤

2.1 创建虚拟环境并安装 PyTorch

以下以 CUDA 10.1 为例，其他版本请参考 PyTorch 官网 或替换对应版本号。

# 创建 conda 环境
conda create -n marl python==3.6.1
conda activate marl

# 安装 PyTorch (根据实际 CUDA 版本调整，国内用户可使用清华源加速)
pip install torch==1.5.1+cu101 torchvision==0.6.1+cu101 -f https://download.pytorch.org/whl/torch_stable.html
# 可选：使用清华源加速常规包安装
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

2.2 安装 on-policy 核心包

cd on-policy
pip install -e .

提示：requirements.txt 可能包含冗余依赖，建议先运行代码，缺什么装什么。

2.3 安装特定环境依赖 (按需选择)

A. StarCraft II (SMAC)

下载 SC2 客户端 (4.10 版本) 并配置路径：

unzip SC2.4.10.zip
# 解压密码为 iagreetotheeula
echo "export SC2PATH=~/StarCraftII/" >> ~/.bashrc
source ~/.bashrc

• 将 SMAC 地图文件移至 ~/StarCraftII/Maps/。
• 若需稳定 ID，将 stableid.json 复制至 ~/StarCraftII/。
• SMAC v2: 请参照 smacv2 安装，并确保 SMAC_Maps 文件夹中包含 32x32_flat.SC2Map。

B. Hanabi

需编译 C 扩展：

pip install cffi
cd envs/hanabi
mkdir build & cd build
cmake ..
make -j

C. MPE (Multiagent Particle-World)

pip install seaborn

D. GRF (Google Research Football)

请参考 football 官方仓库 进行安装。

3. 基本使用

3.1 开始训练

以 MPE 环境为例，进入脚本目录并赋予执行权限后运行：

cd on-policy/scripts
chmod +x ./train_mpe.sh
./train_mpe.sh

• 修改场景: 编辑 .sh 文件或查看 scripts/train/ 下的 Python 脚本，可更改地图名称（如 simple_spread, simple_speaker_listener 等）。
• 其他环境: 脚本命名规则为 train_algo_environment.sh (例如 train_mappo_smac.sh)。

3.2 结果可视化

• 默认: 使用 Weights & Biases (W&B)。首次使用需注册账号并登录。
• 切换 TensorBoard: 在命令行或 .sh 脚本中添加 --use_wandb 参数即可禁用 W&B 并启用 TensorBoard。
• 结果存储: 本地结果默认保存在 scripts/results 子文件夹中。

3.3 模型评估 (以 Hanabi 为例)

运行提供的评估脚本进行 10 万次试验评分：

./eval_hanabi_forward.sh

重要提示: 复现论文结果前，请务必检查关键超参数（如 rollout threads, episode length, ppo epoch, clip term 等）。针对不同地图/场景的优化脚本已更新至 /train/train_xxx_scripts/*.sh，建议优先使用这些脚本。