DeepMind Lab 文本关卡(Text Levels)指南:从文本网格到可运行地图的完整编译流程
DeepMind Lab 文本关卡(Text Levels)指南:从文本网格到可运行地图的完整编译流程
导读
DeepMind Lab 提供了一种极其轻量的关卡创作方式:把一张地图直接"画"成几行 ASCII 文本,再由内置编译器自动翻译成标准的 Quake III .map 文件,最终经由 q3map2 与 bspc 工具编译为可运行的关卡。本文以仓库中的 docs/developers/creating_levels/text_level.md 为核心,完整讲解文本关卡的格式规范、实体层与变化层的语义、翻译为 .map 的底层算法、全局配置参数、随机性来源、默认单元格动作以及端到端的示例;同时结合 deepmind/level_generation/text_level/ 下的真实源码(解析器、翻译器、导出器与 Lua 绑定)与 game_scripts/ 中的实际调用,让读者不仅能写出第一张文本关卡,还能理解它从文本到 .map、再到 .bsp 的完整生命历程。
文本关卡是什么
文本关卡(Text Level)是 DeepMind Lab 中一种由简单文本格式编译而来的关卡。它不需要可视化编辑器,也不需要手工编写冗长的 .map 实体清单,而是用一份"人类可读、可 diff、可版本管理"的纯文本网格来描述地图的抽象结构,再配合一组由用户提供的"钩子"(hooks)来描述如何解释这份文本中领域相关的语义。
按照 level_generation.md 的说明,DeepMind Lab 的关卡本质上是 Quake III Arena 关卡,最终打包为 .pk3 文件。文本关卡只是其中的一个来源:它被编译为 .map 文件后,再用仓库中的 q3map2 工具把 .map 转成 .bsp(关卡几何),用 bspc 生成可选的 .aas(供游戏内 bot 使用的导航信息)。整条流水线可以离线执行,也可以在 DeepMind Lab 运行时通过 Lua 扩展在程序内完成(见下文 mapFromTextLevel)。
文本关卡格式:实体层与变化层
一份文本关卡描述的是最简单的一类地图:由正方形单元格组成的矩形网格。它由两个独立的文本层构成,二者都遵循相似的解析规则。
实体层(Entity Layer)的解析规则
实体层文本按以下规则解释(均以 docs/developers/creating_levels/text_level.md 为准):
- 关卡文本由若干行组成,行由平台相关的换行符分隔,并被解释为单字节字符序列,推荐使用 ASCII 编码。一行的长度是去掉换行符后的字节数。
- 长度为零的行被忽略。
- 非空行的数量即地图的高度
H。 - 最长一行的长度即地图的宽度
W。 - 每个字符对应一个网格单元格。网格坐标
(0, 0)位于左上角,第i行的第j个字符对应单元格(i, j)的值。 - 以下单元格值(在系统的编码中)是特殊的:
" "(空格)表示空单元格,"*"(星号)表示墙;其余所有单元格值应为可打印字符。 - 文本中未明确指定的单元格值被隐含为墙单元格。
这一"未指定即墙"的规则非常关键:它意味着你可以写出非矩形(参差不齐)的文本,而缺失部分会自动补成墙,使地图天然封闭。这一点在源码 parse_text_level.cc 中也能得到印证:IsWall 判定 c == '*' || c == '\0',即星号与"未定义(空字节)"都视作墙;GridMaze 中每个 Cell 的默认 value 也是 kInaccessible = '*'(见 grid_maze.h)。
变化层(Variation Layer)的解析规则
变化层的解析规则与实体层类似,但有两点区别:
- 所有字符值都表示"默认"(default),只有
'A'–'Z'分别表示 26 个命名变化(variation)之一。 - 位于网格之外的变化层单元格,或位于墙单元格位置的变化层单元格,都会被忽略。只有网格内部非墙的单元格才可能拥有变化。
变化层是可选的;例如空字符串就表示"每个单元格都没有变化"。
从源码看,变化层的解析同样发生在 parse_text_level.cc:它对每个网格位置读取变化字符,只有落在 'A'–'Z' 区间内的字符才会被写入 maze.SetEntityAt(i, j, entity, var)(源码注释明确说明该代码假设 A–Z 在编码中连续排列,如 ASCII)。而 grid_maze.h 中的 SetEntityAt 只在单元格不是 kInaccessible 时才设置变化值——与文档"墙单元格上的变化被忽略"完全一致。
解析流程的内部数据结构
文本与变化层会先被解析为内部的 GridMaze("网格迷宫")结构,再交给翻译阶段。ParseTextLevel(level_text, variations_text) 的签名与职责见 parse_text_level.h:若变化文本为空,解析器会自动补一个空格字符(variations_text.empty() -> push_back(' ')),等价于"无变化"。GridMaze 中的每个 Cell 记录三件事:主实体值 value、可选的变化 variation、以及一组"开口"(opening),见 grid_maze.h。开口以位掩码表示四个方向:kNorth=1、kSouth=2、kEast=4、kWest=8,CreateOpening 用按位或累积开口。
翻译:从网格到 .map
开口与墙的推导
文本关卡翻译为 .map 数据的核心规则是:两个相邻的非墙实体之间,在对应方向上存在一个"开口"(opening)。由此,每个非墙单元格拥有 0 到 4 个开口;对每个没有开口的方向,输出中就会添加一个墙实体。文档给出了直观的示意:
^ opening (N)
....|......
# | :
# :
Wall (W) # ----> opening (E)
# :
# :
############
Wall (S)
每个非墙单元格还可以拥有一个命名变化(由变化层对应值决定),它决定该单元格的基本几何与外观。
这一算法在 parse_text_level.cc 中有精确实现:解析器先"打破垂直墙"——对每一行,若相邻两列的墙状态相同(同为墙或同为非墙),则在这两个单元格之间创建一对东西向开口(CreateOpening(i, j, kEast) 与 CreateOpening(i, j+1, kWest));再"打破水平墙"——对每一列做同样的南北向处理(kSouth 与 kNorth 成对创建)。这样,翻译阶段只需根据每个单元格缺失开口的方向补墙即可。
用户回调:处理自定义单元格
实体层的"用户单元格值"(既非空格也非星号的值)会被逐个交给用户提供的回调函数。回调以 (i, j, c) 为参数:(i, j) 是单元格位置,c 是其值。函数需表明自己是否能够处理该值:
- 若能处理,则返回一个(可能为空的)实体字符串列表,这些字符串会被追加到最终的
.map输出中; - 若不能处理,则对该单元格值执行默认动作(见下文)。
当前计划支持以 Lua 代码形式提供的用户回调:回调返回 nil 表示失败,返回字符串数组表示成功。
仓库中的实际实现比文档描述更进一步,值得展开。在 C++ 侧,回调类型被定义为:
using TranslateTextLevelCallback = std::function<bool(
std::size_t, // i 坐标
std::size_t, // j 坐标
char, // 实体值
const MapSnippetEmitter&, // 生成 .map 数据的辅助对象
std::vector<std::string>*)>; // 用户产出的 .map 数据出口
见 translate_text_level.h。回调返回 true 表示用户处理了该实体,v 中的字符串被原样追加到最终输出;返回 false 则可能触发默认动作('P' 生成出生点,'I'/'H' 生成门)。
Lua 侧绑定见 lua_bindings.cc:LuaCustomEntityCallback 以 f(i, j, ent, emitter) 调用 Lua 函数,并严格遵守文档语义——
- 无返回值或返回单个
nil:表示函数未处理该实体(此时可能调用默认处理器); - 否则必须返回单个结果,且该结果要么是字符串、要么是字符串数组,所有字符串被追加到输出集合中,实体被视为已处理;
- 返回空字符串可以在不产生任何输出的情况下"处理"实体(例如用于抑制默认处理器);
- Lua 函数中的任何错误(包括返回不符合上述约定的值)都会导致该实体被视为未处理,且不向
.map输出追加任何数据。
MapSnippetEmitter:拼装 .map 片段的辅助工具
为了让用户回调方便地生成合法的 .map 片段,翻译器提供 MapSnippetEmitter(见 translate_text_level.h),它封装了一系列"发射器"方法:
| 方法 | 作用 |
|---|---|
AddEntity(i, j, height, class_name, attributes) |
在单元格 (i, j) 中心、指定高度处生成一个带类别名与属性集合的实体 |
AddSpawn(i, j, height, angle_rad) |
在 (i, j) 单元格指定高度处生成出生点,朝向由弧度角决定 |
AddDoor(i, j, direction) |
生成门单元格。类型 'I' 的门沿东西方向穿越(连接 (i, j-1) 与 (i, j+1));类型 'H' 的门沿南北方向穿越(连接 (i-1, j) 与 (i+1, j)) |
AddFenceDoor(i, j, direction) |
栅栏门,与门类似,但由一系列方块构成,可以透视(源码中 kFenceDoorThickness = 0.04、kFenceDoorPosts = 4,见 translate_text_level.cc) |
AddPlatform(i, j, height) |
生成平台单元格:顶层薄地板纹理、强调边界的黑色中间层、砖纹底座,以及从平台底部延伸到地面的"隐形柱子",防止玩家从平台下方穿过 |
AddGlassColumn(i, j, height) |
生成从地面一直延伸到指定高度的隐形柱体,截面占满整个单元格 |
这些辅助方法不仅面向 C++ 回调,也通过 LuaSnippetEmitter(Lua 类名 deepmind.lab.TextLevelEmitter)暴露给 Lua。注册的方法包括 makeEntity、makeSpawnPoint、makeDoor、makeFenceDoor、addPlatform、addGlassColumn,全部采用"表调用约定",例如 makeEntity{i = i, j = j, classname = 'apple_reward'},见 lua_bindings.h。其中 makeDoor{i = i, j = j, isEastWest = true} 中的 isEastWest 布尔值会被映射为 'I' 或 'H' 门类型(见 lua_bindings.cc)。
全局设置
文本关卡的生成有一组可配置参数,其中部分可以配置或扩展:
- 主题(theme):用于装饰地图的纹理集合。
- 贴花频率(decal frequencies):以给定速率随机添加贴花来点缀地图。
- 天空盒(skybox):一个始终以"无穷远面"方式渲染的纹理立方体;只要存在天空盒,单元格的天花板就是敞开的。
在 C++ 侧,这些参数集中在 text_level_settings.h 的 TextLevelSettings 结构中,其默认值如下:
| 参数 | 默认值 | 说明 |
|---|---|---|
theme |
NullTheme |
纹理主题,默认使用实验室风格纹理 |
skybox_texture_name |
空 | 天空盒纹理名;非空时单元格天花板敞开 |
wall_decal_frequency |
0.1 |
墙面随机贴花频率 |
floor_object_frequency |
0.05 |
地面随机物件频率 |
cell_size |
100.0 / kWorldToGameUnits |
单元格边长(按世界/游戏单位换算) |
ceiling_scale |
1.0 |
天花板缩放 |
light_intensity |
1.0 |
灯光强度 |
ceiling_height |
1.0 |
迷宫包围盒高度,多楼层关卡(如平台关卡)可从 Lua 侧调大 |
draw_default_layout |
true |
是否绘制默认墙与地板;平台关卡需要关闭 |
Theme 抽象类(text_level_settings.h)定义了主题需要提供的全部回调:按变化与方向返回墙纹理(wall(variation, direction))、地板纹理(floor(variation))、天花板纹理(ceiling(variation))、平台踏板(platform_tread())与平台立板(platform_riser()),以及根据墙面/地面候选位置生成贴花装饰(WallDecorations / FloorDecorations)。仓库自带的 NullTheme 实现给出了具体的默认纹理示例,例如地板为 map/lab_games/lg_style_01_floor_orange、墙为 map/lab_games/lg_style_01_wall_green、天花板为 map/lab_games/fake_sky、墙面贴花为 decal/lab_games/dec_img_style01_001。
主题并不局限于 C++。在 lua_text_level_maker.cc 中,引擎用 LuaTheme 把用户 Lua 表包装成 Theme:Lua 侧只需提供 theme:mazeVariation(variation) 返回该变化的地板、天花板、四面墙(wallN/wallE/wallS/wallW)、riser、tread 纹理表;纹理以 {tex = 'map/...', width = 1024, height = 1024, scale = 1.0, angle = 0.0} 形式描述。可选的 theme:placeWallDecals(args) 与 theme:placeFloorModels(args) 用于返回贴花与地面模型的位置。
主题列表
文档列出的当前支持主题如下(默认主题为 MISHMASH):
- MISHMASH(默认)
- TRON
- MINESWEEPER
- TETRIS
- GO
- PACMAN
- INVISIBLE_WALLS
在仓库中,这些主题以"纹理集"的形式定义于 game_scripts/themes/texture_sets.lua,其条目依次为 MISHMASH、TRON、MINESWEEPER、TETRIS、GO、PACMAN、INVISIBLE_WALLS(另有 CUSTOMIZABLE_FLOORS 与 CAPTURE_THE_FLAG 两个扩展集)。以 MISHMASH 为例(texture_sets.lua),它提供了 20 种地板纹理、1 种天花板纹理(map/lab_games/fake_sky)与多面墙纹理池;每个纹理条目默认使用 1024×1024 的源尺寸。INVISIBLE_WALLS 主题则把墙设为 map/poltergeist(半透明/特殊材质墙),用于需要"看不见墙"的实验设置。Lua 侧的主题工厂 themes.fromTextureSet(themes.lua)会为每种变化从纹理池中随机选择一面墙纹理作为四个方向的统一墙纹理(mazeVariation),并按 decalFrequency(默认 0.1)与 floorModelFrequency(默认 0.05)计算贴花与地面模型的数量与位置。
随机性:可复现的关卡生成
文本关卡中的多处地图特征都是随机选取的:
- 对每个变化,从地图主题的纹理池中随机分配一个纹理。
- 墙与地板上的贴花随机添加(频率可配置)。
因此在翻译过程中需要一个随机源来做出这些选择。用户必须提供一个随机数生成器(RNG)作为随机性的来源;强烈建议使用可播种(seedable)的伪随机数生成器以保证可复现性。
翻译函数的 C++ 签名明确接收 std::mt19937_64* rng(translate_text_level.h),即 C++ 标准库的 64 位 Mersenne Twister。在 Lua 侧,引擎通过 map_maker:randomGen():seed(value) 让用户设定随机种子(见 game_scripts/common/make_map.lua),common.random 模块在此基础上提供 choice、shuffle 等工具,供主题工厂在 themes.lua 中选取变化纹理、打乱贴花与地面模型位置。由于所有随机决策都来自同一个可播种的 RNG,同样的实体层 + 变化层 + 种子必然产生同样的地图,这对强化学习实验的"相同任务、不同种子"范式至关重要。
默认动作:P、H、I
当用户回调表示无法处理某个单元格值时,翻译器会对其执行默认动作。文档认可的默认单元格值如下:
P:默认动作在此单元格创建出生点(spawn point)。H:默认动作创建一个南北方向穿越的门,即位于(i, j)的门连接(i ± 1, j)。I:默认动作创建一个东西方向穿越的门,即位于(i, j)的门连接(i, j ± 1)。
注意命名上的小反差:H 是 Horizontal 门但沿行方向(上下)穿越,I 门沿列方向(左右)穿越——文档与 translate_text_level.h 中的 ASCII 示意图均以此约定为准:
********************
* I *
****************H***
* *
*******
端到端示例:四房间小地图
文档给出了一个完整的示例。实体层:
********
*a * x *****
** * *
**** I *
* * *
* *****
* *
******H*******
* I P *
**************
变化层:
AAA
AAA
AAA
CCCCCCCC BBB
这张示例地图展示了一个由门分隔的四个房间的小地图:
- 左上房间没有变化,其中有实体值为
a与x的额外实体; - 其余三个房间分别拥有变化
A、B、C; - 右下房间(变化为
B)有一个出生点——前提是实体值P、H、I使用了默认动作; - 中部左侧还有一个"第五个房间"(未与地图边缘用墙隔开,因此不可达)。
由于"未指定即墙"的规则,实体层等价于如下"规整矩形"形式:
**************
*a * x *******
** * ***
**** I ***
* * ***
* *******
* ******
******H*******
* I P *
**************
而变化层中除 'A'–'Z' 之外的所有字符都是等价的,因此下面这种用 . 填充的形式可读性更好:
..............
..............
........AAA...
........AAA...
........AAA...
..............
..............
..............
.CCCCCCCCC.BBB.
..............
在 DeepMind Lab 中运行文本关卡
离线编译流水线
文本关卡编译后的产物是 .map 文件。按 level_generation.md 的说明,.map 需要继续交给 q3map2 转换为 .bsp、由 bspc 生成 .aas,最终打包为 .pk3 放入 base 目录(例如 $HOME/.deepmind_lab/baselab)即可被 DeepMind Lab 加载。整条离线链路即:text level → .map → .bsp (+.aas) → .pk3。
程序内生成:mapFromTextLevel
文本关卡也可以在 DeepMind Lab 运行时通过 Lua 扩展在程序内生成。引擎在 lua_text_level_maker.cc 中注册了 mapFromTextLevel 方法;Lua 侧的封装位于 game_scripts/common/make_map.lua,其关键参数为:
| 参数 | 说明 |
|---|---|
entityLayer |
实体层文本字符串 |
variationsLayer |
变化层文本字符串(可为空) |
mapName |
生成地图的名字 |
allowBots |
是否允许 bot(生成 .aas) |
useSkybox |
为 true 时使用默认天空盒 map/lab_games/sky/lg_sky_03,单元格天花板敞开 |
theme |
主题对象,默认由 textureSet(默认 texture_sets.MISHMASH)构造 |
decalFrequency / floorModelFrequency |
贴花与地面模型的随机频率 |
callback |
自定义实体回调;默认实现把 A 映射为 apple_reward、G 映射为 goal |
make_map.lua 中默认回调的写法可以看作文档所述 Lua 回调的实战范本:
callback = kwargs.callback or function(i, j, c, maker)
local pickup = kwargs.pickups and kwargs.pickups[c] or PICKUPS[c]
if pickup then
return maker:makeEntity{
i = i,
j = j,
classname = pickup,
}
end
end
即:遇到能识别的字符值,就用 maker:makeEntity 生成对应实体并返回(实体被处理);否则返回 nil(未处理,交给默认动作)。工厂层(如 game_scripts/factories/explore/factory.lua)会先用 mazeGeneration{seed = ...}:entityLayer() / :variationsLayer() 生成实体层与变化层文本,再把这些文本传入 mapFromTextLevel,从而把"文本关卡 + 程序化迷宫生成"无缝衔接起来。
小结
文本关卡是 DeepMind Lab 关卡创作体系中"上手成本最低"的入口:它用纯文本把地图压缩为一个二维字符网格,用空格与星号表达空地与墙体,用 'A'–'Z' 表达视觉变化,用 P/H/I 三个默认值表达出生点与两种方向的门,再通过用户回调把任意自定义实体注入 .map。从源码看,这条链路完全打通:ParseTextLevel 把两层文本解析为 GridMaze(parse_text_level.cc),TranslateTextLevel 结合可播种 RNG、用户回调与 TextLevelSettings 输出 .map(translate_text_level.h),LuaTheme/LuaSnippetEmitter 让主题与实体注入全部可在 Lua 侧完成(lua_text_level_maker.cc、lua_bindings.h),而 make_map.lua 则提供了开箱即用的运行封装。对于研究实验而言,文本关卡最大的价值在于可读、可复现、可程序化生成:同一份实体层与变化层配上不同随机种子,即可批量产出结构相似而外观各异的任务场景。