Module format 

Information and structures for vpk0 files.

There are three structures at the start of a vpk0 file:

1. Header
2. Offset Bitsize Huffman Tree
3. Length Bitsize Huffman Tree

Header

There is a nine byte header at beginning of the file that includes the sample number for the encoded offsets, as well as the size of the decompressed data. The key data can be extracted into a VpkHeader by using vpk_info().

Byte Num	Description
0..4	magic bytes (“vpk0”)
4..8	size in big endian bytes of decompressed data
9	Sample Method (0 => One Sample; 1 => Two Sample )

Huffman Trees

After the header, there are two linearly encoded Huffman trees: one for the offsets, and one for the lengths. The two trees can be extracted into their String representations as TreeInfo by using vpk_info().

Tree leafs are encoded as a 0 followed by an eight bit value leaf. Tree nodes are encoded by a 1, and combine the most recent two nodes/leaves. For example, the simple tree (1, (4, 7)) would be encoded in binary as:

0 00000001 0 00000100 0 00000111 1 1

and it would give the following Huffman codes:

Bitsize	Code
1	0
4	10
7	11

So, let’s say that you wanted to encode an offset of seven with the same tree as above:

┌ read next four bits
|  ┌ value
10 0111

Single leaf trees are valid, but the leaf will have a “zero length” huffman code. Existing decoders return of value of zero for a zero-length tree.

Note that the trees do not store the actual offset or length value, but rather they store the number of bits to read for the actual offset or length.

Offset Tree

The offset tree stores the bit sizes for encoding an “LZSS” offset value. The offset tells the decoder how far to move back in the decoded output before copying back. While the vpk0 format can single or double sample encoded offsets, those differences do not affect the tree.

Length Tree

The length tree stores the bit sizes for encoding an “LZSS” length value. The length tells the decoder how many bytes copy back from decoded output.

An Example

Let’s encode the exciting and useful ascii string “YAAAAAAAAAAAAAA” into a one sample vpk0 file. We’ll use an inefficient offset and length tree of (1, (4, 7)). The LZSS encoding of the input will be [‘Y’, ‘A’, (1, 13)], where (1, 13) is an offset of 1 and a length of 13.

Header
76706B30 <- "vpk0"
0000000F <- original file size of 15 bytes
00       <- one sample

Offset Tree (see above for how this was generated)
0 00000001 0 00000100 0 00000111 1 1
Length Tree
0 00000001 0 00000100 0 00000111 1 1

Encoded Data
0 01011001 <- uncoded ascii 'Y'
0 01000001 <- uncoded ascii 'A'
┌ encoded
| ┌ read next 1 bit
| | ┌ offset value (1)
| | | ┌ read next 7 bits
| | | |  ┌ length value (13)
1 0 1 11 0010011

Structs

TreeInfo

Textual representations of the offsets and lengths Huffman trees in a vpk0 file

VpkHeader

The information stored at the start of a vpk0 file

Enums

VpkMethod

Valid lookback methods for a VPK compressed file.