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)
• Read the official Unity WebGL documentation
• Read the WebGL Networking section of the Unity documentation
• 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 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 <script> 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.