MMDX12

Overview: What is a Shader Pack?

Learn what MMDX12 shader packs are, how they work, which render paths support them, and their folder structure.

Introduction to Shader Packs

MMDX12 shader packs let you customize how a character model’s materials are shaded on a per-character basis. Without altering the underlying engine renderer, anyone can create custom cel-shading or distinctive anime styles with just a few lightweight files.

A shader pack is simply a folder containing:

  • pack.json: The manifest defining metadata, material classification rules, and configurable sliders.
  • surface.hlsl: HLSL source code implementing a single shading entry point (PackShade).
  • preview.png or preview.jpg (optional): A preview image for the shader manager and online gallery (16:9 recommended).
  • README.md, LICENSE (optional): Documentation and licensing terms.

Supported Render Paths and Scope

Shader packs integrate seamlessly into real-time playback and offline video rendering workflows.

Where Shader Packs Apply

  • Raster Path: Standard play mode, the Studio viewport, and video exports using the “래스터” (Raster) renderer.
  • Real-Time Ray Tracing Path: The RT viewport and video exports using the “실시간 RT” (Real-time RT) renderer.
  • Path Tracing and Offline GI (MMDX12 1.5.0+): packs that ship an optional pt_surface.hlsl also shade the path tracer and the offline GI renderer (stills and videos). See PT / GI Packs. A pack without that file uses the default shading there.

Where Default Shading is Preserved

  • Path Tracing and Offline GI for packs without pt_surface.hlsl: they use the default shading model. The offline GI renderer always draws the app’s default outlines.
  • Stages and Props: Background stages, furniture, and accessory props are never shaded by character packs.
  • Special Views: Studio Unlit, Wireframe, and orthographic quad views retain default shading.

Engine Guarantees

Shader packs strictly replace the pixel shading of character materials. The following aspects remain managed by the engine and continue to work as expected:

  • Vertex skinning and skeletal animation transforms
  • Characteristic MMD edge outlines
  • Cascaded shadow maps and ray-traced shadows
  • All post-processing effects (bloom, depth of field, TAA, upscalers, etc.)

Where Packs Live

Pack folders are located relative to the MMDX12 executable:

  1. Built-in Packs: <MMDX12 folder>/shaders/packs/<id>/
    • Shipped with the application; cannot be deleted from within the app (e.g. hoyo_toon).
  2. Installed Packs: <MMDX12 folder>/shader_packs/<id>/
    • Packs installed from the online gallery, imported from zip archives, or created by you. Packs downloaded online also contain .mmdx_install.json.

Pack ID Rules

  • Lowercase letters a-z, digits 0-9, underscores _, and hyphens -, up to 64 characters.
  • Built-in pack IDs cannot be replaced by user packs.
  • If a duplicate ID is found, the subsequent pack is marked as a “duplicate” and cannot be selected.

Next Steps

  • Quickstart: Using packs in the app and creating a new pack with live hot reload.
  • Manifest Specification: Deep dive into pack.json fields, material rules, and parameters.
  • Shader API: Contract details for surface.hlsl and available helper functions.
  • Screen Effect Packs: Whole-screen post-processing packs (API 3), the effect stack and the online-only gallery effects.
  • PT / GI Packs: pt_surface.hlsl, shading a pack in the path tracer and the offline GI renderer.
  • HoYo Toon Walkthrough: Detailed analysis of the bundled anime cel-shading pack.
  • Debugging and Validation: Interpreting compiler output and using the standalone pack_check.exe tool.
  • Publishing and Gallery: Packaging your zip and submitting to the official gallery.