Archives

esx reads, checks, extracts and packs these formats:

Game	Format
Morrowind	TES3 BSA
Oblivion, Fallout 3, Skyrim	BSA 103, 104 and 105
Fallout 4	GNRL and DX10 BA2, versions 1, 7 and 8
Starfield	GNRL and DX10 BA2, versions 2 and 3

Inspect

esx archive info 'MyMod - Main.ba2'
esx archive list 'MyMod - Main.ba2' --pattern '*.dds'
esx archive check 'MyMod - Main.ba2'

check decompresses every entry and reports corrupt entries with their offsets.

Extract

esx archive extract 'MyMod - Main.ba2' -o extracted

DX10 entries become complete DDS files. Use --overwrite to replace existing files. Extraction rejects parent traversal, duplicate targets and symlinked directories. A corrupt entry can stop a full extraction after earlier files are written.

Pack

esx archive pack ./assets -o 'MyMod - Main.ba2'
esx archive pack ./assets -o 'MyMod - Textures.ba2' --archive-format fo4-dds

Choose the format with --archive-format. The values are fo4-dds, tes3, tes4, fo3, sse, sf and sf-dds. esx skips plugin, archive and executable files. It publishes the output after all inputs pack without error.

To pack one Fallout 4 directory into the two archives of a mod, give --textures-output:

esx archive pack ./Data -o 'MyMod - Main.ba2' --textures-output 'MyMod - Textures.ba2' --share-data

DDS files go to the DX10 archive at --textures-output. Other assets go to the archive at -o. esx finishes packing both archives before publication starts. A packing error publishes neither. If an archive would be empty, esx skips it and warns with ARCHIVE_EMPTY.

--include and --exclude select files by path. You can repeat each option:

esx archive pack ./Data -o 'MyMod - Main.ba2' --include 'Meshes/' --include '*.bgsm' --exclude '*.txt'

A file must match an --include pattern, if supplied, and no --exclude pattern. Patterns ignore letter case and accept / and \. Without * or ?, a pattern is a path prefix. With wildcards, it must match the full path. * also matches separators.

With --file-list, esx validates the list before filtering it. Directory scans skip excluded files without checking them. This lets --exclude omit files that esx cannot pack, such as a file in the directory root.

Option	Use
--textures-output FILE	Pack the DDS files into a second, DX10 archive. Fallout 4 only.
--include GLOB, --exclude GLOB	Select files by path prefix or glob.
--share-data	Reuse identical payloads.
--split-size BYTES	Write numbered parts. One asset larger than the limit stays whole.
--archive-flags, --file-flags	Set BSA flags. Use decimal or 0xHEX.
--max-chunks, --single-mip-width, --single-mip-height	Control texture chunks.
--target xbox	Pack tiled Xbox DDS files. The output name must end in _xbox.ba2.

DX10 textures and SSE textures with embedded names always use compression.

Folder names with different letter case

The game reads Meshes/actors and Meshes/Actors as one folder. A Linux directory can contain both. Directory scans warn with ARCHIVE_PATH_CASE and name both paths. With --file-list, esx rejects a path below such a folder and names both spellings. Move the files into one folder and remove the other.

Paths in a mesh

A Fallout 4 mesh (NIF) has texture paths, material names and other file paths. nif show lists the fields that esx can edit. Use --asset-kind to see the fields of one kind only. The kinds are texture, material and mesh:

esx nif show Gun.nif --asset-kind texture

nif set changes fields. One call can make many edits. Repeat --edit FIELD=VALUE, or give --edits FILE with a JSON list of {"field": ..., "value": ...} objects:

esx nif set Gun.nif \
  --edit 'blocks/9/BSShaderTextureSet/Textures/0=Textures/Gun/Gun_d.dds' \
  --edit 'blocks/9/BSShaderTextureSet/Textures/1=Textures/Gun/Gun_n.dds' -o Fixed.nif

If one edit fails, esx writes no file.

nif set-paths changes path fields by rule. Use it when many fields have the same incorrect folder name:

esx nif set-paths Gun.nif --replace 'textures/OldMod/=textures/NewMod/' --asset-kind texture -o Fixed.nif --dry-run

Each --replace FROM=TO rule replaces FROM with TO in each path field, or in the fields of the --asset-kind that you give. FROM ignores letter case, and / and \ are equal. esx writes TO as you give it. The report lists each changed field with its value before and after. With --dry-run, esx writes no file.

Check a release

release check checks a plugin and its packaged assets, then combines the results in one report:

esx --data '/path/to/Fallout 4/Data' release check release/MyMod.esp

Section	Check
roundtrip	debug roundtrip: each record encodes to its bytes.
plugin_check	plugin check: unresolved FormIDs, wrong reference types and decoding errors.
archive_check	archive check on each archive: each entry reads and decompresses.
assets	plugin assets --recursive --include-companions: each asset of the plugin resolves.
behavior_verify	behavior verify: each file of the behavior build is in the release with the same bytes.

Without --archive, esx uses MyMod - Main.ba2 and MyMod - Textures.ba2 in the folder of the plugin, when they exist. The behavior check runs when behavior.lock.json is in the folder of the plugin, or when you give --behavior-lock FILE. Without a lock, the section says that esx skipped the check.

Each section has an issues count and the report of its command. The assets and behavior_verify sections list only the items that have a problem. The top-level issues value is the total. When the total is not 0, the exit code is 7 and the report is in error.details.

Find assets

A resource lookup searches loose files and archives together. Loose files in --data win. Between archives, a later archive wins.

esx resource where 'strings/MyMod_en.STRINGS' --data ./Data --archive 'MyMod - Main.ba2'
esx resource list --data ./Data --pattern 'strings/*'
esx resource extract 'meshes/example.nif' --archive 'MyMod - Main.ba2' -o example.nif

resource where lists every copy, with the highest priority first.

plugin assets MyMod.esp --recursive --fail-on-missing checks record paths and mesh/material dependencies. Sound records can name a .wav file while the archive contains its compiled .xwm. The scan tries the XWM when no WAV exists, and plugin collect-assets copies it with its actual extension. IDLE animation queries with $(Subgraph), * or ? depend on the selected animation context and are excluded from the literal-file scan. Concrete IDLE filenames are still checked.