dream_archive 1.1.0

Pure-Rust Bethesda BA2 and BSA archive reader, extractor, and writer
Documentation

dream_archive

Read, extract and write Bethesda's BSA and BA2 archives in pure Rust, from Morrowind to Starfield.

One type opens all three generations: Morrowind's BSA, the TES4 BSA of Oblivion through Skyrim SE, and the BA2 of Fallout 4 and Starfield. The same calls list, look up, read, stream and extract any of them, and a builder writes each family it reads. Archive paths stay bytes, because the formats never say which code page their names are in; the crate converts only when you name one. With the luau feature, it is also an l3i extension providing the Luau module @dream/archive.

Documentation, including the full Rust and Luau API reference: https://dreamweave-mp.github.io/dream_archive/

Install

cargo add dream_archive

Rust 1.88. The default features read and write every family; parallel adds parallel extraction, and luau the Luau module.

Formats

Family Games Read and extract Write
TES3 BSA Morrowind yes yes
TES4 BSA, versions 103 to 105 Oblivion to Skyrim SE yes, including hash-only archives yes
BA2 GNRL Fallout 4, Fallout 76, Starfield yes yes
BA2 DX10 Fallout 4, Fallout 76, Starfield yes, as DDS files from DDS files or texture metadata
BA2 GNMF console textures metadata only no

Console layouts and XMem compression are refused with an error.

Usage

use dream_archive::Archive;

fn main() -> dream_archive::Result<()> {
    let archive = Archive::open_path("Morrowind.bsa")?;
    for entry in archive.entries().take(3) {
        if let Some(path) = entry.path() {
            println!("{path}");
        }
    }

    // Any spelling of the path: case and slash direction do not matter.
    let texture = archive.read_file_required("Textures/Tx_Wood.DDS")?;
    println!("{} bytes", texture.len());
    Ok(())
}
use dream_archive::Tes3BsaBuilder;

fn main() -> dream_archive::bsa::Result<()> {
    let mut builder = Tes3BsaBuilder::new();
    builder.add_dir("MyMod")?;
    builder.write_path("MyMod.bsa")?;
    Ok(())
}
local dreamArchive = require("@dream/archive")
local archive = dreamArchive.openPath("Morrowind.bsa")
local entry = archive:get("textures/tx_wood.dds")
print(entry.size, entry.hashHex)

For a command line, see dream_archivetool, which is built on this crate.

Where to read next

Development

cargo fmt --check
cargo clippy --all-targets --all-features -- -W clippy::pedantic -D warnings
cargo test --all-features

The luau feature needs l3i's toolchain, clang, lld and cross-language thin LTO, which .cargo/config.toml sets; the test-only luau-analysis feature adds l3i's analysis frontend for the typed tests, so cargo test --features luau builds without it. The site in content/ is a DreamWeave Mod Template site; preview it with zola serve.

License

dream_archive is licensed under either of MIT or Apache-2.0, at your option. Releases up to and including 1.0.0 were GPL-3.0-only.

Support

Has dream_archive been useful to you? Consider amplifying the signal through ko-fi.