README-saves.md

Borderlands 3 Commandline Savegame Editor - Savegame Editing Reference

This is the documentation for the save editing portions of the BL3 CLI Savegame Editor. For general app information, installation, upgrade procedures, and other information, please see the main README file.

These docs will assume that you've installed via pip3 - if you're using a Github checkout, substitute the commands as appropriate. The equivalent commands will be:

python -m bl3save.cli_edit -h
python -m bl3save.cli_info -h
python -m bl3save.cli_import_protobuf -h
python -m bl3save.cli_import_json -h
python -m bl3save.cli_archive -h

Table of Contents

• Basic Operation
• Output Formats
• Modifying the Savegame
  • Character Name
  • Save Game ID
  • Save Game GUID
  • Guardian Rank
  • Character Level
  • Mayhem Level
  • Mayhem Random Seed
  • Currency (Money and Eridium)
  • Takedown Discovery Missions
  • Mission Deletion
  • Seasonal Event Status
  • Item Levels
  • Item Mayhem Levels
  • Wipe Inventory
  • Unlocks
    • Ammo/Backpack Unlocks
    • Eridian Resonator
    • Eridian Analyzer
    • Inventory Slots
    • Vehicles
    • Vehicle Skins
    • TVHM
    • Eridian Cube Puzzle
    • All Unlocks at Once
  • Copy Playthrough States
    • NVHM to TVHM
    • TVHM to NVHM
  • "Un-Finish" NVHM
  • Import Items
• Importing Raw Protobufs
• Importing JSON
• Savegame Info Usage
  • Items/Inventory
  • Fast Travel Stations
  • Challenges
  • Missions

Basic Operation

At its most basic, you can run the editor with only an input and output file, and it will simply load and then re-encode the savegame. For instance, in this example, old.sav and new.sav will be identical as far as BL3 is concerned:

bl3-save-edit old.sav new.sav

If new.sav exists, the utility will prompt you if you want to overwrite it. If you want to force the utility to overwrite without asking, use the -f/--force option:

bl3-save-edit old.sav new.sav -f

As the app processes files, it will output exactly what it's doing. If you prefer to have silent output (unless there's an error), such as if you're using this to process a group of files in a loop, you can use the -q/--quiet option:

bl3-save-edit old.sav new.sav -q

Note that currently, the app will refuse to overwrite the same file that you're editing. You'll need to move/rename the new.sav over the original, if you want it to replace your current save. Be sure to keep backups!

Output Formats

The editor can output files in a few different formats, and you can specify the format using the -o/--output option, like so:

bl3-save-edit old.sav new.sav -o savegame
bl3-save-edit old.sav new.pbraw -o protobuf
bl3-save-edit old.sav new.json -o json
bl3-save-edit old.sav new.txt -o items

• savegame - This is the default, if you don't specify an output format. It will save the game like a valid BL3 savegame. This will likely be your most commonly-used option.
• protobuf - This will write out the raw, unencrypted Protobuf entries contained in the savegame, which might be useful if you want to look at them with a Protobuf viewer of some sort (such as this one), or to make hand edits of your own. Raw protobuf files can be imported back into savegames using the separate bl3-save-import-protobuf command, whose docs you can find near the bottom of this README.
• json - Alternatively, this will write out the raw protobufs as encoded into JSON. Like the protobuf output, you should be able to edit this by hand and then re-import using the bl3-save-import-json utility. NOTE: JSON import is not super well-tested yet, so keep backups!
• items - This will output a text file containing item codes which can be read back in to other savegames. It uses a format similar to the item codes used by Gibbed's BL2/TPS editors. (It will probably be identical to the codes used by Gibbed's BL3 editor, once that is released, but time will tell on that front.)
  • You can optionally specify the --csv flag to output a CSV file instead of "regular" text file. The first column will be the item names, the second will be the item codes.

Keep in mind that when saving in items format, basically all of the other CLI arguments are pointless, since the app will only save out the items textfile.

Modifying the Savegame

Here's a list of all the edits you can make to the savegame. You can specify as many of these as you want on the commandline, to process multiple changes at once.

Character Name

This can be done with the --name option:

bl3-save-edit old.sav new.sav --name "Gregor Samsa"

Save Game ID

Like with BL2/TPS, I suspect that this ID isn't at all important, but the editor can set it anyway with the --save-game-id option. BL3 itself sets the savegame ID to match the filename of the savegame, if interpreted as a hex value (so 10.sav would have an ID of 16).

bl3-save-edit old.sav new.sav --save-game-id 2

Save Game GUID

This is another identifier I suspect isn't actually important at all, but there's an internal GUID which can be used to identify savegames uniquely. The --randomize-guid option will randomize this value, so if you're copying a character or something you can ensure that the value is different between them. As I say, I have no idea if that's ever actually important (I've copied characters many times without randomizing this value, and they've worked fine) but here's the option anyway:

bl3-save-edit old.sav new.sav --randomize-guid

Guardian Rank

Guardian Rank can be zeroed out using the --zero-guardian-rank argument. This is useful when a savegame gets out of sync from your profile, such as if you download a savegame from the internet, or if you're making changes to values in your profile. After zeroing out the Guardian Rank in a savegame, the next time the character is loaded into the game, it will inherit the main profile's Guardian Rank.

bl3-save-edit old.sav new.sav --zero-guardian-rank

Character Level

You can set your character to a specific level using --level <num>, or to the max level allowed by the game using --level-max

bl3-save-edit old.sav new.sav --level 20
bl3-save-edit old.sav new.sav --level-max

Mayhem Level

This is only really useful before you've got Mayhem Mode unlocked. You can use the --mayhem argument to activate Mayhem mode even from the very beginning of the game. Note that you still won't have access to the Mayhem console on Sanctuary until it's properly unlocked by the game, so this will be the only way of changing Mayhem mode until that point in the game. This will set the Mayhem level for all playthroughs found in the game.

bl3-save-edit old.sav new.sav --mayhem 10

Note that in order to have Anointments drop while playing in Normal mode, your savegame does need to have THVM unlocked, so see the --unlock docs below for how to do that.

Mayhem Random Seed

The active modifiers in Mayhem Mode are all generated using a single random seed which is specified on a per-playthrough basis. If you have a set of Mayhem modifiers you like, you can take that seed (shown in the bl3-save-info output) and set it onto another save using the --mayhem-seed argument:

bl3-save-edit old.sav new.save --mayhem-seed -3938591

The seeds may be positive or negative, and can range up to 2 billion or so, both negative and positive. Note that if Gearbox changes the pool of available Mayhem modifiers, such as by disabling some, or adding new ones, the random seeds you're used to will start to give a different result, so you may have to reroll a bunch to find your favorite set, again.

Currency (Money and Eridium)

Money and Eridium can be set with the --money and --eridium arguments, respectively:

bl3-save-edit old.sav new.sav --money 20000000
bl3-save-edit old.sav new.sav --eridium 10000

Takedown Discovery Missions

You can clear out the two Takedown Discovery missions using the --clear-takedowns argument, if you have a character who you don't ever plan to do Takedowns with, but want those mission-pickup notifications gone, without going through the hassle of travelling to the Takedown maps yourself:

bl3-save-edit old.sav new.sav --clear-takedowns

Note that if you decide to do the Takedowns later, you'll have to pilot Sanctuary over to their pickup points before they'll appear in your Fast Travel menu; this argument doesn't unlock the Fast Travel locations itself.

Obviously it doesn't take long to just do the Discovery missions yourself; you can always just fail out of the Takedown itself by fast-travelling out of the map, but this option would save you a minute or two, anyway.

Mission Deletion

If you ever have a sidemission lock up, or just want to repeat a side mission, the --delete-pt1-mission and --delete-pt2-mission arguments can be used to delete the mission from your savegame so it can be picked up again. Note that this will only work for side missions. Plot missions aren't picked up at will like side missions are, and deleting plot missions will basically lock your character out of the rest of the game.

The pt1 argument corresponds to the first playthrough (Normal/NVHM), and the pt2 argument corresponds to the second playthrough (TVHM). To use this argument, you'll need to know the full object path to the mission you want to delete. This can be found using bl3-save-info --mission-paths. Docs for that function can be found here.

bl3-save-edit old.sav new.sav --delete-pt1-mission /Game/Missions/Side/Zone_0/Prologue/Mission_UnderwearTink.Mission_UnderwearTink_C
bl3-save-edit old.sav new.sav --delete-pt2-mission /Game/Missions/Side/Zone_0/Prologue/Mission_UnderwearTink.Mission_UnderwearTink_C

The --delete-pt1-mission and --delete-pt2-mission arguments can be specified more than once if you'd like to delete more than one mission at a time.

Seasonal Event Status

There are a few options available to clear out seasonal event challenge status (Bloody Harvest, Broken Hearts, and Revenge of the Cartels). This will allow you to go through the challenge ranks as if you'd not played the event yet. This is admittedly a bit silly, but it might be useful when paired with the Event Rewards mods, which let you use challenge rewards from the previous years.

To clear out the event challenge statuses individually:

bl3-save-edit old.sav new.sav --clear-bloody-harvest
bl3-save-edit old.sav new.sav --clear-broken-hearts
bl3-save-edit old.sav new.sav --clear-cartels

Or, you can do all three at once:

bl3-save-edit old.sav new.sav --clear-all-events

Item Levels

There are two arguments to set item levels. The first is to set all items/weapons in your inventory to match your character's level. If you're also changing your character's level at the same time, items/weapons will get that new level. This can be done with --items-to-char

bl3-save-edit old.sav new.sav --items-to-char

Alternatively, you can set an explicit level using --item-levels

bl3-save-edit old.sav new.sav --item-levels 57

Item Mayhem Levels

There are two arguments to set item mayhem levels. The first is to set all weapons to the maximum mayhem level, which is currently 10, using --item-mayhem-max. Note that currently only weapons and grenades can have Mayhem applied; other items will end up generating a message like <num> were unable to be levelled.

bl3-save-edit old.sav new.sav --item-mayhem-max

Alternatively, you can specify a specific Mayhem level with --item-mayhem-levels:

bl3-save-edit old.sav new.sav --item-mayhem-levels 5

To remove Mayhem levels from weapons/greandes entirely, specify 0 for --item-mayhem-levels.

Wipe Inventory

Inventory can be wiped entirely using the --wipe-inventory argument:

bl3-save-edit old.sav new.sav --wipe-inventory

This will happen prior to any item imports (see below), so you can wipe the inventory and import in the same command (and then use the above levelling commands to alter the gear after import).

Unlocks

There are a number of things you can unlock with the utility, all specified using the --unlock argument. You can specify this multiple times on the commandline, to unlock more than one thing at once, like so:

bl3-save-edit old.sav new.sav --unlock ammo --unlock backpack

Ammo/Backpack Unlocks

The ammo and backpack unlocks will give you the maximum number of SDUs for all ammo types, and your backpack space, respectively. The ammo SDU unlock will also fill your ammo reserves.

bl3-save-edit old.sav new.sav --unlock ammo
bl3-save-edit old.sav new.sav --unlock backpack

Eridian Resonator

The resonator unlock is what allows you to crack open Eridium deposits throughout the game. You ordinarily receive this as a reward for the plot mission "Beneath the Meridian."

bl3-save-edit old.sav new.sav --unlock resonator

Eridian Analyzer

Likewise, the analyzer unlock is what allows you to decode the Eridian writings scattered throughout BL3. You ordinarily receive this ability during the plot mission "The Great Vault."

bl3-save-edit old.sav new.sav --unlock analyzer

Inventory Slots

You can use the gunslots, artifactslot, and comslot unlocks to activate the inventory slots which are ordinarily locked until certain points in the game. You can also use the allslots to unlock all of them at once, rather than having to specify three unlocks.

bl3-save-edit old.sav new.sav --unlock gunslots
bl3-save-edit old.sav new.sav --unlock comslot
bl3-save-edit old.sav new.sav --unlock artifactslot

Or:

bl3-save-edit old.sav new.sav --unlock allslots

Vehicles

You can use the vehicles unlock to unlock all vehicles and vehicle parts. Note that this does not prematurely unlock the Catch-A-Ride system. You will still have to at least complete the story mission with Ellie which unlocks those, to have access to the vehicles.

bl3-save-edit old.sav new.sav --unlock vehicles

Vehicle Skins

You can use vehicleskins to unlock all vehicle skins, for all vehicle types.

bl3-save-edit old.sav new.sav --unlock vehicleskins

TVHM

You can use the tvhm unlock to unlock TVHM mode early:

bl3-save-edit old.sav new.sav --unlock tvhm

Eridian Cube Puzzle

The Eridian Cube puzzle in Desolation's Edge (on Nekrotafeyo) is ordinarily only doable once per savegame. The cubepuzzle unlock will let you complete it more than once:

bl3-save-edit old.sav new.sav --unlock cubepuzzle

All Unlocks at Once

You can also use all to unlock all the various --unlock options at once, without having to specify each one individually:

bl3-save-edit old.sav new.sav --unlock all

Copy Playthrough States

NVHM to TVHM

The --copy-nvhm argument can be used to copy mission status, unlocked Fast Travels, Mayhem Mode, and Last Map Visited from Normal mode (NVHM) to TVHM, so your character in TVHM will be at basically the exact same game state as in Normal.

bl3-save-edit old.sav new.sav --copy-nvhm

TVHM to NVHM

The --copy-tvhm argument can be used to copy mission status, unlocked Fast Travels, Mayhem Mode, and Last Map Visited from TVHM to Normal mode (NVHM), so your character in Normal will be at basically the exact same game state as in TVHM.

bl3-save-edit old.sav new.sav --copy-tvhm

"Un-Finish" NVHM

Alternatively, you can use the --unfinish-nvhm argument to completely discard all TVHM data, and set the game state so that NVHM was never finished. Note that this does not reset any mission status, so if you've already legitimately finished NVHM in the savegame, you won't be able to re-unlock it in-game (though --unlock tvhm or --copy-nvhm could still be used to unlock). This is primarily useful just if you wanted to undo a --copy-nvhm run, or for myself when testing things out using saves from my BL3 Savegame Archive.

bl3-save-edit old.sav new.sav --unfinish-nvhm

Import Items

The -i/--import-items option will let you import items into a savegame, of the sort you can export using -o items. Simply specify a text file as the argument to -i and it will load in any line starting with BL3( as an item into the savegame:

bl3-save-edit old.sav new.sav -i items.txt

Note that by default, the app will not allow Fabricators to be imported into a save, since the player doesn't have a good way to get rid of them. You can tell the app to allow importing Fabricators anyway with the --allow-fabricator option (which has no use when not used along with -i/--import-items)

bl3-save-edit old.sav new.sav -i items.txt --allow-fabricator

If the utility can't tell what an item is during import (which may happen if BL3 has been updated but this editor hasn't been updated yet), it will refuse to import the unknown items, unless --allow-fabricator is specified, since the unknown item could be a Fabricator. Other edits and imports can still happen, however.

If you have items saved in a CSV file (such as one exported using -o items --csv), you can add the --csv argument to import items from the CSV:

bl3-save-edit old.sav new.sav -i items.csv --csv

When reading CSV files, any valid BL3 item code found by itself in a field in the CSV will be imported, so the CSV doesn't have to be in the exact same format as the ones generated by -o items --csv.

Importing Raw Protobufs

If you've saved a savegame in raw protobuf format (using the -o protobuf option, or otherwise), you may want to re-import it into a savegame, perhaps after having edited it by hand. This can be done with the separate utility bl3-save-import-protobuf. This requires a -p/--protobuf argument to specify the file where the raw protobuf is stored, and a -t/--to-filename argument, which specifies the filename to import the protobufs into:

bl3-save-import-protobuf -p edited.pbraw -t old.sav

By default this will prompt for confirmation before actually overwriting the file, but you can use the -c/--clobber option to force it to overwrite without asking:

bl3-save-import-protobuf -p edited.pbraw -t old.sav -c

NOTE: This (and the JSON import) is the one place where these utilities expect to overwrite the file you're giving it. In the above examples, it requires an existing old.sav file, and the savefile contents will be written directly into that file. This option does not currently create a brand-new valid savegame for you.

Importing JSON

If you saved a savegame in JSON format (using the -o json option), you may want to re-import it into a savegame, perhaps after having edited it by hand. This can be done with the separate utility bl3-save-import-json. This requires a -j/--json argument to specify the file where the JSON is stored, and a -t/--to-filename argument, which specifies the filename to import the JSON into:

bl3-save-import-json -j edited.json -t old.sav

By default this will prompt for confirmation before actually overwriting the file, but you can use the -c/--clobber option to force it to overwrite without asking:

bl3-save-import-json -j edited.json -t old.sav -c

NOTE: This (and the protobuf import) is the one place where these utilities expect to overwrite the file you're giving it. In the above examples, it requires an existing old.sav file, and the savefile contents will be written directly into that file. This option does not currently create a brand-new valid savegame for you.

Savegame Info Usage

The bl3-save-info script is extremely simple, and just dumps a bunch of information about the specified savegame to the console. If you specify the -v/--verbose option, it'll output a bunch more info than it ordinarily would, such as inventory contents and discovered Fast Travel stations:

bl3-save-info -v old.sav

Instead of doing a global "verbose" option, you can instead choose to output just some of the extra information:

Items/Inventory

The -i/--items argument will output your inventory, including item codes which could be put in a text file for later import:

bl3-save-info -i old.sav

Fast Travel Stations

The --fast-travel argument will output a list of all unlocked Fast Travel stations, per playthrough. These are reported as the raw object name in the game, so you may have to use a level name reference to get a feel for what is what.

bl3-save-info --fast-travel old.sav

Challenges

The --all-challenges argument will output the state of all challenges in your savegame. Note that BL3 uses challenges to keep track of a lot of info in the savegames, and this list will be over 1.5k items long! As with the fast travel stations, these will be reported as the raw object names.

bl3-save-info --all-challenges old.sav

Missions

The --all-missions argument will output all of the missions that the character has completed, in addition to the active missions which are always shown.

bl3-save-info --all-missions old.sav

If you want to see the actual object paths to any reported missions (for instance, when looking to clear out sidemission progress to deal with locked missions), use the --mission-paths option:

bl3-save-info --mission-paths old.sav
bl3-save-info --all-missions --mission-paths old.sav