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
XMemcompression 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_archiveas an l3i extension:dream.archive, module@dream/archive, typedream.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. - Compression
Override - 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.
- File
Format - Archive family detected by
guess_format.
Traits§
- Byte
Slice - 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
- Ba2Dx10
Builder - Result
- Result type for top-level archive auto-detection operations.
- Tes3
BsaBuilder - Tes4
BsaBuilder