Construct's debugger is an essential tool for testing your game and diagnosing anything that's not working like you expected. It has advanced tools for viewing the state of the game, pausing and stepping one frame at a time, profiling performance, and much more. The debugger was first introduced around 5 years ago in Construct 2, and carried over to Construct 3 largely unaltered. However we're pleased to announce that as of r115 Construct 3 has a brand-new debugger that's been completely rewritten from the ground up! It has a wide range of improvements including major new features. You can try it out today in the r115 beta release or newer.
Use the C3 runtime
The debugger is deeply integrated with the runtime. The new debugger has been built for the new C3 runtime only, so you'll need to switch your project to the C3 runtime before you can try the new debugger. In case you've missed the past news about the development of an all-new runtime for Construct, see our past C3 runtime blogs. As of the latest release the runtime option is now enabled by default, so you don't need to enable experimental features in settings any more.
Launching the debugger
In case you haven't used it before, you can preview with the debugger using the drop-down menu next to the preview button.
Overview
First off, here's what the new debugger looks like.
The overall layout is similar to the old one, but with a refreshed design to better match the editor, improve usability, and improve the display quality on high-DPI displays. There's also a new toolbar icon to take screenshots of the game.
Introducing the GPU profiler
Construct 3 added support for GPU usage measurements, which provides an overall measurement of how busy the GPU is (which is the hardware responsible for actually rendering the pixels in the game). This is separate to the CPU usage (which runs the game logic). While it's useful to have an indication of how busy the GPU is, there has previously been no way to find out where to look if you want to make improvements. Now, for the first time ever in Construct, you can view a per-layer real-time profile of where GPU time is being spent in the game.
The 'Rain demo' is a good example, being a GPU-heavy tech demo. If you look at the GPU profiler table at the bottom, it clearly indicates that a layer using a bumpmapping effect is taking up the most GPU time, followed by a layer for rain splashes. Therefore, out of the 15 layers the layout uses, these two would be the best places to start making changes to optimise the game's rendering performance. It's an invaluable tool that helps guide you when optimising your game on the GPU, especially since there have previously been very few ways to investigate GPU performance other than looking at the framerate.
Note that GPU profiling has only been recently re-enabled in browsers - it was disabled after the Spectre security vulnerabilites came to light while they worked on mitigations. If you see a "not supported" message, try Chrome Beta or Chrome Canary. It should be enabled by default in the stable version of Chrome in the next couple of releases.
Revised CPU profiler
The old debugger showed profiling information in a large and quite confusing series of nested tables. This has been revised to a straightforward table in the new debugger.
This is easier to read and the bar highlights provide an at-a-glance overview of the relative time consumed by each activity. The table lists both self time and total time, self time being the time excluding any sub-items. For example an event group's self time covers time spent in its own events, but not any sub-groups within it. However the total time will include all the sub-groups within it. By default the table sorts by self time, since it is usually the most useful way to identify which part of the game needs optimising. However you can also sort by total time instead for a more top-down approach.
The CPU profile is also now more detailed. It includes new entries for plugin and behavior processing, which previously would have been included as part of "Engine". For example if you have 1000 objects moving with the Bullet behavior, every tick the engine must update the movement for all 1000 bullet behaviors, which could be quite a lot of CPU time. Separating this out in to its own measurement makes it clearer why your CPU usage might end up high. The new profile also measures time spent in triggers, separately from normal events.
Breakpoints in loops and triggers
The old debugger did not support placing breakpoints in triggered or looping events. This was due to the limitations of JavaScript when the debugger was originally written in 2013: there was no way to pause execution, so breakpoints were implemented using a bit of a hack that only runs sections of the event sheet. However this hack was not good enough to cover triggers and loops, so they simply couldn't be supported.
Fast-forward to 2018 and thanks to the latest JavaScript features, the engine is now able to genuinely suspend execution in the event system. This has been used as the basis for a much improved breakpoint system which now also supports loops and most triggers. This is pretty complex to implement especially since triggers can fire almost anywhere in the engine, and support for pausing has to be specially written in, with careful treatment to ensure the performance of non-debug mode is not impacted. Due to the complexity of this some triggers still don't support breakpoints, but many of the most common ones do, such as input events, On start of layout, functions, and so on. Also the technical capability is there, so we can probably support all triggers in future as well.
Once you can stop on breakpoints in loops and triggers, it's extra useful to be able to see local variables and the current loop index. So when you hit a breakpoint, the new debugger shows you those as well. Below is an image with a small project designed to find prime numbers using some looping events, demonstrating hitting a breakpoint in a loop. The debugger now also shows the loop indices and local variables. In the image the debugger helps identify it's marking the number 574005 as not prime because it has a factor of 3.
The Step button also lets you step through events, conditions and actions one at a time. It now also lets you step all the way through a loop, one iteration at a time. Since you can now also break in functions, breakpoints are a far more useful debugging tool, allowing even highly algorithmic events to be paused and stepped through.
Improved performance & more
The debugger shows a lot of information and updating the display can be quite performance intensive, and correspondly impact the performance of the game. We've taken steps to ensure the new debugger has as little performance impact on the game as possible. However the really big difference comes when you run the C3 runtime in a worker. This lifts the entire runtime off the thread used by the debugger, so both can run in parallel at the same time - essentially completely removing the performance overhead of the debugger from the runtime. This should make it much more feasible to use the debugger with performance-intensive parts of the game, as well as make more accurate measurements in the profilers.
Other smaller improvements include ensuring the entire debugger is now fully translatable, so if you don't use Construct in English, you shouldn't see any terms still in English in the debugger. Additionally we've made a range of smaller bug fixes and usability improvements to ensure it's easy and smooth to use. Having said that this is the first public release of a major new feature, so it may be a little buggy while it's in beta! Give it a spin and as ever, let us know if you run in to any issues.
Conclusion
The debugger is an essential development tool, especially for advanced users. It also provides profilers that are key to identifying performance issues in your games. The new debugger built for the C3 runtime is much more powerful. The performance tools are significantly improved, allowing per-layer profiling of GPU performance, and providing a much better CPU profiler. The event debugging tools are also much more powerful now, with the ability to set breakpoints and step through loops and triggers, while viewing the loop index and local variables.
You can try out the new debugger today in r115 or newer! Just don't forget to switch to the C3 runtime first. The new debugger is the last major piece of the puzzle for the next big upgrade for Construct 3: providing an all-new, modernised, faster and more powerful runtime. We hope to fully launch the new runtime in the near future, which will be a great milestone in the development of Construct 3!