Unity Shaders (HLSL/ShaderLab)

Hand-written shader syntax, includes, and pragmas differ sharply between Built-in Render Pipeline (BIRP) and URP, and between Unity versions. Prefer the local docs over pre-trained knowledge for block structure, include paths, and pragma directives — Unity has renamed and moved shader library files across versions, and BIRP/URP syntax is easy to cross-contaminate from memory. This skill covers hand-written .shader files only — Shader Graph and render-pipeline selection are owned by the sibling unity-rendering-pipelines skill.

Retrieval Sources

Docs root: /media/artiq/FRESH_DRIVE/Books/Unity6/Documentation/en/Manual/

Key Guidelines

ShaderLab Structure (Properties/SubShader/Pass/Tags)

ShaderLab is the outer declarative wrapper — Shader, Properties, SubShader, Pass, Tags — around one or more inner HLSL program blocks; ShaderLab itself has no math, just structure, state, and metadata. A Shader block can contain a Properties block, one or more SubShader blocks, an optional custom editor assignment, and an optional Fallback. Unity picks the first SubShader that is compatible with the current GPU/pipeline, so put your most-capable SubShader first and simpler fallbacks after it. Inside a SubShader, an optional LOD value and a Tags block (commonly RenderPipeline, Queue, RenderType) scope which pipeline and render order the SubShader applies to; a SubShader then contains one or more Pass blocks, each of which can have its own Name, its own Tags (most importantly LightMode, which controls when the pipeline runs the pass), render-state commands, and a shader code block.

Shader "Examples/StructureDemo"
{
    Properties
    {
        [MainColor] _BaseColor("Base Color", Color) = (1, 1, 1, 1)
    }

    SubShader
    {
        // SubShader Tags scope this whole SubShader to URP and the opaque queue.
        Tags { "RenderType" = "Opaque" "RenderPipeline" = "UniversalPipeline" "Queue" = "Geometry" }
        LOD 100

        Pass
        {
            Name "ForwardUnlit"
            // Pass Tags control when this specific Pass runs.
            Tags { "LightMode" = "SRPDefaultUnlit" }

            HLSLPROGRAM
            #pragma vertex vert
            #pragma fragment frag
            #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl"

            struct Attributes { float4 positionOS : POSITION; };
            struct Varyings   { float4 positionHCS : SV_POSITION; };

            CBUFFER_START(UnityPerMaterial)
                half4 _BaseColor;
            CBUFFER_END

            Varyings vert(Attributes IN)
            {
                Varyings OUT;
                OUT.positionHCS = TransformObjectToHClip(IN.positionOS.xyz);
                return OUT;
            }

            half4 frag() : SV_Target { return _BaseColor; }
            ENDHLSL
        }
    }

    // Used only if no SubShader above is compatible with the current hardware/pipeline.
    Fallback "Universal Render Pipeline/Unlit"
}

HLSLPROGRAM vs CGPROGRAM

URP/SRP shaders use HLSLPROGRAM/ENDHLSL and include files from Packages/com.unity.render-pipelines.*; legacy Built-in Render Pipeline shaders use CGPROGRAM/ENDCG and include .cginc files such as UnityCG.cginc. These are not interchangeable — mixing CGPROGRAM blocks with URP includes, or HLSLPROGRAM blocks with UnityCG.cginc, produces broken output (often solid pink/magenta) or compile errors, because the macro and function names in each library conflict or are simply absent from the other. A single Shader file can legitimately contain one SubShader targeting URP (tagged "RenderPipeline" = "UniversalPipeline") and a second SubShader with no RenderPipeline tag as a BIRP-compatible fallback, each using its own program-block type and includes — this is the standard way to ship one shader that degrades gracefully across pipelines.

Shader "Examples/DualPipelineUnlit"
{
    Properties
    {
        [MainColor] _BaseColor("Base Color", Color) = (1, 0, 0, 1)
    }

    // Picked when the active pipeline asset is a UniversalRenderPipelineAsset.
    SubShader
    {
        Tags { "RenderType" = "Opaque" "RenderPipeline" = "UniversalPipeline" }
        Pass
        {
            HLSLPROGRAM
            #pragma vertex vert
            #pragma fragment frag
            #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl"

            struct Attributes { float4 positionOS : POSITION; };
            struct Varyings   { float4 positionHCS : SV_POSITION; };

            CBUFFER_START(UnityPerMaterial)
                half4 _BaseColor;
            CBUFFER_END

            Varyings vert(Attributes IN)
            {
                Varyings OUT;
                OUT.positionHCS = TransformObjectToHClip(IN.positionOS.xyz);
                return OUT;
            }
            half4 frag() : SV_Target { return _BaseColor; }
            ENDHLSL
        }
    }

    // No RenderPipeline tag = Built-in-only. Unity falls through to this SubShader
    // when no SRP is active.
    SubShader
    {
        Tags { "RenderType" = "Opaque" }
        Pass
        {
            CGPROGRAM
            #pragma vertex vert
            #pragma fragment frag
            #include "UnityCG.cginc"

            fixed4 _BaseColor;

            struct appdata { float4 vertex : POSITION; };
            struct v2f      { float4 pos : SV_POSITION; };

            v2f vert(appdata v)
            {
                v2f o;
                o.pos = UnityObjectToClipPos(v.vertex);
                return o;
            }
            fixed4 frag(v2f i) : SV_Target { return _BaseColor; }
            ENDCG
        }
    }
}

Vertex/Fragment Function Structure

Structure vertex/fragment stages as input/output structs whose fields carry explicit HLSL semantics connecting them to mesh data — Unity's URP convention names these Attributes (vertex input) and Varyings (vertex-to-fragment output), while legacy BIRP code and tutorials often use appdata/v2f. Every Varyings-equivalent struct must include a float4 field with the SV_POSITION semantic (clip-space position); everything else is up to you, but interpolator counts are limited by target platform, so pack related data into single float4s where possible (e.g. two float2 UV sets into one float4). BIRP additionally ships prebuilt vertex-input structs in UnityCG.cginc (appdata_base, appdata_tan, appdata_full, appdata_img) so you don't have to hand-declare common combinations of position/normal/tangent/UV/color.

Shader "Examples/VertexFragmentStructure"
{
    Properties { _BaseMap("Base Map", 2D) = "white" {} }
    SubShader
    {
        Tags { "RenderType" = "Opaque" "RenderPipeline" = "UniversalPipeline" }
        Pass
        {
            HLSLPROGRAM
            #pragma vertex vert
            #pragma fragment frag
            #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl"

            struct Attributes
            {
                float4 positionOS : POSITION;
                float3 normalOS   : NORMAL;
                float2 uv         : TEXCOORD0;
                float4 color      : COLOR;
            };

            struct Varyings
            {
                float4 positionHCS : SV_POSITION;  // Required: clip-space position.
                float3 normalWS    : TEXCOORD0;    // Reuse TEXCOORD slots for custom data.
                float2 uv          : TEXCOORD1;
                float4 color       : COLOR;
            };

            TEXTURE2D(_BaseMap);
            SAMPLER(sampler_BaseMap);
            CBUFFER_START(UnityPerMaterial)
                float4 _BaseMap_ST;
            CBUFFER_END

            Varyings vert(Attributes IN)
            {
                Varyings OUT;
                OUT.positionHCS = TransformObjectToHClip(IN.positionOS.xyz);
                OUT.normalWS    = TransformObjectToWorldNormal(IN.normalOS);
                OUT.uv          = TRANSFORM_TEX(IN.uv, _BaseMap);
                OUT.color       = IN.color;
                return OUT;
            }

            half4 frag(Varyings IN) : SV_Target
            {
                half4 tex = SAMPLE_TEXTURE2D(_BaseMap, sampler_BaseMap, IN.uv);
                return tex * IN.color;
            }
            ENDHLSL
        }
    }
}

Render State (Cull/ZWrite/Blend/ZTest/Stencil)

Render-state commands (Cull, ZWrite, ZTest, ZClip, Blend, BlendOp, ColorMask, AlphaToMask, Offset, Stencil, Conservative) configure fixed-function GPU state before your shader program runs for that Pass. Placed inside a Pass block they apply to that Pass only; placed directly inside a SubShader block (outside any Pass) they apply to every Pass within it unless a Pass overrides them locally. Blending defaults to Off; when enabled without an explicit BlendOp, the operation defaults to Add, and the blend equation is finalValue = sourceFactor * sourceValue OP destinationFactor * destinationValue. ZWrite is conventionally On for opaque geometry and Off for transparent geometry (since transparent surfaces normally shouldn't occlude what's behind them); disabling it means you may need to sort geometry yourself to avoid ordering artifacts. The Stencil block's Ref/ReadMask/WriteMask/Comp/Pass/Fail/ZFail fields are all optional and independently overridable per front/back face via *Front/*Back suffixes.

Shader "Examples/RenderStateDemo"
{
    Properties
    {
        [MainColor] _BaseColor("Base Color", Color) = (1, 1, 1, 0.5)
    }
    SubShader
    {
        Tags { "RenderType" = "Transparent" "RenderPipeline" = "UniversalPipeline" "Queue" = "Transparent" }

        Pass
        {
            Cull Back
            ZWrite Off
            ZTest LEqual
            Blend SrcAlpha OneMinusSrcAlpha
            BlendOp Add
            ColorMask RGB

            Stencil
            {
                Ref 1
                Comp Always
                Pass Replace
            }

            HLSLPROGRAM
            #pragma vertex vert
            #pragma fragment frag
            #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl"

            struct Attributes { float4 positionOS : POSITION; };
            struct Varyings   { float4 positionHCS : SV_POSITION; };

            CBUFFER_START(UnityPerMaterial)
                half4 _BaseColor;
            CBUFFER_END

            Varyings vert(Attributes IN)
            {
                Varyings OUT;
                OUT.positionHCS = TransformObjectToHClip(IN.positionOS.xyz);
                return OUT;
            }
            half4 frag() : SV_Target { return _BaseColor; }
            ENDHLSL
        }
    }
}

#pragma Directives & Variants/Keywords

#pragma vertex <name> and #pragma fragment <name> are required in any regular graphics shader and name the entry-point functions; #pragma target <model> and #pragma require <features> declare the minimum shader model / GPU features the program needs (Unity warns and can fail to compile on platforms below the target). Shader keywords let one HLSL program compile into multiple variants: #pragma multi_compile <keywords> keeps every listed variant in the build regardless of whether any material currently uses it (good for things toggled at runtime by script); #pragma shader_feature <keywords> behaves the same at compile time but Unity strips variants that no material in the project actually references, shrinking the build (good for material-authored toggles). Add a leading underscore (_) as a keyword in the set to create the "all keywords in this set disabled" variant explicitly — without it, that all-off state isn't a distinct compiled variant for shader_feature/multi_compile sets of two or more keywords. Branch on keywords with a plain HLSL if (Unity compiles it to the right static branch or dynamic branch depending on the directive used) or with #if defined(...).

Shader "Examples/KeywordVariants"
{
    Properties
    {
        [MainColor] _BaseColor("Base Color", Color) = (1, 1, 1, 1)
        [Toggle(_RIM_ON)] _UseRim("Enable Rim Light", Float) = 0
    }
    SubShader
    {
        Tags { "RenderType" = "Opaque" "RenderPipeline" = "UniversalPipeline" }
        Pass
        {
            HLSLPROGRAM
            #pragma vertex vert
            #pragma fragment frag
            #pragma target 3.5

            // shader_feature: variants no material uses are stripped from the build.
            #pragma shader_feature_local _RIM_ON
            // multi_compile: every listed variant is always kept (e.g. toggled at
            // runtime via Shader.EnableKeyword / material.EnableKeyword).
            #pragma multi_compile _ _ADDITIONAL_LIGHTS

            #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl"

            struct Attributes { float4 positionOS : POSITION; float3 normalOS : NORMAL; };
            struct Varyings   { float4 positionHCS : SV_POSITION; float3 normalWS : TEXCOORD0; };

            CBUFFER_START(UnityPerMaterial)
                half4 _BaseColor;
            CBUFFER_END

            Varyings vert(Attributes IN)
            {
                Varyings OUT;
                OUT.positionHCS = TransformObjectToHClip(IN.positionOS.xyz);
                OUT.normalWS = TransformObjectToWorldNormal(IN.normalOS);
                return OUT;
            }

            half4 frag(Varyings IN) : SV_Target
            {
                half4 color = _BaseColor;
            #if defined(_RIM_ON)
                half rim = 1 - saturate(dot(normalize(IN.normalWS), half3(0, 0, 1)));
                color.rgb += rim;
            #endif
                return color;
            }
            ENDHLSL
        }
    }
}

URP Includes vs Built-in cginc Includes

URP shaders include library files from Packages/com.unity.render-pipelines.universal/ShaderLibrary/ (and .../render-pipelines.core/ShaderLibrary/); BIRP shaders include .cginc files that ship inside the Unity Editor install itself and are found on the compiler's built-in include path (no package path needed). The two hierarchies are not compatible with each other and must never both be included in the same program block.

Shader "Examples/IncludeChainDemo"
{
    SubShader
    {
        Tags { "RenderType" = "Opaque" "RenderPipeline" = "UniversalPipeline" }
        Pass
        {
            HLSLPROGRAM
            #pragma vertex vert
            #pragma fragment frag

            // Core.hlsl pulls in Common.hlsl, SpaceTransforms.hlsl, Packing.hlsl, etc.
            #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl"
            // Lighting.hlsl pulls in RealtimeLights.hlsl, AmbientOcclusion.hlsl, and
            // Shadows.hlsl. It's safe to include alongside Core.hlsl — URP headers
            // use include guards.
            #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Lighting.hlsl"

            struct Attributes { float4 positionOS : POSITION; };
            struct Varyings   { float4 positionHCS : SV_POSITION; };

            Varyings vert(Attributes IN)
            {
                Varyings OUT;
                OUT.positionHCS = TransformObjectToHClip(IN.positionOS.xyz);
                return OUT;
            }

            half4 frag() : SV_Target
            {
                Light mainLight = GetMainLight();
                return half4(mainLight.color, 1);
            }
            ENDHLSL
        }
    }
}

Writing a Basic Lit Shader

A hand-written lit shader means reimplementing the lighting model yourself — sampling the main light, applying shadow attenuation, and (if needed) looping over additional lights — that Shader Graph's Lit target or BIRP Surface Shaders normally generate for you. In URP, GetMainLight() returns a Light struct with direction/color/distanceAttenuation/shadowAttenuation, but shadowAttenuation only reflects real shadowing if you instead call the shadow-coordinate overload GetMainLight(shadowCoords), where shadowCoords comes from GetShadowCoord(VertexPositionInputs); you also need a multi_compile for the main-light shadow keywords so the correct shadow-sampling variant compiles in. Critically, the object also needs a ShadowCaster pass so other objects can receive shadows cast by it — rather than hand-writing one, UsePass can pull in the built-in Lit shader's, referencing it by uppercased Pass name.

Shader "Examples/BasicLit"
{
    Properties
    {
        [MainTexture] _BaseMap("Base Map", 2D) = "white" {}
        [MainColor] _BaseColor("Base Color", Color) = (1, 1, 1, 1)
    }

    SubShader
    {
        Tags { "RenderType" = "Opaque" "RenderPipeline" = "UniversalPipeline" "Queue" = "Geometry" }

        Pass
        {
            Name "ForwardLit"
            Tags { "LightMode" = "UniversalForward" }

            HLSLPROGRAM
            #pragma vertex vert
            #pragma fragment frag

            // Required so this shader can access the main light's shadow map.
            #pragma multi_compile _ _MAIN_LIGHT_SHADOWS _MAIN_LIGHT_SHADOWS_CASCADE _MAIN_LIGHT_SHADOWS_SCREEN
            #pragma multi_compile _ _ADDITIONAL_LIGHTS

            #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Lighting.hlsl"

            struct Attributes
            {
                float4 positionOS : POSITION;
                float3 normalOS   : NORMAL;
                float2 uv         : TEXCOORD0;
            };

            struct Varyings
            {
                float4 positionCS   : SV_POSITION;
                float3 normalWS     : TEXCOORD0;
                float2 uv           : TEXCOORD1;
                float4 shadowCoords : TEXCOORD2;
            };

            TEXTURE2D(_BaseMap);
            SAMPLER(sampler_BaseMap);
            CBUFFER_START(UnityPerMaterial)
                float4 _BaseMap_ST;
                half4 _BaseColor;
            CBUFFER_END

            Varyings vert(Attributes IN)
            {
                Varyings OUT;
                VertexPositionInputs posInputs = GetVertexPositionInputs(IN.positionOS.xyz);
                VertexNormalInputs   nrmInputs = GetVertexNormalInputs(IN.normalOS);

                OUT.positionCS   = posInputs.positionCS;
                OUT.normalWS     = nrmInputs.normalWS;
                OUT.uv           = TRANSFORM_TEX(IN.uv, _BaseMap);
                OUT.shadowCoords = GetShadowCoord(posInputs);
                return OUT;
            }

            half4 frag(Varyings IN) : SV_Target
            {
                half4 albedo = SAMPLE_TEXTURE2D(_BaseMap, sampler_BaseMap, IN.uv) * _BaseColor;

                // The shadowCoords overload sets Light.shadowAttenuation from the
                // main light's shadow map instead of always returning 1.
                Light mainLight = GetMainLight(IN.shadowCoords);
                half3 diffuse = LightingLambert(mainLight.color, mainLight.direction, normalize(IN.normalWS))
                                 * mainLight.distanceAttenuation * mainLight.shadowAttenuation;

                return half4(albedo.rgb * diffuse, albedo.a);
            }
            ENDHLSL
        }

        // Reuse the built-in Lit shader's ShadowCaster pass rather than hand-writing
        // one — this is what lets OTHER objects receive shadows cast by this shader.
        UsePass "Universal Render Pipeline/Lit/SHADOWCASTER"
    }
}

Common Mistakes

Quick Reference

Advanced Notes

Shader variant stripping for build size. URP shaders lean heavily on keywords, so an unaudited shader can compile into thousands of variants, each adding to build size and build time. To check actual variant counts, set a non-Disabled Shader Variant Log Level under Project Settings > Graphics > URP > Additional Shader Stripping Settings, enable Development Build, and build — Unity logs a per-shader Total=<kept>/<total>(<percent>) breakdown to the Console and Editor.log (search for Shader Stripping); enabling Export Shader Variants additionally writes Temp/graphics-settings-stripping.json and Temp/shader-stripping.json. To actually reduce the count: enable Strip Unused Variants in the same settings panel (URP then strips variants for features disabled across every URP/Universal Renderer asset in the build); disable unused features (post-processing effects, XR/VR modules) at the project-settings level rather than per-shader, since that's what lets the stripper prove a variant is unreachable; and disable individual shader keywords directly via Shader Build Settings in Graphics settings when you know a feature is unused project-wide. Also strip debug-only pragmas (#pragma enable_d3d11_debug_symbols) before a final build — they disable optimizations and bloat every affected variant. See urp/shader-stripping-features.html and urp/shader-stripping-check.html.

multi_compile vs shader_feature, precisely. Both declare a set of mutually-related keywords and compile one shader variant per combination, but they differ in when unused variants get discarded. multi_compile variants are always included in the build — use it for keywords toggled by script/runtime logic (quality tiers, platform capability keywords like UNITY_DEVICE_SUPPORTS_NATIVE_16BIT) where you can't know ahead of time which variant a given build needs. shader_feature variants are stripped at build time unless some material in the build actually references that keyword combination — use it for keywords exposed as material-authored toggles (e.g. a [Toggle] property), since most projects only ever use a handful of the possible combinations. Both directives support _local suffixes (e.g. shader_feature_local) to scope the keyword to the containing shader only rather than declaring it globally, which further reduces global keyword pressure — a shader is limited to roughly 128 total keywords (4 of which Unity reserves) before performance in the Editor degrades. dynamic_branch is a third option that compiles a single program with a true runtime branch instead of separate variants — no variant explosion at all, at the cost of a per-fragment/vertex branch; prefer it for keywords that change value frequently per-frame or per-object where variant-count reduction matters more than avoiding a branch. Use #pragma skip_variants <keyword...> to prune specific variants out of a built-in keyword shortcut set (e.g. multi_compile_fwdadd plus skip_variants POINT POINT_COOKIE) when you know some lighting combinations never occur in your project.