Borderlands 2 / Borderlands: The Pre-Sequel Save File Modification Tool

This is a simple command line utility to extract and modify player information from a Borderlands 2 or Borderlands: The Pre-Sequel save file. It offers a simple way to perform common actions on a character, such as setting money, unlocking Black Market SDUs, and can also generate a hand-editable JSON file which can then be converted back into a savegame.

Note the following before trying to use it:

• It has no graphical interface and is not easy to use
• It does not provide any mechanisms for creating items or weapons, or even editing items/weapons in a useful fashion.
• It is a proof of concept and can corrupt your save files (take backups!)
• It requires a working Python 2 interpreter (2.6 or later, not 3)

This repository is a fork of the original at https://github.com/pclifford/borderlands2

There are several difference between this fork and the original. The most obvious difference is in the method of specifying modification arguments. Also, the original version defaulted to writing savegames usable on consoles, whereas this fork defaults to writing savegames usable on PC. The -b or --bigendian argument can be specified to have this fork generate Console-appropriate files, though note that many of the changes since the fork have not been tested on consoles. If there are problems with console integration, contact me and I'd be happy to try and fix it.

Note too that the JSON generated by this fork isn't going to be compatible with the JSON generated by the main branch, so don't try to mix between the two.

Running the program

There are two executables: bl2_save_edit.py and bltps_save_edit.py, for Borderlands 2 and Borderlands: The Pre-Sequel, respectively. The functionality of both is virtually identical, only differing in a few of the modification options (--moonstone instead of --eridium, for instance).

The basic form of the utility is to specify and input and output file. If no other options are given, the utility effectively just copies the savegame without making any changes, like so:

python bl2_save_edit.py save0001.sav save0002.sav

Input and Output

By default, the utility saves in a format usable by Borderlands, but you can specify alternate outputs to use, using the -o or --output option. The most useful outputs are:

• savegame - This is the default, and the only output usable by Borderlands itself.
• json - This is the most human-editable format, saved in a text-based heirarchy in JSON format, which should be fairly reasonable to work with.
• items - This will save the character's inventory and bank into a text file which can then be imported into other tools like Gibbed, or imported into other characters using this tool.
• csv - A hybrid of items and json, this is helpful for building a spreadsheet of known items. For BL2 (but not BLTPS) it outputs symbolic names for item parts rather than internal borderlands asset IDs.

For example, saving to a JSON file for later hand-editing:

python bl2_save_edit.py -o json save0001.sav testing.json

After hand-editing a JSON file, you can convert it back by specifying the -j or --json option, to tell the utility that you're loading from a JSON file, like so:

python bl2_save_edit.py -j testing.json save0002.sav
python bl2_save_edit.py --json testing.json save0002.sav

To save the character's inventory to a text file:

python bl2_save_edit.py --output items save0001.save items.txt

To later import the items in items.txt to a savegame, use the -i or --import-items argument:

python bl2_save_edit.py -i items.txt save0002.sav new.sav
python bl2_save_edit.py --import-items items.txt save0002.sav new.sav

(note that the savefile with the imported items is new.sav - You'd have to copy that back over to save0002.sav afterwards)

CSV format output cannot be directly imported; you should paste the item codes into a text file and use the -i method

Other Output Formats

There are also a couple other output formats you can specify with -o, though they are primarily only useful to programmers looking to work with the raw data a little more closely:

• decoded - The raw protocol buffer data, after decompression.
• decodedjson - A midway point between decoded and json, this will generate a JSON file, so it'll be technically editable by hand, but most of the internal data structures will be present as raw protobuf strings.

Modifying Savegames (JSON Method)

As mentioned above, one way to edit your characters is to save them out as a parsed JSON file, edit the JSON by hand (in a text editor), and then re-export the JSON into a savefile. As always, make sure to take backups of your savefiles before overwriting them.

1. python bl2_save_edit.py -o json save0001.sav to_edit.json
2. Edit to_edit.json in a text editor, to suit
3. python bl2_save_edit.py -j to_edit.json save0001.sav

Modifying Savegames (Using Commandline Arguments)

Alternatively, you can alter many attributes of your character by just using commandline options. You can specify as few or as many of these as you want. Note that if you specify -o items to save a character's items to a text file, the majority of these options will have no effect.

Character Name

This can be done with the --name option:

python bl2_save_edit.py --name "Gregor Samsa" old.sav new.sav

Save Game ID

This is probably not actually useful; Borderlands seems to automatically set this to a value it thinks is appropriate. The ID tends to match the filename, though, and I personally end up setting it just because it seems to make sense to. You'll probably be fine if you never touch this option. It can be changed with --save-game-id like so:

python bl2_save_edit.py --save-game-id 2 save0001.sav save0002.sav

Character Level

This will also update your character's XP if needed, and is available with the --level option:

python bl2_save_edit.py --level 72 old.sav new.sav

Money

Set money with the --money option:

python bl2_save_edit.py --money 3000000 old.sav new.sav

Eridium (Borderlands 2 Only)

Set available Eridium with the --eridium option. Note that the game will reduce this to a maxmimum of 500 if you attempt to add more:

python bl2_save_edit.py --eridium 500 old.sav new.sav

Moonstone (Borderlands: The Pre-Sequel Only)

Set available Moonstone with the --moonstone option. Note that the game will reduce this to a maxmimum of 500 if you attempt to add more:

python bltps_save_edit.py --moonstone 500 old.sav new.sav

Seraph Crystals (Borderlands 2 Only)

Set the available Seraph Crystals with the --seraph option. The game will enforce a maximum of 999:

python bl2_save_edit.py --seraph 999 old.sav new.sav

Torgue Tokens (Borderlands 2 Only)

Set the available Torgue Tokens with the --torgue option. The game will enforce a maximum of 999:

python bl2_save_edit.py --torgue 999 old.sav new.sav

Item Levels

The --itemlevels argument can be used to set all items in your inventory to either your character's current level, or to the level you specify.

To set to the character's level:

python bl2_save_edit.py --itemlevels 0 old.sav new.sav

To set to a specific level:

python bl2_save_edit.py --itemlevels 50 old.sav new.sav

Note that items of level 1, however, are always left alone.

Backpack Size

The --backpack option can be used to set the size of your backpack. To set the maximum possible size of the backpack, either specify 39 or "max". Note that the utility will also enforce that the backpack size is a multiple of 3, and between the range of 12 and 39.

python bl2_save_edit.py --backpack max old.sav new.sav
python bl2_save_edit.py --backpack 31 old.sav new.sav

Bank Size

Similarly, the --bank option can be used to set the size of your bank, and will round up to multiples of 2, between 6 and 24. To specify the maximum value, either use 24 or "max".

python bl2_save_edit.py --bank max old.sav new.sav
python bl2_save_edit.py --bank 16 old.sav new.sav

Gun Slots

The --gunslots option can be used to set the total number of open gun slots (ordinarily unlocked via story missions). Valid values are 2, 3, and 4:

python bl2_save_edit.py --gunslots 2 old.sav new.sav
python bl2_save_edit.py --gunslots 3 old.sav new.sav
python bl2_save_edit.py --gunslots 4 old.sav new.sav

Unlocks

There are a few things which can be unlocked via this utility, with the --unlock option. This option can be specified more than once to unlock more than one thing.

Ammo

This option will unlock all ammo SDU upgrades (ordinarily available in the black market). This will also automatically refill all ammo pools:

python bl2_save_edit.py --unlock ammo old.sav new.sav

Challenges

Some challenges do not actually appear in the challenge list until certain prerequisites are met. For instance, the challenge for long-range shotgun kills doesn't actually appear until the challenge for short-range shotgun kills has reached level 5. This will unlock all those challenges regardless of the prerequisites. (Note: this only applies to non-level-specific challenges)

python bl2_save_edit.py --unlock challenges old.sav new.sav

True Vault Hunter Mode (playthrough 2)

To unlock TVHM:

python bl2_save_edit.py --unlock tvhm old.sav new.sav

Creature Slaughterdome (Borderlands 2 Only)

NOTE: I'm unsure whether or not this would actually work on a system without the Creature Slaughterdome explicitly enabled, but it's possible maybe it does?

The Creature Slaughterdome might be unlockable with:

python bl2_save_edit.py --unlock slaughterdome old.sav new.sav

Ammo

The --maxammo option can be used to refill all ammo to its current maximum level (based on what you've already purchased at the black market). This is obviously a bit silly ordinarily, given how easy ammo is to come by.

python bl2_save_edit.py --maxammo old.sav new.sav

To actually increase your total available ammo pool, as you'd do through the black market, use --unlock ammo (see above). Doing so will then also refill ammo as if --maxammo had been specified.

Challenge Levels

This option is admittedly rather silly, but the --challenges argument will let you set your character's challenge levels to the specified values. The valid options are:

• zero
• max
• bonus

If set to zero, the level of all your non-level-specific challenges will be reset to zero, so you can start accumulating again. (Possibly useful if you want to start from scratch but haven't completed enough to use the in-game reset.)

python bl2_save_edit.py --challenges zero old.sav new.sav

If set to max, the level of all non-level-specific challenges will be set to one under than their maximum level, possibly making it easier to accrue a good deal of Badass Rank very quickly.

python bl2_save_edit.py --challenges max old.sav new.sav

If set to bonus, the level of all non-level-specific challenges will be set to one under the levels at which they provide bonus skins/heads, for the challenges which do so. It will leave all other challenges alone.

python bl2_save_edit.py --challenges bonus old.sav new.sav

It's also possible to specify both max and bonus, in which case all challenges will be set just under their completion level, except for the ones which provide bonuses, which will then be set to be primed to receive those bonuses:

python bl2_save_edit.py --challenges max --challenges bonus old.sav new.sav

Combining Commandline Options

In general, the various options can be combined. To make a few changes to a savegame but save as parsed JSON:

python bl2_save_edit.py --name "Laura Palmer" --save-game-id 2 --money 3000000 --output json save0001.sav laura.json

To take that JSON, unlock TVHM and Challenges, and set challenges to their primed "bonus" levels, and save as a real savefile:

python bl2_save_edit.py --json --unlock tvhm --unlock challenges --challenges bonus laura.json save0002.sav

Working with Savegames to/from Consoles

NOTE: As mentioned above, this fork has not actually been tested on Consoles, so it's possible that the generated savegames might not work. Use at your own risk!

The safest way to convert a PC savegame to Console, or vice-versa, would be to use JSON as an intermediate step. For the commands which deal with the console savegames, be sure to specify the -b or --bigendian options. For instance, to convert from a Console savegame to a PC savegame:

python savegame.py -b -o json xbox.sav pc.json
python savegame.py -j pc.json pc.sav

Or to convert from a PC savegame to a Console savegame:

python savegame.py --output json pc.sav xbox.json
python savegame.py --json --bigendian xbox.json xbox.sav

Exporting character items

All items stored and held in the character's bank or inventory can be exported to a text file as a list of codes, in a format compatible with Gibbed's save editor. This is accomplished with -o items or --output items like so:

python bl2_save_edit.py -o items savegame.sav items.txt

Importing character items

A text file of codes generated as above, or assembled by hand, can be imported into a character using the -i or --import-items arguments, like so:

python bl2_save_edit.py -i items.txt old.sav new.sav
python bl2_save_edit.py --import-items items.txt old.sav new.sav

By default all items will be inserted into the inventory, but this can be changed with a line containing "; Bank" to indicate that all following items should go into the bank, or one of either "; Weapons" or "; Items" to indicate that all following items should go into the inventory. For example, importing a file containing the following will put a Vault Hunter's Relic into the inventory and a Righteous Infinity pistol into the bank:

; Bank
BL2(h0Hd1Z+jY/s2Qy++Zu8Ba9qXoOmjwJ6NhrlsOmhNMX+oJo5CfQns)
; Items
BL2(B2vuv4tz1zSQCf2pqLJCS5XD/tKN4FXpjRJLnn1v85U=)

Other commandline options

There are a few other commandline options available when running the utilities.

Quiet Output

By default, the utility is rather chatty and will tell you what it's doing at all times. To disable output except for errors, use the -q or --quiet option:

python bl2_save_edit.py -q old.sav new.sav
python bl2_save_edit.py --quiet old.sav new.sav

Force Overwrites

By default, the utility will refuse to overwrite a file without getting confirmation from the user first. To disable that yes/no prompt and force the app to overwrite the file automatically, use -f or --force like so:

python bl2_save_edit.py -f old.sav new.sav
python bl2_save_edit.py --force old.sav new.sav

Help

The utility will also show you what all of its commandline options are at the commandline, using the -h or --help options:

python bl2_save_edit.py -h
python bl2_save_edit.py --help

Sample output from that option is shown below, though might get out-of-date if I forget to update this README after updating the program:

usage: bltps_save_edit.py [-h] [-o {savegame,decoded,decodedjson,json,items}]
                          [-i IMPORT_ITEMS] [-j] [-b] [-q] [-f] [--name NAME]
                          [--save-game-id SAVE_GAME_ID] [--level LEVEL]
                          [--money MONEY] [--moonstone MOONSTONE]
                          [--itemlevels ITEMLEVELS] [--backpack BACKPACK]
                          [--bank BANK] [--gunslots {2,3,4}]
                          [--unlock {tvhm,challenges,ammo}]
                          [--challenges {zero,max,bonus}] [--maxammo]
                          input_filename output_filename

Modify Borderlands: The Pre-Sequel Save Files

positional arguments:
  input_filename        Input filename, can be "-" to specify STDIN
  output_filename       Output filename, can be "-" to specify STDOUT

optional arguments:
  -h, --help            show this help message and exit
  -o {savegame,decoded,decodedjson,json,items}, --output {savegame,decoded,decodedjson,json,items}
                        Output file format. The most useful to humans are:
                        savegame, json, and items (default: savegame)
  -i IMPORT_ITEMS, --import-items IMPORT_ITEMS
                        read in codes for items and add them to the bank and
                        inventory (default: None)
  -j, --json            read savegame data from JSON format, rather than
                        savegame (default: False)
  -b, --bigendian       change the output format to big-endian, to write
                        PS/xbox save files (default: False)
  -q, --quiet           quiet output (should generate no output unless there
                        are errors) (default: True)
  -f, --force           force output file overwrite, if the destination file
                        exists (default: False)
  --name NAME           Set the name of the character (default: None)
  --save-game-id SAVE_GAME_ID
                        Set the save game slot ID of the character (probably
                        not actually needed ever) (default: None)
  --level LEVEL         Set the character to this level (default: None)
  --money MONEY         Money to set for character (default: None)
  --moonstone MOONSTONE
                        Moonstone to set for character (default: None)
  --itemlevels ITEMLEVELS
                        Set item levels (to set to current player level,
                        specify 0) (default: None)
  --backpack BACKPACK   Set size of backpack (maximum is 39, "max" may be
                        specified) (default: None)
  --bank BANK           Set size of bank(maximum is 24, "max" may be
                        specified) (default: None)
  --gunslots {2,3,4}    Set number of gun slots open (default: None)
  --unlock {tvhm,challenges,ammo}
                        Game features to unlock (default: {})
  --challenges {zero,max,bonus}
                        Levels to set on challenge data (default: {})
  --maxammo             Fill all ammo pools to their maximum (default: False)

TODO

1. Borderlands:TPS has a bunch more data stored in the file that we don't currently parse, so the JSON generated with -o json includes a pretty large _raw section up at the top, for all the data we don't know about. The Gibbed editor seems to know about some of these, and I'd sort of like to go through and see if anything's worth decoding for this utility.

2. The internal modify_save function starts off with the raw, decoded protobuf, and each little snippet in there decodes further as-needed, and then re-encodes once it's done. I wonder if it'd make more sense to just unwrap the whole thing to JSON at the beginning and then re-wrap at the end, rather than doing it piecemeal like that. The current method is sort of nice in that only the bits of the file that actually need to get touched are processed, but on the other hand, it adds a bunch of unnecessary cruft in there.