这几个月我在做什么：Rig2 插件开发与 Mine-imator 格式研究

这几个月我大部分精力都放在一件事上：把 rig2 从“一个绑定”慢慢做成“一套能工作的 Blender 动画生态”。

如果只看结果，它现在像是几个独立项目：

rig2_addons：Rig2 在 Blender 里的主插件
mi2bl：把 Mine-imator 的 .miobject 和 .miframes 导进 Blender
r2bb：把 Rig2 动画再导回 Blockbench 一侧

但如果从开发过程看，这些东西其实都是同一条线上的不同阶段。我最开始想解决的是“Rig2 在 Blender 里怎么更顺手地工作”，后来很快发现，真正麻烦的不是 UI，而是数据本身。只要 Mine-imator 的格式理解不够深，导入、约束、相机、灯光、IK、动作复用，最后都会变成一堆看起来能跑、实际上经不起检验的补丁。

先从 Rig2 插件本体开始

rig2_addons 这个仓库在 2026 年 2 月 23 日有了第一版成型结构。那时它主要还是一个绑定与控制工具：有基础模块、UI 面板、属性、操作符，也开始整理自己的目录结构，把代码往 src/modules、src/core、src/ui 这种比较能长期维护的布局上收。

后面几周里，我做的不是“堆功能”，而是先把 Blender 侧的使用方式固定下来：

把控制入口集中到更稳定的面板位置
给逻辑骨骼和一些关键属性做统一入口
加上中英文本地化
让 Rig2 的导入、绑定、控制这几件事在操作路径上更顺

这个阶段最重要的不是某个按钮，而是我越来越确认一件事：Rig2 不能只是一份 .blend 资产，它得有自己的工具层、自己的数据层、自己的扩展接口。否则每多做一个模块，后面维护成本都会指数上升。

真正困难的部分，其实是读懂 Mine-imator

从 2026 年 3 月初到 3 月中旬，我的重心逐渐转向 mi2bl。一开始我以为这会是一个典型的“解析 JSON -> 映射 Blender 属性”的工作，结果越做越发现，Mine-imator 的格式细节远比表面复杂。

1. `default_values` 不是你以为的“默认值”

这是我最早踩中的一个坑。

Mine-imator 的很多动画数据不是“每帧都写完整状态”，而是只保存相对引擎硬编码默认值发生变化的部分。也就是说，真正的状态恢复并不是：

keyframe -> object

而更像是：

引擎硬默认值 -> timeline 的 default_values -> 当前关键帧增量

mi2bl 在 2026 年 3 月 12 日那次重构里，开始明确实现这套三层合并逻辑。这个改动看起来偏底层，但它几乎决定了后面所有导入是否可信。没有这层，很多“看起来差一点点”的错位，其实根本不是 Blender 的问题，而是前面的状态恢复就已经错了。

2. Y/Z 轴问题不是小 bug，而是整个映射的地基

另一个特别关键的问题是坐标轴。

在实际解析里，我确认了 Mine-imator 保存的数据里，UI 里的“向上”和“深度”并不是直接按直觉落盘的，Y/Z 之间存在历史性的交换问题。所以在 mi2bl 里，位置映射最后落成了这样一组关系：

POS_X -> Blender X
POS_Z -> Blender -Y
POS_Y -> Blender Z

旋转侧也要跟着一起修，尤其是 ROT_Z 需要做符号翻转，才能和 Blender 里的朝向对齐。这个结论不是凭感觉硬试出来的，而是我在做对象导入、相机、路径约束、IK 映射时反复交叉验证后才敢定下来的。

3. 不是所有对象都应该直接变成“一个 Blender 物体”

Mine-imator 和 Blender 的变换模型并不一样，所以 mi2bl 里后来采用了比较稳定的一套做法：Pivot-based hierarchy。

简单说就是，很多节点导入后不会只生成一个对象，而是拆成：

负责承接 Mine-imator 变换的 pivot
真正承载数据的子对象

相机和灯光尤其需要这样做。因为在 Mine-imator 里，它们的旋转、默认朝向、景深、抖动、光照参数，和 Blender 原生对象的工作方式并不一致。如果不先把“变换层”和“数据层”拆开，后面的动画和约束会越来越难修。

我对 Mine-imator 做了哪些更深入的研究

做 mi2bl 之后，我顺手把很多原本只能“猜”的东西，逐步写成了文档和可复用实现。

相机

在 2026 年 3 月 9 日左右，我把 Mine-imator 相机的一批常用参数映射到了 Blender 原生属性里，包括：

FOV
DOF
focus distance
exposure
gamma
camera shake

其中抖动不是简单地塞关键帧，而是更接近 Mine-imator 原始语义地落在 Blender 的 F-curve noise modifier 上。

灯光

灯光是另一个很容易“看起来差不多，其实不对”的模块。

Mine-imator 更像是 Strength + Range 的组合模型，而 Blender 灯光更接近物理能量参数。我最后采用的是一套带物理感的转换方式，把能量近似映射为：

Energy = Strength × Range² × 4π

这并不意味着两边会像数学公式那样百分之百一致，但至少它给了我一个稳定、可重复校准的基准，而不是每种灯都靠肉眼手调。

路径系统

在 2026 年 3 月 10 日，mi2bl 开始支持把 Mine-imator 的 path/pathpoint 系统导成 Blender 里的 NURBS curve，并把跟随路径的逻辑用约束接起来。这个地方很有意思，因为它不是单纯“读点”，而是要判断它更接近 Blender 里的哪种曲线行为，最后我选择了接近 MI 语义的 order 3 NURBS。

IK

到了 2026 年 3 月 16 日，IK 这块也终于被我理顺了。

我专门去分析了 Mine-imator 对 IK_TARGET、IK_TARGET_ANGLE、IK_BLEND、IK_ANGLE_OFFSET 的处理方式，最后确认它和 Blender 里“目标物体 + 极向目标 + influence + pole angle”这一组概念是可以比较自然对齐的。也就是说，这部分不是只能做“近似模拟”，而是有机会做成比较高保真的转译。

这也是我这几个月最喜欢的一类工作：不是为了“导入成功”而导入，而是尽量先把对方格式的真实语义搞明白，再决定 Blender 里应该怎么落。

四月份，重点开始转向“能不能长期发布和维护”

如果说三月份更多是在解决“能不能正确工作”，那四月份我花的力气主要在解决“能不能长期交付”。

Face Capture 从原型走向独立模块

rig2_addons 在 2026 年 4 月 18 日开始正式接入 face_cap 模块，之后在 4 月 19 日到 4 月 25 日之间，我连续做了几轮重构：

把 face capture 的 UI、运行时和绑定逻辑拆开
支持多绑定目标
加入头部旋转的四元数应用
做本地网络状态展示
最后把接收端逻辑收敛到原生模块

对我来说，这一步的意义不只是“多了个面捕功能”，而是 Rig2 终于开始显露出“实时输入接口”这一层形态。以后不管是 face capture 还是别的驱动源，都会越来越像接到同一个骨架控制总线上。

`miframes` 和 `face_cap` 开始走向 C++ 原生后端

这是四月份另一个非常关键的变化。

从 2026 年 4 月 22 日起，到 4 月 25 日密集提交的这一批改动里，我把两块对性能和稳定性更敏感的逻辑逐步抽到了原生后端：

rig2_miframes
rig2_face_cap

同时我也做了几件以后一定会省很多事的基础设施工作：

统一 native API contract
移除 Python fallback
加入 abi3 支持
处理 Windows 宏兼容问题
做跨平台二进制打包

这一步其实挺像给插件补地基。用户最终看到的也许只是“这个按钮更快了”或者“这个功能终于不抽风了”，但对开发者来说，更重要的是后面的实现边界开始清楚了。

从“本地项目”走向“可分发产品”

到了 2026 年 4 月 30 日，我又补上了一块更偏产品化的内容：OrbisAuth 激活 + Cloudflare R2 上传工作流。

这意味着 Rig2 不再只是“我本地有一份代码和一个 .blend 文件”，而是开始具备：

商业功能解锁入口
平台相关原生模块的分发能力
更安全的二进制更新路径

我一直觉得，很多 Blender 插件项目做不下去，不是因为功能想法不够，而是发布链路太脆。只要一碰到原生依赖、多平台、授权、更新，项目就会开始变形。四月份这部分工作，说白了就是在提前处理这些迟早要来的问题。

现在回头看，我真正做的不是一个插件

如果只给 Rig2 下一个简短定义，我现在会说：

它是一套围绕 Blender 展开的 Minecraft 动画数据中间层。

绑定、控件、面捕、动作导入、格式研究、原生加速、跨工具互通，这些东西表面上分散，实际上都在服务同一件事：让 Mine-imator、Rig2、Blender 之间的数据不再只能靠经验和手工修补流动。

我现在越来越不想做那种“差不多能用”的桥接工具了。因为一旦项目规模变大，所有“差不多”最后都会变成成本。相反，只要格式研究足够扎实，很多看似麻烦的功能反而会越做越稳。

接下来我还想继续补的几块

接下来我最想继续推进的方向，大概有这些：

把 mi2bl 对更多对象类型和特殊轨道的支持继续补齐
继续压实 miframes 与 face_cap 的原生后端边界
完善 Rig2 内部的逻辑骨骼与驱动组织方式
让 r2bb 这类“导出去”的能力也尽量达到可复用、可预期的程度

如果这套生态后面真的能变成一个稳定工作流，我希望它靠的不是某一个炫目的功能，而是每一层都足够诚实：数据怎么来的，语义怎么解释，最后在 Blender 里为什么会这样工作，都说得清楚。