# 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.

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)*

## 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.