Trait ModContentProvider

Source

pub trait ModContentProvider: Send + Sync {
    // Required methods
    fn mod_project(&mut self) -> Result<ModProject>;
    fn list_layer_wads(&mut self, layer: &str) -> Result<Vec<String>>;
    fn read_wad_overrides(
        &mut self,
        layer: &str,
        wad_name: &str,
    ) -> Result<Vec<(Utf8PathBuf, Vec<u8>)>>;
    fn read_wad_override_file(
        &mut self,
        layer: &str,
        wad_name: &str,
        rel_path: &Utf8Path,
    ) -> Result<Vec<u8>>;
    fn read_raw_override_file(&mut self, rel_path: &Utf8Path) -> Result<Vec<u8>>;

    // Provided methods
    fn read_raw_overrides(&mut self) -> Result<Vec<(Utf8PathBuf, Vec<u8>)>> { ... }
    fn content_fingerprint(&self) -> Result<Option<u64>> { ... }
}

Expand description

Abstracts how mod content is accessed during overlay building.

Implementors provide access to mod project metadata, layer structure, and WAD override data without prescribing how content is stored or read.

All mod WAD content is treated as overlays — individual file overrides that get patched on top of the original game WADs. There is no concept of full WAD replacement; every mod contributes individual chunks.

§Implementing

Implementations must be Send + Sync:

Send — the builder moves providers across threads.
Sync — content_fingerprint takes &self and may be called concurrently via par_iter(). This method should only read filesystem metadata (stat calls), so it should not require mutation.

Most content-reading methods still take &mut self to allow stateful readers (e.g., seeking within a ZIP archive). If an implementation needs interior mutability for content_fingerprint, it can use synchronization primitives like Mutex or RwLock.

The returned Vec<(PathBuf, Vec<u8>)> from read_wad_overrides uses paths that are resolved to u64 hashes by resolve_chunk_hash:

Named paths (e.g., data/characters/aatrox/skin0.bin) are hashed via ltk_modpkg::utils::hash_chunk_name.
Hex-hash filenames (e.g., 0123456789abcdef.bin) are parsed directly as u64 values. This is used by packed WAD content where original paths are lost.

Required Methods§

Source

fn mod_project(&mut self) -> Result<ModProject>

Return the mod’s project configuration.

This provides the mod name, version, description, author list, and — most importantly — the layer definitions that control how overrides are applied.

Source

fn list_layer_wads(&mut self, layer: &str) -> Result<Vec<String>>

List WAD targets that have override content in the given layer.

Returns WAD filenames such as "Aatrox.wad.client" or "Map11.wad.client". The builder uses these names to look up the corresponding game WAD via GameIndex::find_wad.

Source

fn read_wad_overrides( &mut self, layer: &str, wad_name: &str, ) -> Result<Vec<(Utf8PathBuf, Vec<u8>)>>

Read all override files for a WAD in a layer.

Returns (relative_path, file_bytes) pairs. The relative path is the file’s location within the WAD (e.g., data/characters/aatrox/skin0.bin), used to compute the chunk path hash. The bytes are the uncompressed file content that will replace the corresponding chunk in the game WAD.

Source

fn read_wad_override_file( &mut self, layer: &str, wad_name: &str, rel_path: &Utf8Path, ) -> Result<Vec<u8>>

Read a single override file from a WAD in a layer.

Used in pass 2 to re-read only the bytes needed for WADs being rebuilt, rather than loading all overrides into memory at once.

Source

fn read_raw_override_file(&mut self, rel_path: &Utf8Path) -> Result<Vec<u8>>

Read a single raw override file by its relative path.

Used in pass 2 to re-read only the bytes needed for WADs being rebuilt.

Provided Methods§

Source

fn read_raw_overrides(&mut self) -> Result<Vec<(Utf8PathBuf, Vec<u8>)>>

Read all RAW override files from the mod.

RAW overrides are files identified by their game asset path (e.g., assets/characters/aatrox/skin0.bin) rather than being pre-organized into WAD target directories. These files are routed to the correct WADs at overlay build time using the GameIndex hash lookup.

Returns (relative_path, file_bytes) pairs where the relative path is the game asset path used to compute the chunk path hash.

The default implementation returns an empty list.

Source

fn content_fingerprint(&self) -> Result<Option<u64>>

Compute a fingerprint that changes when any mod content changes.

Used by the metadata cache to detect stale entries. Returns None if the provider cannot efficiently compute a fingerprint (cache will be skipped for this mod).

Takes &self (not &mut self) because fingerprinting is a read-only operation and may be called in parallel across mods. Implementations should only inspect filesystem metadata (file sizes, modification times), not read file contents.

For filesystem providers: hash of (path, size, mtime) tuples. For archive providers: archive file size + mtime.