Skip to main content

Crate dream_archive

Crate dream_archive 

Source
Expand description

Pure-Rust library for Bethesda archive formats.

The top-level Archive facade is the ordinary entry point: detect an archive, list entries, look files up, open file-like readers, and extract them without first caring whether the container is BA2, TES3 BSA, or TES4 BSA. Format-specific modules remain available for archive metadata, hash-only BSA workflows, builder policy, and other places where the formats insist on being different (because of course they do).

Archive paths are byte strings. Bethesda archive formats do not reliably declare filename encodings, and older tools commonly wrote paths using the system code page of the machine that produced the archive. Keep archive lookup byte-first when possible. If accepting user-facing Unicode text, use the BSA filename helpers to encode that text explicitly before lookup rather than guessing a code page.

Every family matches a lookup path the same way, with dream_path’s normalization: \ and / are one separator, ASCII case is ignored, leading and repeated separators are dropped, and a trailing separator names a folder, so it matches no file. Archives that store no names hash the normalized path.

§Feature flags

The default feature set enables BA2 and BSA support. Individual format families can be selected with ba2, bsa-tes3, and bsa-tes4; bsa enables both BSA generations. parallel enables Rayon-backed bulk extraction paths.

The luau feature exposes the Luau bindings as an l3i extension through the luau module (dream.archive, module @dream/archive, type dream.archive.Archive). It enables BA2 and BSA support. The crate never creates a VM: the host composes luau::ArchiveExtension into a runtime plan and decides whether to expose the module as a global. lua is the old name of the same feature.

§Capability summary

  • BA2 GNRL: read, extract, and write.
  • BA2 DX10: read, extract by reconstructing DDS headers from archive texture metadata, and write from supported DDS files or explicit texture metadata plus raw texture payload bytes.
  • BA2 GNMF: Sony GNM (.gnf) texture metadata parsing only. Payload extraction/writing is intentionally out of scope for now because correct support requires console texture swizzle/unswizzle semantics, not a raw chunk dump.
  • TES3 BSA: read, extract, and write.
  • TES4 BSA: read, extract, and write for PC v103/v104/v105 archives, including compressed, hash-only, and embedded-name layouts.
  • Console/Xbox archive layouts and XMem compression are explicitly unsupported.

§Example

let archive = dream_archive::Archive::open_path("Data/SomeArchive.bsa")?;
for entry in archive.entries() {
    if let Some(path) = entry.path() {
        println!("{path}");
    }
}

let bytes = archive.read_file_required("textures/example.dds")?;
println!("extracted {} bytes", bytes.len());

let mut reader = archive.open_file_required("textures/example.dds")?;
let mut streamed = Vec::new();
std::io::Read::read_to_end(&mut reader, &mut streamed)?;

§Building archives

let mut builder = dream_archive::Tes3BsaBuilder::new();
builder.add_dir("Data")?;
builder.write_path("MyMod.bsa")?;
let mut builder = dream_archive::Tes4BsaBuilder::skyrim_le();
builder.add_dir("Data")?;
builder.write_path("MyMod.bsa")?;
let mut builder = dream_archive::Ba2Builder::new();
builder.set_compression(Some(dream_archive::ba2::Ba2CompressionFormat::Zip));
builder.add_dir("Data")?;
builder.write_path("MyMod.ba2")?;
let mut builder = dream_archive::Ba2Dx10Builder::new();
builder.add_dds_file("textures/example.dds", "example.dds")?;
builder.write_path("Textures.ba2")?;

Builder add_file / add_dir calls are deferred: they record source paths and sizes, then read payload bytes during write_path, write_seek, or to_vec. Use add_bytes when the payload is already in memory. Rewriters can preserve unchanged members with format-specific add_archive_entry methods and stable entry ids from entries_with_ids, avoiding the old “extract every preserved file into a Vec first” routine. That routine had all the elegance of swallowing a filing cabinet.

§Legacy BSA filename encodings

let encoded = dream_archive::bsa::encode_filename(
    "textures/zażółć.dds",
    dream_archive::bsa::FilenameEncoding::Windows1250,
)?;
assert_eq!(encoded.as_ref(), b"textures/za\xbf\xf3\xb3\xe6.dds");

§Luau bindings

Enable the luau feature and compose luau::ArchiveExtension into an l3i RuntimePlan:

use l3i::Runtime;
use l3i::extension::{RuntimePlan, RuntimePolicy};

let plan = RuntimePlan::builder()
    .policy(RuntimePolicy::new().compat_global("@dream/archive", "dreamArchive"))
    .extension(dream_archive::luau::ArchiveExtension)
    .finalize()?;
let runtime = Runtime::from_plan(&plan)?;
runtime.exec(r#"
    local builder = dreamArchive.ba2.Builder.new()
    builder:addBytes("meshes/example.nif", "payload")
    local archive = dreamArchive.openBytes(builder:toBytes())
    assert(archive:readFileRequired("meshes/example.nif") == "payload")
"#)?;

Lua strings are byte buffers for archive paths; payloads are Luau buffers or strings. Host filesystem paths are the explicit exception and must be valid UTF-8. Optional reads return nil for missing archive members; *Required methods raise Lua errors. See the luau module documentation for the full Lua-facing contract.

Re-exports§

pub use dream_path;
pub use flate2;
pub use dream_path::bstr;

Modules§

ba2
BA2 archive support.
bsa
BSA support shared by TES3/Morrowind and TES4-family archives.
luau
Luau bindings for dream_archive as an l3i extension: dream.archive, module @dream/archive, type dream.archive.Archive.

Structs§

BStr
A wrapper for &[u8] that provides convenient string oriented trait impls.
BString
A wrapper for Vec<u8> that provides convenient string oriented trait impls.
Copied
Makes a deep copy of the input in APIs that support owned data.

Enums§

Archive
Parsed archive opened through the top-level auto-detection facade.
BsaFormat
BSA archive generation detected by guess_format.
CompressionOverride
Per-file compression policy for archive builders.
Entries
Non-allocating iterator over entries in a top-level Archive.
Entry
Borrowed entry view returned by the top-level archive facade.
Error
Errors produced by top-level archive auto-detection operations.
FileFormat
Archive family detected by guess_format.

Traits§

ByteSlice
A trait that extends &[u8] with string oriented methods.
ByteVec
A trait that extends Vec<u8> with string oriented methods.

Functions§

detect_path
Detect the archive family of a filesystem path.
guess_format
Weak archive-family sniffing. This is not full validation, but it reads enough header bytes to distinguish BA2, TES3 BSA, and TES4+ BSA containers.

Type Aliases§

Ba2Builder
Ba2Dx10Builder
Result
Result type for top-level archive auto-detection operations.
Tes3BsaBuilder
Tes4BsaBuilder