Publishing Unity WebGL Games on Kongregate

The quick and painful death of the Unity Web Player has left many browser game developers scrambling to update and publish their content using Unity’s new HTML5 WebGL target. Now that Unity 5.3 is quite stable, we are recommending developers publish both Web Player and WebGL builds when hosting their games on Kongregate. Even though Unity 5.4 will remove support for the Web Player, it currently gives users the best possible experience in older browsers. This blog post will provide some best practices and tips on how to avoid common pitfalls when publishing your Unity game to Kongregate.

Preparation

The following steps will help you prepare your project for WebGL deployment on Kongregate:

We highly recommend upgrading to the latest version of Unity (at least 5.3)

Ensure your game properly functions as a Web Player build (test in FireFox/Safari)

The main takeaway from the documentation is that some of the things that "just work" in your Web Player build either flat out won’t work or could cause problems when you use the WebGL target:

Sockets will not work

HTTP requests via `WWW` need to have [CORS](http://enable-cors.org/) enabled on the server side

Unity 5.3 added a lot of features to make WebGL deployment smaller, faster, and easier

Client Modifications

If you already have a functioning Web Player build the changes required for WebGL should be fairly minimal. In general, anywhere you have a #if UNITY_Web Player block you will want to replace it with a #if UNITY_Web Player || UNITY_WEBGL block.

If you are using any plugins for your game, make sure to update them to the latest versions to address any potential issues.

Server Modifications

In order for HTTP requests to keep functioning properly in a WebGL build, Cross Origin Resource Sharing must be enabled on the server. Enable CORS is a wonderful resource for determining how to do this for your particular server application. Depending on the complexity of your server code, this could be a one-line fix or a fairly complex modification. Luckily, since many developers face this problem, there is a great chance that someone has already figured out how to do this for your particular server framework.

For one of our games using Python with Google App Engine the fix turned out to be the addition of one line in a common request handler class:

self.response.headers.add_header('Access-Control-Allow-Origin', '*')

Using an HTML Template

Note: If you are using Unity 5.6 or higher, an updated version of the following template can be found here.

Unity allows you to specify an HTML template for your WebGL build, which you can style to your liking. This is also an important step because it allows you to load the Kongregate Javascript API.

The following is a template based on a wonderful example from The Alex Ocias Blog. It removes margin/padding, loads the Kongregate Javascript API by including https://cdn1.kongregate.com/javascripts/kongregate_api.js in the head tag, features a progress bar, and has an indeterminate spinner:

You can save this file as Assets/WebGLTemplates/Kongregate/index.html in your project, and it should show up in the Player Settings for WebGL, as shown below:

It is important to note that this template is meant for games uploaded to and hosted on Kongregate, and it may not function properly if you are hosting the game yourself. If you are explicitly loading the Kongregate API in a higher-level frame (like with the Kongregate Shell), or injecting the script tag yourself via Application.ExternalEval or something similar, then the API &lt;script&gt; tag can be removed.

Building and Packaging

When you build your WebGL project, you will end up with an index.html file and a Development, Compressed, or Release folder, depending on the type of build and version of Unity. Development builds should only be used for testing/debugging, as they are extremely large and slow. Note: Unity 5.3 no longer generates a Compressed folder, as the assets are always compressed. If you are using a version of Unity lower than 5.3, we highly recommend you upgrade.

Kongregate expects your WebGL build to be submitted as a separate index.html file, and a zip with Development, Compressed, or Release folders at the top level, as shown below (for a release build):

index.html

MyGame.zip

Release

MyGame.datagz

MyGame.jsgz

MyGame.memgz

UnityLoader.js

If your assets are compressed (ending in gz as shown above) and are packaged into the Compressed or Release folder, the Kongregate web servers will deliver them so that the browser can handle the decompression, avoiding the need to expand them in JavaScript (and improving the smoothness of the progress bar).

Uploading

If you are uploading an existing Unity game to add WebGL support, you can simply click the “Upload a new version” link on your game page, and provide the WebGL ZIP file in the WebGL/HTML5 file slot.

For uploading a new game, it is recommended that you choose the Unity game type (as opposed to HTML5). This will allow us to serve the Web Player build to browsers that support it, and the WebGL version to browsers without plugin support (such as Chrome).

Once your game has finished uploading, viewing it in Chrome should show you the loading animation from the HTML template, and then the game itself:

Once you’ve done some testing, it is time to publish your game and bask in the glory of your plugin-free HTML5 game!

Demo

To see a WebGL/HTML5 game in action you can head on over and play Endless Boss Fight using Chrome.

More articles you might like:

The Long Ago Kongregate has been around for a relatively long time. We were around when Flash was cool, and also when it became uncool. We were also around when SSL was considered an optional luxury that added significant overhead and latency to network requests. Thus, we built our site with the assumption that HTTP was a fine protocol to use most everywhere, and SSL should just be used "as needed" -- for authentication, purchasing, and other sensitive data. That assumption held up for over a decade, but in recent years there has been a large movement toward using SSL everywhere, with search engines and browser vendors alike starting to punish sites for serving up un-encrypted content. Visiting Kongregate using HTTP on modern browsers was starting to become a scary and confusing experience for our players, so we decided it was time to bite the bullet and switch to using HTTPS wherever possible. The Basic Challenge Converting to SSL can be a daunting task for even simple sites without much user-generated content. Here is a short list of

Let me tell you a tale about an initiative to reduce Flash dependencies on what used to be a "Flash gaming" site. This is the story about a large-scale project with the best possible outcome being that users don't notice any changes, and the worst possible outcome of everything breaking horribly. This, my friends, is the story of Kongregate's Death to Flashy initiative. In the Beginning When we first started building Kongregate, we didn't have to worry much about whether or not users had Flash installed. It was very much ubiquitous, and since you couldn't play most of the games on the site without it we could build features based on the assumption that Flash was available. We built our chat client in Flash, we created APIs for both ActionScript 2 and 3, games implemented them, and all was good. For a very long time, the vast majority of the games on Kongregate were made with Flash, even most of our externally hosted "iframe" games. Some of these external games eventually needed a way to interact

Now that the Unity WebPlayer is mostly a thing of the past, making sure your Unity WebGL content runs smoothly is more important than ever. The main pain point that we hear from developers relates to the dreaded “out of memory” errors that end users encounter when trying to play WebGL games. This is a particularly frustrating issue for players using 32-bit versions of browsers, since they are much less likely to have a large contiguous block of free memory for the Unity heap. This article will cover some more tips and tricks for diagnosing and resolving memory-related issues with your Unity WebGL game. Monitoring Memory Usage When profiling and optimizing your Unity WebGL game, it is important to keep track of multiple kinds of memory usage. The first is the Unity heap, which defaults to 256MB and can be changed in the Publishing Settings interface under “WebGL Memory Size.” We touched on some optimization techniques for this chunk of memory (and why you want to keep it as small as possible) in a previous blog post. To reiterate, the