Yuanhao Feng

返回

你想让 AI 造一座 Minecraft 城堡,最直接的想法是让大模型逐方块输出坐标和材质。

一栋 30×30×30 的建筑约 27,000 个体素位置。即使只列非空方块,输出仍然是数千行坐标加材质,每行长这样:

[12, 5, 8, "stone_bricks"]
plaintext

除了 token 成本,逐块坐标还给编辑和复用带来困难。用户说”把屋顶换成红色”,坐标序列里没有标识屋顶的结构信息,需要先找出对应的方块。

CubeMuse 的做法是把”建什么”交给 LLM,“怎么画”交给确定性引擎。两个系统之间用一套 JSON 指令集通信。这篇文章讲这个分离是怎么做的,以及为什么这样分。

LLM 管意图 代码管几何 自然语言 Agent 循环 LLM + 工具箱 检索 视觉 DSL JSON DSL 引擎 18 ops → 体素 Grid 渲染 导出

CubeMuse 是什么#

CubeMuse 是一个浏览器端的 AI 建筑生成器,面向 Minecraft 玩家和创作者。用户用自然语言描述想要的建筑,AI 生成结构化建造方案,确定性引擎将方案渲染为体素建筑,最后导出为 Java 版(.litematic)或基岩版(.mcstructure)在游戏中使用。

LLM 擅长理解自然语言意图,精确的空间计算则交给代码处理。这个分工是系统设计的出发点。

后文会频繁使用以下术语:

术语定义
Grid体素网格,存储每个位置的方块,是渲染和导出的唯一真相源
Palette调色板,将 16 位索引映射到具体方块类型和状态
Chunk16×16×16 的存储分块,Grid 只分配非空 chunk
OpDSL 中的一条建造指令,如 wall、roof、door
Op-log一份完整的 DSL 程序(JSON),是产出 Grid 的”配方”
Blueprint一份建造方案 = Grid(结果) + Op-log(配方)

坐标输出与结构化指令#

方案 A: 模型直出坐标 方案 B: 结构化指令 [0, 0, 0, "stone_bricks"], [1, 0, 0, "stone_bricks"], [2, 0, 0, "stone_bricks"], [3, 0, 0, "stone_bricks"], ... (300+ 行) [8, 4, 5, "oak_planks"], [8, 4, 6, "oak_planks"] 每个非空方块一行,约 300+ 行 {"op":"room","id":"main", ...} {"op":"roof","anchor":{...},...} {"op":"door","anchor":{...},...} 3 条 op,引擎计算全部几何 输出 token ~4,500 ~150 30:1 ✗ 改材质 = 全量重新生成 ✗ 复用 = 复制粘贴坐标 ✗ 增量修改 = 无"屋顶"概念 ✗ 导出 = 丢失全部语义 ✓ 改材质 = 改 palette 一行 ✓ 复用 = group + repeat ✓ 增量修改 = 替换单条 op ✓ 导出 = palette + 命名实体

用一个具体例子说明。一栋 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" }
json

3 条 op,token 量比坐标方案低一个数量级以上。

结构化指令也让后续操作更容易实现:

  1. 材质编辑。 把屋顶从深色改成红色,只需修改对应的 palette 条目。
  2. 结构复用。 一排窗户可以用 group 定义,再通过 repeat 复制。
  3. 局部修改。 把屋顶改成 hip 式,只需替换 roof op 的 shape 参数,其余 op 保持不变。
  4. 格式转换。 导出 .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 操作的三个抽象层次#

抽象 表达力 结构 op 说意图,引擎算几何 wall room roof staircase 构件: door window beam 模型描述建筑语义,引擎处理 block state (facing / half / shape / hinge) 参数几何 op 说参数,引擎算体素 shape (7 种) path fill sphere / dome / cylinder / cone / ellipsoid / arch / pyramid; Bresenham 折线体素化 自由体素 op 逐方块放置 (逃生舱) blocks (≤512) 组合 op 跨层复用与变换 group repeat mirror rotate 表面 op 装饰与组件 detail place_component scatter LLM 优先使用最高抽象层。只有当上层 op 无法表达时才降级到下一层。 "缺的从来不是自由度,而是阶梯的低层台阶。" DSL v0.9.0 结构 7 + 几何 3 + 自由 1 + 组合 4 + 表面 3 = 18 op

本文将 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" }
  }
}
json

Op 通过 "material": "wall" 引用材质角色。修改对应的 palette 条目后,所有引用该角色的方块都会更新。

Palette 将 op 与方块 ID 分开管理。模型仍需选择具体方块: prompt 给模型列了一份方块词汇表(木料家族、石材、楼梯台阶、玻璃、16 色块、铜及其氧化变体等),模型从中选 ID 填进 palette。同一个方块 ID 只需在 palette 中定义,替换材质时也只需修改这一处。prompt 要求每份方案使用 3-5 种材质角色并保持对比度。

锚点定位与依赖校验#

确定操作类型之后,还需要指定它的位置。

CubeMuse 提供三种定位模式:

  1. 绝对坐标 box,由 from 和 to 指定: 闭区间,适合第一个落地的 op。
  2. 锚点 anchor(ref + align + offset + inset)(AI 首选): 引用前一个命名 op 的面、中心或边。
  3. 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 双表示#

Blueprint Grid (真相源) 16³ 16³ 空 16³ ... 16-bit palette 索引,稀疏分块 只分配非空 chunk Palette: 0→air 1→oak_planks 2→stone_bricks ... Op-log (配方) op: room id: "main" ... op: roof anchor.ref: "main.top_face" op: door anchor.ref: "main.south_face" DSL JSON 程序,确定性回放 → Grid 确定性回放 渲染 / 导出 AI 理解 / 版本对比 Grid 不存数据库。数据库只存 Op-log (程序 JSON)。打开蓝图时回放。 确定性保证: 相同 op 序列 → 相同 Grid。黄金测试的基础。 喂给 AI 的不是 Grid 也不是完整 Op-log,而是 Structure Summary (3-4 行文本摘要)。

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, 确定性回放 → Grid
plaintext

Grid 不存数据库。数据库只存 Op-log(程序 JSON,含起点快照)。打开蓝图时从 Op-log 回放出 Grid。这保证了两者永远一致。确定性保证: 相同的 op 序列产出相同的 Grid。这是黄金测试(golden test)的基础。

AI 读取的是 Structure Summary,即一段 3-4 行的结构摘要,包含边界、材质分布 top-8 和命名实体列表。原始体素数据从不直接进入 LLM 上下文。

双端导出: 版本中立方块模型#

NeutralBlock Java 风格命名 + 方块状态 (block states) Java 适配器 命名转换 + NBT 编码 Bedrock 适配器 状态映射 + LE-NBT .litematic .mcstructure 跨版本差异在导出时检测,生成替换报告

内部统一用 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,以及系统如何控制生成过程。

参考资料#

LLM 管意图,代码管几何
https://me.yuanhaofeng.com/blog/cubemuse-build-dsl
作者 Yuanhao Feng
发布于 2026年9月9日