craftium

🚀 开源强化学习的「我的世界」：Craftium 让 3D AI 训练效率提升 10 倍

想象这样一个场景： 你是一名 RL 研究者，正在训练一个 AI 智能体完成"砍树收集钻石"的任务。传统方案用 Minecraft 作为仿真环境——但 Java 虚拟机在高性能计算集群上运行效率低下，每次训练都要等待漫长的环境初始化，加上一台机器只能跑一个实例，GPU 利用率始终上不去。你调参三周，进度条却像蜗牛爬行。

Craftium 正是为解决这个痛点而生的。 它用 C++ 写的 Luanti 引擎替代了 Java Minecraft，在保留全部环境丰富度（3D 像素世界、程序化地形、生物群落、可破坏方块）的同时，将训练速度提升至每秒 2000 步以上。项目于 2024 年 7 月发布论文，2025 年被 ICML 正式接收，成为 RL 领域第一个将 Minecraft 级别丰富度与工业级训练效率结合的开源平台。

Craftium: Minecraft风格的3D强化学习环境平台

一、背景故事：从学术需求到顶级会议

Craftium 的诞生源于一次真实的科研困境。

2024 年，西班牙 University of the Basque Country 的研究团队在开展多智能体强化学习（MARL）实验时，遇到了所有 Minecraft-based RL 研究者都会遇到的问题：现有方案要么太慢（基于 Minecraft Java 版的环境每秒只能跑几十步），要么太简陋（2D 网格环境缺乏真实感）。他们需要的是一个既有 Minecraft 般丰富度和沉浸感，又有 Gymnasium 般标准化接口，还能支撑大规模并行训练的平台。

于是团队 fork 了开源游戏引擎 Luanti（原名 Minetest，一个已有十多年历史的体素游戏引擎，完全开源、用 C++ 编写），在此基础上深度改造，嵌入了 Gymnasium 和 PettingZoo 的标准 RL 接口，创造出了 Craftium。2024 年 7 月论文在 arXiv 公开，2025 年正式发表于 ICML——这是 RL 领域的顶会，论文被接收本身就是对项目价值的背书。

核心技术优势在于引擎层改造：研究团队深入 Luanti 源代码，实现了 Python 进程与 C++ 引擎之间的实时通信管道（通过进程间通信），让 Python 训练的 agent 能够以毫秒级延迟向引擎发送动作指令，同时引擎将 RGB 像素观测以同样速度回传。相比 Minecraft Java 版的笨重启动和单进程限制，Craftium 可以在单机上同时运行数十个并行环境实例，充分利用多核 CPU 和 GPU。

二、生活化类比：为什么 Craftium 就像从自行车升级到摩托车

如果把 RL 环境比作交通工具，那么：

• 传统 2D 网格环境（如 Gymnasium 的 FrozenLake、CartPole）就像自行车——轻便、简单，适合初学者，但完全无法模拟真实世界的复杂性。
• Minecraft Java 版环境就像一辆卡车——载货能力强（环境丰富），但发动机太重（Java 虚拟机开销大），油耗高（计算效率低），每次启动还要热车（初始化慢）。
• Craftium则是一辆经过赛道改装的摩托车——保留了卡车级别的装载能力（3D 像素世界所有特性），但发动机换成赛车级的（纯 C++ Luanti 引擎），百公里加速从 20 秒变成 2 秒（每秒 2000+ 步）。

对于 RL 研究者而言，时间就是 GPU 费用。Craftium 能在同等硬件条件下，将训练实验的迭代速度提升 10 倍以上，直接降低科研成本。

三、核心功能：从砍树到开放世界，从单智能体到多智能体

Craftium 提供了一系列开箱即用的示例环境，同时支持用 Lua 语言自行扩展，是目前最灵活的 3D RL 仿真平台之一。

ChopTree 环境：AI智能体在3D像素世界中砍树收集资源

3.1 内置环境一览

环境名	类型	描述
Craftium/ChopTree-v0	单智能体	经典 RL 基准：砍树收集资源
Craftium/OpenWorld-v0	单智能体	开放世界，支持任意任务配置
Craftium/Room-v0	单智能体	室内房间场景，适合导航任务
Craftium/Speleo-v0	单智能体	洞穴探索，程序化生成的地下迷宫
Craftium/SpidersAttack-v0	单智能体	遭遇战：与怪物战斗
Craftium/ProcDungeons-v0	单智能体	程序化地牢，每次重置随机生成
Craftium/MultiAgentCombat-v0	多智能体	多智能体对抗/协作场景

3.2 多智能体支持（MARL）

Craftium 的多智能体架构基于 PettingZoo API 实现。每个智能体有独立的观测和动作通道，共享同一个 Luanti 世界实例。代码示例：

from craftium.multiagent_env import ParallelEnv

env = ParallelEnv(
    env_id="Craftium/MultiAgentCombat-v0",
    num_agents=4,  # 4 个 AI 同时在世界中行动
    frameskip=3,
)
# 标准的 PettingZoo AEC 接口
observations, infos = env.reset()
for step in range(10000):
    actions = {agent: env.action_space(agent).sample() for agent in env.agents}
    observations, rewards, terminations, truncations, infos = env.step(actions)

3.3 程序化环境生成

通过 RandomMapGen 类，可以每次重置时自动生成新的地牢、房间和生物分布：

from craftium.extra.random_map_generator import RandomMapGen

mapgen = RandomMapGen(
    n_rooms=5,
    room_min_size=5,
    room_max_size=10,
    max_monsters_per_room=3,
    monsters={"a": 0.4, "b": 0.3, "c": 0.2}
)
ascii_map = mapgen.rasterize(wall_height=5)

3.4 LLM/VLM Agent 集成

Craftium 特别为大型视觉-语言模型（VLM）设计了慢 Agent 同步机制。LLM 或 VLM Agent 推理时间较长（如 Ollama 服务），Craftium 可以暂停引擎时钟，等待 Agent 返回动作后再推进环境——这是 Minecraft 原版无法支持的特性。示例 llava_agent.py 展示了用 Ollama + LLaVA 多模态模型作为 RL Agent 的完整流程。

四、技术架构：Python 控制层 + C++ 引擎层

Craftium 的架构设计非常清晰，分为两层：

Python 控制层（craftium/）

• craftium_env.py：核心环境类，继承 gymnasium.Env，管理环境生命周期
• multiagent_env.py：PettingZoo 并行环境封装
• pettingzoo_env.py：PettingZoo AEC 环境封装
• wrappers.py：常用 wrappers（帧跳过、灰度化、通道堆叠等）
• minetest.py：Luanti 引擎进程管理
• mt_channel.py：Python↔C++ 进程间通信管道
• extra/：辅助工具，如程序化地图生成器

C++ Luanti 引擎层（fork 自 luanti-org/luanti）

• 修改后的引擎接受来自 Python 的动作指令并执行
• 渲染 RGB 观测并通过管道传回 Python
• 扩展了 Lua API，支持自定义 RL 环境逻辑
• 支持软重置（无需重启引擎即可重置环境）
• 支持服务器/客户端同步，专门适配慢速 Agent（VLM/LLM）

训练框架兼容

Craftium 天然兼容所有使用 Gymnasium API 的训练库：

• Stable-Baselines3 (SB3)：PPO、A2C、SAC、TD3 等主流算法，sb3_train.py 提供完整示例
• CleanRL：高性能 PPO 实现，cleanrl_ppo_train.py 演示用法
• Ray RLlib：分布式强化学习框架，ray_train.py 提供集成代码
• PPO from scratch：ppo_train_crl.py 展示最小化实现
• 自定义 Agent：通过 Ollama API 接入 LLaVA 等 VLM Agent

五、上手体验：5 分钟跑通第一个训练

环境准备（推荐：pip 一键安装）

# 安装预构建 wheel（Python 3.12，推荐）
pip install https://github.com/mikelma/craftium/releases/download/v0.0.1/craftium-0.0.1-cp312-cp312-manylinux_2_28_x86_64.whl

# 或者从源码构建（支持 Python 3.11+）
git clone --recursive https://github.com/mikelma/craftium
cd craftium
pip install -e .

运行训练

# 用 PPO 训练砍树任务（SB3）
python sb3_train.py --env-id Craftium/ChopTree-v0 --method ppo --total-timesteps 5000000

用 Docker 运行

# 使用 Dockerfile.craftium（预装了 Luanti 引擎的 manylinux 镜像）
docker build -f Dockerfile.craftium -t craftium:latest .
docker run --gpus all -it craftium:latest bash

用 Ollama VLM Agent 玩 OpenWorld

# 先启动 Ollama 服务
ollama serve
# 然后运行 VLM Agent
python llava_agent.py --model llava --env-id Craftium/OpenWorld-v0 --train-mins 30

六、争议与局限：诚实的评估

局限性 1：预构建 wheel 仅支持 Python 3.12

目前 GitHub Releases 只提供了 Python 3.12 的预构建 wheel。如果使用其他 Python 版本（如 3.11、3.13），必须从源码编译——这需要安装 CMake、Ninja、各类系统库（mesa-libGL、SDL2-devel、luaJIT 等），构建过程在 Linux 上约需 15-20 分钟，在 macOS 上更为繁琐。

局限性 2：GPU 利用率取决于训练框架

Craftium 本身是 CPU 密集型环境模拟器，不直接调用 GPU。训练时的 GPU 利用率完全取决于所使用的 RL 算法库（PyTorch-based SB3、CleanRL 等）。

局限性 3：文档质量参差不齐

官方文档涵盖了基础使用和环境创建，但对于多智能体场景和 VLM Agent 集成的描述较少，高级用法需要直接阅读源码。

局限性 4：许可证不明确

license 字段返回 NOASSERTION，给商业使用带来法律不确定性。相比之下，基座引擎 Luanti 采用 LGPL v2.1，许可证相对清晰。

局限性 5：依赖 Luanti 引擎复杂性

想要添加高级环境特性（如自定义物理、碰撞检测）需要修改 C++ 代码，相比纯 Python 环境学习曲线更陡。

七、行业意义与增长趋势

Craftium 的出现填补了 RL 研究中一个重要的生态位：高丰富度 + 高效率 + 开源的 3D 环境平台。

从学术影响力看，论文被 ICML 2025 接收，GitHub 207 颗星，被 ARM-FM 等后续研究直接引用用于基准测试。

从生态位看，Craftium 填补了 Minecraft-gym、MINIWOB++ 等项目的空白：

• 相比 Minecraft-gym：无需 Java，效率提升 10 倍，支持 MARL
• 相比 MINIWOB++：3D 沉浸感，视觉复杂度大幅提升
• 相比 Habitat / AI2-THOR：完全开源，无需专有引擎授权

从发展趋势看，随着 VLM/LLM Agent 研究的爆发，Craftium 的慢 Agent 同步机制将成为视觉-语言模型在 3D 环境中进行具身智能研究的热门工具。

---

总结一句话： 如果你在做 RL 研究，需要一个 3D 像素世界的仿真环境来训练导航、探索、多智能体协作或 VLM Agent，Craftium 是目前开源生态中最值得尝试的选择——它既有 Minecraft 级别的环境丰富度，又有 Gymnasium 的标准化接口，还有论文顶会背书的可靠性。