Video Game in C: using X macros to define game data

As my brother and I recently released our last video game voxel invaders on android and symbian, I though I would share some of the technical details about it. For my the first post I will talk about a quite useful, although rarely used, C trick known as "X macros", and how we can use it to simplify game code.

The code is written in plain C, and the original design was very simple: all the elements of the game are stored in a structure (called obj_t in the code) that looks like that:

struct obj_t { 
    int type;
    float pos[3];
    float speed[3];
    sprite_t *sprite;
    // A lot of other attributes follow...
};

The important attribute of the structure is the first one: int type. This value allows us to differentiate all the kinds of objects in the game (in C++ I would have probably used subclassing instead). We can see it as a pointer to the object class, except that it is not a real pointer but an index on an array of a structure obj_info_t that contains all the information about a type of object (the game equivalent of a C++ class).

file objects.h:

struct obj_info_t {
   const char *sprite_file;
   float initial_speed[3];
   void (*on_hit)();
   // Lot of other attributes...
};

enum {
   PLAYER,
   ENEMY_A,
   ENEMY_B,
   // And so on...
   OBJ_COUNT
};

file objects.c:

obj_info_t obj_infos[] = {
    // PLAYER
    {
        "data/img1.png",  // sprite_file
        {0, 1, 0},        // initial speed
        NULL             // on hit
    },
    // ENEMY_A
    {
        "data/img2.png",  // sprite_file
        {1, 2, 2},        // initial speed
        enemy_a_on_hit    // on hit
    },
    // And so on..
};

By the way, this kind of design was mostly inspired by the code of the original doom game by John Carmack.

The first improvement we can do is to realize that since we are using C98, we can make the array declaration look better using designated initializers:

file objects.c:

obj_info_t obj_infos[] = {
    [PLAYER] = {
        .sprite_file = "data/img1.png",
        .initial_speed = {0, 1, 0},
    },
    [ENEMY_A] = {
        .sprite_file = "data/img2.png",
        .initial_speed = {1, 2, 2},
        .on_hit = enemy_a_on_hit,
    },
    // And so on.
};

See how the code already looks nice and simple. Although this is how our code looked like for a while, at some point we started to get annoyed by a problem with this pattern. The problem is that every time we define a new enemy, we need to modify too files: the file containing the object types enum, and the file containing the object infos array. Beside, since there is no way to separate the array or the enum into several files, those two files got bigger and bigger. This might not seem too bad, but really it is, specially when you have to find the definition of a given object in the thousand of lines of code containing the obj_infos array.

As I mentioned, the original doom engine also used this kind of pattern, and I think the way they overcame this problem was to use a special tool that would automatically generate the C code for both the enum and the array.

In our case I though writing a C generator tool would be overkill. That is where I realized that there is a simple way to have the C preprocessor generates those two parts (enum and global array) for us. Later when I searched for occurrences of this pattern online I found out this is known as "X macros", there is a very comprehensive article about it from Randy Meyers.

The idea behind C macros is to use a C preprocessor macro that, depending on the context, will expand to either the enum part, either the array initializer part.

In our simple case, it would be something like this:

file object_defs.h:

OBJ(PLAYER,
    .sprite_file = "data/img1.png",
    .initial_speed = {0, 1, -},
)

OBJ(ENEMY_A,
    .sprite_file = "data/img2/png",
    .initial_speed = {1, 2, 2},
    .on_hit = enemy_a_on_hit,
)

file object.h:

#define OBJ(name, ...) name,

enum {
    #include "object_defs.h"
}

file objects.c:

#define OBJ(name, ...) [name] = {__VA_ARGS__},

obj_info_t obj_infos[] = {
    #include "object_defs.h"
}

And so, thanks to this trick, we just need to modify the objects_def.h file to add or remove an object type. Both our enum and our global array will be automatically updated by the preprocessor at compile time. As a bonus, this makes it easy to split the object definitions into several files. For that we just need to #include all the needed files instead of just object_defs.h.