Daggerfall Mod:BSA file formats

The UESPWiki – Your source for The Elder Scrolls since 1995
Jump to: navigation, search

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

General BSA Files[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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[edit]