Fixing WebGL Out of Memory (OOM) Crashes in Unity: Tuning WebGL Memory Size and Asset Optimization Techniques

One of the most critical and frequent issues encountered when running Unity games on the WebGL platform is an abrupt crash due to "Out of Memory (OOM)". When this occurs, the browser's developer console (F12) displays errors such as Cannot enlarge memory arrays or Out of memory, and the game screen freezes or turns into a browser-native crash screen. In this article, we will explain how the browser's virtual memory limits work with Unity, how to adjust the WebAssembly heap size, and step-by-step techniques to optimize assets to prevent crashes.

1. The Root Cause: WebAssembly (Wasm) Memory Layout and Browser Sandbox Limits

Memory management in WebGL is fundamentally different from native desktop, console, or mobile builds.

A Unity WebGL build translates C# code into C++ via IL2CPP, which is then compiled into WebAssembly (Wasm). Because Wasm runs inside a secure, sandboxed browser environment, it cannot directly access the host system's physical RAM. Instead, it operates within a contiguous block of virtual memory allocated by the browser, known as the Wasm Heap.

Out of Memory crashes occur under three main conditions:

• Exceeding the WebGL Memory Size: When the total memory demanded by active assets (textures, 3D models, audio, etc.) exceeds the initial heap size allocated in Unity's Player Settings (typically 256MB or 512MB by default).
• Browser Tab Memory Caps: Browsers (Chrome, Firefox, Safari) and mobile operating systems enforce strict memory limits per tab. Even if memory growth is allowed, exceeding these system limits causes the browser process to terminate the tab.
• Memory Fragmentation: Frequently loading and unloading assets partitions the Wasm heap into tiny, non-contiguous free blocks. Even if total free memory is high, Unity may crash because it cannot find a single contiguous block of memory large enough to fit a new asset (e.g., a high-resolution texture or a scene AssetBundle).

2. Solution 1: Tuning WebGL Memory Size (Heap Size)

First, optimize the initial WebAssembly heap allocation size to match your game's memory characteristics.

1. In the Unity Editor, navigate to Edit > Project Settings > Player.
2. Select the WebGL tab and expand the Resolution and Presentation section.
3. Locate the WebGL Memory Size field (labeled "Memory Size" in older Unity versions).

This setting determines the contiguous memory pool the WebAssembly instance reserves upon startup.

3. Solution 2: Streaming Assets and Manual Memory Release

Packaging all assets inside the primary WebGL build forces the entire project into the Wasm heap at startup. Instead, load assets dynamically over the network and purge them from memory when they are no longer in use.

Dynamic Loading via Addressable Assets

Keep the main Wasm binary small by uploading heavy assets (such as character models and environment meshes) to a remote server as AssetBundles. Load them asynchronously only when required.

Here is an example C# script showing how to load and cleanly unload an asset to reclaim heap memory:

using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;

public class AssetMemoryManager : MonoBehaviour
{
    [SerializeField] private string assetAddress = "MyLargeHeavyCharacter";
    private GameObject spawnedObject;
    private AsyncOperationHandle<GameObject> loadHandle;

    public void LoadAsset()
    {
        // Load asset asynchronously
        loadHandle = Addressables.LoadAssetAsync<GameObject>(assetAddress);
        loadHandle.Completed += OnLoadCompleted;
    }

    private void OnLoadCompleted(AsyncOperationHandle<GameObject> handle)
    {
        if (handle.Status == AsyncOperationStatus.Succeeded)
        {
            spawnedObject = Instantiate(handle.Result);
        }
        else
        {
            Debug.LogError($"Failed to load asset: {assetAddress}");
        }
    }

    // Call this to clean up the asset and free memory
    public void ReleaseAsset()
    {
        if (spawnedObject != null)
        {
            Destroy(spawnedObject);
            spawnedObject = null;
        }

        // Release the Addressables handle to return memory to the heap
        if (loadHandle.IsValid())
        {
            Addressables.Release(loadHandle);
            Debug.Log("Asset memory released from Wasm Heap.");
        }

        // Request Unity to garbage collect unreferenced asset data
        Resources.UnloadUnusedAssets();
    }
}

4. Solution 3: Optimizing Textures and Audio Compression

Because WebGL runs in browsers where hardware-specific compressed formats (like ASTC or BC7) might not be universally supported, Unity often falls back to uncompressed RGBA 32-bit textures in GPU memory, bloating memory consumption.

• Apply Crunch Compression: Enable Use Crunch Compression in the Inspector for your UI and 3D textures. This significantly reduces both the build bundle download size and the runtime memory footprint.
• Stream Audio Clips: Setting background music (BGM) to "Decompress On Load" forces Unity to decode large uncompressed audio buffers directly into the Wasm heap. Select Streaming or Compressed In Memory for long tracks instead.

5. Solution 4: Managed Code Stripping to Reduce Binary Size

Engine code and scripts themselves contribute to the initial WebAssembly binary footprint. Reduce this by stripping unused engine code.

1. Go to Edit > Project Settings > Player.
2. Expand Other Settings.
3. Locate the Optimization section and set Managed Stripping Level to Medium or High.

This automatically strips unused assemblies, classes, and physics/audio/rendering subsystems from the final build, reducing the startup memory required to initialize the Wasm module.