Procgen2（前身 Procgen）是一个提供高速程序化生成的横版卷轴图形环境的开源项目，专为强化学习设计。它的核心亮点是 CEnv 接口：游戏用 C/C++ 编写并编译成动态库（.so/.dylib/.dll），再由 Python 通过 cenv/cenv.py 直接加载调用——无需绑定代码、性能损失极小，即可获得符合 Gymnasium 规范的reset()/step()/render()完整环境 API。本教程将带你从零完成「编译 → 加载 → 交互」全流程。

1️⃣ 准备工作：环境与依赖清单

开始前请确认你的机器上已安装：

💡 为什么需要 SDL3？Procgen2 各游戏（如 coinrun）依赖 SDL3 的软件渲染来生成观察画面，这一点在开发指南 DEV_GUIDE.md 中有明确说明。

拿到源码：

git clone https://gitcode.com/gh_mirrors/pr/Procgen2 cd Procgen2

2️⃣ 了解项目结构：游戏在哪里

仓库中所有游戏都放在games/目录下，每个游戏是独立的 C++ 模块：

• games/coinrun/ —— 官方推荐参考的完整示例（cenv/USAGE_GUIDE.md 也指向它）
• games/chaser/、games/jumper/、games/maze/ 等共 7 个游戏
• cenv/ —— Python 侧加载器 cenv/cenv.py 与接口头文件 cenv/cenv.h

根目录的 CMakeLists.txt 已自动包含全部子游戏目录，因此只需在仓库根目录构建一次即可得到所有游戏的动态库。

3️⃣ 第一步：用 CMake 编译出动态库

在仓库根目录执行（对应各游戏 CMakeLists.txt 中add_library(... SHARED ...)的目标）：

mkdir build cd build cmake .. cmake --build .

构建完成后，你会在build/games/<游戏名>/下得到共享库，例如：

• build/games/coinrun/libCoinRun.so
• build/games/chaser/libChaser.so
• build/games/caveflyer/libCaveFlyer.so

📌 Windows 上产物为.dll，macOS 上为.dylib。文件名以实际构建输出为准，Python 加载时填入对应路径即可。

4️⃣ 第二步：用 Python 加载 CEnv 动态库

核心只需三行。CEnv类内部用ctypes.CDLL加载.so，自动绑定cenv_make、cenv_reset、cenv_step、cenv_render、cenv_close五个函数，并把观察空间/动作空间解析成标准 Gymnasium Space（详见 cenv/cenv.py）：

from cenv.cenv import CEnv import numpy as np env = CEnv("build/games/coinrun/libCoinRun.so") print(env.observation_space) # 观察空间定义 print(env.action_space) # 动作空间定义

支持可选参数：

# render_mode: "human" / "single_rgb_array" # options: 传递给 C 端 cenv_make 的键值选项，例如指定画面宽高 env = CEnv("build/games/caveflyer/libCaveFlyer.so", options={"width": 512, "height": 512})

5️⃣ 第三步：reset / step / render 完整交互循环

交互方式与任意 Gymnasium 环境完全一致。下面这个最小示例会随机行动并打印奖励（完整可运行版本见 game_test.py，它加载的是 chaser 并统计 FPS）：

obs, info = env.reset() for i in range(1000): action = np.random.randint(0, 16) # 动作可为 int 或 np.array obs, reward, terminated, truncated, info = env.step(action) if terminated: obs, info = env.reset() print("Resetting...")

想要实时观看画面？调用env.render()拿到 RGB 数组，即可用 pygame 显示。仓库自带的 interactive_viewer.py 是一个完整演示——加载 CaveFlyer，用键盘 WASD 控制、E 攻击、R 重置：

import pygame, pygame.surfarray import numpy as np width, height = 512, 512 screen = pygame.display.set_mode((width, height)) obs, info = env.reset() while True: obs, reward, term, trunc, info = env.step(action) if term: obs, info = env.reset() else: image = env.render() # (height, width, 3) uint8 数组 surf = pygame.surfarray.make_surface(np.swapaxes(image, 0, 1)) screen.blit(surf, (0, 0)) pygame.display.flip()

另外，观察本身也包含画面：obs["screen"]是 64×64×3 的图像观测，训练时无需依赖render()。

6️⃣ 常见问题排查

❓ 报OSError: cannot open shared object？动态库路径不对。CEnv第一个参数是.so的实际路径，相对当前 Python 工作目录，建议先用ls build/games/确认文件名。

❓cmake ..提示找不到 SDL3？先安装 SDL3 和 SDL3_image 开发包（Linux 包管理器搜索SDL3、SDL3_image相关包），再重新执行 CMake。

❓ 加载时抛Non-zero error code!？这是cenv_make返回了非 0 错误码，通常是渲染模式或 options 参数不被该游戏支持，检查render_mode与options键名（如width/height）。

❓ 想用别的语言写环境？CEnv 接口是纯 C 约定，任何能产出共享库并遵守 C 调用约定的语言都可以。接口定义见 cenv/cenv.h，最小 C 示例环境见 cenv/test_env.c 与 cenv/test_env.py。

7️⃣ 小结与延伸阅读

按「CMake 编译 → CEnv 加载动态库 → reset/step/render 循环」三步，你就把 Procgen2 的游戏接入了自己的强化学习训练流程。关键资料一览：

• CEnv 完整用法指南：cenv/USAGE_GUIDE.md
• Python 加载器实现：cenv/cenv.py
• 游戏开发规范（ECS、渲染器、资源管理）：DEV_GUIDE.md
• 完整游戏示例：games/coinrun/coinrun.cpp
• 性能测试脚本：game_test.py
• 交互式试玩脚本：interactive_viewer.py

祝你训练顺利，跑通第一个算法！🎮