Yuanhao Feng

返回

第一篇介绍了 CubeMuse 的结构化指令集,DSL 引擎执行 op-log 后产出 Grid。Grid 是体素网格,存储每个位置的方块,是渲染和导出的唯一数据来源。这篇讲 Grid 如何变成浏览器里可交互的 3D 建筑。

首先要解决的是性能问题。一栋中等规模的建筑有几千到几万个方块,每个方块都是边长为 1、有六个面的立方体。如果给每个方块单独创建一个 Mesh,draw call 数量会随方块数线性增长,提交命令会成为 GPU 的性能瓶颈。CubeMuse 的渲染管线用 greedy meshing 把相邻同材质面合并成大矩形,用隐藏面剔除跳过被遮挡的面,用顶点 AO 近似环境光遮蔽,再按透明度分三个 pass 绘制。

分块网格与渲染管线#

Grid 内部按 Chunk 组织。Chunk 是边长 16 格的立方体,是存储和网格化的基本单位。每格用 Uint16 下标引用 Palette,Palette 保存去重后的方块 id 与状态。Grid 只分配非空 Chunk,空区域不占内存。

网格化按 Chunk 进行。每个 Chunk 中的方块先按几何类型分别处理:占满一格的整方块走 greedy meshing 路径,楼梯、台阶、栅栏等非整方块走逐块几何展开路径。两条路径都将结果写入同一组 typed array,包括 positions、normals、colors、uvs、layers、indices。随后按材质透明度分成 opaque、cutout、transparent 三段几何。每个非空段对应一个 Mesh,用 MeshBasicMaterial 绘制,明暗完全来自烘焙在顶点色里的面方向系数和 AO。

Grid + Palette Uint16 下标引用去重方块 按 16³ 分块 (Chunk) 逐 Chunk 处理 整方块 (full) 隐藏面剔除 顶点 AO 采样 Greedy 合并 模型方块 (15 种) 逐块几何展开 AO 固定档位 3 opaque cutout transparent 三段几何 → BufferGeometry → MeshBasicMaterial 不透明队列 (opaque + cutout) 透明队列 (远 → 近排序)

三段几何最终进入 Three.js 的两个绘制队列。opaque 和 cutout 共用不透明队列,transparent 进入透明队列,按对象投影深度从远到近排序。项目早期采用 instanced cube 方案,每个方块 id 一组实例,后来换成了当前的 chunk 网格方案。网格化算法只依赖 typed array 操作,可以在 Node 环境中运行,截图脚本和测试都复用同一套代码。

隐藏面剔除与 Greedy meshing#

建筑中,大部分方块面都被相邻方块遮挡,可以省去这些面的生成。对每个整方块的六个面,如果该方向有相邻方块,且它的材质不透明、几何占满一格,就跳过这个面。透明整方块的判据不同:相邻格具有相同 Palette 下标时省略该面,这样同种玻璃内部不出现分界线,不同颜色的玻璃之间保留边界。

剔除后的可见面进入 greedy meshing。算法按六个面方向逐层处理。每层用一个 16×16 的 mask 表示,每格记录一个合并键。合并键由 Palette 下标和四角 AO 组成,key 相同的连续格才能合并。扫描从左上角开始,遇到未处理的格时,先沿 u 方向扩宽,再沿 v 方向逐行检查,增加高度,生成一个矩形 quad。合并范围限于单个 Chunk。

4×4 mask 合并过程 原始 mask 逐步扫描 合并结果 A A B B A A B B A A A A A A A A u → v ↓ Q1 Q2 Q3 key=A UV: 2×2 key=B UV: 2×2 key=A UV: 4×2 16 个单位面 → 3 个 quad → 6 个三角形 合并键 = Palette 下标 + 四角 AO  key 不同或跨 Chunk 边界时不合并 扫描方向: 从左上起,先 u 扩宽,再 v 扩高 ① 2×2 A ② 2×2 B ③ 4×2 A 纹理通过 RepeatWrapping 按格重复,UV 跨度 = 合并面覆盖的格数

合并后的面使用与格数相同的 UV 跨度,纹理通过 RepeatWrapping 按格平铺。一个 2×3 的合并面 UV 范围就是 (0,0) 到 (2,3),GPU 采样时自动重复贴图。

下面是几个场景的面数对比。实心石块立方体的数据通过在 Node 中运行当前网格化函数得到。

场景方块数原始单位面剔除后剔除率最终 quad三角形
4³ 石块643849675%612
8³ 石块5123,07238487.5%612
16³ 石块4,09624,5761,53693.75%612
32³ 石块32,768196,6086,14496.875%2448

16³ 的实心方块剔除 93.75% 的面后剩 1,536 个单位面。greedy meshing 把这 1,536 个面合成 6 个 quad,进一步减少 99.6% 的面片数量。32³ 的场景横跨八个 Chunk,每个外表面被 Chunk 边界切成四块,最终是 24 个 quad。

再看一栋由 194 块方块组成的小屋,包围盒为 7×6×7。整方块原有 1,152 个面,剔除后剩 414 面,剔除率为 64%。合并后为 107 个 quad。加上门模型的 6 个 quad,整栋建筑共 113 个 quad、226 个三角形、2 个非空几何段。

顶点 AO 与面方向光照#

CubeMuse 的明暗完全由面方向系数和顶点 AO 决定,无需实时光照。面方向系数是固定常量,顶面 1.0、底面 0.5、东西面 0.6、南北面 0.8,模拟日光从正上方照射的效果。顶点 AO 在网格生成阶段计算,用邻接方块近似角落处的环境光遮蔽。

每个可见面的四个角各采样外侧层的三个邻格:两个边邻格 s1、s2 和一个对角邻格 c。如果两个边邻格都被遮挡,AO 档位为 0(最暗),对角格不参与计算。否则 AO = 3 - s1 - s2 - c,其中 s1、s2、c 为 0 或 1。四个档位的 AO 系数分别是 0.45、0.63、0.82、1.00。

角点 AO 采样 当前面 角点 s1 s2 c 边邻格 边邻格 对角邻格 AO 公式 s1, s2 = 遮挡 ? 1 : 0 c = 遮挡 ? 1 : 0 s1 && s2 ? AO=0 : AO=3-s1-s2-c 两边同时遮挡时,对角格不参与计算 四级 AO 亮度 AO = 3 1.00 无遮挡 AO = 2 0.82 一边遮挡 AO = 1 0.63 一边 + 对角 AO = 0 0.45 两边遮挡 对角线翻转 C00 C11 默认对角线 C00–C11 C01 C10 翻转对角线 C10–C01 当 AO00+AO11 < AO10+AO01 选择亮度差较小的对角线划分三角形 面方向系数: 顶 1.0 / 底 0.5 / 东西 0.6 / 南北 0.8  顶点色 = 面方向系数 × AO 系数

顶点色的三个分量均为面方向系数乘以 AO 系数。东面一个角只有一个边邻格遮挡时,AO 档位为 2,顶点亮度 = 0.6 × 0.82 = 0.492。

构建 mask 时就会计入 AO,随后再进行合并。两个相邻格即使 Palette 下标相同,只要四角 AO 不同,合并键就不同,不会被合并到同一个 quad。这保证了合并后的大面片不会丢失角落的明暗过渡。

四角 AO 还影响三角化方向。每个 quad 由两个三角形组成,默认沿 C00 到 C11 的对角线切分。当 AO00 + AO11 < AO10 + AO01 时,改用 C10 到 C01 的对角线,选择亮度差较小的对角线,避免在 AO 不对称的角落出现锯齿状的明暗分界。

非整方块的子长方体统一使用 AO 档位 3(最亮),十字植物的面方向亮度设为 1。这些模型的体积较小,逐角采样带来的改善有限。

方块模型与状态#

楼梯、台阶和门等方块只占格子的一部分。楼梯占半格加一个台阶,台阶只有半格高,门由两格组成但宽度只有一面。这些非整方块无法走 greedy meshing,需要按 ModelKind 逐块展开几何。

CubeMuse 定义了 15 种 ModelKind:full、slab、stairs、door、cross、flat、pane、fence、gate、wall、trapdoor、rod、box、wallflat、potted。确定 ModelKind 时,先查显式表,再按方块家族规则匹配名称前缀或后缀,剩余的归入 full。

方块模型几何示意 整方块走 Greedy 合并,其余 15 种 ModelKind 逐块展开子长方体或专用 quad full 1×1×1 Greedy 合并 slab y: 0–0.5 子长方体 stairs facing + half + shape (转角) cross 两片相交 quad 4 个三角形 cutout + 双面 ascending rail 高度 0 → 1 1 片斜面 quad 2 个三角形 非整方块不参与 Greedy 合并,AO 统一取档位 3 (最亮) 完整列表: full / slab / stairs / door / cross / flat / pane / fence / gate / wall / trapdoor / rod / box / wallflat / potted 栅栏、石墙和玻璃板采用固定形状近似,邻接连通未实现

大多数模型方块展开成单位格内的子长方体。台阶是 y 范围 0 到 0.5 的扁方块。楼梯根据 facing 和 half 状态展开成底部半块加朝向侧的上层半块,内外转角 shape 进一步调整几何。门的几何变换由 facing、hinge、open 三个状态决定。原木根据 axis 选择端面纹理。

两类方块使用专门的 quad 路径。十字植物(cross)生成两片相交的 quad,共 4 个三角形,用 cutout 材质和双面渲染保留叶片轮廓。上坡铁轨(ascending rail)读取方向状态,生成一片从高度 0 到 1 的斜面 quad。直轨和曲轨沿贴地路径处理,曲轨贴图采用直轨近似。

非整方块会保留更多的面。邻格是楼梯或半台阶时,墙面继续生成。只有贴在格子边界且被相邻整方块完全遮挡的面才会省略。栅栏、石墙与玻璃板采用固定形状近似,邻接连通尚未实现。

透明与镂空材质#

三段几何分别对应三种材质配置。

几何类别示例transparentdepthWritealphaTestside
opaque石头、木板、树叶falsetrue0FrontSide
cutout花草、铁轨、梯子falsetrue0.5DoubleSide
transparent玻璃、水truefalse0FrontSide

opaque 是默认材质:写入深度,正面渲染,不做 alpha 测试。石头、木板和树叶都属于 opaque。树叶虽然在 Minecraft 中有透明像素,但 CubeMuse 将其作为整方块处理,贴图按固定植被色染色后填满整个面。

cutout 用于有镂空的模型方块。花草、铁轨、梯子用 alpha 测试丢弃 alpha 小于 0.5 的像素,保留不规则轮廓。cutout 启用双面渲染,从任何角度都能看到叶片。cutout 写入深度,不需要排序。

transparent 用于玻璃和水。开启 alpha 混合,关闭深度写入,正面渲染。水的贴图在解码时将 alpha 乘以 0.7。Three.js 将 opaque 和 cutout 放入同一个不透明列表先绘制,然后绘制透明列表。透明列表内按 Mesh 的投影深度从远到近排序。一个 Chunk 的透明面合在同一个 Mesh,内部三角形保持生成时的索引顺序。因此,复杂交叠时的排序仍是近似结果。

纹理角色与异步加载#

每个方块的不同面可以使用不同纹理。草块的顶面是草地,侧面是草泥过渡,底面是泥土。CubeMuse 用纹理角色(face role)选择纹理层:每个 Palette 条目有一个基址 N,面方向通过 faceRoleIndex 映射到角色偏移,顶面取 N+0,侧面取 N+1,底面取 N+2。每个纹理层是一张 16×16 RGBA 的像素切片,所有层按层号堆叠在一个 DataArrayTexture 里。石头只有一种角色占一层,草块有三种角色占三层,原木有 end 和 side 两种角色占两层。

纹理角色选层 Palette 条目 grass_block 基址 = N faceRoleIndex 按面方向选角色 top N+0 side N+1 bottom N+2 DataArrayTexture 层 N 层 N+1 层 N+2 每层 16×16 RGBA 原木: end + side (2 层)  石头: all (1 层)  合并面通过 RepeatWrapping 按格平铺 异步加载时序 t ① 同步初始化 程序占位像素填入每层 (纯色) ② 创建 atlas 对象 NearestFilter / 关闭 mipmap / RepeatWrapping ③ 异步装载 (逐层) 候选路径: vanilla/ → pixel-perfection/ 解码 PNG → 染色 (如植被色) → 覆盖对应层字节 ④ needsUpdate = true 装载结束 → GPU 重新上传 atlas 缓存 Palette 内容签名相同 → 复用 新增 Palette 条目 → 重建 截图等待 pending/ready 信号 兜底 PNG 装载失败 → 保留占位内容

合并后的大面片仍然需要逐格平铺纹理。顶点的纹理层号由 Palette 条目基址加角色偏移得到,UV 跨度等于合并覆盖的格数,GPU 通过 RepeatWrapping 自动重复。NearestFilter 保留像素风格,关闭 mipmap。

加载分三步。第一步同步完成:为每一层填入程序生成的纯色占位像素,创建 DataArrayTexture 对象。第二步逐层异步装载贴图:按候选路径先查 vanilla 目录,再查 Pixel Perfection 目录。找到 PNG 后进行解码,按需应用植被色或水色,再用真实像素覆盖对应层的字节。第三步设置 needsUpdate = true,Three.js 在下一帧将数据重新上传到 GPU。装载失败的层保留占位内容。

编辑时,atlas 按 Palette 内容签名缓存。方块位置变化但 Palette 不变时复用 atlas。新增 Palette 条目时重建 atlas 并重新装载贴图。截图脚本通过 pending 和 ready 信号等待装载完成,确保截到完整纹理。

脏 Chunk 与局部重建#

用户编辑一个方块时,只需要重建受影响的 Chunk,其余 Chunk 的几何和 GPU 资源保持不变。

为确定受影响的范围,先将改动坐标沿各轴扩展 1 格,把影响邻面可见性和角点 AO 的位置也包括进来。再将扩展后的坐标范围除以 16 并用 floor 向下取整,得到脏 Chunk 集合。一次单格编辑根据位置不同,可能涉及 1、2、4 或 8 个 Chunk。

单格编辑的脏 Chunk 影响范围 改动坐标各轴 ±1 外扩后,按 floor(÷16) 确定脏 Chunk 集合 Chunk 0 内部点 (8, 8, 8) 范围 7–9 均在 Chunk 0 内 1 个脏 Chunk C0 C1 面边界 (15, 8, 8) x 范围 14–16 跨两个 Chunk 2 个脏 Chunk 棱边界 (15, 15, 8) x, y 各跨两个 Chunk 2 × 2 × 1 4 个脏 Chunk 角点 (15, 15, 15) 三轴各跨两个 Chunk 2 × 2 × 2 8 个脏 Chunk 未脏 Chunk 保留 ChunkMesh + BufferGeometry 引用  fromGrid 不匹配时回退全量重建

编辑坐标脏 Chunk 数原因
(8, 8, 8)1范围 7 至 9 均在 Chunk 0 内
(15, 8, 8)2x 范围 14 至 16 跨两个 Chunk
(15, 15, 8)4x、y 各跨两个 Chunk
(15, 15, 15)8三轴各跨两个 Chunk

增量重建只对脏 Chunk 重新执行网格化。未受影响的 Chunk 保留原有的 ChunkMesh 和 BufferGeometry 引用,GPU 资源继续复用。Palette 追加新条目时保留原有顺序,已有条目的下标和纹理层基址保持稳定,未受影响的 Chunk 的旧 layer 属性可以继续使用。

增量路径有一个安全检查:传入的 fromGrid 必须与缓存的 Grid 引用一致,且 dirtyKeys 非空。引用不匹配时回退到全量重建。切换图纸或载入新建筑也会触发全量重建。对 typed array 的深比较已验证增量结果与全量结果一致,未受影响的 Chunk 也保持同一对象引用。

参考资料#

CubeMuse 的体素引擎
https://me.yuanhaofeng.com/blog/cubemuse-voxel-engine
作者 Yuanhao Feng
发布于 2026年10月4日