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](https://github.com/DreamWeave-MP/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

```sh
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

```rust
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(())
}
```

```rust
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(())
}
```

```luau
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](https://DreamWeave-MP.github.io/dream_archivetool/),
which is built on this crate.

## Where to read next

- [Start here]https://dreamweave-mp.github.io/dream_archive/docs/start-here/: open, read,
  extract, build
- [Formats]https://dreamweave-mp.github.io/dream_archive/docs/formats/: versions, names,
  hashes, compression, and what is refused
- [Archive paths]https://dreamweave-mp.github.io/dream_archive/docs/paths/ and
  [hashes]https://dreamweave-mp.github.io/dream_archive/docs/hashes/: lookups, legacy code
  pages, and hash-only archives
- [Building archives]https://dreamweave-mp.github.io/dream_archive/docs/building/ and
  [BA2 textures]https://dreamweave-mp.github.io/dream_archive/docs/textures/
- [Embedding Luau]https://dreamweave-mp.github.io/dream_archive/docs/luau-hosts/: l3i setup, and
  moving from the 0.2 `mlua` binding
- [Rust API]https://dreamweave-mp.github.io/dream_archive/docs/api/ and
  [Luau API]https://dreamweave-mp.github.io/dream_archive/docs/luau/
- [Changelog]https://dreamweave-mp.github.io/dream_archive/home/changelog/

## Development

```sh
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](https://github.com/DreamWeave-MP/DreamWeave-Mod-Template) site; preview
it with `zola serve`.

## License

dream_archive is licensed under either of [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE), 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](https://ko-fi.com/magicaldave) through ko-fi.