Version: 2023.1
WebGL native plug-ins for Emscripten
Cache behavior in WebGL

Memory in Unity WebGL

Memory constraints in Unity WebGL can restrict the complexity of the content you run.

WebGL 内容在浏览器中运行。浏览器在其内存空间中分配应用程序运行内容所需的内存。 可用内存量因以下因素而异:

  • The device you use
  • The operating system you use
  • The browser you use, and whether it runs on a 32 or 64 processor
  • 浏览器的 JavaScript 引擎解析代码所需的内存量
  • 浏览器为每个选项卡使用单独进程,还是内容需要与所有其他打开的选项卡共享内存空间。

Note: For information on security risks related to WebGL memory, refer to Security and Memory Resources.

Memory usage in Unity WebGL

The following areas of Unity WebGL content require the browser to allocate significant amounts of memory.

Unity 堆

Unity uses a memory heap to store all Unity engine runtime objects. These include managed and native objects, loaded Assets, Scenes, and shaders. This is like the memory that Unity Players use on any other platform.

The Unity heap is a contiguous block of allocated memory. Unity supports automatic resizing for the heap to suit the needs of the application. The heap size expands as an application runs, and can expand up to 2GB. Unity creates this memory heap as a Memory object. The Memory object’s buffer property is a re-sizable ArrayBuffer that holds the raw bytes of memory accessed by WebAssembly code.

Automatic resizing of the heap can cause your application to crash if the browser fails to allocate a contiguous memory block in the address space. For this reason, it’s important to keep the Unity heap size as small as possible. Therefore, be mindful when you are planning the memory usage of your application. If you want to test the size of your Unity heap, you can use the Profiler to profile the contents of the memory block.

You can control the initial size and growth of the heap by using the Memory Growth Mode options in the WebGL Player Settings. The default options are configured to work well for all desktop use cases. However, for mobile browsers you need to use the advanced tuning options. For mobile browsers, it’s recommended to configure the Initial Memory Size to the typical heap usage of the application.

Asset data

When you create a Unity WebGL build, Unity generates a .data file. This contains all the Scenes and Assets the application needs to launch. Because Unity WebGL doesn’t have access to the real file system, it creates a virtual memory file system, and the browser unpacks the .data file here. The Emscripten framework (JavaScript) allocates this memory file system in the browser memory space. While your content runs, the browser memory keeps the uncompressed data. To keep both download times and memory usage low, try to keep this uncompressed data as small as possible.

To reduce memory use, you can pack your Asset data into AssetBundles. AssetBundles offer full control over your asset downloads. You can control when your application downloads an asset, and when the runtime unloads it. You can unload unused assets to free up memory.

AssetBundles are downloaded directly into the Unity heap, so these don’t result in extra allocation by the browser.

Enable Data Caching to automatically cache the Asset data in your content on the user’s machine. This means you don’t need to re-download that data during later runs. The Unity WebGL loader implements Data Caching with the IndexedDB API. This option lets you to cache files which are too large for the browser to cache natively.

Data caching enables the browser to store application data on the user’s machine. Browsers often limit the amount you can store in their cache and the maximum file size that can be cached. This is often not enough for an application to run smoothly. The Unity WebGL loader Caching with the IndexedDB API that lets Unity store the data in the IndexedDB instead of the browser cache.

要启用数据缓存选项,请转到 File > Build Settings > Player Settings > Publishing Settings

垃圾收集

Garbage collection is the process of locating and freeing up unused memory. After the garbage collector collects unused memory it reallocates it inside the Unity heap. The garbage collector will then inspect the stacks and register for loaded object references. If the garbage collector finds an object that’s no longer referenced, it frees up the memory used by that object.

For an overview on how Unity garbage collection works, refer to Automatic Memory Management. WebGL garbage collection runs when the stack is empty. The stack is a part of the Unity heap but not the heap itself. As you cannot debug in JavaScript, the garbage collector will only run in WebGL in situations where the stack is empty. This currently happens once after every frame.

On most other platforms, the garbage collection process is different, where the collector pauses all running threads so it can inspect the stack. You can debug the garbage collection process using the Unity Profiler.

The garbage collector runs on the main thread. That is, if you have a long-running loop, the following code might fail when you run it on WebGL because the collector doesn’t get a chance to run the garbage collector between iterations of the loop. This means the garbage collector can’t free up memory that the intermediate string objects use, and runs out of memory in the Unity heap.

string hugeString = "";
 
for (int i = 0; i < 100000; i++)
 
{
 
 hugeString += "foo";
 
} 

其他资源

WebGL native plug-ins for Emscripten
Cache behavior in WebGL