FAQ

General

Does Shader Script work with the Built-in Render Pipeline?

No. Shader Script generates shaders for URP and HDRP only. See Requirements and installation.

Can I use Shader Script and Shader Graph in the same project?

Yes. They're independent: materials with Shader Script shaders and materials with Shader Graph shaders work side by side. They can't be combined, though: a Shader Graph can't use a Shader Script shader, and Shader Script code can't use Shader Graph nodes. Many nodes have a counterpart in ShaderLib, which produces the same result.

What kinds of shaders can I write?

Lit and Unlit shaders for materials, and Fullscreen shaders for post-processing. See Shader kinds and stages. Other kinds, such as compute shaders, aren't supported.

Can I use my existing HLSL code?

No. Shader code is written in C#, and there is no way to include .hlsl files or add HLSL directly. Port the functions you need to shared code: the syntax is close to HLSL, and the math functions have the same names.

Can I use Vector3, Color, Mathf or Unity.Mathematics in shader code?

No. Use the shader types, such as float3 and float4, and the math class. Unity.Mathematics has types with the same names, but they're different types, which shader code can't use: make sure using Unity.Mathematics; isn't in your shader files. See How translation works.

Does Shader Script add anything to my builds?

The generated shader is a regular Unity shader. The C# code that Shader Script generates to carry it is compiled only in the Editor, so it isn't in builds. Your shader classes stay in your assemblies, but nothing calls them at runtime.

Is a generated shader slower than a handwritten one?

The generated code is ordinary HLSL that follows your C# code closely: each statement becomes the equivalent HLSL statement, with no extra layer in between. The passes around your code are built like the render pipeline's own shaders. See How translation works.

Can I use a generated shader without Shader Script?

No. The generated shader includes files from the Shader Script package, and the .shaderscript asset is imported by the package.

Your IDE

Visual Studio doesn't show Shader Script's errors until I save the file. Why?

Visual Studio 2022 runs source generators, such as Shader Script's, only when you save a file or build the project, so by default it shows Shader Script's errors only then. To see them as you type, open Tools > Options > Text Editor > C# > Advanced, set Source Generators > Source generator execution to Automatic, and restart Visual Studio. The Unity Console shows the errors in either case. See Diagnostics.

My IDE doesn't show the descriptions of Shader Script's types and methods. How do I fix it?

Restart the IDE. Shader Script puts the file with the descriptions next to its compiled assembly when Unity compiles scripts, and an IDE that was already open, for example while you installed or updated the package, doesn't notice it. If the descriptions are still missing, make Unity compile scripts, for example by saving a change to one of your scripts, and restart the IDE again.

Working with shaders in a project

Should I commit the .shaderscript files to version control?

Yes, together with their .meta files. Materials refer to a shader by the ID in its .meta file. If the .shaderscript file isn't committed, it's recreated on another machine with a new ID, and the materials there lose their shader.

How do I change a shader's name?

Pass the name to the attribute: [Shader("My Shaders/Water")]. Materials keep their shader, since they don't refer to it by name. Scripts that find the shader by name, with Shader.Find, need the new name.

How do I rename or move a shader class?

A shader's .shaderscript asset is named after the class and lies next to the class's file. To keep the materials that use the shader:

• To rename the class, first rename the .shaderscript asset in the Project window to the new class name, then rename the class. Until the class is renamed, the asset reports an import error.
• To move the class's file, move the .shaderscript asset with it, in the Project window.

Otherwise, Shader Script creates a new .shaderscript asset, and the materials keep using the old one. Delete an old asset that you no longer need: once its class is gone, it reports an error when it's imported.

A shader has no .shaderscript asset. How do I create it?

Run Tools > Shader Script > Reimport All. This can happen when Shader Script is added to a project that already contains shader classes. See Debugging shaders for other common problems.

My question isn't here. Where can I ask?

In Discussions, Q&A on GitHub. Bugs go to Issues. See Support.