Kongregate Developers

Back to Blog Posts

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:

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:

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

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:

WebGL Template Settings

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 zipped with the index.html file at the top-level, and Development, Compressed, or Release folders alongside it, as shown below (for a release build):

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).

Uploading a game

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:

Loading

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.

EBF

Author

Ben Vinson

While studying for his B.S. in Computer Science from the University of Colorado, Ben was a major contributor to the book Software Engineering for Game Developers.

After graduating, Ben started work as a game developer at Electronic Arts. He was also the creator of the Leeroy Jenkins video, which is probably his greatest achievement to date.

Follow us on Twitter to keep up-to-date with our weekly blog posts.

Comments