Tes2Mod: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


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.  



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


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: 



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: 



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