Pack

A library providing packing of files into runtime reading optimized archives, across different platforms.
For example can be used to load game resources. (images, shaders, models, levels, etc...)

See the documentation.

Features

• Compressed file pack creation
• Runtime optimized file pack reading
• Automatic file data deduplication
• Maximum ZSTD compression level
• Optional faster data reading (LZ4)
• Customizable compression threshold
• C and C++ implementations
• Supports Windows, macOS and Linux

Usage example

voidpackReaderExampleCPP()
{
pack::Reader packReader("resources.pack");
auto itemIndex = packReader.getItemIndex("textures/sky.png");
std::vector<uint8_t> itemData;
packReader.readItemData(itemIndex, itemData);
// use data...
}

voidpackReaderExampleC()
{
PackReaderpackReader=NULL;
PackResultpackResult=createFilePackReader("resources.pack", 0, false, 1, &packReader);
if (packResult!=SUCCESS_PACK_RESULT) abort();
uint64_titemIndex=0;
boolresult=getPackItemIndex(packReader, "textures/sky.png")
if (!result) abort();
uint32_tdataSize=getPackItemDataSize(packReader, itemIndex);
uint8_t*itemData= (uint8_t*)malloc(dataSize);
if (!itemData) abort();
packResult=readPackItemData(packReader, itemIndex, itemData, 0)
if (packResult!=SUCCESS_PACK_RESULT) { free(data); abort(); }
// use data...destroyPackReader(packReader);
}

Build requirements

• C99 compiler
• C++17 compiler (optional)
• Git 2.53+
• CMake 3.16+

Use building instructions to install all required tools and libraries.

CMake options

Name	Description	Default value
PACK_BUILD_SHARED	Build Pack shared library	ON
PACK_BUILD_UTILITIES	Build Pack utility programs	ON
PACK_BUILD_TESTS	Build Pack library tests	ON

CMake targets

Name	Description	Windows	macOS	Linux
pack-static	Static Pack library	.lib	.a	.a
pack-shared	Dynamic Pack library	.dll	.dylib	.so
packer	Packer executable	.exe
unpacker	Unpacker executable	.exe
pack-info	Pack info executable	.exe

Cloning

git clone --recursive -j8 https://github.com/cfnptr/pack

Building

• Windows: ./scripts/build-release.bat
• macOS / Linux: ./scripts/build-release.sh

Utilities

packer

Creates compressed data pack from files.

• Usage: packer [-z, -v, -s] <pack-path> <file-path-1> <item-path-1>...
• Example: packer resources.pack C:/Users/user/Desktop/sky.png images/sky.png

Arguments:

• -z <zipThreshold>: Specifies file compression threshold when we just pack file without compressing it. It's used for already compressed resources like images. Default value is 10. (0% - 100% range)
• -v <dataVersion>: Specifies resources.pack file version. It's used to check if we are loading correct resources pack for a current game or application version. Default value is 0.
• -s: Use faster decompression algorithm sacrificing resources pack file size.

unpacker

Extracts compressed data pack files.

• Usage: unpacker <pack-path>
• Example: unpacker resources.pack

pack-info

Shows pack file information.

• Usage: pack-info <pack-path>
• Example: pack-info resources.pack

Third-party

• lz4 (BSD 2-Clause license)
• mpio (Apache-2.0 License)
• zstd (BSD License)