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.