README

TilePack Archive is a fast, custom binary archive format with indexed access – designed for tile-based resources such as map tiles, offline assets, or collections of small files.

🚀 Features

Compact, binary format with custom header
Recursively includes all files from a source directory
Fast indexed access via offset map at the archive’s end
Ideal for embedded systems, offline distribution, and tiled image rendering
Supports arbitrary file types (e.g., .jpg, .png, .json, etc.)
Lightweight – no external decompression tools needed

🔧 Installation

Install via Composer:

composer require ddbase3/tilepack-archive

📦 Usage

Create an archive

use TilePack\TilePackWriter;

$writer = new TilePackWriter();
$writer->createArchive('path/to/tiles/', 'output/archive.tpa');

Read a file from the archive

use TilePack\TilePackReader;

$reader = new TilePackReader('output/archive.tpa');
$data = $reader->readFile('z/3/x4_y2.jpg');

file_put_contents('copy.jpg', $data);

📁 Archive Format

A TilePack archive consists of:

A header for identification (TILEPACK)
The tile data, per file:
- Path length (uint32)
- Path (UTF-8)
- File size (uint32)
- File content (binary)
A compact index stored at the end:
- Each entry maps a file path to its byte offset
- Enables direct seeking with fseek() without scanning the archive

🧪 Run Tests

vendor/bin/phpunit

🤝 License

This project is licensed under the terms of the LGPL.

👤 Author

Daniel Dahme
contourz.de
Photographer and developer with a focus on performance and creative tooling.

ddbase3 / tilepack-archive

Maintainers

Details