从 Blender 插件到系统级体素引擎：MoziToolKit 的 Rust 重构与实时同步之路

0. 引言

在三维动画制作与游戏资产渲染的工作流中，将 Minecraft 世界与角色资产导入 Blender 往往是一个看似简单却充满暗坑的过程：UV 扭曲撕裂、多材质槽位导致的渲染调用（Draw Call）雪崩、PBR 贴图不规范、生物群系丢失动态色盘……

为了解决这些琐碎但高频的痛点，我在两个多月前启动了 MoziToolKit。起初，它只是一个用于自动化清理网格和重建材质的 Python 插件；但随着需求不断延展，我们希望进一步打破传统「导出世界文件 $\to$ 外部工具转 OBJ $\to$ 导入 Blender」的割裂长链路，直接构建一条支持原版模型解析、方块变体烘焙与 WebSocket 双向实时同步（Live Sync）的通道。

而当体素数量突破千万量级时，Python 的解释执行开销、内存占用与 GIL 限制迅速筑起了性能高墙。为了真正实现视口无感热同步与极限吞吐，底层引擎的彻底下沉势在必行——这促成了 libmozitoolkit 的诞生。

本文将完整复盘这一路从脚本工具集到独立 Rust 核心引擎的架构演进与技术攻坚。

1. 起点：三维资产管线中的微小痛点

2026 年 7 月末，MoziToolKit 的第一个 Commit 落地。当时的定位非常克制：解决静态模型导入后的局部缺陷。

1.1 自适应细分与挤出 UV 修复

在处理像素风格资产时，经常需要对特定面进行几何挤出（Extrude）。然而，常规挤出操作会导致侧面 UV 沿法线拉伸变形。MoziToolKit 最初引入了 auto_extrude_repair 与 adaptive_pixel_split：

自适应像素网格切分：根据面的物理尺寸与绑定的贴图分辨率，自动计算出对应的像素网格比例，将单面均匀细分为规则四边形（Quads），并完整保留原始骨骼权重与边缘折痕（Crease）。
侧面 UV 几何重建：分析挤出几何边缘的拓扑朝向，自动从原方块纹理中拾取对应边缘像素并生成正确的连续平铺 UV，消除了人工手动解包对齐的繁琐过程。

1.2 材质体系化：LabPBR 1.3 与动态图集

随后，工具集开始处理材质层面的核心挑战：

LabPBR 1.3 物理对齐：构建了参数化的节点组模板，将游戏 PBR 资源包中的法线（Normal）、高光/金属度/粗糙度（Specular）解包，精准映射至 Blender Principled BSDF。在后续十余次迭代中，逐步对齐了 Random Walk 次表面散射（SSS）、薄壁透光（Thin Wall）、自发光物理强度（Emission）以及透光介质（Transmission）与粗糙度无扭曲映射。
MaxRectsBinPack 图集缝合：一个场景中若包含数百种方块，每个方块独立使用多张 16×16 贴图，会导致 Blender 材质槽位极度膨胀。MoziToolKit 引入了多通道图集打包算法，支持静态贴图栅格化对齐、多尺寸实体矩形混排，并将动态垂直长条贴图（Animated Strips）同步平铺绑定到单一着色器中，通过顶点属性驱动帧动画。

2. 破局：从「后处理工具」到「实时桥梁」

即便静态后处理管线日趋成熟，制作流程依旧存在根本性阻碍：创作者在游戏中搭建完场景后，必须先关服保存存档，再通过外部软件框选、导出、烘焙、导入。一旦游戏内结构需要微调，整个繁复流程必须重来一遍。

我们希望打通一条直连通道：在游戏内拖动选区，Blender 视口即刻生成对应的几何模型与材质；游戏内敲掉一个方块，Blender 视口实时更新。

为此，系统拓展出了两大关键组件：

+-----------------------------------------------------------+
|                   Minecraft (Yefira Mod)                  |
+-----------------------------------------------------------+
                              |
                     WebSocket 二进制流
                              v
+-----------------------------------------------------------+
|               MoziToolKit (Blender 侧运行时)               |
|                                                           |
|  [ LiveSyncSession ] <--- CRC32 状态指纹比对 / 增量更新    |
|           |                                               |
|           v                                               |
|   [ VoxelStorage ]  <--- 16x16x16 Chunk 结构化存储        |
|           |                                               |
|           v                                               |
|     [ MC Baker ]    <--- 解析原版 JAR/资源包 JSON BlockState|
|           |                                               |
|           v                                               |
|  [ Direct Mesher ]  <--- 6向邻域面剔除 / 流体网格 / 顶点焊接 |
|           |                                               |
|           v                                               |
|  [ foreach_set ]    ---> Blender 3D Viewport              |
+-----------------------------------------------------------+

2.1 无头模型烘焙器（MC Baker）

原版 Minecraft 的方块呈现并不简单等同于正方体，它依赖极其复杂的 BlockState 与 Multipart JSON 规则（如红石线根据相邻连接动态衍生、栅栏根据四个方向的接触状态拼装子模型、楼梯朝向与倒置）。

我们在 Python 端实现了独立的无头状态烘焙器：

解析原版 JAR 与资源包中的模型继承树与材质占位符（Texture Variables）。
准确求解 Multipart 组合条件并进行几何空间变换（uvlock、X/Y 轴旋转）。
处理每个几何图元的 cullface 属性，为后续面剔除提供准确的几何基准。

2.2 二进制流式协议与直接网格引擎（Direct Mesh Engine）

早期我们尝试过通过 Blender 几何节点（Geometry Nodes）实例化点云，但渲染海量实例时的视口交互性能并不理想。随后我们转向了 Direct Mesh Engine：

流式分阶段协议：协议定义了 9 种二进制包格式（握手、全量快照、Section 增量、CRC32 清单比对等）。将同步拆分为 INGEST（网络包非阻塞摄取入库）与 BUILD（几何确定性网格化）两个互不干扰的阶段。
边界自愈机制：以 16×16×16 的 Chunk Section 为网格构建单元。当某个 Section 构建完毕后，若其邻接 Section 后续抵达，系统会自动将其边界标记为 Dirty，进行跨区块接缝面剔除与多边形缝合，彻底消除区块接缝处漏面的问题。

3. 撞墙：Python 性能天花板

在小规模选区（如 5×5 Chunk）下，Python 版本的表现尚可。但当创作者在服务器中选择大场景（如几百个 Chunk、千万级体素点）或者动态拖拽选区框时，性能悬崖出现了。

3.1 内存爆炸与 GC 停顿

在 Python 中，每个体素即使仅用简短的字符串或元组表示，加上哈希表（dict）的开销，内存膨胀系数也是惊人的。一次 1400 万体素的加载会瞬间吞噬数吉字节内存。当用户频繁拖拽调整选区时，旧对象的释放引发频繁的垃圾回收停顿，导致视口完全冻结。

3.2 循环与计算吞吐极限

几何生成本质上是密集的数值与位运算：

邻接面遮挡判断：每个方块需要检查 6 个方向的邻居状态、透明度与外形边界重叠。千万次循环即使经过尽可能的字典预取优化，在纯 Python 虚拟机里依然需要跑数秒乃至数十秒。
空间顶点焊接（Vertex Welding）：为了生成平滑法线与干净的多边形，需要根据空间坐标哈希消除重复顶点。Python 版本的焊接操作开销巨大。
主线程与 GIL 束缚：Blender 的 Python API 要求所有对数据块（bpy.data）的修改必须在主线程执行。即便将网络 I/O 移至后台线程，网格计算仍会占用大量主线程时间片，造成 UI 卡死与渲染帧率暴跌。

即使我们引入了 18×18×18 本地步长网格（Local Stride Grid）、时间预算分片切分（Time-budget Chunking），也只能缓解卡顿感，无法从根本上跨越语言执行效率的数量级差距。

计算密集型与数据密集型的核心逻辑，必须从 Python 中彻底剥离。

4. 重生：原生 Rust 核心 `libmozitoolkit`

2026 年 9 月 7 日，libmozitoolkit 仓库创建。目标非常纯粹：将整个数据解析、体素存储、面剔除、模型烘焙与网格生成管线彻底下沉至 Rust，Python 端仅保留最薄的一层 Blender UI 与视口接入胶水。

4.1 四层解耦架构设计

整个工程被划分为严谨的 Cargo Workspace 架构：

+---------------------------------------------------------------+
|                      mtk-py (PyO3 0.24)                       |
|               Zero-Copy Buffer Protocol / memoryview          |
+---------------------------------------------------------------+
                               |
       +-----------------------+-----------------------+
       v                                               v
+--------------+                               +---------------+
|   mtk-sync   | (原生 WebSocket / tungstenite) |   mtk-voxel   |
+--------------+                               +---------------+
       |                                               |
       v                                               v
+--------------+  +--------------+             +---------------+
| mtk-resource |  |  mtk-texture |             |   mtk-model   |
+--------------+  +--------------+             +---------------+
       \                 |                            /
        +----------------+---------------------------+
                         v
                  +--------------+
                  |   mtk-cull   | (微秒级空间遮挡与剔除)
                  +--------------+
                         |
                         v
                  +--------------+
                  |   mtk-core   | (扁平化 MeshData / UV 几何算法)
                  +--------------+

mtk-core：系统基石。定义统一的标准 3D 坐标空间（Z-up）、数学常量、基础 UV 几何算法（Shoelace 面积、翻转矫正）以及核心网格容器 MeshData。
mtk-cull：高吞吐面剔除引擎。完整实现了 Minecraft 1.21+ 的遮挡判定语义，利用位运算快速排查非完全不透明几何体与复杂四边形接触面。
mtk-model：无头模型烘焙器。处理 BlockState 变体矩阵、JSON 继承与多组件组合，并集成了针对复杂方块实体（如床、箱子、潜影盒、头颅、饰纹陶罐）的 MiEx 参数化实体模型解析。
mtk-voxel：连续内存体素存储与网格生成。封装基于连续切片的 18×18×18 边界填充网格，实现纯多边形生成与物理流体曲面构建。
mtk-texture & mtk-resource：原生的 2D BSP 图集缝合器与 OptiFine / Continuity CTM 连纹运行时求解器。
mtk-sync：纯 Rust 实现的异步网络会话层，使用 tungstenite 直连游戏端口，剥离对外部 Python C-wheel 的环境依赖。
mtk-py：薄封装的高性能 PyO3 导出层。

4.2 零拷贝（Zero-Copy）数据桥梁

在 Python/Rust 混合架构中，跨语言边界的数据搬运极易成为新的性能瓶颈。如果网格在 Rust 侧构建好后，再序列化为 Python 对象或者深度拷贝（Deep Copy），性能提升将大打折扣。

我们贯彻了 Data In Data Out 与 零拷贝缓冲协议（Buffer Protocol） 原则：

MeshData 底层采用绝对平铺的一维向量（Flat Vec<f32> / Vec<u32>）保存顶点、法线、UV、面属性等数据。
在 mtk-py 中，通过 PyO3 的 PyBuffer 与 Python 的 memoryview 直接暴露 Rust 内部缓冲区的内存指针。
Blender 侧无需任何数据解析循环，直接通过 C 级别的 mesh.vertices.foreach_set("co", mesh_data.positions_flat) 等 API 瞬时完成整块几何体的高速灌入。

4.3 并行化与算法优化

Rayon 并行流水线：由于各 Section 之间的数据在读取时完全独立，SectionMesher 可以轻松通过 Rayon 进行多核并行网格化，吞吐量直接随 CPU 核心数线性提升。
空间哈希焊接优化：在顶点焊接中引入针对整数/量化坐标优化的 FxHashMap，配合快速无缝焊接算法，将单区域网格的物理去重耗时从原先 Python 的数秒甚至数十秒，在 Rust 侧直接降至 80ms 以内。
双向数学等价性验证：在架构迁移之初，我们编写了严苛的跨语言对比测试套件（test_verify_against_blender），逐个比对顶点坐标、法线方向、UV 范围和 CRC32 校验码，确保 Rust 引擎在输出结果上与原版达到 100% 的几何数学一致性。

5. 攻坚细节与核心特性沉淀

在近期的迭代中，一系列复杂的渲染与几何特性也在底层得到了彻底解决：

5.1 复杂流体表面与接触面精细剔除

Minecraft 中的水流并非简单的立方体，其表面高度取决于相邻流体块的下落状态与水平流向。

系统实现了流体表面物理高度求解器，能够生成倾斜的连续多边形，并自动校准 32×32 流体贴图的原生采样窗口。
修复了固体天花板遮挡导致的空洞缺陷：由于流体表面默认最高为 $\frac89$，若其上方存在实体方块，顶部水面不得被错误消隐，必须精确保留。同时处理下落流体柱侧面的连续平铺纹理。

5.2 确定性植物随机偏移与自然变体

原版自然地形中的草丛、花朵并非居中摆放，而是带有确定性的位置微调；部分方块（如泥土、石头）在放置时具有随机的面旋转（0°、90°、180°、270°）。

在 mtk-core 中完整实现了原版 48 位线性同余生成器（LCG，JavaRandom）与 Mth.getSeed 空间哈希算法。
无需依赖外部随机种子，在网格化过程中根据方块的世界坐标直接算出确定性的平移向量与旋转变体，达成 1:1 还原游戏自然观感的目标。

5.3 实体方块与参数化模型解耦

对于原版中缺乏标准 JSON 模型的特殊方块（如带有铰链开合的箱子、悬挂告示牌、带有物理悬挂倾斜角度的钟、雕纹陶罐等）：

集成了 upstream MiEx 的表达式求值器（evaluator.rs），支持在运行时根据 BlockState 属性（facing、attached 等）动态演算模型的图元尺寸与 Box UV 展开。
针对 2D 平面贴花模型（如红石线交叉分支）的特殊去重机制：严禁将同平面内重叠的 2D 贴花视作穿模遮挡而误剔除，确保红石线在多组件展开时完整呈现。

6. 总结与展望

回看从 MoziToolKit 到 libmozitoolkit 的演进历程，这不仅是一次单纯的语言重写，更是一次完整的软件工程重构：

各司其职的混合架构：让 Python 专注于其最具生产力的领域——处理 Blender 的 UI 交互、操作符注册与管线调度；让 Rust 承载其天生擅长的重任——高性能内存布局、高并发并行计算、无锁流式同步与严苛的内存安全。
拒绝盲目移植，坚持纯数据抽象：如果将 Blender 的 bpy 概念直接渗入 Rust，只会得到一份别扭的绑定代码。将底层彻底抽象为纯粹的几何数据与字节流（Data In Data Out），不仅保证了核心库的极简与高效，也让未来将其复用到 WebAssembly、独立查看器乃至游戏引擎中成为可能。

目前，基于 libmozitoolkit 的新一代实时同步与体素网格生成系统已经稳固运转。后续，我们还将探索更多系统级图形管线与角色绑定自动化的可能，持续打造更极致的创作者工具链体验。