Version: 2020.1
Using materials with C# scripts
Physically Based Rendering Material Validator

Scripting for materials that use the Standard Shader

In the Built-in Render Pipeline, the Standard ShaderA built-in shader for rendering real-world objects such as stone, wood, glass, plastic and metal. Supports a wide range of shader types and combinations. More info
See in Glossary
has some extra requirements if you want to modify materials at runtime.

This is because - behind the scenesA Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More info
See in Glossary
- the Standard ShaderA small script that contains the mathematical calculations and algorithms for calculating the Color of each pixel rendered, based on the lighting input and the Material configuration. More info
See in Glossary
is actually many different shaders rolled into one. These different types of shader are called Shader VariantsAn internal version of the Shader that Unity generates according to the specific combination of Shader keywords and their status. If you add more keywords to the Shader, you increase the number of possible combinations, which results in more Shader Variants. More info
See in Glossary
and can be thought of as all the different possible combinations of the shader’s features, when activated or not activated.

For example, if you choose to assign a Normal MapA type of Bump Map texture that allows you to add surface detail such as bumps, grooves, and scratches to a model which catch the light as if they are represented by real geometry. More info
See in Glossary
to your material, you activate that variant of the shader which supports Normal Mapping. If you subsequently also assign a Height Map then you activate the variant of the shader which supports Normal Mapping and Height Mapping.

This is a good system, because it means that if you use the Standard Shader, but do not use a Normal Map in a certain material, you are not incurring the performance cost of running the Normal Map shader code - because you are running a variant of the shader with that code omitted. It also means that if you never use a certain feature combination (such as HeightMap & Emissive together), that variant is completely omitted from your build - and in practice you will typically only use a very small number of the possible variants of the Standard Shader.

Unity avoids simply including every possible shader variant in your build, because this would be a very large number, some tens of thousands! This high number is a result not only of each possible combination of features available in the material InspectorA Unity window that displays information about the currently selected GameObject, asset or project settings, allowing you to inspect and edit the values. More info
See in Glossary
, but also there are variants of each feature combination for differing renderingThe process of drawing graphics to the screen (or to a render texture). By default, the main camera in Unity renders its view to the screen. More info
See in Glossary
scenarios such as whether or not HDRhigh dymanic range
See in Glossary
is being used, lightmapsA pre-rendered texture that contains the effects of light sources on static objects in the scene. Lightmaps are overlaid on top of scene geometry to create the effect of lighting. More info
See in Glossary
, GI, fog, etc. Including all of these would cause slow loading, high memory consumption, and increase your build size and build time.

Instead, Unity tracks which variants you’ve used by examining the material assets used in your project. Whichever variants of the Standard Shader you have included in your project, those are the variants which are included in the build.

This presents two separate problems when accessing materials via script that use the Standard Shader.

1. You must enable the correct Keywords for your required Standard Shader variant

If you use scripting to change a material that would cause it to use a different variant of the Standard Shader, you must enable that variant by using the EnableKeyword function. A different variant would be required if you start using a shader feature that was not initially in use by the material. For example assigning a Normal Map to a Material that did not have one, or setting the Emissive level to a value greater than zero, when it was previously zero.

The specific Keywords required to enable the Standard Shader features are as follows:

Keyword Feature
_NORMALMAP Normal Mapping
_ALPHATEST_ON “Cut out” Transparency Rendering ModeA Standard Shader Material parameter that allows you to choose whether the object uses transparency, and if so, which type of blending mode to use. More info
See in Glossary
_ALPHABLEND_ON “Fade” Transparency Rendering Mode
_ALPHAPREMULTIPLY_ON “Transparent” Transparency Rendering Mode
_EMISSION Emission Colour or Emission Mapping
_PARALLAXMAP Height Mapping
_DETAIL_MULX2 Secondary “Detail” Maps (Albedo & Normal Map)
_METALLICGLOSSMAP Metallic/Smoothness Mapping in Metallic Workflow
_SPECGLOSSMAP Specular/Smoothness Mapping in Specular Workflow

Using the keywords above is enough to get your scripted Material modifications working while running in the editor.

However, because Unity only checks for Materials used in your project to determine which variants to include in your build, it will not include variants that are only encountered via script at runtime.

This means if you enable the _PARALLAXMAP keyword for a Material in your script, but you do not have a Material used in your project matching that same feature combination, the parallax mapping will not work in your final build - even though it appears to work in the editor. This is because that variant will have been omitted from the build because it seemed to not be required.

2. You must make sure Unity includes your required shader variants in the build

To do this, you need to make sure Unity knows that you want to use that shader variant by including at least one Material of that type in your Assets. The material must be used in a scene or alternatively be placed in your Resources Folder - otherwise Unity will still omit it from your build, because it appeared unused.

By completing both of the above steps, you have the full ability to modify your Materials using the Standard Shader at runtime.

If you are interested in learning more about the details of shader variants, and how to write your own, read about Making multiple shader program variants here.

Using materials with C# scripts
Physically Based Rendering Material Validator