BAM file format

Applies to:
BG1, BG1: TotS, BG2, BG2: ToB, PST, IWD, IWD:HoW, IWD:TotL, IWD2, BGEE

File versions

General Description
This file format describes animated graphics. Such files are used for animations (both creature animations, item and spell animations) and interactive GUI elements (e.g. buttons) and for logical collections of images (e.g. fonts). BAM files can contain multiple sequences of animations, up to a limit of 255.

NB. While the BAM format allows the dimensions of a frame to be very large, the engine will only show frames up to a certain size. This maximum size varies with the version of the engine:
BG1: Unknown
BG2: 256*256
PST: Unknown (greater than 256*256)
IWD1: Unknown
IWD2: Unknown
BGEE: Unknown (1024*1024 or greater)

Detailed Description

Offset Size (data type) Description
0x0000 4 (char array) Signature ('BAM ')
0x0004 4 (char array) Version ('V1  ')
0x0008 2 (word) Count of frame entries
0x000a 1 (unsigned byte) Count of cycles
0x000b 1 (unsigned byte) The compressed colour index for RLE encoded bams (ie. this is the colour that is compressed)

The transparency index is set to the first occurence of RGB(0,255,0). If RGB(0,255,0) does not exist in the palette then transparency index is set to 0
0x000c 4 (dword) Offset (from start of file) to frame entries (which are immediately followed by cycle entries)
0x0010 4 (dword) Offset (from start of file) to palette
0x0014 4 (dword) Offset (from start of file) to frame lookup table

Cycles may share the frames, which is accomplished by using a layer of indirection. Instead of specifying which frames belong to a given cycle, each cycle has a list of frame indices.

Offset Size (data type) Description
0x0000 2 (word) Frame width
0x0002 2 (word) Frame height
0x0004 2 (signed word) Frame center X coordinate
0x0006 2 (signed word) Frame center Y coordinate
0x0008 4 (dword)
  • bits 30-0: Offset to frame data
  • bit 31: 0=Compressed (RLE), 1=Uncompressed

These entries refer to a range of indices in the frame lookup table, which in turn points to the actual frames. Note that entries in the frame lookup table can also be shared between cycles.

Offset Size (data type) Description
0x0000 2 (word) Count of frame indices in this cycle
0x0002 2 (word) Index into frame lookup table of first frame index in this cycle

The palette is a standard array of RGBQUAD structures, with a layout as follows:
Alpha component of the RGBQUAD is unused.

Alpha is only considered when used in the context of the user interface (e.g. for portrait, worldmap or spellbook icons). An alpha value of 00h is treated as fully opaque to maintain backwards compatibility with non-Enhanced games. Alpha values of 01h .. FFh indicate transparency ranging from almost completely transparent to fully opaque. Full transparency can be realized by using palette index 0.

This is an array of frame indices. A cycle specifies a sequence of entries in this table. For instance, an animation might start at the 0th element in this array, and travel over 6 frames. (The next animation, then, would typically start at the 6th element and run over some number of indices.) If the first 6 entries in this table were { 0, 1, 1, 2, 3, 4 }, the animation would display frame #0, followed by frame #1 for two time periods, followed by frames 2, 3, 4 in order. To find the number of entries in this lookup table, find the largest value of start+count in the cycle entries table.

If this is not a compressed frame, then this is simply width*height bytes, which are pixel values using the palette specified earlier. If this is a compressed frame, the data is compressed with a run-length-encoding scheme. The scheme is as follows:
  • Any byte which is not the transparent index from the header represents itself
  • The transparent index followed by a byte x represents (x+1) copies of the transparent index

BAMC format
Overall structure:
  • Header
  • zlib compressed data

  • A BAMC file consists of a 12 byte header followed by a zlib compressed BAM file.

    Offset Size (data type) Description
    0x0000 4 (char array) Signature ('BAMC')
    0x0004 4 (char array) Version ('V1  ')
    0x0008 4 (dword) Uncompressed data length