WebGL Debugging

Rob · January 17, 2018, 12:39am

A WebGL build of your game is a great way to share it with friends and family, however, when an error occurs in your game, it can be very difficult to initially identify the issue. Quite often be presented with a pop-up resembling this;

Not only is this not a lot of fun, it can feel incredibly overwhelming.

The following steps should help you to rebuild your project and identify the issue, hopefully, you will then be able to resolve the problem yourself, but if not, you will at least have more useful information to provide to someone else who may be able to help you.

Viewing the browser’s console

Browse to your game using Chrome^*, and then launch the developer tools;

There are several useful shortcuts for opening the DevTools:

Use Ctrl+Shift+I (or Cmd+Opt+I on Mac) to open the DevTools.
Use Ctrl+Shift+J (or Cmd+Opt+J on Mac) to open the DevTools and bring focus to the Console.

^* Other browsers will invariably have a similar tool.

You should be able to view the browser’s Console, the information it displays initially may not be overly helpful as by default Unity will;

remove unused engine code
minify code
obfuscate code

Unity does this to reduce the size of your built solution.

The following is an example of a less than helpful console log;

Changing your build settings

To access more useful information you need to prevent Unity from making the above changes, you can do so by making the following changes to your build settings;

Open Build Settings…
Check you have WebGL selected as the Platform
Tick Development Build

image.png630×611 32.1 KB
Click on the Player Settings… button
Expand Other Settings in the Inspector
Untick Strip Engine Code
Set all of the Log Types to Full

image.png491×618 30.1 KB
Expand Publishing Settings in the Inspector
Select Full With Stacktrace for Enable Exceptions
Tick Debug Symbols

Note: Screenshots were taken from Unity 2017.3.0f3 so may vary slightly depending on version

Rebuild, republish and browse

Create a new WebGL build of your game
Republish it - you could use services such as ShareMyGame.com or Itch.io.
Browse to your game
When your error occurs, view the browser’s console

Having changed the build settings, the output in the console should now be more meaningful, the Development Build won’t be minified/obfuscated and will contain human-readable method names.

If you still can’t resolve your issue

Even with the human-readable information, you may still find you are not able to resolve the issue yourself, or perhaps understand what some of the output actually means, however, you can now provide this information when you post a topic seeking help. You can either copy/paste, take a screenshot, or provide a link to your game and ask for someone to take a look at the console.

When the problem is resolved

Remember to change your build settings back and re-publish a non-development build version once your problem is resolved. You should find that the smaller build will publish more quickly and load more quickly for the players of your game.

I hope the above information is of use.