状态： 维护中（预计会修复漏洞并进行少量更新）

Procgen 基准测试

[博客文章] [论文]

16个简单易用的程序化生成的 Gym 环境，能够直接衡量强化学习智能体在多大程度上能快速习得通用技能。这些环境以极高的运行速度（每秒数千步）运行于单核处理器之上。

我们在2020年举办了一场竞赛，利用这些环境来评估强化学习中的样本效率与泛化能力。您可以通过这里了解更多详情。

这些环境与论文【利用程序化生成来对强化学习进行基准测试】（https://cdn.openai.com/procgen.pdf）相关联。（参考文献：#citation）论文中部分实验的代码已收录在[train-procgen](https://github.com/openai/train-procgen) 仓库中。对于熟悉原始【CoinRun 环境】（https://github.com/openai/coinrun）的用户，请务必阅读下方更新后的 CoinRun 描述，因为该环境已发生了细微变化。

与【Gym Retro】相比，这些环境具有以下特点：

• 更快：Gym Retro 环境本身已经非常高效，而 Procgen 环境的运行速度可提升至 4 倍以上。
• 随机化：Gym Retro 环境始终一成不变，因此你只需记住一系列动作序列，就能获得最高奖励；而 Procgen 环境则采用随机化设计，因此无法做到这一点。
• 可定制化：如果你从源码安装，可以自由地对环境进行实验，甚至自定义环境。每个环境的环境特定代码往往少于 300 行。相比之下，在 Gym Retro 中几乎不可能实现这一点。

支持平台：

• Windows 10
• macOS 10.14（Mojave）、10.15（Catalina）
• Linux（manylinux2010）

支持 Python 版本：

• 3.7 64 位
• 3.8 64 位
• 3.9 64 位
• 3.10 64 位

支持 CPU：

• 至少需要支持 AVX 指令集

安装

首先，请确保你已安装支持的 Python 版本：

# 运行这些命令以检查正确的 Python 版本
python -c "import sys; assert (3,7,0) <= sys.version_info <= (3,10,0), 'Python 版本不正确'; print('ok')"
python -c "import platform; assert platform.architecture()[0] == '64bit', 'Python 不是 64 位'; print('ok')")

要安装 wheel 包：

pip install procgen

若出现类似“无法找到满足需求的 procgen 版本”的错误，请升级 pip：pip install --upgrade pip。

若想交互式地试用某个环境：

python -m procgen.interactive --env-name coinrun

按键包括：左/右/上/下 + Q、W、E、A、S、D，用于执行不同（依赖于环境）的动作。你的得分会显示在左下角，标注为“episode_return”。在某一回合结束时，你还可以查看最终的“episode_return”，以及“prev_level_complete”——如果成功完成关卡，则该值为 1。

要创建一个 Gym 环境的实例：

import gym
env = gym.make("procgen:procgen-coinrun-v0")

要创建一个 Gym3（向量化的）环境的实例：

from procgen import ProcgenGym3Env
env = ProcgenGym3Env(num=1, env_name="coinrun")

Docker

我们附带了一个 Dockerfile，用于演示一种基于 Docker 的最小化设置，该设置适用于运行随机代理。

docker build docker --tag procgen
docker run --rm -it procgen python3 -m procgen.examples.random_agent_gym

此外，还有一个用于从源码安装的 Dockerfile：

docker build . --tag procgen --file docker/Dockerfile.dev
docker run --rm -it procgen python -c "from procgen import ProcgenGym3Env; env = ProcgenGym3Env(num=1, env_name='coinrun'); print(env.observe())"

环境

观测空间是一个盒状空间，其中的 RGB 像素以 numpy 数组的形式呈现，形状为 (64, 64, 3)。人类玩家的预期步速为 15 赫兹。

动作空间为 Discrete(15)，对应需要按下哪些按钮组合。按钮组合已在 env.py 中定义。

如果你使用的是向量化环境，观测空间将转换为一个字典形式的空间，像素则存储在键 “rgb” 下。

以下是这 16 个环境：

图片	名称	描述
	bigfish	玩家以一条小鱼的身份开始游戏，通过食用其他鱼类逐渐变大。玩家只能食用比自己体型更小的鱼类，且这种大小的判定完全依据鱼体宽度。若玩家与一条体型更大的鱼类接触，便会遭到吞噬，游戏随即结束。玩家在食用较小的鱼类时可获得少量奖励；而当玩家的体型超过所有其他鱼类时，将获得丰厚奖励，此时游戏亦告结束。
	bossfight	玩家操控一艘小型星际飞船，必须摧毁一只体型远大于自己的Boss星际飞船。在与玩家交战时，Boss会随机从一组可能的攻击方式中选择一种。玩家需巧妙躲避来袭的弹道，否则将被摧毁。玩家还可以利用随机散布的流星作为掩护。经过一段预设时间后，Boss会变得脆弱，其护盾也会随之降低。此时，玩家的弹道攻击将对Boss造成伤害。一旦Boss受到一定数量的伤害，玩家将获得奖励，同时Boss会重新提升护盾强度。若玩家多次以这种方式对Boss造成伤害，Boss将被彻底摧毁，玩家将获得丰厚奖励，游戏也随之结束。
	caveflyer	玩家需在一片复杂的洞穴网络中航行，最终抵达出口。玩家的移动方式借鉴了Atari游戏《太空侵略者》：飞船可以旋转，并沿当前轴向向前或向后移动。大部分奖励都来自成功抵达关卡终点，不过玩家也可以通过使用飞船的激光武器摧毁沿途的目标物体来获取额外奖励。关卡中遍布着静止和移动的致命障碍物。
	chaser	该游戏灵感源自Atari游戏《MsPacman》。关卡布局采用Kruskal算法生成，随后逐步移除墙壁，直至洞穴中不再存在死胡同。玩家需收集所有绿色的球状物。当玩家收集到3颗大型星星时，这些星星会在短时间内使敌人变得脆弱。若与未处于脆弱状态的敌人发生碰撞，玩家将被击败。当敌人的生命值被消耗至一定程度时，地图上会生成一颗蛋，过一段时间后会孵化成新的敌人，从而保持敌人总数不变。玩家每收集一个球状物可获得少量奖励，而完成关卡则可获得丰厚奖励。
	climber	这是一款简单的平台跳跃游戏。玩家需攀爬一串平台，在途中收集星星。收集一颗星星可获得小额奖励，而收集全部星星则可获得更高奖励。若玩家成功收集所有星星，游戏即告结束。关卡中还散布着致命的飞行怪物。
	coinrun	这是一款简单的平台跳跃游戏。玩家的目标是收集关卡最右侧的硬币，而玩家则从关卡最左侧出发。代理需躲避静止的锯齿状障碍物、来回踱步的敌人，以及通往死亡的深谷。需要注意的是，此前发布的CoinRun版本会直接将速度信息绘制在观察数据上，而当前版本则未作此处理。这使得游戏环境变得更加艰难。
	dodgeball	该游戏 loosely 受Atari游戏《Berzerk》的启发。玩家出生在一个房间内，房间的墙壁和敌人分布随机。触碰墙壁会直接导致游戏结束，关卡就此终止。玩家的移动速度相对缓慢，可在整个房间内自由穿梭。游戏中还有缓慢移动的敌人，它们偶尔会向玩家投掷球状物。玩家也可以投掷球状物，但只能朝自己所面向的方向投掷。若所有敌人均被击中，玩家可前往解锁的平台，从而获得显著的关卡通关奖励。
	fruitbot	这是一款滚动式游戏，玩家需操控一台机器人，在墙缝间穿梭，并沿途收集水果。玩家每收集到一颗水果可获得正向奖励，而若误捡到非水果物品，则可获得更大的负向奖励。关卡中产生的物体有一半为水果（正向奖励），另一半为非水果（负向奖励）。如果玩家成功抵达关卡终点，将获得丰厚奖励。有时，玩家还需使用钥匙解锁那些阻挡道路的门。
	heist	玩家需盗取隐藏在锁链网络背后的宝石。每把锁都有三种不同的颜色，而开启这些锁所需的钥匙则散落在关卡各处。关卡布局呈迷宫形态，同样由Kruskal算法生成。当玩家收集到某一颜色的钥匙后，便可打开对应颜色的锁。玩家手中的所有钥匙都会显示在屏幕右上角。
	jumper	这是一款开放世界布局的平台跳跃游戏。玩家扮演一只兔子，需在广阔的世界中寻找胡萝卜。为了达成这一目标，玩家可能需要在关卡中上下起伏。玩家具备“双跳”能力，能够灵活穿梭于复杂多变的关卡布局，轻松抵达高处的平台。关卡中还布满了尖刺障碍物，一旦与之接触，玩家将被摧毁。屏幕上设有指南针，可显示玩家与胡萝卜之间的方向及距离。游戏唯一的奖励来自于收集胡萝卜，此时游戏即告结束。由于存在一个漏洞——玩家可以在关键物体（如障碍物或目标）上方重生——约7%的关卡会在一次操作后立即结束，而其中绝大多数关卡的奖励均为零。
	leaper	该游戏灵感源自经典游戏《青蛙过河》。玩家需穿越数条车道，最终抵达终点并获得奖励。第一条车道上布满了汽车，玩家需小心避开这些车辆。第二条车道上则铺满了漂浮在河面上的原木。玩家需从一根原木跳到另一根原木，顺利渡过河流。若玩家不慎跌入河中，游戏即告结束。
	maze	玩家扮演一只老鼠，需在迷宫中穿梭，找到唯一一块奶酪并获得奖励。迷宫由Kruskal算法生成，尺寸范围从3×3到25×25不等。迷宫的尺寸在该范围内均匀采样。玩家可通过上下左右移动，探索迷宫的各个角落。
	miner	该游戏灵感源自经典游戏《BoulderDash》。玩家扮演一只机器人，可挖掘泥土，从而在广阔的世界中自由穿梭。这个世界拥有重力，而泥土则支撑着巨石和钻石。巨石和钻石会从空隙中坠落，并相互滚落。若巨石或钻石砸中玩家，游戏即告结束。玩家的目标是收集关卡中的所有钻石，然后顺利驶出关卡。玩家每收集到一颗钻石可获得少量奖励，而完成关卡则可获得丰厚奖励。
	ninja	这是一款简单的平台跳跃游戏。玩家扮演一名忍者，需在狭窄的岩壁间跳跃，同时避开炸弹障碍物。玩家可从多个角度投掷飞星，以清除炸弹，必要时还可采取此策略。玩家的跳跃动作可在多个时间步中进行充能，从而增强跳跃效果。玩家在关卡终点收集到蘑菇后，即可获得奖励，游戏随即结束。
	plunder	玩家需通过发射炮弹，从屏幕底部的己方舰船对敌方海盗舰进行攻击，将其摧毁。屏幕上的计时器会缓缓倒计时。若计时器归零，游戏即告结束。每当玩家开火时，计时器会提前几步推进，鼓励玩家合理分配弹药。玩家需注意避免击中友军舰船。击中敌方舰船可获得正向奖励，而击中友军舰船则会面临高额计时器惩罚。左下角的目标会提示玩家要瞄准的敌方舰船颜色。
	starpilot	这是一款简单的横版射击游戏。对于人类玩家来说，游戏难度较高，因为所有敌人皆会发射直接瞄准玩家的弹道。若无法快速闪避，玩家将很快遭遇失败。游戏中既有快速行动的敌人，也有行动迟缓的敌人；既有生命值较高的固定炮塔，也有遮蔽玩家视线的云层，甚至还有难以逾越的流星。

已知问题

• bigfish——玩家有时可能会被困在环境的边界附近。
• caveflyer——在约 0.5% 的关卡中，玩家会在敌人的身旁生成，并且无论采取何种操作，都会在一步之内死亡。
• jumper——在约 7% 的关卡中，玩家会生成在敌人的上方或目标的上方，导致无论采取何种操作，关卡都会在一步之内结束。
• miner——存在较低的概率出现无法解决的关卡配置，要么钻石无法到达，要么出口无法抵达。

我们并不打算针对这些问题进行补丁修复，而是计划保持环境原样，以方便已发布结果的可重复性。

环境选项

• env_name——环境的名称，或者用逗号分隔的环境名称列表，用于在 VecEnv 中分别实例化每个环境。
• num_levels=0——可生成的唯一关卡数量。设置为 0 时，将使用无限多的关卡。
• start_level=0——用于生成关卡的最低种子值。start_level 和 num_levels 共同决定了可能的关卡集合。
• paint_vel_info=False——在左上角显示玩家的移动速度信息。仅在特定游戏中支持此功能。
• use_generated_assets=False——使用随机生成的资源，而非人工设计的资源。
• debug=False——若从源代码构建，将设置为 True 以启用调试模式。
• debug_mode=0——一个有用的标志，会传递给 Procgen 环境。在调试过程中可根据需要自行调整使用。
• center_agent=True——决定观察值是聚焦于代理，还是展示整个关卡。请自行承担风险进行覆盖。
• use_sequential_levels=False——当玩家到达关卡终点时，关卡将结束，同时选择新的关卡。如果将 use_sequential_levels 设置为 True，则到达关卡终点并不会终止整个关卡，新关卡的种子将基于当前关卡的种子生成。若将此设置与 start_level=<某个种子> 和 num_levels=1 结合使用，即可实现一条线性排列的关卡序列，类似于 gym-retro 或 ALE 游戏。
• distribution_mode="hard"——关卡的变体类型，可用选项包括 "easy"、"hard"、"extreme"、"memory"、"exploration"。所有游戏均支持 "easy" 和 "hard"，而其他选项则取决于具体游戏。默认为 "hard"。切换至 "easy" 可以减少每局游戏的步数，非常适合测试或在计算资源有限的情况下使用。
• use_backgrounds=True——通常情况下，游戏会使用人工设计的背景；若将此标志设置为 False，游戏将采用纯黑色背景。
• restrict_themes=False——部分游戏会从多个主题中选取资源；若将此标志设置为 True，这些游戏将只使用单一主题。
• use_monochrome_assets=False——若将此标志设置为 True，游戏将使用单色矩形，而非人工设计的资源。建议与 restrict_themes=True 一起使用。

以下是设置相关选项的方法：

import gym
env = gym.make("procgen:procgen-coinrun-v0", start_level=0, num_levels=1)

由于 gym 环境源自 gym3 环境，因此禁止过早调用 reset() 方法，且 render() 方法也不会执行任何操作。要渲染环境，请在构造函数中传入 render_mode="human"，这会将 render_mode="rgb_array" 传递给环境构造函数，并将其包装在 gym3.ViewerWrapper 中。如果您只想获取帧数据，而不希望看到窗口，则可传入 render_mode="rgb_array"。

对于 gym3 向量化的环境：

from procgen import ProcgenGym3Env
env = ProcgenGym3Env(num=1, env_name="coinrun", start_level=0, num_levels=1)

要使用 gym3 环境进行渲染，请传入 render_mode="rgb_array"。若您希望查看输出结果，可使用 gym3.ViewerWrapper。

保存与加载环境状态

如果您使用的是 gym3 接口，可以保存并加载环境状态：

from procgen import ProcgenGym3Env
env = ProcgenGym3Env(num=1, env_name="coinrun", start_level=0, num_levels=1)
states = env.callmethod("get_state")
env.callmethod("set_state", states)

此方法会返回一个字节字符串列表，用于表示向量化环境中每局游戏的状态。

注意事项

• 为了确保实验结果的可重复性，您应依赖特定版本的该库（通过 == 进行比较）。您可以使用 pip show procgen 来获取当前安装的版本。
• 本库无需使用 GPU，也未对 GPU 进行任何依赖或利用。
• 虽然该库应具备线程安全特性，但每个独立的环境实例只能由单个线程使用。除非将 num_threads 设置为 0，否则该库不支持多线程。即便您设置了 num_threads=0，Qt 也未必能保证线程安全，因此建议您在多线程环境下创建环境，或者干脆完全避免使用多线程。

从源代码安装

如果您想自定义环境或创建新环境，建议从源代码构建。如果您尚未安装 Miniconda，可前往 https://docs.conda.io/en/latest/miniconda.html 获取 Miniconda；或者手动从 environment.yml 中安装所需依赖项。在 Windows 系统上，您还需要安装 “Visual Studio 16 2019”。

git clone git@github.com:openai/procgen.git
cd procgen
conda env update --name procgen --file environment.yml
conda activate procgen
pip install -e .
# 应该显示“正在构建 procgen...完成”
python -c "from procgen import ProcgenGym3Env; ProcgenGym3Env(num=1, env_name='coinrun')"
# 应该会弹出一个窗口，让您能够体验 coinrun 环境
python -m procgen.interactive

环境代码采用 C++ 编写，并编译成共享库，公开了 gym3.libenv C 接口，随后由 Python 加载。C++ 代码使用 Qt 进行绘图。

创建新环境

在从源代码安装完成后，您可以自定义现有环境，或创建属于自己的新环境。若想打造一款快速的 C++ 2D 环境，您可以 fork 这个仓库并按照以下步骤操作：

• 将 src/games/bigfish.cpp 复制到 src/games/<name>.cpp。
• 在您的 C++ 文件中，将 BigFish 替换为 <name>，并将 "bigfish" 替换为 "<name>"。
• 将 src/games/<name>.cpp 添加到 CMakeLists.txt 中。
• 运行 python -m procgen.interactive --env-name <name> 进行测试。

该仓库包含 Travis CI 配置，可编译您的环境并构建 Python 轮子，以便轻松安装。若想通过缓存 Qt 编译过程来加快构建速度，您需要在 common.py 和 设置服务账号凭据 中配置 GCS 存储桶。

向信息字典中添加信息

要将 C++ 游戏代码中的游戏信息导出至 Python，您可以定义一个新的 info_type。info_type 会出现在 gym 环境返回的 info 字典中，或在 gym3 环境的 get_info() 中使用。

要定义一个新的 info_type，只需在 VecGame 构造函数中添加以下代码：vecgame.cpp

{
    struct libenv_tensortype s;
    strcpy(s.name, "heist_key_count");
    s.scalar_type = LIBENV_SCALAR_TYPE_DISCRETE;
    s.dtype = LIBENV_DTYPE_INT32;
    s.ndim = 0,
    s.low.int32 = 0;
    s.high.int32 = INT32_MAX;
    info_types.push_back(s);
}

这样，Python 代码便可以预期接收一个整数，并将其暴露在 info 字典中。

在添加上述代码后，您可以在 heist.cpp 中添加以下代码：

void observe() override {
    Game::observe();
    int32_t key_count = 0;
    for (const auto& has_key : has_keys) {
        if (has_key) {
            key_count++;
        }
    }
    *(int32_t *)(info_bufs[info_name_to_offset.at("heist_key_count")]) = key_count;
}

每次环境被观察时，该代码都会更新 heist_key_count 信息值。

如果您运行交互式脚本（确保已从源码安装），新键应该会显示在左下角：

python -m procgen.interactive --env-name heist

变更记录

请参阅 CHANGES 以了解各版本中新增的功能。

贡献方式

有关贡献方式的信息，请参阅 CONTRIBUTING。

资产

请参阅 ASSET_LICENSES 以获取资产许可证的相关信息。

引用格式

请使用以下 BibTeX 条目进行引用：

@article{cobbe2019procgen,
  title={利用程序化生成来评估强化学习},
  author={Cobbe, Karl and Hesse, Christopher and Hilton, Jacob and Schulman, John},
  journal={arXiv preprint arXiv:1912.01588},
  year={2019}
}

Procgen 快速上手指南

Procgen 是一个包含 16 个程序化生成环境的基准测试工具，专为评估强化学习（RL）智能体的泛化能力和样本效率而设计。这些环境基于 Gym 接口，单核运行速度极快（每秒数千步），且每次生成的关卡均随机变化，防止智能体死记硬背动作序列。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Windows 10、macOS (10.14+) 或 Linux (manylinux2010)。
• CPU 要求：必须支持 AVX 指令集。
• Python 版本：仅支持 64 位 Python，版本需在 3.7 到 3.10 之间。

您可以运行以下命令验证环境是否合规：

# 检查 Python 版本是否在 3.7 - 3.10 之间
python -c "import sys; assert (3,7,0) <= sys.version_info <= (3,10,0), 'python is incorrect version'; print('ok')"

# 检查是否为 64 位架构
python -c "import platform; assert platform.architecture()[0] == '64bit', 'python is not 64-bit'; print('ok')"

安装步骤

推荐使用国内镜像源（如清华源或阿里源）以加速安装过程。

1. 升级 pip（避免找不到对应版本的问题）：

   pip install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple
   

2. 安装 procgen：

   pip install procgen -i https://pypi.tuna.tsinghua.edu.cn/simple
   

基本使用

1. 交互式体验

安装完成后，您可以直接启动一个交互式窗口来试玩某个环境（例如 coinrun）。

python -m procgen.interactive --env-name coinrun

• 操作方式：使用方向键 (left/right/up/down) 或 q,w,e,a,s,d 进行控制（具体按键取决于环境）。
• 界面信息：左下角显示当前回合得分 (episode_return)；回合结束时显示最终得分及是否通关 (prev_level_complete)。

2. 代码调用 (Gym 接口)

在 Python 代码中创建标准的 Gym 环境实例：

import gym

# 创建 CoinRun 环境
env = gym.make("procgen:procgen-coinrun-v0")

obs = env.reset()
# 开始你的强化学习训练循环...

3. 代码调用 (向量化 Gym3 接口)

Procgen 原生支持高效的向量化环境（适合并行训练）：

from procgen import ProcgenGym3Env

# 创建包含 1 个环境的向量化实例
env = ProcgenGym3Env(num=1, env_name="coinrun")

# 获取观察值 (返回字典，像素数据在 "rgb" 键下)
obs = env.observe()
print(obs["rgb"].shape)  # 输出形状应为 (1, 64, 64, 3)

4. Docker 快速验证

如果您希望在不污染本地环境的情况下测试，可以使用 Docker：

# 构建镜像
docker build docker --tag procgen

# 运行随机智能体示例
docker run --rm -it procgen python3 -m procgen.examples.random_agent_gym