Debugging HTML5 Games In The Browser

Currently GameMaker:Studio does not come with expansive debug tools for the HTML5 module (this may change with future updates). This does not mean, however, that you cannot easily debug your HTML5 games as there are many dedicated tools for this already available for the different browsers:

- For FireFox you have the excellent Firebug

- For IE8 (IE9 and above has one included) you have Visual Studio For Web

- For Chrome you have the Chrome Debugger

For this article, we have used Chrome it is by far the easiest to use and is also built into the browser itself (note that if you use one of the other browsers, most of the debug tools are the same or very similar anyway).

Overview

Before going into the details, let's start with a brief overview of the basic tool-set that is at your fingertips when using Chrome for debugging. To start with, you should run your game in GameMaker:Studio (making sure that the drop-down target list shows HTML5) and then in the browser right-click the page outside of the canvas element (the game screen) and select Inspect Element (you can also goto the settings menu at the top right of the page and select Tools >>> Developer Tools).
HTML5_InspectElement.png
This will then open a debug console at the bottom of the screen, with a series of icons like this:
HTML5_Chrome_Debugger.png
Below is a brief description of each of these icons and what they do:

Elements - The Elements panel allows you to see the web page as the browser sees it. That is, using the Elements panel, you can see the raw HTML, raw CSS styles, the Document Object Model, and edit these elements live – this means immediate feedback on changes to HTML, CSS, and/or scripts.

Resources - The Resources panel lets you inspect resources that are loaded / available to the inspected page. It lets you interact with Frame trees containing frame resources (HTML, JavaScript, CSS, Images, Fonts, etc.), HTML5 Databases, Local Storage, Cookies and AppCache.

Network - Use the Network panel to learn what components your web page or application is requesting from web servers, how long these requests take, and how much bandwidth is required. You can also view the HTTP request and response headers for each of your resources. The Network panel is perfect for helping you speed up page load times.

Sources - To peer inside the JavaScript for a page, you will use the Sources panel. Here you can find a list of scripts required by the page plus a full featured script debugger.

Timeline - For advanced timing and speed analysis, the Timeline panel offers in-depth visibility into the various Chrome behind-the-scenes activities. You can learn how long the browser takes to handle DOM events, rendering page layouts, and paint the window.

Profiles - The Profiles tool helps you capture and analyze the performance of JavaScript scripts. For example, you can learn which functions take the most time to execute and zoom in on exactly where to optimize.

Audits - The Audit panel is like having your own web optimization consultant sitting next to you. This panel can analyse a page as it loads and provide suggestions and optimizations for decreasing page load time and increase perceived (and real) responsiveness.

Console - Last but definitely not least, the Developer Tools offers a full featured Console. From the Console, you can enter arbitrary JavaScript to programmatically interact with your page.

Although these are all very useful for helping to optimise web pages, we are going to concentrate on only a few of these tools as they are what will help us most when debugging our game: Elements, Resources, Network and possibly the most important of all, Sources.

Elements

As stated above, the Elements panel permits us to view the web page in it's "raw" state (ie: as the browser itself sees the page), and this is an excellent place to start our debugging as it gives us an overview of all the elements that go into making our HTML5 game work. It's worth noting that the layout of this page may show certain differences with the HTML that you have written for your web page that holds your game... this is normal and to see the exact HTML of your page you should use the Resources tab (see below).
HTML5_Element_Tab.png
Above you can see an example image of the elements tab of the Chrome debugger. The important things to note here are as follows:

  1. You can expand and contract parts of the HTML structure to see more (or less) of the page. You may need to do this to get to the JavaScript or to see the elements that you need.
  2. The magnifying glass permits you to highlight and click on any part of the web page and automatically expand that section in the elements view. For example, if you want to quickly find the canvas element (which is where your HTML5 game will be shown), you can click on the magnifying glass, then click on your game and the HTML will expand to show you the relevant code section.
  3. Although GameMaker:Studio calls your game an HTML5 game, it is really made with JavaScript and then shown on the screen using the HTML5 canvas element. This means that the game code itself is not shown in the elements tab, but you can click on the JavaScript name in this tab and it will open up the Source tab to show you the code as it runs.

It is worth noting too that as you mouse over the code in the elements console you will see that the different sections of HTML will highlight on screen as they are shown in the browser, making it exceptionally easy to pinpoint errors or see how changing the code will affect the look of your game. You can even double click on HTML elements and edit them in real time to see how the change will look, or right-click on an element and select Edit as HTML to edit the "raw" HTML. This gives you a great opportunity to change the size, position and layout of your game screen!

Resources

The Resources tab is incredibly important when it comes to debugging your HTML5 game. Here you can see everything that is included with your web page: graphics, sounds, HTML, CSS, etc... as well as what's been placed into local storage and session storage.
HTML5_Resources_Tab.png
The image above is a typical overview of what you can see when you are testing your HTML5 game on Chrome. At the top we have the Frames folder, which is where you can find the contents of your game itself, shared over various sub-folders. You can inspect any one of these elements by simply clicking on it which will then show its contents on the right of the debugger. As you can see in the example image, this is a great way to see how your texture pages are organised!

This page will also show you the "raw" JavaScript and any errors that may be occurring with it (in the above image you can see that beside the "Scripts" there is a number highlighted in red... that is the number of found errors!), as well as the HTML code and quite a few other details. One thing in particular that may be of interest to you if you are saving information to (and loading from) files is the Local Storage section. Here you can get a list of all files currently stored in local storage and if you select any of them, then you will also get a list of the file's contents:
HTML5_LocalStorage.png
In this way you can check your saved information to make sure it is what you would expect and debug any saving or loading of resources or information in case there are any errors there. It is also worth noting that if you right-click on any of the resources on this tab, you can get further options, like viewing the resource in full screen or saving it to disk.

Network

The Network tab may not be the most important of pages, but it is still very useful when your game is finished and/or when testing on your own server rather than directly from GameMaker:Studio. What this tab shows is the ins and outs of all network connections from the page that your game is hosted on.
HTML5_NetWork_Tab.png
This means that you can see how long it takes your game to request sounds, graphics, music or external files, as well as their size, their file type, their status and a number of other facts and figures relating to the online performance of your game.

So why is this important? Well, it enables you to see what is being loaded, what files are missing, what takes a long time to load etc... and so you can concentrate your time on optimising and re-structuring things to improve the final experience of the person playing your game.

Sources

The last part of this debugging section deals with the Sources tab for Chrome. This is where you can get down to important and essential act of debugging the actual JavaScript that contains your game. The first thing to note here is that for debugging, you should always run your game in Debug Mode (press the orange "Play" button in GameMaker:Studio, rather than the green one) as it runs the game using un-obfuscated code. The differences between running normally and running in debug are clear:
HTML5_Debug_Obfuscated.png
As you can see, the code on the left displays the functions and variables as you wrote them (or near enough...) while the code on the right is nearly impossible to make any sense of! Also, the un-obfuscated code contains the original GML scripts as comments above each of the JavaScript codes to make debugging even easier. Note too that all GML variables are prefixed by the letters "gml" - So, "foo" becomes "gmlFoo" in the JavaScript.

Debugging JavaScript

Since your game is actually being run as JavaScript that has been compiled from the GML that GameMaker:Studio uses, the Sources tab is arguably the most important of all the tools that Chrome offers. So, to make things easier, this section will guide you through the basics of using the JS debugger on your game to detect (and resolve) problems.

Getting Started

To start debugging your code, you can either click on the JavaScript call from the HTML in the Elements section (which will open the Sources tab, as explained in the section above), or you can go directly to the Sources tab and then click on the icon at the top left and select the appropriate script from the pop-out menu:
HTML5_JS_Open.png
Once you have your code open, you may think that it looks rather complicated and a bit of a mess. Well, this is due to the way that JavaScript is compressed down to remove all the tabs and white space that makes it readable to you and me (a browser needs no such things!), so we want to switch on Pretty Print which will make the code far more accessible and human readable. This is done by using the button that can be found at the bottom of the debug window as shown here:
HTML5_PrettyPrint.png

Errors

So your game has an error... what to do? First you should try to identify the error (or errors) and this can be done by clicking on the little error icon and numbers that can be seen at the bottom right hand of the screen, which will open up the Console showing the error. It will also jump to the position of the error in the JavaScript itself, as shown in this image:
HTML5_Errors.png
In this way, you can identify problematic pieces of code and see exactly what type of error you have and so get an idea of how to fix it. It should be noted that you can open and close the console at any time using the console button at the bottom of the screen.

Break Points and Pausing

On the right of the Sources tab there are also a number of buttons and sub-tabs where you can test and perform additional functions when running your game. For debugging JavaScript, the most important of these are probably the buttons along the top:
HTML5_ChromeButtons.png

These buttons are (from left to right):

  • Pause/unpause the game
  • Step over (run the next function as a whole)
  • Step into (run each part of the next function)
  • Step out (Leave the current function and continue)
  • Deactivate all breakpoints

The first of these, Pausing, is fairly obvious in what it does - it pauses your game at any point when pressed (and un-pauses again when paused). You can also pause you game in another way by adding in break points.

As you can see in the above image, there is a subsection of the Sources tab labelled Breakpoints and here you can see and review any that have been set for your game. But what is a breakpoint? Well, it is a place in the code that has been predefined as a "break" in the execution and in Chrome they are easily set by simply clicking on the numbers to the left of the code you want to pause at. For example:
HTML5_ChromeBreakPoint.png
In the above image, the breakpoint has been set at line 415, so when the game reaches that part, it will be paused automatically so you can then review the situation. To help you here, you can check out the Call Stack and Scope Variables sub-tabs which will give you details on the functions that were "called" to get you to this point as well as the currently used variables (both local and global).

From this break point onwards you can choose to unpause the game and continue, or you can step through your code with the step over, step in, and step out buttons or you can even deactivate all current breakpoints to continue your game as normal.

Break points and pausing are an excellent way to find errors, investigate problems or just see what exactly is happening at any given time in your game, and are worth investigating so that you can get the most out of this powerful tool.

Have more questions? Submit a request

0 Comments

Article is closed for comments.