Informations on Heroes of Might and Magic 2 AGG format

This is what I could learn about the format of the data, present in the file Heroes2.agg. Most of the information on this page was retrieve from internet.

main aggregate file

The following is the description of James Koppel:

Aggregate files consist of the binary contents of various files concatenated together uncompressed, with a small amount of metadata.

Format for AGG files:

First two bytes: Little endian 16-bit integer describing number of files contained (henceforth, "n")
Next 12n bytes: A 12-byte FileInfo structure for every file consisting of three little-endian 32-bit integers: a file ID (see below), an offset o, and a size s. Bytes in the range [o,o+s-1] will contain the binary contents of the corresponding file.

Note : in Heroes of Might and Magic 1, this section is diffrent. There are 14n bytes FileInfo structure for every file consisting of : a file ID (32 bits), a 16-bits number, and two times the same 32-bits integer representing the size of the file.
Next arbitrary number of bytes: A concatenation of the binary contents of all files in the AGG.
Final 15n bytes: For every file, a 13-character (including trailing null) DOS-compatible filename, followed by two padding characters. The ith file here gives the filename of the ith file in the array of FileInfo's included at the beginning.

A file's ID is a 32-bit hash of its filename computed by the following C function or equivalent:

int hash(char* filename) {
    unsigned int a = 0;
    int b = 0;
    for(int i = strlen(filename)-1; i>=0; i--){
        char c = toupper(filename[i]);
        a=(a<<5)+(a>>25);
        b+=c;
        a+=b+c;
    }
    return a;
}

James also release a program in java to extends and create AGG files.

files in the aggregate

The files includes in the aggregate file are the data of the games.

They are of type :

82M:
This is used for the game's sounds.
FNT:
Two 17 bytes files (bigfont.fnt and smalfont.fnt). The 13 last bytes of these files are null-terminated string with the name of a icn file.

They respectively refer to font.icn and smalfont.icn, that contain each 96 characters images.
XMI:
TODO
PAL:
There is only one file of this type in the archive : the file "kb.pal". This file is the palette. It contains the colors to use to interpret the images in ICN files. It is a 3*256 bytes file. All group of 3 bytes represent a RGB color. You may notice that this palette is very dark (each byte is letter or equal than 0x3F). You must multiplicate all the bytes by 4 to obtain the real game's colors.

Note for Heroes I : there are two pal files in HEROES.AGG archive but they are identical. Caution, in this version the palette must be translate to retrieve the good colors.

Some palette ranges are for color animation (cycling colors) for phoenix, fire elementaries, lava, water :
- 214-217 (red)
- 218-221 (yellow)
- 231-237 (ocean/river/lake colors)
- 238-241 (blue)
The color cycling is an in-game feature. Simply put, if you place color 214, it will be put in a cycle automatically: 214-215-216-217-214-... etc. If you start from color 215, it will go in the game like 215-216-217-214-215-... etc.

Note : in Heroes II, the ten first and the ten last palette's colors are black, as the color of index 36. So twenty colors are lost. Counting others nineteen for cycling, only 217 colors are available for the artwork.
TIL:
TIL files contains tiles for the maps. In these files, the first three groups of 2 bytes are :
- the number of tiles (n)
- tiles' width
- tiles' height
Then there are n times, width * height bytes, that are the colors' index in the palette of the tiles' pixels.

The data contains three TIL files :
- clof32.til : four dark tiles (nigth sky?)
- ground32.til : tiles for all terrain's type in the main map.
- ston.til : stone ground tiles.
BMP:
Three colors bitmap images. These files have a 6 bytes header compose of three times two bytes :
- a magic number whose is always : 0x21 0x00
- width of the bitmap in little endian format
- height of the bitmap in little endian format
Then there are width*height bytes of data (one by pixel) whose values are 0, 1, or 2.
ICN:
These files are like the .def files from HOMM3. Each ICN file contains one or more images (for animations), plus offsets for relative position of frames. They contain the most part of the graphical artwork of the game, and the widgets of the game's interface.
BIN:
TODO

Most of the informations bellow on the formats of these files were extract for the study of the code of fheroes2.

icn format for sprites

All the numbers are encoded in little-endians.

The icn file contains a number n of images, we will name sprites. This is the structure of the file :

2 bytes : the number of sprites
4 bytes : the total size of the file (excluding the 6 first bytes)
13n bytes : representing n sprites headers (see below)
total_size - (count_sprite*13) bytes : concatenation of the data of the sprites.

icn sprite header

s16 offsetX; // positionning offset of the sprite on X axis
s16 offsetY; // positionning offset of the sprite on Y axis
u16 width; // sprite's width
u16 height; // sprite's height
u8 type; // type of sprite : 0 = Normal, 32 = Monochromatic shape
u32 offsetData; // beginning of the data

icn sprite data

Each sprite's pixel has a color taken from a "palette". The palette is an array of 256 colors defined in the file "kb.pal". The format of this file is describe above. The pixel can also be a shadow pixel. The shadow color will be represented by a black pixel with an alpha channel of 64 (0 represents a fully transparent color, and 255 represents a fully opaque color).

The following sheme is repeated many times, describing how to fill pixels. By default a pixel will be transparent.

Scheme for normal sprite

There is one byte for command followed by 0 or more bytes of data. The command byte can be :

0x00 - end of line reached, go to the first pixel of next line. All of remaining pixels of current line are transparent.
0x01 to 0x7F - number n of data. The next n bytes are the colors of the next n pixels.
0x80 - end of data. The sprite is yet totaly describe.
0x81 to 0xBF - number of pixels to skip + 0x80. The (n - 128) pixels are transparents.
0xC0 - put here n pixels of shadow. If the next byte modulo 4 is not null, n equals the next byte modulo 4, otherwise n equals the second next byte.
0xC1 - next byte is the number of next pixels of same color. The second next byte is the color of these pixels.
0xC2 to 0xFF - number of pixels of same color plus 0xC0. Next byte is the color of these pixels.

Scheme for monochromatic shape

The pixels can only be in two states (transparent or black). So the rules are simplified.

Command bytes are :

0x00 - end of line reached, go to the first pixel of next line.
0x01 to 0x7F - number of black pixels
0x80 - end of data. The sprite is yet totaly describe.
0x81 to 0xFF - number of pixels to skip + 0x80. The (n - 128) pixels are transparents.