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 Strip Engine Code option 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. This value is written to a variable named “TOTAL_MEMORY” in the generated html file, so if you want to experiment with this setting, you can edit the html file to avoid the need to rebuild your project.

The Enable Exceptions popup in Publishing Settings lets you enable exception support in WebGL. If you don’t need any exception support, set this to “None”, which will give you the best performance and smallest builds. Any exception thrown will cause your content to stop with an error in that setting. But if you need to use exceptions, you can set it to:

• Explicitly Thrown Exceptions Only (default), which will allow catching exceptions which are explictly thrown from a “throw” statement, and will make “finally” blocks in your code work. This will make the generated JavaScript code from your user scripts bigger and slower, but is usually not that much of an issue if scripts are not the main bottleneck in your project.
• 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, as it generates very large and very slow builds.

The Data caching checkbox in Publishing Settings lets you enable automatic local caching of your player data. If this is enabled, your assets will be stored to a local cached in the browsers IndexedDB database, so that they won’t have to be re-downloaded in subsequent runs of your content. Note that different browsers have different rules on allowing IndexedDB storage, and may ask the user for permission to store the data if this is enabled, and your build exceeds some size limit defined by the browser.

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.
• Take care when using third-party managed dlls, as those may drag in a lot of dependencies and increase the emitted code size significantly.

If you make a release build, Unity will generate a “Compressed” folder next to your build output, which contains a gzip-compressed version of your build. If your web server is configured correctly, it will use these files instead of the much larger “Release” folder, as the http protocol natively supports gzip compression (which is 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 supplies the compressed data. 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 server’s manual.

WebGL 2.0 support (Experimental)

Unity 5.2 includes support for the WebGL 2.0 API, which brings OpenGL ES 3.0-level rendering capabilities to the web. This is currently experimental and disabled by default, as no shipping browser currently supports WebGL 2.0. However, current builds of Firefox Nighly allow you to test the feature, if you enable webgl.enable-prototype-webgl2 in about:config.

To enable WebGL 2.0, uncheck Automatic Graphics API in the Other Settings section of the WebGL Player Settings. Then you can add WebGL 2.0 to the enabled graphics APIs for your build.