Changelog

2.0.0 stable 2026-10-21

dream_archive is a Jess package, written in Luau; the Rust crate continues on the rust branch at 1.1.0.

Breaking changes

• The library is the Jess package org.dreamweave.dream-archive, module @dream-archive, installed with jess rather than Cargo. The Rust crate dream_archive stays at 1.1.0 on crates.io and on this repository's rust branch, and is no longer developed on main.

1.1.0 stable 2026-09-30

Relicensed as MIT OR Apache-2.0 and built on l3i 1.1.0.

Changed

• Relicensed from GPL-3.0 to MIT OR Apache-2.0: this is the first release under the new terms, and releases up to and including 1.0.0 stay GPL.
• Requires dream-path 1.1, its first MIT OR Apache-2.0 release.
• l3i 1.1.0 comes from crates.io; the @dream/archive module is unchanged.

1.0.0 stable 2026-09-29

First stable release: the Luau binding is an l3i extension providing @dream/archive, every archive family looks entries up by hash, and lookups and zlib reads allocate less.

Breaking changes

• The luau feature (lua is the old name of the same feature) binds the crate as an l3i extension, luau::ArchiveExtension, providing @dream/archive. dream_archive::lua, the mlua types and the standalone-lua feature are gone.
• Building with the luau feature needs l3i's toolchain: clang, lld and cross-language thin LTO.
• Every open* in Luau returns the one Archive type; archive:entries() is a view of entry handles, not a table of tables.
• Luau entry hashes are integers: entry.hash and entry.folderHash replace the old tables and fields, with hashHex and folderHashHex for the hex spelling. BA2 hashes are directoryHash, fileHash and extensionHash; sizes and offsets are size, storedSize and offset on every format.
• Luau integer arguments must be exact: readEntry(1.5) is an error instead of a rounded read.
• bsa::Error::InvalidFileRecordFlags is gone. Nothing returned it: both flag bits of a TES4 file record are read as the format defines them.

Added

• get_by_hash, get_id_by_hash and contains_hash on every archive family, get_id by path, and HashFields::from_numeric.
• archive:readInto(entry, buffer, offset) in Luau decodes a member straight into a buffer, and archive:getByHash and archive:containsHash take the family's hash shape.
• Luau type definitions for the whole module, checked by Luau's own type checker in the tests behind the luau-analysis feature.
• toBuffer() on every Luau builder; only ba2.Builder had it.
• dream_archive::flate2, the re-exported flate2 whose Compression set_zlib_level takes, so naming a zlib level needs no flate2 dependency of your own.

Changed

• Path lookups normalize into a stack buffer instead of allocating: contains over 4096 distinct paths takes 0.39 ms instead of 1.03 ms (TES3) and 1.43 ms (TES4).
• zlib members inflate from the archive through one inflater per thread: a 64 KiB TES4 member reads in 18 µs instead of 68 µs.
• Walking entries from Luau is 5 to 23 times faster than with mlua, and small calls such as contains and readEntry take about half as long: 4096 TES3 entries take 0.73 ms instead of 6.15 ms.
• dream-path 1.0 and l3i 1.0.0 come from crates.io; Rust 1.92.

Fixed

• Dx10Builder::add_dds_bytes and add_dds_file take DDS files whose depth field is 1, as many tools write for ordinary textures. A DDS file is a volume texture only when its flags have DDSD_DEPTH or its caps have DDSCAPS2_VOLUME.
• A cubemap's extended DX10 DDS header has an array size of 1, one cube, as the DDS format and DirectXTex count it: extraction wrote 6, which DirectXTex-based tools read as six cubes, and add_dds_bytes and add_dds_file refused cubemaps saved by texconv. Cubemaps extracted by earlier versions, which say 6 over one cube's data, are still accepted.
• Every family matches a lookup path the same way, with dream-path's normalization. BA2 lookups kept repeated separators and dropped a trailing one, so meshes//door.nif missed and meshes/door.nif/ found a member a BSA answered the other way round; hash-only TES4 lookups missed a//b/c.nif. Archives without names now hash the normalized path.
• Luau entry.name is the part of the path after its last separator in every family. For a BA2 entry it was the whole stored path, the same as entry.path.
• Luau entry.folder is "" for an entry at the root of a TES3 archive or a BA2, as it was for TES4, instead of nil; nil means the archive stores no names.
• The crate builds with only the ba2 feature: it now enables the lz4_flex feature its compressor needs, which only bsa-tes4 turned on before. Builds with one BSA family alone no longer carry dead code.

Migration

Compose dream_archive::luau::ArchiveExtension into the host's l3i RuntimePlan. A host that still wants the dreamArchive global adds RuntimePolicy::compat_global("@dream/archive", "dreamArchive"). That release's Embedding Luau page listed what scripts must change; the Luau port's documentation replaces it.

0.2.3 stable 2026-09-27

Fixed

• TES3 entry hashes are read low half first, so Entry::hash equals hash_file(path).0.numeric() for the same path.

0.2.2 stable 2026-09-26

Changed

• Rust 1.88, as mlua 0.12 requires.

Fixed

• Fallout 3's voice archives open: their file name block is padded with NUL bytes after the last name.

0.2.0 stable 2026-09-26

The Lua API runs on Luau, with camelCase names, and Oblivion's archives open.

Breaking changes

• The Lua bindings build against mlua 0.12; standalone-lua selects Luau instead of LuaJIT.
• Lua names are camelCase (dreamArchive.openPath, archive:readFileRequired), and so are enum values ("bsaTes4", "skyrimSe"); constants are UPPER_SNAKE.
• dream_path 0.2 and lz4_flex 0.14.

Fixed

• Oblivion's BSAs open. Their version 103 headers set the bit that means XMem compression from version 104 on; it is now ignored for 103, as OpenMW ignores it.

0.1.6 stable 2026-04-28

Added

• open_file, open_file_required and open_entry: a member as a std::io::Read, borrowed straight from the archive when it is stored uncompressed.

0.1.5 stable 2026-04-28

Added

• Dx10Builder::add_archive_entry copies a DX10 texture's header, chunk records and stored bytes unchanged, instead of rebuilding them.

0.1.1 stable 2026-04-27

Builders read files when they write, and can copy entries from an opened archive.

Breaking changes

• Builders write with write_seek, to any Write + Seek; write_to is gone.

Added

• add_archive_entry on every builder, and add_archive_entry_with_compression on the BA2 and TES4 builders: an entry of an opened archive of the same family, copied when the archive is written.
• Stable entry ids: entries_with_ids, entry_by_id, entry_by_id_required and extract_entry_by_id; extracted_len and extracted_len_by_id for BA2 and TES4.

Changed

• add_file and add_dir record each source's path and size and read it when the archive is written. A source that changed size in between fails the write.

0.1.2 stable 2026-04-27

Added

• dream_path is re-exported.

Changed

• The lua feature no longer picks a Lua runtime: the host chooses one through its own mlua. standalone-lua selects vendored LuaJIT.
• Rust 1.87.

0.1.4 stable 2026-04-27

Added

• A host can add its own Lua methods to the archive userdata: lua::LuaArchive with archive() and path(), create_module_with_archive_methods, register_archive_methods and add_archive_methods.

0.1.3 stable 2026-04-27

Changed

• bstr comes through dream_path and is re-exported as dream_archive::bstr; the crate no longer depends on it directly.

0.1.0 stable 2026-04-27

First release: read, extract and write BA2, TES3 BSA and TES4 BSA archives in pure Rust.

Added

• Archive, which detects the family of any supported archive and lists, reads and extracts it.
• BA2 GNRL and DX10 reading and extraction; DX10 textures come out as DDS files with headers rebuilt from the archive's metadata. GNMF archives are identified, not extracted.
• TES3 BSA reading, extraction and writing.
• TES4 BSA reading, extraction and writing for versions 103, 104 and 105: zlib and LZ4 frames, string tables, embedded names, and hash-only archives through extract_to_with_paths.
• BA2 GNRL writing, and DX10 writing from DDS files or from texture metadata and raw payloads.
• Legacy filename code pages: encode_filename, decode_filename_lossy and extract_to_with_encoding.
• Parallel extraction behind the parallel feature.
• Lua bindings through mlua and vendored LuaJIT, behind the lua feature.