minecraft_rl_tutorial

Minecraft RL：从手工建城到智能体自动建造（中文教程）

本书面向希望把 Minecraft 作为“可交互、可编程、可评测”的三维沙盒世界，用于 强化学习（RL）/模仿学习（IL）/大模型智能体（LLM Agent）研究与工程实践的人。

你将从 Minecraft 的基本概念出发，学习手工搭建城市级构造的方法论，再进入RL 环境/API 选型与任务建模，最后落到Claude/GPT 等 LLM 如何规划与建造、以及如何控制“小人”（Bot/Agent）稳定执行。

仓库结构

index.md（你正在阅读）
chapter1.md ～ chapter12.md
（可选）assets/：图片、示意图、结构截图
（可选）code/：示例代码（Python/JS）、训练脚本、配置文件
（可选）schematics/：Litematica / schematic / structure 文件
（可选）worlds/：示例世界存档（不建议直接提交大文件，可用下载链接）

阅读路线建议

只想快速跑通 RL 环境：第 1 章 → 第 5–8 章 → 第 10 章
只想学习“手工建城”的系统方法：第 1–4 章
想做 LLM 自动建造/Agent：第 1 章 → 第 6 章 → 第 9–11 章
想做城市级端到端系统：按顺序读完第 1–11 章

章节目录（Chapters & Sections）

下面列出每个 chapterX.md 的计划内容：章节简介 + 详细小节清单（含子小节）。
每章的标题结构建议采用 # / ## / ### 三级标题，便于自动生成目录与跨章链接。

Chapter 1 — `chapter1.md`：Minecraft 基础概念（给 RL/Agent 的“世界说明书”）

1.1 Minecraft 是什么：沙盒、规则与可计算性

1.1.1 方块世界与离散网格（Block / Chunk / Region）
1.1.2 生存 / 创造 / 冒险：对实验设定的影响
1.1.3 单人世界 vs 服务器：同步、延迟与可控性

1.2 世界构成：地形、结构与维度

1.2.1 主世界 / 下界 / 末地：差异与任务可行性
1.2.2 结构生成与随机种子（Seed）的实验意义
1.2.3 生物群系与资源分布：对采集/建造的约束

1.3 坐标系与空间方位（Agent 必须“对齐”的语言）

1.3.1 坐标 (x, y, z) 与高度 y
1.3.2 朝向（Yaw/Pitch）与相机视角
1.3.3 距离度量、碰撞箱与可达性

1.4 方块、物品、工具与合成

1.4.1 物品栏/背包/快捷栏：观测与动作接口
1.4.2 合成与配方：树状依赖（crafting graph）
1.4.3 工具效率与耐久：对 reward/时间成本的影响

1.5 红石与命令（可编程“世界内自动化”）

1.5.1 红石基础：信号、逻辑与时序
1.5.2 命令方块 / 数据包：测试与任务脚本化
1.5.3 结构方块、NBT 与存档：可复现构造的载体

1.6 面向 RL 的关键抽象

1.6.1 “环境状态”在 Minecraft 中可能是什么
1.6.2 动作粒度：高层动作 vs 逐 tick 控制
1.6.3 复杂任务：稀疏奖励与长时序信用分配

Chapter 2 — `chapter2.md`：手工建城方法论（城市级构造的“设计蓝图”）

2.1 城市级构造的定义与尺度（从村庄到都市）

2.1.1 城市元素清单：道路、分区、地标、公共空间
2.1.2 尺度与比例：街宽、楼高、密度、天际线
2.1.3 风格约束：中世纪/现代/赛博/日式等

2.2 规划流程（从 0 到 1 的总体设计）

2.2.1 需求：主题、功能、叙事与可玩性
2.2.2 选址：地形适配与资源条件
2.2.3 分区：居住/商业/工业/行政/绿地
2.2.4 交通骨架：主干路、支路、步行系统、桥梁

2.3 模块化设计（让城市“可复制、可扩展、可自动化”）

2.3.1 模块：街区（block）、地块（lot）、建筑原型
2.3.2 连接规则：道路接口、地形接口、立面接口
2.3.3 “构件库”思维：窗、门、屋顶、立柱、装饰件

2.4 视觉统一与材料体系

2.4.1 调色盘：主材/辅材/点缀材
2.4.2 纹理尺度：大面、分割、细节噪声
2.4.3 光照：自然光、灯具、氛围与夜景

2.5 从规划到施工的交付物

2.5.1 总平面图（道路+分区）
2.5.2 街区模板与建筑图鉴
2.5.3 施工顺序与检查清单

Chapter 3 — `chapter3.md`：手工建城施工法（地形 → 骨架 → 街区 → 细节）

3.1 地形工程（Terraforming）

3.1.1 平整、抬高、挖掘与自然过渡
3.1.2 水系：河道、码头、运河与海岸线
3.1.3 性能与美观：细节密度的取舍

3.2 城市骨架先行：道路与基础设施

3.2.1 道路断面：路面、人行道、绿化带
3.2.2 交叉口与转角：可读性与节奏
3.2.3 桥梁、隧道、台阶与坡道（无障碍“动线”）

3.3 街区落地：地块划分与建筑放置

3.3.1 地块尺寸与建筑退线
3.3.2 建筑高度控制与天际线
3.3.3 空间节奏：开阔—拥挤—开阔

3.4 立面与细节：让城市“活起来”

3.4.1 立面分层：底层商业 / 中段 / 屋顶
3.4.2 细节资产：标识、路灯、广告、管线、家具
3.4.3 植被与道具：树阵、花坛、长椅、摊位

3.5 城市可玩性与叙事

3.5.1 地标引导：玩家视线与路径引导
3.5.2 功能场景：市场、学校、车站、工厂、港口
3.5.3 “生活感”：重复中引入微差异

Chapter 4 — `chapter4.md`：建造工具与工程化工作流（为“可复用/可自动化”铺路）

4.1 原版工具链（无需模组）

4.1.1 创造模式常用操作与快捷实践
4.1.2 命令：填充/克隆/结构保存
4.1.3 结构方块（Structure Block）的城市模块化

4.2 常用建造效率工具（模组/插件生态概览）

4.2.1 WorldEdit 类：批量编辑与笔刷
4.2.2 Litematica 类：投影蓝图与 schematic 管理
4.2.3 地图/规划辅助：网格、标注与测距

4.3 数据与版本管理（让成果可复现）

4.3.1 世界存档与种子管理
4.3.2 schematic/structure 的版本化策略
4.3.3 构件库组织：命名规范与元数据

4.4 面向 RL/Agent 的“可控场景”制作

4.4.1 训练场：平地、标定点、障碍与测试路线
4.4.2 任务脚本：重置、计时、计分与终止条件
4.4.3 日志与回放：复盘 agent 行为

Chapter 5 — `chapter5.md`：强化学习基础与 Minecraft 任务建模

5.1 Minecraft 作为 MDP/POMDP

5.1.1 状态、观测、动作、奖励、终止
5.1.2 部分可观测：视角限制与记忆
5.1.3 长时序任务：稀疏奖励与探索难题

5.2 动作空间设计（最关键的工程选择之一）

5.2.1 低层动作：移动/转向/交互（细粒度）
5.2.2 高层动作：导航到点、放置结构、执行蓝图
5.2.3 分层控制：Options / Skills / BT（行为树）/ HTN

5.3 奖励设计与课程学习（Curriculum）

5.3.1 形状化奖励（Shaping）的边界
5.3.2 子目标序列：采集→加工→搭建→装饰
5.3.3 失败样本与惩罚：避免训练崩坏

5.4 评测与对标（Benchmarks）

5.4.1 成功率、时间、资源消耗
5.4.2 结构正确性：与目标蓝图的差异度量
5.4.3 泛化：新地形/新材料/新布局

Chapter 6 — `chapter6.md`：Minecraft 的 RL 环境与 API 全景（选型指南）

6.1 环境选型维度（你真正需要什么）

6.1.1 观测：RGB/深度/方块网格/语义
6.1.2 动作：离散/连续、tick 级控制、宏动作
6.1.3 重置与速度：训练吞吐、并行、稳定性
6.1.4 版本与生态：原版/模组/服务端

6.2 常见 RL 环境/平台（概览）

6.2.1 Project Malmo 系（基于 Minecraft + 任务 XML/脚本）
6.2.2 MineRL 系（数据集、基准任务、Gym 风格封装）
6.2.3 自建环境：服务端插件/模组 + 自定义观测/动作

6.3 Bot 控制与编程接口（不只 RL）

6.3.1 Mineflayer（JS bot）与生态插件
6.3.2 路径规划/自动挖掘（如 Baritone 类思路）
6.3.3 服务器插件（Spigot/Paper 等）与事件系统

6.4 与 Gymnasium / RLlib / SB3 等框架对接

6.4.1 环境封装接口：reset/step/seed/render
6.4.2 并行采样：向量化环境与分布式 rollout
6.4.3 记录与复现：episode 日志、轨迹保存

6.5 工程建议：从 Demo 到 Research/Production

6.5.1 最小可行闭环（MVP）清单
6.5.2 常见坑：同步、掉帧、卡死、回放不一致
6.5.3 调试策略：可视化、断言、沙盒关卡

Chapter 7 — `chapter7.md`：观测、动作与奖励的“城市建造”专用设计

7.1 观测表示（Representation）

7.1.1 RGB 视觉：优缺点与训练代价
7.1.2 方块网格/体素窗口（voxel window）
7.1.3 语义化观测：建筑类别、道路边界、地块 ID
7.1.4 记忆：地图构建、占据栅格与拓扑图

7.2 动作编排（Action Orchestration）

7.2.1 原子动作：放置/破坏/使用/切换物品
7.2.2 宏动作：铺路、拉直线、建墙、盖屋顶
7.2.3 蓝图执行动作：按“施工序列”批处理

7.3 奖励与约束（城市任务常见指标）

7.3.1 结构匹配：与目标 schematic 的差异
7.3.2 可达性：道路连通、入口可进入
7.3.3 美学与规则：对称/比例/风格一致性（可选）
7.3.4 资源/时间：材料消耗、施工步数、失败恢复代价

7.4 分层任务拆解（Hierarchical）

7.4.1 城市级 → 街区级 → 建筑级 → 构件级
7.4.2 技能库（Skills）：复用与组合
7.4.3 任务调度：优先级、依赖与并行

Chapter 8 — `chapter8.md`：训练策略、数据与评估（RL / IL / Offline）

8.1 训练策略谱系

8.1.1 在线 RL：PPO/SAC/DQN 等的适用边界
8.1.2 模仿学习：BC/DAgger/轨迹回放
8.1.3 Offline RL：数据集质量与分布外风险

8.2 探索与稀疏奖励对策

8.2.1 课程学习与自动关卡生成
8.2.2 内在奖励（好奇心/计数）在 Minecraft 的实践要点
8.2.3 失败回滚与安全探索

8.3 评估体系（城市建造的“验收标准”）

8.3.1 功能正确：道路通、建筑能进、结构完整
8.3.2 视觉一致：材料、比例、立面节奏
8.3.3 泛化测试：不同地形/不同地块/不同风格

8.4 复现实验（Reproducibility）

8.4.1 固定版本、固定 seed、固定重置脚本
8.4.2 指标与日志：训练曲线、成功率、失败类型
8.4.3 最小可复现工程模板（目录与配置建议）

Chapter 9 — `chapter9.md`：Claude / GPT 如何“规划并建造”（LLM Agent 的建造工作流）

9.1 LLM 在建造任务中的角色划分

9.1.1 规划器（Planner）：从目标到步骤
9.1.2 解释器（Translator）：把步骤转成可执行动作/命令
9.1.3 监督者（Verifier）：检查偏差并纠错

9.2 Prompt 设计：从“想法”到“可执行”

9.2.1 目标格式：约束、风格、尺度、材料预算
9.2.2 产出格式：结构化计划（JSON/YAML/表格）
9.2.3 坐标与参照系：原点、方向、网格对齐

9.3 工具调用与函数接口（让 LLM 真正“动手”）

9.3.1 函数：查询环境状态（位置/背包/方块）
9.3.2 函数：执行动作（移动/放置/破坏/切换）
9.3.3 函数：批量操作（按蓝图/按区域/按图层）
9.3.4 失败处理：重试、回滚、替代方案

9.4 让 LLM 产出“城市级设计”而不是堆方块

9.4.1 先总图后细化：骨架→街区→建筑→细节
9.4.2 模块库 + 组合：原型复用与变化规则
9.4.3 自检：一致性检查清单（道路连通/对齐/材料）

9.5 LLM + RL 的组合方式（混合智能）

9.5.1 LLM 做高层规划，RL 做低层控制
9.5.2 LLM 生成 reward/课程/关卡
9.5.3 反思与记忆：跨 episode 的错误归因与修复

Chapter 10 — `chapter10.md`：如何控制“小人”（Bot/Agent 控制、导航与稳定执行）

10.1 控制层级：从输入到行为

10.1.1 低层：键鼠级动作（移动、视角、交互）
10.1.2 中层：导航到点、对准方块面、放置序列
10.1.3 高层：执行施工任务、管理子目标与依赖

10.2 导航与路径规划（城市施工的底座能力）

10.2.1 网格寻路 vs 物理可达性
10.2.2 台阶/门/水/梯子：特殊地形处理
10.2.3 施工期动态障碍：边建边走的鲁棒性

10.3 精确放置（Placement）与对齐（Alignment）

10.3.1 “看向哪一面”：hitbox、raycast 与误差
10.3.2 直线、平面与层：道路/墙/屋顶的批量策略
10.3.3 容错：偏一格怎么办（检测、纠正、补救）

10.4 资源与背包管理（生存模式尤其重要）

10.4.1 材料清单与补给路线
10.4.2 合成树与加工链的执行
10.4.3 施工中断恢复：存档点与任务断点

10.5 安全与稳定性（工程实践）

10.5.1 防卡死：超时、重置、脱困动作
10.5.2 防破坏：保护区域、白名单方块、只增不删策略
10.5.3 观测漂移：延迟、丢包与不同步检测

Chapter 11 — `chapter11.md`：端到端案例：自动建城系统（从文本需求到落地城市）

11.1 系统架构总览

11.1.1 输入：城市需求（风格/尺度/功能/地形）
11.1.2 中间件：规划、模块库、调度器、校验器
11.1.3 输出：世界存档 + 结构文件 + 评测报告

11.2 资产库（Asset Library）与规则库（Rules）

11.2.1 街区模板与建筑原型库
11.2.2 材料调色盘与替换规则
11.2.3 连接规则：道路接口、地块边界、地形适配

11.3 施工执行：批处理与在线修正

11.3.1 离线生成（直接改世界/结构写入）
11.3.2 在线施工（bot 逐步建造）
11.3.3 混合策略：先离线大体量，再在线补细节

11.4 评测与验收

11.4.1 结构差异对比（目标 vs 实际）
11.4.2 可达性与功能测试
11.4.3 可视化报告：热力图、错误清单、修复建议

11.5 扩展：多智能体与协同施工

11.5.1 分工：道路组/建筑组/装饰组
11.5.2 冲突解决：锁区、任务队列与一致性
11.5.3 通信协议：共享地图与进度

Chapter 12 — `chapter12.md`：附录（清单、模板、FAQ、资源索引）

12.1 快速清单

12.1.1 “建城”必备模板（总图/地块/原型/材料）
12.1.2 “RL 环境”必备模板（reset/step/logging）
12.1.3 “LLM Agent”必备模板（工具函数/计划格式/校验）

12.2 常见问题与排错

12.2.1 放置总是偏一格/对不准面
12.2.2 环境不同步/观测延迟
12.2.3 训练不收敛/奖励崩坏/探索失败

12.3 术语表（Glossary）

12.3.1 Minecraft 术语
12.3.2 RL/IL/Offline RL 术语
12.3.3 Agent 工程术语（planner/executor/verifier 等）

12.4 资源索引（建议按主题整理）

12.4.1 环境与 API 文档
12.4.2 论文与项目（Minecraft RL、LLM Agent）
12.4.3 建造素材与教程（城市规划/建筑风格）

章节之间的引用约定（建议）

坐标以 (x, y, z) 表示，方向以 +X/-X/+Z/-Z 或 N/E/S/W（需要在第 1 章固定）
蓝图统一用：
- “占地尺寸”：width × depth × height
- “原点”：origin（左下角/中心点等需声明）
- “朝向”：facing
所有可执行计划建议提供：
- materials（材料清单）
- steps（步骤序列）
- checks（每步验收条件）
- rollback（失败回滚策略）