HVQ Filesystem
HVQ is the primary image compression format used in all 3 Mario Party titles for the N64, and the HVQ Filesystem is the name of the organizing structure for the vast majority of HVQ images.
The HVQ Filesystem is strikingly similar to the Main Filesystem, but it is slightly unique in its table structure.
The HVQ FS, like the Main FS, is composed of directories and files within those directories. A directory contains a set of HVQ image tiles that together make up a single background image, such as a board background or scene. Most big, static backgrounds are contained in this filesystem.
There is no compression built into the filesystem, because HVQ itself is a compressed image format.
There are dozens of ASM references to the start of this filesystem, which makes it impractical to relocate the structure by hex editor alone. Beyond this, there are no known violations of the abstraction barrier (access directly into a directory or file by ASM).
At the start of the filesystem, there is a directory table with offsets to each of the background directories. The background directory offsets should be increasing (the directories are layed out in order).
| Offset | Description |
|---|---|
0x0 |
u32 directory_count |
0x4 |
u32 offsets[directory_count + 1] |
The twist with the HVQ FS is that every table has an extra offset that points to the end of the entire structure. This is because there is no size information present with each file, so taking the difference between the current offset and the next is required to know the length of the HVQ data. (There seems to be ways to determine the length from pieces of the HVQ header as well, but that has not been verified to be always correct.)
PP64 aligns this table, each directory, and each HVQ file on word-divisible offsets in the ROM.
The start of each directory is a file table, because the only point of the directory is to group a set of HVQ image tiles. Like the background directory table, this is an offset listing.
| Offset | Description |
|---|---|
0x0 |
u32 tile_count |
0x4 |
u32 offsets[tile_count + E] |
What is the + E?
There are extra files included besides the tiles themselves, and there is also an extra offset reserved that just points to the end of the directory.
| Game | Value of E |
|---|---|
| Mario Party 1 | 2 |
| Mario Party 2 | 3 |
One of the extra files is a background info file, which contains some details about the background image. In Mario Party 2, there is also an extra HVQ-MPS file that is not part of the tile count.
The background info file encodes basic information about the background that the following HVQ files represent.
| Offset | Description |
|---|---|
0x0 |
u32 tile_width (px) |
0x4 |
u32 tile_height (px) |
0x8 |
u32 tile_x_count |
0xC |
u32 tile_y_count |
There are more fields after this that appear to be floating point numbers. These mystery values may relate to the camera used with the background.
Following the info file is each of the HVQ files as pointed to by the file table. The ordering is bottom to top, left to right, when considering the 2D set of tiles. So after dividing an image into tiles, the bottom row of tiles is written first.
With the addition of animations in Mario Party 2, the HVQ filesystem also contains some tiles that are run length compressed rather than HVQ compressed. These have a small header followed by the compressed data.
| Offset | Description |
|---|---|
0x0 |
u32 compression_type (always 3) |
0x4 |
u32 decompressed_size (always 0x1800 for 64 x 48 tiles) |
0x8 |
u8 compressed_data[] |
In practice, the original tiles that use this format are part of animations; it may be that HVQ was too slow to do animation tile swapping with. PartyPlanner64 makes use of this simpler format when overwriting boards for more than just animation tiles.