Unity WebGL TOTAL_MEMORY allocation

Memory problems in the browser?

Soon after we have put our development build  for Volley Brawl on Kongregate, we noticed some technical issues with memory allocation for the WebGL build. As you might know, you can adjust the TOTAL_MEMORY allocation not only in the WebGL settings, but any time later on directly in the HTML file. As memory allocation was a bit of a blackbox to us, we felt pretty insecure, how much memory we should allocate to our application and started to play around with different values.

  • 8000 MB – RangeError = invalid array length, too high allocation
  • 512 MB OK
  • 80 MB OK
  • 50 MB – Out of memory = not enough memory allocated

Total_Memory_01

As an example, with using 512 MB, the result was, that in some browsers on some machines, the game went fine but some testers provided feedback, that they could not play the game as some memory related error messages occured on loading the game in the browser. So we had to find a way to specifiy the amount of allocated memory more precisely, as too low allocation seemed to throw error messages as well as too high allocations, especially on older machines or when running different applications in the background.

Note: if you want to keep a long story short, scroll down and start reading from Autoconnecting the Unity Profiler in Dev Builds.

Browser errors

Here are two error-messages which we think are directly related to memory issues, although not explicitly mentioning this:

Total_Memory_02

According to the official Unity Manual there are two main reasons for memory issues:

  1. Browser failing to allocate memory for the Unity heap.
    • Error: Out of memory
    • cannot be easily detected, as the error message comes from the browser and does not necessarily mention the memory as a problem
    • as a countermeasure we can DECREASE the TOTAL_MEMORY parameter in the HTML file (=WebGL Memory Size in the Player Settings)
  2. Unity is exceeding the allocated memory heap
    • Error: RangeError: invalid array length
    • this one should have a more pointing error message, as it is coming from Unity.
    • the countermeasure would be to INCREASE the memory to be allocated.

The Task Manager

A first approach was to find out more about memory usage in the Task Manager. So we ran some tests and monitored the memory allocation and its changes closely:

  • Firefox only, without any webpage: ~ 210 MB
  • Loading our blog fa-games.de: ~ 310 MB
  • Loading Kongregate, without any game started ~ 380 MB
  • Loading Volley Brawl in Kongregate with 170 MB allocation: ~ 865 MB
  • Loading Volley Brawl in Kongregate with 512 MB allocation: ~ 1,200 MB

This was pretty much a proof of the allocated WebGL memory of e.g. 170 MB (respective 512 MB) was directly and completely reserved in the total memory usage of Firefox and is not something like an “upper boundary”. So this was not a valid way to find out how much memory was required in fact. We were in need of another solution.

The Log File

The next thing we looked into, was the size of the build we took from the Editor.log. This is a text file, which is updated after every build. We found it at the following location (we are using Windows 10, for other operating systems, please refer to this post):

C:\Users\username\AppData\Local\Unity\Editor\Editor.log

After scrolling down quite some pages in the file, we came across this:

Content Size Share
Textures 36.7 mb 74.9%
Meshes 1.2 mb 2.5%
Animations 151.8 kb 0.3%
Sounds 5.6 mb 11.4%
[…]
Total 48.9 mb 100%

And this one (used assets and files from the resources sprites folder, sorted by uncompressed size):

Size Share Location
5.4 mb 10.9% Assets/Sprites/dunes_far_background.tga
5.3 mb 10.9% Assets/Sprites/1024x1024_Sprites_01.png
2.7 mb 5.5% Assets/Sprites/sky_background.tga
[…]

Not very surprisingly, most space is used by textures and sounds (first table). If we try to reduce the build size in general, we can find out more about the high memory consumers in the second table. Though 48.9 MB total does not seem to be much, we should keep in mind, that this is the compressed build size. So this was also not the approach we were looking for, as it says nothing about the memory usage itself, rather than the required file size which needs to be downloaded.

Autoconnecting the Unity Profiler in Dev Builds

In order to find out what memory requirements were for real, we finally came across the Unity Profiler. To make full use of the profiler for our purposes, we need to create a development build: in the WebGL build settings, we just have to enable Development Build and Autoconnect Profiler and go for it.

Total_Memory_03

Note: the output folder for the build is then /Development and not /Release as you might be used to. Consider this in case you are using an own WebGL Template (adjust the pathes).

Furthermore, we just want to test the settings locally and our Kongregate Stats don’t work locally. Therefore, we integrated a compiler directive around these statements:

<code>
#if DEVELOPMENT_BUILD
</code>

In the end, this was exactly what we’ve been looking for: on the left, we have the dev build in Firefox, on the right, we have the auto-connected Unity Profiler. We did not even have to set this profiler up, just start the Window in Unity.

Total_Memory_04

As a result, we found out that we had a total memory allocation of 83 MB troughout the whole play time (peak). Most of which is used for Textures (45 MB).

Wow, that’s an amazing feature… thank you Unity Dev Team!

Done with number guessing!

Now that we know the amount of total memory our game requires, we could adjust the TOTAL_MEMORY parameter in the HTML file. Don’t forget to switch back from dev build to release build. The estimation from the profiler is 83 MB, in order to have some buffer, we doubled this figure and rounded up to 170 MB (which still should be low enough to fit machines with low total memory). Though it seems to be working with smaller sizes, too (successfully tested down to 80 MB).

With the methods above, we were able to figure out how large the download will be and how much memory we should allocate for the WebGL build (at least). In the end we were able to adjust the TOTAL_MEMORY parameter in the HTML file to fit our needs more precisely and received no more feedbacks that the game failed loading due to memory issues anymore.

We would be glad if this approach was a help to some of you guys out there who had similar issues with their WebGL builds, as it took us some time to get to this point.

Please submit us your feedback, if you were able to play Volley Brawl with these settings on Kongregate, or if you keep coming across memory issues.

Your Fantasy Arts Team

Share on FacebookShare on Google+Tweet about this on TwitterShare on TumblrShare on LinkedInEmail this to someone

Readers Comments (1)

  1. I think TOTAL_MEMORY is an int32 and thus can’t go beyond 20-something mb?

Leave a comment

Your email address will not be published.