NPK file format

The NPK file format is loosely based on Quake's PACK file format. It consists of a header describing its contents, an arbitrary number of packed files (uncompressed and otherwise identical to their loose on-disk source files), and a table indicating the location and size of each packed file.

The NPK format has been used in all my games as far back as Arc Aether Anomalies (2008) and has been revised once in 2014. This document contains notes on version differences where necessary. (For the case of YHtWtG, version 1.0 may be assumed.)

Unless otherwise specified, the types "int" refers to a 32-bit integer, "short" to a 16-bit integer, and "byte" to an 8-bit integer. All values are assumed to be little-endian.

The first element of the pack file is the header. Its size and contents vary depending on version:

struct NPackFileHeader
{
	unsigned int MagicWord;			// Expected to be '.kpn' (v1.0) or 'kpn.' (v2.0)
	short MajorVersion;				// Does not exist in v1.0!
	short MinorVersion;				// Does not exist in v1.0!
	unsigned int TableOffset;		// Offset in bytes from start of file to table of contents
	unsigned int TableSize;			// Size in bytes of table of contents
};

As its size may vary, the header must be read an element at a time and not all at once.

The first 32 bits of the file are always a "magic word" unsigned int indicating its type. In version 1.0, this was erroneously '.kpn' (0x2e6b706e). In version 2.0, this was corrected to 'kpn.' (0x6b706e2e). This can be used to distinguish between version 1.0 and all subsequent versions, as explicit version information was not added until version 2.0.

If and only if the magic word is 'kpn.', indicating version 2.0+, then it will be followed by two shorts indicating major and minor version respectively.

The next two values are unsigned ints indicating the location and size of the table of contents, which is located at the end of the pack file. The location is expressed as an offset from the start of the pack file in bytes, and the size is expressed in bytes.

Entries in the table of contents are defined as follows:

struct NPackFileContent
{
	char Filename[248];				// The filename of the packed file, typically does not contain any path information
	unsigned int Offset;			// Offset in bytes from the start of the pack file to this packed file
	unsigned int Size;				// Size in bytes of this packed file
};

The number of entries in the table of contents may be calculated as Header.TableSize / sizeof(NPackFileContent). Its contents may be read wholesale into an array or presized vector<NPackFileContent>, or they may be loaded one at a time into a map/dictionary keyed by filename for faster access. Once this is done, individual packed files may be loaded by comparing a requested filename (e.g., "yhtwtg_xs.map") against entries in the table of contents, then seeking to the offset specified and reading up to the size in bytes specified.