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 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).
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).
This will then open a debug console at the bottom of the screen, with a series of icons like this:
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.
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.
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.
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.
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.
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).
Above you can see an example image of the elements tab of the Chrome debugger. The important things to note here are as follows:
- 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.
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!
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.
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!
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.
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.
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.
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
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:
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.