dream_archivetool

Inspect, extract, create and update Bethesda BSA and BA2 archives.

Bethesda's games keep their assets in archives: .bsa from Morrowind to Skyrim Special Edition, .ba2 from Fallout 4 on. dream_archivetool lists and checks what is inside one, extracts it, packs folders into new ones, and adds files to existing ones. Every name and every target is checked before anything is written, nothing you already have is replaced unless you say so, and an archive it cannot rewrite without losing something is refused before the file is touched. Every command that writes can print its plan first.

It is a command line, a Rust library, and a Luau extension that adds its operations to dream_archive's archives. dream_archive reads and writes the formats; this crate decides what is safe to do with them.

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

Download the build for your system from the releases: Windows, macOS, Linux, Android and PortMaster. Or build it:

cargo install dream_archivetool

dream_archivetool info Morrowind.bsa
dream_archivetool list --json Morrowind.bsa
dream_archivetool verify Morrowind.bsa --read-payloads
dream_archivetool extract Morrowind.bsa 'Icons\Tx_GoldIcon.dds' --output out
dream_archivetool extract-all Morrowind.bsa --output out --dry-run
dream_archivetool create MyMod.bsa MyMod --format tes3
dream_archivetool add MyMod.bsa MyModUpdate

[dependencies]
dream_archivetool = { version = "1", default-features = false }

use dream_archivetool::{ArchiveTool, ExtractAllOptions, OverwriteMode};

let options = ExtractAllOptions {
    output: Some("out".into()),
    overwrite: OverwriteMode::Skip,
    ..ExtractAllOptions::default()
};
let summary = ArchiveTool::extract_all("Morrowind.bsa", &options)?;

With the luau feature, dream_archivetool::luau::ArchivetoolExtension is an l3i extension providing the module @dream/archivetool and adding verify, diff, extract and the rest to every dream.archive.Archive. The host composes it with dream_archive's extension; the crate never creates a VM or installs a global.

• Start here: look inside an archive, take files out, pack a folder in
• Extracting and Creating and updating: what each command checks, writes and refuses
• Command line and JSON output
• Rust API, Luau API and Embedding Luau, including what changed from the 0.2 mlua binding
• Changelog

cargo fmt --check
cargo clippy --all-targets --all-features -- -W clippy::pedantic -D warnings
cargo test --all-features
cargo test --no-default-features
cargo doc --no-deps --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 in tests/luau_api.rs, so cargo test --features luau builds without it. cargo bench --bench archive_ops times the Rust operations and prints each one's peak heap growth; cargo bench --bench luau_boundary --features luau times frozen Luau scripts. docs/architecture.md says which layer owns what.

The site in content/ is a DreamWeave Mod Template site; preview it with zola serve.

Rust 1.88. dream_archivetool 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-or-later.

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