Building and Running a WebGL Project

When you build a WebGL project, Unity will create a folder with the following files:

• an index.html file that embeds your content in a web page.
• a JavaScript file containing the code for your player.
• a .mem file containing a binary image to initialize the heap memory for your player.
• a .data file containing the asset data and scenes.
• some supporting JavaScript files to initialize and load the player.

You can view your WebGL player directly in the Firefox browser by simply opening the index.html file. For safety/security reasons, most other browsers place restrictions on scripts opened from local file: URLs, so this technique will not work. If you use Unity’s Build & Run command (menu: File > Build & Run) then the file will be temporarily hosted in a local web server and opened from a localhost URL (this avoids the security restrictions).

Currently, the Firefox and Chrome browsers are known to support Unity WebGL players.

Build Player Options

WebGL allows you to select an Optimization level in the Build Player window. These correspond to optimization flags (-O1 - -O3) passed to the emscripten compiler. In general, “Slow” produces unoptimized builds, but has much lower build times then the other options, so it can be used for iterating on code issues. “Fast” produces optimized builds, and “Fastest” enables some additional optimizations, but makes your builds take a long time to complete (so you might want to use it only for final releases).

When you tick the “Development Build” checkbox, Unity will generate a development build (with Profiler support and the development console for errors, like on other platforms). Additionally, Development builds are non-minified, so the generated JavaScript is human-readable and preserves function names (so you will get useful stack traces for errors), but very large to distribute.

The “Autoconnect Profiler” checkbox must be used when you want to profile your Unity WebGL content. It is not possible to connect the Profiler to a running build like on other platforms, as the profiler connection is handled using WebSockets on WebGL, but the browser will only allow outgoing connections from the content, so the only way to use the Profiler in WebGL is to check “Autoconnect Profiler” to have the content connect to the Editor.

Player Settings

WebGL has some additional options in the Player Settings (menu: Edit > Project Settings > Player).

The Stripping Level popup in Other Settings lets you enable code stripping for WebGL. Note that WebGL does not differentiate between different stripping levels, it is either enabled or not. If you enable Stripping, Unity will not include code for any classes you don’t use - so if you don’t use any physics components or methods for instance, the whole physics engine will be stripped from your build.

The WebGL memory size field in Publishing Settings lets you specifiy how much memory (in MB) the content should allocate for it’s heap. If this value is too low, you will get out of memory errors when your loaded content and scenes would not fit into the available memory. But if you set this value too high, your content might fail to load in some browsers or on some machines, because the browser might not have enough available memory to allocate the requested heap size.

The Enable Exceptions popup in Publishing Settings lets you enable exception support in WebGL. It is advised to set this to “None” and not to use exceptions in WebGL for best performance. Any exception thrown will cause your content to stop with an error in that setting. But if you must use exceptions, you can set it to:

• Explicitly Thrown Exceptions Only, which will allow catching exceptions which are explictly thrown from a “throw” statement. This will make the generated JavaScript code bigger and slower.
• Full, which, additional to the above, will also generate exceptions for Null References and for out of bounds array access. These are generated by embedding checks for any access to references into the generated code, so it will cause additional code size increases and slowdowns. Also, this will add managed stack traces to exceptions. It is advisable to use this mode only when you need to debug issues in your code.

Distribution size

When publishing for WebGL, it is important to keep your build size low so people get reasonable download times before the content will start. For generic tips on reducing asset sizes, see here. Some additonal comments specific to WebGL:

• Don’t build Development builds, they are unminified to preserve function names.
• Set Optimization Level to “Fastest”
• Set “Enable Exceptions” in Player Settings to “None”
• Enable “Stripping Level” in Player Settings.

Note that Unity does not compress either the generated code or data for distribution. The reason for this is that the http protocol actually supports gzip compression on a protocol level, which is then handled natively by the browser, and thus decompresses faster then Unity could handle decompression by itself in JavaScript code. However, this means that you need to make sure that your http server actually compresses the transfers. You can check that by loading your content and inspecting network transfers in your browsers development tools. You should find “Content-Encoding: gzip” in the response headers for the js and data downloads. If you are hosting your files on an Apache web server, Unity will write an invisible .htaccess file into the build results folder, which tells Apache to compress the transfers, so this should just work. If you are using other web servers, check your servers manual.