Overview

Examples

#include <bsa/tes4.hpp>
#include <cstdio>
#include <filesystem>

int main()
{
    std::filesystem::path oblivion{ "path/to/oblivion" };
    bsa::tes4::archive bsa;
    const auto version = bsa.read(oblivion / "Data/Oblivion - Voices2.bsa");
    const auto file = bsa["sound/voice/oblivion.esm/imperial/m"]["testtoddquest_testtoddhappy_00027fa2_1.mp3"];
    if (file) {
        file->write(std::filesystem::path{ "happy.mp3" }, version);
    }
}

#include <bsa/tes4.hpp>
#include <cstddef>
#include <utility>

int main()
{
    const char payload[] = { "Hello world!\n" };
    bsa::tes4::file f;
    f.set_data({ reinterpret_cast<const std::byte*>(payload), sizeof(payload) - 1 });

    bsa::tes4::directory d;
    d.insert("hello.txt", std::move(f));

    bsa::tes4::archive archive;
    archive.insert("misc", std::move(d));
    archive.archive_flags(bsa::tes4::archive_flag::file_strings | bsa::tes4::archive_flag::directory_strings);
    archive.archive_types(bsa::tes4::archive_type::misc);

    archive.write("example.bsa", bsa::tes4::version::sse);
}

CMake Options

Integration

bsa uses CMake as its primary build system. Assuming that bsa and its dependencies have been installed to a place where CMake can find it, then using it in your project is as simple as:

find_package(bsa REQUIRED CONFIG)
target_link_libraries(${PROJECT_NAME} PUBLIC bsa::bsa)

XMem Codec

The xmem codec is a compression format available as part of the xbox development kit (XDK). This compression format is utilized only in TESV. archive.exe for TESV:SSE has this compression flag available, however it is unimplemented, and the game will simply use LZ4 instead. Support for this format is very difficult due to its proprietary nature, however there exists an implementation of the format as part of the XNA framework, which is freely available, albeit as a 32-bit binary. Thus, support for this format is only available on Windows, and requires users to opt into it via the BSA_SUPPORT_XMEM CMake option. Additionally, users must build the xmem support proxy separately, and bundle the resulting binary with their own.

Important Notes

• If the hash of one file compares equal to the hash of another file, then they are equal. It doesn't matter if they have different file names, or if they store different data blobs. The game engine uniquely identifies file's based on their hash alone.
• UTF-8 inputs are not well formed. The game engine has a crippling bug where extended ascii characters can index out-of-bounds, producing unreproducible hashes. It is the user's job to ensure they aren't attempting to store paths which contain such characters. The game engine will accept them, but it will never be able to reproducibly locate them.
• The game engine normalizes paths to use the \ character instead of the standard /. As such, users should be aware that file paths retrieved from the virtual file system may not constitute valid paths on their native file system.
• Avoid writing file paths which are close to the limit of MAX_PATH. Bethesda uses fixed buffers everywhere with no input validation, so they will most likely crash the game.
• Make sure to lexically normalize your paths before you pass them. Bethesda uses really basic path splitting methods, and bsa replicates them.
• Files can not be split into more than 4 chunks inside a ba2. Bethesda uses a fixed buffer to store the chunks, and exceeding that limit will likely crash the game.

Dependencies

Alternatives

• C#
  • BSA Browser
  • Oblivion Mod Manager
  • Wabbajack
• C++
  • Bethesda Archive Extractor (no source)
  • BSAopt
  • BSAPACK
  • Cathedral Assets Optimizer
  • DDSopt
  • Fallout 4 Tools
  • Libbsa
  • Mod Organizer 2
• Java
  • FO3 Archive Utility (no source)
• Javascript
  • bsa
• Pascal
  • BSArch
• Python
  • Bethesda Structs
  • Wrye Bash
• Unknown
  • BSA Commander (no source)
  • BSA Unpacker (no source)
  • TES4BSA (no source)