Files
VRMify-Enhanced/tools
Black-Cyan 60cce66993
Tests / test (push) Has been cancelled
初始化 VRMify 增强版(VRMify Enhanced)
导入上游源码,为所有面向用户的品牌显示处添加「增强版 / Enhanced」标识;包含 unitypackage→VRM 的纯色 Toon 材质、兽耳 SpringBone、Unity 描边、UV 接缝白边补偿修复,以及默认不强制 T-pose。146 个单元测试通过。
2026-11-15 23:21:59 +08:00
..

工具

VRMify 增强版 · Enhanced fork 的开发与批量处理脚本。

开发和批量处理用的脚本,不随程序打包。转换器本身(convert/、formats/)只用 Python 标准库; 这里的检查工具另需 jsonschema(pip install -r requirements-dev.txt)和 Node.js。

批量转换 batch_convert.py

python tools/batch_convert.py model -o vrm
python tools/batch_convert.py model -o vrm --only 穗穗 爱弥斯 --variants spring
  • 模型目录下每个子文件夹算一个角色,递归找所有 .pmx;文件夹里的 .zip 中的 PMX 也会解出来一起转 (在临时目录里解压,不改动模型目录)。
  • 默认输出两份:<输出>/有SpringBone/<角色>/ 和 <输出>/无SpringBone/<角色>/。
  • 「<名字>by<游戏>_<哈希>」形式的文件夹名会整理成「<游戏>—<名字>」。
  • --report 结果.json 保存每个模型的日志。

静态检查 qa/check_vrm.py

python tools/qa/check_vrm.py vrm          # 递归检查目录下所有 .vrm
python tools/qa/check_vrm.py a.vrm -v     # 通过的也打印摘要

检查 humanoid 结构、网格、表情绑定、SpringBone 链,以及 VRM 官方 JSON Schema (第一次运行时从 vrm-c/vrm-specification 下载固定版本,缓存在 qa/.schema-cache/)。 UniVRM 对不合规数据很少容错——比如材质颜色绑定少一个分量、BlendShape 重名,都会让 Unity 里的 导入直接中断(表现为卡在加载中),这些都会被它报出来。有错误时退出码为 1。

动态测试 qa/dynamics.py

cd tools/qa/harness && npm install        # 第一次
python tools/qa/dynamics.py vrm/有SpringBone -j 4
python tools/qa/dynamics.py a.vrm --fps 30 --jitter 0.3 --motions idle,walk_real,run,leg_raise

用 three.js + three-vrm 在 Node 里无界面地跑 SpringBone(和 UniVRM 同一套规则),测:

指标 含义 参考范围(VRoid / 官方示例模型)
静止偏移 站着不动 2 秒后弹簧末端离绑定姿势的距离 < 5 cm
hf 末端 8 Hz 以上的颤动能量 / 链长 ×1000(平均 / 最大) 头发 2~16,裙摆 3~58
swing 末端最大摆幅 / 链长 —
穿腿 裙摆关节落在模型自己腿部碰撞体里的比例(含静止时的重叠,和 idle 对比看) —
张开 相邻裙摆链末端比静止时多分开的距离(平均 / 90% / 最大,cm);腿把裙子从中间劈开时变大 原 PMX 的 MMD 物理:走路 4~15

动作:idle(放下手臂、轻微晃动)、walk_real / run(带根运动的走路 / 跑步)、leg_raise (抬腿 70°)等,定义在 qa/harness/motions.mjs。超出参考范围的数值标「!」,--strict 时返回 1。

回归对比 regress.py

改转换代码前后,用本机的真实模型确认输出有没有变、变在哪里:

python tools/regress.py record model/角色A model/角色B/某.pmx   # 记下基准(默认 VRM 1.0,--spec 0x 记 0.x)
python tools/regress.py check                                   # 用当前代码重转、校验、对比基准
python tools/regress.py check --code ../旧版本的代码目录          # 用另一份代码转(比如 git worktree)
  • 基准在 tests/.golden/(不进仓库:模型许可不允许再分发,衍生数据也只留在本机),记录 glTF JSON 全文和二进制块的 sha256。
  • check 对每个样本:转换 → check_vrm 结构和 Schema 校验 → 列出 JSON 里不同的路径(最多 20 条)、二进制块是否一致。 有错误或差异时退出码为 1。变化是否符合预期要自己判断,确认后重新 record。

骨骼自检扫描 scan_models.py

python tools/scan_models.py model ~/Downloads -o 结果.txt

对目录里的每个 PMX(压缩包在临时目录里解开)只跑骨骼处理和转换时的自检,不写 VRM,几秒一个: 付与骨合并了几根、按比例拆权重的骨有几根,以及自检问题——网格在 MMD 里跟着关节转、在 VRM 里却不跟, 或者 humanoid 骨位置明显不对(在身体另一侧、离父骨或网格太远)。这些问题转换时也会写进日志。 改骨骼相关的代码前后各跑一次对比,发版前跑一次;有自检问题时退出码为 1。

表情截图 qa/snapshots.py

python tools/qa/snapshots.py a.vrm -o a.png                     # 全身、脸、表情预设、口型、眨眼、视线四个方向
python tools/qa/snapshots.py 旧/a.vrm 新/a.vrm -o 对比.png       # 每个输入一行,上下对照
python tools/qa/snapshots.py model/角色/角色.pmx -o a.png         # 不是 VRM 的先用当前代码转一份(临时目录)
python tools/qa/snapshots.py a.vrm --custom --cols 12 -o a.png  # 再加上自定义表情,每段 12 列

用无界面的 Edge / Chrome(--browser 指定路径)加载界面预览用的 ui/viewer/viewer-core.js 来拍, 和程序里看到的一致;WebGL 走软件渲染,不依赖显卡,一个模型几秒。模型没有的表情格子标「无」。 改表情相关的代码前后各拍一张对照,比只看 regress.py 的 JSON 差异直观。

单元测试 tests/

python -m unittest discover -s tests -v

不需要真实模型:tests/synth.py 合成一个小的 MMD 人形 PMX(标准骨名、头发物理、几个表情、两张贴图), 测转换(1.0 / 0.x、元信息、结果确定性、贴图瘦身)、转换后调整(vrm_edit 的套用 / 还原 / 幂等)和 zip 输入。 装了 jsonschema 时顺带做官方 Schema 校验;没装 Pillow 时跳过贴图瘦身的测试。

程序图标 make_icon.py

python tools/make_icon.py      # → ui/icon.ico(exe 图标)+ ui/web/icon.png(页面图标),需要 Pillow

圆角蓝底 + 白色菱形,和界面左上角的「◆」一致;改颜色、形状就改这个脚本再重新生成。

打包发布 build_release.py

python tools/build_release.py                          # → dist/VRMify-v<版本>-win64.zip
python tools/build_release.py --expect-version v0.1.0  # tag 和 ui/version.py 不一致时报错(Actions 里这么调用)

按 VRMify.spec 打包,把 LICENSE、README 放进程序文件夹,再压成绿色版 zip。GitHub Actions 的 release.yml 用的也是它,流程见 README 的「开发」一节。

冒烟测试 smoke_exe.py

python tools/smoke_exe.py dist/VRMify-v0.1.2-win64.zip   # 发布 zip、解开的程序文件夹或 exe 都行

单元测试测源码,这里测打包以后的 exe:用临时数据目录启动 --no-open,通过它自己的 HTTP 接口 加入合成的 PMX / zip / FBX / unitypackage 并转换,检查版本号、页面和预览库、每个输出过 check_vrm、 PMX 原生预览和调整面板接口。PyInstaller 漏打模块或页面资源时会在这里失败(退出码 1,并打印 exe 的输出)。 release.yml 打包后自动跑,不通过就不建 Release。