The Debugger

Bugs refer to software defects - things not working as you expected in your game or app. Debugging refers to the process of fixing these issues. The Construct 2 debugger is a tool to help you find and fix bugs in your game.

Note: the debugger is available in the Free edition of Construct 2, but the 'Watch' and 'Profile' tabs, the ability to edit values, and the ability to use breakpoints, are unavailable.

How to run the debugger

The debugger can be run from the ribbon Home tab, the quick-launch bar, by right-clicking a layout or project in the Project Bar, or by using the keyboard shortcut Ctrl+F5.

The debugger works much like an ordinary preview, except that an extra panel appears alongside the game in the browser showing lots of information and some useful controls.

When in debug mode, the address in the browser also ends with /debug, e.g. http://localhost:50000/debug. You can also switch between normal preview and the debugger by going between these URLs. You can even run the debugger on a mobile device using preview over Wifi and adding /debug to the end of the preview URL as well, e.g. http://192.168.1.3:50000/debug.

Customising the debugger panel

The debug panel in the browser can be resized by pulling the gripper that appears in the grey titlebar of the debugger (to the left of where it says Inspector). This allows you to pull it out to see more information, or collapse it down to just its tools and a summary of the performance information.

The debugger can also be popped out in to its own window. This is especially useful on multi-monitor setups. The game will show using the full browser window, and a separate browser window displays the debug panel. Click the pop-out button indicated below to do this. Clicking it again, or closing the popup window, will restore it to the main browser window again.

The main debugger commands

Alongside the pop-out button are some other useful tools. They are as follows:

Pause

Pause the game so it is no longer progressing. This is useful to spend a while inspecting some information at a particular moment. When paused it turns in to a Resume button; click it again to resume running.

Step

can only be used when paused. It advances the game by a single frame. Delta-time (dt) is set as if the game were running at 60 FPS. This can be useful to inspect a moment frame-by-frame and watch how an event like a collision is handled.

Save

and Load make a temporary savegame, allowing you to quickly save the state of the game and then restore back to that state at any time later on. This can be useful for repeatedly running the same part of a game over and over again. As with ordinary savegames, the state is stored persistently in the current browser. So the savegame will not be available in a different browser, but will be available in the same browser even after closing and reopening it, rebooting, etc.

Restart

will simply refresh the game, loading it from scratch again.

Performance summary

Some details about the performance of the game appear in a light grey. For more advice on performance, see Performance Tips. The displayed values are, reading from left to right:

The object count

(e.g. 500 objects): how many objects are currently created. Using too many objects can degrade performance. This value corresponds to the objectcount system expression.

The framerate

(e.g. 60 FPS): how many frames per second the game is running at. Most system's displays update at 60 Hz, so the game should run at 60 FPS for optimal rendering. This value corresponds to the fps system expression.

The estimated CPU time

(e.g. 20% CPU): an estimate of how much CPU time is being spent in the logic of the game. This is not always accurate, especially since it only takes in to account time spent on the main javascript thread, and should only be considered a ballpark figure. The profiler can break this down in to how much time is being spent in each area of the game, and is described in more detail later on in this guide. This value corresponds to the CPUUtilisation system expression.

The estimated image memory use

(e.g. 32.5mb images): an estimate of how much memory is being used by the currently loaded images in the game. This is only available in WebGL mode. Images typically use up the most memory in a game, but note this value excludes everything else, such as memory required to run the logic of the game, and memory required to play music and sound effects. See the blog post Remember not to waste your memory for more advice on image memory use. This value corresponds to the ImageMemoryUsage system expression.

The renderer

(e.g. webgl): whether the game is rendering in canvas2d or webgl mode. WebGL mode is faster and supports shader effects. This value corresponds to the renderer system expression. Some additional performance details appear in the Performance section of the System object's inspector view, which is displaying by default:

Collision checks/sec

(e.g. 1144 (~22 / tick)): how many times in the last second the engine had to test for a collision between two objects. Collision checks are invoked by the On collision or Is overlapping sprite conditions, and many behaviors perform additional collision checks automatically. In brackets, the average checks per tick is also shown. For example if there were 600 collision checks in the last second and the framerate is 60 FPS, the estimated checks per tick will be 10. This tells you on average there were about ten collision checks per frame, although the actual value will often vary frame-by-frame.

Poly checks/sec

(e.g. 60 (~1 / tick)): most collision checks are very fast, and the engine can tell trivially that two objects are not overlapping (by verifying that their bounding boxes do not overlap). However if two objects' bounding boxes are overlapping, the engine must do a more expensive check where the collision polygons of each object are tested against each other. This value tells how many checks of this kind were made in the last second, as well as with the average per tick as with the Collision checks/sec value. Usually the Poly checks/sec value is considerably smaller, but if it is high, it indicates a possible performance problem.

The 'Inspector' tab

The debugger has three tabs: the Inspector, the Watch, and the Profile tabs. The Inspector tab is used to view and edit values .

The Inspector view is divided in to two sections: on the left appears a list of all the object types in the project, including the System object, and on the right appears a list of tables of values relating to the selected object, similar to the Properties Bar.

The object list

Click the name of an object type in the object list to expand it. The number of instances of that object type appears in brackets after the object name. If the object type only has one instance, or is a global object like the System object or Audio object, it will immediately start inspecting the object. Otherwise it expands a dropdown with a list of all the object instances sorted by their index ID (IID). Clicking a particular instance will then inspect just that instance.

The values view

As with the Properties Bar, the values view shows a list of categorised tables displaying all the information about the currently inspected object. The displayed values depend on what is being inspected; for example the Sprite object displays information about its current animation frame, the Audio object displays information about currently playing sound and music, and the System object displays information about the engine, layout, and layers. Most often these values correspond to object properties from the Properties bar, as well as the object's expressions.

Instance variables and behavior values are also shown if the selected object has any.

It is often useful to view these values while running the game. However, they can also be edited. As with the Properties Bar, simply click on a value and type in a new value to change it. Edited values appear in bold. Not all values are editable - those with a light grey background are read-only. This can be an excellent way to experiment with how your project works.

The eye icon to the right of values can be used to add the value to the Watch tab. This is described in more detail later on.

The Tools section gives you the ability to destroy the inspected object. By default the inspected object is also outlined with a dotted red rectangle in the game. If this is distracting, uncheck the Highlight checkbox.

Objects in a container also provide a list of links to inspect the other instances in the container with the currently inspected object.

The 'Watch' tab

The inspector only allows you to view one object at a time, and often also includes a great deal of information, most of which you may not be interested in. Clicking the eye icon beside values in the Inspector adds that single value to the Watch tab. This allows you to combine different values from different objects in to a single space, as well as reduce the displayed values to just the ones you're interested in.

In the Watch tab, values can be edited as with the Inspect tab.

The Watch tab shows crosses instead of eyes to the right of the values. Click the cross to remove the value from the watch. Note if you are watching a value from an object and the object is destroyed, the watch value will automatically be removed.

Category headers also have their own eye or cross icons. Clicking them will add or remove the entire section to or from the watch.

The 'Profile' tab

The Profile tab provides a more detailed breakdown of the estimated CPU usage. The game must be running continuously for the profiler to be able to collect and display information. It then displays a breakdown of the estimated CPU time spent in each part of the game logic. It updates once a second and the values shown are for the previous second only.

It must be noted that the overall CPU usage is an estimate to begin with, and all other values are therefore estimates. The details shown in the profiler only relate to the main javascript thread, and the CPU could be busy with other tasks, such as processing audio or running pathfinding calculations. Additionally the time for the GPU to render the game is not taken in to account at all by the profiler. It is entirely possible the framerate is limited by the speed at which the GPU can render, but the profiler is not able to directly identify this. It can be inferred if the framerate is low but the CPU usage is not high.

Despite the above caveats, the profiler can be used to identify "hot spots" which would be good candidates to attempt to optimise first if there is a performance problem. For more performance advice, see Performance Tips. Note that optimisation is often not necessary and is a waste of time if the game is already running fast enough. For a deeper discussion of the subject, see the blog post Optimisation: don't waste your time.

Profiler breakdown

The profiler shows nested tables identifying how much CPU time has been spent in each part of the engine, down to individual event groups. The top-level items are:

Events

A breakdown of how much time was spent running event logic in the event sheets used by the layout. This is first broken down in to each event sheet (in case includes were used), and then further down in to groups and nested groups of events. This can help identify the most CPU-intensive events which you may want to optimise.

Physics simulation

How much time has been spent processing the Physics behavior. Physics simulation can be very CPU-intensive. If this value is high, consider using fewer physics objects.

Draw calls

How long it took the CPU to issue rendering calls, not including the time for the GPU to complete them. In some cases, rendering calls can be quite CPU intensive, especially when very large numbers of objects are on-screen. Some browsers also forward all draw calls to another thread to be processed in parallel, in which case the Draw calls measurement will likely be an underestimate.

Engine

The remaining time spent in the Construct 2 engine, which is the overall estimated CPU with the events, physics and draw calls times subtracted away. This includes processing behaviors and other engine housekeeping.

Breakpoints

When running the debugger, it's possible to set breakpoints to pause execution of an event sheet on a specific event, condition or action. For more information, see the manual entry on breakpoints.