ltk_modpkg

A Rust library for reading, writing, and packing .modpkg archives, the binary mod distribution format for League of Legends mods in the League Mod Toolkit.

Overview

A .modpkg file is a binary container that stores mod content organized by layers and WAD targets, with per-chunk zstd compression, xxhash checksums, and embedded metadata (name, version, authors, license, thumbnail, etc.).

This crate provides:

Reading: mount a modpkg from any Read + Seek source and access chunks by path hash
Writing: build a modpkg from scratch using ModpkgBuilder
Extraction: extract modpkg contents back to disk
Metadata: read/write msgpack-encoded mod metadata

Packing a mod project directory into a modpkg lives in the ltk_mod_project crate (its modpkg cargo feature), whose ModpkgFormat backend drives ModpkgBuilder from here.

Usage

Reading a modpkg

use ltk_modpkg::Modpkg;
use std::fs::File;

let file = File::open("my-mod_1.0.0.modpkg")?;
let mut modpkg = Modpkg::mount_from_reader(file)?;

// Read metadata
let metadata = modpkg.load_metadata()?;
println!("{} v{}", metadata.name, metadata.version);

// List WADs
for wad_name in modpkg.wads.values() {
    println!("WAD: {wad_name}");
}

Packing a mod project

Project packing lives in ltk_mod_project behind its modpkg feature. The format-neutral ProjectPacker scans the project; ModpkgFormat encodes it:

use ltk_mod_project::modpkg::ModpkgFormat;
use ltk_mod_project::ProjectPacker;

// Loads mod.config.json/toml automatically from the project directory
let packer = ProjectPacker::from_dir("my-mod")?;
let file = std::fs::File::create("build/my-mod_1.0.0.modpkg")?;
packer.pack(ModpkgFormat::new(file))?;

Building a modpkg programmatically

use ltk_modpkg::builder::{ModpkgBuilder, ModpkgChunkBuilder, ModpkgLayerBuilder};
use ltk_modpkg::ModpkgCompression;

let builder = ModpkgBuilder::default()
    .with_layer(ModpkgLayerBuilder::base())
    .with_chunk(
        ModpkgChunkBuilder::new()
            .with_path("data/characters/graves/skin0.bin")
            .unwrap()
            .with_compression(ModpkgCompression::Zstd)
            .with_layer("base")
            .with_wad("Graves.wad.client"),
    );

let mut output = std::fs::File::create("out.modpkg")?;
builder.build_to_writer(&mut output, |chunk, cursor| {
    // provide raw chunk data here
    Ok(())
})?;

Project structure

The expected mod project layout (used by ltk_mod_project's ProjectPacker):

my-mod/
├── mod.config.json             # or mod.config.toml
├── README.md                   # optional, embedded in modpkg
├── thumbnail.webp              # optional, embedded in modpkg
├── content/
│   ├── base/                   # base layer (priority 0)
│   │   ├── Graves.wad.client/  # WAD target directory
│   │   │   ├── data/
│   │   │   └── assets/
│   │   └── Map11.wad.client/
│   │       └── data/
│   └── high-res/               # additional layer
│       └── Graves.wad.client/
│           └── assets/
└── build/                      # output directory

License

Apache-2.0

ltk_modpkg 0.12.0