Workaround for shader variant explosion freeze that occurs during build is a serious technical bug that frequently occurs in real-machine testing and rendering pipeline extensions. Explanation of the solution to the variant explosion where the progress bar freezes and stops for several minutes at the shader compilation step when building a Unity project.

Specific symptoms of the problem

When executing a project build in Unity, the Unity editor completely freezes the moment the "Compiling Shader..." progress bar is displayed, and no progress is made for more than 30 minutes, or in the worst case, the editor is forced to close (crash) due to insufficient memory.

Real-world analogy: A factory punk that wastefully mass-produces hundreds of thousands of all-purpose jutoku knives with all the combinations of attachments they don't use

As a result of trying to manufacture tens of thousands of Jutoku knives with scissors, nail clippers, and bottle openers as separate actual knives for each of the ``all patterns (knives with only scissors sticking out, knives with scissors and bottle opener sticking out, etc.)'' that customers might order) and displaying them in a warehouse, the factory (compiler) got punctured and froze. By changing to a system (Shader Feature) that only creates patterns (materials used) that are actually ordered on the spot, we can instantly reduce the number of pieces produced to just a few pieces.

Workaround for shader variant explosion freeze that occurs during build troubleshooting diagram

Figure: Shader variant Overview of the defect occurrence mechanism and resolution approach for the workaround for explosion freeze that occurs during build

Assumed causes and detailed mechanism

This is because the combinations of multiple custom keywords (Shader Keyword: #pragma multi_compile, etc.) defined in the shader multiply, and millions of "shader variants (substantive programs)' are automatically generated internally, causing the CPU's pre-compilation processing to reach its limit and become punctured.

Solution approach and optimization procedure

Open the Shader Graph custom keyword settings and switch the definition type from "Multi Compile (forcibly generate all combinations)" to "Shader Feature (automatically detect and generate only the combinations actually used in the project)". Additionally, we have introduced the "IPreprocessShaders" script (Shader Stripping) that automatically thins out unnecessary combinations during build, dramatically reducing the total number of variants.