using-bgs-archive

Using bgs-archive

bgs-archive is the agent-native CLI for Bethesda BA2/BSA archives. It detects archive family/version, lists entries, extracts assets, and packs supported BSA/BA2 outputs for MO2 overlay workflows.

Use this skill for:

• unpacking or extracting BA2/BSA assets;
• repacking supported BA2/BSA archives;
• inspecting archive contents, format, version, compression, or entry counts;
• preparing packed assets for a mod overlay.

Do not use it for plugin records (.esp/.esm/.esl) or load-order edits. Route those through xEdit / load-order skills.

Prerequisites — capability discovery first

Always query the live binary before choosing a game, format, or packing path:

bgs-archive --json capabilities
# Alias:
bgs-archive --json caps

Read the JSON envelope and branch on data.write_support and data.read_support. Do not assume DX10 or GNMF packing exists just because DX10/GNMF extraction works.

If bgs-archive is not on PATH, locate the GitHub Release-installed binary under:

~/.bgs-modding-superpowers/tools/bgs-archive/<version>/

or build from the source tree:

cd D:\awesome-bgs-mod-master\tools\bgs-archive
$env:PATH = "$env:USERPROFILE\.cargo\bin;$env:PATH"
cargo build --release
target\release\bgs-archive.exe --json capabilities

Hard rules

• Never write a packed archive into the game's Data folder or any Stock-Game tree.
• Pack output belongs in an MO2 mod overlay: <MO2_Root>/mods/<mod-name>/Data/....
• Extract and inspect archives freely, but keep extraction outputs in a workspace or overlay staging folder, not in game Data.
• DX10/GNMF pack is unsupported in this version. Extract works; packing returns unsupported.
• Use --json for agent workflows and branch on the envelope, not human text.

资产优先级判断 / Asset precedence judgment

Asset precedence is the runtime question "which asset bytes does the game actually read for this virtual path?" It is related to load order, but it is not the same layer as plugin-record conflict resolution.