MMDX12

调试与验证

排查着色器编译错误、分析 mmdx12.log 日志、使用命令行验证工具 pack_check.exe 以及自动化无头测试方法。

处理着色器编译错误

在编写 HLSL 遇到拼写错误或类型不匹配时，MMDX12 具备完善的容错保护机制：

  1. 平滑安全回退：发生编译报错的角色模型会立即自动切换回 MMD 原生着色，确保软件界面与视口不会崩溃闪退。
  2. 全局通知栏：主视口上方将弹出显眼的红色警告通知。
  3. 软件内诊断面板：点击顶部导航栏的“셰이더（着色器）”标签页，该包的状态会显示为“컴파일 오류（编译错误）”，右侧检查器面板会完整列出 DXC 编译器的原生错误日志。
  4. 定位日志文件：查看与 MMDX12.exe 同目录生成的 mmdx12.log，搜索以 [E] 开头的报错行，即可精准定位出错的文件名与具体代码行号： 
    [E] surface.hlsl:48:12: error: no matching function for call to 'smoothstep'

独立验证工具：pack_check.exe

随 MMDX12.exe 一同分发的 pack_check.exe 是一个专门用于离线检验着色器包完整性的独立命令行工具，无需打开图形界面即可运行。

命令行语法

pack_check.exe <包目录或包.zip> [--compile]

检查要点

  • 清单语法：校验 pack.json 必填项（version、name）、ID 命名规范、参数上限（最多 16 个）以及材质分类语法。
  • 文件体积与安全约束：确保解压总体积不超过 32 MB、文件总数不超过 200 个、无非法文件扩展名及软硬链接。
  • 离线编译验证（--compile）：直接调用 DXC 编译器对光栅化与光追着色器进行语法及语义编译测试。

退出代码与 CI 自动化

  • 0：校验通过，未发现问题。
  • 1：检测到错误或规范违例。

该工具非常适合集成至 GitHub Actions 或各类持续集成（CI）自动化流水线中，用于在提交 PR 时自动把关质量：

# CI 脚本配置示例
pack_check.exe ./my_pack --compile
if [ $? -ne 0 ]; then
  echo "着色器包验证失败"
  exit 1
fi

模板生成与热重载流

  1. 在软件着色器管理器中点击“새 팩 만들기（新建包）”，从官方模板快速脚手架工程。
  2. MMDX12 在后台持续监听激活包所在的文件夹。
  3. 只要在代码编辑器中保存 pack.json、*.hlsl、*.hlsli 或预览图片，软件便会立即清除旧缓存并在毫秒级内完成静默重编译。
  4. 开发者只需在编辑器中按下 Ctrl + S，即可在旁侧的 MMDX12 视口中实时预览光影改动。

无头渲染捕获测试（Headless Mode）

无需手动进入 UI，可通过命令行让 MMDX12 自动播放指定动作并截取特定帧画面输出为图片：

MMDX12.exe --character "ModelName" --song "SongName" --autoplay --shader-pack my_pack --frames 600 --capture out.png

程序会在运行至第 600 帧时自动将视口保存为 out.png 并安静退出，十分便于在持续集成中进行着色前后的图像视觉比对。