https://github.com/hypernewbie/vark
Vark - Simple LZAV Archive
https://github.com/hypernewbie/vark
archive cli compression cpp game-dev gamedev header-only high-performance lzav mmap
Last synced: about 1 month ago
JSON representation
Vark - Simple LZAV Archive
- Host: GitHub
- URL: https://github.com/hypernewbie/vark
- Owner: hypernewbie
- Created: 2025-12-24T02:35:36.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-04-05T20:55:24.000Z (3 months ago)
- Last Synced: 2026-05-27T02:33:55.692Z (about 1 month ago)
- Topics: archive, cli, compression, cpp, game-dev, gamedev, header-only, high-performance, lzav, mmap
- Language: C++
- Homepage: https://uaasoftware.com/vark.html
- Size: 16.9 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Vark - Simple LZAV Archive
[](https://github.com/hypernewbie/vark/actions/workflows/build.yml)
[](https://github.com/hypernewbie/vark/releases/download/v1.04/vark-windows-v1.04.zip) [](https://github.com/hypernewbie/vark/releases/download/v1.04/vark-linux-v1.04.zip) [](https://github.com/hypernewbie/vark/releases/download/v1.04/vark-macos-v1.04.zip)
### Load stuff at DDR2 RAM speed!
Vark is a minimal LZAV archive library and tool, designed for speed and simplicity. It uses the LZAV compression algorithm, which is fast and efficient.
For more information about LZAV, see [LZAV on GitHub](https://github.com/avaneev/lzav).
> NOTE: Vark is vibe coded using Gemini AI, albeit closely instructed and architected by the author, who is a professional software engineer. Use at your own risk.
## Features
- Simple C-style C++ interface
- Fast LZAV compression and decompression
- Minimal archive format
- Sharded compression support for fast partial reads
- Memory-Mapped I/O support (MMAP)
## Performance
* **CPU** AMD Ryzen Gen 3
* **SSD** Samsung 970 Evo Plus M2
* **Test Data:** 12.58 MB (Mixed File Types)
* **Sharded Test Data:** 9.02 MB (PNG File)
| Mode | Task | Throughput |
| --- | --- | --- |
| **Normal** (Single-threaded) | Compression | 0.486 GB/s |
| | Decompression | 1.689 GB/s |
| **Persistent** (FP + TempBuffer) | Decompression | 2.549 GB/s |
| **Persistent** (MMAP) | **Decompression** | **6.486 GB/s** |
| **LZAV In-Memory** (Raw Ref) | Compression | 4.721 GB/s |
| | Decompression | 10.013 GB/s |
| **Sharded** (MMAP) | Random 4KB Read | 1.037 GB/s |
| | **Sequential 256KB Read** | **16.215 GB/s** |
## Usage
### C++ API
```cpp
#include "vark.h"
// Define implementation in one C++ file
#define VARK_IMPLEMENTATION
#include "vark.h"
Vark vark;
// Create a new archive
VarkCreateArchive( vark, "data.vark", VARK_WRITE );
// Append a file
VarkCompressAppendFile( vark, "file.txt" );
// Append a file with sharded compression (optimized for random access)
VarkCompressAppendFile( vark, "large_asset.dat", VARK_COMPRESS_SHARDED );
// Load an existing archive for reading
VarkLoadArchive( vark, "data.vark", VARK_MMAP );
// Decompress a full file
std::vector data;
VarkDecompressFile( vark, "file.txt", data );
// Partially decompress a sharded file (e.g., read 1KB at offset 512)
// This is significantly faster for large files as it only decodes necessary shards
VarkDecompressFileSharded( vark, "large_asset.dat", 512, 1024, data );
// Always close when done
VarkCloseArchive( vark );
```
#### Flags
| Flag | Description |
| --- | --- |
| `VARK_PERSISTENT_FP` | Keeps the file handle open between operations. Recommended for batch tasks. |
| `VARK_MMAP` | Uses Memory-Mapped I/O for zero-copy reads. Incompatible with `VARK_WRITE`. |
| `VARK_WRITE` | Enables write/append operations. Disables read operations. |
### CLI
```
Usage: vark [--help] [--version] [-c] [-cs] [-a] [-as] [-x] [-l] [-v] archive [files]...
A minimal LZAV archive tool for fast compression and decompression. Supports sharded compression for efficient random access to large files. Use without flags for smart mode: extracts existing archives or creates new ones automatically.
Positional arguments:
archive archive file path
files input files or directories [nargs: 0 or more]
Optional arguments:
-h, --help shows help message and exits
-v, --version prints version information and exits
-c Create archive
-cs Create archive (sharded compression)
-a Append to archive
-as Append to archive (sharded)
-x Extract archive
-l List archive contents
-v Verify archive integrity
Examples:
vark data.vark Extract archive (smart mode)
vark -c game.vark assets/ Create archive from directory
vark -cs textures.vark images/ Create with sharded compression
vark -a game.vark newfile.dat Append file to existing archive
vark -l game.vark List archive contents
```
## Build
Vark uses CMake for building.
```bash
# Configure the project
cmake -S . -B build
# Build the tool and tests
cmake --build build --config Release
# Run tests
ctest --test-dir build -C Release --output-on-failure
```
The build will produce `vark` (the CLI tool) and `vark_tests` (the test suite) in the build directory.
## License
Vark is released under the MIT License:
```
Copyright 2026 UAA Software
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
associated documentation files (the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge, publish, distribute,
sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial
portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
```