Debugging


When programming your game, whether using code or Drag and Drop, it can be very easy to make mistakes - using the wrong variables, passing the wrong arguments, or using the wrong functions are just some of the most common errors we all make - and these mistakes are not always detected by the syntax checker that is included with the script/action editor. That means that these mistakes will only become apparent when you actually run or compile your game, and even then it can sometimes be difficult to know exactly what is going wrong. It can therefore be of vital importance to know how your game is performing on the chosen device, as well as see what instances are in the room, what global variables have been created and a whole host of other details.

Now, you can check a lot of these things yourself by adding in so-called "debug code" to your games to display on the screen the information you require, or you can have it that it shows messages when there is an error, but this is often a lot of work and if you aren't sure where the problem is in the first place then it can be a time consuming case of trial and error to track down your bug. For that, GameMaker Studio 2 has a special test mode called Debug Mode which will start the Debug Module, and there is also a comprehensive error reporting system which displays messages at run time to help you track down any problems with your game.

The sections below cover the different ways that you can debug your game:

When an error occurs during the compiling and execution of a project this is reported with a message in the Compile Errors Output Window, much like the one shown below: Compile Errors

Most compiler error messages follow the same outline, with a message stating the object that the error has occurred in, then the Event along with the line number, and then finally a short description of the error itself. This type of information being provided by the error reporting is very important as it detects and reports the syntax and language related bugs that are going to cause your finished game to crash, but it won't report more subtle bugs, nor does it give feedback on performance. For those types of things you should use Debug Mode (explained below).

Apart from these compile errors, you can also get syntax errors. These will be detected as you add your DnD™ actions or code and are shown in the Syntax Errors Output Window, similar to the image shown below: Syntax Errors

As with the compiler errors, the syntax errors window will direct you to the object, the event and the specific lines that are giving the issue, and will often be shown with a brief explanation of what the error is.


If you need to check things more carefully, you can run the game in Debug Mode by clicking the debug run button . When you do, the Debug Module will open along with your game. This module permits you to monitor how everything is working in your game, from the global performance, right down to the values of individual variables in individual instances. You can find out further information about the Debug Module and its possibilities and how to use it from the following page:

  1. The Debug Module

Note that when you use the Debug Module, you can also add Breakpoints to your code or DnD™. A breakpoint is a point in the game loop where you want the debug module to pause and let you step through the actual game code a line at a time. You can add breakpoints using the key "F9", and they will be shown in the Output Window where you can enable/disable them as required.


When running a game for debugging, you can also see how your game performs and get an overview of how everything is working together by using the Profile option in the Debug Module. This will give very detailed information on how a game is performing and how long it takes to perform specific function calls or events (see the section on The Debug Module for further details). However this requires that the debug module is running which may not be what you want, especially if you wish to test final executables on devices etc...

In these cases, and as a compliment to the profiler, you can display the debug bar in your game, which will display much memory, CPU power and GPU power your game is using.

Debug Bar

This Debug Bar shows in a helpful graphic of CPU/GPU usage in the actual game window itself, and this can be toggled on and off in your game using the function show_debug_overlay(). This bar is split into sections, with each section being 1/60th of a second. As you can see from the image below, the bar is made up of various colours, with each one signifying a different aspect of the games performance, where the larger the bar, the more time that aspect requires and the larger the performance hit from it:

  • Green - Input / Output processing (ie: keyboard, mouse, gamepad, networking etc...)

  • Red - The update speed of the step event

  • Yellow - The time required for the draw event

  • Orange - Debug update time, which is only normally visible when you use the debug module

  • White - GPU left over time, which is the time spent waiting for the GPU to finish the rendering of the frame before the next one can start

  • Cyan - The text rendering time

  • Grey - The time required to clear screen each draw step

  • Dark Red - The GPU flush, which is how long the GPU takes to clear images from memory

Apart from the coloured bars, there are also a few values at the top. These values represent the following:

  • FPS - This is the "Frames per Second" of your game, and basically shows how fast your game is running. This value is not clamped to the game speed of your game, and so shows you how much "overhead" you have to play with. The larger this value compared to your game speed, the smoother your game will run and the more overhead you have for adding further things. Note that this value may vary a lot during a session, but when you close your game, the compiler output window within GameMaker Studio 2 will show you the minimum and maximum as well as the average values for this (note that the minimum value can be negative! This is not a bug, but due to the startup times and the way that the game is processed when initialised).

  • Texture Swaps - This number shows how many times your game is swapping textures per game frame (the time it takes GameMaker Studio 2 to run all events is a game tick, and the number of game ticks per second is set by the room speed). Textures (sprites and backgrounds) are stored on texture pages, and if you have a lot of image assets in your game, then GameMaker Studio 2 has to swap between texture pages to draw them all, therefore if this value is high (over 20, for example) you really should look into ways to optimise this as it will affect the performance of your game, especially on mobile platforms.

  • Vertex Batches - This is how many times the game is sending off texture batches to the GPU per game frame, and (as with Texture Swaps) you want this to be as low as possible. Texture batches, are basically bundles of data that are sent all at once to the GPU for rendering. The batch is "broken" when you change a font, a colour, a blend mode, or any other draw status that affects how things are drawn on a global scale, so you should try to limit these things to as few objects as possible since a high number of batches will adversely affect your games performance.

NOTE: texture swaps and vertex batches will never be zero and will normally show values of 2 or 3, since even with an empty room an no objects GameMaker Studio 2 still has to draw and batch things.

With these tools you can see how well your game is performing and what areas need "tweaked" to increase this performance. You can find out more information on performance issues and ways to optimise your game on the YoYo Games Help Center - Optimising Your Games.

As an additional tool for debugging compiled games, there are certain command line parameters that can be used when you run the final game package on Window. For information on how this works please see here.