https://github.com/needle-tools/shader-variant-explorer
Shader Variant Explorer lets you peek into Unity's shader compilation process to better understand the composition of shader files.
https://github.com/needle-tools/shader-variant-explorer
Last synced: about 1 year ago
JSON representation
Shader Variant Explorer lets you peek into Unity's shader compilation process to better understand the composition of shader files.
- Host: GitHub
- URL: https://github.com/needle-tools/shader-variant-explorer
- Owner: needle-tools
- License: mit
- Created: 2021-07-07T00:59:50.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2023-10-12T01:58:10.000Z (over 2 years ago)
- Last Synced: 2025-04-24T08:04:51.186Z (about 1 year ago)
- Language: C#
- Homepage:
- Size: 209 KB
- Stars: 66
- Watchers: 3
- Forks: 5
- Open Issues: 1
-
Metadata Files:
- Readme: Readme.md
- License: License.md
Awesome Lists containing this project
README
# 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](https://needle.tools) •
[Discord Community](https://discord.gg/UHwvwjs9Vp) •
[@NeedleTools](https://twitter.com/NeedleTools) •
[@marcel_wiessler](https://twitter.com/marcel_wiessler) •
[@hybridherbst](https://twitter.com/hybridherbst)