gym-超级马里奥兄弟

一个基于 OpenAI Gym 的环境，用于在任天堂娱乐系统（NES）上运行《超级马里奥兄弟》和《超级马里奥兄弟2：失落关卡》，使用了 nes-py 模拟器。

安装

推荐通过 pip 安装 gym-super-mario-bros：

pip install gym-super-mario-bros

使用

Python

在尝试创建环境之前，必须先导入 gym_super_mario_bros。这是因为 Gym 环境是在运行时注册的。默认情况下，gym_super_mario_bros 环境使用 NES 的完整动作空间，包含 256 种离散动作。为了限制动作范围，gym_super_mario_bros.actions 提供了三个动作列表（RIGHT_ONLY、SIMPLE_MOVEMENT 和 COMPLEX_MOVEMENT），供 nes_py.wrappers.JoypadSpace 包装器使用。有关这三个列表中合法动作的详细说明，请参阅 gym_super_mario_bros/actions.py。

from nes_py.wrappers import JoypadSpace
import gym_super_mario_bros
from gym_super_mario_bros.actions import SIMPLE_MOVEMENT
env = gym_super_mario_bros.make('SuperMarioBros-v0')
env = JoypadSpace(env, SIMPLE_MOVEMENT)

done = True
for step in range(5000):
    if done:
        state = env.reset()
    state, reward, done, info = env.step(env.action_space.sample())
    env.render()

env.close()

注意： gym_super_mario_bros.make 只是 gym.make 的别名，方便使用。

注意： 在训练代码中移除对 render 的调用可以显著提升速度。

命令行

gym_super_mario_bros 提供了一个命令行界面，可以通过键盘或均匀随机移动来游玩环境。

gym_super_mario_bros -e <要游玩的环境ID> -m <`human` 或 `random`>

注意： 默认情况下，-e 设置为 SuperMarioBros-v0，-m 设置为 human。

注意： SuperMarioBrosRandomStages-* 支持 --stages/-S 标志，用于指定要从中随机选择关卡的集合，例如 -S 1-4 2-4 3-4 4-4。

环境

这些环境允许玩家有 3 次机会（生命值）通关游戏中的 32 个关卡。环境只会将可获得奖励的游戏画面发送给智能体；过场动画、加载屏幕等不会从 NES 模拟器传递给智能体，智能体在这些期间也无法执行动作。如果无法通过修改 NES 的 RAM 来跳过过场动画，环境会锁定 Python 进程，直到模拟器准备好进行下一步操作。

环境	游戏	ROM	截图
SuperMarioBros-v0	SMB	标准
SuperMarioBros-v1	SMB	下采样
SuperMarioBros-v2	SMB	像素化
SuperMarioBros-v3	SMB	矩形化
SuperMarioBros2-v0	SMB2	标准
SuperMarioBros2-v1	SMB2	下采样

单个关卡

这些环境允许玩家仅有一次机会（一次生命）通关游戏中的单个关卡。

使用以下模板：

SuperMarioBros-<世界>-<阶段>-v<版本>

其中：

• <世界> 是一个介于 1 到 8 之间的数字，表示游戏中的世界；
• <阶段> 是一个介于 1 到 4 之间的数字，表示某个世界中的具体关卡；
• <版本> 是一个介于 0 到 3 之间的数字，用于指定使用的 ROM 模式：
  • 0：标准 ROM
  • 1：下采样 ROM
  • 2：像素化 ROM
  • 3：矩形化 ROM

例如，要在下采样 ROM 上游玩 4-2 关卡，可以使用环境 ID SuperMarioBros-4-2-v1。

随机关卡选择

随机关卡选择环境会随机选取一个关卡，并允许玩家尝试通关。一旦玩家死亡并调用 reset 方法，环境就会再次随机选择一个新的关卡。目前此功能仅适用于标准版《超级马里奥兄弟》，而不适用于《失落关卡》。要使用这些环境，只需在 SuperMarioBros 的 ID 后加上 RandomStages。例如，若要使用标准 ROM 并结合随机关卡选择功能，可以使用 SuperMarioBrosRandomStages-v0。若想固定随机种子，可在调用 reset 之前使用环境的 seed 方法，如 env.seed(222)，或者直接在 reset 方法中传入 seed 参数，例如 reset(seed=222)。

除了可以从全部 32 个原始关卡中随机选择外，还可以指定用户自定义的关卡子集，以将随机选择范围限定在特定子集中。例如，可以选择只包含城堡关卡、水下关卡、地下关卡等。

要指定一个关卡子集用于随机抽选，可以创建一个允许被抽选的关卡列表，并将其传递给 gym.make() 函数。例如：

gym.make('SuperMarioBrosRandomStages-v0', stages=['1-4', '2-4', '3-4', '4-4'])

上述示例将在每次调用 reset 时，从 1-4、2-4、3-4 和 4-4 中随机选择一个关卡。

步骤

关于 step 方法返回的奖励和信息的相关说明。

奖励函数

奖励函数假设游戏的目标是尽可能向右移动（增加智能体的 x 值），同时尽可能快地移动，且不能死亡。为了建模这个游戏，奖励由三个独立的变量组成：

1. v：状态之间智能体 x 值的差值
   • 在这种情况下，它表示当前步骤的瞬时速度
   • v = x1 - x0
     • x0 是步骤前的 x 位置
     • x1 是步骤后的 x 位置
   • 向右移动 ⇔ v > 0
   • 向左移动 ⇔ v < 0
   • 不动 ⇔ v = 0
2. c：帧之间游戏时钟的差值
   • 这个惩罚项可以防止智能体静止不动
   • c = c0 - c1
     • c0 是步骤前的时钟读数
     • c1 是步骤后的时钟读数
   • 没有时钟滴答 ⇔ c = 0
   • 有时钟滴答 ⇔ c < 0
3. d：死亡惩罚项，用于惩罚智能体在某个状态下死亡
   • 这个惩罚项鼓励智能体避免死亡
   • 生存 ⇔ d = 0
   • 死亡 ⇔ d = -15

r = v + c + d

奖励会被截断到区间 (-15, 15)。

info 字典

step 方法返回的 info 字典包含以下键：

键	类型	描述
coins	int	收集到的金币数量
flag_get	bool	如果马里奥到达了旗帜或斧头，则为真
life	int	剩余的生命数，即 {3, 2, 1}
score	int	累积的游戏分数
stage	int	当前关卡，即 {1, ..., 4}
status	str	马里奥的状态，即 {'small', 'tall', 'fireball'}
time	int	时钟剩余的时间
world	int	当前世界，即 {1, ..., 8}
x_pos	int	马里奥在关卡中的 x 位置（从左侧算起）
y_pos	int	马里奥在关卡中的 y 位置（从底部算起）

引用

如果您在研究中使用了 gym-super-mario-bros，请引用它。

@misc{gym-super-mario-bros,
  author = {Christian Kauten},
  howpublished = {GitHub},
  title = {{S}uper {M}ario {B}ros for {O}pen{AI} {G}ym},
  URL = {https://github.com/Kautenja/gym-super-mario-bros},
  year = {2018},
}

gym-super-mario-bros 快速上手指南

gym-super-mario-bros 是一个基于 OpenAI Gym 接口构建的超级马里奥兄弟（NES 版）强化学习环境。它使用 nes-py 模拟器，支持标准的《超级马里奥兄弟》及《超级马里奥兄弟 2》（失落的关卡）。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux 或 macOS (Windows 支持可能受限，建议在 WSL 或 Docker 中运行)
• Python 版本: 3.6 - 3.9 (推荐 Python 3.8+)
• 前置依赖:
  • gym: 强化学习框架
  • nes-py: NES 模拟器核心
  • numpy: 数值计算库

提示：国内用户建议使用清华源或阿里源加速安装过程。

安装步骤

推荐使用 pip 进行安装。

1. 基础安装

直接使用 pip 安装最新稳定版：

pip install gym-super-mario-bros

2. 国内加速安装（推荐）

如果您在中国大陆，使用镜像源可以显著提升下载速度：

pip install gym-super-mario-bros -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

Python 代码示例

以下是最小化的运行示例，展示了如何创建环境、限制动作空间并运行游戏循环。

注意：

1. 必须先导入 gym_super_mario_bros 以注册环境。
2. 默认动作空间包含 256 种组合，建议使用 JoypadSpace 包装器将其简化为常用动作（如 SIMPLE_MOVEMENT）。
3. 训练时请注释掉 env.render() 以获得显著的速度提升。

from nes_py.wrappers import JoypadSpace
import gym_super_mario_bros
from gym_super_mario_bros.actions import SIMPLE_MOVEMENT

# 1. 创建环境 (别名：gym_super_mario_bros.make 等同于 gym.make)
env = gym_super_mario_bros.make('SuperMarioBros-v0')

# 2. 应用动作空间包装器 (将动作限制为简单的移动和跳跃)
env = JoypadSpace(env, SIMPLE_MOVEMENT)

done = True
for step in range(5000):
    if done:
        # 重置环境，如果是新回合则返回初始状态
        state = env.reset()
    
    # 执行随机动作
    state, reward, done, info = env.step(env.action_space.sample())
    
    # 渲染画面 (仅在调试/演示时开启，训练时请关闭)
    env.render()

env.close()

命令行试玩

该工具内置了命令行界面，可以直接通过键盘或随机策略玩游戏。

基本命令格式：

gym_super_mario_bros -e <环境 ID> -m <模式：human 或 random>

示例：启动默认环境并使用键盘控制

gym_super_mario_bros
# 等价于：gym_super_mario_bros -e SuperMarioBros-v0 -m human

示例：指定特定关卡版本并观察随机游走

gym_super_mario_bros -e SuperMarioBros-4-2-v1 -m random

常用环境 ID 说明

环境 ID	描述
SuperMarioBros-v0	标准 ROM，完整游戏 (32 关，3 条命)
SuperMarioBros-v1	下采样 ROM (分辨率更低，适合快速训练)
SuperMarioBros-<世界>-<关卡>-v<版本>	单关卡模式 (例如：SuperMarioBros-1-1-v0)
SuperMarioBrosRandomStages-v0	随机关卡模式 (每次重置随机选择一关)