Borderlands 4 Save Utility

A TypeScript-based web tool to decrypt and encrypt Borderlands 4 save files for editing, with advanced item serial analysis and reverse engineering documentation. 100% client-side - your save files never leave your computer!

If you find this tool helpful, please consider giving it a ⭐!

🌐 Web Version

Use the tool directly in your browser with drag-and-drop file upload.

• Try it locally: cd web && npm install && npm run dev
• Deploy your own: See web/README.md for deployment instructions
• 100% client-side - Your save files never leave your computer
• TypeScript implementation - Full source code available

View Web Version Documentation →

📊 Item Serial Research

Extensive reverse engineering has been performed on Borderlands 4's item serial format:

🔍 What We've Discovered

• Serial Structure: @Ug + type + base_weapon_id (6-7 bytes) + part_data (variable)
• Base Weapon Identification: Legendary weapons have unique 6-7 byte signatures
• Part-Based Stats: Damage, DPS, and reload time calculated from weapon parts, not stored directly
• Level Editing: Confirmed for type 'd' shotguns (byte 33)
• Weapon Cloning: Copy serials to duplicate exact weapons

📚 Research Documentation

• SERIAL_FORMAT.md - Complete serial format specification
• DEEP_ANALYSIS.md - Comprehensive reverse engineering analysis
• WEAPON_STATS.md - Quick reference for all analyzed weapons
• RESEARCH_SUMMARY.md - Executive summary of findings
• ASSET_EXTRACTION_GUIDE.md - Guide to extract game assets for further research

🎯 Current Capabilities

✅ What Works:

• Decrypt/encrypt save files
• Decode item serials
• Identify weapon types and base weapon IDs
• Clone existing weapons (copy serial)
• Modify level for type 'd' shotguns
• Compare weapon variants byte-by-byte

❌ What Doesn't Work (Yet):

• Generate new weapons from scratch (requires game asset extraction)
• Modify display stats (damage, magazine, etc.) - calculated by game
• Swap specific weapon parts - structure unknown without part tables

⚠️ Important Notes

ONLY STEAM SAVES SUPPORTED

• Backup your save files before using this tool
• Your Steam ID is the 17-digit number that starts with 7656119...
• On Windows: C:\Users\{username}\Documents\My Games\Borderlands 4\Saved\SaveGames - folder name is your Steam ID
• The Steam ID MUST match the original save file owner
• If you get PKCS7 or zlib errors, verify your Steam ID is correct

Save File Types

• #.sav (1.sav, 2.sav, etc.) - Character progress, inventory, level
• Profile.sav - Cosmetics, unlocks, account-wide settings

Weapon Editing Limitations

Based on reverse engineering research:

• ✅ Weapon cloning: Copy item serials to duplicate weapons (100% reliable)
• ✅ Level editing: Works for type 'd' shotguns (byte 33)
• ❌ Stat editing: Display stats calculated from parts (cannot directly modify)
• ❌ Part swapping: Part structure unknown (requires game asset extraction)

Recommendation: To get desired weapons, clone serials from existing items rather than attempting stat modification.

🛠️ Development

cd web
npm install
npm run dev          # Start development server
npm test            # Run tests
npm run build       # Build for production

🤝 Contributing

Contributions welcome! Areas that need work:

1. More weapon serial samples (especially common/uncommon items)
2. Same weapon at different levels (to isolate level encoding)
3. Game asset extraction (part definition tables)
4. Stat calculation formulas

Open an issue or PR if you have findings to share!

License

MIT License

Copyright (c) 2025

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.