Shader Variant Explorer

What's this?

Shader Variant Explorer lets you peek into Unity's shader compilation process and understand the composition of shader files better.
Under the hood, existing Unity tools and APIs are exposed with a fast-to-use UI.

Installation 💾

Shader Variant Explorer is available on OpenUPM: https://openupm.com/packages/com.needle.shader-variant-explorer

1. Add the OpenUPM registry with the com.needle scope to your project

   • open Edit/Project Settings/Package Manager
   • add a new Scoped Registry:

   Name: OpenUPM
   URL:  https://package.openupm.com/
   Scope(s): com.needle
   

   • click Save

2. Add this package:

   • open Window/Package Manager
   • click +
   • click Add package from git URL or Add package by name
   • paste com.needle.shader-variant-explorer
   • click Add

Alternative: git package (no PackMan updates, not recommended)

• open Window/Package Manager
• click +
• click Add package from git URL or Add package by name
• paste https://github.com/needle-tools/shader-variant-explorer.git?path=package
• click Add

You can open the Shader Variant Explorer by selecting Window > Analysis > Shader Variant Explorer.

How to use 💡

1. Open Window > Analysis > Shader Variant Explorer

2. Select a shader file

3. Click Preprocess. This will run Unity's shader preprocessor, extract line and file information, and collect used keywords.
   Note: due to a limitation in Unity's APIs, this will open the resulting file. Just ignore that for now.

4. Scroll through the preprocessor result. You can double-click lines to quickly jump to their original source file.

5. Press Collapse Files to see a structural overview of the shader (which files is it composed of, and in which order).

6. In the top toolbar, you can choose the shader compilation target, e.g. Vulkan. Clicking Preprocess again will update the results.
   Note: some targets might not work or crash the shader compiler, e.g. PS5 will crash if you don't have that Unity module installed.

7. Click on Select Keyword Combination to choose which variant you want to see.
   You can also use the breadcrumb navigation to add/remove keywords.

8. Once you chose some keywords, you can also click Select Filtered Combination to pick from the remaining valid options.

9. (on 2021.2+) you can also compile just the selected keyword variant by clicking Compile selected variant or enabling Auto Compile in the right pane.

Known Issues 🦴

The shader compiler and preprocessor will crash in some combinations.
Also, you might find Unity shader bugs.

• if you create a new surface shader and select DIRECTIONAL_COOKIE — one of the valid variants returned by the preprocessor — you'll get a shader compile error)

Pressing the Compile button can take ages, depending on which shader you're trying to compile.

• URP/Lit compiles into a 2GB file
• haven't dared to check HDRP/Lit.

In some cases, the shader compiler seems to crash completely. From then on, only empty files are returned; you'll need to restart Unity.

Contact ✒️

needle — tools for unity • Discord Community • @NeedleTools • @marcel_wiessler • @hybridherbst