agentsclimarketplace

Webgl shader constraints

Skill adevra/unity-shader-agent-skills/skills/webgl-shader-constraints

Curated agent skills for Unity shader development targeting mobile GPUs and WebGL browsers.

Install
npx -y skills add adevra/unity-shader-agent-skills --skill webgl-shader-constraints

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 8 stars8 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

WebGL 1.0/2.0 shader restrictions, variant stripping, loop/indexing rules, and browser deployment workarounds for Unity

SKILL.md

8.3 KB, as published. Nobody here has run it

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

  1. 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.

  2. 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.

  3. 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.

  4. WebGL only supports baked GI and non-directional lightmaps. No real-time GI, no directional lightmaps, no light probes with L2 spherical harmonics.

  5. 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.

  6. 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

FeatureWebGL 1.0 (ES 2.0)WebGL 2.0 (ES 3.0)
Array indexingConstants/loop index onlyDynamic indexing allowed
LoopsCounting for onlyAll loop types
GPU instancingNoYes
3D texturesNoYes
Texture arraysNoYes
Integer texturesNoYes
texelFetchNoYes
Uniform Buffer ObjectsNoYes
Vertex texture units0 guaranteed≥16 guaranteed
MRT (Multiple Render Targets)NoYes
Deferred renderingNot possiblePossible (but expensive)
Directional lightmapsNoNo (Unity limitation)
Precision qualifiersOptionalMandatory

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--)
        {
            // Strip deferred variants (useless on WebGL)
            if (snippet.passType == PassType.Deferred)
            {
                data.RemoveAt(i);
                continue;
            }
            
            // Strip specific keywords
            var keywords = data[i].shaderKeywordSet;
            if (keywords.IsEnabled(new ShaderKeyword("_SHADOWS_SOFT")) ||
                keywords.IsEnabled(new ShaderKeyword("_ADDITIONAL_LIGHTS")))
            {
                data.RemoveAt(i);
            }
        }
    }
}

WEBGL PERFORMANCE TIPS

  1. Shader compilation blocks the main thread. Unlike native builds, WebGL compiles shaders synchronously. Many shaders = long freeze on first load. Minimize variant count.

  2. Use URP instead of Built-in for web. URP produces smaller builds and fewer shader variants when properly configured.

  3. Texture compression matters. Use ASTC (preferred) or ETC2 for WebGL 2.0. DXT/BC formats only work on desktop browsers.

  4. Memory is severely limited. WebGL runs inside the browser's memory sandbox. Large shader variant collections can trigger OOM crashes.

  5. 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

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.