Quick Fixes

Vertex Form package uses WebGL 2 by default for Web builds, and for most projects that remains the right choice. WebGPU is available as an experimental alternative, and this guide covers what it offers, how to turn it on, and the problems you are likely to hit once you do.

Why WebGPU

WebGL 2 is based on older native graphics APIs. WebGPU is designed around modern GPU architecture and maps onto Vulkan, Direct3D 12, and Metal, which allows the browser to use the GPU far more efficiently.

The practical gains:

• Compute shaders. The single biggest reason to move. WebGL 2 has no compute support at all, so any GPU-side data processing — streaming, culling, simulation, procedural generation — has to be faked or done on the CPU.
• Lower driver overhead, which translates to better frame times in draw-call-heavy scenes.
• Modern rendering features that the WebGL 2 backend cannot express.

The tradeoff is maturity. WebGPU is experimental in Unity and explicitly not recommended for production. Browser support varies, and several Unity subsystems do not work correctly on the backend yet.

Enabling WebGPU

WebGPU is not enabled automatically the way WebGL 2 is. You add it manually:

1. Open Edit → Project Settings → Player.
2. Select the Web settings tab.
3. Expand Other Settings.
4. Disable Auto Graphics API. Unity now shows the Graphics API list.
5. Click + and choose WebGPU (Experimental).
6. Drag WebGPU to the top of the list.

Unity uses the first API in the list as the default and tries the next one if the first is unavailable. Keeping WebGL 2 below WebGPU gives you a fallback for browsers without WebGPU support.

A critical caveat about that fallback: it only fires when device creation fails. If WebGPU initializes successfully and then fails to render, users get a black screen with no automatic recovery. Do not treat the fallback as a safety net for the issues below.

Issue 1: Black screen caused by WebXR

This is the most common cause of a completely black canvas.

WebXR currently renders exclusively through WebGL. The XRGPUBinding specification that would allow WebGPU rendering in XR sessions is an unimplemented proposal, and Unity's WebXR Export package is built on XRWebGLLayer, which cannot be created in a WebGPU context.

A WebXR provider registering against a WebGPU device interferes with the render loop even outside an immersive session, so the page goes black on normal load.

Fix: open Project Settings → XR Plug-in Management → Web and disable the WebXR provider, then rebuild.

There is no workaround. WebGPU and WebXR are mutually exclusive until the binding ships in browsers and Unity's package adopts it. If XR support is a hard requirement for your project, WebGPU is not currently an option.

Issue 2: Wrong colors and unlit scenes

Two symptoms come from the same subsystem:

• Colors are globally shifted compared to the Editor — typically a warm cast where the Editor shows cool tones.
• A scene loads correctly when opened first, but renders black or unlit when loaded after another scene.

Both point at the baked lighting pipeline failing to decode or regenerate on the WebGPU backend.

In Window → Rendering → Lighting → Environment:

In Project Settings → Player → Other Settings:

Regenerate lighting after each change, since these alter what gets baked. Change one setting at a time so you know which one mattered.

Setting Ambient Source to Color is a visual downgrade — it removes directional ambient information, which is noticeable in spaces lit largely by the sky. Try Uncompressed reflections on their own first; if that resolves the problem, leave Source on Skybox and keep the better lighting.

Issue 3: Other known causes

• MSAA with stacked cameras (URP). A documented Unity 6 issue produces black screens in Web builds when MSAA is enabled alongside a Base plus Overlay camera stack. Disable MSAA in the URP asset or unstack the cameras to test.
• IL2CPP managed code stripping. Scripts referenced only through serialization or reflection can be stripped out of the build. Set Managed Stripping Level to Minimal to test; if that fixes it, write a link.xml rather than disabling stripping permanently.
• Stale build cache. Toggling graphics APIs or color space can leave incremental artifacts that confuse the next link step. Delete Library/Bee and the player artifacts, then rebuild clean.

Isolating an unknown cause

When the cause isn't obvious, bisect rather than guess:

1. Build a minimal scene — one camera, one lit primitive, WebGPU only.
2. If it renders, the backend works and the problem is in your content or packages. Add things back until it breaks.
3. If it doesn't render, the problem is environmental and your project isn't implicated.

Test scene transitions explicitly. A scene that renders correctly on first load can still fail when loaded second, and only navigating between scenes will surface it.

Recommended approach

Establish a working WebGL 2 baseline before enabling WebGPU, so you always have a known-good build to compare against. Keep WebGL 2 as the priority graphics API for anything user-facing, and treat WebGPU as an experimental branch until the capability you need from it — usually compute shaders — outweighs the remaining instability.