virtualfs

VirtualFs is a library for the Crystal programming language that lets an app treat many different sources of files as one unified folder structure. You can mount a regular folder on disk, or a zip file, a tar file, or the library's own custom archive format called vpak, and then read files from any of them using the same simple commands, without your code needing to know where a file actually lives.

This is aimed mainly at people building games, desktop apps, or other tools that need to bundle lots of small files, like images, audio, or configuration, into their shipped product. Instead of packaging thousands of loose files, everything can be packed into one vpak archive with built in compression and deduplication, meaning identical pieces of data are only stored once even if many files share them. Archives can also be encrypted per file using standard modern encryption methods.

One useful feature is priority based mounting: you can mount a patch archive on top of the original game files, and if a file exists in both, the patch version is used automatically, which makes it easy to ship updates without rebuilding the whole package. The library also supports reading just a portion of a file without decompressing the whole thing, memory mapped access for speed, and even serving files directly over HTTP with support for partial downloads.

The library includes a command line tool called vpack for building, listing, and verifying these archive files, alongside a documented byte level specification of the vpak format itself for anyone who wants to write their own compatible tooling. It is installed as a normal Crystal shard dependency in a project's shard.yml file.