Crate ltk_overlay 

WAD overlay builder for League of Legends mods.

This crate builds WAD overlay directories from a set of enabled mods. The overlay contains patched copies of game WAD files with mod content applied on top, which a patcher DLL can redirect the game to load instead of the originals.

How It Works

The overlay build process has four stages:

1. Indexing — Scan the game’s DATA/FINAL directory and mount every .wad.client file. Build two indexes:

   • Filename index: WAD filename (case-insensitive) -> filesystem paths
   • Hash index: chunk path hash (u64) -> list of WAD files containing it

2. Collecting overrides — For each enabled mod (in order), read its layer structure and WAD override files through the ModContentProvider trait. Each override file is resolved to a u64 path hash (either parsed from a hex filename or computed from the normalized path). All overrides are collected into a single HashMap<u64, Vec<u8>>. When multiple mods override the same hash, the first mod in the list (highest priority) wins.

3. Distributing to WADs — Using the hash index, each override is distributed to every game WAD that contains that path hash (“cross-WAD matching”). This means a single skin texture override will automatically be applied to both the champion WAD and any map WAD that shares the same asset.

4. Patching WADs — For each affected game WAD, a patched copy is built in the overlay directory. The patched WAD contains all original chunks plus the overrides, with optimizations for audio files (kept uncompressed) and chunk deduplication.

Content Provider Abstraction

Mod content is accessed through the ModContentProvider trait, which decouples the builder from any particular storage format. Implementations can read from:

• Filesystem directories (FsModContent)
• .modpkg archives (ModpkgContent)
• .fantome ZIP archives (FantomeContent)

Incremental Rebuild

After a successful build, an overlay.json state file is persisted (in the state directory) containing the list of enabled mod IDs, a game directory fingerprint, and per-WAD override fingerprints. On the next build:

• Exact match: mod list, game fingerprint, and all per-WAD fingerprints match, and every overlay WAD exists on disk — the build is skipped entirely.
• Incremental: game fingerprint matches but the mod list changed. Per-WAD override fingerprints are compared and only WADs whose inputs changed are re-patched. Stale WADs (no longer needed) are removed.
• Full rebuild: game fingerprint or state version changed — all overlay WADs are wiped and rebuilt from scratch.

The game index (GameIndex) is also cached to disk to avoid re-mounting every WAD file on subsequent builds when the game hasn’t been patched.

Example

use ltk_overlay::{OverlayBuilder, EnabledMod, FsModContent};
use camino::Utf8PathBuf;

let game_dir = Utf8PathBuf::from("C:/Riot Games/League of Legends/Game");
let profile_dir = Utf8PathBuf::from("C:/Users/.../profiles/default");
let overlay_root = profile_dir.join("overlay");

let mut builder = OverlayBuilder::new(game_dir, overlay_root, profile_dir)
    .with_progress(|progress| {
        println!("Stage: {:?}, Progress: {}/{}",
            progress.stage, progress.current, progress.total);
    });

builder.set_enabled_mods(vec![
    EnabledMod {
        id: "my-mod".to_string(),
        content: Box::new(FsModContent::new(Utf8PathBuf::from("/path/to/mod"))),
        enabled_layers: None,
    },
]);

let result = builder.build()?;
println!("Built {} WADs in {:?}", result.wads_built.len(), result.build_time);

Re-exports

pub use builder::EnabledMod;

pub use builder::ModWadReport;

pub use builder::OverlayBuildResult;

pub use builder::OverlayBuilder;

pub use builder::OverlayProgress;

pub use builder::OverlayStage;

pub use builder::BASE_LAYER_NAME;

pub use content::FsModContent;

pub use content::ModContentProvider;

pub use error::Error;

pub use error::Result;

pub use fantome_content::FantomeContent;

pub use game_index::GameIndex;

pub use modpkg_content::ModpkgContent;

pub use state::OverlayState;

Modules

builder

Main overlay builder implementation (two-pass architecture).

content

Mod content provider abstraction.

error

Error types for overlay operations.

fantome_content

Content provider for .fantome ZIP archives.

game_index

Game file indexing for WAD and chunk lookup.

meta_cache

Persistent metadata cache for the two-pass overlay builder.

modpkg_content

Content provider for .modpkg archives.

state

Overlay state persistence for build caching.

utils

Path normalization and hash resolution utilities.

wad_builder

WAD patching: applying mod overrides to game WAD files.