GGS Debug Library

I’m working on some game libraries, tools and utilties. The first thing I’m posting is some debugging libraries. Stuff I use while making a game, specifically a console game.

There’s 4 major parts to it

  1. a debug console.

    This is just the ability to do a printf to the display. Most development systems let you print to a terminal or inside the debugger. The problem with those systems is the artist, the desginer or myself is not looking at the debugger. We are looking at the game. Therefore, important messages need to be displayed in the game or they will go un-noticed.

    On top of that, games generally erase and re-draw the entire screen every frame so some method of re-drawing the messages needs to be created. Without a system like this that process can get quite cumbersome.

    The systmem supports output in different colors as well as flashing output to make very important messages stand out.

  2. print to the debug terminal

    Most dev systems have an OutputDebugString type of way to get a message to the terminal. These are just wrappers that provide more functionalty like printf and so I have one place to fix if I switch engines.

  3. print to the screen

    Again, most systems have a DrawText function that will draw a string. I just always need wrappers so I can do printf style formatting and again, I want it in one place so if I switch engines I don’t have to learn a new api or change other code to use a new api.

  4. debug menus

    This is the biggest part. These are menus, controllable from the joypad/controller that you can pull up in the game to inspect and or edit things in realtime.

For all of these my #1 goal was to make something easy to use. So for example there is no need to init any of them. While you can set a few parameters they will work without any settings. The menus and the console only require 1 function to be called for them to operate, etc…

The menus in particular have been designed to be easy to add items to with lots of default handlers. In one line you can add menus that edit bools, ints, floats, either directly or can edit them through functions or even member functions. Menus that call callbacks in C style, CPP function object style and member function style.

They handle enums, although you need to supply a value-label table. They can also handle STL collections and display them as menu items.

Some other features.

  • They handle menus that have too many items to fit on the screen and will let the user scroll through them.
  • They support non-uniform height menu items.
  • They handle the menus cascacding past the right edge of the screen
  • They are platform independent.

    There is a file debugplatform.h that defines a few functions. You create your own debugplatform.cpp and provide those few stubbs and the all these debug systems will start working.

  • They are semi draw order independent.

    Originally when a submenu cascaded into the right edge of the screen I would just move it flush right. I assumed since a menu’s parent was drawn before itself I thought the children would draw over their parents and therefore be usable. Unfortunately when I tried it out it became clear that in the engine I was using it in, draw order was not preserved. Text draws and rectangle draws were queued separately. So, I changed the menus to figure out what the right most edge they need is and then I push everything else to the left. Now the draw order doesn’t matter as much since nothing ever overlaps. Rectangles still need to be either drawn before text or with a lower Z order but that’s not the responsibility of these routines.

Anyway, I have no idea if anyone other than me will find these useful. I know that many teams are using systems that have other ways to accomplish this kind of thing. For me though I have found them useful and so have the teams I’ve been on. It’s my hope that now that I have my own I’ll never have to write them again.

If you are interested you can find them on sourceforge here. They are released under the NewBSD license so use them how ever you want. There are not a lot of docs yet but the code is pretty well commented. There’s also a file called debugmenus_examples.cpp that shows how to setup a bunch of different kinds of menus. And, there’s a Win32 sample as well to actually see them run. To keep it simple the sample uses the keyboard to emulate a joypad. The cursor keys are the DPAD. The space bar is the Action button if you want to call it that. Think X on the PS3 or A on the 360. Backspace is the cancel button.

  • nvictor
    Game library

    Greg,

    Are you creating a new game library or just working on existing?

    This is interesting

  • nvictor

    Forget my above question. Can you make a zip of the debugging librairies? I can’t install tortoiseSVN…

  • I’d suggest you install normal Subversion then. That’s the only way you’ll get the current version. There is a zip file on sourceforge but it’s guaranteed to be old.

  • nvictor

    I got it. Does it require the directx SDK? If yes, which packages are important?

  • The debug libraries do not require any particular sdk. They require you to implement your own debugplatform.cpp to provide the glue to a few routines in your own engine.

    The example program that uses the libraries does require DirectX.

  • Greg – certainly, text output on screen is absolutely useful for debugging. For real time data tweaking though I would really suggest looking into doing a simple network layer that a PC based tool can communicate with your game engine while it is running.

    It’s way easier to do a color picker using Windows Forms in C#, for example, than it would be to rewrite your own in runtime code. The same goes for the large majority of tools.

    After setting up such a system on my current PS3/XB360 project we’ve ended up linking nearly every tool in some way to the engine across the network for real time manipulation. Special FX editing, cutscene parameter editing, entity spawning / parameters, post process shader parameter tweaking, etc. Bonus points for the ability to screw with your coworkers by connecting to their running game on the LAN and goofing off with their game settings when they least expect it. 🙂

    It looked like Square had a similar system in use on FF12 based on the GDC postmortem they did.

  • We have over the net editing. It’s nice when you have that setup. Unfortunately it requires far more work than just booting up a dev kit so there’s still some use in having some debug UI in the game that runs without a PC with custom software needing to be around.