0.0.4 Parallel Extraction Fix

Fixes intermittent File exists errors when parallel extraction workers create a shared output folder. Existing checks against traversing symlinks and non-directory entries remain in place.

• Adds a regression test for concurrent extraction.
• Adds standalone CLI downloads for Windows and Linux: bsa-ba2-tool-cli-*. The existing GUI downloads remain available.
• Includes licenses and third-party notices in the downloads, with SHA256 checksums in SHA256SUMS.

0.0.3 Minor Fixes

Minor fixes to the GUI and CLI commands.

0.0.2 General Improvements

BSA flag support

BSA flags are now detected automatically from the files being packed.

Detection covers:

• Meshes
• Textures
• Sounds and music
• Voices
• Trees
• Fonts
• Menus and interface files
• Shaders
• Miscellaneous files

Runtime-sensitive flags are also applied:

• Mesh archives retain strings during startup.
• Script and sound archives retain filenames.
• Texture-only archives use embedded filenames.
• Skyrim SE omits the unsupported miscellaneous-content bit.
• The compressed flag reflects whether compression is actually enabled.

Unsafe combinations are rejected:

• Embedded filenames cannot be used in mixed-content archives.
• Skyrim SE texture archives using embedded filenames must be compressed.
• Oblivion-only content flags cannot be applied to later BSA versions.
• Required directory and filename-table flags cannot be disabled.

CLI flag commands

Running this by itself now lists every known BSA archive and content flag:

bsa-ba2-tool flags

To preview exactly which flags would be selected for a folder:

bsa-ba2-tool flags ./my_mod skyrimse

To preview an uncompressed archive:

bsa-ba2-tool flags ./my_mod skyrimse --no-compression

The catalog includes hexadecimal flag values, descriptions, and warnings for Xbox-only flags that are intentionally not exposed for PC archive creation.

GUI flag workflow

The GUI now has a Flags… dialog when creating BSA archives.

It provides:

• Live flag detection based on selected files
• Archive and content flag bitmasks
• Automatic detection by default
• Optional manual flag overrides
• Locked required name-table flags
• Validation messages for unsafe combinations
• Updates whenever file selection or target game changes

BSA flags do not appear as applicable when creating BA2 archives.

Large BSA handling

Classic BSA archives now use the xEdit-style signed 32-bit offset ceiling of 2,147,483,647 bytes as the engine-safe boundary.

Without splitting, the CLI warns before packing oversized input and checks the resulting archive afterward.

Automatic splitting is available with:

bsa-ba2-tool pack ./large_mod large_mod.bsa skyrimse --split

Split archives receive deterministic names:

large_mod.part001.bsa
large_mod.part002.bsa
large_mod.part003.bsa

The splitter:

• Groups files before archive creation
• Defaults to the BSA 2 GiB safety boundary
• Reserves space for archive metadata and filenames
• Uses a conservative loose-file-size estimate
• Checks the actual archive size afterward
• Never allows a BSA split target above the engine-safe boundary

A custom smaller target can be used:

bsa-ba2-tool pack ./large_mod large_mod.bsa skyrimse
--split
--split-size-mib 1900

Individual files cannot span multiple archive parts. If one file exceeds the chosen target, packing stops with an explanation.

Every generated part must be installed and registered appropriately through the game or mod manager.

Large BA2 handling

BA2 archives are not treated as having the classic BSA 2 GiB limit:

• BA2 archive offsets are 64-bit.
• Individual packed and unpacked chunk sizes remain 32-bit.
• General BA2 entries larger than the 32-bit chunk limit are rejected.

The default BA2 split target is 4 GiB. This is a practical distribution and older-tool compatibility target, not a confirmed game-engine hard limit.

bsa-ba2-tool pack ./large_data main.ba2 starfield-v3 general --split

Custom BA2 part sizes are supported:

bsa-ba2-tool pack ./large_data main.ba2 fo4-fo76 auto
--split
--split-size-mib 3072

Output names follow the same .part001.ba2 pattern.

Disk-backed BA2 packing

Large BA2 archives can now be created without holding the entire build in RAM:

bsa-ba2-tool pack ./large_data main.ba2 starfield-v3 general
--disk-backed

Disk-backed mode:

• Processes and stages one archive entry at a time
• Reduces peak memory use to roughly one input file’s working set
• Supports General and DX10 texture BA2 archives
• Supports the available compression choices
• Uses memory mapping when assembling staged output
• Requires temporary disk space roughly comparable to the resulting archive

Temporary files default beside the output archive. A different location can be selected:

bsa-ba2-tool pack ./large_data main.ba2 starfield-v3 general
--disk-backed
--temp-dir D:\BA2-Temp

Disk-backed mode currently applies only to BA2 archives.

Splitting and disk-backed packing can be combined:

bsa-ba2-tool pack ./large_data main.ba2 starfield-v3 general
--split
--disk-backed

GUI large-archive warnings

The GUI now calculates the total size of selected loose files before packing.

It displays a confirmation popup when:

• A BSA selection exceeds 2 GiB
• A BA2 selection exceeds 4 GiB

The BSA warning explains the potential engine failure/crash risk and shows an equivalent CLI --split command.

The BA2 warning explains that BA2 uses 64-bit offsets but recommends CLI splitting and disk-backed packing for compatibility and lower memory usage.

Important: the GUI warns and can continue creating one archive, but splitting and disk-backed operation are currently CLI features.

Compression options

The CLI now exposes:

--compression auto
--compression none
--compression zlib
--compression lz4

Unsupported format/codec combinations are rejected instead of producing an archive the target game cannot read.

LZ4 Fast and HC modes

LZ4 packing now supports two strategies:

--lz4-mode fast
--lz4-mode hc

HC remains the default.

Example:

bsa-ba2-tool pack ./data main.ba2 starfield-v3 general
--compression lz4
--lz4-mode hc

Faster packing:

bsa-ba2-tool pack ./data main.ba2 starfield-v3 general
--compression lz4
--lz4-mode fast

The distinction is:

• fast: faster archive creation, usually larger output
• hc: slower archive creation, usually smaller output
• Both have similarly fast decompression
• Both produce the same game-readable LZ4 format

These modes apply to:

• Skyrim SE LZ4-frame BSA
• Starfield v3 LZ4 BA2

They do not apply to Oblivion, Fallout 3/New Vegas, Skyrim LE, or Fallout 4-family archives because those use zlib.

CLI overhaul

The CLI was moved to Clap with structured commands, typed arguments, validation, aliases, examples, and command-specific help.

Commands are now:

extract
pack
flags
list
info

Older spellings remain available:

unpack
ls
inspect
detect-flags

Other improvements include:

• --help documentation
• --version support
• Validated game names
• Validated BA2 layouts
• Compression compatibility errors
• Better packing progress
• Better error messages and context
• Clear post-build size warnings

Archive information

The info command now reports more useful details:

bsa-ba2-tool info archive.bsa

Depending on the format, it displays:

• Archive format
• Format version
• File count
• Physical archive size
• Compression codec
• BSA archive flag bitmask
• BSA content flag bitmask
• Decoded flag names
• BSA 2 GiB safety status
• BA2 64-bit offset information
• BA2 32-bit chunk-size information
• BA2 string-table status

BA2 format selection

BA2 packing accepts:

auto
general
textures

auto selects DX10 only when every selected file is a DDS texture. Mixed content uses General BA2.

The GUI now exposes the same Auto, General, and Textures/DX10 selection.

Extraction safety

Archive extraction now validates output paths before writing.

Entries containing unsafe paths are rejected, including:

• Absolute paths
• Parent-directory traversal such as ../
• Paths that would escape the selected output directory

There is also a workaround for an LZ4 decompression problem in the current ba2 crate. LZ4 chunks are decoded into initialized buffers and their decoded sizes are validated before
reconstruction.

GUI workflow improvements

The GUI gained:

• Archive information display
• BA2 Auto/General/DX10 selection
• Live BSA flag inspection
• Manual validated BSA flag overrides
• Better progress-state handling
• More reliable cancellation-state handling
• Sorted folder scanning
• Large-archive confirmation dialogs
• Improved status and error messages
• Morrowind removed from packing targets because TES3 BSA writing is not supported

0.0.1 Initial Release

This is the first release of the BSA BA2 Handler. If there are any features you want me to add or take a look into adding let me know either in the discord or open up an issue or pull request.