Skip to content
/ pack Public

Runtime optimized multi-platform data packing library for realtime game resources loading

License

Notifications You must be signed in to change notification settings

cfnptr/pack

Repository files navigation

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
  • Customisable compression threshold
  • C and C++ implementations

Usage example

void packReaderExampleCPP()
{
    pack::Reader packReader("resources.pack");
    auto itemIndex = packReader.getItemIndex("textures/sky.png");
    std::vector<uint8_t> itemData;
    packReader.readItemData(itemIndex, itemData);
    // use data...
}
void packReaderExampleC()
{
    PackReader packReader = NULL;
    PackResult packResult = createFilePackReader("resources.pack", false, 1, &packReader);
    if (packResult != SUCCESS_PACK_RESULT) abort();

    uint64_t itemIndex = 0;
    bool result = getPackItemIndex(packReader, "textures/sky.png")
    if (!result) abort();

    uint32_t dataSize = 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);
}

Supported operating systems

  • Windows (10/11)
  • Ubuntu (22.04/24.04)
  • macOS (14/15)

This list includes only those systems on which functionality testing is conducted. However, you can also compile it under any other Linux distribution or operating system.

Build requirements

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 https://github.com/cfnptr/pack

Building CI

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

Utilities

packer

Creates compressed data pack from files.

  • Usage: packer <pack-path> <file-path-1> <item-path-1>...
  • Example: packer resources.pack C:/Users/user/Desktop/sky.png images/sky.png

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

  • mpio (Apache-2.0 License)
  • zstd (BSD License)