Daggerfall Mod:BSA file formats

This is a description of the format of the *.BSA files found in the Daggerfall's ARENA2 directory.

General BSA Files

There are five BSA files in Daggerfall's ARENA2 directory (ARCH3D, BLOCKS, MAPS, MONSTER, and MIDI). Although they contain different data, their overall structure is the same. This format has been derived from all these five files.

A BSA file is very similar to a "tarball" (TAR) file. It is a convenient means of concatenating several different files into a single file without losing information or structure. Elements of a BSA file are referred to as "Records". Each Record contains one or more subelements.

General File Layout

BSA File coarse structure

BsaHeader
+Record
BsaFooter

The BsaHeader structure is a fixed-size structure which reports the count of contained records, as well as the type of the records contained. Following this is a contiguous list of records. Reading and decoding the records is file-dependent, detailed in separate articles. The variably-sized BsaFooter structure follows the records. The BsaFooter reports the offset within the file for each record, as well as the index or name of the structure. Each element of the BsaFooter has a fixed-size (determined by the BsaHeader), which makes locating the BsaFooter trivial.

Reading a BSA File consists of reading the BsaHeader to determine the type of the file and the count of the records. From this, the position of the BsaFooter may be computed. At this point one may then iterate the contained records.

BSA Header

The first 4 bytes of a valid BSA File consists of a BsaHeader structure. This structure reports the count of records contained within the file, as well as the type of indexing (described below) used.

BsaHeader structure

Offset by Ordinal	Type	Name	Description
0-1	UInt16	RecordCount	The count of record entries contained within the BSA file.
2-3	BsaType	Type	An enumeration describing the indexing of the BSA File. Records within the file are to be accessed via either a string index (Ex: "S0000019.RDI"), or an integral index (Ex: 2416).

BsaType

The BsaHeader.Type field is an enumeration of the following values:

BsaType enumeration

Value	Type	Description
0x0100	NameRecord	Records are associated/indexed with a 7-bit ASCII string name.
0x0200	NumberRecord	Records are associated/index with a UInt16 recordID.

BsaFooter

At the end of the file is a contiguous list of RecordIndex structures. Each RecordIndex element describes the index and offset of a record within the BSA File. The specific structure is dependent on the BsaHeader.Type field, but each is of a fixed-length. There are exactly BsaHeader.RecordCount elements within the list. Each type of RecordIndex structure is described below.

Since each type is of fixed-length, to iterate these descriptors one merely needs to navigate from the end of the file a number of bytes equals to the BSA File's RecordCount entry multiplied by the size of the descriptor.

For example: if the BsaHeader.Type is 0x0100, and the BsaHeader.RecordCount is 23, then the BsaFooter begins at (23 * 18) bytes from the end of the file.

Only after one has iterated the descriptors, one can begin to read the contained Records.

The records are stored in the same order as they appear in the BSA Directory Section; that is to say the third descriptor refers to the third record.

NameRecord

The BsaFooter of 0x0100 type files (NameRecord) is composed of a contiguous list of 18 byte record descriptors, documented below. Each NameRecordDescriptor reports the size of the described record, and the record's 7-bit ASCII String name which is to be used as the record's index:

NameRecordDescriptor Structure

Offset by Ordinal	Type	Name	Description
0-11	7-bit ASCII string	RecordName	The name of the NameRecord described. All entries are in DOS 8.3 format. All entries are null-padded.
12-13	Int16	Compressed	Indicates the file is compressed. This is not used in Daggerfall
14-17	Int32	RecordSize	The size of the NameRecord entry in bytes.

NumberRecord

The BsaFooter of 0x0200 type files (NumberRecord) is composed of a contiguous list of 8 byte record descriptors. Each NumberRecordDescriptor reports the size of the described record, and the record's UInt16 recordId which is to be used as the record's index:

NumberRecordDescriptor Structure

Offset by Ordinal	Type	Name	Description
0-1	UInt16	RecordId	The recordId by which Daggerfall's engine accesses the records.
2-3	Int16	Compressed	Indicates the file is compressed. This is not used in Daggerfall
4-7	Int32	RecordSize	The size of the NameRecord entry in bytes.

BSA Records

Once one has iterated the BsaFooter elements at the end of the BSA File, one can compute the positions of individual records within the file. The first record starts immediately following the BsaHeader structure. All records are contiguous (a successor follows immediately after her predecessor).

The files are not necessarily "stand-alone", but contain references to records in other files. The Daggerfall world is designed on a "lego" system. For example: One would define the 3D mesh for a building in ARCH3D, then one would include a reference to that building in BLOCKS, then one would refer to that block in multiple towns in MAPS. In this way a third-order infinity system can be constructed.

This format and structure of the record data will depend on the actual BSA file.

The basic contents for the seven BSA files are as follows:

ARCH3D.BSA - 3D Object Information

The necessary 3D mesh/structure information required by Daggerfall's rendering engine.

BLOCKS.BSA - Dungeon/town block information

This file's records describe the "modules" used to build the town exteriors, building interiors, and dungeon interiors. These records will also contain the necessary scripting records for levers, elevators, switches, et al.

MAPS.BSA - Location information (towns, dungeon, houses, temples, etc...)

The records of this file report the world.

Each record describes a distinct location (see Location Types), reporting which BLOCKS records are necessary to "build" the location, and other sundry data.

MONSTER.BSA - Monster data (no images)

Contains ASCR####.ANC and ENEMY###.CFG files in a type 0x0100 directory.

MIDI.BSA - HMI formatted music

Contains MIDI data stored in the proprietary HMI format in a type 0x0100 directory.

DAGGER.SND - WAVE formatted audio data

Contains raw audio data (8-bit unsigned, mono, ~11025 samples per second) in a type 0x0200 directory.

MAPSAVE.SAV - Automap data

Contains MAPSAVE.0## files for each region in a type 0x0100 directory.

(See Location Types).

Appendices

• Building Types
• Class and Enemy CFGs
• Coordinate Limits
• Land Creation Notes
• Location Types
• Region Numbers
• UV Texture Coordinates