Unity WebGL Performance & Deployment Checklist
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:
| Check | Setting Location | Recommended Production Value | Why It Matters |
|---|---|---|---|
[ ] | Publishing Settings > Compression Format | Brotli | Typically 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 Hashes | Enabled (Checked) | Appends content hashes to filenames so CDNs can safely cache .wasm.br and .data.br with immutable. |
[ ] | Publishing Settings > Data Caching | Enabled (Checked) | Caches decompressed .data assets inside browser IndexedDB (UnityCache) for instant repeat loads. |
[ ] | Publishing Settings > Decompression Fallback | Disabled (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 Exceptions | Explicitly Thrown Exceptions Only or None | Full exception stack traces bloat .wasm binary size and slow down IL2CPP execution. |
[ ] | Other Settings > Strip Engine Code | Enabled (Checked) | Strips unused native C++ Unity modules (e.g., Terrain, Cloth, 3D Physics in a 2D game) from .wasm. |
[ ] | Other Settings > Managed Stripping Level | High (paired with Assets/link.xml) | Removes unreferenced C# classes and methods before IL2CPP translation. |
[ ] | Other Settings > IL2CPP Code Generation | Faster (smaller) builds | Optimizes generated C++ for smaller WebAssembly binary size and faster browser compilation. |
[ ] | Resolution and Presentation > Run In Background | Disabled (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.brHeaders:Content-Type: application/wasm(Required forWebAssembly.instantiateStreaming)Content-Encoding: brCache-Control: public, max-age=31536000, immutable(when using hashed filenames)
[ ][Build].framework.js.brHeaders:Content-Type: application/javascriptContent-Encoding: br
[ ][Build].data.brHeaders:Content-Type: application/octet-streamContent-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.
- Confirm the browser console does not print
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
RGBA32lightmaps or UI sprites. - Max texture resolution clamped to
1024x1024or2048x2048where appropriate; Generate Mip Maps disabled on 2D UI sprites (saving ~33% memory compared to mipmapped textures).
- All textures use hardware-compressed formats (ASTC for mobile/cross-platform WebGL or Basis Universal), avoiding unnecessary uncompressed
[ ]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).
- Background music tracks (> 5 seconds) set to Compressed In Memory (or streamed via Addressables) with Vorbis quality at
[ ]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.
- Scene transitions release previous level handles (
[ ]High-DPIdevicePixelRatioClamping:config.devicePixelRatiois clamped (for example,<= 1.5on mobile devices and<= 2.0on desktop Retina displays) so 3x mobile screens do not allocate 9x framebuffer pixel counts.
[ ]TextMeshPro Font Atlases:- Replaced dynamic OS
.ttffonts with static TextMeshPro SDF atlases restricted to required character sets.
- Replaced dynamic OS
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 Environment | Rendering Backend | Key Verification Checks | Target 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 callbacks | Meets project load-time & FPS target (e.g., 60 FPS); zero console errors |
| Desktop Firefox (Windows & macOS) | WebGL 2 | Wasm heap allocation, keyboard focus capture inside canvas/iframe, audio playback after first click | Smooth input focus; no ArrayBuffer allocation failures |
| macOS Safari | WebGL 2 (Metal) | Shader compilation hitches on first material appearance, WebAudio context resume on user click | Zero 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 switch | Zero 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 throttling | Sustained 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:
(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
- Build hangs at 90% on the loading bar:
- The
0% -> 90%progress range represents downloading.dataand.wasm;90% -> 100%represents WebAssembly instantiation and runningAwake()/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.
- The
Uncaught ReferenceError: createUnityInstance is not defined:[Build].loader.jseither failed to load (404 path mismatch) orcreateUnityInstancewas called before the<script src="...loader.js">onloadevent fired.
- Keyboard input (
WASD/ Spacebar) scrolls the host webpage:- Either embed the build inside an isolated
<iframe>(like ourWebGLEmbed.tsxarchitecture) or manageWebGLInput.captureAllKeyboardInput = falsewhen HTML inputs outside the canvas are focused.
- Either embed the build inside an isolated
- Updated build deployed to CDN, but returning players see crashes or missing assets:
- The browser served the new
.wasmbinary alongside a stale cached.datafile from IndexedDB. Enable Name Files As Hashes in Publishing Settings and bumpPlayerSettings.bundleVersion.
- The browser served the new
Frequently Asked Questions
Related Unity WebGL Guides & Consulting
- Unity WebGL Performance Guide: Wasm, Memory & Caching — Deep dive into WebAssembly streaming compilation, IndexedDB caching, and
.jslibinterop. - Unity WebGL Integration with React and Next.js — Production TypeScript patterns for embedding Unity in React/Next.js apps.
- Unity WebGL Browser Portal Optimization Guide — Two-tier loader shells for GamePix, Poki, and CrazyGames.
- Unity WebGL Optimization Consultancy — Hire an experienced Unity WebGL engineer to audit your build size, fix mobile Safari OOM crashes, or ship your browser game.
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
Unity WebGL Game Optimization Guide: Tuning Size & Performance for Browser Portals
A comprehensive guide on optimizing Unity WebGL browser games for GamePix, Poki, and CrazyGames. Master sub-15MB initial loader shells, Wasm code stripping, Basis Universal textures, and Addressable streaming.
Unity WebGL Integration with React and Next.js: Complete Engineering Guide
A production engineering guide to integrating Unity WebGL into React and Next.js applications—covering SSR avoidance, instance lifecycle cleanup, C# to TypeScript messaging, and HTTP header configuration.
Unity WebGL Performance Guide: Reduce Load Time & Memory Usage
An engineering guide to Unity WebGL performance covering WebAssembly streaming compilation, Brotli HTTP headers, IndexedDB caching, GPU texture compression, .jslib interop, and browser memory profiling.