Module yay0

Adds support for the Yay0 compression format used for first-party N64 and early GameCube games.

Because the Yay0 format is so lightweight, this module is designed to not have any persistence. It takes in data, and will return the de/compressed data contained inside.

Format

The Yay0 format is part of the Lempel-Ziv family of algorithms, which use a “sliding window” to allow for copying repetitive data from previously in the output buffer. The input is split into three sections. The first contains flag bytes that signal whether to copy from the input or from the output buffer, the second contains all copyable data, and the third contains all lookback+length pairs.

Header

The header is as follows, in big-endian format:

Offset	Field	Type	Notes
0x0	Magic number	u8[4]	Unique identifier (“Yay0”) to let us know we’re reading a Yay0-compressed file.
0x4	Output size	u32	The size of the decompressed data, needed for the output buffer.
0x8	Copy data offset	u32	Offset to the copyable data section. See format for details.
0xC	Lookback offset	u32	Offset to the lookback data section. See format for details.

Decompression

The decompression algorithm is as follows, ran in a loop until you write enough bytes to fill the output buffer:

• Set three pointers, one to header+0x10 for flag data, one to the copy data offset, and one to the lookback offset.
• Read one byte from the flag data, which is 8 flag bits from high to low.
• For each flag bit, if it is a 1, copy one byte from the data section to the output.
• If it is a 0, copy bytes from earlier in the output buffer:
  • Read two bytes from the lookback section.
  • Get the first nibble (code >> 12). If it is 0, read one byte from the copy data section and add 18 (0x12). Otherwise, add 2 to the nibble. Use that as the number of bytes to copy.
  • Add 1 to the lower nibbles (code & 0xFFF) and treat that as how far back in the buffer to read, from the current position.
  • Note that the count can overlap with the destination, and needs to be copied one byte at a time for correct behavior.
  • Copy that amount of bytes from the lookback position to the current position.

Usage

This module offers the following functionality:

Decompression

• decompress_from_path: Provide a path, get decompressed data back
• decompress_from: Provide the input data, get decompressed data back
• decompress: Provide the input data and output buffer, run the decompression algorithm

Compression

• compress_from_path: Provide a path, get compressed data back
• compress_from: Provide the input data, get compressed data back
• compress_n64: Provide the input data and output buffer, run the compression (matching algorithm)

Utilities

• read_header: Returns the header information for a given Yay0 file
• worst_possible_size: Calculates the worst possible compression size for a given filesize

Structs

Header

See the module header for more information.

Yay0

Utility struct for handling Yay0 compression.

Enums

CompressionAlgo

All supported Yay0 compression algorithms

Error

Error conditions for when reading/writing Yay0 files