skyrim-save

name	skyrim-save
description	Read and scan Skyrim save files (.ess). Use when debugging save issues, searching for orphaned scripts, checking mod footprint in saves, or investigating save bloat.
paths	**/*.ess

Save File Analysis

Use scripts/read-save.py to decompress and scan Skyrim save files. Requires Python with lz4 package (pip install lz4). All output is JSON.

Commands

Get save info (player name, level, location, plugin count):

python scripts/read-save.py info "<path-to-save.ess>"

List all plugins in the save:

python scripts/read-save.py plugins "<path-to-save.ess>"

Search for a string (script names, EditorIDs, variable names):

python scripts/read-save.py search "<save.ess>" --string "MyModScriptName"

Search for a FormID (as hex, little-endian uint32):

python scripts/read-save.py search "<save.ess>" --formid 0x0001ABCD

Search for a raw hex byte pattern:

python scripts/read-save.py search "<save.ess>" --hex "DEADBEEF"

Common Debugging Use Cases

• Orphaned scripts: Search for a script name from a removed mod. If it still appears, the save has orphaned instances.
• Effect accumulation: Search for a spell's FormID and count occurrences. More than expected = stacking bug.
• Mod footprint: Search for a mod's prefix (e.g., "MyMod_") to see how many references it left in the save.
• Save bloat: Compare decompressedSize across saves to detect growth over time.

Save File Structure

SSE/VR saves use LZ4 compression. General layout of the decompressed data:

• 0-100KB: Header, plugin list, screenshot
• 100KB-~22MB: Global data tables, ChangeForms (binary)
• ~22MB+: Papyrus string table, script instances, FormID arrays

Limitations

• Read-only — cannot edit or write back valid saves
• Binary search only — cannot parse structured Papyrus instance data (variable values, active effect state)
• For structured save editing, use ReSaver (Java GUI)