Allegro datafiles are similar to ZIP archive files in that they can contain multiple files of different types and sizes, with support for encryption and compression. However, Allegro datafiles differ from the files of general-purpose archival programs in that they are geared entirely to store game resources. Allegro datafiles use the LZSS compression algorithm when compression is used.

Datafiles are created by the Allegro Datafile archiving utility and have a .dat extension. They can contain bitmaps, sounds, FLI animations, Mappy levels, text files, and any other type of file or binary data that your game will need. You can distribute your game with a single executable and a single datafile.

One of the best things about datafiles is that, because they are so easy to create and use, you can use a datafile for any program you write, not just games. This really adds a strong degree of appeal to Allegro even for general-purpose programming, developing command-line utilities and support programs in addition to full-blown game editors and similar programs. Instead of distributing a background image, sprite image, and sound file in a small game, simply bundle it all together in a datafile and send it off to your friends with the program file. In other words, you don't have to reserve datafile use only for big projects; you can use datafiles frequently even on non-game projects.

Datafiles use a struct to keep track of their resources. The struct looks like this:

typedef struct DATAFILE
{
  void *dat;   //pointer to the actual data
  int type;    //type of the data
  long size;   //size of the data in bytes
  void *prop;  //list of object properties
} DATAFILE;

When you refer to an object in a datafile, you must use a DATAFILE struct to get at the resource. Usually you will not need to be concerned with anything other than the dat member variable, which is a void pointer to the object in the file (or in memory after the datafile has been loaded).

Would you like a quick example? Although I haven't covered the load_datafile function yet, here is an example of how you might load a datafile into memory and then grab a sprite directly out of the datafile:

DATAFILE *data = load_datafile("game.dat");
draw_sprite(screen, data[PLAYER_SPRITE].dat, x, y);

If you want to identify a resource by type (for instance, to verify that the resource is a valid type), you can use the type member variable of the DATAFILE struct. Table 18.1 provides a list of the various types of objects that can be stored in a datafile.

Before you can practice using datafiles, you need to learn how to create and manage them. This will also give you a heads-up on extracting the game resources from other people's games that use Allegro datafiles! Not that I would condone the theft of artwork. . .but it is interesting to see how some people develop their artwork.

Allegro comes with a command-line utility program called dat.exe that you will use to create and manage your datafiles. The Allegro utilities are located in the tools folder inside the root Allegro folder, wherever you installed it (based on the sources). If you have extracted Allegro to your root drive folder, then the dat.exe program is likely to be found in allegro ools. You will need to open a command prompt or shell and change to that folder to run the program. Alternatively, you might want to just add allegro ools to your system path. In Windows, you would do that by typing

path=C:allegro	ools;%path%

After you do this, you will be able to maintain your datafiles from any folder on the hard drive because dat.exe will be included in the path. Here is the output from dat.exe if you run it with no parameters:

Datafile archiving utility for Allegro 4.2.0, MinGW32
By Shawn Hargreaves, 2005

Usage: dat [options] filename.dat [names]

Options:
  '-a' adds the named files to the datafile
  '-bpp colordepth' grabs bitmaps in the specified format
  '-c0' no compression
  '-c1' compress objects individually
  '-c2' global compression on the entire datafile
  '-d' deletes the named objects from the datafile
  '-dither' dithers when reducing color depths
  '-e' extracts the named objects from the datafile
  '-g x y w h' grabs bitmap data from a specific grid location
  '-h outputfile.h' sets the output header file
  '-k' keeps the original file names when grabbing objects
  '-l' lists the contents of the datafile
  '-m dependencyfile' outputs makefile dependencies
  '-o output' sets the output file or directory when extracting data
  '-p prefixstring' sets the prefix for the output header file
  '-pal objectname' specifies which palette to use
  '-s0' no strip: save everything
  '-s1' strip grabber specific information from the file
  '-s2' strip all object properties and names from the file
  '-t type' sets the object type when adding files
  '-transparency' preserves transparency through color conversion
  '-u' updates the contents of the datafile
  '-v' selects verbose mode
  '-w' always updates the entire contents of the datafile
  '-007 password' sets the file encryption key
  'PROP=value' sets object properties

I'm not going over all these options; consider it your homework for the day. The really important thing to know about the dat.exe syntax is the usage.

Usage: dat [options] filename.dat [names]

When you run dat.exe, first you must include any options, then the name of the datafile, followed by the files you want to add to (or extract from) the datafile. Looking through the options, you see that –a is the parameter that adds files to a datafile. But you must also use the –t option to tell dat what kind of file you are adding. Go ahead and try it. Locate a bitmap file, change to that directory from the command prompt (or shell), and adapt the following command to suit the bitmap file you intend to add to the datafile.

dat -a -t BMP -bpp 16 test.dat back.bmp

Do you see the -bpp 16 parameter? You must specify the color depth of the bitmaps you are adding to the datafile or it will treat them as 8-bit images (one byte per pixel). I have used the -bpp16 parameter to instruct the dat program to store the file as a 16-bit bitmap. The output from dat should look something like this:

test.dat not found: creating new datafile
Inserting back.bmp -> BACK_BMP
Writing test.dat

Now you can find out whether the bitmap image is actually stored inside the test.dat file.

dat -l test.dat

You should see a result that looks something like this:

Reading test.dat
- BMP - BACK_BMP        - bitmap (640x480, 16 bit)

Great, it worked! Now there's just one problem. I see from the options list that I can add compression to the datafile using the -c2 option, so I'd like to reduce the size of the file. Here is the command to do that:

dat -c2 test.dat

The output looks like this:

Reading test.dat
Writing test.dat

I see that the file has been reduced from 900 KB to about 100 KB. Perfect!

Now let's add another file to the datafile, and then I'll explain how to get to these objects from an Allegro program. Let's add another bitmap file called ship.bmp to the datafile:

dat -a -t BMP -bpp 16 test.dat ship.bmp

Here is the output:

Reading test.dat
Inserting ship.bmp -> SHIP_BMP
Writing test.dat

Now that you have added two files to the datafile, take a peek inside:

dat -l test.dat

produces this output:

Reading test.dat
- BMP - BACK_BMP                    - bitmap (640x480, 16 bit)
- BMP - SHIP_BMP                    - bitmap (111x96, 16 bit)

If you take a look at the file size, you'll see that it is still compressed. Trying to compress it again results in the same file size, so it's apparent that once -c2 has been applied to a datafile, compression is then applied to any new files added to it.

I should also point out that you should reference the objects in the file in the order they are displayed using dat -l test.dat. You can reference the back.bmp file using array index 0, explode.wav using array index 1, and so on.

The dat tool is able to generate a header file containing the datafile definition of values using the -h option. This will save you the trouble of adding constants or definitions in your program to reference the objects in the datafile, because the dat.exe program can do this for you. Here is an example:

dat test.dat -h defines.h

That produces a file that looks like this:

/* Allegro datafile object indexes, produced by dat v4.2.0, MinGW32 */
/* Datafile: test.dat */
/* Date: Sat Sep 16 20:49:59 2006 */
/* Do not hand edit! */

#define BACK_BMP                  0          /* BMP */
#define SHIP_BMP                  1          /* BMP */

It is best to include this header file directly in your project and not edit it manually. When you include the datafile definition header in your project, and then you re-run the dat program to rebuild the header, it will automatically be updated in your game project. For this reason, it's best to include the file rather than paste the definitions in your code—unless your program is small.

You have learned some details about what datafiles are made of and how to create and update them. Now it's time to put them to the test in a real Allegro program that will load the datafile and retrieve game objects directly out of the datafile. First you need to go over the datafile functions to learn how to manipulate a datafile with source code.

DATAFILE *load_datafile(const char *filename);

draw_sprite(screen, (BITMAP *)data[SPRITE].dat, x, y);

void unload_datafile(DATAFILE *dat);

DATAFILE *load_datafile_object(const char *filename, const char *objectname);

sprite = load_datafile_object("datafile.dat", "SPRITE_BMP");

void unload_datafile_object(DATAFILE *dat);

DATAFILE *find_datafile_object(const DATAFILE *dat, const char *objectname);

Now that you have a basic understanding of how datafiles are created and what the data inside a datafile looks like, it's time to learn how to read a datafile in an Allegro program. I have written a short program that loads the test.dat file you created earlier in this chapter and displays the back.bmp and ship.bmp files stored in the datafile. You should be able to use this basic example (along with the list of datafile object types) to use any other type of file in your programs (such as samples or Mappy files). Figure 18.1 shows the output of the TestDat program.

Figure 18.1. The TestDat program demonstrates how to read bitmaps from an Allegro datafile.

#include <allegro.h>

#define MODE GFX_AUTODETECT_WINDOWED
#define WIDTH 640
#define HEIGHT 480
#define WHITE makecol(255,255,255)

//define objects in datafile
#define BACK_BMP 0
#define SHIP_BMP 1

int main(void)
{
  DATAFILE *data;
  BITMAP *sprite;

  //initialize the program
  allegro_init();
  install_keyboard();
  install_timer();
  set_color_depth(16);
  set_gfx_mode(MODE, WIDTH, HEIGHT, 0, 0);

  //load the datafile
  data = load_datafile("test.dat");

  //blit the background image using datafile directly
  blit(data[BACK_BMP].dat, screen, 0, 0, 0, 0, WIDTH-1, HEIGHT-1);

  //grab sprite and store in separate BITMAP
  sprite = (BITMAP *)data[SHIP_BMP].dat;
  draw_sprite(screen, sprite, WIDTH/2-sprite->w/2,
      HEIGHT/2-sprite->h/2);

  //display title
  textout_ex(screen,font,"TestDat Program (ESC to quit)",0,0,WHITE,-1);

  //pause
  while(!keypressed());

  //remove datafile from memory
  unload_datafile(data);

  allegro_exit();
  return 0;
}
END_OF_MAIN()

This chapter will see the final enhancement to Tank War! It's been a long journey for this game, from a meager vector-based demo on through the various stages to bitmaps, sprites, scrolling backgrounds, and animation. The final revision to the game (the ninth) will add sound effects to the game and incorporate the resources into a datafile, as explained in this chapter. In addition, since this is the last update that will be made to Tank War, I have decided to throw in a few extras for good measure.

At the time when we covered joysticks back in Chapter 5, it was premature to add joystick support to Tank War. Much time has passed, and you have learned a great deal in the intervening chapters, so now you'll finally have the opportunity to add joystick support to the game. Along the way, I'll show you how to limit the input routines a little to make the tanks move more realistically.

By the time you have finished this section, Tank War will have sound effects, joystick support, and improved gameplay. All that remains is for you to create some new map files using Mappy to really see how far you can take the game! I would also suggest that you play with the techniques learned in Chapter 16 for testing collisions with Mappy tiles in order to add solid blocks to Tank War. As that is beyond the goals of this chapter, I leave the challenge to you. Now let's get started on the changes to the game.

/* Allegro datafile object indexes, produced by dat v4.2.0, MinGW32 */
/* Datafile: sounds.dat */
/* Date: Wed Aug 30 02:11:54 2006 */
/* Do not hand edit! */

#define AMMO_WAV                         0        /* SAMP */
#define FIRE_WAV                         1        /* SAMP */
#define GOOPY_WAV                        2       /* SAMP */
#define HARP_WAV                         3        /* SAMP */
#define HIT1_WAV                         4        /* SAMP */
#define HIT2_WAV                         5        /* SAMP */
#define OHHH_WAV                         6        /* SAMP */
#define SCREAM_WAV                       7        /* SAMP */

dat sounds.dat -h datafile.h

#ifndef _TANKWAR_H
#define _TANKWAR_H

#include <stdlib.h>
#include "allegro.h"
#include "mappyal.h"
#include "datafile.h"

//define the datafile object
DATAFILE *datafile;

.
.
.
//sprite bitmaps
BITMAP *tank_bmp[2][8][8];
BITMAP *bullet_bmp;
BITMAP *explode_bmp;

//double buffer
BITMAP *buffer;

//screen background
BITMAP *back;

//variables used for sound effects
#define PAN 128
#define PITCH 1000
#define VOLUME 128
#define NUM_SOUNDS 8
#define AMMO 0
#define HIT1 1
#define HIT2 2
#define FIRE 3
#define GOOPY 4
#define HARP 5
#define SCREAM 6
#define OHHH 7
SAMPLE *sounds[NUM_SOUNDS];

//some variables used to slow down keyboard input
int key_count[2];
int key_delay[2];

//function prototypes
void loadsounds();
void readjoysticks();
void loaddatafile();
void animatetank(int num);
void updateexplosion(int num);

void loaddatafile()
{
  datafile = load_datafile("sounds.dat");
  if (datafile == NULL) {
      allegro_message("Error loading datafile");
      return;
  }
}

void loadsounds()
{
     //install a digital sound driver
     if (install_sound(DIGI_AUTODETECT, MIDI_NONE, "") != 0) {
         allegro_message("Error initializing sound system");
         return;
  }

  //load the ammo sound
  sounds[AMMO] = (SAMPLE *)datafile[AMMO_WAV].dat;
  if (!sounds[AMMO]) {
      allegro_message("Error loading ammo.wav");
      return;
  }
  //load the hit1 sound
  sounds[HIT1] = (SAMPLE *)datafile[HIT1_WAV].dat;
  if (!sounds[HIT1]) {
      allegro_message("Error reading hit1.wav");
      return;
  }
  //load the hit2 sound
  sounds[HIT2] = (SAMPLE *)datafile[HIT2_WAV].dat;
  if (!sounds[HIT2]) {
      allegro_message("Error reading hit2.wav");
      return;
  }
  //load the fire sound
  sounds[FIRE] = (SAMPLE *)datafile[FIRE_WAV].dat;
  if (!sounds[FIRE]) {
      allegro_message("Error reading fire.wav");
      return;
  }
  //load the goopy sound
  sounds[GOOPY] = (SAMPLE *)datafile[GOOPY_WAV].dat;
  if (!sounds[GOOPY]) {
      allegro_message("Error reading goopy.wav");
      return;
  }
  //load the harp sound
  sounds[HARP] = (SAMPLE *)datafile[HARP_WAV].dat;
  if (!sounds[HARP]) {
      allegro_message("Error reading harp.wav");
      return;
  }
  //load the scream sound
  sounds[SCREAM] = (SAMPLE *)datafile[SCREAM_WAV].dat;
  if (!sounds[SCREAM]) {
      allegro_message("Error reading scream.wav");
      return;
  }
  //load the ohhh sound
  sounds[OHHH] = (SAMPLE *)datafile[OHHH_WAV].dat;
  if (!sounds[OHHH]) {
      allegro_message("Error reading ohhh.wav");
      return;
  }
  //cannons are reloading
  play_sample(sounds[0], VOLUME, PAN, PITCH, FALSE);
}

void loadsprites()
{
     //load explosion image
     if (explode_bmp == NULL)
     {
         explode_bmp = load_bitmap("explode.bmp", NULL);
     }

     //initialize explosion sprites
     explosions[0] = (SPRITE*)malloc(sizeof(SPRITE));
     explosions[1] = (SPRITE*)malloc(sizeof(SPRITE));
}

  }
  else
  {
     //play "end of explosion" sound
     play_sample(sounds[HARP], VOLUME, PAN, PITCH, FALSE);

     explosions[num]->alive = 0;
     explosions[num]->curframe = 0;
  }
}

void explode(int num, int x, int y)
{
    //initialize the explosion sprite
    explosions[num]->alive = 1;
    explosions[num]->x = x;
    explosions[num]->y = y;
    explosions[num]->curframe = 0;
    explosions[num]->maxframe = 20;

    //play explosion sounds
    play_sample(sounds[GOOPY], VOLUME, PAN, PITCH, FALSE);
    play_sample(sounds[HIT1], VOLUME, PAN, PITCH, FALSE);
    play_sample(sounds[HIT2], VOLUME, PAN, PITCH, FALSE);
}

void movebullet(int num)
{
   int x, y, tx, ty;
   x = bullets[num]->x;
   y = bullets[num]->y;

   //is the bullet active?
   if (!bullets[num]->alive) return;

   //move bullet
   bullets[num]->x += bullets[num]->xspeed;
   bullets[num]->y += bullets[num]->yspeed;
   x = bullets[num]->x;
   y = bullets[num]->y;

   //stay within the virtual screen
  if (x < 0 || x > MAPW-6 || y < 0 || y > MAPH-6)
  {
     //play the ammo sound
     play_sample(sounds[AMMO], VOLUME, PAN, PITCH, FALSE);

     bullets[num]->alive = 0;
     return;
  }

  //look for a direct hit using basic collision
  tx = scrollx[!num] + SCROLLW/2;
  ty = scrolly[!num] + SCROLLH/2;
  if (inside(x,y,tx-15,ty-15,tx + 15,ty + 15))
  {
     //kill the bullet
     bullets[num]->alive = 0;

     //blow up the tank
     x = scrollx[!num] + SCROLLW/2;
     y = scrolly[!num] + SCROLLH/2;

     //draw explosion in enemy window
     explode(num, tanks[!num]->x, tanks[!num]->y);
     scores[num]++;

     //kill any "near miss" sounds
     if (num)
         stop_sample(sounds[SCREAM]);
     else
         stop_sample(sounds[OHHH]);
  }

  else if (inside(x,y,tx-30,ty-30,tx + 30,ty + 30))
  {
    //it's a near miss!
    if (num)
        //player 1 screams
        play_sample(sounds[SCREAM], VOLUME, PAN, PITCH, FALSE);
    else
        //player 2 ohhhs
        play_sample(sounds[OHHH], VOLUME, PAN, PITCH, FALSE);
  }
}

void fireweapon(int num)
{
  int x = scrollx[num] + SCROLLW/2;
  int y = scrolly[num] + SCROLLH/2;

  //ready to fire again?
  if (!bullets[num]->alive)
  {
     //play fire sound
     play_sample(sounds[FIRE], VOLUME, PAN, PITCH, FALSE);

     bullets[num]->alive = 1;

void readjoysticks()
{
     int b, n;

     if (num_joysticks)
     {
         //read the joystick
         poll_joystick();

         for (n=0; n<2; n++)
         {
              //left stick
              if (joy[n].stick[0].axis[0].d1)
                  turnleft(n);

              //right stick
      if (joy[n].stick[0].axis[0].d2)
          turnright(n);

      //forward stick
      if (joy[n].stick[0].axis[1].d1)
          forward(n);

      //backward stick
      if (joy[n].stick[0].axis[1].d2)
          backward(n);

      //any button will do
      for (b=0; b<joy[n].num_buttons; b++)
           if (joy[n].button[b].b) {
               fireweapon(n);
               break;
         }
    }
  }
}

void forward(int num)
{
  if (key_count[num]++ > key_delay[num]) {
      key_count[num] = 0;

      tanks[num]->xspeed++;
      if (tanks[num]->xspeed > MAXSPEED)
          tanks[num]->xspeed = MAXSPEED;
  }
}

void backward(int num)
{
  if (key_count[num]++ > key_delay[num]) {
   key_count[num] = 0;

   tanks[num]->xspeed--;
   if (tanks[num]->xspeed < -MAXSPEED)
       tanks[num]->xspeed = -MAXSPEED;
  }
}

void turnleft(int num)
{
  if (key_count[num]++ > key_delay[num]) {
      key_count[num] = 0;

      tanks[num]->dir--;
      if (tanks[num]->dir < 0)
          tanks[num]->dir = 7;
  }
}

void turnright(int num)
{
  if (key_count[num]++ > key_delay[num]) {
      key_count[num] = 0;

      tanks[num]->dir++;
      if (tanks[num]->dir > 7)
          tanks[num]->dir = 0;
  }
}

void getinput()
{
  //hit ESC to quit
  if (key[KEY_ESC])   gameover = 1;

  //WASD - SPACE keys control tank 1
  if (key[KEY_W])     forward(0);
  if (key[KEY_D])     turnright(0);
  if (key[KEY_A])    turnleft(0);
  if (key[KEY_S])    backward(0);
  if (key[KEY_SPACE]) fireweapon(0);

  //arrow - ENTER keys control tank 2
  if (key[KEY_UP])       forward(1);
  if (key[KEY_RIGHT]) turnright(1);
  if (key[KEY_DOWN])   backward(1);
  if (key[KEY_LEFT])   turnleft(1);
  if (key[KEY_ENTER]) fireweapon(1);

  //short delay after keypress
  //rest(20);
}

//main function
void main(void)
{
  int anim;

  //initialize the game
  allegro_init();
  install_keyboard();
  install_timer();
  srand(time(NULL));
  loaddatafile();
  setupscreen();
  setuptanks();
  loadsprites();
  loadsounds();

//load the Mappy file
if (MapLoad("map3.fmp")) {
    allegro_message ("Can't
    return;
}
//install the joystick handler
install_joystick(JOY_TYPE_AUTODETECT);
poll_joystick();
//setup input delays
key_count[0] = 0;
key_delay[0] = 2;
key_count[1] = 0;
key_delay[1] = 2;

  //check for keypresses
  if (keypressed())
      getinput();
  readjoysticks();

  //slow the game down
  rest(30);
}

  //free the MappyAL memory
  MapFreeMem();

  //remove the sound driver
  remove_sound();

  //remove the joystick driver
  remove_joystick();

  return 0;
}
END_OF_MAIN()

Final Comments about Tank War

Figure 18.2 shows the latest version of Tank War. It's been a long haul, and you've seen the game grow from a meager vector game to the current incarnation with animated sprites and scrolling backgrounds. Let's list the features of the latest version of the game:

Figure 18.2. The newest version of Tank War.

• Two-player split-screen gameplay

• Scrolling battlefield

• Support for new maps created with Mappy

• Advanced update code shows all the action in both windows

• Keyboard and joystick support

• 64 animated frames for each tank

• Numerous sound effects enhance gameplay

• Supports maps with up to 30,000 tiles

• Battlefield can be up to 5,500 × 5,500 pixels in size

• Runs on Windows, Linux, Mac OS X, and many other systems

This chapter provided an introduction to Allegro datafiles and showed you how to create them, modify them, and read them into an Allegro program or game. Datafiles make it much easier to distribute your games to others because you need only include the datafile and executable program file. Datafiles can contain any type of file, but some items are predefined so they are recognized and handled properly by Allegro. Although we are technically done with Tank War now, be sure to check out the final version of the game, revealed in the Epilogue at the end of Chapter 22.

You can find the answers to this chapter quiz in Appendix A, “Chapter Quiz Answers.”