Unity WebGL
WebGL Optimization
Checklist
Browser Games
WebAssembly
Game Engineering

Unity WebGL Performance & Deployment Checklist

9 min read
Eshan Naithani

Shipping a Unity WebGL build to a self-hosted web app, Next.js frontend, or browser game portal (such as GamePix, Poki, or CrazyGames) requires verifying both Unity Editor build settings and server/browser runtime behavior. A single misconfigured HTTP header or uncompressed texture atlas can turn a fast-loading build into a 60 MB+ download that triggers memory pressure on mobile browsers.

Use this engineering checklist before every staging and production WebGL release. For deep architectural explanations behind each check, refer to our Unity WebGL Performance Guide and Unity WebGL React & Next.js Integration Guide.


1. Unity Editor Build & Player Settings Checklist

Configure these settings in Edit > Project Settings > Player > WebGL before building your release artifact:

CheckSetting LocationRecommended Production ValueWhy It Matters
[ ]Publishing Settings > Compression FormatBrotliTypically reduces uncompressed .wasm and .data transfer payloads substantially (e.g., 62%–83% in our Unity 6 AI NPC demo build, depending on asset compressibility).
[ ]Publishing Settings > Name Files As HashesEnabled (Checked)Appends content hashes to filenames so CDNs can safely cache .wasm.br and .data.br with immutable.
[ ]Publishing Settings > Data CachingEnabled (Checked)Caches decompressed .data assets inside browser IndexedDB (UnityCache) for instant repeat loads.
[ ]Publishing Settings > Decompression FallbackDisabled (if you control CDN headers) / Enabled (only if host blocks .br headers)Native HTTP Content-Encoding: br enables WebAssembly.instantiateStreaming without JS decompression stalls.
[ ]Publishing Settings > Enable ExceptionsExplicitly Thrown Exceptions Only or NoneFull exception stack traces bloat .wasm binary size and slow down IL2CPP execution.
[ ]Other Settings > Strip Engine CodeEnabled (Checked)Strips unused native C++ Unity modules (e.g., Terrain, Cloth, 3D Physics in a 2D game) from .wasm.
[ ]Other Settings > Managed Stripping LevelHigh (paired with Assets/link.xml)Removes unreferenced C# classes and methods before IL2CPP translation.
[ ]Other Settings > IL2CPP Code GenerationFaster (smaller) buildsOptimizes generated C++ for smaller WebAssembly binary size and faster browser compilation.
[ ]Resolution and Presentation > Run In BackgroundDisabled (unless multiplayer)Prevents hidden browser tabs from burning CPU/GPU battery when the user switches tabs.

2. Server Compression, MIME Type & Hosting Checklist

Verify these HTTP response headers in Chrome DevTools > Network on your live staging URL:

  • [ ] [Build].wasm.br Headers:
    • Content-Type: application/wasm (Required for WebAssembly.instantiateStreaming)
    • Content-Encoding: br
    • Cache-Control: public, max-age=31536000, immutable (when using hashed filenames)
  • [ ] [Build].framework.js.br Headers:
    • Content-Type: application/javascript
    • Content-Encoding: br
  • [ ] [Build].data.br Headers:
    • Content-Type: application/octet-stream
    • Content-Encoding: br
  • [ ] CORS Headers (When Hosting Build Files on a Separate CDN Domain):
    • Access-Control-Allow-Origin: https://yourdomain.com (or * for public static assets)
    • Access-Control-Expose-Headers: Content-Length, Content-Encoding
  • [ ] Zero Console Streaming Warnings:
    • Confirm the browser console does not print WebAssembly.instantiateStreaming failed because your server does not serve wasm with application/wasm MIME type.

3. Memory Profiling & Asset Footprint Checklist

Browser tabs operate within OS- and browser-enforced memory limits that vary by device RAM and browser architecture, and the WebAssembly linear memory ArrayBuffer does not shrink back to the OS once expanded during a session. Audit every asset category in Editor.log and the Unity Memory Profiler:

  • [ ] Texture Compression Format:
    • All textures use hardware-compressed formats (ASTC for mobile/cross-platform WebGL or Basis Universal), avoiding unnecessary uncompressed RGBA32 lightmaps or UI sprites.
    • Max texture resolution clamped to 1024x1024 or 2048x2048 where appropriate; Generate Mip Maps disabled on 2D UI sprites (saving ~33% memory compared to mipmapped textures).
  • [ ] AudioClip Load Types:
    • Background music tracks (> 5 seconds) set to Compressed In Memory (or streamed via Addressables) with Vorbis quality at 35%–50% and Force To Mono enabled where stereo separation is unnecessary.
    • Avoid leaving long music tracks set to Decompress On Load (for example, a 3-minute stereo 44.1 kHz 16-bit track expands from a ~3 MB compressed file to ~30 MB+ of raw PCM RAM).
  • [ ] Addressables Reference Count Verification:
    • Scene transitions release previous level handles (Addressables.Release) before allocating the next level's bundles so peak Wasm heap memory stays flat.
    • Ran Window > Asset Management > Addressables > Analyze > Check Duplicate Bundle Dependencies to confirm zero duplicated shared materials or textures across bundles.
  • [ ] High-DPI devicePixelRatio Clamping:
    • config.devicePixelRatio is clamped (for example, <= 1.5 on mobile devices and <= 2.0 on desktop Retina displays) so 3x mobile screens do not allocate 9x framebuffer pixel counts.
  • [ ] TextMeshPro Font Atlases:
    • Replaced dynamic OS .ttf fonts with static TextMeshPro SDF atlases restricted to required character sets.

4. Browser Compatibility Test Matrix

Before signing off on a release, execute this test matrix across real target devices (not just Desktop Chrome DevTools mobile emulation):

Target EnvironmentRendering BackendKey Verification ChecksTarget Pass Criteria (Adjust to Project Scope)
Desktop Chrome / Edge (Windows & macOS)WebGL 2 (ANGLE D3D11 / Metal)Initial load time, IndexedDB cache hit on reload (from disk cache / IndexedDB), fullscreen toggle, .jslib callbacksMeets project load-time & FPS target (e.g., 60 FPS); zero console errors
Desktop Firefox (Windows & macOS)WebGL 2Wasm heap allocation, keyboard focus capture inside canvas/iframe, audio playback after first clickSmooth input focus; no ArrayBuffer allocation failures
macOS SafariWebGL 2 (Metal)Shader compilation hitches on first material appearance, WebAudio context resume on user clickZero black/magenta shader fallbacks; audio unmutes cleanly
iOS Safari (iPhone / iPad)WebGL 2 (Metal; device- & OS-dependent Jetsam memory limits)Play 3 consecutive level transitions + trigger fullscreen/orientation lock + background/foreground tab switchZero tab reloads ("A problem repeatedly occurred"); thermal stability
Android Chrome (Mid-Range 4GB RAM Device)WebGL 2 (ANGLE Vulkan / GLES)Touch input latency, devicePixelRatio frame rate, memory stability under 4G throttlingSustained target FPS (e.g., 30 or 60 FPS); initial download within portal/project budget

5. Before / After Optimization Measurement Template

Copy this markdown table into your pull requests, engineering post-mortems, or client optimization reports to record verifiable improvements:

MARKDOWN
### Unity WebGL Optimization Benchmark Report
- **Project / Build Version**: [e.g., v1.4.0]
- **Unity Version**: [e.g., Unity 6000.0.x LTS]
- **Test Device & Browser**: [e.g., Chrome 130 Desktop + iPhone 14 iOS Safari]

| Metric | Baseline (Before) | Optimized (After) | Delta (%) |
| :--- | :--- | :--- | :--- |
| **Uncompressed `.wasm` Size** | __ MB | __ MB | __% |
| **Compressed `.wasm.br` Transfer Size** | __ MB | __ MB | __% |
| **Compressed `.data.br` Transfer Size** | __ MB | __ MB | __% |
| **Total Initial Network Download** | __ MB | __ MB | __% |
| **Cold Load Time to Interactive (Fast 4G)** | __ sec | __ sec | __% |
| **Warm Load Time (IndexedDB Cache Hit)** | __ sec | __ sec | __% |
| **Peak Wasm Linear Heap Size** | __ MB | __ MB | __% |
| **Peak Total Browser Tab Memory** | __ MB | __ MB | __% |
| **Average Frame Time / FPS (Gameplay)** | __ FPS (__ ms) | __ FPS (__ ms) | __% |
| **Batches / SetPass Calls (Peak Scene)** | __ / __ | __ / __ | __% |

(For a real-world example using this exact methodology, see how our AI NPC WebGL Demo compressed 62.20 MB of raw .wasm and .data artifacts down to 13.71 MB via Brotli, or review our Bird Sort Mania Case Study.)


6. Common Deployment Failures & Quick Fixes

  1. Build hangs at 90% on the loading bar:
    • The 0% -> 90% progress range represents downloading .data and .wasm; 90% -> 100% represents WebAssembly instantiation and running Awake()/Start() in Scene 0. If the bar freezes at 90%, check the browser DevTools Console for an unhandled C# exception in Scene 0 initialization or a blocked synchronous network call.
  2. Uncaught ReferenceError: createUnityInstance is not defined:
    • [Build].loader.js either failed to load (404 path mismatch) or createUnityInstance was called before the <script src="...loader.js"> onload event fired.
  3. Keyboard input (WASD / Spacebar) scrolls the host webpage:
    • Either embed the build inside an isolated <iframe> (like our WebGLEmbed.tsx architecture) or manage WebGLInput.captureAllKeyboardInput = false when HTML inputs outside the canvas are focused.
  4. Updated build deployed to CDN, but returning players see crashes or missing assets:
    • The browser served the new .wasm binary alongside a stale cached .data file from IndexedDB. Enable Name Files As Hashes in Publishing Settings and bump PlayerSettings.bundleVersion.

Frequently Asked Questions


Need help architecting or optimizing your Unity mobile game? Let's discuss your technical roadmap.

Share this article

Get Practical Unity Development Insights

Technical guides on Unity performance, AI gameplay systems, mobile monetization, and game development.

Unsubscribe at any time. Your data is never shared.

Recommended Reading

More articles in Unity WebGL