So, you have been working on Mobile games for a while using Unity, and probably heard that with Unity 5 it was possible to port your games for the Web sans Unity Web Player.

Great, right? Well, yeah, but there are a few things to know before making your game work with WebGL.

Let’s start by answering the following question:

WHY IS WEBGL SO IMPORTANT FOR GAME DEVELOPMENT?

For starters the Web has always been a strong platform with an established user base of about everyone. At the time of writing this, with WebGL you can target almost every desktop platform that has a relatively modern Web browser without the need of installing any additional plugins.

But the most important part of building for the Web is that you control the distribution. Forget about sending your build for review, or uploading your package through a console and waiting hours to test your build. With web technologies it has always been a matter of uploading your files via FTP and seeing the changes reflected in real time.

This is clearly and advantage when you are iterating fast and want to test your latest build on an environment that resembles production.

Also important to mention is that Google Chrome has recently dropped support for NPAPI, which means plugin based games (like those using Unity Web Player) won’t longer run on that Browser. Other browsers may follow in this decision in the future, so it’s better to be prepared.

But enough for an introduction, let’s move  on to the interesting stuff. As with any other platform, when you build your Unity 5 project for WebGL, there are a few things to take into consideration.

Here’s a handy list of issues we ran into when porting our first game from Android/iOS to Facebook Canvas (all this information can also be found on Facebook’s Developer Documentation and/or Unity docs):

FIRST THINGS FIRST: UNSUPPORTED NAMESPACES

Everything in the System.Net namespace (particularly System.Net.Sockets) are non-functional in WebGL.

According to Unity docs, this is because:

Due to security implications, JavaScript code does not have direct access to IP Sockets to implement network connectivity.

If you need to use Networking in WebGL, you currently have the options to use the WWW or UnityWebRequest classes in Unity or the new Unity Networking features. It’ll bring some headaches because of CORS (Cross-origin resource sharing), which basically means you won’t be able to access any other URL that is not in the same domain as the one where your game is hosted. Alternatively, you can also shoot yourself in the foot… mhhh, I mean, if you own the server that you are trying to access, you can add some headers to your Apache configuration to enable CORS.

This is probably one of the biggest headaches you’ll have to solve in order to port your game to WebGL (if you use asset bundles or need to download resources from an external server).

Just in case you were wondering:

The same applies to Unity’s old UnityEngine.Network* classes, which are not available when building for WebGL.

Let’s make it clear: this is not Unity’s fault, at all, it’s just the way the Web is designed to work.

WebGL is an AOT (ahead of time) platform, so it does not allow dynamic generation of code using System.Reflection.Emit.

Basically, anything in the System.Threading namespace is not supported.

So far we’ve dealt with unsupported namespaces. For us, the way to work around these issues was to use Visual Studio 2015′s search tools to do a search in our Entire Solution for files where those namespaces were being imported (using namespace blabla). Afterwards we would add a pre-processor directive for !UNITY_WEBGL, and find a way to fix all the errors that came up when the offending namespaces where removed (with further uses if UNITY_WEBGL).

Example:

#if !UNITY_WEBGL
using System.Threading;
#endif

SECOND: ASSET BUNDLES

There are some considerations when using AssetBundles on the WebGL platform:

When you are using class types in your AssetBundle which are not used in your main build, this can cause Unity to strip the code for those classes from the build, which will then cause it to fail when trying to load assets from the AssetBundle. Information about how to deal with this issue can be found here.

Since WebGL does not support threading, and since http downloads will only become available when finished, Unity WebGL builds need to decompress AssetBundle data on the main thread when the download is done, thus blocking the main thread. To avoid this interruption, you may want to avoid using the default LZMA Format for your AssetBundles, and compress using LZ4 instead, which is decompressed very efficiently on-demand. If you need smaller compression sizes then LZ4 delivers, you can configure your web server to gzip-compress the files on the http protocol level (on top of LZ4 compression).

THIRD: BUILDING AND TESTING

This is probably one of the worse parts of building for WebGL. It’s not clear what each setting does to the final build or how you are supposed to test and debug your game. Read through this section to find out and thank me later.

You can view your WebGL player directly in most browsers by simply opening the index.html file. For security reasons, Chrome places 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). You can also run Chrome with the –disable-web-security command line option to enable it to load content from file: urls.

In our case, we created a simple *.bat script with this single line (edit accordingly if you installed Chrome in another directory):

“C:\Program Files (x86)\Google\Chrome\Application\chrome.exe” –disable-web-security

At least in Windows, you’ll be able to have the script in your desktop and double-click it to launch a Chrome window that will allow CORS. We found this is the simplest way to test builds on the fly and used this flow during our process. It even works for builds that are hosted on a server.

Tips for building:

These are quoted word to word from Unity docs, but we marked those that we’ve found have the most effect in the final build size and performance.

Specify the “Crunch” texture compression format for all your compressed textures in the Texture Importer (Depends on your project).

Don’t deploy Development builds, they are not compressed or Minified and so have much larger file sizes (VERY IMPORTANT for build size).

Set Optimization Level to “Fastest” (VERY IMPORTANT for performance).

Set “Enable Exceptions” in Player Settings to “None” if you don’t need exceptions in your build (VERY IMPORTANT for performance).

Enable “Strip Engine Code” in Player Settings (VERY IMPORTANT for build size).

Take care when using third-party managed dlls, as those may drag in a lot of dependencies and increase the emitted code size significantly (Didn’t affect us).

Update: Settings exceptions to “None” could bring issues if your code depends on Exceptions in order to execute properly (for example, when calling a server). You’ll have to test this and find out what works best for your game.

Profiling WebGL

You can use the Unity profiler on WebGL, just like on any other platform. One important distinction is that you cannot attach to running players in WebGL, though, as WebGL uses WebSockets for communication, which will not allow incoming connections on the browser side. Instead, you need to use the “Autoconnect profiler” checkbox in the build settings. Note also that draw calls cannot currently be profiled for WebGL.

Debugging WebGL

Good luck with this. Currently, it’s not possible to debug WebGL builds. In our workflow, we went old school and added Debug.Log calls in the places where we were having problems. Every browser has it’s own developer console that is usually accessed by pressing F12.

Combining this with a Development build with exceptions enabled is your best bet.

Browser compatibility

Up-to date information for each browser and version can be found here.

That said, it’s also good to consider some of the older browsers that don’t offer good/any WebGL compatibility. In those cases, (like Internet Explorer), it’s best to have a Unity Web Player build and load one or the other depending on Browser support.

On the other hand, Google Chrome completely ditched Unity Web Player support, so the only option there is to go with WebGL. All in all, we recommend using WebGL for every browser except IE.

Something to note is that it works surprisingly well on Edge, Chrome is Okay and in my experience Firefox has been the worst (more on that in the next point).

Memory!

This is another big problem. The browser will complain if you assign too much memory, but it will crash if you don’t assign enough. So basically, it’s an exercise of finding the right amount so the browser will allow it to run, but at the same time won’t crash during run-time.

There are two ways in which you can change the amount of memory the game will require at startup (this is the only time when a game gets assigned memory in WebGL, so you need to make sure it’ll be enough to fit the whole game plus any assets you’ll need to download during run-time). The first method is using Player Settings in Unity Editor. Under WebGL settings, select Publishing Settings and enter the memory size. Default is 256MB. In our case, it was enough for the Release build (around 90MB), but not for the Development build (around 300 MB).

This is where Firefox has been the worst for us. Every other browser had no problem in assigning 512 MB of memory for a Development build to run, except Firefox. That means (in our case) we were not able to test Development builds. It’s not that bad, but if your game is larger than ours, it could come to a case where not even your Release build will run.

We are still doing some research about this point in particular and will update when there are new findings.

Update: as someone mentioned on a Reddit comment, this is because Firefox is already using too much memory on other tabs, not because it can’t assign 512MB. Closing and re-opening Firefox does the trick.

The second way to change your memory size is by opening the index.html file generated by Unity, and navigating to the piece of code shown below: