Debugging

From ENIGMA
Jump to navigation Jump to search

During the course of developing your game you may encounter unexpected issues or discover that some code doesn't behave the way you expected it to. Debugging commonly refers to the process of finding the root cause of such issues and correcting them. ENIGMA does a lot to make this entire process much easier.

Debug Mode

The biggest difference between debug mode and run mode is that debug mode will compile your game with debug symbols. It will also compile the engine itself using debug symbols. Basically, when you compile a program, in any language, certain things like variable names, which are what we mean when we say symbols, will be removed in a release build. The reason compilers remove these symbols is because it allows the program to perform more optimally and have a smaller executable size. The problem is these symbols, such as variable names, can be extremely useful for finding out why a program crashes or where it actually crashed at in the source code.

Debugging in ENIGMA currently works a little differently than it does in GameMaker because we have not yet created an integrated debugger. We can build a game in debug mode by simply hitting the debug button next to the run button. When the compiler finishes building the game it will open it, at which point you can simply close it. With the game now built with debug symbols included, we can use a debugger to analyze it. The compiler ENIGMA primarily uses is GCC, which we distribute as MinGW in the Windows ZIP. It comes with its own debugger called GDB.

If you used a newer setup method than the Windows ZIP and for some reason do not have GDB installed yet, you can install it through pacman or apt-get. Usually it comes with the gcc and base-devel packages though.

# pacman 64 bit
pacman -Sy mingw64/mingw-w64-x86_64-gdb
# pacman 32 bit
pacman -Sy mingw32/mingw-w64-i686-gdb

# apt-get
sudo apt-get install gdb

If we look back at the compiler output we can see where the game was actually built to, which should look similar to the following:

Built to C:/Users/Owner/AppData/Local/Temp/egm8728035953002966422.exe

The next thing we need to do is open a terminal, which is usually command prompt on Windows. The portable ZIP also ships git-bash.bat which can be used for this exercise. When we have the terminal open with gdb in our path we can enter the following command (replacing my example file path here with the one from your own compile window):

gdb C:/Users/Owner/AppData/Local/Temp/egm8728035953002966422.exe

At this point all you really need to do is enter run and GDB should start your game. Now you can proceed to the part of the game that crashes or exhibits other problematic behavior. When the game crashes we can enter bt in the gdb terminal and it will give us an entire stack trace.

Program received signal SIGSEGV, Segmentation fault.
0x00000000 in ?? ()
(gdb) bt
#0  0x00000000 in ?? ()
#1  0x007c9e95 in enigma_user::surface_create (width=800, height=600,
    depthbuffer=false) at Graphics_Systems/OpenGL1/GLsurface.cpp:127

This example stack trace was produced by a game that had failed to create a surface with OpenGL. What's great about this though is that, thanks to the debugging symbols, GDB was able to tell us the crash was in the C++ source file GLsurfaces.cpp in ENIGMA's engine on line 127.

Tip: On Windows, you can copy a terminal to your clipboard by right clicking on the window title bar and selecting Edit -> Select All then Edit -> Copy

Profiling

It can also be useful to profile and monitor a game's usage of system resources such as the CPU or RAM. Games with lots of heavy computations and logic benefit the most from being compiled. Using common profiling tools can be useful to find bottlenecks in the game's performance. Depending on which graphics system you are using, whether it's OpenGL or Direct3D, you should be able to use most of the tools created for those APIs on your game's executable.

See Also