LLM 管意图,代码管几何
CubeMuse 用 JSON 指令集连接 LLM 与确定性引擎,由模型描述建造意图,代码负责几何计算。
你想让 AI 造一座 Minecraft 城堡,最直接的想法是让大模型逐方块输出坐标和材质。
一栋 30×30×30 的建筑约 27,000 个体素位置。即使只列非空方块,输出仍然是数千行坐标加材质,每行长这样:
[12, 5, 8, "stone_bricks"]plaintext除了 token 成本,逐块坐标还给编辑和复用带来困难。用户说”把屋顶换成红色”,坐标序列里没有标识屋顶的结构信息,需要先找出对应的方块。
CubeMuse 的做法是把”建什么”交给 LLM,“怎么画”交给确定性引擎。两个系统之间用一套 JSON 指令集通信。这篇文章讲这个分离是怎么做的,以及为什么这样分。
CubeMuse 是什么#
CubeMuse 是一个浏览器端的 AI 建筑生成器,面向 Minecraft 玩家和创作者。用户用自然语言描述想要的建筑,AI 生成结构化建造方案,确定性引擎将方案渲染为体素建筑,最后导出为 Java 版(.litematic)或基岩版(.mcstructure)在游戏中使用。
LLM 擅长理解自然语言意图,精确的空间计算则交给代码处理。这个分工是系统设计的出发点。
后文会频繁使用以下术语:
| 术语 | 定义 |
|---|---|
| Grid | 体素网格,存储每个位置的方块,是渲染和导出的唯一真相源 |
| Palette | 调色板,将 16 位索引映射到具体方块类型和状态 |
| Chunk | 16×16×16 的存储分块,Grid 只分配非空 chunk |
| Op | DSL 中的一条建造指令,如 wall、roof、door |
| Op-log | 一份完整的 DSL 程序(JSON),是产出 Grid 的”配方” |
| Blueprint | 一份建造方案 = Grid(结果) + Op-log(配方) |
坐标输出与结构化指令#
用一个具体例子说明。一栋 8×5×6 的小屋,坐标方案的输出长这样:
[0,0,0,"stone_bricks"], [1,0,0,"stone_bricks"], [2,0,0,"stone_bricks"], ...plaintext约 300 个非空方块,按主流 BPE 分词器每行约 15 token,总计约 4,500 输出 token。
同一栋建筑用结构化指令:
{ "op": "room", "id": "main", "box": { "from": [0,0,0], "to": [8,4,6] }, "wall_material": "wall" }
{ "op": "roof", "anchor": { "ref": "main.top_face" }, "size": [8,4,6], "shape": "gable", "material": "roof" }
{ "op": "door", "anchor": { "ref": "main.south_face", "align": "center" }, "size": [1,2,1], "facing": "south", "material": "door" }json3 条 op,token 量比坐标方案低一个数量级以上。
结构化指令也让后续操作更容易实现:
- 材质编辑。 把屋顶从深色改成红色,只需修改对应的 palette 条目。
- 结构复用。 一排窗户可以用
group定义,再通过repeat复制。 - 局部修改。 把屋顶改成 hip 式,只需替换 roof op 的
shape参数,其余 op 保持不变。 - 格式转换。 导出
.litematic或.mcstructure时,适配器根据 Grid 中的方块及其 palette 映射,生成目标格式所需的数据。
这些不只是理论推演。项目早期实测证实直接输出体素的方案 token 成本高两个数量级且空间一致性无保证。LLM 一次调用直出完整结构的天花板同样有限(已有研究 ↗中 GPT-4 完整率仅 38%)。另一个曾考虑的方案是 Voyager ↗ 式自由代码生成。视觉天花板可能更高,但产品丢失了命名编辑句柄、材质替换、锚点对齐、确定性测试和 agent 的定向修订能力。CubeMuse 需要保留结构化蓝图,支持生成后的编辑、分享和导出。
一套 JSON 指令集#
JSON 格式与两层校验#
JSON 是 LLM 常用的结构化输出格式,也省去了维护自定义文本解析器的工作。JSON Schema 提供结构校验(字段类型、枚举值、必填项、additionalProperties: false 拒绝未知字段),在此之上还有语义校验层: 检查锚点 ref 是否指向已存在的命名实体、材质角色是否已在 palette 中声明、box.from ≤ box.to 等约束。两层校验叠加,引擎可以在执行前拦截非法 op。工具调用(tool_calls)直接返回 JSON 对象,省去了从自由文本中提取结构的步骤,也减少了格式出错的概率。
DSL 操作的三个抽象层次#
本文将 18 个 op 按抽象程度分为三层。从结构指令到自由体素,模型能控制的细节逐渐增多。生成时优先使用高层指令,无法表达的细节再交给低层操作。
第一层: 结构 op。 说意图,引擎算几何。
包含 wall、room、roof、staircase,以及 door、window、beam 等构件。地板和天花板分别通过 room 的 floor_material 和 ceiling_material 参数设置,立柱则用 axis 为 y 的 beam 表达。这层 op 描述建筑意图。模型说”这里放一面山墙屋顶”,引擎计算每个方块的朝向、上下半部和形状状态。
以 roof 为例:
{ "op": "roof", "anchor": { "ref": "main.top_face", "offset": [0,1,0] }, "size": [10,5,8], "shape": "gable", "material": "roof" }json模型只写了一行。引擎做的事: 确定屋脊线位置,为两道坡面分别计算朝向,填充山墙三角形(gable_fill)。出檐通过扩大屋顶的水平覆盖范围实现: 锚点向上偏移一格,size 每个水平轴各加 2。gable 屋顶真正在变的只有 facing(两个取值,各管一道坡面),其余状态整片统一。
hip 屋顶最能体现结构 op 的价值。它的四个角各需要不同的转角形状(outer_left、outer_right),整个屋面的朝向、形状逐块不同。如果让模型直接输出每块楼梯的 block state,错误率极高,因为这是在把最容易出错的部分交给概率模型。
第二层: 参数几何 op。 说参数,引擎算体素。
包含 shape(sphere、dome、cylinder、cone、ellipsoid、arch、pyramid 共 7 种)、path(Bresenham 折线体素化,最多 64 路点)和 fill(实心填充)。这层提供通用几何原语。shape 支持 hollow 壳体,一条 op 就能造一个空心穹顶。path 用 Bresenham 算法做 3D 折线体素化,用于桅杆、树枝、缆线等线状结构。
第三层: 自由体素 op。 直接指定方块。
只有一个 op: blocks,每次限 512 个方块,超出直接拒绝。直接指定每个方块的位置和材质。抽象最低、表达力最强。用于任何上两层无法表达的细节: 雕塑的五官、线条装饰、手动编辑的记录。
prompt 要求优先使用结构 op,仅在必要时使用 blocks。Schema 拒绝超过 512 格的调用,eval 则持续监控 blocks 在输出中的占比,检查模型是否过度依赖逐块生成。
后处理与组件放置。 在已有结构上补充细节或放置预制组件。
detail 扫描当前作用域已累积的网格,自动为建筑补上勒脚、窗台、檐口等装饰细节。引擎在每份 AI 产出的程序尾部自动追加一条 detail op,prompt 据此禁止模型手动摆放这类装饰。scatter 在既有表面上随机撒落植被或碎石,内建支撑检查(只落在实体表面上,绝不覆盖、绝不悬空)。place_component 将预制组件放置到指定位置,相当于一次库调用。这三类操作单独列出,用于补充前述几何指令。
组合与变换 op#
group、repeat、mirror、rotate 四个 op 用于复用和变换其他 op 的输出。它们跨层工作:
- group 将一组 op 封装为命名组件。子 op 在独立子网格渲染,再 stamp 到主网格。相当于函数定义。
- repeat 沿向量平移复制一组 op。一面墙上的三扇窗户不需要写三遍。
- mirror 沿 x、y 或 z 平面镜像。翻转时会自动调整方块的 facing、half、hinge 和形状手性。楼梯镜像后朝向正确,门的铰链换边。
- rotate 绕 Y 轴旋转 90°、180° 或 270°,同时调整方块状态。旋转还会交换
axis的 x 和 z 取值。
对称建筑只需描述其中一半,再用 mirror 生成另一半,就能保持严格对称。
材质角色解耦#
Palette 将角色名映射到具体方块:
{
"palette": {
"primary": { "id": "minecraft:oak_planks" },
"wall": { "id": "minecraft:stone_bricks" },
"roof": { "id": "minecraft:dark_oak_stairs" },
"accent": { "id": "minecraft:stripped_oak_log" },
"glass": { "id": "minecraft:glass_pane" }
}
}jsonOp 通过 "material": "wall" 引用材质角色。修改对应的 palette 条目后,所有引用该角色的方块都会更新。
Palette 将 op 与方块 ID 分开管理。模型仍需选择具体方块: prompt 给模型列了一份方块词汇表(木料家族、石材、楼梯台阶、玻璃、16 色块、铜及其氧化变体等),模型从中选 ID 填进 palette。同一个方块 ID 只需在 palette 中定义,替换材质时也只需修改这一处。prompt 要求每份方案使用 3-5 种材质角色并保持对比度。
锚点定位与依赖校验#
确定操作类型之后,还需要指定它的位置。
CubeMuse 提供三种定位模式:
- 绝对坐标
box,由from和to指定: 闭区间,适合第一个落地的 op。 - 锚点
anchor(ref+align+offset+inset)(AI 首选): 引用前一个命名 op 的面、中心或边。 - Along 边数组: 沿一条边以指定间距排列放置,用于窗带、柱列等重复结构。
用对比说明锚点的作用。
没有锚点时,模型需要自己算门的坐标。墙从 [0,0,0] 到 [8,4,6],门应该在 [4,0,3]。改了墙的宽度后,门还在 [4,0,3],已经不在中心了。多轮修改后坐标漂移,门悬空,窗嵌墙里。
有锚点时:
{ "op": "door", "anchor": { "ref": "main.south_face", "align": "center" }, "size": [1,2,1], "facing": "south", "material": "door" }json门会自动贴在 main 南面中心,随墙体的位置和宽度变化重新定位。
锚点是 DSL 的基本保证: 门不悬空、窗户条间距均匀、屋顶紧贴墙顶。
在底层实现上,命名实体(带 id 的 op)执行后注册自己的边界框,后续 op 通过 anchor.ref: "<name>.<part>" 引用。<part> 可以是面(south_face、top_face)、角(min、max)、中心(center、center_bottom)、楼层(floor:N)或边(edge:<dir>)。这些引用关系构成一个依赖图,让整个建筑在多轮修改中保持内部一致性。JSON Schema 检查 ref 的字符串类型,语义校验层进一步检查引用是否合法: ref 必须指向前序已执行 op 的 id,part 必须是合法取值。
Grid 与 Op-log 双表示#
Grid: 唯一真相源#
渲染、导出和统计都读取 Grid。
- 16×16×16 chunk 稀疏存储,只分配非空 chunk
- 每个格位存 16 位 palette 索引,最多 65,535 种不同方块
- 索引 0 = air
- 存储结构同为 palette + 索引数组,与
.litematic、.schem和.mcstructure三种格式同构;导入导出时适配器按各格式要求做索引重排和字节序转换
Op-log: 可重放的建造程序#
Op-log 是一份 DSL 程序的 JSON 文本。从起点状态执行一遍,确定性地产出完整 Grid。起点通常是空网格,但导入的现有建筑会编码为起点快照(边界框 + palette + RLE 压缩体素)存入程序的 base 字段,后续 op 在此基础上追加。导入件与生成件在编辑、撤销、AI 修订、导出上走同一条路径。
程序自带 dsl_version 字段。引擎版本演进时(比如 roof 的 gable_fill 缺省值从 false 改为 true),迁移层给存量程序显式补上旧缺省值,确保老图纸逐格不变、新程序享受新缺省。“配方”能跨版本重放,是 Op-log 作为持久表示的前提。
状态读取与程序回放#
Grid 保存执行结果,供渲染和导出直接读取,避免每次都重新执行程序。Op-log 保留建造过程和命名结构,支持版本对比及 replace_group 这类定向修改,也减少了 AI 理解作品时所需的信息量。Blueprint 同时包含这两种表示:
Blueprint
├── Grid ← 渲染 / 导出读这里
│ ├── Palette ← 索引 → 方块类型+状态
│ └── Chunks[] ← 16³ 稀疏分块
└── Op-log ← AI 理解 / 版本对比读这里
└── DslProgram ← JSON, 确定性回放 → GridplaintextGrid 不存数据库。数据库只存 Op-log(程序 JSON,含起点快照)。打开蓝图时从 Op-log 回放出 Grid。这保证了两者永远一致。确定性保证: 相同的 op 序列产出相同的 Grid。这是黄金测试(golden test)的基础。
AI 读取的是 Structure Summary,即一段 3-4 行的结构摘要,包含边界、材质分布 top-8 和命名实体列表。原始体素数据从不直接进入 LLM 上下文。
双端导出: 版本中立方块模型#
内部统一用 Java 风格命名加方块状态(block states)作为中立表示,称为 NeutralBlock。它复用 Java 版的命名体系,因为 Java 版的方块名覆盖最全、社区工具链最成熟。
导入和导出时,由适配器完成格式转换:
- Java 端:
.litematic(Litematica)导入导出;.schem(Sponge v1-v3)仅导入 - 基岩端:
.mcstructure(Structure Block)
跨版本差异在导出时检测,生成替换报告。例如 Java 的 quartz_pillar 在基岩端对应 quartz_block[chisel_type=lines],标为 renamed;楼梯的 Java shape 状态(转角形态)在基岩端被丢弃(基岩自动计算拐角);词汇表外的方块原样保留名称并标为 unsupported。映射表只覆盖 DSL 词汇表实际产出的方块,不嵌入完整的万行跨版本数据集。
结语#
这套设计明确了各部分的职责:
- DSL 表达建造意图,引擎负责几何计算和结构 op 所需的 block state。
- 锚点通过命名实体表达相对位置,依赖图维护结构内部的一致性。
- Palette 集中管理材质角色与方块 ID 的映射,方便统一替换材质。
- Op-log 保留可编辑的建造程序,Grid 保存渲染和导出所需的体素结果。
这套管线构成了 CubeMuse 的建造基础。下一篇讨论模型如何选择和组织 op,以及系统如何控制生成过程。
参考资料#
- 3D Building Generation in Minecraft via Large Language Models ↗, Hu et al., 2024
- Voyager: An Open-Ended Embodied Agent with Large Language Models ↗, Wang et al., 2023
- mc-bench/orchestrator ↗, GitHub