HFD Files in detail

What are HFD Files?

HFD Files are small text files that describe to Packafied some of its supported file formats. This means that new HFD files can be written to make Packafied support new file types. Packafied uses all the HFD files it can find in its HFD Directory to work out the format of the files it loads.

As of Packafied 0.4, there are two types of files. There are HFD Files that are compatible with HAMM, and there are FD files that can only be used in Packafied. In this section, both FD and HFD files will be called HFD files.

HFD File Format

HFD files are just plain text files, so you can any text editor to create them. Before you read this, make sure you understand what 'package' files are, and that you know how they work.

In HFD Files, a long integer is 4 bytes long. The first position of the file is 1, not 0 as in many programming languages, so be careful when specifying positions in files!

Generally, there is one line enclosed in square brackets ([]) that are headings, and the value for this heading follows on the next line. No blank lines are allowed! Here is a list of the different headings:

(*) The add extension heading's values are 3 lines in length, unlike the others.
(**) These headings are not supported by Packafied at this time, only HAMM.
(***) These headings are new to Packafied and not used by HAMM, though HAMM will still work if it encounters this heading.
(X) This heading is only to be used in FD files, as they are not supported in HAMM.

The [EXTENSION] heading

The value under this heading is the extension of the files that will be opened. For instance, for WAD files, the value would be WAD.

e.g.
[EXTENSION]
WAD

The [START OF TABLE] heading

The value under this heading states what position the pointer to the start of the table of entries is. For instance, WAD files have their table of entries at the end of the file. The pointer to this position, however, is stored always at position 9 (after the 8th byte) in the file.

e.g.
[START OF TABLE]
9

The [ABS START OF TABLE] heading

This value, unlike the start of table heading, specifies where the table starts directly. You would use this heading if the file you were dealing with had its entries at the start of the file, and that the table of entries always started at a certain position. For instance, entries always begin at position 9 in an MVL file.

e.g.
[ABS START OF TABLE]
9

Note that either START OF TABLE, or ABS START OF TABLE must be used in an HFD file, but NOT both!

The [NUMBER OF ENTRIES] heading

This value specifies where the long integer is stored in the file which describes how many entries there are present in it. For instance, you can find out how many entries there are in a WAD file by reading the long integer at position 5.

e.g.
[NUMBER OF ENTRIES]
5

The [ENTRY LENGTH] heading

Under this heading, put how long each entry is in the table (in bytes). For instance, if you have a table that has the following data:
name(13),length(4),resolution(8),position(4)
the length for one entry would be 13+4+8+4, or 29 bytes. This includes ALL data, even if HAMM or Packafied isn't going to need to read it later on.

e.g.
[ENTRY LENGTH]
29

The [START] heading

This is where we start getting into each entry. The value under the START heading represents where the value that points to the start of the entry is. For instance, in a WAD file, the first piece of data in each entry is where (what position in the WAD file, in bytes) the data of the entry is located. Since it is the first value, it would look like:

[START]
1

The [LENGTH] heading

This also applies to each entry. The value under the length heading represents the size (in bytes) of the data of the entry. For instance, in a WAD file, the length of the data is the 2nd piece of data in the table. So it would look something like:

[LENGTH]
5

The [NAME] heading

This also applies to each entry. The value under this heading represents what position of each entry the name of the file is stored under. For instance, in a WAD file, the name of each entry is stored after the start and length data, so it would look something like:

[NAME]
9

The [NAME LENGTH] heading

The NAME heading tells Packafied or HAMM where the name is located in each entry, but we still don't know how long each name can go to. This value under this heading represents the maximum length of each file name in the table of entries. For WAD files, this value would be 8, since file names cannot be longer than 8 characters. Note that when working out the length of a file name, everything is included, like full-stops and the NULL value at the end of the name.

The [LOWER CASE] heading

Put a 1 under this heading, and all file names that are originally in upper case will be converted to lower case. This is useful only to make all the file names look a bit neater!

e.g.
[LOWER CASE]
1

Packafied doesn't currently support the lower case heading.

Actually, you can put anything under a lower case heading. It doesn't matter. Filenames are converted to lower case if the LOWER CASE heading is detected.

The [START MODE] heading

We all have our problems, and sometimes files do not specify in their tables of entries where each entry starts! Normally, this would cause problems, since Packafied or HAMM would not know where each entry starts. Thanks to different start modes, though, the start of each file can be calculated by incrementing the length for each successive file. Use this heading ONLY if you do NOT have a START heading! (duh!). Put a 1 under a start mode heading and the start of each file will be calculated by using the length to increment the start every time. The offset to the first file data is set to be the byte after the table of entries.

If the file writes the offset to the first contained file to a position, you can use the [FIRST DATA OFFSET] heading. If this heading exists, the offset of the first file is read from the file at the specified position in [FIRST DATA OFFSET]. Otherwise the offset of the first file is set to be the byte after the table.

If there is no start of each file (offset) specified in the table of entries, give it a shot!

e.g.
[START MODE]
1

Put a 2 under START MODE if the value gathered at the position specified by the START heading represents the position AFTER the table instead of the byte position in the file. To demonstrate this, let's take an example. You have a file with a table at the start of the file, and the data afterwards. The first entry, though, specifies a start at position 0. What this means, though, is that the data start 0 bytes AFTER THE END OF THE TABLE, not at position 0 in the file!!! To tell HAMM or Packafied this, you must put a value of 2 under the START MODE heading.

e.g.
[START MODE]
2

The [CHECK] heading

The value under this heading is used to check that the file opened is actually of that type. For instance, PWAD files have the text 'PWAD' as the first 4 characters in the file. If you want to add the checking ability to your HFD file, simply put:

[CHECK]
PWAD

Make sure you don't put extra spaces on this line. Whatever is on this line is used to check the first characters in the file you are opening. That means if you put spaces at the end of this line, they are also checked. This heading is not necessary, so if it doesn't work, don't worry.

The [STRIP PATHS] heading

Some files have entire pathnames stored in them as well as the filename. For instance, Quake PAK files may have something like:
weapons\axe\axe1.wav
as one name. HAMM could load this, but it would be treated as one long file name instead of path and filename. To make it look tidier, simply put a 1 under the STRIP PATHS heading and only file names will be displayed. This heading is not currently supported in Packafied due to problems when renaming files.

Actually, I lied earlier... I told you a Quake path that wouldn't exist. That's because instead of weapons\axe\axe1.wav, it would actually be weapons/axe/axe1.wav, with slashes instead of backslashes. To get rid of forward slashes, use a 2 under the STRIP PATHS heading instead of a 1.

The [NUMENTRIES MODE] heading

Put a 1 under the numentries mode heading if the number of entries read from the position specified by the NUMBER OF ENTRIES heading represents number of bytes of entries instead of number of entries. In other words, put a 1 under this heading if the value read from NUMBER OF ENTRIES represents the number of bytes in the table instead of the number of entries in the table.

For instance, in Quake PAK files, this is the case. To work out the number of entries you must divide the 'number of entries' value by the length of each entry in the table.

e.g.
[NUMENTRIES MODE]
1

The [SOUND SPEED] heading

This is only relevant to RAW sound files, not WAV files. The value under this heading represents the speed of all RAW files in Hertz. This is useful for S11 and S22 files in Descent, where S11 files are sounds in 11025 Hz, and S22 files are the better quality sounds in 22050 Hz. So, for S11 files, you would put:

[SOUND SPEED]
11025

and for S22 files, you would put:

[SOUND SPEED]
22050

Note that RAW sound files MUST be 8 bit!!! Unfortunately, if RAW files are 16 bit, they will not be playable.

The Sound Speed heading is not supported in Packafied because it doesn't have any internal viewers yet.

Note that if you don't use the [SOUND SPEED] heading, HAMM defaults to 11025 Hz.

The [ADD EXTENSION] heading

This heading is very useful when used well. For files like WAD files, where the file names don't have extensions, it can be extremely hard identifying what sort of file, say, D_README is. This is where ADD EXTENSION comes in! Use it in the following way:

[ADD EXTENSION]
containingstring
extension
mode

For instance, we could have the following for a WAD file:

[ADD EXTENSION]
d_
.mus
1

This means that any file that STARTS with 'd_' will have a '.mus' extension added to it. This would include d_readme, d_runnin, but not refd_1. If the mode was 0, though, refd_1 WOULD have '.mus' added to it. ADD EXTENSION is very useful for associating files that normally don't have an extension. For the example above, we could associate all .mus files with a batch file that

  1. converts the MUS file to a MIDI file
  2. plays the MIDI file with Media Player
Special Cases
If you make containingstring zero length, then ALL files will have the extension added to them! This is useful with S11 and S22 files, where we know that all files within these files are RAW sound files.

The Add Extension heading is not supported in Packafied yet.

The [DESCRIPTION] heading

The item under this heading is used to describe the HFD file. For example, to describe a file that loads up Descent 3 HOG files, put:

[DESCRIPTION]
loads Descent 3 HOG Files

Simple and to the point!

Note: The [DESCRIPTION] heading is optional.

The [FIRST DATA OFFSET] heading

Specifies the position in the file where the offset to the first byte of data can be found.

This heading can only be used if the ABS START OF TABLE heading is used. If start mode is equal to 1, this heading is used if it exists to locate the first offset of the data.
If start mode is anything else, after every editing operation, the value is updated in the package file, but is not actually used as offsets are given with each file.

For example, say a package file does not write offsets with any of its contained files. Therefore, startmode is 1. If this heading did not exist, the offset for the first file would be calculated as being the first byte at the end of the table. But if the file wrote the offset to the first data at position 9, put:

[FIRST DATA OFFSET]
9

and the offset to the first file would be read from position 9 instead. Editing operations that need to update this value, such as adding and deleting, write new data offsets to this position when needed.

Note: The [FIRST DATA OFFSET] heading is not supported by HAMM, and therefore should only be used FD files, not HFD files!