MMDX12

Debugging and Validation

Troubleshooting compile errors, inspecting mmdx12.log, running the standalone pack_check.exe validator, and headless testing.

Handling Compiler Errors

If you make a typo or syntax mistake in your HLSL code, MMDX12 will not crash:

  1. Graceful Fallback: The affected character automatically falls back to default MMD shading so you can keep working uninterrupted.
  2. Visual Notification: A red banner notification appears at the top of the window.
  3. In-App Diagnostics: In the Shader tab, the pack’s status switches to Compile Error. Selecting the pack reveals the verbatim diagnostic output from the DXC compiler in the right inspector.
  4. Log Inspection: Detailed error messages are written to mmdx12.log (generated next to MMDX12.exe). Look for lines tagged [E] indicating the exact source file and line number: 
    [E] surface.hlsl:48:12: error: no matching function for call to 'smoothstep'

Command-Line Validator: pack_check.exe

MMDX12 ships with a dedicated validation utility, pack_check.exe, located alongside the main executable. It lets you inspect and verify pack packages without launching the full application.

Syntax

pack_check.exe <pack folder or pack.zip> [--compile]

Checks Performed

  • Manifest Integrity: Verifies required keys (version, name), ID naming rules, parameter limits (maximum 16), and material class mappings.
  • Package Limits: Enforces constraints identical to the in-app installer: total uncompressed size under 32 MB, maximum 200 files, allowed file extensions only, and absence of symlinks or hardlinks.
  • Offline Compilation (--compile): Invokes DXC to compile the HLSL shader for both raster and ray-tracing pipelines.

Exit Codes and CI Integration

  • 0: Validation passed (no problems found).
  • 1: Errors or specification violations detected.

This makes pack_check.exe an ideal tool for Continuous Integration (CI) and GitHub Actions workflows:

# Example CI pipeline step
pack_check.exe ./my_pack --compile
if [ $? -ne 0 ]; then
  echo "Shader pack validation failed"
  exit 1
fi

Template Creation and Hot Reload

  1. In the Shader Manager, click New Pack (새 팩 만들기) to scaffold a clean project from the official template.
  2. MMDX12 continuously watches active pack directories in the background.
  3. Saving pack.json, *.hlsl, *.hlsli, or the preview image immediately invalidates the cache and triggers background recompilation.
  4. You can see shader changes reflect in the viewport within milliseconds simply by pressing Ctrl + S in your code editor.

Headless Capture Testing

You can verify the visual outcome of your shader without navigating the UI by running MMDX12 in headless capture mode:

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

This runs the scene for 600 frames, dumps the resulting frame to out.png, and exits cleanly, which is perfect for automated rendering comparisons.