| name | webgl-shader-constraints |
| description | WebGL 1.0/2.0 shader restrictions, variant stripping, loop/indexing rules, and browser deployment workarounds for Unity |
WebGL Shader Constraints and Workarounds for Unity
TRIGGER
Use this skill when the user is developing Unity shaders for WebGL browser deployment. Triggers include: "WebGL", "browser game", "web build", "WebGL 1.0", "WebGL 2.0", "WebGPU", "GLSL", "OpenGL ES 2.0/3.0", "shader compilation web", "web build size", "shader variants web", "Always Included Shaders", or any mention of deploying Unity content to browsers. Also trigger when the user reports shader errors only on web builds, or when dealing with build size issues related to shaders.
CORE RULES
-
WebGL 1.0 (OpenGL ES 2.0) forbids dynamic array indexing. You can only index arrays with constants or loop counter variables. This is the #1 cause of shader failures on WebGL 1.0.
-
WebGL 1.0 only allows counting for loops. No while loops, no do-while loops. The loop counter must be initialized, compared, and incremented in the for statement. The loop bound must be a constant expression.
-
WebGL 2.0 (OpenGL ES 3.0) removes loop and indexing restrictions but adds mandatory precision qualifiers. All variables must have explicit precision (highp, mediump, lowp) or use the default precision statement.
-
WebGL only supports baked GI and non-directional lightmaps. No real-time GI, no directional lightmaps, no light probes with L2 spherical harmonics.
-
Never use the Standard Shader for WebGL builds. It compiles hundreds of variants and can add 50MB+ to build size. Use Simple Lit, Unlit, or custom shaders with minimal keywords.
-
Aggressively strip shader variants for web. Every variant increases download size and initial shader compilation time (which blocks the main thread in the browser).
WEBGL 1.0 vs 2.0 FEATURE COMPARISON
| Feature | WebGL 1.0 (ES 2.0) | WebGL 2.0 (ES 3.0) |
|---|
| Array indexing | Constants/loop index only | Dynamic indexing allowed |
| Loops | Counting for only | All loop types |
| GPU instancing | No | Yes |
| 3D textures | No | Yes |
| Texture arrays | No | Yes |
| Integer textures | No | Yes |
texelFetch | No | Yes |
| Uniform Buffer Objects | No | Yes |
| Vertex texture units | 0 guaranteed | ≥16 guaranteed |
| MRT (Multiple Render Targets) | No | Yes |
| Deferred rendering | Not possible | Possible (but expensive) |
| Directional lightmaps | No | No (Unity limitation) |
| Precision qualifiers | Optional | Mandatory |
LOOP AND INDEXING WORKAROUNDS (WebGL 1.0)
// FAILS on WebGL 1.0 — dynamic array indexing
half4 colors[4];
int index = someCalculation();
half4 result = colors[index]; // ERROR: non-constant index
// WORKAROUND — unroll with if/else
half4 result;
if (index == 0) result = colors[0];
else if (index == 1) result = colors[1];
else if (index == 2) result = colors[2];
else result = colors[3];
// FAILS on WebGL 1.0 — while loop
int i = 0;
while (i < count) { /* ... */ i++; } // ERROR
// WORKAROUND — counting for loop with constant bound
for (int i = 0; i < 16; i++) // 16 is a constant
{
if (i >= count) break; // dynamic exit
// ... loop body
}
// FAILS on WebGL 1.0 — non-constant loop bound
for (int i = 0; i < _DynamicCount; i++) { } // ERROR
// WORKAROUND — constant max with early break
#define MAX_ITERATIONS 32
for (int i = 0; i < MAX_ITERATIONS; i++)
{
if (i >= _DynamicCount) break;
// ... loop body
}
SHADER VARIANT STRIPPING FOR WEB
Shader variants are the single biggest contributor to WebGL build size. Each variant must be downloaded and compiled by the browser.
Step 1: Remove Always Included Shaders
In Project Settings > Graphics > Always Included Shaders, remove everything you don't need. The Standard Shader alone adds hundreds of variants.
Step 2: Use shader_feature instead of multi_compile
// BAD for web — compiles ALL keyword combinations
#pragma multi_compile _ _FEATURE_A
#pragma multi_compile _ _FEATURE_B
// = 4 variants (2 × 2)
// GOOD for web — only compiles variants used by materials in build
#pragma shader_feature _ _FEATURE_A
#pragma shader_feature _ _FEATURE_B
// = only variants referenced by materials in scenes
Step 3: Use local keywords (max 64 per shader)
// Global keywords (shared pool of 256, wasteful)
#pragma multi_compile _ _MY_KEYWORD
// Local keywords (per-shader pool of 64, efficient)
#pragma shader_feature_local _ _MY_KEYWORD
Step 4: Conditional compilation for web
// Strip expensive features on WebGL
#if !defined(SHADER_API_GLES) && !defined(SHADER_API_GLES3)
// Desktop-only features here (SSR, complex lighting, etc.)
#endif
// Or target mobile/web specifically
#if defined(SHADER_API_MOBILE) || defined(SHADER_API_GLES) || defined(SHADER_API_GLES3)
// Simplified mobile/web path
#else
// Full desktop path
#endif
Step 5: Programmatic stripping with IPreprocessShaders
using UnityEditor.Build;
using UnityEditor.Rendering;
using System.Collections.Generic;
class WebGLShaderStripper : IPreprocessShaders
{
public int callbackOrder => 0;
public void OnProcessShader(Shader shader, ShaderSnippetData snippet,
IList<ShaderCompilerData> data)
{
for (int i = data.Count - 1; i >= 0; i--)
{
if (snippet.passType == PassType.Deferred)
{
data.RemoveAt(i);
continue;
}
var keywords = data[i].shaderKeywordSet;
if (keywords.IsEnabled(new ShaderKeyword("_SHADOWS_SOFT")) ||
keywords.IsEnabled(new ShaderKeyword("_ADDITIONAL_LIGHTS")))
{
data.RemoveAt(i);
}
}
}
}
WEBGL PERFORMANCE TIPS
-
Shader compilation blocks the main thread. Unlike native builds, WebGL compiles shaders synchronously. Many shaders = long freeze on first load. Minimize variant count.
-
Use URP instead of Built-in for web. URP produces smaller builds and fewer shader variants when properly configured.
-
Texture compression matters. Use ASTC (preferred) or ETC2 for WebGL 2.0. DXT/BC formats only work on desktop browsers.
-
Memory is severely limited. WebGL runs inside the browser's memory sandbox. Large shader variant collections can trigger OOM crashes.
-
Test on mobile browsers. iOS Safari WebGL performance is significantly worse than desktop Chrome. Many effects that work on desktop Chrome will fail or stutter on mobile Safari.
WEBGPU (FUTURE)
Unity 6 has experimental WebGPU support. When available, WebGPU removes many WebGL restrictions: compute shaders, storage buffers, better threading. However, as of 2025, WebGL 2.0 remains the production target for browser games. Write shaders targeting WebGL 2.0 and plan WebGPU as a progressive enhancement.
SOURCES
